# https://github.com/m-velikov/cpp-quick-start-mcp 项目说明书 生成时间：2026-06-21 19:55:09 UTC ## 目录 - [Overview & Architecture](#page-1) - [Installation & Client Integration](#page-2) - [Scaffolding Skills Knowledge Base](#page-3) - [Best Practices & Workflow Orchestration](#page-4) ## Overview & Architecture ### 相关页面 相关主题：[Installation & Client Integration](#page-2), [Scaffolding Skills Knowledge Base](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md) - [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md) - [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md) - [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md) - [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md) - [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md) - [data/scaffold-cmake-presets/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake-presets/SKILL.md) - [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md) - [data/scaffold-doctest/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-doctest/SKILL.md) - [data/best-practices-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md) - [data/best-practices-code-review/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-code-review/SKILL.md)
# Overview & Architecture ## 1. 项目定位与目标 `cpp-quick-start-mcp` 是一个基于 Model Context Protocol (MCP) 的服务器，专门面向 C++ 项目的脚手架（scaffolding）与现代化改造场景。它通过 npm 分发，当前最新版本为 **v0.7.0**，安装后提供 `cpp-quick-start-mcp` 命令，支持默认的 stdio 传输和可选的 HTTP/SSE 模式（默认监听 `0.0.0.0:3000`） 资料来源：[README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)。 其核心价值在于将分散在 C++ 生态中的最佳实践——构建系统（CMake/Make/Meson/Bazel）、包管理（Conan/vcpkg）、测试框架（doctest 等）、静态分析（clang-tidy/cppcheck）、CI/CD（GitHub Actions/GitLab CI）、目录布局（Pitchfork Layout）——封装为统一的 MCP 工具、资源与提示词，让 AI 智能体通过对话方式即可生成符合现代 C++ 工程规范的项目结构，避免"凭记忆"生成不一致或过时的样板代码 资料来源：[README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)。 ## 2. 整体架构 服务器采用"分层元技能"（layered meta-skill）设计：底层是大量按目录组织的 `SKILL.md` 技能库，顶层由一个名为 `go` 的元提示词统一驱动整个生成流程 资料来源：[data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)。 ```mermaid flowchart TB U[用户 / AI 智能体] --> P[MCP 提示词
go] P --> M[meta-quickstart 元技能
Mode A 新项目 / Mode B 既有项目] M --> R[资源发现
list-resources] M --> S[技能库
data/scaffold-*/SKILL.md] S --> BS[构建系统
CMake / Make / Meson / Bazel] S --> QA[质量工具
clang-tidy / cppcheck] S --> CI[CI/CD
GitHub Actions / GitLab CI] S --> PKG[包管理 / 测试 / 布局] M --> OUT[项目产物
AGENTS.md + skills/
+ 完整脚手架文件] ``` ## 3. 核心组件 ### 3.1 提示词（Prompt） `go` 是唯一的元提示词，作为 Level 2 "Meta-Skill" 存在，其职责不是直接写 C++ 代码，而是根据用户偏好生成针对其工具链定制化的具体技能 资料来源：[data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)。它强制执行"预检扫描 → 模式 A/B 选择 → 多轮分类访谈 → 资源发现 → 文件生成"的工作流。 ### 3.2 技能（Skills） 所有技能均以 `SKILL.md` 文件形式存放在 `data/scaffold-*/` 下，每个文件都带有 YAML frontmatter（`name` + `description`），`description` 字段必须说明技能做什么以及何时使用，供其他智能体判断是否加载 资料来源：[data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)。技能按职能可分为： | 类别 | 代表技能 | 关键约束 | |------|---------|---------| | 构建系统 | `scaffold-cmake` / `scaffold-meson` / `scaffold-make` / `scaffold-bazel` | 强制非递归 / 模块化，目标化 CMake | | 测试 | `scaffold-doctest` 等 | 通过 `FetchContent` 或包管理器接入 | | 质量 | `scaffold-cppcheck` / `scaffold-clang-tidy` | 需与构建系统及 pre-commit 联动 | | CI/CD | `scaffold-github-actions` / `scaffold-gitlab-ci` | 缓存编译产物，固定镜像 | | 布局 / 配置 | `scaffold-pitchfork-layout` / `scaffold-cmake-presets` / `scaffold-base-configs` | Pitchfork 标准 + 隐藏 base preset | 例如 `scaffold-cmake` 强制要求使用 Modern CMake：`cmake_minimum_required(VERSION 3.20)`、按目标拆分 `CMakeLists.txt`、通过 `target_compile_features` 而非全局变量设置 C++ 标准 资料来源：[data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)。 ### 3.3 资源（Resources） 技能同时作为 `mcp://scaffold/*` 资源暴露，智能体在生成文件前可按需读取对应指令，避免幻觉 资料来源：[README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)。 ### 3.4 持久化产物 完成生成后，项目根会写入 `AGENTS.md`（智能体协作指南与 Workspace Skills 索引表） 资料来源：[data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)，并随项目携带永久性的 `skills//SKILL.md`，供后续智能体在每次任务开始时优先读取。基础配置文件 `.gitignore`、`.gitattributes`、`.clangd` 也会一并落地 资料来源：[data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md)。 ## 4. 工作流与约束 `meta-quickstart` 在启动时强制扫描当前目录，以判定是"空目录（Mode A）"还是"既有项目（Mode B）" 资料来源：[data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)。Mode A 通过多选访谈覆盖构建系统、标准、布局、测试等十余个分类；Mode B 则跳过全量访谈，进入"添加新组件 / 现代化改造"二选一分支。两条路径最终都会调用 `list-resources` 工具拉取全部可用技能，再向用户主动推荐相关项。 在产出质量上，工作区技能模板要求所有命令必须以可直接复制粘贴的 fenced 代码块呈现，禁止出现读者需自行替换的占位符；任务类技能必须包含 `## Commands` 与 `## Expected Output` 两节 资料来源：[data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)。通用最佳实践则由独立的 `best-practices-*` 系列兜底，例如 Meson 项目应保持根 `meson.build` 整洁并通过 `add_project_arguments` 注入警告 资料来源：[data/best-practices-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md)；代码评审强调单一职责、强抽象、依赖单向流动等原则 资料来源：[data/best-practices-code-review/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-code-review/SKILL.md)。 ## See Also - [scaffold-cmake](scaffold-cmake.md) — CMake 脚手架细节 - [scaffold-pitchfork-layout](scaffold-pitchfork-layout.md) — Pitchfork 目录布局规范 - [Workspace Skills 与 AGENTS.md](workspace-skills.md) — 持久化智能体协作指南 --- ## Installation & Client Integration ### 相关页面 相关主题：[Overview & Architecture](#page-1)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md) - [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md) - [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md) - [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md) - [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md) - [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
# Installation & Client Integration `cpp-quick-start-mcp` 是一个面向 C++ 项目的 Model Context Protocol (MCP) 服务器。它通过标准 MCP 接口向 AI 智能体（例如 Claude Code、Cursor 等）暴露一组「脚手架技能（Scaffolding Skills）」与动态资源，从而引导智能体为新项目或现有项目生成符合现代 C++ 规范的目录结构、构建脚本、CI 配置以及代理协作规范 资料来源：[README.md:1-40]()。 本页聚焦于该服务器的**安装**与**客户端集成**两条主线，覆盖 NPM 全局安装、本地源码构建、stdio 与 HTTP/SSE 两种运行模式，以及将服务器接入 MCP 客户端所需的基本配置与调用约定。 ## 安装方式 服务器以 Node.js 包形式分发，因此安装前需要本地具备 Node.js 与 `npm` 运行时。README 推荐两条等价路径 资料来源：[README.md:42-67]()： ### 方式一：从 NPM 注册表安装（推荐） ```bash npm install -g @m-velikov/cpp-quick-start-mcp ``` 安装完成后，`cpp-quick-start-mcp` 命令将进入全局 PATH，可被任意 MCP 客户端调用。该方式最稳定，适合普通使用者。 ### 方式二：从源码构建并本地安装 适合希望修改技能内容、参与贡献或在 CI 中固定版本的场景： ```bash # 1. 克隆并安装依赖 git clone https://github.com/m-velikov/cpp-quick-start-mcp.git cd cpp-quick-start-mcp npm install # 2. 构建产物 npm run build # 3. 从本地目录进行全局安装 npm install -g . ``` 不论使用哪种方式，安装成功后的可执行入口名称均为 `cpp-quick-start-mcp` 资料来源：[README.md:60-66]()。 ## 服务器启动模式 服务器默认通过 **stdio** 与 MCP 客户端通信，因此大部分支持 MCP 协议的客户端无需任何额外参数即可直接调用。若需要把服务器作为独立 HTTP 服务暴露，则可显式指定端口与绑定地址 资料来源：[README.md:70-78]()。 | 模式 | 启动命令 | 适用场景 | | --- | --- | --- | | stdio（默认） | `cpp-quick-start-mcp` | Claude Code、Cursor 等本地 MCP 客户端直连 | | HTTP / SSE | `cpp-quick-start-mcp --port 3000` | 远程/容器化部署、Web 调试或多客户端共享 | HTTP/SSE 模式默认监听 `0.0.0.0:3000`，即绑定全部网卡接口，可通过局域网访问；若部署到云服务器，请确保防火墙/安全组放行该端口。 ```mermaid flowchart LR A[用户] --> B{MCP 客户端} B -->|stdio| C[cpp-quick-start-mcp] B -->|HTTP/SSE| D[cpp-quick-start-mcp --port 3000] C --> E[(Scaffolding Skills)] D --> E E --> F[新项目脚手架
build/CMakeLists.txt 等] E --> G[现有项目改造
AGENTS.md 等] ``` ## 客户端集成 ### 在 MCP 客户端中注册服务器 对于支持 MCP 的客户端（Claude Code、Cursor、Cline 等），典型配置是在客户端配置文件中声明一个 stdio 类型的 MCP server，命令指向 `cpp-quick-start-mcp`。例如 Claude Code 的 `mcp_servers.json` 可写为： ```json { "mcpServers": { "cpp-quick-start": { "command": "cpp-quick-start-mcp", "args": [] } } } ``` 若采用 HTTP/SSE 部署，则把 `command/args` 替换为 `url: http://:3000` 即可。客户端会通过 MCP 协议列出该服务器暴露的工具（`go`、`list-resources` 等）与资源（`mcp://scaffold/*`）。 ### 可用资源与触发入口 服务器启动后会向客户端暴露两类核心能力： 1. **入口工具**：`go` 工具启动完整的「C++ 栈访谈 → 计划 → 脚手架生成」流程，会先扫描当前目录、判断是新项目（Mode A）还是现有项目（Mode B），再读取对应的脚手架技能 资料来源：[data/meta-quickstart/SKILL.md:13-31]()。 2. **动态资源**：形如 `mcp://scaffold/cmake`、`mcp://scaffold/github-actions`、`mcp://scaffold/pitchfork-layout` 等 URI，承载具体的「How-to」级指令，供智能体在生成对应产物时按需读取 资料来源：[README.md:30-40]()。 ### 在生成的项目中继续使用 服务器在生成项目时，会在项目根目录写入 `AGENTS.md` 与 `skills/` 目录，使后续的智能体协作具备「自我描述」能力 资料来源：[data/scaffold-agents/SKILL.md:8-30]()。每个工作区技能必须遵守统一的目录布局、YAML frontmatter 与「Commands + Expected Output」结构 资料来源：[data/scaffold-workspace-skills/SKILL.md:1-30]()。同时，Pitchfork 目录布局技能要求将 `include//`、`src//`、`build/` 等标准目录作为脚手架的一部分 资料来源：[data/scaffold-pitchfork-layout/SKILL.md:5-22]()。 ## 常见失败模式与排查 - **`cpp-quick-start-mcp: command not found`**：通常意味着全局 npm bin 目录不在 `PATH` 中。可使用 `npm config get prefix` 找到全局 bin 路径并加入 `PATH`，或改用 `npx @m-velikov/cpp-quick-start-mcp` 直接运行。 - **HTTP/SSE 模式端口被占用**：更换端口，例如 `cpp-quick-start-mcp --port 3100`；同时确认服务器是否真的监听了 `0.0.0.0` 而非 `127.0.0.1` 资料来源：[README.md:72-78]()。 - **客户端看不到 `mcp://scaffold/*` 资源**：MCP 客户端必须支持 resources 能力；若不支持，请改用 stdio + 支持 tools 的客户端调用 `go` 工具。 - **生成的项目缺少 `AGENTS.md` 或 `skills/`**：检查 `go` 工具执行时是否处于空目录或已被识别的项目根目录；元技能在开始前会扫描目录内容 资料来源：[data/meta-quickstart/SKILL.md:13-20]()。 ## See Also - [Architecture & Skills Overview](Architecture-&-Skills-Overview.md) - [Scaffolding Workflow (Mode A & Mode B)](Scaffolding-Workflow.md) - [Configuration & Resources](Configuration-&-Resources.md) --- ## Scaffolding Skills Knowledge Base ### 相关页面 相关主题：[Best Practices & Workflow Orchestration](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md) - [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md) - [data/scaffold-bazel/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-bazel/SKILL.md) - [data/scaffold-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-meson/SKILL.md) - [data/scaffold-make/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-make/SKILL.md) - [data/scaffold-cmake-presets/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake-presets/SKILL.md) - [data/scaffold-vcpkg/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-vcpkg/SKILL.md) - [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md) - [data/scaffold-doctest/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-doctest/SKILL.md) - [data/scaffold-cppcheck/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cppcheck/SKILL.md) - [data/scaffold-clang-tidy/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-clang-tidy/SKILL.md) - [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md) - [data/scaffold-gitlab-ci/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-gitlab-ci/SKILL.md) - [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md) - [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
# Scaffolding Skills Knowledge Base ## 概述与目标 Scaffolding Skills Knowledge Base 是 `cpp-quick-start-mcp` 服务器内置的知识资源库，通过 `mcp://scaffold/*` URI 暴露给 AI Agent。每一个技能（Skill）是一份结构化的 Markdown 指令，告诉 Agent 如何为 C++ 项目生成特定领域（如构建系统、依赖管理、CI、静态分析、目录布局等）的样板文件。 元技能（meta-quickstart，名为 `go`）负责调度整个知识库：根据用户选择拉取并组装对应的子技能，生成统一的项目脚手架。资料来源：[data/meta-quickstart/SKILL.md]()。 ```mermaid flowchart TD A[Agent 触发 meta-quickstart / go] --> B{扫描当前目录} B -->|空目录| C[Mode A: 12 项偏好访谈] B -->|已有项目| D[Mode B: 增补或现代化] C --> E[list-resources 发现 mcp://scaffold/*] D --> E E --> F[read-resource 拉取子技能] F --> G[生成项目根文件 + skills/*] G --> H[输出 AGENTS.md 与永久技能] ``` ## 元技能与编排流程 `meta-quickstart/SKILL.md` 明确规定了三步流程：项目扫描、Mode A/B 访谈、资源发现与主动建议。Agent 必须先列出现有目录，再决定走「新建项目」还是「改造现有项目」分支。资料来源：[data/meta-quickstart/SKILL.md]()。 Mode A 强制要求覆盖 12 个类别（构建系统、测试框架、CI 提供方、包管理器、目录布局、代码质量、平台目标等），并通过多选/自由输入工具逐批提问。资料来源：[data/meta-quickstart/SKILL.md]()。 在资源发现阶段，Agent 必须调用 `list-resources` 列出全部 `mcp://scaffold/*` 资源，再做差距分析，主动建议用户采纳尚未要求但有价值的技能（如 `scaffold-cppcheck`、`scaffold-code-hygiene`、`scaffold-github-actions`）。资料来源：[data/meta-quickstart/SKILL.md]()。 ## 技能分类与覆盖范围 知识库按职责划分为多个子技能。下表汇总了当前仓库内可见的子技能及其对应文件： | 类别 | 技能名称 | 核心产出 | | --- | --- | --- | | 构建系统 | `scaffold-cmake` / `scaffold-bazel` / `scaffold-meson` / `scaffold-make` | 现代化 `CMakeLists.txt`（目标式、≥ 3.20）；Bazel `MODULE.bazel` + `BUILD`；模块化 `meson.build`；非递归 `Makefile` | | 依赖与打包 | `scaffold-vcpkg` / `scaffold-conan` | `vcpkg.json` manifest；Conan 配置 + 工具链 | | 测试框架 | `scaffold-doctest` / `scaffold-gtest` 等 | `FetchContent` 集成、测试可执行文件与 `add_test()` 注册 | | 代码质量 | `scaffold-clang-tidy` / `scaffold-cppcheck` | `.clang-tidy` 检查项与命名规则；`run-cppcheck` 自定义目标 | | CI/CD | `scaffold-github-actions` / `scaffold-gitlab-ci` | 多阶段流水线（`build` + `test`）、`ccache` 缓存 | | 目录布局 | `scaffold-pitchfork-layout` | 严格的 `src/`、`include//`、`tests/` 等目录划分 | | 基础配置 | `scaffold-base-configs` | `.gitignore`、`.gitattributes`、`.clangd` | | Agent 协作 | `scaffold-agents` | `AGENTS.md` 拓扑与资源纪律规范 | | 预设与体验 | `scaffold-cmake-presets` | `CMakePresets.json`（版本 3+，隐藏基预设 + 公开预设） | | 工作区技能 | `scaffold-workspace-skills` | 规范 `skills//SKILL.md` 永久技能写法 | 例如，CMake 技能要求使用 `target_compile_features( PUBLIC cxx_std_20)` 强制 C++ 标准，并明确禁止「单体式」顶层 `CMakeLists.txt`，必须按目标拆分文件。资料来源：[data/scaffold-cmake/SKILL.md]()。CMake Presets 技能则规定使用 Ninja 作为默认生成器，并通过隐藏基预设统一 `CMAKE_EXPORT_COMPILE_COMMANDS`。资料来源：[data/scaffold-cmake-presets/SKILL.md]()。 Make 技能特别强调：GNU Make 不支持 `**` 通配符，必须使用 `find` 命令发现源文件；同时强制非递归设计，通过 `include` `.mk` 文件来组织多子目录。资料来源：[data/scaffold-make/SKILL.md]()。 vcpkg 技能要求生成合法 JSON（包含 `$schema`、`name`、`version`、`dependencies`）的 `vcpkg.json`，并在需要基线锁定时附 `vcpkg-configuration.json`。资料来源：[data/scaffold-vcpkg/SKILL.md]()。 ## 技能文档的结构与消费方式 所有技能（`scaffold-*` 与 `best-practices-*`）均遵守统一的 Markdown 模板：YAML frontmatter 声明 `name` 与 `description`（`Use when ...`），正文则用 `## Instructions` / `## Requirements` 等小节给出可直接复制的代码块。资料来源：[data/scaffold-workspace-skills/SKILL.md]()。 Meta 技能会强制要求命令必须以 fenced code block 形式给出，避免占位符歧义；同时为任务型技能（`configure-project`、`build-project`、`test-project`）规定固定章节顺序：`## Commands` → `## Expected Output`。资料来源：[data/scaffold-workspace-skills/SKILL.md]()。 `AGENTS.md` 中的 Workspace Skills 索引表必须真实反映项目 `skills/` 目录下的内容，禁止保留示例占位行，从而保证 Agent 在执行任务前能精准匹配并加载相关技能。资料来源：[data/scaffold-agents/SKILL.md]()。 资源纪律方面，知识库强调「建议而非越权」：Agent 只实现用户明确请求的内容，对额外改进以一两句话提示即可，避免消耗用户预算。资料来源：[data/scaffold-agents/SKILL.md]()。 ## See Also - [cpp-quick-start-mcp 项目主页](https://github.com/m-velikov/cpp-quick-start-mcp) - Release v0.7.0 更新日志： --- ## Best Practices & Workflow Orchestration ### 相关页面 相关主题：[Scaffolding Skills Knowledge Base](#page-3), [Overview & Architecture](#page-1)
相关源码文件 以下源码文件用于生成本页说明： - [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md) - [data/best-practices-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md) - [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md) - [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md) - [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md) - [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md) - [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
# Best Practices & Workflow Orchestration ## 概述 "最佳实践与工作流编排"是 `cpp-quick-start-mcp` 服务器的核心能力层，它并不直接编写 C++ 代码，而是通过 **元技能 (Meta-Skill)** 驱动一组原子技能完成从需求访谈到项目脚手架生成的完整流水线。资料来源：[data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md) 中明确将 `go` 描述为 Level 2 "Meta-Skill"，其目标是根据用户的工具栈选择生成与之匹配的 `scaffold-*` 与 `build-*` 任务技能。 整套编排层解决三个关键问题： 1. **避免凭空捏造 (anti-hallucination)**：所有脚手架命令和约定都必须来自真实读取的技能文件，而不是模型记忆。 2. **决策可追溯**：通过分模式 (Mode A / Mode B) 显式控制新项目与既有项目两条不同流程。 3. **最佳实践即资源**：将 CMake、Conan、Meson、Clang-Tidy 等最佳实践作为可被 `list-resources` 工具枚举的 MCP 资源（`mcp://scaffold/...`）提供。资料来源：[README.md:Dynamic Scaffolding Resources](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)。 ## 编排流程：Mode A vs Mode B 元技能 `go` 在执行任何操作前都必须先进行 **预扫描 (Pre-flight Project Scan)**，通过 `ls` 当前目录判定目标路径是空白目录还是已有项目，并据此切换工作流。资料来源：[data/meta-quickstart/SKILL.md:Pre-flight Project Scan](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)。 ### Mode A：全新项目访谈 当目录为空时，代理必须通过交互式多选工具（如 `ask_question`）**逐一询问 12 个类别**的用户偏好，例如构建系统、测试框架、布局规范、CI 提供商等。流程强调： - 即便一次调用只能容纳 4 个问题，代理也必须 **按批次连续提问**，禁止跳过任何类别。 - 必须为每个问题保留自由文本输入选项，以支持用户自定义答案。 - 完成 12 类别后进入 **Step 2：资源发现与主动建议**，调用 `list-resources` 枚举所有可用的 `mcp://scaffold/*` 资源，并将其嵌入最终的生成计划。 ### Mode B：既有项目增量 / 现代化 如果目录已包含 `CMakeLists.txt`、`Makefile` 或 `src/` 等标记，代理切换到 Mode B，**禁止进行完整的 Mode A 访谈**。取而代之的是： 1. **约定扫描**：读取既有构建文件与若干源文件，自动推断构建系统、包管理器、目录布局、命名风格与代码格式。 2. **路径选择**：询问用户是 "添加新组件" 还是 "现代化并增强 Agent 开发支持"。 3. **目标平台与一致性检查**：询问桌面/移动、Windows/Linux 等平台，并通过 **布局一致性检查 (Layout Conformity Check)** 评估新增组件是否破坏既有目录约定；若破坏，则主动建议迁移到 Pitchfork 布局。资料来源：[data/scaffold-pitchfork-layout/SKILL.md:Existing Project Additions](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md)。 ```mermaid flowchart TD A[开始] --> B{目录是否为空?} B -- 是 --> C[Mode A: 12 类访谈] B -- 否 --> D[Mode B: 约定扫描] D --> E{添加组件 vs 现代化?} E -- 添加 --> F[组件访谈 + 平台询问] E -- 现代化 --> G[缺失工具访谈 + 布局重构建议] C --> H[Step 2: list-resources] F --> H G --> H H --> I[生成 scaffold-* / build-* 技能] I --> J[结束] ``` ## 最佳实践资源集合 编排层把最佳实践作为独立的 MCP 资源提供，确保模型不会基于过期记忆给出错误建议。以 Meson 资源为例，它明确要求： - 通过 `subdir()` 保持根 `meson.build` 简洁，避免在顶层堆叠所有 `library()` / `executable()`。 - 使用 `add_project_arguments()` 添加项目级警告，**禁止硬编码 GCC/Clang 特定标志**，需先判断 `cpp.get_id()`。 - 利用 WrapDB 与 `dependency()` 的 `fallback` 优雅处理缺失的系统包。 - 通过 `meson test -C build` 运行完整测试套件。 资料来源：[data/best-practices-meson/SKILL.md:Structured Build Files](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md)。 类似地，基础配置文件技能为任何新 C++ 仓库定义了 **必须生成** 的根目录文件，包括标准 `.gitignore`、`* text=auto eol=lf` 规则的 `.gitattributes`，以及让 clangd 在 `build/` 中找到 `compile_commands.json` 的 `.clangd`。资料来源：[data/scaffold-base-configs/SKILL.md:.gitignore](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md)。 ## 代理拓扑与工作区技能 编排的最终落地形态是项目内 **永久存在的工作区技能**。根据 [data/scaffold-agents/SKILL.md:Workspace Skills](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)，每个项目应在 `skills/` 目录下拥有 `configure-project`、`build-project`、`test-project` 等任务技能，它们的结构由 [data/scaffold-workspace-skills/SKILL.md:Requirements](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md) 严格规定： - 必须使用 kebab-case 命名。 - 必须含 YAML frontmatter（`name`、`description`），`description` 必须包含 `Use when ...` 触发条件。 - 每个命令必须以可直接复制的代码块形式出现，**不允许**出现 `` 类占位符。 - 任务技能必须依次包含 `## Commands` 与 `## Expected Output` 两个小节。 `AGENTS.md` 同时强制要求任何后续代理在开始任务前先扫描 `skills/` 索引表，匹配触发条件后必须 **完整读取** 对应的 `SKILL.md`，禁止凭记忆配置、构建或重构。这条 "READ FIRST" 规则正是整个编排系统的安全护栏——它把分散的最佳实践文档固化为代理必须显式调用的契约。资料来源：[data/scaffold-agents/SKILL.md:READ FIRST](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)。 ## See Also - [Pitchfork Layout Specification](https://github.com/vector-of-bool/pitchfork/blob/develop/data/spec.bs) — 目录布局权威规范。 - MCP 资源列表：`mcp://scaffold/cmake`、`mcp://scaffold/conan`、`mcp://scaffold/github-actions`、`mcp://scaffold/gitlab-ci` 等，可在 `list-resources` 调用时枚举。 - [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md) — 安装与运行方式。 --- --- ## Doramagic 踩坑日志 项目：m-velikov/cpp-quick-start-mcp 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/m-velikov/cpp-quick-start-mcp | host_targets=mcp_host, claude, cursor ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/m-velikov/cpp-quick-start-mcp | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/m-velikov/cpp-quick-start-mcp | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/m-velikov/cpp-quick-start-mcp | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | release_recency=unknown