SpecPilot

SpecPilot

SpecPilot 是一款面向 Claude Code、Cursor 和 ChatGPT 等 AI 编码 Agent 的规范驱动开发（SDD）命令行工具。它会初始化、验证并同步 .specs/ 目录，让 AI 辅助编码始终以不断更新的需求、架构和任务规范为依据，而不是偏离代码库。

MCP 服务

更喜欢在编辑器中操作？SpecPilot 也可以作为远程 MCP 服务运行，因此 Claude Code、Cursor 或 Copilot 可以自行完成整个入门流程——回答它们能从仓库中 推断出的问题，只向你询问其余信息。

claude mcp add --transport http specpilot https://init.specpilot.dev/mcp

然后向你的 Agent 提问："使用 SpecPilot 为此项目进行入门设置"。

对于 Cursor、VS Code 和其他客户端，将其添加为 HTTP（可流式传输）服务：

{
  "mcpServers": {
    "specpilot": {
      "type": "http",
      "url": "https://init.specpilot.dev/mcp"
    }
  }
}

无需安装，也无需 API 密钥。完整设置说明：https://specpilot.dev/mcp-setup

specpilot serve 还会提供本地 MCP 端点，让你的 AI IDE 能读取此机器上的规范、添加或移动任务并设置文件夹：参见下文的本地 MCP 端点。

快速开始

# Install globally
npm install -g specpilot

# Create a new project
specpilot init my-project --lang typescript --framework react

# Add specs to existing project
cd existing-project
specpilot add-specs

# Validate specifications
specpilot validate

🚀 后续步骤：使用 AI 填充规范

创建项目后，请按照以下步骤使用 AI 填充规范：

1. 打开生成的指南：查看 .specs/README.md，获取完整指南
2. 复制入门提示词：使用 .specs/development/onboarding.md 中的提示词
3. 粘贴到你的 AI Agent 中：ChatGPT、Claude 或其他 AI 助手
4. 检查生成的规范文件：查看 AI 生成的需求和架构

这种 AI 辅助方式可确保生成的规范全面、优质，并契合项目需求。

命令

命令	说明
init <name>	初始化新的 SDD 项目
init <name> --dry-run	预览将要创建的文件，但不写入
add-specs	为现有项目添加规范
validate	验证规范文件
archive	归档过长的 prompts.md / tasks.md 条目
backfill	补充缺失的强制规则、斜杠命令和 Claude Code 技能
list	显示可用模板
migrate	转换旧版 .project-spec 文件夹（很少需要）
refine [desc]	优化项目规范
serve [folders...]	通过本项目的 .specs/ 提供本地 Web 界面，也可通过指定的每个文件夹的 .specs/ 提供界面，并包括记在 ~/.specpilot/projects.json 中的项目（你提供服务或打开的每个项目；有 .specs/ 的项目会在启动时重新打开）；如果文件夹没有 .specs/ 且没有已记录的项目，则在你从页面打开项目之前不会打开任何项目（可移动任务、新建任务、重新生成所有命令文件、查看没有 .specs/ 的文件夹的设置视图，除非使用 --read-only）

**提示——命令别名：**所有命令都有一个可代替完整名称的短别名。 init → i  ·  validate → v  ·  migrate → m  ·  list → ls  ·  refine → ref  ·  archive → ar  ·  add-specs → add  ·  backfill → bf 示例：specpilot i my-app 与 specpilot init my-app 完全相同。

每条命令的选项

命令	选项
init	--lang · --framework · --dir · --specs-name · --no-prompts · --dry-run
validate	--fix · --verbose
migrate	--from · --to · --backup
list	--lang · --verbose
refine	--update · --no-prompts
archive	--dry-run · --force
add-specs	--no-analysis · --no-prompts
backfill	--dir · --specs-name · --dry-run · --no-prompts
serve	--port · --poll · --read-only · --open · --no-mcp · --stop

运行 specpilot <command> --help，查看完整的标志说明和默认值。

示例

# Initialize with specific language/framework
specpilot init api --lang python --framework fastapi

# Preview files that would be created without writing anything
specpilot init api --dry-run

# Refine specifications
specpilot refine "REST API for user management" --update

# Validate with auto-fix
specpilot validate --fix

specpilot serve

通过项目的 .specs/ 提供本地 Web UI，你还可以在待办、当前冲刺和审核之间移动任务，批准 Agent 已完成的内容或将其退回，添加新任务，更新 SpecPilot 的命令文件，在尚无 .specs/ 的文件夹中设置 .specs/，以及打开更多项目。不指定文件夹时，它会提供运行命令所在的项目（包含 .specs/ 的文件夹）；也可以指定一个或多个文件夹来提供服务，所有文件夹共用一个服务，或者稍后从页面打开它们。按 Ctrl+C 停止。

specpilot serve                  # this project, at http://127.0.0.1:4321
specpilot serve --port 5000 --open
specpilot serve ../api ../web    # two projects on one server; switch in the left rail
specpilot serve ../new-project   # no .specs/ there yet: the page sets it up (or `specpilot serve .`)
specpilot serve --stop           # stop the server on port 4321 from another terminal (--port for another)

选项	默认值	说明
--port <n>	4321	监听端口（仅限 127.0.0.1）
--poll <ms>	1000	更改检测间隔，单位为毫秒（最小 250）；仅在页面打开时轮询
--read-only		不可移动任务、不可添加任务、不可使用 Setup 视图步骤、不可打开文件夹，也不提供注册表：UI 仅供读取，不显示拖动手柄、Add 或 Archive 按钮，也不提供写入路由
--open		在默认浏览器中打开 UI
--no-mcp		不启用本地 MCP 端点 /mcp（默认会为你的 AI IDE 提供该端点，并在 Home 和 Setup 视图中显示 Connect Your AI IDE 卡片；见下文）。仍接受 --mcp，但不会产生任何变化
--stop		停止此计算机上运行于 --port（默认 4321）的 SpecPilot 服务，效果等同于按 Ctrl+C；不接受其他选项。无法通过此方式停止 --read-only 服务：请在其终端中按 Ctrl+C

• 多个项目：可以指定任意文件夹；没有 .specs/ 的文件夹也会提供服务，并显示设置视图（见下文）。项目按命令行中的顺序从 0 开始编号（../api 是项目 0，../web 是项目 1）；此编号对应服务器 /api/ 路由中的 ?project=<n>，也对应任何非首个项目的页面链接开头的 #1/...（没有编号表示项目 0）。每个项目都有自己的任务、文件和实时重新加载；移动任务只会更改该项目的 tasks.md。从页面打开的文件夹（见下文）会获得下一个编号；服务器运行期间编号不会变化，单个服务器最多承载 20 个项目。
• 退出：左侧栏底部的电源按钮会在确认后停止服务器，效果与 Ctrl+C 或 specpilot serve --stop 相同（会先停止并清理正在运行的副本）。之后页面会显示 SpecPilot 已停止；其他已打开的页面只是不再更新。使用 --read-only 时不显示。
• 移动任务：拖动一行，使用 Alt+Up/Down 重新排序，并使用 Alt+Left/Right 在 Backlog、Current Sprint 和 Review 之间移动（Backlog 和 Current Sprint 可双向移动；Current Sprint 可移至 Review，也可从 Review 移回），或者打开卡片菜单（右键单击、点击卡片上的 ⋯ 按钮，或按 Shift+F10），选择 Move to <lane>（移至该栏末尾，或选择 <lane>, top 移至栏首）、Move up 或 Move down；菜单中还有 Open details 和 Copy ID。移动只会更改 .specs/planning/tasks.md 中的一行，不会更改其他内容，并提供撤销操作；Completed 和 Won't do 中的行无法移动。如果页面加载后文件在磁盘上发生了变化，移动会被拒绝，页面也会重新绘制。使用 --read-only 启动即可关闭移动功能。
• 工作进行中时的警告：当项目位于 main 或 master 以外的分支上，或者 .specs/ 文件在过去两分钟内于磁盘上发生更改，且并非由页面所致（即有 Agent 或编辑器正在工作）时，页面上的移动操作和 Archive 都会先询问。对话框会说明可能发生的情况（更改会随分支上的工作一起提交，并可能在合并时冲突；Agent 保存较旧版本的 tasks.md 可能会撤销更改），并提供 Cancel 或 Move anyway；Archive 会将该检查加入自己的检查列表。页面只知道加载后观察到的情况。Approve 和 Send back 不会询问。
• Review 栏：.specs/planning/tasks.md 中的 ## Review 用于存放已完成、等待你检查后才算完成的工作；栏标题为 Review HITL（human-in-the-loop，人机协作）。你的 AI Agent 会将已完成的工作从 Current Sprint 移至 Review，不会直接移到 Completed（生成的指令文件和 MCP 服务都对此有说明）。打开 Review 卡片：Approve 会在该行追加 Approved <date> 并显示 Approved 标记，面板会说明下一步操作（让你的 Agent 收尾；Copy prompt 会复制相应语句）；Send back 会打开备注框（What needs fixing? (optional)，最多 200 个字符，按 Cmd/Ctrl+Enter 发送，按 Escape 取消），追加 Sent back <date>: <note> 并将该行移至 Current Sprint 的顶部，以便 Agent 接手；两种操作都可撤销，面板会在 History 下列出之前的备注。将卡片拖出 Review，或按 Alt+← 将其移出 Review，等同于不带备注的 Send back，因此已批准后移回的行将不再处于已批准状态。行标记为 Approved 后，Agent 会手动写入 Completed 条目（编号、CD ID、提交）；SpecPilot 从不写入该条目。文件中如有 ## Won't do，它会作为 Completed 后的只读栏显示，默认折叠为一条栏带，点击后展开。使用 --read-only 时关闭。
• Type 和 Priority：当 Backlog、Current Sprint 和 Review 使用 | ID | Type | Priority | Description | 表格（init 写入的格式）时，每张卡片会在底行显示其 Priority（P1 至 P3）和 Type（feat、bug、chore），任务详情会通过两组按钮设置这些值并一次性保存；New Task 也会提供这些选项。仍使用 | ID | Description | 的表格会照常工作；当三个栏都使用此格式时，栏上方会显示一条说明，告诉你如何添加这些列（Copy prompt）。如果三个栏的格式不一致，则会显示警告，因为带有 Type 或 Priority 的行无法移入缺少相应列的表格。使用 --read-only 时关闭。
• 章节标题：如果 .specs/planning/tasks.md 缺少 ## Backlog、## Current Sprint、## Review 或 ## Completed，栏上方会显示警告，列出空栏、文件中现有的内容以及修复方法（编辑文件；最好请你的 AI IDE 操作，这样引用该章节的内容也会一并更新），并提供 Open tasks.md in VS Code 和 Copy prompt；对于看板不认识的 ## 标题，会显示说明，告知其行不会在此处显示；如果已知章节用普通文本行或列表而非表格存放任务，则会显示警告，说明该栏不会显示其中的任务以及如何将它们转换为表格。警告在本次会话中会折叠为一行栏带；说明则会一直显示，直到标题发生变化。specpilot validate 会针对缺少的标题发出警告，--fix 会重命名可明确识别的变体。
• Commands 和 Skills：每个视图都会将文件分为两组列出。From SpecPilot 下列出其字节内容与 SpecPilot 已发布版本相符的 specpilot-* 命令（位于 .claude/commands/ 和 .github/prompts/ 中），以及仍是 SpecPilot 根据你的 project.yaml 生成的 specpilot-project 技能；其他所有内容都列在 Yours 下，包括你编辑过的 specpilot-* 命令。Commands 标题中的 Regenerate All 会对命令文件执行 specpilot backfill 所执行的操作，不做其他更改：对于项目中包含指令文件的每个 IDE，它会在每个 IDE 的命令文件夹中添加缺失的 specpilot-* 命令，并将未编辑过的命令更新为当前版本；这也包括页面未列出的命令文件夹（.cursor/commands/、.windsurf/workflows/、.agent/workflows/、.codex/prompts/）。它还会根据 .specs/project/project.yaml（名称、语言、框架、平台、包管理器、测试框架、仓库 URL、许可证）刷新 .claude/skills/specpilot-project/SKILL.md，前提是该技能仍是 SpecPilot 自己生成的；如果缺少该技能，也会添加。如果你编辑过技能，或者其生成所依据的值已不再与 project.yaml 中的内容相符，则会保留，并说明原因 does not match SpecPilot's render of project.yaml。绝不会写入编辑过的文件、链接、链接文件夹中的文件、你自己的命令和技能、指令文件以及 .specs/。执行情况会在发生时显示于分组上方：已更新、已添加、已保留及原因，以及页面未列出的文件夹。
• New Task：Backlog 或 Current Sprint 栏标题中的 + Add 按钮会打开该栏的小型表单：填写描述，表单上方会显示新行将使用的 ID。SpecPilot 会在 .specs/planning/tasks.md 中该章节表格的末尾添加一行 | <ID> | <description> |，不会更改文件中的其他内容。ID 使用下一个可用编号：Backlog 使用 BL-###，Current Sprint 使用 CS-###；编号比 tasks.md 和 tasks-archive.md 中当前使用的最高编号大 1（只计算 ID 列和行首标签中的 ID，不计算描述中提及的 ID；不会填补空缺）。描述会完全按你输入的内容写入，包括 Markdown；不会添加标签或日期。如果描述中有换行符、控制字符、| 或末尾的 \，或者超过 4000 个字符，则会拒绝添加并说明原因，表单中仍会保留你的输入。新行会被选中，并在详情面板中打开。如果页面加载后文件在磁盘上发生了变化，则不会添加任何内容，页面也会重新绘制。与移动任务一样，此操作受保护；使用 --read-only 时关闭。
• 归档最早的 Completed 行：Completed 栏标题中有一个 Archive 按钮。点击后会打开对话框，说明此操作的作用，并列出适用的检查项及其状态：分支（与 specpilot archive 一样，建议合并后在 main 或 master 上归档）以及 ## Completed 的 40 行限制（specpilot validate 发出的警告），并说明将移动多少行。触发警告的检查项会显示勾选框，勾选所有框后 Archive 按钮才会启用。随后，它会对该章节执行与 specpilot archive 相同的操作：最早的行会逐字节移至 .specs/planning/tasks-archive.md 末尾的带日期区块中，最新的 20 行保留不动，两个文件中的其他内容均不变，栏中会显示剩余内容。即使未超出行数限制，仍可通过勾选限制检查项来归档。prompts.md 交由 specpilot archive 处理。与移动任务一样，此操作受保护；使用 --read-only 时关闭。
• 设置视图：没有 .specs/ 的文件夹（你指定、从页面打开或克隆的文件夹）会显示设置视图，而不是其他视图；Home 上的 Start a New Project 也会显示该视图，并提供 Project name 和 Parent folder（带有 Browse…）。由你的 AI IDE 完成设置：它会读取代码，回答它能回答的问题，并向你询问其余问题。该视图会用三个步骤说明操作方式：1 Connect your AI IDE，显示此服务的配置、Copy 按钮和状态；在 IDE 连接到 /mcp 之前会显示 Waiting for a connection，连接后则显示 Connected · <the IDE's name>；2 Tell it what to do，提供一行可粘贴到 IDE 中的文字（Set up SpecPilot for <folder>，或 Start a SpecPilot project called <name> in <parent>）；3 Progress，显示四行进度，对应 IDE 的调用（Read the code、Answer the questions、Write the files、Validate）。当 .specs/ 出现后，页面会打开该项目；没有 Finish 按钮。新建项目时，页面会在你输入时检查名称和父文件夹，并将 <parent>/<name> 记为本次服务器运行期间唯一可创建新项目的位置；在 IDE 创建项目之前不会创建任何内容，且目标文件夹必须不存在或为空。没有 MCP 时，该视图会说明这一点以及如何重启。在现有文件夹中运行 specpilot add-specs，或在新文件夹中运行 specpilot init，会在终端中提出相同的问题。当前目录默认选项不会提供设置视图（启动需要 .specs/；使用 specpilot serve . 指定该目录）。如果设置中断，下次运行 specpilot serve 时会删除遗留的 .specpilot-setup-<id>/ 文件夹（只删除该文件夹，识别依据为其标记文件）。
• Home：左侧栏顶部的徽标、项目列表下方的 + 磁贴（或按 h 键，或访问 #home）会显示 “Your specs, as a board.”、Open a Project Folder 按钮以及 Recent projects（路径、上次打开时间，以及已打开项目的 git 分支）；点击项目即可打开，点击 Remove from list 可将其从列表中移除（不会更改文件夹）。specpilot serve 会从第一个项目的 Tasks 视图启动（你指定的第一个文件夹；如果没有，则使用最近打开的项目）；如果文件夹没有 .specs/，且没有任何已记住的项目，它会在未打开项目的状态下启动并显示 Home（终端会显示 No .specs/ folder in <folder>；该文件夹本身不会被提供服务，使用 specpilot serve . 指定它）。使用 --read-only 时没有 Home，因此没有 .specs/ 的文件夹仍会以状态码 1 退出。
• 从页面打开项目：Home 上的 Open a Project Folder 会打开一个面板（Clone a Repository 会打开同一面板的 Clone 标签页）；输入文件夹路径（/Users/you/project 或 ~/project），或点击 Browse… 在系统文件夹对话框中选择文件夹（macOS；安装了 zenity 或 kdialog 的 Linux；Windows），然后点击 Open，该文件夹便会与其他项目一同获得服务；如果没有 .specs/，则会显示设置视图。以此方式打开的文件夹下次会列在 Recent projects 中，并记录到 ~/.specpilot/projects.json（路径、上次打开时间和固定标记，最多 50 个；首次为项目提供服务时会创建该文件，每个获得服务或打开的项目都会加入其中）。启动时，在你指定的文件夹之后，具有 .specs/ 的已记住项目会按固定状态和最近打开时间排序重新打开，总数最多为 20 个（终端会显示 Reopened <k> remembered projects from ~/.specpilot/projects.json.）；没有 .specs/ 的文件夹仍保留在列表中，供你点击打开；不存在的文件夹会被跳过，重新打开项目不会更改该文件。Remove from list 会忘记文件夹，但不会更改它。Browse… 只会填入路径；点击 Open 后才会打开文件夹。Clone 标签页中的 Parent folder 和设置视图（Start a New Project）中的 Parent folder 也有相同的 Browse… 按钮，同样只会填入字段。已在 macOS 上测试：选择文件夹后会填入字段，点击 Open 会打开文件夹；无论在 Browse… 还是 Open 时都不会出现隐私提示，即使文件夹位于 ~/Documents 中也一样。Linux 和 Windows 的对话框尚未手动测试。主目录、驱动器根目录以及已打开的文件夹都会被拒绝；无法读取的 projects.json 会保持原样，页面和终端都会说明原因。此操作与移动任务一样受保护。
• 从页面克隆仓库：Home 上的 Clone a Repository（或同一面板中的 Clone 标签页）会要求输入仓库 URL、父文件夹和文件夹名称（留空则使用仓库名称），然后运行你已安装的 git clone 并打开结果：如果仓库有 .specs/，则在 Tasks 视图中打开；如果没有，则在设置视图中打开。接受的 URL 格式：https://host/path、git@host:path 和 ssh://host/path；https URL 不得包含用户名或密码（git 会像在终端中一样使用你的凭据助手和 ssh 密钥），因此对于 Azure DevOps，请省略 org@ 部分。不克隆子模块，也没有分支或深度选项。目标文件夹必须不存在或为空；父文件夹必须符合 Start a New Project 的规则。输入或粘贴 URL 时，只要你还没手动输入文件夹名称，Folder name 就会填入仓库名称。克隆运行期间，面板会显示已用时间；git 报告后还会显示其阶段和百分比（Receiving objects 42% · 0:13，随后是 Resolving deltas 和 Updating files）；在此之前，或 git 未报告进度时，会显示动态进度条。git 不会收到任何可能让它等待输入的问题：如果仓库需要但无法获取登录信息，git 会返回自己的错误消息，即最后一行 fatal: 错误及其上一行，例如 Host key verification failed. fatal: Could not read from remote repository.；克隆运行 10 分钟后会停止。页面无法替你接受 ssh 主机密钥：如果你从未连接过该主机，请先在终端中运行一次 ssh -T git@host，然后重新克隆。将按原样使用你的 ssh 设置；SpecPilot 在 macOS 和 Linux 上不会设置 ssh 选项。一次只能运行一个克隆任务。克隆失败、被停止或取消（点击 Cancel、按 Escape、关闭标签页或按 Ctrl+C）时，都会删除已下载的内容；按 Ctrl+C 时服务器最多等待 5 秒进行清理。需要在 PATH 中有 git。这是 SpecPilot 唯一会为页面启动其他程序、也是唯一会使用网络的情况。在 Windows 上，ssh 会以批处理模式运行（除非你设置了 GIT_SSH_COMMAND、GIT_SSH 或 core.sshCommand）；被停止的克隆任务可能会留下 git 辅助进程，直到该进程自行结束后清理才会尝试，因此如果辅助进程仍占用文件，清理可能会失败；届时会显示相应消息。
• 在 VS Code 中打开：每个项目视图右上角的图标（以及 Home 上每个仍存在的 Recent project 旁边的图标）都是指向该项目文件夹的 vscode://file/ 链接。浏览器会将链接交给 VS Code，VS Code 会在打开前询问；SpecPilot 本身不会启动任何程序。如果未安装 VS Code，则不会发生任何操作。任务详情面板中有 Open tasks.md in VS Code，会打开 .specs/planning/tasks.md 并定位到该任务所在行；VS Code 会在它选择的窗口中打开文件（默认是你最后使用的窗口），该窗口可能不属于此项目。只会打开 VS Code，不会打开 Insiders 或其他编辑器。每个 .specs/ 文件的文件视图，以及 Instructions、Commands 和 Skills 文件的每个详情面板中也有 Open in VS Code，用于打开相应文件。
• 在 AI IDE 中打开：当有可用操作时，Open in VS Code 旁边的闪光图标会显示一个简短菜单。若项目中有 .cursor/rules/specpilot.mdc（SpecPilot 为 Cursor 写入的文件），则会显示 Open in Cursor（cursor://file/）。只要 .specs/development/onboarding.md 存在，Send onboarding prompt to Cursor 就会通过 Cursor 自己的链接将提示词发送到 Cursor 聊天窗口（提示词保留在本机；Cursor 会等待你确认，并使用当前置顶的窗口，因此请先在 Cursor 中打开项目）；Copy onboarding prompt 则会复制提示词，供没有打开链接功能的 Claude Code 或其他 IDE 使用。对于过长而无法放入 Cursor 链接的提示词（10,000 个字符），会改为复制提示词。此选项只在项目视图中显示，不会显示在 Home 的项目行中。
• 不会写入其他内容：在有 .specs/ 的项目中，服务器唯一能更改的文件是其 .specs/planning/tasks.md，以及通过 Regenerate All 更改的 specpilot-* 命令文件和 specpilot-project 技能；在没有 .specs/ 的指定文件夹中，设置过程会创建新文件，不会更改其他内容；新项目是一个带有新文件的新文件夹（或空文件夹）；克隆项目是一个由 git clone 填充的新文件夹（或空文件夹）；~/.specpilot/projects.json 是项目以外唯一会写入的文件；其他所有内容都会在每次请求时读取。
• 仅限回环地址：仅绑定到 127.0.0.1；任何不是 127.0.0.1:<port> 或 localhost:<port> 的 Host 标头都会被拒绝（403）。
• 实时重新加载：页面打开期间，每隔 --poll 毫秒通过 stat() 轮询允许访问的文件，并在 /api/events 上推送更改的路径；打开的页面会就地更新。
• 显示内容：.specs/、CLAUDE.md、AGENTS.md、.github/copilot-instructions.md、.claude/commands/、.claude/skills/ 和 .github/prompts/，均以文件自身的文本显示。
• 限制：不会显示经过符号链接文件夹的路径、隐藏文件和 node_modules。如果无法仅更改一行，移动任务和新建任务会被拒绝，而不会尝试近似处理：例如尚无表格的章节（新项目中的 [TODO]）、文件末尾没有换行符且移动涉及最后一行，或 tasks.md 不是有效的 UTF-8。如果编辑器恰好在服务器写入文件的同时保存 tasks.md，其保存内容可能会被覆盖；git 可用于恢复文件。VS Code 会将以 :<number> 结尾的路径视为行号，因此名称以这种形式结尾的项目文件夹（notes:12）可能无法通过 Open in VS Code 作为文件夹打开。该链接中的 Windows 路径（C:\…）未经测试。在安装了 Cursor 的机器上，Cursor 链接未经测试；Windsurf 目前没有相关链接。添加或移除 .cursor/rules/specpilot.mdc 后，该变化会在页面下次刷新时显示，而不会立即显示，因为此文件不会被监视。设置视图中的 Connected 状态会显示 IDE 连接时发送的名称（clientInfo）；已通过两个 MCP 修订版本的测试请求进行检查，但未在所有 IDE 中检查。设置工具所需的顺序会通过 MCP instructions 和工具说明发送；IDE 是否会向其 Agent 显示 instructions 由 IDE 决定，目前仅通过测试请求进行了检查。能够读取此页面的本地程序也可以自行注册新项目的文件夹：设置工具旨在避免 Agent 因操作失误而写入其他位置，并不能防范已在你计算机上运行的软件。

本地 MCP 端点（specpilot serve）

服务器也会在 http://127.0.0.1:<port>/mcp 上响应 MCP 请求，因此这台机器上的 Claude Code、Cursor 和其他 AI IDE 可以读取规范，并通过与页面相同的检查添加或移动任务。该功能默认开启；启动时加上 --no-mcp 即可关闭（之后 Setup 视图会说明如何重新启动）。仍接受 --mcp，但不会产生任何影响。

specpilot serve
# MCP endpoint: http://127.0.0.1:4321/mcp
# Add to your IDE's MCP settings: {"mcpServers":{"specpilot-local":{"type":"http","url":"http://127.0.0.1:4321/mcp","headers":{"X-SpecPilot-Token":"<token>"}}}}

从终端、Home 上的 Connect Your AI IDE 卡片，或 Setup 视图第 1 步（Copy 按钮）复制该行，粘贴到 IDE 的 MCP 设置中；也可以粘贴到项目中的 .mcp.json，并将 .mcp.json 加入 .gitignore。

• 工具：specpilot_list_projects、specpilot_read_spec、specpilot_list_tasks、specpilot_new_task、specpilot_move_task、specpilot_validate_specs（不使用 --fix，不会写入任何内容）和 specpilot_regenerate_commands。每个工具都可选择指定 project 索引。两个任务写入工具都需要 specpilot_list_tasks 返回的 sha256；如果 tasks.md 此后发生更改，写入将被拒绝（提示“自上次读取后已更改”），且不会写入任何内容。打开的页面会通过实时重新加载显示更改。
• 设置工具：specpilot_setup_questions（接受路径）返回在代码中检测到的内容以及所有问题，包括选项和建议；specpilot_setup_project（接受路径、答案和用户提供了哪些答案）会写入 .specs/、指令文件和技能（并创建新项目的文件夹），运行 specpilot validate，然后返回已写入的文件和结果。总计 9 个工具。它们仅适用于页面正在设置的文件夹：你指定、打开或克隆且没有 .specs/ 的文件夹，或你在 Setup 视图中指定的新项目文件夹。服务器会告知 IDE 操作顺序（提出问题、从代码中获取答案、询问用户其余问题、写入、报告结果）。Setup 视图中的 Progress 行会跟随这些调用更新。
• 与页面相同的防护机制：仅限 loopback、Host 检查、令牌检查（错误或缺失的 X-SpecPilot-Token 会导致 403）、仅限 JSON、大小上限为 64 KB、页面的读取允许列表、页面的写入允许列表，以及页面和 IDE 共用一把写入锁。来自网页的请求（任何其他 Origin）都会被拒绝并返回 403；IDE 不会发送 Origin。克隆和项目列表不是工具。
• 协议版本：MCP 2026-07-28（无握手；版本、Mcp-Method 和 Mcp-Name 标头必须与请求正文匹配），以及 2025-11-25 和 2025-06-18（使用 initialize），均使用同一个 URL。支持两种版本的客户端会自行选择一种；配置行相同。使用 Streamable HTTP，仅支持 POST，不使用会话；响应为 JSON，不会以流形式发送，也不会发送更改通知。
• 令牌：每次启动 serve 都会生成一个新令牌，因此重启后需要重新复制该行。若要保持配置行不变，可在 serve 和 IDE 的环境中设置 SPECPILOT_MCP_TOKEN（至少 32 个字符，不能包含空格）；配置行随后会显示 ${SPECPILOT_MCP_TOKEN}，Claude Code 会从环境中填入令牌（其他 IDE：请将其替换为令牌）。SpecPilot 不会将令牌写入任何位置。
• --read-only：仅提供 4 个读取工具（不包含任务写入、Regenerate 或设置工具）；端点使用自己的令牌，页面仍为只读。
• 指令文件：由 init、add-specs 以及通过 AI IDE 进行设置生成的文件还会附带一项流程要求：连接时，任务必须使用 SpecPilot MCP 工具；否则编辑 .specs/planning/tasks.md，并保留其表格格式（Backlog、Current Sprint 或 Review 下使用 | ID | Type | Priority | Description |，或在已有相应格式的文件中使用 | ID | Description |；Completed 下使用 | # | ID | Description |；每个任务占一行）。如果现有文件中没有 Tasks 行，specpilot backfill 会将其添加进去。

支持的语言和框架

TypeScript

• React：单页应用
• Express：REST API
• Next.js：全栈应用
• Nest.js：可扩展的服务端应用
• Vue：渐进式 UI 框架
• Angular：企业级单页应用框架

JavaScript

• React：SPA 应用
• Express：REST API

注意：JavaScript 不会显示框架提示词——如有需要，请显式传入 --framework。

Python

• FastAPI：现代 REST API
• Django：全栈应用
• Flask：轻量级 REST API
• Streamlit：数据科学 / ML 应用

Kotlin

• Android：原生 Android 应用
• Spring：服务端 REST API
• Ktor：异步 Kotlin Web 框架
• Compose：Jetpack Compose UI

Swift

• iOS：原生 iOS 应用
• SwiftUI：声明式 Apple UI
• Vapor：Swift 服务端框架

项目结构

SpecPilot 会生成一个 .specs/ 文件夹，其中包含组织有序的子目录：

.specs/
├── architecture/
│   ├── api.yaml              # CLI / REST API / GraphQL interface spec
│   └── architecture.md       # System design decisions and patterns
├── development/
│   ├── context.md            # Development memory, decisions, learnings
│   ├── onboarding.md         # One-time AI bootstrap prompt — delete after first use
│   └── prompts.md            # AI interaction log — MANDATED, update every session
├── planning/
│   ├── roadmap.md            # Release milestones and objectives
│   └── tasks.md              # Sprint tracker (backlog / current / completed)
├── project/
│   ├── project.yaml          # Project config and AI context (MANDATED)
│   └── requirements.md       # Functional & non-functional requirements
├── quality/
│   └── tests.md              # Test strategy, coverage targets, acceptance criteria
└── security/
    ├── security-decisions.md # ADR-style security design decisions
    └── threat-model.md       # Threat inventory with impact/likelihood/mitigation

还会在项目根目录生成一个 AI 上下文文件（.github/copilot-instructions.md、CLAUDE.md、.cursor/rules/specpilot.mdc、.windsurfrules、.antigravity/rules.md 等），具体取决于你选择的 IDE/Agent

配置

SpecPilot 无需全局配置。每个项目都是独立的，设置保存在 project.yaml 中。

IDE 和 Agent 支持

SpecPilot 会在项目初始化期间生成 AI Agent 配置文件。运行 specpilot init 时，系统会提示你选择 AI IDE/Agent：

桌面 IDE（工作区设置）：

• GitHub Copilot - 集成 Copilot 的行业标准工具
• Cursor - 优化 AI 上下文的 AI 优先代码编辑器
• Windsurf - 高级 AI 编码助手
• Antigravity - 具备上下文感知能力的 AI 驱动 IDE

云端 AI Agent（指令文件）：

• Claude Code - Anthropic Claude Code CLI Agent（CLAUDE.md）
• Codex - 具有指令上下文的 OpenAI Codex Agent

生成的配置文件：

每种 IDE/Agent 选择都会在项目根目录生成一个 AI 上下文文件：

IDE/Agent	生成的文件
GitHub Copilot	.github/copilot-instructions.md
Codex	.github/copilot-instructions.md
Cursor	.cursor/rules/specpilot.mdc
Windsurf	.windsurfrules
Antigravity	.antigravity/rules.md
Claude Code	CLAUDE.md

所有上下文文件均包含：项目名称 / 技术栈、关键要求、代码理念、代码规则和重新锚定提示词。

对于桌面 IDE：.vscode/settings.json（或 .cursor/、.windsurf/ 等）

• IDE 专属的工作区文件夹设置，用于代码和 .specs
• 开发所需的扩展推荐
• 用于更好地集成规范的 AI 上下文配置

生成的斜杠命令

每种 IDE/Agent 选择还会生成 8 个 specpilot-* 斜杠/工作流命令（status、reanchor、report、sync、refine、validate、archive、backfill），将关键 CLI 操作映射为编辑器内命令——例如，Claude Code 使用 .claude/commands/specpilot-status.md，Cursor 使用 .cursor/commands/，GitHub Copilot 使用 .github/prompts/。在现有项目上运行 backfill，会为已配置的 IDE 补齐缺失的命令，并将未编辑过的命令更新到当前版本；已编辑的文件会保留并列出。每个命令文件都会报告为已添加、已更新（至当前版本）或已保留，并说明原因：kept: modified（你修改过；删除该文件并重新运行 specpilot backfill 即可获取最新版本）、kept: CRLF line endings（已知版本使用 Windows 换行符保存）、kept: symbolic link（不会写入链接所指向的文件）、kept: folder is a symbolic link or not a folder（不会写入链接指向的 .claude/ 或类似目录），或 kept: could not be written: <code>（写入失败；其余操作仍会继续）。specpilot serve 页面上的 Regenerate All 会执行相同的步骤。完整列表及各 IDE 对应的路径，请参阅完整指南。

生成的设置/指令会自动配置你的 AI Agent，以便：

• 将 .specs/ 文件夹纳入 AI 上下文
• 了解项目结构和需求
• 遵循规范驱动开发原则
• 使用开发指南和入门提示词

示例：

# During init, you'll be prompted to select your IDE/Agent
specpilot init my-project --lang typescript --framework react
# Respond with your preferred IDE/Agent:
# - vscode, cursor, windsurf, antigravity (desktop)
# - claude-code, codex (cloud agents)

故障排除

常见问题

权限错误

sudo chown -R $USER ~/.npm-global
npm config set prefix '~/.npm-global'

未找到模板

specpilot list --verbose

验证失败

specpilot validate --verbose --fix

迁移问题

错误："Source structure 'complex' not found"

# For NEW projects, use:
specpilot init my-project

# For EXISTING projects without specs:
specpilot add-specs

# Only use migrate if you have an old .project-spec folder
specpilot migrate --from complex --to simple --backup

调试模式

DEBUG=specpilot specpilot <command>

为什么选择 SpecPilot？

SpecPilot 实践规范驱动开发（SDD），优先编写规范：

Specifications → Architecture → Code → Tests → Deployment

优点：

• 清晰：每个人都清楚需要构建什么
• 一致：在各项目中采用标准化结构
• 质量：内置验证和测试
• 适配 AI：为 AI 助手提供清晰的上下文
• 易于维护：提供全面的文档

参与贡献

本项目遵循 SDD 原则。贡献指南请参阅 .specs/。

开发环境设置

git clone https://github.com/girishr/SpecPilot.git
cd SpecPilot
npm install
npm run build
npm link  # For local testing

specpilot serve 的浏览器测试

页面的点击、按键、焦点和实时重载会在无头 Chromium 中进行测试，与 npm test 分开运行：

npx playwright-core install chromium-headless-shell  # once, if Playwright's Chromium is not on this machine yet
npm run test:browser                                  # builds, then runs src/__browser__/ (about 10 s)

测试套件会在临时 HOME 目录下的项目样例副本（src/__browser__/fixture/，而非本仓库自身的 .specs/）上启动构建后的服务，因此不会在仓库或 ~/.specpilot/ 中写入任何内容。测试失败时，会打印错误信息和堆栈、屏幕截图以及页面 HTML 的路径；这些文件会保存在临时文件夹中。

快速贡献指南

1. 查看 .specs/project/requirements.md
2. 检查 .specs/planning/tasks.md
3. 进行更改时同步更新规范
4. 提交前运行 specpilot validate

发布遵循 docs/RELEASING.md 中的清单。

文档

• 完整指南：全面的文档
• SpecPilot 与 GitHub Spec Kit 的比较：并排比较，帮助你选择合适的工具
• 更新日志：版本历史
• 问题反馈：错误报告和功能请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

---

秉持规范驱动开发原则，为严肃的生产项目打造。