# https://github.com/Pimzino/spec-workflow-mcp 项目说明书
生成时间：2026-05-14 07:49:06 UTC
## 目录
- [项目概述](#page-overview)
- [快速开始](#page-quick-start)
- [安装配置](#page-installation)
- [系统架构](#page-architecture)
- [文件结构](#page-file-structure)
- [规格工作流程](#page-spec-workflow)
- [审批系统](#page-approval-system)
- [任务管理](#page-task-management)
- [Web 仪表板](#page-dashboard)
- [VSCode 扩展](#page-vscode-extension)
## 项目概述
### 相关页面
相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)
- [vscode-extension/src/webview/index.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)
- [src/dashboard_frontend/src/modules/api/api.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)
# 项目概述
## 简介
spec-workflow-mcp 是一个基于 Model Context Protocol (MCP) 的开发工作流管理系统，旨在为 AI 辅助软件开发提供规范化的项目管理和协作框架。该项目通过 MCP 协议与各种 AI 工具（如 Cursor、Claude Desktop、VSCode 等）集成，帮助开发团队在 AI 驱动的开发环境中维护一致的规范、追踪任务进度、管理审批流程，并记录实现日志。
资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
## 核心功能
### MCP 协议集成
作为 MCP 服务器运行，spec-workflow-mcp 提供了一套完整的工具集，使 AI 助手能够与本地项目进行深度交互。开发者可以通过简单的配置将项目目录与各种 AI 客户端连接，从而获得规范感知的工作流支持。
资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
### 规范文档管理
项目支持创建和维护以下核心规范文档：
| 文档类型 | 描述 | 位置 |
|---------|------|------|
| Specs | 软件规格说明文档 | `.spec-workflow/specs/` |
| Steering | 方向指引文档（product.md、tech.md、structure.md） | `.spec-workflow/steering/` |
| Templates | 文档模板 | `.spec-workflow/templates/` |
| Approvals | 审批记录 | `.spec-workflow/approvals/` |
| Archive | 归档文档 | `.spec-workflow/archive/` |
资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
### 实现日志追踪
系统会自动记录 AI 生成的代码变更，包括修改的文件、创建的文件、代码统计（新增/删除行数）以及生成的各类产物（API 端点、组件、函数、类、集成点等）。这一功能确保了开发过程的可追溯性，便于团队审查和回溯。
资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
## 技术架构
### 系统组件架构
```mermaid
graph TD
A[AI 客户端
Cursor/Claude Desktop/VSCode] -->|MCP 协议| B[spec-workflow-mcp
MCP Server]
B --> C[规范存储层
.spec-workflow 目录]
B --> D[Web Dashboard
端口 5000]
B --> E[VSCode 扩展
内嵌 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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)
### REST API 架构
Dashboard 后端提供丰富的 REST API 端点，主要包括：
| API 类别 | 端点模式 | 功能 |
|---------|---------|------|
| Specs | `GET/PUT /specs/:name` | 获取/更新规格文档 |
| Tasks | `GET/PUT /specs/:name/tasks/:id/status` | 任务状态管理 |
| Approvals | `POST /approvals/:id/:action` | 审批操作 |
| Batch | `POST /approvals/batch/:action` | 批量审批 |
| Snapshots | `GET /approvals/:id/snapshots/:version` | 版本快照 |
资料来源：[src/dashboard_frontend/src/modules/api/api.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)
## 部署方式
### 标准部署
项目支持通过 npx 直接运行，配置方式因客户端而异：
**Cursor 配置示例：**
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
### Docker 容器部署
项目提供完整的 Docker 支持，适合隔离部署场景：
```bash
# 使用 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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
## 安全特性
spec-workflow-mcp 实现了企业级的安全控制措施：
| 安全特性 | 描述 |
|---------|------|
| 本地绑定 | 默认绑定 `127.0.0.1`，防止网络暴露 |
| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |
| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、动作和结果 |
| 安全响应头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |
| CORS 保护 | 跨域资源共享控制 |
资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
## 项目结构
### 典型项目目录布局
```
your-project/
.spec-workflow/
approvals/ # 审批文件存储
archive/ # 归档的规范文档
specs/ # 活动规格文档
steering/ # 方向指引文档
templates/ # 文档模板
user-templates/ # 用户自定义模板
config.example.toml # 配置示例
```
### 开发环境
```bash
# 安装依赖
npm install
# 编译项目
npm run build
# 开发模式运行
npm run dev
```
资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
## 许可协议
本项目采用 GPL-3.0 开源许可证发布。
资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
---
## 快速开始
### 相关页面
相关主题：[项目概述](#page-overview), [安装配置](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
- [docs/USER-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/USER-GUIDE.md)
- [docs/PROMPTING-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/PROMPTING-GUIDE.md)
- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)
- [containers/example.mcp.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/example.mcp.json)
# 快速开始
本页面提供 spec-workflow-mcp 项目的快速上手指南，帮助用户在最短时间内完成环境配置并开始使用规范驱动的工作流程。
## 概述
spec-workflow-mcp 是一个基于规范驱动（Specification-Driven）的开发工作流程管理工具，通过 MCP（Model Context Protocol）协议与 AI 工具集成，帮助开发团队在 AI 辅助环境下高效管理项目开发流程。
快速开始指南旨在为用户提供：
- 环境配置的最简路径
- 与 AI 工具集成的标准方式
- 界面选择与启动方法
- 首个项目规范文档的创建流程
资料来源：[README.md:1-50]()
## 环境要求
### 系统要求
| 要求类型 | 最低版本 | 推荐版本 |
|---------|---------|---------|
| Node.js | 18.x | 20.x LTS |
| npm | 9.x | 10.x |
| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | macOS 14+ / Ubuntu 22.04+ / Windows 11 |
### AI 工具兼容性
spec-workflow-mcp 通过 MCP 协议与以下 AI 工具集成：
- Claude Desktop
- Cursor
- VS Code (通过扩展)
- 其他支持 MCP 协议的工具
资料来源：[containers/example.mcp.json:1-30]()
## 安装方式
### 方式一：MCP 配置集成（推荐）
将 spec-workflow-mcp 添加到 AI 工具的 MCP 配置中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
> **注意**：将 `/path/to/your/project` 替换为实际项目路径。
### 方式二：全局安装
```bash
npm install -g @pimzino/spec-workflow-mcp
```
### 方式三：项目本地安装
```bash
npm install @pimzino/spec-workflow-mcp
```
资料来源：[README.md:15-35]()
## 界面选择
根据使用场景，spec-workflow-mcp 提供两种界面选项：
### Web 仪表盘
适用于 CLI 用户和跨项目管理者。
启动命令：
```bash
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 # 配置文件示例
```
### 配置文件
复制并编辑配置文件：
```bash
cp .spec-workflow/config.example.toml .spec-workflow/config.toml
```
主要配置项：
| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `dashboard.port` | 仪表盘端口 | 5000 |
| `dashboard.host` | 仪表盘主机 | localhost |
| `specs.directory` | 规范文档目录 | specs |
| `archive.enabled` | 是否启用归档 | true |
资料来源：[docs/USER-GUIDE.md:10-80]()
## 工作流程概览
### 标准开发流程
```mermaid
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]()
## 常见问题
### 问题一：仪表盘无法启动
**解决方案**：
```bash
# 检查端口占用
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]()
## 下一步
完成快速开始后，建议继续阅读以下文档：
- [用户指南](docs/USER-GUIDE.md) - 深入了解所有功能
- [提示工程指南](docs/PROMPTING-GUIDE.md) - 优化 AI 交互
- [接口指南](docs/INTERFACES.md) - 仪表盘和扩展详细说明
- [开发指南](docs/DEVELOPMENT.md) - 参与项目开发
---
## 安装配置
### 相关页面
相关主题：[快速开始](#page-quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
- [README.ko.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)
- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)
- [docs/CONFIGURATION.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md)
- [src/config.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/config.ts)
# 安装配置
## 概述
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` 配置节进行定义，主要参数如下：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| command | string | 是 | 执行命令，通常为 `npx` |
| args | array | 是 | 命令参数数组 |
| 路径参数 | string | 是 | 目标项目目录的绝对或相对路径 |
标准的 npx 启动命令格式为：
```json
{
"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`，配置示例：
```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` 命令添加服务器：
```bash
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project
```
**关键要点**：
- `-y` 标志用于跳过 npm 提示，确保自动化安装
- `--` 分隔符确保路径参数被传递给 spec-workflow 脚本而非 npx
Windows 用户如果上述命令不生效，可以使用替代方案：
```bash
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 服务器配置：
```json
{
"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 格式：
```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` 中：
```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`：
```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 用户的推荐接口，启动命令：
```bash
npx -y @pimzino/spec-workflow-mcp@latest --dashboard
```
仪表板默认运行在 `http://localhost:5000`。
> **重要说明**：只需要一个仪表板实例，所有项目都连接到同一个仪表板。
资料来源：[README.ko.md:22-29]()
### Docker 部署
对于隔离部署环境，spec-workflow-mcp 支持 Docker 容器化运行：
#### 使用 Docker Compose（推荐方式）
```bash
cd containers
docker-compose up --build
```
#### 使用 Docker CLI
```bash
# 构建镜像
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 包含企业级安全功能，适用于企业环境：
| 安全特性 | 说明 |
|---------|------|
| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |
| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |
| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、操作和结果 |
| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |
| CORS 保护 | 跨域资源共享控制 |
资料来源：[README.md:164-174]()
### 本地绑定
默认情况下，Web 仪表板仅监听 `127.0.0.1`（localhost），这确保了：
- 只有本机浏览器可以访问仪表板
- 外部网络无法连接到服务
- 适用于开发和测试环境
### 速率限制
系统实现了请求速率限制机制：
- 每分钟每客户端 120 个请求
- 超过限制的请求会被拒绝
- 自动清理过期记录以释放资源
## 本地开发配置
### 安装依赖
```bash
npm install
```
资料来源：[README.md:60]()
### 构建项目
```bash
npm run build
```
构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist/` 目录。
### 开发模式运行
```bash
npm run dev
```
开发模式提供热重载功能，代码修改后自动重新编译和重启服务。
资料来源：[README.md:61-67]()
## 配置验证
### 验证步骤
1. **检查 MCP 服务器状态**：在对应的 AI 工具中确认 MCP 服务器已正确加载
2. **验证仪表板连接**：访问 `http://localhost:5000` 确认 Web 仪表板可访问
3. **检查项目目录**：确认 `.spec-workflow` 目录已在项目根目录创建
4. **测试规范创建**：尝试创建一个新的规范文档验证写入权限
### 常见配置问题
| 问题 | 可能原因 | 解决方案 |
|------|---------|---------|
| MCP 服务器无法启动 | npx 未安装或版本过旧 | 安装最新版本的 Node.js 和 npm |
| 仪表板无法访问 | 端口 5000 被占用 | 更换端口或终止占用进程 |
| 权限错误 | 项目目录不可写 | 检查目录权限设置 |
| 路径解析失败 | 相对路径未正确解析 | 使用绝对路径替代相对路径 |
## 扩展配置
### VSCode 扩展配置
VSCode 用户可以使用专门的扩展程序，获得更好的集成体验：
```bash
# 从 VSCode Marketplace 安装扩展
# 然后在扩展设置中配置项目路径
```
VSCode 扩展提供了内联的用户界面，无需单独启动 Web 仪表板。
资料来源：[README.ko.md:31-35]()
### 多项目配置
spec-workflow-mcp 支持同时管理多个项目：
1. 每个项目需要独立的 `.spec-workflow` 目录
2. 所有项目可以共享同一个仪表板实例
3. 在 MCP 配置中使用不同的路径参数指向各项目
```json
{
"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"]
}
}
}
```
## 配置架构图
```mermaid
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
```
## 下一步
配置完成后，建议阅读以下文档：
- [工作流指南](docs/WORKFLOW.md) - 开发工作流和最佳实践
- [接口指南](docs/INTERFACES.md) - 仪表板和 VSCode 扩展详情
- [工具参考](docs/TOOLS-REFERENCE.md) - 完整工具文档
- [故障排除](docs/TROUBLESHOOTING.md) - 常见问题及解决方案
---
## 系统架构
### 相关页面
相关主题：[文件结构](#page-file-structure), [Web 仪表板](#page-dashboard)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/server.ts)
- [src/dashboard/multi-server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/multi-server.ts)
- [src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)
- [src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx)
- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
- [src/dashboard_frontend/src/modules/pages/SettingsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/SettingsPage.tsx)
- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
# 系统架构
## 概述
Spec-Workflow-MCP 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统，旨在为 AI 驱动的软件开发提供结构化的规格管理和实现跟踪能力。该系统采用模块化架构设计，支持多个项目连接至单一仪表板实例，实现跨项目的规格、任务和实施日志的统一管理。
系统的核心设计理念是将 AI 开发过程的结构化，通过规格文档（Spec）、任务拆解、实施日志等机制，确保 AI 生成的代码与预期规格保持一致。
## 整体架构
```mermaid
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 Server | 处理 AI 工具请求的核心服务器 | 标准输入/输出 |
| Dashboard Server | Web 仪表板服务器 | 5000 |
| WebSocket Server | 实时通信服务 | 与仪表板共享端口 |
服务器支持两种运行模式：独立 MCP 模式和仪表板模式。运行 MCP 模式时，服务器通过标准输入输出与 AI 客户端通信；运行仪表板模式时，启动 Web 服务器提供可视化界面。
### 多服务器管理
系统采用多服务器架构，允许连接多个项目至同一个仪表板实例：
```mermaid
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]()
| 功能 | 描述 |
|------|------|
| 规格监控 | 监听 specs 目录下的规格文件变更 |
| 任务跟踪 | 监控任务状态文件的变化 |
| 实施日志 | 记录文件创建和修改事件 |
| 归档检测 | 检测已归档规格的状态变化 |
文件变更通过 WebSocket 实时推送至前端界面，实现多客户端的状态同步。
## 前端架构
### Web 仪表板
Web 仪表板基于 React 构建，提供完整的项目管理和监控界面：
```mermaid
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]
```
#### 页面模块
| 页面 | 功能 |
|------|------|
| 概览页 | 显示项目统计、规格完成度、任务进度 |
| 任务页 | 看板和列表两种视图，支持状态筛选和排序 |
| 日志页 | 展示实施日志，包括文件变更、统计信息、工件记录 |
| 设置页 | 管理自动清理任务、API 端点配置 |
### WebSocket 通信
WebSocket 模块负责客户端与服务端之间的实时双向通信：
资料来源：[src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx]()
```mermaid
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 # 配置示例
```
### 实施日志条目
系统记录每次规格实施的完整信息：
| 字段 | 类型 | 描述 |
|------|------|------|
| id | string | 唯一标识符 |
| timestamp | Date | 执行时间戳 |
| specification | string | 关联规格 |
| status | string | 执行状态 |
| filesModified | string[] | 修改的文件列表 |
| filesCreated | string[] | 创建的文件列表 |
| statistics | object | 代码统计（行数增删等） |
| artifacts | object | 工件记录 |
### 工件类型
| 类型 | 说明 |
|------|------|
| apiEndpoints | API 端点定义 |
| components | UI 组件 |
| functions | 函数定义 |
| classes | 类定义 |
| integrations | 集成点 |
## 安全机制
系统实现了企业级安全特性：
```mermaid
graph LR
subgraph "安全层"
RATE[速率限制]
CORS[CORS 保护]
HEAD[安全头]
LOG[审计日志]
end
Request[请求] --> RATE
RATE --> CORS
CORS --> HEAD
HEAD --> LOG
```
| 安全功能 | 说明 |
|----------|------|
| 本地绑定 | 默认绑定至 127.0.0.1，防止网络暴露 |
| 速率限制 | 每客户端 120 请求/分钟，自动清理 |
| 审计日志 | 结构化 JSON 日志，记录时间戳、操作者、动作和结果 |
| 安全头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |
| CORS 保护 | 限制跨域访问 |
## 部署模式
### Docker 部署
系统支持 Docker 容器化部署：
```dockerfile
# 容器结构
┌─────────────────────────────┐
│ spec-workflow-mcp │
├─────────────────────────────┤
│ Node.js Runtime │
│ ├─ Dashboard Server │
│ ├─ WebSocket Server │
│ └─ MCP Protocol Handler │
└─────────────────────────────┘
```
容器部署命令：
```bash
# 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]()
| 客户端 | 配置方式 |
|--------|----------|
| Claude Desktop | settings.json |
| Cline/Claude Dev | MCP 配置 |
| Continue | MCP 配置 |
| Cursor IDE | settings.json |
| Codex | config.toml |
## 实时同步机制
```mermaid
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]
```
所有连接至同一仪表板实例的客户端共享状态视图，确保多端操作的一致性。
---
## 文件结构
### 相关页面
相关主题：[系统架构](#page-architecture), [规格工作流程](#page-spec-workflow)
相关源码文件
以下源码文件用于生成本页说明：
- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)
- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)
- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)
- [src/dashboard_frontend/src/modules/pages/TasksPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx)
- [src/dashboard_frontend/src/modules/pages/LogsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/LogsPage.tsx)
- [src/dashboard_frontend/src/modules/pages/SteeringPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/SteeringPage.tsx)
# 文件结构
## 概述
`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]()
| 目录名 | 用途 |
|--------|------|
| `approvals/` | 存放规格审批文件 |
| `archive/` | 归档已完成或废弃的规格 |
| `specs/` | 存放活跃的规格文档 |
| `steering/` | 存放指导性文档 |
| `templates/` | 系统内置模板 |
| `user-templates/` | 用户自定义模板 |
| `config.example.toml` | 配置文件示例 |
## 核心业务逻辑层 (`src/`)
`src/` 目录包含了系统的主要业务逻辑，采用 TypeScript 实现。
### 核心模块 (`src/core/`)
核心模块包含系统的基础功能组件：
| 文件 | 职责 |
|------|------|
| `implementation-log-migrator.ts` | 实现日志的数据迁移和格式化转换 |
### 仪表板模块 (`src/dashboard/`)
仪表板模块负责实现日志管理和数据展示功能：
| 文件 | 职责 |
|------|------|
| `implementation-log-manager.ts` | 实现日志的添加、查询、格式化和导出功能 |
### Markdown 模板 (`src/markdown/templates/`)
模板系统用于生成标准化的项目文档：
| 模板文件 | 用途 |
|----------|------|
| `design-template.md` | 设计文档模板 |
| `requirements-template.md` | 需求文档模板 |
| `tasks-template.md` | 任务清单模板 |
## 仪表板前端 (`src/dashboard_frontend/`)
仪表板前端是一个独立的 Web 应用，提供图形化界面来管理规格工作流。
### 页面模块 (`src/dashboard_frontend/src/modules/pages/`)
| 页面文件 | 功能描述 |
|----------|----------|
| `TasksPage.tsx` | 任务管理页面，包含进度跟踪和任务列表展示 |
| `LogsPage.tsx` | 实现日志页面，展示文件变更、创建和统计数据 |
| `SteeringPage.tsx` | 指导文档页面，提供项目文档导航 |
| `JobExecutionHistory.tsx` | 作业执行历史页面，记录批处理任务执行情况 |
### 架构流程图
```mermaid
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/`)
| 文件/目录 | 用途 |
|-----------|------|
| `App.tsx` | 主应用组件，包含项目概览和任务列表 |
| `index.html` | Web 视图入口 HTML |
| `comment-modal.html` | 注释模态框 HTML |
| `components/LogEntryCard.tsx` | 日志条目卡片组件 |
### Web 视图组件关系
```mermaid
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 扩展的实际运行：
| 文件 | 对应源文件 |
|------|------------|
| `index.html` | 编译后的主入口 |
| `comment-modal.html` | 编译后的注释模态框 |
| `main.js` | 打包后的主应用代码 |
| `comment-modal.js` | 打包后的模态框代码 |
| `globals.css` | 全局样式 |
| `i18n.js` | 国际化资源 |
## 实现日志数据结构
系统通过 `ImplementationLogEntry` 接口管理实现日志，包含以下关键字段： 资料来源：[src/dashboard/implementation-log-manager.ts:1-20]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 日志唯一标识符 |
| `timestamp` | Date | 创建时间戳 |
| `summary` | string | 实现摘要 |
| `statistics` | object | 代码统计信息（文件数、行数变更等） |
| `filesModified` | string[] | 修改的文件列表 |
| `filesCreated` | string[] | 创建的文件列表 |
| `artifacts` | object | 生成的代码构件 |
### Artifacts 子结构
`artifacts` 对象包含多种代码构件类型的记录： 资料来源：[src/dashboard/implementation-log-manager.ts:30-60]()
| 构件类型 | 字段说明 |
|----------|----------|
| `apiEndpoints` | API 端点：method、path、purpose、location、requestFormat、responseFormat |
| `components` | 组件：name、type、purpose、location、props、exports |
| `functions` | 函数：name、purpose、location、signature、isExported |
| `classes` | 类：name、purpose、location、methods、isExported |
| `integrations` | 集成：description、frontendComponent、backendEndpoint、dataFlow |
## 前端组件架构
### 任务页面组件 (`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]()
```typescript
interface LogEntryCardProps {
entry: ImplementationLogEntry;
}
```
## 多语言支持
项目包含国际化（i18n）支持，通过 `i18n.js` 模块提供多语言文本资源。已确认的语言版本包括：
- 英语（默认）
- 法语（`README.fr.md`）
## 构建与部署
### 前端构建
```bash
npm install
npm run build
```
### VSCode 扩展构建
VSCode 扩展的 Web 视图代码独立构建到 `webview-dist/` 目录，然后与扩展主体打包。 资料来源：[vscode-extension/webview-dist/index.html:1-20]()
### 开发模式
```bash
npm run dev
```
## 架构总览图
```mermaid
graph TD
subgraph 前端层
A[仪表板前端
React + TypeScript]
B[VSCode 扩展 WebView]
end
subgraph 核心层
C[实现日志管理
implementation-log-manager]
D[日志迁移器
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/`) 确保文档标准化
这种模块化设计使得系统各部分可以独立开发、测试和部署，同时保持良好的可维护性和可扩展性。
---
## 规格工作流程
### 相关页面
相关主题：[任务管理](#page-task-management), [审批系统](#page-approval-system)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/WORKFLOW.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/WORKFLOW.md)
- [src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)
- [src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)
- [src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)
- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)
- [src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)
# 规格工作流程
## 概述
规格工作流程（Spec Workflow）是 spec-workflow-mcp 项目的核心功能模块，为 AI 代码助手提供结构化的项目开发流程管理能力。该工作流程通过规范化的文档创建、审批和执行机制，帮助开发团队在 AI 辅助编程环境中保持开发目标的一致性和可追溯性。
规格工作流程的主要目标是：
- 在项目启动阶段建立清晰的产品愿景和技术架构
- 将大型需求拆解为可执行的小粒度任务
- 通过审批流程确保 AI 生成的内容符合预期
- 记录实现过程中的关键产物，便于后续维护
资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)
## 核心概念
### 规格文档类型
规格工作流程使用多种类型的文档来组织项目信息：
| 文档类型 | 文件路径 | 用途 |
|---------|---------|------|
| 产品文档 | `.spec-workflow/steering/product.md` | 定义产品愿景、目标用户和关键特性 |
| 技术文档 | `.spec-workflow/steering/tech.md` | 记录技术架构决策和技术栈 |
| 结构文档 | `.spec-workflow/steering/structure.md` | 描述代码库组织结构和模块架构 |
| 设计文档 | `.spec-workflow/specs/{name}/design.md` | 具体规格的设计说明 |
| 任务文档 | `.spec-workflow/specs/{name}/tasks.md` | 将设计拆解为可执行任务 |
资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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）是项目的顶层规划文档，包括产品愿景、技术架构和代码结构三个核心文档。
### 工作流程阶段
引导文档工作流程分为三个阶段：
```mermaid
graph TD
Start([开始]) --> P1_Template[检查用户模板
user-templates/]
P1_Template --> P1_Read{是否有自定义模板?}
P1_Read -->|是| P1_Custom[读取自定义模板]
P1_Read -->|否| P1_Default[读取默认模板
templates/]
P1_Custom --> P1_Analyze[分析产品需求]
P1_Default --> P1_Analyze
P1_Analyze --> P1_Create[创建文件
steering/product.md]
P1_Create --> P1_Approve[approvals
action: request
filePath only]
P1_Approve --> P1_Status[approvals
action: status
轮询状态]
P1_Status --> P1_Check{状态?}
P1_Check -->|needs-revision| P1_Update[根据用户评论更新文档]
P1_Update --> P1_Create
P1_Check -->|approved| P1_Clean[approvals
action: delete]
P1_Clean -->|失败| P1_Status
P1_Clean -->|成功| P2_Template
P2_Template --> P2_Read[检查技术模板]
P2_Read --> P2_Analyze[分析技术栈]
P2_Analyze --> P2_Create[创建文件
steering/tech.md]
P2_Create --> P2_Approve[approvals
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[创建文件
steering/structure.md]
P3_Create --> P3_Approve[approvals
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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`
## 规格创建工作流程
规格创建工作流程用于生成具体的项目规格文档，包括设计文档和任务列表。
### 工作流程阶段
```mermaid
graph TD
Start([开始]) --> P1_Template[检查设计模板]
P1_Template --> P1_Read[读取模板内容]
P1_Read --> P1_Analyze[分析需求]
P1_Analyze --> P1_Create[创建文件
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[创建文件
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)
## 审批系统
审批系统是规格工作流程的质量保障机制，确保 AI 生成的内容经过人工确认后再执行。
### 审批操作
| 操作 | 参数 | 说明 |
|-----|------|------|
| request | filePath | 创建新的审批请求 |
| status | - | 查询当前审批状态 |
| delete | - | 审批通过后删除记录 |
### 审批状态
| 状态 | 含义 | 后续操作 |
|-----|------|---------|
| pending | 等待审批 | 继续轮询 |
| approved | 已批准 | 删除审批并继续下一步 |
| needs-revision | 需要修改 | 根据评论更新文档，重新请求审批 |
### 审批流程状态图
```mermaid
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 | 加载引导文档工作流指令 | src/tools/steering-guide.ts |
| spec-workflow-guide | 加载规格创建工作流指令 | src/tools/spec-workflow-guide.ts |
| approvals | 管理审批工作流 | 工具模块 |
### 工作流工具参数
```typescript
// 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）负责将任务文档解析为可执行的任务列表。
### 解析流程
```mermaid
graph LR
A[tasks.md] --> B[task-parser.ts]
B --> C{解析任务}
C --> D[验证任务格式]
D --> E[提取任务属性]
E --> F[返回任务列表]
```
### 任务属性
| 属性 | 说明 | 来源 |
|-----|------|------|
| id | 唯一标识符 | 文档解析 |
| title | 任务标题 | 文档解析 |
| description | 任务描述 | 文档解析 |
| status | 执行状态 | 运行时更新 |
| leverage | 杠杆值 | 用户指定 |
资料来源：[src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)
## 实现日志
实现日志（Implementation Log）用于记录任务执行过程中的关键信息。
### 日志条目结构
```typescript
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
## 接口选项
规格工作流程提供两种用户界面：
### 网页仪表盘
- 默认端口：5000
- 启动命令：`npx -y @pimzino/spec-workflow-mcp@latest --dashboard`
- 访问地址：http://localhost:5000
- 特点：集中管理，一个实例可供所有项目使用
### VSCode 扩展
- 集成到 VSCode 编辑器
- 提供内联任务管理和审批功能
- 适合 VSCode 用户
## 配置
### MCP 服务器配置
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
### 配置文件
项目根目录下的 `config.example.toml` 提供了配置选项示例。
## 许可证
本项目采用 GPL-3.0 开源许可证。
---
## 审批系统
### 相关页面
相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)
- [src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)
- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)
- [src/dashboard_frontend/src/modules/approvals](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/approvals)
- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
- [src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx)
# 审批系统
## 概述
审批系统（Approval System）是 spec-workflow-mcp 项目中用于管理和追踪文档审批流程的核心模块。该系统贯穿整个规范工作流，从产品文档、技术文档、结构文档到任务文档的创建和更新，都需要经过审批环节才能完成。
审批系统的设计遵循以下核心原则：
- **请求-审批-状态轮询**模式：每次文档创建或更新都需要发起审批请求，并通过轮询机制追踪审批状态
- **批量操作支持**：支持多选模式下的批量批准或拒绝操作
- **状态驱动的流程控制**：通过状态检查点（needs-revision/approved）决定下一步操作
- **多端一致性**：VSCode 扩展和 Web Dashboard 提供统一的审批界面
## 架构设计
### 系统组件
```
┌─────────────────────────────────────────────────────────────────┐
│ 审批系统架构 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ VSCode │ │ Web │ │ MCP │ │
│ │ 扩展 │ │ Dashboard │ │ Server │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 审批存储层 │ │
│ │ approval-storage.ts │ │
│ └──────────┬──────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ 文件系统 │ │
│ │ .spec-workflow/ │ │
│ │ approvals/ │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 核心模块职责
| 模块 | 文件路径 | 职责 |
|------|---------|------|
| 审批工具 | `src/tools/approvals.ts` | 提供 `request`、`status`、`delete` 等审批操作函数 |
| 审批存储 | `src/dashboard/approval-storage.ts` | 管理审批记录的文件持久化 |
| 审批页面 | `src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx` | Web Dashboard 审批 UI |
| VSCode 组件 | `vscode-extension/src/webview/App.tsx` | VSCode 扩展内的审批卡片组件 |
## 审批工作流
### 完整状态流程
```mermaid
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([审批拒绝])
```
### 各阶段的审批操作
根据工作流定义，审批操作分为三种类型：
| 操作类型 | 用途 | 触发条件 |
|---------|------|---------|
| `request` | 发起新的审批请求 | 文档创建或更新后 |
| `status` | 轮询审批状态 | 请求后持续检查 |
| `delete` | 删除已完成的审批记录 | 审批状态为 approved 后 |
资料来源：[src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)
### 各阶段的审批节点
审批系统应用于以下工作流阶段：
```mermaid
graph LR
subgraph 产品文档阶段
P1_Request[approvals
action: request]
P1_Status[approvals
action: status]
end
subgraph 技术文档阶段
P2_Request[approvals
action: request]
P2_Status[approvals
action: status]
end
subgraph 结构文档阶段
P3_Request[approvals
action: request]
P3_Status[approvals
action: status]
end
subgraph 设计文档阶段
D_Request[approvals
action: request]
D_Status[approvals
action: status]
end
subgraph 任务阶段
T_Request[approvals
action: request]
T_Status[approvals
action: status]
end
```
每个阶段的审批流程遵循相同的模式：创建文档 → 请求审批 → 轮询状态 → 根据结果更新或完成。
资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)
## 数据模型
### 审批记录结构
```typescript
interface Approval {
id: string; // 唯一标识符
title: string; // 审批标题
description?: string; // 审批描述
filePath?: string; // 相关文件路径（仅包含路径，不含内容）
createdAt: Date | string; // 创建时间
status: 'pending' | 'approved' | 'rejected' | 'needs-revision';
category?: string; // 分类（用于过滤）
}
```
### 审批状态枚举
| 状态值 | 含义 | 后续操作 |
|-------|------|---------|
| `pending` | 待审批 | 等待用户响应 |
| `approved` | 已批准 | 可删除记录，流程继续 |
| `rejected` | 已拒绝 | 需要重新修改后再次提交 |
| `needs-revision` | 需要修订 | 根据评论更新文档后重新提交 |
资料来源：[src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx)
## 前端组件
### 审批卡片组件
审批卡片是展示单个审批记录的核心组件，位于 VSCode 扩展的 Webview 中：
```typescript
// 卡片显示的信息
- 标题 (title): 显示审批主题
- 描述 (description): 可选的审批说明
- 文件路径 (filePath): 以等宽字体显示的代码路径
- 创建时间: 使用 formatDistanceToNow 格式化显示
- 状态徽章: pending 状态显示待处理标识
```
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
### 卡片操作按钮
| 按钮 | 功能 | 状态 |
|-----|------|-----|
| 批准 (Approve) | 批准该审批请求 | 显示处理中状态 |
| 拒绝 (Reject) | 拒绝该审批请求 | 显示处理中状态 |
| 在编辑器中打开 | 查看审批文件内容 | - |
### 批量操作
审批系统支持多选模式下的批量操作：
```typescript
// 批量操作状态
interface BatchState {
selectionMode: boolean; // 是否处于选择模式
selectedApprovalIds: Set; // 已选中的审批 ID
batchProcessing: boolean; // 是否正在处理
pendingAction: 'approve' | 'reject' | null; // 待执行的批量操作
batchResult: BatchApprovalResult | null; // 批量操作结果
}
```
批量操作界面包含：
1. **选择计数显示**：显示已选择的审批数量
2. **清除选择按钮**：取消当前所有选择
3. **批量批准按钮**：批准所有选中的审批
4. **批量拒绝按钮**：拒绝所有选中的审批
5. **结果提示**：显示操作成功或失败的数量统计
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
### 审批页面组件
Web Dashboard 的审批页面（ApprovalsPage）提供更完整的功能：
#### 筛选功能
```typescript
// 分类过滤
const [filterCategory, setFilterCategory] = useState('all');
// URL 参数支持高亮显示特定审批
const [searchParams, setSearchParams] = useSearchParams();
const highlightedId = searchParams.get('id');
```
#### 模态框警告
| 模态框 | 触发条件 | 用途 |
|-------|---------|------|
| 审批警告 | 批量操作前 | 确认批量操作的潜在影响 |
| 修订警告 | 修订审批无评论时 | 提示用户添加修订说明 |
资料来源：[src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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. **清理归档**：已批准的审批记录可被删除，相关文档移动到归档目录
## 国际化支持
审批系统支持多语言显示，关键翻译键位：
| 翻译键 | 说明 |
|-------|------|
| `approvals.status.pending` | 待处理状态 |
| `approvals.approve` | 批准按钮 |
| `approvals.processing` | 处理中状态 |
| `approvals.openInEditor` | 在编辑器中打开 |
| `approvals.created` | 创建时间（带时间参数） |
| `approvals.noPending` | 无待处理审批 |
| `approvals.selectedCount` | 已选中数量 |
| `approvals.clearSelection` | 清除选择 |
| `approvalsPage.approvalWarning.message` | 审批警告消息 |
| `approvalsPage.revision.noCommentsTitle` | 修订无评论标题 |
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
## API 接口
### 审批相关 API
| 接口名 | 功能 | 参数 |
|-------|------|-----|
| `approveRequest(id, response)` | 批准指定审批 | id: 审批ID, response: 响应内容 |
| `rejectRequest(id, response)` | 拒绝指定审批 | id: 审批ID, response: 响应内容 |
| `getApprovalContent(id)` | 获取审批内容 | id: 审批ID |
| `approvalsActionBatch(ids, action)` | 批量操作 | ids: 审批ID数组, action: 操作类型 |
| `approvalsUndoBatch(ids)` | 撤销批量操作 | ids: 审批ID数组 |
### 状态轮询机制
```typescript
// 状态轮询流程
async function pollStatus(approvalId: string) {
let status = await getApprovalStatus(approvalId);
while (status === 'pending') {
await sleep(1000); // 轮询间隔
status = await getApprovalStatus(approvalId);
}
return status;
}
```
## 样式与用户体验
### 视觉设计
审批卡片采用以下设计规范：
```css
/* 卡片容器 */
.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）的核心环节：
```mermaid
graph TD
subgraph 工作流阶段
Create[创建文档] --> Approve[请求审批]
Approve --> Poll[轮询状态]
Poll --> Check{状态判断}
Check -->|修订| Update[更新文档]
Update --> Create
Check -->|批准| Continue[继续下一阶段]
Check -->|拒绝| Failed[流程失败]
end
```
### 统计面板集成
审批统计信息集成在 Dashboard 的统计面板中：
| 统计项 | 字段 | 显示逻辑 |
|-------|------|---------|
| 待审批数量 | `approvals.length` | 大于0时显示警告色 |
| 审批状态 | awaiting / allClear | 根据数量显示不同文案 |
资料来源：[src/dashboard_frontend/src/modules/pages/DashboardStatistics.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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 日志输出
---
## 任务管理
### 相关页面
相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)
相关源码文件
以下源码文件用于生成本页说明：
- [src/dashboard_frontend/src/modules/pages/TasksPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx)
- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
- [vscode-extension/src/extension/utils/taskParser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts)
- [src/dashboard_frontend/src/modules/api/api.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)
- [src/dashboard_frontend/src/modules/components/KanbanTaskCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/components/KanbanTaskCard.tsx)
- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)
# 任务管理
## 概述
任务管理是 spec-workflow-mcp 项目的核心功能模块，负责规范化和跟踪项目中的开发任务。该模块支持多状态流转、看板视图、实时进度统计以及任务元数据管理，为团队提供了清晰的任务可视化和管理能力。
任务管理系统的核心设计目标包括：
- **状态驱动的工作流**：通过明确的任务状态定义团队工作进度
- **Markdown 格式兼容**：任务以 Markdown 复选框格式存储，便于版本控制
- **多端一致性**：Web 仪表板和 VSCode 扩展共享同一任务状态管理逻辑
- **阻塞机制**：支持标记任务阻塞原因，便于问题追踪
资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx)
---
## 任务状态定义
### 状态类型
系统定义了四种互斥的任务状态：
| 状态值 | 复选框标记 | 含义 | 视觉标识 |
|--------|-----------|------|---------|
| `pending` | 空格 ` ` | 待处理 | 默认灰色 |
| `in-progress` | 短横 `-` | 进行中 | 橙色边框 |
| `completed` | 小写 `x` | 已完成 | 绿色样式 |
| `blocked` | 波浪 `~` | 已阻塞 | 红色边框 |
资料来源：[vscode-extension/src/extension/utils/taskParser.ts:13-16](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts#L13-L16)
### 状态转换规则
```mermaid
stateDiagram-v2
[*] --> pending : 新建任务
pending --> in-progress : 开始处理
in-progress --> completed : 任务完成
in-progress --> blocked : 发现阻塞
blocked --> in-progress : 解除阻塞
blocked --> pending : 回退待处理
completed --> pending : 重新打开
```
状态转换时的处理逻辑：
```typescript
// 拦截 blocked 状态以记录原因
if (newStatus === 'blocked') {
setPendingBlockedTaskId(taskId);
setKanbanBlockedReasonOpen(true);
return;
}
```
资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx:77-82](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx#L77-L82)
---
## 任务数据模型
### 核心字段
```typescript
interface Task {
id: string; // 任务唯一标识 (如 "1.1", "2.3.1")
status: TaskStatus; // 当前状态
completed?: boolean; // 是否已完成 (计算属性)
inProgress?: boolean; // 是否进行中 (计算属性)
blockedReason?: string; // 阻塞原因 (仅 blocked 状态)
prompt?: string; // AI 执行提示词
leverage?: string; // 复用/杠杆信息
purposes?: string[]; // 任务目的列表
requirements?: string[]; // 特殊需求列表
isHeader?: boolean; // 是否为分组标题
}
```
### 任务元数据展示
看板卡片支持展示丰富的任务元数据：
| 元数据字段 | 展示位置 | 样式特征 |
|-----------|---------|---------|
| 任务 ID | 卡片顶部 | 等宽字体，深色背景 |
| Leverage | 青色标签 | 青色背景，等宽字体 |
| Purposes | 绿色标签 | 列表形式展示 |
| Requirements | 橙色标签 | 逗号分隔展示 |
| AI Prompt | 可展开区域 | 带复制按钮 |
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
---
## Markdown 格式解析
### 任务格式规范
任务以标准 Markdown 复选框语法存储：
```markdown
- [ ] 1.1 任务描述
- [-] 1.2 进行中的任务
- [x] 1.3 已完成任务
- [~] 1.4 阻塞的任务 (原因在下一行)
```
解析器支持 `-` 和 `*` 两种列表标记符：
```typescript
// 正则匹配模式
const checkboxMatch = line.match(/^(\s*)([-*])\s+\[([ x\-~])\]\s+(.+)/);
```
资料来源：[vscode-extension/src/extension/utils/taskParser.ts:26-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts#L26-L35)
### 状态更新机制
```typescript
export function updateTaskStatus(
content: string,
taskId: string,
newStatus: 'pending' | 'in-progress' | 'completed' | 'blocked',
reason?: string
): string {
const statusMarker = newStatus === 'completed' ? 'x' :
newStatus === 'in-progress' ? '-' :
newStatus === 'blocked' ? '~' :
' ';
// ... 遍历并更新匹配的任务行
}
```
资料来源：[vscode-extension/src/extension/utils/taskParser.ts:48-61](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts#L48-L61)
---
## 看板视图
### 布局结构
```mermaid
graph TD
subgraph 看板布局
A[待处理列] --> B[进行中列]
B --> C[已完成列]
B --> D[已阻塞列]
end
subgraph 任务统计
E[总任务数] --> F[完成率百分比]
G[进度条组件] --> F
end
```
### 任务卡片组件
```typescript
// KanbanTaskCard 核心交互
interface KanbanTaskCardProps {
task: Task;
isInProgress: boolean;
copiedTaskId: string | null;
onCopyTaskPrompt: () => void;
onToggleExpand: () => void;
}
```
关键交互特性：
- **触摸优化**：最小点击目标 44x44 像素（WCAG AAA 标准）
- **复制功能**：一键复制 AI Prompt 到剪贴板
- **进行中指示**：橙色脉冲动画标识当前处理任务
资料来源：[src/dashboard_frontend/src/modules/components/KanbanTaskCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/components/KanbanTaskCard.tsx)
---
## API 接口
### 任务状态更新
```
PUT /specs/{specName}/tasks/{taskId}/status
```
**请求参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `specName` | string | 是 | 规格文档名称（URL 编码） |
| `taskId` | string | 是 | 任务标识符（URL 编码） |
| `status` | TaskStatus | 是 | 新状态值 |
| `reason` | string | 否 | 阻塞原因（仅 blocked 时） |
**响应结构：**
```typescript
interface TaskStatusResponse {
success: boolean;
task: Task;
progress: number; // 0-100 百分比
}
```
资料来源：[src/dashboard_frontend/src/modules/api/api.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)
### 进度查询
```
GET /specs/{specName}/tasks/progress
```
**返回数据：**
```typescript
interface TaskProgress {
total: number; // 总任务数
completed: number; // 已完成数
inProgress: string | null; // 当前进行中的任务ID
progress: number; // 完成百分比
taskList: Task[]; // 完整任务列表
}
```
---
## 实施日志管理
### 日志条目结构
```typescript
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 导出格式
实施日志支持导出为 Markdown 格式，便于文档化和分享：
```markdown
## Task Summary
_任务摘要信息_
---
## Statistics
- Lines Added: {count}
- Lines Removed: {count}
## Files Modified
- file1.ts
- file2.ts
---
## Artifacts
### API Endpoints
#### POST /api/resource
- **Purpose:** 端点用途说明
- **Location:** 文件路径
### Components
#### ComponentName
- **Type:** 组件类型
- **Purpose:** 组件用途
```
资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)
---
## 前端状态管理
### 乐观更新策略
任务状态更新采用乐观更新模式，先更新本地 UI 再同步服务器：
```typescript
// 标记待更新任务
pendingStatusUpdatesRef.current.add(taskId);
// 乐观更新本地数据
setData((prevData: any) => {
const updatedTaskList = prevData.taskList.map((t: any) =>
t.id === taskId ? {
...t,
status: newStatus,
completed: newStatus === 'completed',
inProgress: newStatus === 'in-progress',
blockedReason: undefined
} : t
);
return { ...prevData, taskList: updatedTaskList };
});
```
资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx:84-100](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx#L84-L100)
### 剪贴板操作
支持现代 Clipboard API 和传统 fallback 方案：
```typescript
function copyTaskPrompt(specName: string, task: any, onSuccess?, onFailure?) {
const command = task.prompt || `Please work on task ${task.id} for spec "${specName}"`;
// 现代 API
if (navigator.clipboard?.writeText) {
navigator.clipboard.writeText(command).then(() => onSuccess?.());
} else {
// 传统方案 (HTTP over LAN 等场景)
fallbackCopy(command, onSuccess, onFailure);
}
}
```
资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx)
---
## 统计与可视化
### 任务计数器
```typescript
const taskCounts = {
all: nonHeaderTasks.length,
completed: nonHeaderTasks.filter(t => t.status === 'completed').length,
'in-progress': nonHeaderTasks.filter(t => t.status === 'in-progress').length,
pending: nonHeaderTasks.filter(t => t.status === 'pending').length,
blocked: nonHeaderTasks.filter(t => t.status === 'blocked').length,
headers: tasks.filter(t => t.isHeader).length
};
```
### 进度条组件
进度百分比计算公式：
```
progress = (completedTasks / totalTasks) * 100
```
显示时四舍五入至整数：
```tsx
{Math.round(taskData.progress)}%
```
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
---
## 筛选与排序
### 状态筛选
| 筛选值 | 显示内容 |
|--------|---------|
| `all` | 所有任务 |
| `pending` | 仅待处理 |
| `in-progress` | 仅进行中 |
| `completed` | 仅已完成 |
| `blocked` | 仅已阻塞 |
### 排序控制
- **看板视图**：按状态列自动分组
- **列表视图**：支持多维度排序（优先级、创建时间等）
---
## 最佳实践
### 1. 阻塞原因记录
当任务进入 `blocked` 状态时，应在弹窗中详细说明阻塞原因，便于团队协作排查问题。
### 2. Prompt 规范
每个任务应配置明确的 `prompt` 字段，为 AI 提供清晰的执行指令。
### 3. Leverage 复用
对于可复用的代码或组件，应在 `leverage` 字段中记录相关位置和说明。
### 4. 实时同步
多端操作时注意同步状态，避免冲突覆盖。
---
## Web 仪表板
### 相关页面
相关主题：[VSCode 扩展](#page-vscode-extension), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)
- [src/dashboard_frontend/src/modules/app/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/app/App.tsx)
- [src/dashboard_frontend/src/modules/pages](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages)
- [src/dashboard_frontend/src/modules/api/api.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)
- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)
# Web 仪表板
Web 仪表板是 spec-workflow-mcp 项目的核心可视化界面，为开发者提供图形化的项目状态监控、规范文档管理和任务追踪功能。仪表板通过 Web 界面形式呈现，允许用户在浏览器中直观地查看所有已连接项目的规格文档、审批状态和实现日志。
## 功能概述
Web 仪表板的主要功能包括：
| 功能模块 | 描述 |
|---------|------|
| 项目概览 | 显示所有已连接项目的基本统计信息 |
| 规格文档管理 | 列出活跃和已归档的规格文档 |
| 任务追踪 | 展示每个规格文档的任务进度和状态 |
| 审批管理 | 处理实现日志的审批流程 |
| 自动清理 | 配置和管理自动化清理任务 |
| 设置管理 | 仪表板全局配置和偏好设置 |
资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()
## 系统架构
### 组件结构
Web 仪表板采用前后端分离的架构设计：
```mermaid
graph TD
A[Web 浏览器] --> B[Dashboard Frontend
React SPA]
B --> C[Dashboard Backend
Express.js]
C --> D[文件系统
.spec-workflow]
E[多个项目 Workspace] --> D
B --> F[API 模块
api.tsx]
F --> C
```
前端部分位于 `src/dashboard_frontend/` 目录，使用 React 构建单页应用。主要页面组件包括：
- **App.tsx** - 根组件，管理全局状态和页面路由
- **SettingsPage.tsx** - 设置页面，管理自动化清理和偏好配置
- **TasksPage.tsx** - 任务页面，展示任务详情和进度
资料来源：[src/dashboard_frontend/src/modules/app/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/app/App.tsx)()
### 部署架构
仪表板支持多种部署方式：
```mermaid
graph LR
A[直接运行] --> B[npx --dashboard]
C[Docker 容器] --> D[docker-compose]
B --> E[http://localhost:5000]
D --> E
```
## 核心页面
### 项目概览页面
概览页面展示当前选中项目的核心统计数据：
| 统计项 | 说明 |
|-------|------|
| 活跃规格文档数 | 当前处于活跃状态的规格文档总数 |
| 已完成规格文档数 | 已完成实现的规格文档数 |
| 已归档规格文档数 | 归档的历史规格文档数 |
| 任务完成率 | 已完成任务占总任务数的比例 |
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)()
### 任务页面
任务页面详细展示每个规格文档下定义的任务列表，支持以下功能：
- **状态筛选** - 按 pending、in-progress、completed、blocked 状态筛选
- **AI 提示词** - 显示任务关联的 AI 提示词内容
- **杠杆值** - 显示任务的杠杆指数（leverage）
- **进度追踪** - 实时更新任务完成进度
```mermaid
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/TasksPage.tsx)()
### 设置页面
设置页面提供仪表板全局配置功能，包括自动化清理任务的配置：
- 管理跨所有已连接项目运行的自动化清理作业
- 配置清理频率和保留策略
- 查看清理任务执行日志
资料来源：[src/dashboard_frontend/src/modules/pages/SettingsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/SettingsPage.tsx)()
## API 接口
仪表板前端通过统一的 API 模块与后端通信：
```typescript
// 规格文档相关 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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)()
## 部署配置
### 环境变量
| 变量名 | 默认值 | 说明 |
|-------|-------|------|
| `DASHBOARD_PORT` | `5000` | 仪表板运行端口 |
| `SPEC_WORKFLOW_PATH` | `./workspace` | 项目工作区路径 |
### Docker 部署
使用 Docker Compose 部署是最推荐的方案：
```bash
cd containers
docker-compose up --build
```
自定义端口部署示例：
```bash
docker run -p 8080:8080 \
-e DASHBOARD_PORT=8080 \
-v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
spec-workflow-mcp
```
资料来源：[containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)()
### 快速启动
通过 npx 直接启动本地仪表板：
```bash
npx -y @pimzino/spec-workflow-mcp@latest --dashboard
```
仪表板启动后可通过 http://localhost:5000 访问。
> **注意**：仅需一个仪表板实例即可管理所有已连接项目，所有项目共享同一仪表板服务。
资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()
## 安全特性
Web 仪表板实现了企业级安全控制：
| 安全特性 | 描述 |
|---------|------|
| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |
| 速率限制 | 每客户端 120 请求/分钟，自动清理过期连接 |
| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者和结果 |
| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |
| CORS 保护 | 跨域资源共享控制 |
## 前端国际化
仪表板支持多语言界面，使用 i18n 模块处理翻译资源：
```typescript
// 语言切换时自动更新
t.changeLanguage(g) // g 为语言代码
_.setLanguagePreference(g)
```
语言偏好设置会被持久化保存，用户下次访问时自动应用已选语言。
## 与 VSCode 扩展的关系
Web 仪表板与 VSCode 扩展共用同一前端组件库和样式资源。编译后的静态资源位于 `vscode-extension/webview-dist/` 目录：
| 文件 | 用途 |
|-----|------|
| `index.html` | VSCode 内嵌 WebView 入口 |
| `main.js` | 编译后的主应用代码 |
| `globals.css` | 全局样式定义 |
| `comment-modal.html` | 注释弹窗页面 |
这确保了仪表板界面与 VSCode 扩展内嵌 WebView 的一致用户体验。
## 工作流程示意
```mermaid
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 扩展
### 相关页面
相关主题：[Web 仪表板](#page-dashboard), [安装配置](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [vscode-extension/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)
- [vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)
- [vscode-extension/src/extension/providers/SidebarProvider.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)
- [vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)
- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)
- [vscode-extension/src/webview/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/comment-modal.html)
- [vscode-extension/webview-dist/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)
# VSCode 扩展
## 概述
VSCode 扩展是 spec-workflow-mcp 项目的重要组成部分，为 Visual Studio Code 用户提供原生的开发体验。通过该扩展，用户可以直接在 VSCode 编辑器中访问和管理项目规格文档、审批流程以及实现日志，无需切换到独立的 Web 仪表板。
该扩展基于 VSCode Webview API 构建，采用 React 作为前端框架，实现了与核心工作流引擎的深度集成。扩展通过 MCP（Model Context Protocol）协议与后端服务通信，为用户提供实时的工作状态反馈和交互能力。
扩展的主要设计目标是降低 AI 辅助开发的工作流门槛，让开发者能够在熟悉的 IDE 环境中完成从规格创建、审批到实现追踪的完整流程。
## 架构设计
### 整体架构
VSCode 扩展采用前后端分离的架构模式，核心组件分为三个层次：
```mermaid
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)
### ApprovalEditorService（审批编辑器服务）
`ApprovalEditorService` 负责处理审批相关的数据操作和服务调用。该服务封装了所有与审批流程相关的业务逻辑，包括审批请求的创建、提交、撤销以及历史记录的查看。
服务层的设计遵循单一职责原则，将数据获取逻辑与 UI 层分离，使得组件可以专注于用户界面的渲染，而无需关心底层的数据获取机制。通过依赖注入模式，扩展可以更容易地进行单元测试和功能扩展。
资料来源：[vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)
### App.tsx（主应用组件）
`App.tsx` 是 Webview 的根组件，负责协调各个子组件的渲染和状态管理。该组件使用 React Context API 共享全局状态，使得深层嵌套的组件也能方便地访问和更新应用状态。
组件结构采用功能模块化的设计，主要区域包括：
- 概览面板：显示项目统计信息
- 规格列表：展示所有活跃和归档的规格文档
- 任务视图：呈现规格关联的任务及其进度
- 日志视图：展示实现日志条目
资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)
### LogEntryCard 组件
`LogEntryCard` 是一个专门用于展示实现日志条目的卡片组件。它将复杂的日志数据解析为用户友好的格式，支持多种内容的可视化展示。
组件支持展示的内容类型：
| 内容类型 | 描述 | 数据格式 |
|---------|------|---------|
| 文件修改 | 列出本次实现修改的文件 | 字符串数组 |
| 文件创建 | 列出本次实现创建的文件 | 字符串数组 |
| API 端点 | 记录 API 接口信息 | 对象数组 |
| 组件 | 前端组件元数据 | 对象数组 |
| 函数 | 函数定义和导出信息 | 对象数组 |
| 类 | 类定义和方法信息 | 对象数组 |
| 集成 | 前端后端集成信息 | 对象数组 |
组件采用条件渲染策略，仅当对应类型的数据存在时才显示相应的区域。这种设计减少了不必要的 DOM 操作，提升了渲染性能。
资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)
## 功能特性
### 规格文档管理
扩展提供了完整的规格文档管理界面，用户可以：
- 查看所有活跃规格的列表和状态
- 浏览已归档规格的历史记录
- 追踪每个规格关联的任务进度
- 直接在 VSCode 中编辑规格内容
规格列表采用卡片式布局，每个卡片显示规格名称、任务进度条和关键元数据。进度条使用颜色编码来区分完成状态，绿色表示已完成的任务数量，灰色表示总任务数量。
### 任务追踪系统
任务追踪功能集成在规格详情视图中，允许用户：
- 查看任务的元数据，包括目的、需求和技术杠杆点
- 展开和折叠 AI 提示内容
- 复制任务提示用于其他场景
- 追踪任务的完成状态
任务视图支持展开/折叠交互，用户可以点击任务标题来显示或隐藏详细信息。这种交互模式在处理大量任务时特别有用，可以帮助用户专注于当前关注的内容。
### 审批工作流
审批功能通过专门的编辑器服务实现，支持以下操作：
- 提交审批请求
- 批准或拒绝申请
- 批量处理多个审批请求
- 查看审批历史快照
- 比较不同版本之间的差异
审批编辑器服务封装了所有与审批相关的数据操作，包括快照生成、版本比较和批量操作。这种封装确保了 UI 层可以专注于用户交互，而无需处理复杂的业务逻辑。
### 实现日志查看
实现日志功能允许用户回顾开发过程中的所有变更：
- 按时间线查看日志条目
- 查看每次实现修改和创建的文件
- 了解 API 端点、组件、函数等代码工件
- 追踪前后端集成的数据流
日志条目卡片提供了丰富的信息展示，包括统计数据（新增/删除行数）、文件列表和各类代码工件。每个工件条目都包含名称、目的、位置等关键信息，便于开发者快速定位代码。
### 评论模态框
评论功能通过独立的模态框实现，用户可以在任何支持评论的上下文中添加评论。模态框采用独立的 HTML 页面加载，确保样式与 VSCode 主题一致。
评论模态框的样式通过 CSS 变量与 VSCode 主题系统集成：
```css
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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/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](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)
### 国际化支持
扩展内置了国际化支持，通过 `i18n.js` 模块提供多语言文本资源。用户界面中的所有可显示文本都通过翻译键引用，而非硬编码的字符串。这种设计使得扩展可以轻松支持新的语言环境。
翻译键采用层级命名规范，例如 `overview.projectTitle` 表示概览面板的项目标题文本。
### 响应式布局
Webview 界面采用响应式设计，针对不同的面板宽度提供优化的布局：
- 小屏幕：单列布局，元素垂直堆叠
- 大屏幕：双列或多列布局，充分利用空间
任务视图中的元素根据容器宽度自动调整字体大小和间距。图标、标签和内容区域都采用相对单位，确保在不同尺寸的视口中保持可读性。
## 配置与安装
### 安装方式
用户可以通过 VSCode 扩展市场安装该扩展，或者通过命令行加载本地构建的扩展包。
VSCode 配置示例：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
### 扩展配置
扩展支持通过 `package.json` 进行配置，包括：
| 配置项 | 类型 | 描述 |
|-------|------|------|
| `displayName` | 字符串 | 扩展显示名称 |
| `description` | 字符串 | 扩展功能描述 |
| `version` | 字符串 | 扩展版本号 |
| `engines` | 对象 | VSCode 引擎版本要求 |
资料来源：[vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)
## 开发指南
### 本地开发
扩展的开发环境配置遵循标准的 VSCode 扩展开发流程：
```bash
# 安装依赖
npm install
# 在开发模式下运行
npm run dev
# 构建生产版本
npm run build
```
开发模式下，扩展会自动监听源文件的变化并重新加载，无需手动重启 VSCode。
### Webview 资源管理
Webview 所需的静态资源（HTML、CSS、JavaScript）需要在 `webview-dist` 目录中预编译。开发流程中，这些资源由构建系统自动处理，但在发布前需要确保所有资源都已正确打包。
Webview 的入口点通过 `comment-modal.html` 定义，该文件引用编译后的脚本和样式资源。
### 消息协议
扩展与 Webview 之间的消息采用以下协议格式：
```typescript
interface WebviewMessage {
type: string;
payload?: any;
requestId?: string;
}
```
每条消息包含消息类型标识和可选的数据负载。对于需要响应的消息，Webview 应在处理完成后发送带有对应 `requestId` 的响应消息。
## 相关资源
- 主项目文档：[SPEC Workflow MCP 文档](../README.md)
- 开发指南：[开发文档](../docs/DEVELOPMENT.md)
- 工作流程：[工作流程指南](../docs/WORKFLOW.md)
- 工具参考：[工具参考文档](../docs/TOOLS-REFERENCE.md)
---
---
## Doramagic 踩坑日志
项目：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