简介

spec-workflow-mcp 是一个基于 Model Context Protocol (MCP) 的开发工作流管理系统，旨在为 AI 辅助软件开发提供规范化的项目管理和协作框架。该项目通过 MCP 协议与各种 AI 工具（如 Cursor、Claude Desktop、VSCode 等）集成，帮助开发团队在 AI 驱动的开发环境中维护一致的规范、追踪任务进度、管理审批流程，并记录实现日志。

资料来源：README.md

核心功能

MCP 协议集成

作为 MCP 服务器运行，spec-workflow-mcp 提供了一套完整的工具集，使 AI 助手能够与本地项目进行深度交互。开发者可以通过简单的配置将项目目录与各种 AI 客户端连接，从而获得规范感知的工作流支持。

资料来源：README.md

规范文档管理

项目支持创建和维护以下核心规范文档：

资料来源：README.fr.md

实现日志追踪

系统会自动记录 AI 生成的代码变更，包括修改的文件、创建的文件、代码统计（新增/删除行数）以及生成的各类产物（API 端点、组件、函数、类、集成点等）。这一功能确保了开发过程的可追溯性，便于团队审查和回溯。

资料来源：src/dashboard/implementation-log-manager.ts

技术架构

系统组件架构

graph TD
    A[AI 客户端<br/>Cursor/Claude Desktop/VSCode] -->|MCP 协议| B[spec-workflow-mcp<br/>MCP Server]
    B --> C[规范存储层<br/>.spec-workflow 目录]
    B --> D[Web Dashboard<br/>端口 5000]
    B --> E[VSCode 扩展<br/>内嵌 Webview]
    
    C --> F[Specs 文档]
    C --> G[Steering 文档]
    C --> H[Approvals 审批]
    C --> I[Archive 归档]
    C --> J[实现日志]
    
    D --> K[React 前端]
    E --> L[React Webview]

前端技术栈

项目采用现代化的前端技术构建用户界面：

• React: 核心 UI 框架
• TypeScript: 类型安全保证
• Tailwind CSS: 样式解决方案
• i18n 国际化: 支持多语言切换

VSCode 扩展的 Webview 使用独立的模块化架构，包含主入口文件、i18n 模块和全局样式资源。

资料来源：vscode-extension/src/webview/index.html

REST API 架构

Dashboard 后端提供丰富的 REST API 端点，主要包括：

资料来源：src/dashboard_frontend/src/modules/api/api.tsx

部署方式

标准部署

项目支持通过 npx 直接运行，配置方式因客户端而异：

Cursor 配置示例：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Claude Desktop 配置：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

资料来源：README.md

Docker 容器部署

项目提供完整的 Docker 支持，适合隔离部署场景：

# 使用 Docker Compose（推荐）
cd containers
docker-compose up --build

# 或使用 Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

Dashboard 访问地址：http://localhost:5000

资料来源：README.md

安全特性

spec-workflow-mcp 实现了企业级的安全控制措施：

资料来源：README.md

项目结构

典型项目目录布局

your-project/
  .spec-workflow/
    approvals/       # 审批文件存储
    archive/         # 归档的规范文档
    specs/           # 活动规格文档
    steering/        # 方向指引文档
    templates/       # 文档模板
    user-templates/  # 用户自定义模板
    config.example.toml  # 配置示例

开发环境

# 安装依赖
npm install

# 编译项目
npm run build

# 开发模式运行
npm run dev

资料来源：README.fr.md

许可协议

本项目采用 GPL-3.0 开源许可证发布。

资料来源：README.fr.md

概述

spec-workflow-mcp 是一个基于规范驱动（Specification-Driven）的开发工作流程管理工具，通过 MCP（Model Context Protocol）协议与 AI 工具集成，帮助开发团队在 AI 辅助环境下高效管理项目开发流程。

快速开始指南旨在为用户提供：

• 环境配置的最简路径
• 与 AI 工具集成的标准方式
• 界面选择与启动方法
• 首个项目规范文档的创建流程

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

环境要求

系统要求

AI 工具兼容性

spec-workflow-mcp 通过 MCP 协议与以下 AI 工具集成：

• Claude Desktop
• Cursor
• VS Code (通过扩展)
• 其他支持 MCP 协议的工具

资料来源：containers/example.mcp.json:1-30

安装方式

方式一：MCP 配置集成（推荐）

将 spec-workflow-mcp 添加到 AI 工具的 MCP 配置中：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

注意：将 /path/to/your/project 替换为实际项目路径。

方式二：全局安装

npm install -g @pimzino/spec-workflow-mcp

方式三：项目本地安装

npm install @pimzino/spec-workflow-mcp

资料来源：README.md:15-35

界面选择

根据使用场景，spec-workflow-mcp 提供两种界面选项：

Web 仪表盘

适用于 CLI 用户和跨项目管理者。

启动命令：

npx -y @pimzino/spec-workflow-mcp@latest --dashboard

仪表盘访问地址：http://localhost:5000

VSCode 扩展

适用于 VSCode 用户，提供无缝的编辑体验。

安装方式：在 VSCode 扩展市场搜索 "Spec Workflow" 并安装。

资料来源：docs/INTERFACES.md:1-50

项目初始化

自动初始化

首次使用 MCP 工具时，系统会自动创建 .spec-workflow 目录结构：

your-project/
  .spec-workflow/
    approvals/      # 审批文件存储
    archive/        # 归档规范存储
    specs/          # 规范文档存储
    steering/      # 指导文档存储
    templates/      # 规范模板
    user-templates/ # 用户自定义模板
    config.example.toml  # 配置文件示例

配置文件

复制并编辑配置文件：

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

主要配置项：

资料来源：docs/USER-GUIDE.md:10-80

工作流程概览

标准开发流程

graph TD
    A[创建规范文档] --> B[定义任务清单]
    B --> C[AI 执行任务]
    C --> D{任务验证}
    D -->|通过| E[更新规范进度]
    D -->|失败| F[修订或重新执行]
    E --> G{所有任务完成?}
    G -->|否| B
    G -->|是| H[归档规范]
    F --> C

规范文档结构

每个规范文档包含以下核心部分：

1. 元数据：名称、版本、状态
2. 概述：功能描述和目标
3. 任务清单：具体实现任务及状态
4. 验收标准：完成条件定义

资料来源：docs/PROMPTING-GUIDE.md:1-60

首次使用指南

步骤一：创建首个规范

在 AI 对话中描述要实现的功能，系统将自动生成规范文档框架：

请帮我创建一个新的规范文档，用于实现用户认证功能。

步骤二：审查规范

使用仪表盘或 VSCode 扩展查看生成的规范文档，确认任务分解正确。

步骤三：执行任务

按照任务清单逐项执行，AI 将根据规范要求辅助代码实现。

步骤四：跟踪进度

通过仪表盘的任务面板实时查看进度更新。

步骤五：归档完成

规范所有任务完成后，将规范移至归档目录保存。

资料来源：docs/USER-GUIDE.md:80-150

常见问题

问题一：仪表盘无法启动

解决方案：

# 检查端口占用
lsof -i :5000

# 使用其他端口
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 5001

问题二：MCP 连接失败

解决方案：

1. 确认 Node.js 版本 >= 18.x
2. 检查 MCP 配置文件语法
3. 重启 AI 工具

问题三：规范文档未自动创建

解决方案：手动创建 .spec-workflow 目录结构，确保 specs/ 子目录存在。

资料来源：docs/USER-GUIDE.md:150-200

下一步

完成快速开始后，建议继续阅读以下文档：

• 用户指南 - 深入了解所有功能
• 提示工程指南 - 优化 AI 交互
• 接口指南 - 仪表盘和扩展详细说明
• 开发指南 - 参与项目开发

概述

spec-workflow-mcp 是一个基于 MCP（Model Context Protocol）协议的 AI 辅助开发工作流工具。它通过标准化规范（spec）驱动的方式，帮助开发团队协调 AI 工具与人类开发者之间的协作。安装配置是整个系统的入口点，正确配置 MCP 服务器是将 spec-workflow 集成到现有开发环境的关键步骤。

该工具支持多种主流 AI 编程工具的集成，包括 Claude Desktop、Claude Code CLI、Cline、Cursor、Continue 以及 VSCode 扩展程序。配置方式根据不同的客户端略有差异，但核心概念相同：启动 MCP 服务器并指向项目目录。

项目目录结构

spec-workflow-mcp 在项目根目录创建一个 .spec-workflow 隐藏目录，用于存储所有配置、规范文档和历史记录。

your-project/
  .spec-workflow/
    approvals/           # 审批文件存储
    archive/             # 归档的规范文档
    specs/               # 规范文档主目录
    steering/            # 引导文件目录
    templates/           # 内置模板
    user-templates/      # 用户自定义模板
    config.example.toml  # 配置文件模板

资料来源：README.md:45-54

.spec-workflow 目录结构设计遵循单一职责原则，每个子目录管理特定类型的数据。规范文档存储在 specs/ 中，审批流程相关文件存储在 approvals/，而 archive/ 用于存放已完成的规范文档以便追溯。

MCP 服务器配置

核心配置参数

MCP 服务器通过 mcpServers 配置节进行定义，主要参数如下：

标准的 npx 启动命令格式为：

{
  "command": "npx",
  "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}

资料来源：README.md:18-24

参数说明：

• -y 标志用于跳过 npm 安装确认提示，实现更流畅的自动化安装流程
• @pimzino/spec-workflow-mcp@latest 指定包名称和版本号
• 最后一个参数是项目目录的绝对路径或相对路径

各客户端配置方式

#### Claude Desktop

Claude Desktop 的配置文件位于 claude_desktop_config.json，配置示例：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

重要提示：在启动 MCP 服务器之前，需要单独运行 --dashboard 命令启动仪表板。

资料来源：README.md:75-89

#### Claude Code CLI

对于 Claude Code CLI，需要使用 mcp add 命令添加服务器：

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project

关键要点：

• -y 标志用于跳过 npm 提示，确保自动化安装
• -- 分隔符确保路径参数被传递给 spec-workflow 脚本而非 npx

Windows 用户如果上述命令不生效，可以使用替代方案：

claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"

资料来源：README.md:31-47

#### Cline / Claude Dev

在 Cline 或 Claude Dev 中添加 MCP 服务器配置：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

资料来源：README.md:95-103

#### Continue IDE Extension

Continue 配置使用相同的 JSON 格式：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

资料来源：README.md:107-115

#### Cursor IDE

Cursor 的配置需添加到 settings.json 中：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

资料来源：README.md:119-127

#### Codex

Codex 使用 TOML 格式配置文件，位于 ~/.codex/config.toml：

[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]

资料来源：README.md:140-144

仪表板配置

Web 仪表板

Web 仪表板是 CLI 用户的推荐接口，启动命令：

npx -y @pimzino/spec-workflow-mcp@latest --dashboard

仪表板默认运行在 http://localhost:5000。

重要说明：只需要一个仪表板实例，所有项目都连接到同一个仪表板。

资料来源：README.ko.md:22-29

Docker 部署

对于隔离部署环境，spec-workflow-mcp 支持 Docker 容器化运行：

#### 使用 Docker Compose（推荐方式）

cd containers
docker-compose up --build

#### 使用 Docker CLI

# 构建镜像
docker build -f containers/Dockerfile -t spec-workflow-mcp .

# 运行容器
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

Docker 部署会将容器内的 /workspace/.spec-workflow 目录映射到宿主机的 ./workspace/.spec-workflow，确保数据持久化。

资料来源：README.md:146-157

安全配置

安全控制特性

spec-workflow-mcp 包含企业级安全功能，适用于企业环境：

资料来源：README.md:164-174

本地绑定

默认情况下，Web 仪表板仅监听 127.0.0.1（localhost），这确保了：

• 只有本机浏览器可以访问仪表板
• 外部网络无法连接到服务
• 适用于开发和测试环境

速率限制

系统实现了请求速率限制机制：

• 每分钟每客户端 120 个请求
• 超过限制的请求会被拒绝
• 自动清理过期记录以释放资源

本地开发配置

安装依赖

npm install

资料来源：README.md:60

构建项目

npm run build

构建过程会将 TypeScript 源码编译为 JavaScript，输出到 dist/ 目录。

开发模式运行

npm run dev

开发模式提供热重载功能，代码修改后自动重新编译和重启服务。

资料来源：README.md:61-67

配置验证

验证步骤

1. 检查 MCP 服务器状态：在对应的 AI 工具中确认 MCP 服务器已正确加载
2. 验证仪表板连接：访问 http://localhost:5000 确认 Web 仪表板可访问
3. 检查项目目录：确认 .spec-workflow 目录已在项目根目录创建
4. 测试规范创建：尝试创建一个新的规范文档验证写入权限

常见配置问题

扩展配置

VSCode 扩展配置

VSCode 用户可以使用专门的扩展程序，获得更好的集成体验：

# 从 VSCode Marketplace 安装扩展
# 然后在扩展设置中配置项目路径

VSCode 扩展提供了内联的用户界面，无需单独启动 Web 仪表板。

资料来源：README.ko.md:31-35

多项目配置

spec-workflow-mcp 支持同时管理多个项目：

1. 每个项目需要独立的 .spec-workflow 目录
2. 所有项目可以共享同一个仪表板实例
3. 在 MCP 配置中使用不同的路径参数指向各项目

{
  "mcpServers": {
    "spec-workflow-project-a": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project-a"]
    },
    "spec-workflow-project-b": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project-b"]
    }
  }
}

配置架构图

graph TD
    A[用户开发环境] --> B[AI 编程工具]
    B --> C[MCP 客户端]
    C --> D[MCP 服务器]
    D --> E[spec-workflow-mcp 核心]
    E --> F[.spec-workflow 目录]
    E --> G[Web 仪表板]
    E --> H[文件系统]
    
    F --> I[specs/ 规范文档]
    F --> J[approvals/ 审批]
    F --> K[archive/ 归档]
    F --> L[steering/ 引导]
    F --> M[templates/ 模板]
    
    G --> N[localhost:5000]
    
    style A fill:#e1f5fe
    style G fill:#fff3e0
    style F fill:#f3e5f5

下一步

配置完成后，建议阅读以下文档：

• 工作流指南 - 开发工作流和最佳实践
• 接口指南 - 仪表板和 VSCode 扩展详情
• 工具参考 - 完整工具文档
• 故障排除 - 常见问题及解决方案

概述

Spec-Workflow-MCP 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统，旨在为 AI 驱动的软件开发提供结构化的规格管理和实现跟踪能力。该系统采用模块化架构设计，支持多个项目连接至单一仪表板实例，实现跨项目的规格、任务和实施日志的统一管理。

系统的核心设计理念是将 AI 开发过程的结构化，通过规格文档（Spec）、任务拆解、实施日志等机制，确保 AI 生成的代码与预期规格保持一致。

整体架构

graph TB
    subgraph "客户端层"
        VSCode[VSCode 扩展]
        CLI[CLI 工具]
        其他AI[其他 MCP 客户端]
    end
    
    subgraph "核心服务层"
        MCP[MCP 服务器]
        WS[WebSocket 服务]
        API[REST API 服务]
    end
    
    subgraph "仪表板层"
        Dashboard[Web 仪表板]
        Frontend[React 前端]
    end
    
    subgraph "数据层"
        FS[文件系统存储]
        LogDB[实施日志]
        Config[项目配置]
    end
    
    VSCode --> MCP
    CLI --> MCP
    其他AI --> MCP
    
    MCP --> WS
    MCP --> FS
    MCP --> LogDB
    
    WS <--> Dashboard
    Dashboard --> Frontend
    
    Dashboard --> Config
    Frontend --> Config

核心组件

MCP 服务器

MCP 服务器是系统的核心入口点，负责处理来自各种 AI 工具的请求。服务器启动时加载项目配置，建立文件系统监控，并注册 MCP 工具集。

服务器支持两种运行模式：独立 MCP 模式和仪表板模式。运行 MCP 模式时，服务器通过标准输入输出与 AI 客户端通信；运行仪表板模式时，启动 Web 服务器提供可视化界面。

多服务器管理

系统采用多服务器架构，允许连接多个项目至同一个仪表板实例：

graph LR
    subgraph "Dashboard Instance"
        DM[仪表板管理器]
        CM[连接管理器]
        PM[项目管理器]
    end
    
    P1[项目 1]
    P2[项目 2]
    P3[项目 N]
    
    DM --> CM
    CM --> PM
    
    P1 <--> PM
    P2 <--> PM
    P3 <--> PM

每个连接的项目维护独立的配置和状态，仪表板通过项目标识符进行区分和路由。

文件系统监控

文件监控模块负责实时跟踪 .spec-workflow 目录下的变更：

资料来源：src/dashboard/watcher.ts

文件变更通过 WebSocket 实时推送至前端界面，实现多客户端的状态同步。

前端架构

Web 仪表板

Web 仪表板基于 React 构建，提供完整的项目管理和监控界面：

graph TD
    App[主应用]
    Overview[概览页]
    Tasks[任务页]
    Logs[日志页]
    Settings[设置页]
    
    App --> Overview
    App --> Tasks
    App --> Logs
    App --> Settings
    
    Overview --> WS[WebSocket 连接]
    Tasks --> WS
    Logs --> WS
    
    WS --> Provider[WebSocket Provider]

#### 页面模块

WebSocket 通信

WebSocket 模块负责客户端与服务端之间的实时双向通信：

资料来源：src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx

sequenceDiagram
    participant Client as 前端客户端
    participant WS as WebSocket Provider
    participant Server as Dashboard Server
    
    Client->>WS: 建立连接
    WS->>Server: 初始化 WebSocket 连接
    
    Server->>WS: 连接状态更新
    WS->>Client: 状态同步
    
    loop 文件变更监控
        Server->>WS: 发送变更事件
        WS->>Client: 广播更新
    end
    
    Client->>WS: 发送操作请求
    WS->>Server: 转发请求

WebSocket Provider 维护连接状态，处理重连逻辑，并向下游组件提供状态更新上下文。

VSCode 扩展

VSCode 扩展提供嵌入式开发体验：

资料来源：vscode-extension/src/webview/App.tsx

┌─────────────────────────────────────┐
│         VSCode Extension            │
├─────────────────────────────────────┤
│  Webview Container                  │
│  ┌───────────────────────────────┐  │
│  │  React Application            │  │
│  │  ├─ Overview Panel            │  │
│  │  ├─ Task List                 │  │
│  │  ├─ Implementation Logs        │  │
│  │  └─ Settings                   │  │
│  └───────────────────────────────┘  │
├─────────────────────────────────────┤
│  VSCode API Integration             │
│  ├─ File System Watcher            │  │
│  ├─ Status Bar Updates             │  │
│  └─ Command Palette                │  │
└─────────────────────────────────────┘

扩展通过 WebView 与主进程通信，利用 VSCode 原生 API 实现文件系统监控和 UI 集成。

数据模型

项目结构

项目根目录/
  .spec-workflow/
    approvals/      # 审批文件
    archive/        # 已归档规格
    specs/          # 规格文档
    steering/       # 方向性文档
    templates/      # 模板文件
    user-templates/ # 用户自定义模板
    config.example.toml  # 配置示例

实施日志条目

系统记录每次规格实施的完整信息：

工件类型

安全机制

系统实现了企业级安全特性：

graph LR
    subgraph "安全层"
        RATE[速率限制]
        CORS[CORS 保护]
        HEAD[安全头]
        LOG[审计日志]
    end
    
    Request[请求] --> RATE
    RATE --> CORS
    CORS --> HEAD
    HEAD --> LOG

部署模式

Docker 部署

系统支持 Docker 容器化部署：

# 容器结构
┌─────────────────────────────┐
│       spec-workflow-mcp     │
├─────────────────────────────┤
│  Node.js Runtime            │
│  ├─ Dashboard Server        │
│  ├─ WebSocket Server        │
│  └─ MCP Protocol Handler    │
└─────────────────────────────┘

容器部署命令：

# Docker Compose 方式
cd containers
docker-compose up --build

# Docker CLI 方式
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

MCP 客户端集成

系统作为 MCP 服务器运行，支持多种 AI 工具客户端：

资料来源：README.md

实时同步机制

graph TB
    subgraph "变更源"
        File[文件变更]
        User[用户操作]
        AI[AI 执行]
    end
    
    File --> Watcher[文件系统监控]
    User --> API[API 调用]
    AI --> MCP[MCP 执行]
    
    Watcher --> Event[变更事件]
    API --> Event
    MCP --> Event
    
    Event --> Broadcast[广播至所有客户端]
    
    Broadcast --> WS1[Dashboard 1]
    Broadcast --> WS2[Dashboard 2]
    Broadcast --> WS3[VSCode Extension]

所有连接至同一仪表板实例的客户端共享状态视图，确保多端操作的一致性。

概述

spec-workflow-mcp 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统。该项目采用前后端分离架构，包含核心业务逻辑层、仪表板前端以及 VSCode 扩展三大部分。文件结构设计遵循模块化原则，将核心功能、界面展示和编辑器扩展清晰地分离在不同的目录中。 资料来源：README.fr.md:1-10

顶层目录结构

spec-workflow-mcp/
├── .spec-workflow/          # 项目规范配置目录
├── src/                     # 核心业务逻辑
├── vscode-extension/        # VSCode 扩展
├── vscode-extension/
│   └── webview-dist/        # 构建产物
├── src/dashboard_frontend/  # 仪表板前端
└── docs/                    # 文档

`.spec-workflow/` 规范目录结构

.spec-workflow/ 目录是项目的工作空间根目录，包含了规格驱动的所有配置文件和文档模板。 资料来源：README.fr.md:25-35

核心业务逻辑层 (`src/`)

src/ 目录包含了系统的主要业务逻辑，采用 TypeScript 实现。

核心模块 (`src/core/`)

核心模块包含系统的基础功能组件：

仪表板模块 (`src/dashboard/`)

仪表板模块负责实现日志管理和数据展示功能：

Markdown 模板 (`src/markdown/templates/`)

模板系统用于生成标准化的项目文档：

仪表板前端 (`src/dashboard_frontend/`)

仪表板前端是一个独立的 Web 应用，提供图形化界面来管理规格工作流。

页面模块 (`src/dashboard_frontend/src/modules/pages/`)

架构流程图

graph TD
    A[用户界面] --> B[任务页面 TasksPage]
    A --> C[日志页面 LogsPage]
    A --> D[指导页面 SteeringPage]
    A --> E[执行历史 JobExecutionHistory]
    B --> F[核心服务层]
    C --> F
    D --> F
    E --> F
    F --> G[spec-workflow 核心]
    G --> H[文件系统]

VSCode 扩展 (`vscode-extension/`)

VSCode 扩展为开发者提供了在编辑器内直接访问规格工作流的能力。

Web 视图源文件 (`vscode-extension/src/webview/`)

Web 视图组件关系

graph LR
    A[index.html] --> B[main.tsx]
    A --> C[App.tsx]
    B --> D[React 应用挂载]
    C --> E[LogEntryCard]
    C --> F[任务列表]
    C --> G[项目统计]
    E --> H[ArtifactSection]

构建产物 (`vscode-extension/webview-dist/`)

构建后的静态资源用于 VSCode 扩展的实际运行：

实现日志数据结构

系统通过 ImplementationLogEntry 接口管理实现日志，包含以下关键字段： 资料来源：src/dashboard/implementation-log-manager.ts:1-20

Artifacts 子结构

artifacts 对象包含多种代码构件类型的记录： 资料来源：src/dashboard/implementation-log-manager.ts:30-60

前端组件架构

任务页面组件 (`TasksPage.tsx`)

任务页面负责展示和管理规格任务，包含以下核心功能： 资料来源：src/dashboard_frontend/src/modules/pages/TasksPage.tsx:1-50

• 进度追踪：显示任务完成百分比和总体进度条
• 任务列表：支持列表和网格视图切换
• 元数据展示：展示 Purpose、Requirements、Leverage、Prompt 等任务属性
• AI 提示词：可展开的 AI 生成提示词查看器

日志页面组件 (`LogsPage.tsx`)

日志页面提供实现日志的详细查看功能： 资料来源：src/dashboard_frontend/src/modules/pages/LogsPage.tsx:1-40

• 统计数据：文件变更数、净变更行数
• 文件变更列表：展示修改和创建的文件路径
• 构件展示：按类型分类展示生成的代码构件

日志卡片组件 (`LogEntryCard.tsx`)

日志条目卡片组件用于在 VSCode 扩展中渲染单个日志条目： 资料来源：vscode-extension/src/webview/components/LogEntryCard.tsx:1-80

interface LogEntryCardProps {
  entry: ImplementationLogEntry;
}

多语言支持

项目包含国际化（i18n）支持，通过 i18n.js 模块提供多语言文本资源。已确认的语言版本包括：

• 英语（默认）
• 法语（README.fr.md）

构建与部署

前端构建

npm install
npm run build

VSCode 扩展构建

VSCode 扩展的 Web 视图代码独立构建到 webview-dist/ 目录，然后与扩展主体打包。 资料来源：vscode-extension/webview-dist/index.html:1-20

开发模式

npm run dev

架构总览图

graph TD
    subgraph 前端层
        A[仪表板前端<br/>React + TypeScript]
        B[VSCode 扩展 WebView]
    end
    
    subgraph 核心层
        C[实现日志管理<br/>implementation-log-manager]
        D[日志迁移器<br/>implementation-log-migrator]
        E[Markdown 模板系统]
    end
    
    subgraph 数据层
        F[.spec-workflow/ 目录]
        G[配置文件]
    end
    
    A --> C
    B --> C
    C --> D
    C --> F
    D --> F
    E --> F

总结

spec-workflow-mcp 项目采用清晰的分层架构设计：

1. 核心层 (src/core/) 提供业务逻辑和数据处理能力
2. 仪表板层 (src/dashboard/ + src/dashboard_frontend/) 提供独立的 Web 管理界面
3. 扩展层 (vscode-extension/) 提供编辑器集成功能
4. 模板层 (src/markdown/templates/) 确保文档标准化

这种模块化设计使得系统各部分可以独立开发、测试和部署，同时保持良好的可维护性和可扩展性。

概述

规格工作流程（Spec Workflow）是 spec-workflow-mcp 项目的核心功能模块，为 AI 代码助手提供结构化的项目开发流程管理能力。该工作流程通过规范化的文档创建、审批和执行机制，帮助开发团队在 AI 辅助编程环境中保持开发目标的一致性和可追溯性。

规格工作流程的主要目标是：

• 在项目启动阶段建立清晰的产品愿景和技术架构
• 将大型需求拆解为可执行的小粒度任务
• 通过审批流程确保 AI 生成的内容符合预期
• 记录实现过程中的关键产物，便于后续维护

资料来源：README.md

核心概念

规格文档类型

规格工作流程使用多种类型的文档来组织项目信息：

资料来源：src/tools/steering-guide.ts

模板系统

系统支持自定义模板，允许用户覆盖默认模板行为：

• 用户自定义模板优先：.spec-workflow/user-templates/
• 默认模板：.spec-workflow/templates/

支持的模板文件包括：product-template.md、tech-template.md、structure-template.md、design-template.md、tasks-template.md

引导文档工作流程

引导文档（Steering Documents）是项目的顶层规划文档，包括产品愿景、技术架构和代码结构三个核心文档。

工作流程阶段

引导文档工作流程分为三个阶段：

graph TD
    Start([开始]) --> P1_Template[检查用户模板<br/>user-templates/]
    P1_Template --> P1_Read{是否有自定义模板?}
    P1_Read -->|是| P1_Custom[读取自定义模板]
    P1_Read -->|否| P1_Default[读取默认模板<br/>templates/]
    P1_Custom --> P1_Analyze[分析产品需求]
    P1_Default --> P1_Analyze
    P1_Analyze --> P1_Create[创建文件<br/>steering/product.md]
    P1_Create --> P1_Approve[approvals<br/>action: request<br/>filePath only]
    P1_Approve --> P1_Status[approvals<br/>action: status<br/>轮询状态]
    P1_Status --> P1_Check{状态?}
    P1_Check -->|needs-revision| P1_Update[根据用户评论更新文档]
    P1_Update --> P1_Create
    P1_Check -->|approved| P1_Clean[approvals<br/>action: delete]
    P1_Clean -->|失败| P1_Status
    P1_Clean -->|成功| P2_Template

    P2_Template --> P2_Read[检查技术模板]
    P2_Read --> P2_Analyze[分析技术栈]
    P2_Analyze --> P2_Create[创建文件<br/>steering/tech.md]
    P2_Create --> P2_Approve[approvals<br/>action: request]
    P2_Approve --> P2_Status[轮询状态]
    P2_Status --> P2_Check{状态?}
    P2_Check -->|needs-revision| P2_Update
    P2_Update --> P2_Create
    P2_Check -->|approved| P2_Clean[删除审批]
    P2_Clean -->|成功| P3_Template

    P3_Template --> P3_Read[检查结构模板]
    P3_Read --> P3_Analyze[分析代码结构]
    P3_Analyze --> P3_Create[创建文件<br/>steering/structure.md]
    P3_Create --> P3_Approve[approvals<br/>action: request]
    P3_Approve --> P3_Status[轮询状态]
    P3_Status --> P3_Check{状态?}
    P3_Check -->|needs-revision| P3_Update
    P3_Update --> P3_Create
    P3_Check -->|approved| P3_Clean
    P3_Clean -->|成功| Complete([引导文档完成])

    style Start fill:#e6f3ff
    style Complete fill:#e6f3ff
    style P1_Check fill:#ffe6e6
    style P2_Check fill:#ffe6e6
    style P3_Check fill:#ffe6e6

第一阶段：产品文档

目的：定义愿景、目标和用户成果。

文件操作：

• 检查自定义模板：.spec-workflow/user-templates/product-template.md
• 读取模板：.spec-workflow/templates/product-template.md（无自定义模板时）
• 创建文档：.spec-workflow/steering/product.md

流程：

1. 检查自定义模板
2. 分析现有产品需求
3. 创建 product.md
4. 使用 approvals 工具请求审批
5. 轮询审批状态直到 approved/needs-revision
6. 若 needs-revision：根据评论更新文档，创建新审批
7. 审批通过后：使用 approvals action:delete 删除审批记录

资料来源：src/tools/steering-guide.ts

第二阶段：技术文档

目的：记录技术决策和架构设计。

文件操作：

• 检查自定义模板：.spec-workflow/user-templates/tech-template.md
• 读取模板：.spec-workflow/templates/tech-template.md
• 创建文档：.spec-workflow/steering/tech.md

流程：同产品文档阶段

第三阶段：结构文档

目的：映射代码库组织和模式。

文件操作：

• 检查自定义模板：.spec-workflow/user-templates/structure-template.md
• 读取模板：.spec-workflow/templates/structure-template.md
• 创建文档：.spec-workflow/steering/structure.md

规格创建工作流程

规格创建工作流程用于生成具体的项目规格文档，包括设计文档和任务列表。

工作流程阶段

graph TD
    Start([开始]) --> P1_Template[检查设计模板]
    P1_Template --> P1_Read[读取模板内容]
    P1_Read --> P1_Analyze[分析需求]
    P1_Analyze --> P1_Create[创建文件<br/>specs/{name}/design.md]
    P1_Create --> P1_Approve[请求审批]
    P1_Approve --> P1_Status[轮询状态]
    P1_Status --> P1_Check{状态?}
    P1_Check -->|needs-revision| P1_Update[更新文档]
    P1_Update --> P1_Create
    P1_Check -->|approved| P1_Clean[删除审批]
    P1_Clean -->|成功| P2_Ready

    P2_Ready([就绪]) --> P2_Template[检查任务模板]
    P2_Template --> P2_Break[将设计拆解为任务]
    P2_Break --> P2_Create[创建文件<br/>specs/{name}/tasks.md]
    P2_Create --> P2_Approve[请求审批]
    P2_Approve --> P2_Status[轮询状态]
    P2_Status --> P2_Check{状态?}
    P2_Check -->|needs-revision| P2_Update[更新任务]
    P2_Update --> P2_Create
    P2_Check -->|approved| P2_Clean
    P2_Clean -->|成功| P3_Ready

    P3_Ready([就绪]) --> P3_Impl[执行任务实现]

    style Start fill:#e6f3ff
    style P3_Ready fill:#e6f3ff
    style P1_Check fill:#ffe6e6
    style P2_Check fill:#ffe6e6

第一阶段：设计文档

目的：详细描述规格的设计方案。

文件操作：

• 检查自定义模板：.spec-workflow/user-templates/design-template.md
• 读取模板：.spec-workflow/templates/design-template.md
• 创建文档：.spec-workflow/specs/{name}/design.md

第二阶段：任务文档

目的：将设计方案转换为可执行任务列表。

文件操作：

• 检查自定义模板：.spec-workflow/user-templates/tasks-template.md
• 读取模板：.spec-workflow/templates/tasks-template.md
• 创建文档：.spec-workflow/specs/{name}/tasks.md

任务拆解要求：

• 每个任务应具有清晰的完成标准
• 任务之间应保持独立性
• 明确任务的依赖关系

资料来源：src/tools/spec-workflow-guide.ts

审批系统

审批系统是规格工作流程的质量保障机制，确保 AI 生成的内容经过人工确认后再执行。

审批操作

审批状态

审批流程状态图

stateDiagram-v2
    [*] --> Pending: request
    Pending --> Approved: 用户批准
    Pending --> NeedsRevision: 用户要求修改
    NeedsRevision --> Pending: 更新后重新请求
    Approved --> [*]: delete
    NeedsRevision --> [*]: 取消

项目结构

完整的项目结构如下：

your-project/
  .spec-workflow/
    approvals/          # 审批记录存储
    archive/            # 归档的规格文档
    specs/              # 规格文档目录
      {name}/
        design.md      # 设计文档
        tasks.md       # 任务文档
    steering/           # 引导文档目录
      product.md       # 产品文档
      tech.md          # 技术文档
      structure.md     # 结构文档
    templates/          # 默认模板
    user-templates/     # 用户自定义模板
    config.example.toml # 配置示例

工具引用

主要工具

工作流工具参数

// steering-guide 工具
interface SteeringGuideParams {
  action: 'getInstructions' | 'execute';
  phase?: 'product' | 'tech' | 'structure';
}

// approvals 工具
interface ApprovalsParams {
  action: 'request' | 'status' | 'delete';
  filePath?: string;
}

// spec-workflow-guide 工具
interface SpecWorkflowParams {
  action: 'getInstructions' | 'execute';
  specName?: string;
  phase?: 'design' | 'tasks';
}

任务解析器

任务解析器（Task Parser）负责将任务文档解析为可执行的任务列表。

解析流程

graph LR
    A[tasks.md] --> B[task-parser.ts]
    B --> C{解析任务}
    C --> D[验证任务格式]
    D --> E[提取任务属性]
    E --> F[返回任务列表]

任务属性

资料来源：src/core/task-parser.ts

实现日志

实现日志（Implementation Log）用于记录任务执行过程中的关键信息。

日志条目结构

interface ImplementationLogEntry {
  id: string;
  timestamp: string;
  taskId: string;
  summary: string;
  filesModified: string[];
  filesCreated: string[];
  artifacts: {
    apiEndpoints?: ApiEndpoint[];
    components?: Component[];
    functions?: Function[];
    classes?: Class[];
    integrations?: Integration[];
  };
  statistics: {
    linesAdded: number;
    linesRemoved: number;
  };
}

生成的报告格式

实现日志支持导出为 Markdown 格式的报告，包含以下章节：

• 实现摘要
• 修改的文件列表
• 创建的文件列表
• 产物详情（API 端点、组件、函数、类、集成）

资料来源：src/dashboard/implementation-log-manager.ts

接口选项

规格工作流程提供两种用户界面：

网页仪表盘

• 默认端口：5000
• 启动命令：npx -y @pimzino/spec-workflow-mcp@latest --dashboard
• 访问地址：http://localhost:5000
• 特点：集中管理，一个实例可供所有项目使用

VSCode 扩展

• 集成到 VSCode 编辑器
• 提供内联任务管理和审批功能
• 适合 VSCode 用户

配置

MCP 服务器配置

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

配置文件

项目根目录下的 config.example.toml 提供了配置选项示例。

许可证

本项目采用 GPL-3.0 开源许可证。

概述

审批系统（Approval System）是 spec-workflow-mcp 项目中用于管理和追踪文档审批流程的核心模块。该系统贯穿整个规范工作流，从产品文档、技术文档、结构文档到任务文档的创建和更新，都需要经过审批环节才能完成。

审批系统的设计遵循以下核心原则：

• 请求-审批-状态轮询模式：每次文档创建或更新都需要发起审批请求，并通过轮询机制追踪审批状态
• 批量操作支持：支持多选模式下的批量批准或拒绝操作
• 状态驱动的流程控制：通过状态检查点（needs-revision/approved）决定下一步操作
• 多端一致性：VSCode 扩展和 Web Dashboard 提供统一的审批界面

架构设计

系统组件

┌─────────────────────────────────────────────────────────────────┐
│                        审批系统架构                               │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   VSCode    │  │   Web       │  │   MCP       │              │
│  │   扩展      │  │   Dashboard │  │   Server    │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          ▼                                      │
│              ┌─────────────────────┐                            │
│              │   审批存储层         │                            │
│              │ approval-storage.ts │                            │
│              └──────────┬──────────┘                            │
│                         ▼                                        │
│              ┌─────────────────────┐                            │
│              │   文件系统           │                            │
│              │ .spec-workflow/     │                            │
│              │   approvals/        │                            │
│              └─────────────────────┘                            │
└─────────────────────────────────────────────────────────────────┘

核心模块职责

审批工作流

完整状态流程

graph TD
    Start([开始]) --> Request[发起审批请求]
    Request --> Status[轮询审批状态]
    Status --> Check{状态检查}
    Check -->|needs-revision| Update[根据用户评论更新文档]
    Update --> Request
    Check -->|approved| Clean[删除审批记录]
    Clean -->|success| Complete([流程完成])
    Clean -->|failed| Status
    Check -->|rejected| Rejected([审批拒绝])

各阶段的审批操作

根据工作流定义，审批操作分为三种类型：

资料来源：src/tools/spec-workflow-guide.ts

各阶段的审批节点

审批系统应用于以下工作流阶段：

graph LR
    subgraph 产品文档阶段
        P1_Request[approvals<br/>action: request]
        P1_Status[approvals<br/>action: status]
    end
    
    subgraph 技术文档阶段
        P2_Request[approvals<br/>action: request]
        P2_Status[approvals<br/>action: status]
    end
    
    subgraph 结构文档阶段
        P3_Request[approvals<br/>action: request]
        P3_Status[approvals<br/>action: status]
    end
    
    subgraph 设计文档阶段
        D_Request[approvals<br/>action: request]
        D_Status[approvals<br/>action: status]
    end
    
    subgraph 任务阶段
        T_Request[approvals<br/>action: request]
        T_Status[approvals<br/>action: status]
    end

每个阶段的审批流程遵循相同的模式：创建文档 → 请求审批 → 轮询状态 → 根据结果更新或完成。

资料来源：src/tools/steering-guide.ts

数据模型

审批记录结构

interface Approval {
  id: string;                    // 唯一标识符
  title: string;                 // 审批标题
  description?: string;          // 审批描述
  filePath?: string;             // 相关文件路径（仅包含路径，不含内容）
  createdAt: Date | string;     // 创建时间
  status: 'pending' | 'approved' | 'rejected' | 'needs-revision';
  category?: string;             // 分类（用于过滤）
}

审批状态枚举

资料来源：src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx

前端组件

审批卡片组件

审批卡片是展示单个审批记录的核心组件，位于 VSCode 扩展的 Webview 中：

// 卡片显示的信息
- 标题 (title): 显示审批主题
- 描述 (description): 可选的审批说明
- 文件路径 (filePath): 以等宽字体显示的代码路径
- 创建时间: 使用 formatDistanceToNow 格式化显示
- 状态徽章: pending 状态显示待处理标识

资料来源：vscode-extension/src/webview/App.tsx

卡片操作按钮

批量操作

审批系统支持多选模式下的批量操作：

// 批量操作状态
interface BatchState {
  selectionMode: boolean;        // 是否处于选择模式
  selectedApprovalIds: Set<string>; // 已选中的审批 ID
  batchProcessing: boolean;      // 是否正在处理
  pendingAction: 'approve' | 'reject' | null; // 待执行的批量操作
  batchResult: BatchApprovalResult | null;    // 批量操作结果
}

批量操作界面包含：

1. 选择计数显示：显示已选择的审批数量
2. 清除选择按钮：取消当前所有选择
3. 批量批准按钮：批准所有选中的审批
4. 批量拒绝按钮：拒绝所有选中的审批
5. 结果提示：显示操作成功或失败的数量统计

资料来源：vscode-extension/src/webview/App.tsx

审批页面组件

Web Dashboard 的审批页面（ApprovalsPage）提供更完整的功能：

#### 筛选功能

// 分类过滤
const [filterCategory, setFilterCategory] = useState<string>('all');

// URL 参数支持高亮显示特定审批
const [searchParams, setSearchParams] = useSearchParams();
const highlightedId = searchParams.get('id');

#### 模态框警告

资料来源：src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx

存储机制

审批文件存储

审批记录存储在项目目录的 .spec-workflow/approvals/ 目录下：

your-project/
  .spec-workflow/
    approvals/         # 审批记录存储目录
    archive/           # 已归档的规范
    specs/             # 规范文档
    steering/          # 指导文档
    templates/         # 模板
    user-templates/    # 用户自定义模板
    config.example.toml

文件操作流程

1. 请求审批：创建审批记录文件，记录请求信息和目标文件路径
2. 状态管理：通过文件系统状态或外部服务追踪审批状态
3. 响应处理：用户通过 VSCode 扩展或 Web Dashboard 进行响应
4. 清理归档：已批准的审批记录可被删除，相关文档移动到归档目录

国际化支持

审批系统支持多语言显示，关键翻译键位：

资料来源：vscode-extension/src/webview/App.tsx

API 接口

审批相关 API

状态轮询机制

// 状态轮询流程
async function pollStatus(approvalId: string) {
  let status = await getApprovalStatus(approvalId);
  while (status === 'pending') {
    await sleep(1000); // 轮询间隔
    status = await getApprovalStatus(approvalId);
  }
  return status;
}

样式与用户体验

视觉设计

审批卡片采用以下设计规范：

/* 卡片容器 */
.space-y-3: 元素间距 0.75rem

/* 标题样式 */
.font-medium: 中等字重
.text-sm: 字体大小 14px
.truncate: 文本溢出省略

/* 状态徽章 */
.variant: secondary
.text-xs: 字体大小 12px

/* 按钮样式 */
.h-6: 高度 24px
.px-2: 内边距水平 8px
.text-xs: 字体大小 12px

时间显示

创建时间使用 formatDistanceToNow 函数格式化，例如：

• "5 minutes ago" → "5分钟前"
• "2 hours ago" → "2小时前"
• "1 day ago" → "1天前"

与其他系统的集成

规范工作流集成

审批系统是规范工作流（Spec Workflow）的核心环节：

graph TD
    subgraph 工作流阶段
        Create[创建文档] --> Approve[请求审批]
        Approve --> Poll[轮询状态]
        Poll --> Check{状态判断}
        Check -->|修订| Update[更新文档]
        Update --> Create
        Check -->|批准| Continue[继续下一阶段]
        Check -->|拒绝| Failed[流程失败]
    end

统计面板集成

审批统计信息集成在 Dashboard 的统计面板中：

资料来源：src/dashboard_frontend/src/modules/pages/DashboardStatistics.tsx

最佳实践

发起审批

1. 确保文档已完成编写并保存
2. 提供清晰的审批标题和描述
3. 在 filePath 中指定需要审批的文件路径

审批响应

1. 仔细阅读文档内容
2. 批准时添加简短的响应说明
3. 需要修订时提供具体的修改建议
4. 避免无评论的修订操作

批量操作

1. 批量操作前确认所有选中项
2. 注意系统警告提示
3. 操作后检查结果反馈
4. 及时撤销错误的批量操作

故障排除

常见问题

调试建议

1. 检查浏览器控制台的 API 响应
2. 验证 .spec-workflow/approvals/ 目录权限
3. 确认 MCP Server 连接状态
4. 查看 Dashboard 日志输出

概述

任务管理是 spec-workflow-mcp 项目的核心功能模块，负责规范化和跟踪项目中的开发任务。该模块支持多状态流转、看板视图、实时进度统计以及任务元数据管理，为团队提供了清晰的任务可视化和管理能力。

任务管理系统的核心设计目标包括：

• 状态驱动的工作流：通过明确的任务状态定义团队工作进度
• Markdown 格式兼容：任务以 Markdown 复选框格式存储，便于版本控制
• 多端一致性：Web 仪表板和 VSCode 扩展共享同一任务状态管理逻辑
• 阻塞机制：支持标记任务阻塞原因，便于问题追踪

资料来源：src/dashboard_frontend/src/modules/pages/TasksPage.tsx

功能概述

Web 仪表板的主要功能包括：

资料来源：docs/INTERFACES.md()

系统架构

组件结构

Web 仪表板采用前后端分离的架构设计：

graph TD
    A[Web 浏览器] --> B[Dashboard Frontend<br/>React SPA]
    B --> C[Dashboard Backend<br/>Express.js]
    C --> D[文件系统<br/>.spec-workflow]
    E[多个项目 Workspace] --> D
    
    B --> F[API 模块<br/>api.tsx]
    F --> C

前端部分位于 src/dashboard_frontend/ 目录，使用 React 构建单页应用。主要页面组件包括：

• App.tsx - 根组件，管理全局状态和页面路由
• SettingsPage.tsx - 设置页面，管理自动化清理和偏好配置
• TasksPage.tsx - 任务页面，展示任务详情和进度

资料来源：src/dashboard_frontend/src/modules/app/App.tsx()

部署架构

仪表板支持多种部署方式：

graph LR
    A[直接运行] --> B[npx --dashboard]
    C[Docker 容器] --> D[docker-compose]
    B --> E[http://localhost:5000]
    D --> E

核心页面

项目概览页面

概览页面展示当前选中项目的核心统计数据：

资料来源：vscode-extension/src/webview/App.tsx()

任务页面

任务页面详细展示每个规格文档下定义的任务列表，支持以下功能：

• 状态筛选 - 按 pending、in-progress、completed、blocked 状态筛选
• AI 提示词 - 显示任务关联的 AI 提示词内容
• 杠杆值 - 显示任务的杠杆指数（leverage）
• 进度追踪 - 实时更新任务完成进度

graph TD
    A[获取任务列表] --> B{任务状态}
    B -->|pending| C[待处理]
    B -->|in-progress| D[进行中]
    B -->|completed| E[已完成]
    B -->|blocked| F[已阻塞]
    
    C --> G[状态更新 API]
    D --> G
    E --> G
    F --> G
    G --> H[更新任务状态]

资料来源：src/dashboard_frontend/src/modules/pages/TasksPage.tsx()

设置页面

设置页面提供仪表板全局配置功能，包括自动化清理任务的配置：

• 管理跨所有已连接项目运行的自动化清理作业
• 配置清理频率和保留策略
• 查看清理任务执行日志

资料来源：src/dashboard_frontend/src/modules/pages/SettingsPage.tsx()

API 接口

仪表板前端通过统一的 API 模块与后端通信：

// 规格文档相关 API
getAllSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all`)
getAllArchivedSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all/archived`)
getSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${name}/tasks/progress`)

// 任务状态管理
updateTaskStatus: (specName, taskId, status, reason?) => 
  putJson(`/specs/${specName}/tasks/${taskId}/status`, { status, reason })

// 审批相关 API
approvalsAction: (id, action, body) => postJson(`/approvals/${id}/${action}`, body)
approvalsActionBatch: (ids, action, response) => postJson(`/approvals/batch/${action}`, { ids, response })
approvalsUndoBatch: (ids) => postJson(`/approvals/batch/undo`, { ids })
getApprovalContent: (id: string) => getJson(`/approvals/${id}/content`)
getApprovalSnapshots: (id: string) => getJson(`/approvals/${id}/snapshots`)

资料来源：src/dashboard_frontend/src/modules/api/api.tsx()

部署配置

环境变量

Docker 部署

使用 Docker Compose 部署是最推荐的方案：

cd containers
docker-compose up --build

自定义端口部署示例：

docker run -p 8080:8080 \
  -e DASHBOARD_PORT=8080 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

资料来源：containers/README.md()

快速启动

通过 npx 直接启动本地仪表板：

npx -y @pimzino/spec-workflow-mcp@latest --dashboard

仪表板启动后可通过 http://localhost:5000 访问。

注意：仅需一个仪表板实例即可管理所有已连接项目，所有项目共享同一仪表板服务。

资料来源：docs/INTERFACES.md()

安全特性

Web 仪表板实现了企业级安全控制：

前端国际化

仪表板支持多语言界面，使用 i18n 模块处理翻译资源：

// 语言切换时自动更新
t.changeLanguage(g)  // g 为语言代码
_.setLanguagePreference(g)

语言偏好设置会被持久化保存，用户下次访问时自动应用已选语言。

与 VSCode 扩展的关系

Web 仪表板与 VSCode 扩展共用同一前端组件库和样式资源。编译后的静态资源位于 vscode-extension/webview-dist/ 目录：

这确保了仪表板界面与 VSCode 扩展内嵌 WebView 的一致用户体验。

工作流程示意

sequenceDiagram
    participant User as 用户
    participant Dashboard as Web 仪表板
    participant Backend as 后端服务
    participant FS as 文件系统
    
    User->>Dashboard: 访问 http://localhost:5000
    Dashboard->>Backend: 请求项目列表
    Backend->>FS: 读取 .spec-workflow 配置
    FS-->>Backend: 返回项目元数据
    Backend-->>Dashboard: 返回统计数据
    Dashboard-->>User: 渲染项目概览
    
    User->>Dashboard: 选择规格文档
    Dashboard->>Backend: 获取任务列表
    Backend-->>Dashboard: 返回任务数据
    Dashboard-->>User: 渲染任务页面
    
    User->>Dashboard: 更新任务状态
    Dashboard->>Backend: PUT /specs/{name}/tasks/{id}/status
    Backend->>FS: 更新任务状态文件
    FS-->>Backend: 确认更新
    Backend-->>Dashboard: 返回更新结果

总结

Web 仪表板作为 spec-workflow-mcp 项目的核心用户界面，提供了一个集中化的可视化管理平台。它通过 RESTful API 与后端服务通信，支持多项目管理、任务追踪、审批流程和系统配置等完整功能。仪表板采用 Docker 容器化部署，配置简单快捷，同时具备企业级安全特性，适合团队协作环境使用。

概述

VSCode 扩展是 spec-workflow-mcp 项目的重要组成部分，为 Visual Studio Code 用户提供原生的开发体验。通过该扩展，用户可以直接在 VSCode 编辑器中访问和管理项目规格文档、审批流程以及实现日志，无需切换到独立的 Web 仪表板。

该扩展基于 VSCode Webview API 构建，采用 React 作为前端框架，实现了与核心工作流引擎的深度集成。扩展通过 MCP（Model Context Protocol）协议与后端服务通信，为用户提供实时的工作状态反馈和交互能力。

扩展的主要设计目标是降低 AI 辅助开发的工作流门槛，让开发者能够在熟悉的 IDE 环境中完成从规格创建、审批到实现追踪的完整流程。

架构设计

整体架构

VSCode 扩展采用前后端分离的架构模式，核心组件分为三个层次：

graph TD
    A[VSCode 扩展宿主] --> B[Webview UI 层]
    A --> C[MCP 通信层]
    B <--> D[Webview 消息传递]
    C --> E[后端服务]
    D --> F[用户交互]

目录结构

vscode-extension/
├── README.md                          # 扩展说明文档
├── package.json                       # 扩展配置和依赖
├── src/
│   ├── extension/                     # 扩展后端代码
│   │   ├── providers/
│   │   │   └── SidebarProvider.ts     # 侧边栏提供者
│   │   └── services/
│   │       └── ApprovalEditorService.ts  # 审批编辑器服务
│   └── webview/                       # Webview 前端代码
│       ├── App.tsx                    # 主应用组件
│       ├── comment-modal.html         # 评论模态框 HTML
│       └── components/
│           └── LogEntryCard.tsx       # 日志条目卡片组件
└── webview-dist/                      # 编译后的 Webview 资源
    ├── comment-modal.js               # 评论模态框脚本
    ├── comment-modal.html             # 评论模态框页面
    ├── globals.css                    # 全局样式
    └── i18n.js                        # 国际化脚本

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

Webview 消息通信机制

扩展通过 VSCode 的 postMessage API 实现前端与后端的双向通信。当用户在 Webview 中执行操作时，消息被发送到扩展后端，后端处理请求后返回响应结果。这种模式确保了用户界面的流畅性，同时保持了与核心系统的同步。

Webview 使用 useEffect 钩子监听来自扩展的消息，根据消息类型更新对应的 UI 状态。对于需要持久化的数据操作，扩展会通过 MCP 协议转发到后端服务进行处理。

核心组件

SidebarProvider（侧边栏提供者）

SidebarProvider 是 VSCode 扩展的核心入口点，负责管理侧边栏视图的生命周期。该提供者扩展自 VSCode 的 TreeView API，能够在活动栏中注册一个可折叠的视图区域。

主要职责包括：

• 初始化侧边栏视图结构
• 注册命令和快捷键
• 处理视图项的点击事件
• 管理 Webview 面板的创建和销毁

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

ApprovalEditorService（审批编辑器服务）

ApprovalEditorService 负责处理审批相关的数据操作和服务调用。该服务封装了所有与审批流程相关的业务逻辑，包括审批请求的创建、提交、撤销以及历史记录的查看。

服务层的设计遵循单一职责原则，将数据获取逻辑与 UI 层分离，使得组件可以专注于用户界面的渲染，而无需关心底层的数据获取机制。通过依赖注入模式，扩展可以更容易地进行单元测试和功能扩展。

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

App.tsx（主应用组件）

App.tsx 是 Webview 的根组件，负责协调各个子组件的渲染和状态管理。该组件使用 React Context API 共享全局状态，使得深层嵌套的组件也能方便地访问和更新应用状态。

组件结构采用功能模块化的设计，主要区域包括：

• 概览面板：显示项目统计信息
• 规格列表：展示所有活跃和归档的规格文档
• 任务视图：呈现规格关联的任务及其进度
• 日志视图：展示实现日志条目

资料来源：vscode-extension/src/webview/App.tsx

LogEntryCard 组件

LogEntryCard 是一个专门用于展示实现日志条目的卡片组件。它将复杂的日志数据解析为用户友好的格式，支持多种内容的可视化展示。

组件支持展示的内容类型：

组件采用条件渲染策略，仅当对应类型的数据存在时才显示相应的区域。这种设计减少了不必要的 DOM 操作，提升了渲染性能。

资料来源：vscode-extension/src/webview/components/LogEntryCard.tsx

功能特性

规格文档管理

扩展提供了完整的规格文档管理界面，用户可以：

• 查看所有活跃规格的列表和状态
• 浏览已归档规格的历史记录
• 追踪每个规格关联的任务进度
• 直接在 VSCode 中编辑规格内容

规格列表采用卡片式布局，每个卡片显示规格名称、任务进度条和关键元数据。进度条使用颜色编码来区分完成状态，绿色表示已完成的任务数量，灰色表示总任务数量。

任务追踪系统

任务追踪功能集成在规格详情视图中，允许用户：

• 查看任务的元数据，包括目的、需求和技术杠杆点
• 展开和折叠 AI 提示内容
• 复制任务提示用于其他场景
• 追踪任务的完成状态

任务视图支持展开/折叠交互，用户可以点击任务标题来显示或隐藏详细信息。这种交互模式在处理大量任务时特别有用，可以帮助用户专注于当前关注的内容。

审批工作流

审批功能通过专门的编辑器服务实现，支持以下操作：

• 提交审批请求
• 批准或拒绝申请
• 批量处理多个审批请求
• 查看审批历史快照
• 比较不同版本之间的差异

审批编辑器服务封装了所有与审批相关的数据操作，包括快照生成、版本比较和批量操作。这种封装确保了 UI 层可以专注于用户交互，而无需处理复杂的业务逻辑。

实现日志查看

实现日志功能允许用户回顾开发过程中的所有变更：

• 按时间线查看日志条目
• 查看每次实现修改和创建的文件
• 了解 API 端点、组件、函数等代码工件
• 追踪前后端集成的数据流

日志条目卡片提供了丰富的信息展示，包括统计数据（新增/删除行数）、文件列表和各类代码工件。每个工件条目都包含名称、目的、位置等关键信息，便于开发者快速定位代码。

评论模态框

评论功能通过独立的模态框实现，用户可以在任何支持评论的上下文中添加评论。模态框采用独立的 HTML 页面加载，确保样式与 VSCode 主题一致。

评论模态框的样式通过 CSS 变量与 VSCode 主题系统集成：

body {
  font-family: var(--vscode-font-family), -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
  font-size: var(--vscode-font-size, 13px);
  color: var(--vscode-foreground);
  background: var(--vscode-editor-background);
}

资料来源：vscode-extension/src/webview/comment-modal.html

用户界面设计

主题适配

扩展完全支持 VSCode 的亮色和暗色主题。通过使用 CSS 变量，Webview 可以自动响应主题切换，无需编写额外的主题检测逻辑。所有文本颜色、背景颜色和边框颜色都基于 VSCode 提供的语义化变量定义。

主要使用的 CSS 变量包括：

• var(--vscode-font-family)：字体系列
• var(--vscode-font-size)：字体大小
• var(--vscode-foreground)：前景色
• var(--vscode-editor-background)：编辑器背景色

资料来源：vscode-extension/webview-dist/comment-modal.html

国际化支持

扩展内置了国际化支持，通过 i18n.js 模块提供多语言文本资源。用户界面中的所有可显示文本都通过翻译键引用，而非硬编码的字符串。这种设计使得扩展可以轻松支持新的语言环境。

翻译键采用层级命名规范，例如 overview.projectTitle 表示概览面板的项目标题文本。

响应式布局

Webview 界面采用响应式设计，针对不同的面板宽度提供优化的布局：

• 小屏幕：单列布局，元素垂直堆叠
• 大屏幕：双列或多列布局，充分利用空间

任务视图中的元素根据容器宽度自动调整字体大小和间距。图标、标签和内容区域都采用相对单位，确保在不同尺寸的视口中保持可读性。

配置与安装

安装方式

用户可以通过 VSCode 扩展市场安装该扩展，或者通过命令行加载本地构建的扩展包。

VSCode 配置示例：

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

扩展配置

扩展支持通过 package.json 进行配置，包括：

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

开发指南

本地开发

扩展的开发环境配置遵循标准的 VSCode 扩展开发流程：

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 构建生产版本
npm run build

开发模式下，扩展会自动监听源文件的变化并重新加载，无需手动重启 VSCode。

Webview 资源管理

Webview 所需的静态资源（HTML、CSS、JavaScript）需要在 webview-dist 目录中预编译。开发流程中，这些资源由构建系统自动处理，但在发布前需要确保所有资源都已正确打包。

Webview 的入口点通过 comment-modal.html 定义，该文件引用编译后的脚本和样式资源。

消息协议

扩展与 Webview 之间的消息采用以下协议格式：

interface WebviewMessage {
  type: string;
  payload?: any;
  requestId?: string;
}

每条消息包含消息类型标识和可选的数据负载。对于需要响应的消息，Webview 应在处理完成后发送带有对应 requestId 的响应消息。

相关资源

• 主项目文档：SPEC Workflow MCP 文档
• 开发指南：开发文档
• 工作流程：工作流程指南
• 工具参考：工具参考文档

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 | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code

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

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | 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 | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

7. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | No sandbox install has been executed yet; downstream must verify before user use.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

9. 安全/权限坑 · 来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown