项目定位

Spec Workflow MCP 是一个基于 Model Context Protocol（MCP）的服务器，专注于实现结构化的规范驱动开发（spec-driven development）流程 资料来源：README.md:1-2。它由三个互相协作的组件组成：MCP 核心服务器、实时 Web 仪表盘（Web Dashboard）以及 VSCode 扩展，形成从规范定义、任务分配到实现追踪的完整闭环。

项目以 GPL-3.0 协议开源 资料来源：vscode-extension/package.json:6，目标用户是需要与 AI 代理（如 Claude、GPT 系列）协同完成软件开发工作的团队和个人开发者。

核心能力

项目内置以下主要能力模块 资料来源：README.md:62-70：

• 结构化开发工作流：按 Requirements → Design → Tasks 的顺序生成规范文档
• 实时 Web 仪表盘：通过 WebSocket 推送同步规范状态、任务进度与审批请求
• VSCode 集成：在编辑器侧边栏直接管理规范工作流 资料来源：vscode-extension/README.md:1-9
• 审批工作流：支持通过、拒绝、请求修订以及带版本历史的修订追踪 资料来源：vscode-extension/src/extension/types.ts:50-78
• 实现日志：可搜索的任务实现日志，包含代码行数变更统计 资料来源：vscode-extension/src/extension/types.ts:90-95
• 多语言界面：原生支持英文、中文、日文等 11 种语言 资料来源：README.md:78-82

快速开始

环境要求

• VSCode 版本：1.99.0 或更高 资料来源：vscode-extension/package.json:17
• 工作区要求：需包含 .spec-workflow 目录结构
• Node.js：用于安装依赖与构建项目

安装与构建

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式运行
npm run dev

资料来源：README.md:50-58

初始化项目结构

在项目根目录初始化后，将生成以下 .spec-workflow 目录结构 资料来源：README.md:30-46：

your-project/
  .spec-workflow/
    approvals/      # 审批请求持久化
    archive/        # 已归档规范
    specs/          # 活跃规范文档
    steering/       # 指导文档（产品/技术/结构）
    templates/      # 内置模板
    user-templates/ # 用户自定义模板
    config.example.toml

VSCode 扩展命令

VSCode 扩展通过 onStartupFinished 事件自动激活 资料来源：vscode-extension/package.json:22-25。激活后将在活动栏中显示 "Spec Workflow" 图标，提供以下命令 资料来源：vscode-extension/README.md:38-50：

扩展还提供可配置的音效提醒功能 资料来源：vscode-extension/README.md:55-57，包括审批提醒和任务完成提醒。

仪表盘前端结构

Web 仪表盘基于 React 构建，主入口为 App.tsx 资料来源：src/dashboard_frontend/src/modules/app/App.tsx:1-20。界面采用多语言机制，每种语言对应独立的 JSON 本地化文件，例如 en.json 资料来源：vscode-extension/src/webview/locales/en.json:1-10 和 zh.json 资料来源：vscode-extension/src/webview/locales/zh.json:1-10。

仪表盘主要面板包括：项目概览（Overview）、指导文档（Steering）、规范文档（Specs）、任务管理（Tasks）、审批请求（Approvals）以及实现日志（Logs） 资料来源：vscode-extension/src/webview/locales/en.json:5-11。

社区反馈与已知问题

根据社区反馈，存在以下需要关注的实践要点：

• 任务模板格式兼容性：官方 tasks-template.md 使用 checkbox 与任务标题分行的格式，与仪表盘的解析器存在不兼容问题；开发者创建任务时应确保 checkbox 与标题处于同一行 资料来源：Issue #218
• 审批路径校验：早期版本存在 categoryName 路径穿越风险，目前已通过参数校验修复 资料来源：Issue #220
• 远端访问仪表盘：用户曾要求支持远端访问仪表盘以便团队共享，该需求已在后续版本中实现 资料来源：Issue #202

配套文档

项目提供以下技术文档 资料来源：README.md:18-26：

• FLOW.md — 开发工作流与最佳实践
• INTERFACES.md — 仪表盘与 VSCode 扩展接口说明
• PROMPTING-GUIDE.md — 高级提示词示例
• TOOLS-REFERENCE.md — MCP 工具完整参考
• TROUBLESHOOTING.md — 常见问题与解决方案

参见

• MCP 工具参考
• 审批工作流
• 仪表盘与界面

整体架构概览

Spec Workflow MCP 是一个面向结构化规格驱动开发（spec-driven development）的 Model Context Protocol (MCP) 服务器，由三个相互协作的子系统构成：MCP 核心服务器、实时 Web 仪表盘、VSCode 扩展。三者共享同一份以 .spec-workflow/ 为根的本地文件系统作为唯一事实源（single source of truth），并在协议层通过 MCP 工具与 WebSocket 事件总线进行协作 README.md。

整体目录约定如下：

your-project/
  .spec-workflow/
    approvals/   # 审批请求与修订历史
    archive/     # 已归档的旧规格
    specs/       # 活跃规格（requirements / design / tasks）
    steering/    # 产品、技术、结构等指导文档
    templates/   # 内置模板
    user-templates/  # 用户自定义模板
    config.example.toml

资料来源：README.md

系统的设计哲学是「以 Markdown 文件为持久化层、以 MCP 工具为人机交互层、以仪表盘/编辑器为可视化层」，从而保证 AI 代理（agent）与人类开发者可以同时读写同一份结构化数据。

核心组件与职责

资料来源：README.md、vscode-extension/README.md、vscode-extension/package.json

graph LR
  Agent[AI Agent / LLM] -- MCP Tools --> Core[MCP Core Server]
  Dev[Developer] -- Browser --> Dash[Web Dashboard]
  Dev -- Sidebar --> Ext[VSCode Extension]
  Core -- Read/Write --> FS[(.spec-workflow/)]
  Dash -- WebSocket --> Watcher[File Watcher]
  Ext -- FileSystem Watcher --> FS
  Watcher -- Event Bus --> Dash
  Ext -- "vscode.commands" --> Core

数据模型与共享类型

系统通过一组强类型的 TypeScript 接口在前后端与扩展之间传递状态。ApprovalData 是审批子系统的核心数据结构，其字段同时覆盖文档审批与动作审批两类场景：

• type: 'document' | 'action'
• status: 'pending' | 'approved' | 'rejected' | 'needs-revision'
• category: 'spec' | 'steering'，配合 categoryName 实现分类归档
• revisionHistory 数组记录每次修订的版本号、内容与时间戳

资料来源：vscode-extension/src/extension/types.ts

ApprovalComment 支持多行选区与高亮颜色，保留向后兼容的 lineNumber 字段；SteeringStatus 通过布尔字段区分 product / tech / structure 三类指导文档的存在性 vscode-extension/src/extension/types.ts、vscode-extension/src/webview/lib/vscode-api.ts。

需要特别注意的是，社区曾报告 categoryName 未做路径校验即可被 ApprovalStorage.createApproval() 直接拼接，存在目录遍历风险（issue #220）。这表明数据模型虽简洁，但安全校验必须在存储层额外加固，而非依赖类型约束。

关键流程与运行时行为

1. 规格创建工作流。 顺序生成 Requirements → Design → Tasks 三份 Markdown 文档，每份都遵循 templates/ 下的内置模板 README.md。社区反馈 tasks.md 的 checkbox 与任务标题分两行书写时，仪表盘的解析器无法识别（issue #218），这提示模板语法与解析器之间存在隐式契约。

2. 实时更新链路。 仪表盘通过 useWs() Hook 订阅 WebSocket；App.tsx 中 AppInner 读取 initial 状态以渲染首屏，并使用 localStorage 持久化侧边栏折叠状态 src/dashboard_frontend/src/modules/app/App.tsx。扩展侧则利用 onStartupFinished 激活事件在 VSCode 启动后自动加载，并提供 Spec Workflow: Refresh Data 命令用于手动同步 vscode-extension/package.json。

3. 国际化与可访问性。 locales/ 目录提供 11 套翻译资源（含 zh.json、ja.json、ar.json 等），键名覆盖顶部导航、Tab 标签、审批弹窗与提示语 vscode-extension/src/webview/locales/zh.json、vscode-extension/src/webview/locales/ja.json。

4. 仪表盘远程访问。 默认情况下 Web 仪表盘仅绑定 localhost；社区曾要求暴露到公网共享（issue #202），项目维护者确认已实现该能力，但用户需自行配置网络与鉴权。

已知约束与演进方向

• 响应编码： 当前使用 @toon-format/toon，社区提出 GCF 在压缩率与 LLM 可读性上更优（issue #230）。
• 资源丰富度： 规格文档尚不支持内嵌 SVG/PNG 等图片资产（issue #229）。
• 日志路径： 实现日志目录目前硬编码，社区已请求通过 config.toml 自定义（issue #213）。
• 安全加固： categoryName 路径遍历漏洞需在存储层增加白名单或规范化处理（issue #220）。

See Also

• README.md — 项目总览与功能矩阵
• vscode-extension/README.md — 扩展命令与设置
• vscode-extension/src/extension/types.ts — 共享数据模型定义

一、概述与项目定位

spec-workflow-mcp 是一个基于 Model Context Protocol（MCP）的服务端实现，致力于为 AI 代理与人类协作者提供结构化的规范驱动开发（Spec‑Driven Development）体验。整个系统的核心资料存放在项目根目录下的 .spec-workflow/ 文件夹中，其下划分出 specs/、approvals/、steering/、archive/、templates/、user-templates/ 等子目录，分别承担规范文档、审批记录、指导文档、归档与模板等职责 资料来源：README.md:42-58。

系统通过三大支柱支撑完整的开发循环：

1. 规范工作流（Spec Workflow）：使用 Steering 文档（product.md、tech.md、structure.md）约束全局方向，在 specs/<name>/ 下生成 requirements.md、design.md、tasks.md 三件套；
2. 任务管理（Task Management）：基于 tasks.md 解析任务列表，跟踪 pending / in‑progress / completed / blocked 四种状态；
3. 审批系统（Approval System）：针对规范文档或具体动作发起审批请求，附带评论、注释、高亮与修订历史，闭环后纳入实现日志 资料来源：vscode-extension/src/extension/types.ts:25-72。

此外，VSCode 扩展（vscode-extension/，当前版本 1.1.7）以侧边栏仪表盘的形式提供本地化交互，Web 仪表盘（src/dashboard_frontend/）则提供跨团队的远程访问能力 资料来源：vscode-extension/package.json:1-10、资料来源：vscode-extension/README.md:1-15。

二、任务管理子系统

2.1 数据模型与状态机

任务的核心数据结构在 src/core/task-parser.ts 中定义，并通过 vscode-extension/src/extension/types.ts 中导出的 TaskStatus 联合类型规范状态机：

2.2 解析与校验管线

任务解析分为两个阶段：

• 解析阶段：src/core/parser.ts 读取 tasks.md，使用 ## 区块拆分任务组，并提取编号、标题、状态复选框与子项元数据；
• 校验阶段：src/core/task-validator.ts 校验每个任务的必填字段（文件、需求、复选框格式），不通过的任务会进入 UI 的告警视图 资料来源：vscode-extension/src/webview/lib/vscode-api.ts:62-68。

2.3 常见兼容性陷阱

社区报告指出，官方 tasks-template.md 将复选框与任务标题分两行书写，会导致仪表盘解析失败；用户应确保使用单行格式 - [ ] 1. 标题，并将 _Requirements: 1.1_ 写为缩进的子项 资料来源：Issue #218。

三、审批系统

3.1 数据模型

ApprovalData 是审批系统的核心实体，定义如下关键字段：

• id、title、description 与 filePath：标识与被审文件路径；
• type: 'document' | 'action'：区分文档审批与动作审批；
• status: 'pending' | 'approved' | 'rejected' | 'needs-revision'：审批状态机；
• comments: ApprovalComment[]：内嵌评论，支持单行/多行选择（startLine / endLine）与高亮颜色；
• revisionHistory：包含 version、content、timestamp、reason 的修订版本数组；
• category 固定为 'spec'，categoryName 表示所属规范名称 资料来源：vscode-extension/src/extension/types.ts:62-90、资料来源：vscode-extension/src/webview/lib/vscode-api.ts:35-58。

3.2 存储与持久化

src/dashboard/approval-storage.ts 中的 ApprovalStorage 负责将审批写入 .spec-workflow/approvals/ 目录的 JSON 文件。src/tools/approvals.ts 则将其包装为 MCP 工具，暴露给 AI 代理调用。

3.3 已知安全风险

社区披露了 categoryName 路径穿越漏洞：createApproval() 仅对 filePath 做绝对路径与 .. 检查，但直接拼接 categoryName 到 approvals 目录之下，攻击者可通过 ../ 跳出目录写入任意文件。该问题要求在存储层增加正则白名单（如 /^[a-zA-Z0-9_-]+$/）以及规范化（path.normalize）防御 资料来源：Issue #220。

四、实现日志与多语言支持

4.1 实现日志（Implementation Log）

src/dashboard/implementation-log-manager.ts 追踪每个规范在实施阶段产生的变更条目，包含 linesAdded、linesRemoved、filesChanged 三个聚合指标 资料来源：vscode-extension/src/webview/lib/vscode-api.ts:71-74。社区已请求支持 config.toml 中的自定义日志目录路径，以便将日志集中存放到共享存储或独立卷 资料来源：Issue #213。

4.2 多语言与远程访问

Webview 通过 vscode-extension/src/webview/locales/*.json 提供 10 余种语言（英、日、中、西、葡、德、法、俄、意、韩、阿）。仪表盘层面，社区已确认支持远程启动以供团队共享访问（已通过配置实现） 资料来源：vscode-extension/src/webview/locales/zh.json:1-15、资料来源：Issue #202。

4.3 进阶路线与生态建议

社区同时讨论了两项扩展方向：

• 图像资产打包：在 specs/<name>/assets/ 下放置 SVG/PNG，并由 design.md 相对引用，使规范自包含 资料来源：Issue #229；
• TOON → GCF 编码替换：将工具响应的 @toon-format/toon 编码替换为 Graph Compact Format，以获得更佳的压缩率与 LLM 可读性 资料来源：Issue #230。

See Also

• 项目主页与工具参考
• VSCode 扩展文档
• Issue #218 — tasks 模板兼容性
• Issue #220 — 审批 categoryName 路径穿越
• Issue #229 — 规范中的图像资产

一、项目目录结构与运行时配置

Spec Workflow MCP 将所有规格、模板与配置统一存放在仓库根目录下的 .spec-workflow/ 目录中，便于在多工具（MCP、仪表盘、VSCode 扩展）之间共享同一份事实来源。资料来源：README.md

.spec-workflow/
  approvals/          # 审批请求持久化目录
  archive/            # 已归档的规格
  specs/              # 当前活动的规格（Requirements/Design/Tasks）
  steering/           # 项目级 Steering 文档
  templates/          # 官方任务/需求/设计模板
  user-templates/     # 用户自定义模板
  config.example.toml # 配置示例文件

配置入口为 config.example.toml，社区曾提出希望支持自定义日志目录路径（详见 issue #213），以避免日志污染工作区。仪表盘前端还会将侧边栏折叠状态持久化到 localStorage，键值为 spec-workflow-sidebar-collapsed。资料来源：src/dashboard_frontend/src/modules/app/App.tsx

二、部署模式

2.1 MCP 服务器与开发模式

标准开发流程使用 npm 脚本：

npm install
npm run build
npm run dev

资料来源：README.md

2.2 Web 仪表盘的远程访问

仪表盘早期默认仅监听 localhost，社区曾请求在远端暴露仪表盘以方便团队访问。该功能已被实现（详见 issue #202），意味着部署时可通过宿主网络或反向代理将仪表盘开放给局域网/广域网用户。仪表盘依赖 WebSocket 推送以实现实时刷新（详见 App.tsx 中的 useWs() 调用）。

2.3 VSCode 扩展

VSCode 扩展以独立 npm 包发布，要求 VSCode ^1.99.0，并在启动完成后激活。资料来源：vscode-extension/package.json

graph LR
  A[MCP Server] -->|读写| B[.spec-workflow/]
  C[Web Dashboard] -->|HTTP/WS| A
  D[VSCode Extension] -->|File Watcher| B
  D -->|MCP 集成| A
  B --> E[approvals/]
  B --> F[specs/]
  B --> G[steering/]
  B --> H[archive/]

三、VSCode 扩展的可配置项

VSCode 扩展允许用户通过设置调整通知行为，主要集中在声音通知。资料来源：vscode-extension/README.md

这些设置对应的 TypeScript 类型为 SoundNotificationConfig，定义于 vscode-extension/src/extension/types.ts 与 vscode-extension/src/webview/lib/vscode-api.ts。扩展还提供一组命令用于日常操作，例如 Spec Workflow: Open Dashboard、Spec Workflow: Approve、Spec Workflow: Request Revision、Spec Workflow: Add Comment 等（详见 vscode-extension/package.json）。

界面文案支持多语言（英、日、中、西、葡、德、法、俄、意、韩、阿共 11 种），中文资源文件位于 vscode-extension/src/webview/locales/zh.json。

四、安全考虑与已知风险

4.1 Approval `categoryName` 路径穿越

社区报告指出，审批工具接收调用方传入的 categoryName 字符串，并直接拼接到 approvals/ 目录下。若该字段未被校验，攻击者可借助 ../ 跳出审批目录，写入任意位置。报告同时说明 filePath 字段已对绝对路径与 .. 进行了校验，但 categoryName 的校验缺失（详见 issue #220）。部署方在自托管或开放仪表盘权限时，应：

• 限制可调用 MCP 工具的客户端范围；
• 在反向代理或网关层启用身份认证；
• 关注补丁提交，必要时自行校验 categoryName 仅包含允许字符。

4.2 任务模板格式兼容性

官方 tasks-template.md 中，任务标题与元数据被分成多行书写，而仪表盘的解析器要求标题与元数据位于同一段落，否则会破坏任务渲染（详见 issue #218）。在自定义 user-templates/ 时，应避免改动任务条目的缩进与换行结构，以保证仪表盘与扩展的解析一致性。

4.3 工具响应编码

社区另提议将默认的 @toon-format/toon 编码替换为 GCF（Graph Compact Format），理由是其压缩率更高且对 LLM 可读性更友好，且官方已验证无损（详见 issue #230）。在自动化批处理或跨进程传输场景下，部署方可关注此项变更以减少 token 消耗。

五、部署最佳实践小结

1. 隔离目录：将 .spec-workflow/ 与源代码仓库解耦（例如软链接到固定路径），便于在容器或多机部署间迁移；
2. 锁定配置：基于 config.example.toml 派生正式 config.toml，并通过 CI 校验其格式；
3. 保护审批入口：在仪表盘暴露公网前务必启用鉴权，并及时升级以修复 categoryName 路径穿越；
4. 保持模板一致：自定义任务模板时遵循官方段落结构，避免触发解析器差异；
5. 监控扩展版本：VSCode 扩展当前版本 1.1.7（package.json），升级前应在测试工作区中验证命令面板与通知音配置。

See Also

• 项目主页与功能总览
• VSCode 扩展说明
• 工具响应编码讨论 (issue #230)
• 路径穿越漏洞 (issue #220)
• 远程仪表盘访问 (issue #202)
• 自定义日志目录请求 (issue #213)
• 任务模板格式兼容性 (issue #218)

Pitfall Log / 踩坑日志

项目：Pimzino/spec-workflow-mcp

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory。

1. 安装坑 · 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude_code, claude

3. 配置坑 · 来源证据：[Bug]: Bug Report for spec-workflow-mcp

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：Consider replacing TOON with GCF for tool response encoding

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Consider replacing TOON with GCF for tool response encoding
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/230 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：[Feature]: Support bundled image assets in spec documents

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Support bundled image assets in spec documents
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Pimzino/spec-workflow-mcp/issues/229 | 来源类型 github_issue 暴露的待验证使用条件。

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown