{
"canonical_name": "Pimzino/spec-workflow-mcp",
"compilation_id": "pack_57bee8a1555e411086216f4142cd163f",
"created_at": "2026-05-14T07:51:06.309226+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx -y @pimzino/spec-workflow-mcp@latest` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx -y @pimzino/spec-workflow-mcp@latest",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_438219a89cd843ab91ac6cb00ab33fd2"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_c179faa2023de3d08ae54c2bdd0f94c9",
"canonical_name": "Pimzino/spec-workflow-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Pimzino/spec-workflow-mcp",
"slug": "spec-workflow-mcp",
"source_packet_id": "phit_e52fd36c93ed408a8bcb2706f55c531b",
"source_validation_id": "dval_383337b344f24a1eb3768d462230fcb5"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 344,
"github_stars": 4170,
"one_liner_en": "Spec Workflow MCP",
"one_liner_zh": "Spec Workflow MCP",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, test, git"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "spec-workflow-mcp",
"title_zh": "spec-workflow-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e52fd36c93ed408a8bcb2706f55c531b",
"page_model": {
"artifacts": {
"artifact_slug": "spec-workflow-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx -y @pimzino/spec-workflow-mcp@latest",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/Pimzino/spec-workflow-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Spec Workflow MCP"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Bug Report for spec-workflow-mcp",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"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."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 22,
"forks": 344,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 4170
},
"source_url": "https://github.com/Pimzino/spec-workflow-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Spec Workflow MCP",
"title": "spec-workflow-mcp 能力包",
"trial_prompt": "# spec-workflow-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 spec-workflow-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Spec Workflow MCP 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-installation：安装配置。围绕“安装配置”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-spec-workflow：规格工作流程。围绕“规格工作流程”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-installation\n输入：用户提供的“安装配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-spec-workflow\n输入：用户提供的“规格工作流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-installation：Step 3 必须围绕“安装配置”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-spec-workflow：Step 5 必须围绕“规格工作流程”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Pimzino/spec-workflow-mcp\n- https://github.com/Pimzino/spec-workflow-mcp#readme\n- README.md\n- src/index.ts\n- package.json\n- docs/USER-GUIDE.md\n- docs/PROMPTING-GUIDE.md\n- containers/example.mcp.json\n- docs/CONFIGURATION.md\n- src/config.ts\n- src/core/global-dir.ts\n- src/server.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 spec-workflow-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Bug]: approval categoryName path traversal writes outside approvals dir（https://github.com/Pimzino/spec-workflow-mcp/issues/220）；github/github_issue: [Bug]: Bug Report for spec-workflow-mcp（https://github.com/Pimzino/spec-workflow-mcp/issues/218）；github/github_issue: [Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads（https://github.com/Pimzino/spec-workflow-mcp/issues/201）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: approval categoryName path traversal writes outside approvals dir",
"url": "https://github.com/Pimzino/spec-workflow-mcp/issues/220"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Bug Report for spec-workflow-mcp",
"url": "https://github.com/Pimzino/spec-workflow-mcp/issues/218"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads",
"url": "https://github.com/Pimzino/spec-workflow-mcp/issues/201"
}
],
"status": "已收录 3 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Spec Workflow MCP",
"effort": "安装已验证",
"forks": 344,
"icon": "code",
"name": "spec-workflow-mcp 能力包",
"risk": "可发布",
"slug": "spec-workflow-mcp",
"stars": 4170,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Pimzino/spec-workflow-mcp 项目说明书\n\n生成时间：2026-05-14 07:49:06 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [安装配置](#page-installation)\n- [系统架构](#page-architecture)\n- [文件结构](#page-file-structure)\n- [规格工作流程](#page-spec-workflow)\n- [审批系统](#page-approval-system)\n- [任务管理](#page-task-management)\n- [Web 仪表板](#page-dashboard)\n- [VSCode 扩展](#page-vscode-extension)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n- [vscode-extension/src/webview/index.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n- [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)\n \n\n# 项目概述\n\n## 简介\n\nspec-workflow-mcp 是一个基于 Model Context Protocol (MCP) 的开发工作流管理系统，旨在为 AI 辅助软件开发提供规范化的项目管理和协作框架。该项目通过 MCP 协议与各种 AI 工具（如 Cursor、Claude Desktop、VSCode 等）集成，帮助开发团队在 AI 驱动的开发环境中维护一致的规范、追踪任务进度、管理审批流程，并记录实现日志。\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 核心功能\n\n### MCP 协议集成\n\n作为 MCP 服务器运行，spec-workflow-mcp 提供了一套完整的工具集，使 AI 助手能够与本地项目进行深度交互。开发者可以通过简单的配置将项目目录与各种 AI 客户端连接，从而获得规范感知的工作流支持。\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### 规范文档管理\n\n项目支持创建和维护以下核心规范文档：\n\n| 文档类型 | 描述 | 位置 |\n|---------|------|------|\n| Specs | 软件规格说明文档 | `.spec-workflow/specs/` |\n| Steering | 方向指引文档（product.md、tech.md、structure.md） | `.spec-workflow/steering/` |\n| Templates | 文档模板 | `.spec-workflow/templates/` |\n| Approvals | 审批记录 | `.spec-workflow/approvals/` |\n| Archive | 归档文档 | `.spec-workflow/archive/` |\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n### 实现日志追踪\n\n系统会自动记录 AI 生成的代码变更，包括修改的文件、创建的文件、代码统计（新增/删除行数）以及生成的各类产物（API 端点、组件、函数、类、集成点等）。这一功能确保了开发过程的可追溯性，便于团队审查和回溯。\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## 技术架构\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[AI 客户端
Cursor/Claude Desktop/VSCode] -->|MCP 协议| B[spec-workflow-mcp
MCP Server]\n B --> C[规范存储层
.spec-workflow 目录]\n B --> D[Web Dashboard
端口 5000]\n B --> E[VSCode 扩展
内嵌 Webview]\n \n C --> F[Specs 文档]\n C --> G[Steering 文档]\n C --> H[Approvals 审批]\n C --> I[Archive 归档]\n C --> J[实现日志]\n \n D --> K[React 前端]\n E --> L[React Webview]\n```\n\n### 前端技术栈\n\n项目采用现代化的前端技术构建用户界面：\n\n- **React**: 核心 UI 框架\n- **TypeScript**: 类型安全保证\n- **Tailwind CSS**: 样式解决方案\n- **i18n 国际化**: 支持多语言切换\n\nVSCode 扩展的 Webview 使用独立的模块化架构，包含主入口文件、i18n 模块和全局样式资源。\n\n资料来源：[vscode-extension/src/webview/index.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n\n### REST API 架构\n\nDashboard 后端提供丰富的 REST API 端点，主要包括：\n\n| API 类别 | 端点模式 | 功能 |\n|---------|---------|------|\n| Specs | `GET/PUT /specs/:name` | 获取/更新规格文档 |\n| Tasks | `GET/PUT /specs/:name/tasks/:id/status` | 任务状态管理 |\n| Approvals | `POST /approvals/:id/:action` | 审批操作 |\n| Batch | `POST /approvals/batch/:action` | 批量审批 |\n| Snapshots | `GET /approvals/:id/snapshots/:version` | 版本快照 |\n\n资料来源：[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)\n\n## 部署方式\n\n### 标准部署\n\n项目支持通过 npx 直接运行，配置方式因客户端而异：\n\n**Cursor 配置示例：**\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n**Claude Desktop 配置：**\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Docker 容器部署\n\n项目提供完整的 Docker 支持，适合隔离部署场景：\n\n```bash\n# 使用 Docker Compose（推荐）\ncd containers\ndocker-compose up --build\n\n# 或使用 Docker CLI\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\nDashboard 访问地址：`http://localhost:5000`\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 安全特性\n\nspec-workflow-mcp 实现了企业级的安全控制措施：\n\n| 安全特性 | 描述 |\n|---------|------|\n| 本地绑定 | 默认绑定 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、动作和结果 |\n| 安全响应头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 项目结构\n\n### 典型项目目录布局\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档的规范文档\n specs/ # 活动规格文档\n steering/ # 方向指引文档\n templates/ # 文档模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n### 开发环境\n\n```bash\n# 安装依赖\nnpm install\n\n# 编译项目\nnpm run build\n\n# 开发模式运行\nnpm run dev\n```\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n## 许可协议\n\n本项目采用 GPL-3.0 开源许可证发布。\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [安装配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [docs/USER-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/USER-GUIDE.md)\n- [docs/PROMPTING-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/PROMPTING-GUIDE.md)\n- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)\n- [containers/example.mcp.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/example.mcp.json)\n \n\n# 快速开始\n\n本页面提供 spec-workflow-mcp 项目的快速上手指南，帮助用户在最短时间内完成环境配置并开始使用规范驱动的工作流程。\n\n## 概述\n\nspec-workflow-mcp 是一个基于规范驱动（Specification-Driven）的开发工作流程管理工具，通过 MCP（Model Context Protocol）协议与 AI 工具集成，帮助开发团队在 AI 辅助环境下高效管理项目开发流程。\n\n快速开始指南旨在为用户提供：\n\n- 环境配置的最简路径\n- 与 AI 工具集成的标准方式\n- 界面选择与启动方法\n- 首个项目规范文档的创建流程\n\n资料来源：[README.md:1-50]()\n\n## 环境要求\n\n### 系统要求\n\n| 要求类型 | 最低版本 | 推荐版本 |\n|---------|---------|---------|\n| Node.js | 18.x | 20.x LTS |\n| npm | 9.x | 10.x |\n| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | macOS 14+ / Ubuntu 22.04+ / Windows 11 |\n\n### AI 工具兼容性\n\nspec-workflow-mcp 通过 MCP 协议与以下 AI 工具集成：\n\n- Claude Desktop\n- Cursor\n- VS Code (通过扩展)\n- 其他支持 MCP 协议的工具\n\n资料来源：[containers/example.mcp.json:1-30]()\n\n## 安装方式\n\n### 方式一：MCP 配置集成（推荐）\n\n将 spec-workflow-mcp 添加到 AI 工具的 MCP 配置中：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n> **注意**：将 `/path/to/your/project` 替换为实际项目路径。\n\n### 方式二：全局安装\n\n```bash\nnpm install -g @pimzino/spec-workflow-mcp\n```\n\n### 方式三：项目本地安装\n\n```bash\nnpm install @pimzino/spec-workflow-mcp\n```\n\n资料来源：[README.md:15-35]()\n\n## 界面选择\n\n根据使用场景，spec-workflow-mcp 提供两种界面选项：\n\n### Web 仪表盘\n\n适用于 CLI 用户和跨项目管理者。\n\n启动命令：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表盘访问地址：`http://localhost:5000`\n\n### VSCode 扩展\n\n适用于 VSCode 用户，提供无缝的编辑体验。\n\n安装方式：在 VSCode 扩展市场搜索 \"Spec Workflow\" 并安装。\n\n资料来源：[docs/INTERFACES.md:1-50]()\n\n## 项目初始化\n\n### 自动初始化\n\n首次使用 MCP 工具时，系统会自动创建 `.spec-workflow` 目录结构：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档规范存储\n specs/ # 规范文档存储\n steering/ # 指导文档存储\n templates/ # 规范模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置文件示例\n```\n\n### 配置文件\n\n复制并编辑配置文件：\n\n```bash\ncp .spec-workflow/config.example.toml .spec-workflow/config.toml\n```\n\n主要配置项：\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| `dashboard.port` | 仪表盘端口 | 5000 |\n| `dashboard.host` | 仪表盘主机 | localhost |\n| `specs.directory` | 规范文档目录 | specs |\n| `archive.enabled` | 是否启用归档 | true |\n\n资料来源：[docs/USER-GUIDE.md:10-80]()\n\n## 工作流程概览\n\n### 标准开发流程\n\n```mermaid\ngraph TD\n A[创建规范文档] --> B[定义任务清单]\n B --> C[AI 执行任务]\n C --> D{任务验证}\n D -->|通过| E[更新规范进度]\n D -->|失败| F[修订或重新执行]\n E --> G{所有任务完成?}\n G -->|否| B\n G -->|是| H[归档规范]\n F --> C\n```\n\n### 规范文档结构\n\n每个规范文档包含以下核心部分：\n\n1. **元数据**：名称、版本、状态\n2. **概述**：功能描述和目标\n3. **任务清单**：具体实现任务及状态\n4. **验收标准**：完成条件定义\n\n资料来源：[docs/PROMPTING-GUIDE.md:1-60]()\n\n## 首次使用指南\n\n### 步骤一：创建首个规范\n\n在 AI 对话中描述要实现的功能，系统将自动生成规范文档框架：\n\n```\n请帮我创建一个新的规范文档，用于实现用户认证功能。\n```\n\n### 步骤二：审查规范\n\n使用仪表盘或 VSCode 扩展查看生成的规范文档，确认任务分解正确。\n\n### 步骤三：执行任务\n\n按照任务清单逐项执行，AI 将根据规范要求辅助代码实现。\n\n### 步骤四：跟踪进度\n\n通过仪表盘的任务面板实时查看进度更新。\n\n### 步骤五：归档完成\n\n规范所有任务完成后，将规范移至归档目录保存。\n\n资料来源：[docs/USER-GUIDE.md:80-150]()\n\n## 常见问题\n\n### 问题一：仪表盘无法启动\n\n**解决方案**：\n\n```bash\n# 检查端口占用\nlsof -i :5000\n\n# 使用其他端口\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 5001\n```\n\n### 问题二：MCP 连接失败\n\n**解决方案**：\n\n1. 确认 Node.js 版本 >= 18.x\n2. 检查 MCP 配置文件语法\n3. 重启 AI 工具\n\n### 问题三：规范文档未自动创建\n\n**解决方案**：手动创建 `.spec-workflow` 目录结构，确保 `specs/` 子目录存在。\n\n资料来源：[docs/USER-GUIDE.md:150-200]()\n\n## 下一步\n\n完成快速开始后，建议继续阅读以下文档：\n\n- [用户指南](docs/USER-GUIDE.md) - 深入了解所有功能\n- [提示工程指南](docs/PROMPTING-GUIDE.md) - 优化 AI 交互\n- [接口指南](docs/INTERFACES.md) - 仪表盘和扩展详细说明\n- [开发指南](docs/DEVELOPMENT.md) - 参与项目开发\n\n---\n\n\n\n## 安装配置\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [README.ko.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n- [docs/CONFIGURATION.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md)\n- [src/config.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/config.ts)\n \n\n# 安装配置\n\n## 概述\n\nspec-workflow-mcp 是一个基于 MCP（Model Context Protocol）协议的 AI 辅助开发工作流工具。它通过标准化规范（spec）驱动的方式，帮助开发团队协调 AI 工具与人类开发者之间的协作。安装配置是整个系统的入口点，正确配置 MCP 服务器是将 spec-workflow 集成到现有开发环境的关键步骤。\n\n该工具支持多种主流 AI 编程工具的集成，包括 Claude Desktop、Claude Code CLI、Cline、Cursor、Continue 以及 VSCode 扩展程序。配置方式根据不同的客户端略有差异，但核心概念相同：启动 MCP 服务器并指向项目目录。\n\n## 项目目录结构\n\nspec-workflow-mcp 在项目根目录创建一个 `.spec-workflow` 隐藏目录，用于存储所有配置、规范文档和历史记录。\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档的规范文档\n specs/ # 规范文档主目录\n steering/ # 引导文件目录\n templates/ # 内置模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置文件模板\n```\n\n资料来源：[README.md:45-54]()\n\n`.spec-workflow` 目录结构设计遵循单一职责原则，每个子目录管理特定类型的数据。规范文档存储在 `specs/` 中，审批流程相关文件存储在 `approvals/`，而 `archive/` 用于存放已完成的规范文档以便追溯。\n\n## MCP 服务器配置\n\n### 核心配置参数\n\nMCP 服务器通过 `mcpServers` 配置节进行定义，主要参数如下：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| command | string | 是 | 执行命令，通常为 `npx` |\n| args | array | 是 | 命令参数数组 |\n| 路径参数 | string | 是 | 目标项目目录的绝对或相对路径 |\n\n标准的 npx 启动命令格式为：\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n}\n```\n\n资料来源：[README.md:18-24]()\n\n参数说明：\n- `-y` 标志用于跳过 npm 安装确认提示，实现更流畅的自动化安装流程\n- `@pimzino/spec-workflow-mcp@latest` 指定包名称和版本号\n- 最后一个参数是项目目录的绝对路径或相对路径\n\n### 各客户端配置方式\n\n#### Claude Desktop\n\nClaude Desktop 的配置文件位于 `claude_desktop_config.json`，配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n> **重要提示**：在启动 MCP 服务器之前，需要单独运行 `--dashboard` 命令启动仪表板。\n\n资料来源：[README.md:75-89]()\n\n#### Claude Code CLI\n\n对于 Claude Code CLI，需要使用 `mcp add` 命令添加服务器：\n\n```bash\nclaude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project\n```\n\n**关键要点**：\n- `-y` 标志用于跳过 npm 提示，确保自动化安装\n- `--` 分隔符确保路径参数被传递给 spec-workflow 脚本而非 npx\n\nWindows 用户如果上述命令不生效，可以使用替代方案：\n\n```bash\nclaude mcp add spec-workflow cmd.exe /c \"npx @pimzino/spec-workflow-mcp@latest /path/to/your/project\"\n```\n\n资料来源：[README.md:31-47]()\n\n#### Cline / Claude Dev\n\n在 Cline 或 Claude Dev 中添加 MCP 服务器配置：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:95-103]()\n\n#### Continue IDE Extension\n\nContinue 配置使用相同的 JSON 格式：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:107-115]()\n\n#### Cursor IDE\n\nCursor 的配置需添加到 `settings.json` 中：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:119-127]()\n\n#### Codex\n\nCodex 使用 TOML 格式配置文件，位于 `~/.codex/config.toml`：\n\n```toml\n[mcp_servers.spec-workflow]\ncommand = \"npx\"\nargs = [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n```\n\n资料来源：[README.md:140-144]()\n\n## 仪表板配置\n\n### Web 仪表板\n\nWeb 仪表板是 CLI 用户的推荐接口，启动命令：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表板默认运行在 `http://localhost:5000`。\n\n> **重要说明**：只需要一个仪表板实例，所有项目都连接到同一个仪表板。\n\n资料来源：[README.ko.md:22-29]()\n\n### Docker 部署\n\n对于隔离部署环境，spec-workflow-mcp 支持 Docker 容器化运行：\n\n#### 使用 Docker Compose（推荐方式）\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n#### 使用 Docker CLI\n\n```bash\n# 构建镜像\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\n\n# 运行容器\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\nDocker 部署会将容器内的 `/workspace/.spec-workflow` 目录映射到宿主机的 `./workspace/.spec-workflow`，确保数据持久化。\n\n资料来源：[README.md:146-157]()\n\n## 安全配置\n\n### 安全控制特性\n\nspec-workflow-mcp 包含企业级安全功能，适用于企业环境：\n\n| 安全特性 | 说明 |\n|---------|------|\n| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、操作和结果 |\n| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n资料来源：[README.md:164-174]()\n\n### 本地绑定\n\n默认情况下，Web 仪表板仅监听 `127.0.0.1`（localhost），这确保了：\n- 只有本机浏览器可以访问仪表板\n- 外部网络无法连接到服务\n- 适用于开发和测试环境\n\n### 速率限制\n\n系统实现了请求速率限制机制：\n- 每分钟每客户端 120 个请求\n- 超过限制的请求会被拒绝\n- 自动清理过期记录以释放资源\n\n## 本地开发配置\n\n### 安装依赖\n\n```bash\nnpm install\n```\n\n资料来源：[README.md:60]()\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist/` 目录。\n\n### 开发模式运行\n\n```bash\nnpm run dev\n```\n\n开发模式提供热重载功能，代码修改后自动重新编译和重启服务。\n\n资料来源：[README.md:61-67]()\n\n## 配置验证\n\n### 验证步骤\n\n1. **检查 MCP 服务器状态**：在对应的 AI 工具中确认 MCP 服务器已正确加载\n2. **验证仪表板连接**：访问 `http://localhost:5000` 确认 Web 仪表板可访问\n3. **检查项目目录**：确认 `.spec-workflow` 目录已在项目根目录创建\n4. **测试规范创建**：尝试创建一个新的规范文档验证写入权限\n\n### 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|---------|---------|\n| MCP 服务器无法启动 | npx 未安装或版本过旧 | 安装最新版本的 Node.js 和 npm |\n| 仪表板无法访问 | 端口 5000 被占用 | 更换端口或终止占用进程 |\n| 权限错误 | 项目目录不可写 | 检查目录权限设置 |\n| 路径解析失败 | 相对路径未正确解析 | 使用绝对路径替代相对路径 |\n\n## 扩展配置\n\n### VSCode 扩展配置\n\nVSCode 用户可以使用专门的扩展程序，获得更好的集成体验：\n\n```bash\n# 从 VSCode Marketplace 安装扩展\n# 然后在扩展设置中配置项目路径\n```\n\nVSCode 扩展提供了内联的用户界面，无需单独启动 Web 仪表板。\n\n资料来源：[README.ko.md:31-35]()\n\n### 多项目配置\n\nspec-workflow-mcp 支持同时管理多个项目：\n\n1. 每个项目需要独立的 `.spec-workflow` 目录\n2. 所有项目可以共享同一个仪表板实例\n3. 在 MCP 配置中使用不同的路径参数指向各项目\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow-project-a\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project-a\"]\n },\n \"spec-workflow-project-b\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project-b\"]\n }\n }\n}\n```\n\n## 配置架构图\n\n```mermaid\ngraph TD\n A[用户开发环境] --> B[AI 编程工具]\n B --> C[MCP 客户端]\n C --> D[MCP 服务器]\n D --> E[spec-workflow-mcp 核心]\n E --> F[.spec-workflow 目录]\n E --> G[Web 仪表板]\n E --> H[文件系统]\n \n F --> I[specs/ 规范文档]\n F --> J[approvals/ 审批]\n F --> K[archive/ 归档]\n F --> L[steering/ 引导]\n F --> M[templates/ 模板]\n \n G --> N[localhost:5000]\n \n style A fill:#e1f5fe\n style G fill:#fff3e0\n style F fill:#f3e5f5\n```\n\n## 下一步\n\n配置完成后，建议阅读以下文档：\n\n- [工作流指南](docs/WORKFLOW.md) - 开发工作流和最佳实践\n- [接口指南](docs/INTERFACES.md) - 仪表板和 VSCode 扩展详情\n- [工具参考](docs/TOOLS-REFERENCE.md) - 完整工具文档\n- [故障排除](docs/TROUBLESHOOTING.md) - 常见问题及解决方案\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[文件结构](#page-file-structure), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/server.ts)\n- [src/dashboard/multi-server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/multi-server.ts)\n- [src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n- [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)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [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)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n \n\n# 系统架构\n\n## 概述\n\nSpec-Workflow-MCP 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统，旨在为 AI 驱动的软件开发提供结构化的规格管理和实现跟踪能力。该系统采用模块化架构设计，支持多个项目连接至单一仪表板实例，实现跨项目的规格、任务和实施日志的统一管理。\n\n系统的核心设计理念是将 AI 开发过程的结构化，通过规格文档（Spec）、任务拆解、实施日志等机制，确保 AI 生成的代码与预期规格保持一致。\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n VSCode[VSCode 扩展]\n CLI[CLI 工具]\n 其他AI[其他 MCP 客户端]\n end\n \n subgraph \"核心服务层\"\n MCP[MCP 服务器]\n WS[WebSocket 服务]\n API[REST API 服务]\n end\n \n subgraph \"仪表板层\"\n Dashboard[Web 仪表板]\n Frontend[React 前端]\n end\n \n subgraph \"数据层\"\n FS[文件系统存储]\n LogDB[实施日志]\n Config[项目配置]\n end\n \n VSCode --> MCP\n CLI --> MCP\n 其他AI --> MCP\n \n MCP --> WS\n MCP --> FS\n MCP --> LogDB\n \n WS <--> Dashboard\n Dashboard --> Frontend\n \n Dashboard --> Config\n Frontend --> Config\n```\n\n## 核心组件\n\n### MCP 服务器\n\nMCP 服务器是系统的核心入口点，负责处理来自各种 AI 工具的请求。服务器启动时加载项目配置，建立文件系统监控，并注册 MCP 工具集。\n\n| 组件 | 说明 | 端口/路径 |\n|------|------|----------|\n| MCP Server | 处理 AI 工具请求的核心服务器 | 标准输入/输出 |\n| Dashboard Server | Web 仪表板服务器 | 5000 |\n| WebSocket Server | 实时通信服务 | 与仪表板共享端口 |\n\n服务器支持两种运行模式：独立 MCP 模式和仪表板模式。运行 MCP 模式时，服务器通过标准输入输出与 AI 客户端通信；运行仪表板模式时，启动 Web 服务器提供可视化界面。\n\n### 多服务器管理\n\n系统采用多服务器架构，允许连接多个项目至同一个仪表板实例：\n\n```mermaid\ngraph LR\n subgraph \"Dashboard Instance\"\n DM[仪表板管理器]\n CM[连接管理器]\n PM[项目管理器]\n end\n \n P1[项目 1]\n P2[项目 2]\n P3[项目 N]\n \n DM --> CM\n CM --> PM\n \n P1 <--> PM\n P2 <--> PM\n P3 <--> PM\n```\n\n每个连接的项目维护独立的配置和状态，仪表板通过项目标识符进行区分和路由。\n\n### 文件系统监控\n\n文件监控模块负责实时跟踪 `.spec-workflow` 目录下的变更：\n\n资料来源：[src/dashboard/watcher.ts]()\n\n| 功能 | 描述 |\n|------|------|\n| 规格监控 | 监听 specs 目录下的规格文件变更 |\n| 任务跟踪 | 监控任务状态文件的变化 |\n| 实施日志 | 记录文件创建和修改事件 |\n| 归档检测 | 检测已归档规格的状态变化 |\n\n文件变更通过 WebSocket 实时推送至前端界面，实现多客户端的状态同步。\n\n## 前端架构\n\n### Web 仪表板\n\nWeb 仪表板基于 React 构建，提供完整的项目管理和监控界面：\n\n```mermaid\ngraph TD\n App[主应用]\n Overview[概览页]\n Tasks[任务页]\n Logs[日志页]\n Settings[设置页]\n \n App --> Overview\n App --> Tasks\n App --> Logs\n App --> Settings\n \n Overview --> WS[WebSocket 连接]\n Tasks --> WS\n Logs --> WS\n \n WS --> Provider[WebSocket Provider]\n```\n\n#### 页面模块\n\n| 页面 | 功能 |\n|------|------|\n| 概览页 | 显示项目统计、规格完成度、任务进度 |\n| 任务页 | 看板和列表两种视图，支持状态筛选和排序 |\n| 日志页 | 展示实施日志，包括文件变更、统计信息、工件记录 |\n| 设置页 | 管理自动清理任务、API 端点配置 |\n\n### WebSocket 通信\n\nWebSocket 模块负责客户端与服务端之间的实时双向通信：\n\n资料来源：[src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx]()\n\n```mermaid\nsequenceDiagram\n participant Client as 前端客户端\n participant WS as WebSocket Provider\n participant Server as Dashboard Server\n \n Client->>WS: 建立连接\n WS->>Server: 初始化 WebSocket 连接\n \n Server->>WS: 连接状态更新\n WS->>Client: 状态同步\n \n loop 文件变更监控\n Server->>WS: 发送变更事件\n WS->>Client: 广播更新\n end\n \n Client->>WS: 发送操作请求\n WS->>Server: 转发请求\n```\n\nWebSocket Provider 维护连接状态，处理重连逻辑，并向下游组件提供状态更新上下文。\n\n### VSCode 扩展\n\nVSCode 扩展提供嵌入式开发体验：\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n```\n┌─────────────────────────────────────┐\n│ VSCode Extension │\n├─────────────────────────────────────┤\n│ Webview Container │\n│ ┌───────────────────────────────┐ │\n│ │ React Application │ │\n│ │ ├─ Overview Panel │ │\n│ │ ├─ Task List │ │\n│ │ ├─ Implementation Logs │ │\n│ │ └─ Settings │ │\n│ └───────────────────────────────┘ │\n├─────────────────────────────────────┤\n│ VSCode API Integration │\n│ ├─ File System Watcher │ │\n│ ├─ Status Bar Updates │ │\n│ └─ Command Palette │ │\n└─────────────────────────────────────┘\n```\n\n扩展通过 WebView 与主进程通信，利用 VSCode 原生 API 实现文件系统监控和 UI 集成。\n\n## 数据模型\n\n### 项目结构\n\n```\n项目根目录/\n .spec-workflow/\n approvals/ # 审批文件\n archive/ # 已归档规格\n specs/ # 规格文档\n steering/ # 方向性文档\n templates/ # 模板文件\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n### 实施日志条目\n\n系统记录每次规格实施的完整信息：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| timestamp | Date | 执行时间戳 |\n| specification | string | 关联规格 |\n| status | string | 执行状态 |\n| filesModified | string[] | 修改的文件列表 |\n| filesCreated | string[] | 创建的文件列表 |\n| statistics | object | 代码统计（行数增删等） |\n| artifacts | object | 工件记录 |\n\n### 工件类型\n\n| 类型 | 说明 |\n|------|------|\n| apiEndpoints | API 端点定义 |\n| components | UI 组件 |\n| functions | 函数定义 |\n| classes | 类定义 |\n| integrations | 集成点 |\n\n## 安全机制\n\n系统实现了企业级安全特性：\n\n```mermaid\ngraph LR\n subgraph \"安全层\"\n RATE[速率限制]\n CORS[CORS 保护]\n HEAD[安全头]\n LOG[审计日志]\n end\n \n Request[请求] --> RATE\n RATE --> CORS\n CORS --> HEAD\n HEAD --> LOG\n```\n\n| 安全功能 | 说明 |\n|----------|------|\n| 本地绑定 | 默认绑定至 127.0.0.1，防止网络暴露 |\n| 速率限制 | 每客户端 120 请求/分钟，自动清理 |\n| 审计日志 | 结构化 JSON 日志，记录时间戳、操作者、动作和结果 |\n| 安全头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| CORS 保护 | 限制跨域访问 |\n\n## 部署模式\n\n### Docker 部署\n\n系统支持 Docker 容器化部署：\n\n```dockerfile\n# 容器结构\n┌─────────────────────────────┐\n│ spec-workflow-mcp │\n├─────────────────────────────┤\n│ Node.js Runtime │\n│ ├─ Dashboard Server │\n│ ├─ WebSocket Server │\n│ └─ MCP Protocol Handler │\n└─────────────────────────────┘\n```\n\n容器部署命令：\n\n```bash\n# Docker Compose 方式\ncd containers\ndocker-compose up --build\n\n# Docker CLI 方式\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\n### MCP 客户端集成\n\n系统作为 MCP 服务器运行，支持多种 AI 工具客户端：\n\n资料来源：[README.md]()\n\n| 客户端 | 配置方式 |\n|--------|----------|\n| Claude Desktop | settings.json |\n| Cline/Claude Dev | MCP 配置 |\n| Continue | MCP 配置 |\n| Cursor IDE | settings.json |\n| Codex | config.toml |\n\n## 实时同步机制\n\n```mermaid\ngraph TB\n subgraph \"变更源\"\n File[文件变更]\n User[用户操作]\n AI[AI 执行]\n end\n \n File --> Watcher[文件系统监控]\n User --> API[API 调用]\n AI --> MCP[MCP 执行]\n \n Watcher --> Event[变更事件]\n API --> Event\n MCP --> Event\n \n Event --> Broadcast[广播至所有客户端]\n \n Broadcast --> WS1[Dashboard 1]\n Broadcast --> WS2[Dashboard 2]\n Broadcast --> WS3[VSCode Extension]\n```\n\n所有连接至同一仪表板实例的客户端共享状态视图，确保多端操作的一致性。\n\n---\n\n\n\n## 文件结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [规格工作流程](#page-spec-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n- [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)\n- [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)\n- [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)\n \n\n# 文件结构\n\n## 概述\n\n`spec-workflow-mcp` 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统。该项目采用**前后端分离架构**，包含核心业务逻辑层、仪表板前端以及 VSCode 扩展三大部分。文件结构设计遵循模块化原则，将核心功能、界面展示和编辑器扩展清晰地分离在不同的目录中。 资料来源：[README.fr.md:1-10]()\n\n## 顶层目录结构\n\n```\nspec-workflow-mcp/\n├── .spec-workflow/ # 项目规范配置目录\n├── src/ # 核心业务逻辑\n├── vscode-extension/ # VSCode 扩展\n├── vscode-extension/\n│ └── webview-dist/ # 构建产物\n├── src/dashboard_frontend/ # 仪表板前端\n└── docs/ # 文档\n```\n\n## `.spec-workflow/` 规范目录结构\n\n`.spec-workflow/` 目录是项目的工作空间根目录，包含了规格驱动的所有配置文件和文档模板。 资料来源：[README.fr.md:25-35]()\n\n| 目录名 | 用途 |\n|--------|------|\n| `approvals/` | 存放规格审批文件 |\n| `archive/` | 归档已完成或废弃的规格 |\n| `specs/` | 存放活跃的规格文档 |\n| `steering/` | 存放指导性文档 |\n| `templates/` | 系统内置模板 |\n| `user-templates/` | 用户自定义模板 |\n| `config.example.toml` | 配置文件示例 |\n\n## 核心业务逻辑层 (`src/`)\n\n`src/` 目录包含了系统的主要业务逻辑，采用 TypeScript 实现。\n\n### 核心模块 (`src/core/`)\n\n核心模块包含系统的基础功能组件：\n\n| 文件 | 职责 |\n|------|------|\n| `implementation-log-migrator.ts` | 实现日志的数据迁移和格式化转换 |\n\n### 仪表板模块 (`src/dashboard/`)\n\n仪表板模块负责实现日志管理和数据展示功能：\n\n| 文件 | 职责 |\n|------|------|\n| `implementation-log-manager.ts` | 实现日志的添加、查询、格式化和导出功能 |\n\n### Markdown 模板 (`src/markdown/templates/`)\n\n模板系统用于生成标准化的项目文档：\n\n| 模板文件 | 用途 |\n|----------|------|\n| `design-template.md` | 设计文档模板 |\n| `requirements-template.md` | 需求文档模板 |\n| `tasks-template.md` | 任务清单模板 |\n\n## 仪表板前端 (`src/dashboard_frontend/`)\n\n仪表板前端是一个独立的 Web 应用，提供图形化界面来管理规格工作流。\n\n### 页面模块 (`src/dashboard_frontend/src/modules/pages/`)\n\n| 页面文件 | 功能描述 |\n|----------|----------|\n| `TasksPage.tsx` | 任务管理页面，包含进度跟踪和任务列表展示 |\n| `LogsPage.tsx` | 实现日志页面，展示文件变更、创建和统计数据 |\n| `SteeringPage.tsx` | 指导文档页面，提供项目文档导航 |\n| `JobExecutionHistory.tsx` | 作业执行历史页面，记录批处理任务执行情况 |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[用户界面] --> B[任务页面 TasksPage]\n A --> C[日志页面 LogsPage]\n A --> D[指导页面 SteeringPage]\n A --> E[执行历史 JobExecutionHistory]\n B --> F[核心服务层]\n C --> F\n D --> F\n E --> F\n F --> G[spec-workflow 核心]\n G --> H[文件系统]\n```\n\n## VSCode 扩展 (`vscode-extension/`)\n\nVSCode 扩展为开发者提供了在编辑器内直接访问规格工作流的能力。\n\n### Web 视图源文件 (`vscode-extension/src/webview/`)\n\n| 文件/目录 | 用途 |\n|-----------|------|\n| `App.tsx` | 主应用组件，包含项目概览和任务列表 |\n| `index.html` | Web 视图入口 HTML |\n| `comment-modal.html` | 注释模态框 HTML |\n| `components/LogEntryCard.tsx` | 日志条目卡片组件 |\n\n### Web 视图组件关系\n\n```mermaid\ngraph LR\n A[index.html] --> B[main.tsx]\n A --> C[App.tsx]\n B --> D[React 应用挂载]\n C --> E[LogEntryCard]\n C --> F[任务列表]\n C --> G[项目统计]\n E --> H[ArtifactSection]\n```\n\n### 构建产物 (`vscode-extension/webview-dist/`)\n\n构建后的静态资源用于 VSCode 扩展的实际运行：\n\n| 文件 | 对应源文件 |\n|------|------------|\n| `index.html` | 编译后的主入口 |\n| `comment-modal.html` | 编译后的注释模态框 |\n| `main.js` | 打包后的主应用代码 |\n| `comment-modal.js` | 打包后的模态框代码 |\n| `globals.css` | 全局样式 |\n| `i18n.js` | 国际化资源 |\n\n## 实现日志数据结构\n\n系统通过 `ImplementationLogEntry` 接口管理实现日志，包含以下关键字段： 资料来源：[src/dashboard/implementation-log-manager.ts:1-20]()\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 日志唯一标识符 |\n| `timestamp` | Date | 创建时间戳 |\n| `summary` | string | 实现摘要 |\n| `statistics` | object | 代码统计信息（文件数、行数变更等） |\n| `filesModified` | string[] | 修改的文件列表 |\n| `filesCreated` | string[] | 创建的文件列表 |\n| `artifacts` | object | 生成的代码构件 |\n\n### Artifacts 子结构\n\n`artifacts` 对象包含多种代码构件类型的记录： 资料来源：[src/dashboard/implementation-log-manager.ts:30-60]()\n\n| 构件类型 | 字段说明 |\n|----------|----------|\n| `apiEndpoints` | API 端点：method、path、purpose、location、requestFormat、responseFormat |\n| `components` | 组件：name、type、purpose、location、props、exports |\n| `functions` | 函数：name、purpose、location、signature、isExported |\n| `classes` | 类：name、purpose、location、methods、isExported |\n| `integrations` | 集成：description、frontendComponent、backendEndpoint、dataFlow |\n\n## 前端组件架构\n\n### 任务页面组件 (`TasksPage.tsx`)\n\n任务页面负责展示和管理规格任务，包含以下核心功能： 资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx:1-50]()\n\n- **进度追踪**：显示任务完成百分比和总体进度条\n- **任务列表**：支持列表和网格视图切换\n- **元数据展示**：展示 Purpose、Requirements、Leverage、Prompt 等任务属性\n- **AI 提示词**：可展开的 AI 生成提示词查看器\n\n### 日志页面组件 (`LogsPage.tsx`)\n\n日志页面提供实现日志的详细查看功能： 资料来源：[src/dashboard_frontend/src/modules/pages/LogsPage.tsx:1-40]()\n\n- **统计数据**：文件变更数、净变更行数\n- **文件变更列表**：展示修改和创建的文件路径\n- **构件展示**：按类型分类展示生成的代码构件\n\n### 日志卡片组件 (`LogEntryCard.tsx`)\n\n日志条目卡片组件用于在 VSCode 扩展中渲染单个日志条目： 资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx:1-80]()\n\n```typescript\ninterface LogEntryCardProps {\n entry: ImplementationLogEntry;\n}\n```\n\n## 多语言支持\n\n项目包含国际化（i18n）支持，通过 `i18n.js` 模块提供多语言文本资源。已确认的语言版本包括：\n\n- 英语（默认）\n- 法语（`README.fr.md`）\n\n## 构建与部署\n\n### 前端构建\n\n```bash\nnpm install\nnpm run build\n```\n\n### VSCode 扩展构建\n\nVSCode 扩展的 Web 视图代码独立构建到 `webview-dist/` 目录，然后与扩展主体打包。 资料来源：[vscode-extension/webview-dist/index.html:1-20]()\n\n### 开发模式\n\n```bash\nnpm run dev\n```\n\n## 架构总览图\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[仪表板前端
React + TypeScript]\n B[VSCode 扩展 WebView]\n end\n \n subgraph 核心层\n C[实现日志管理
implementation-log-manager]\n D[日志迁移器
implementation-log-migrator]\n E[Markdown 模板系统]\n end\n \n subgraph 数据层\n F[.spec-workflow/ 目录]\n G[配置文件]\n end\n \n A --> C\n B --> C\n C --> D\n C --> F\n D --> F\n E --> F\n```\n\n## 总结\n\n`spec-workflow-mcp` 项目采用清晰的分层架构设计：\n\n1. **核心层** (`src/core/`) 提供业务逻辑和数据处理能力\n2. **仪表板层** (`src/dashboard/` + `src/dashboard_frontend/`) 提供独立的 Web 管理界面\n3. **扩展层** (`vscode-extension/`) 提供编辑器集成功能\n4. **模板层** (`src/markdown/templates/`) 确保文档标准化\n\n这种模块化设计使得系统各部分可以独立开发、测试和部署，同时保持良好的可维护性和可扩展性。\n\n---\n\n\n\n## 规格工作流程\n\n### 相关页面\n\n相关主题：[任务管理](#page-task-management), [审批系统](#page-approval-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/WORKFLOW.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/WORKFLOW.md)\n- [src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n- [src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n- [src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n \n\n# 规格工作流程\n\n## 概述\n\n规格工作流程（Spec Workflow）是 spec-workflow-mcp 项目的核心功能模块，为 AI 代码助手提供结构化的项目开发流程管理能力。该工作流程通过规范化的文档创建、审批和执行机制，帮助开发团队在 AI 辅助编程环境中保持开发目标的一致性和可追溯性。\n\n规格工作流程的主要目标是：\n\n- 在项目启动阶段建立清晰的产品愿景和技术架构\n- 将大型需求拆解为可执行的小粒度任务\n- 通过审批流程确保 AI 生成的内容符合预期\n- 记录实现过程中的关键产物，便于后续维护\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 核心概念\n\n### 规格文档类型\n\n规格工作流程使用多种类型的文档来组织项目信息：\n\n| 文档类型 | 文件路径 | 用途 |\n|---------|---------|------|\n| 产品文档 | `.spec-workflow/steering/product.md` | 定义产品愿景、目标用户和关键特性 |\n| 技术文档 | `.spec-workflow/steering/tech.md` | 记录技术架构决策和技术栈 |\n| 结构文档 | `.spec-workflow/steering/structure.md` | 描述代码库组织结构和模块架构 |\n| 设计文档 | `.spec-workflow/specs/{name}/design.md` | 具体规格的设计说明 |\n| 任务文档 | `.spec-workflow/specs/{name}/tasks.md` | 将设计拆解为可执行任务 |\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### 模板系统\n\n系统支持自定义模板，允许用户覆盖默认模板行为：\n\n- 用户自定义模板优先：`.spec-workflow/user-templates/`\n- 默认模板：`.spec-workflow/templates/`\n\n支持的模板文件包括：`product-template.md`、`tech-template.md`、`structure-template.md`、`design-template.md`、`tasks-template.md`\n\n## 引导文档工作流程\n\n引导文档（Steering Documents）是项目的顶层规划文档，包括产品愿景、技术架构和代码结构三个核心文档。\n\n### 工作流程阶段\n\n引导文档工作流程分为三个阶段：\n\n```mermaid\ngraph TD\n Start([开始]) --> P1_Template[检查用户模板
user-templates/]\n P1_Template --> P1_Read{是否有自定义模板?}\n P1_Read -->|是| P1_Custom[读取自定义模板]\n P1_Read -->|否| P1_Default[读取默认模板
templates/]\n P1_Custom --> P1_Analyze[分析产品需求]\n P1_Default --> P1_Analyze\n P1_Analyze --> P1_Create[创建文件
steering/product.md]\n P1_Create --> P1_Approve[approvals
action: request
filePath only]\n P1_Approve --> P1_Status[approvals
action: status
轮询状态]\n P1_Status --> P1_Check{状态?}\n P1_Check -->|needs-revision| P1_Update[根据用户评论更新文档]\n P1_Update --> P1_Create\n P1_Check -->|approved| P1_Clean[approvals
action: delete]\n P1_Clean -->|失败| P1_Status\n P1_Clean -->|成功| P2_Template\n\n P2_Template --> P2_Read[检查技术模板]\n P2_Read --> P2_Analyze[分析技术栈]\n P2_Analyze --> P2_Create[创建文件
steering/tech.md]\n P2_Create --> P2_Approve[approvals
action: request]\n P2_Approve --> P2_Status[轮询状态]\n P2_Status --> P2_Check{状态?}\n P2_Check -->|needs-revision| P2_Update\n P2_Update --> P2_Create\n P2_Check -->|approved| P2_Clean[删除审批]\n P2_Clean -->|成功| P3_Template\n\n P3_Template --> P3_Read[检查结构模板]\n P3_Read --> P3_Analyze[分析代码结构]\n P3_Analyze --> P3_Create[创建文件
steering/structure.md]\n P3_Create --> P3_Approve[approvals
action: request]\n P3_Approve --> P3_Status[轮询状态]\n P3_Status --> P3_Check{状态?}\n P3_Check -->|needs-revision| P3_Update\n P3_Update --> P3_Create\n P3_Check -->|approved| P3_Clean\n P3_Clean -->|成功| Complete([引导文档完成])\n\n style Start fill:#e6f3ff\n style Complete fill:#e6f3ff\n style P1_Check fill:#ffe6e6\n style P2_Check fill:#ffe6e6\n style P3_Check fill:#ffe6e6\n```\n\n### 第一阶段：产品文档\n\n**目的**：定义愿景、目标和用户成果。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/product-template.md`\n- 读取模板：`.spec-workflow/templates/product-template.md`（无自定义模板时）\n- 创建文档：`.spec-workflow/steering/product.md`\n\n**流程**：\n\n1. 检查自定义模板\n2. 分析现有产品需求\n3. 创建 `product.md`\n4. 使用 approvals 工具请求审批\n5. 轮询审批状态直到 approved/needs-revision\n6. 若 needs-revision：根据评论更新文档，创建新审批\n7. 审批通过后：使用 approvals action:delete 删除审批记录\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### 第二阶段：技术文档\n\n**目的**：记录技术决策和架构设计。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/tech-template.md`\n- 读取模板：`.spec-workflow/templates/tech-template.md`\n- 创建文档：`.spec-workflow/steering/tech.md`\n\n**流程**：同产品文档阶段\n\n### 第三阶段：结构文档\n\n**目的**：映射代码库组织和模式。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/structure-template.md`\n- 读取模板：`.spec-workflow/templates/structure-template.md`\n- 创建文档：`.spec-workflow/steering/structure.md`\n\n## 规格创建工作流程\n\n规格创建工作流程用于生成具体的项目规格文档，包括设计文档和任务列表。\n\n### 工作流程阶段\n\n```mermaid\ngraph TD\n Start([开始]) --> P1_Template[检查设计模板]\n P1_Template --> P1_Read[读取模板内容]\n P1_Read --> P1_Analyze[分析需求]\n P1_Analyze --> P1_Create[创建文件
specs/{name}/design.md]\n P1_Create --> P1_Approve[请求审批]\n P1_Approve --> P1_Status[轮询状态]\n P1_Status --> P1_Check{状态?}\n P1_Check -->|needs-revision| P1_Update[更新文档]\n P1_Update --> P1_Create\n P1_Check -->|approved| P1_Clean[删除审批]\n P1_Clean -->|成功| P2_Ready\n\n P2_Ready([就绪]) --> P2_Template[检查任务模板]\n P2_Template --> P2_Break[将设计拆解为任务]\n P2_Break --> P2_Create[创建文件
specs/{name}/tasks.md]\n P2_Create --> P2_Approve[请求审批]\n P2_Approve --> P2_Status[轮询状态]\n P2_Status --> P2_Check{状态?}\n P2_Check -->|needs-revision| P2_Update[更新任务]\n P2_Update --> P2_Create\n P2_Check -->|approved| P2_Clean\n P2_Clean -->|成功| P3_Ready\n\n P3_Ready([就绪]) --> P3_Impl[执行任务实现]\n\n style Start fill:#e6f3ff\n style P3_Ready fill:#e6f3ff\n style P1_Check fill:#ffe6e6\n style P2_Check fill:#ffe6e6\n```\n\n### 第一阶段：设计文档\n\n**目的**：详细描述规格的设计方案。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/design-template.md`\n- 读取模板：`.spec-workflow/templates/design-template.md`\n- 创建文档：`.spec-workflow/specs/{name}/design.md`\n\n### 第二阶段：任务文档\n\n**目的**：将设计方案转换为可执行任务列表。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/tasks-template.md`\n- 读取模板：`.spec-workflow/templates/tasks-template.md`\n- 创建文档：`.spec-workflow/specs/{name}/tasks.md`\n\n**任务拆解要求**：\n\n- 每个任务应具有清晰的完成标准\n- 任务之间应保持独立性\n- 明确任务的依赖关系\n\n资料来源：[src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n\n## 审批系统\n\n审批系统是规格工作流程的质量保障机制，确保 AI 生成的内容经过人工确认后再执行。\n\n### 审批操作\n\n| 操作 | 参数 | 说明 |\n|-----|------|------|\n| request | filePath | 创建新的审批请求 |\n| status | - | 查询当前审批状态 |\n| delete | - | 审批通过后删除记录 |\n\n### 审批状态\n\n| 状态 | 含义 | 后续操作 |\n|-----|------|---------|\n| pending | 等待审批 | 继续轮询 |\n| approved | 已批准 | 删除审批并继续下一步 |\n| needs-revision | 需要修改 | 根据评论更新文档，重新请求审批 |\n\n### 审批流程状态图\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: request\n Pending --> Approved: 用户批准\n Pending --> NeedsRevision: 用户要求修改\n NeedsRevision --> Pending: 更新后重新请求\n Approved --> [*]: delete\n NeedsRevision --> [*]: 取消\n```\n\n## 项目结构\n\n完整的项目结构如下：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批记录存储\n archive/ # 归档的规格文档\n specs/ # 规格文档目录\n {name}/\n design.md # 设计文档\n tasks.md # 任务文档\n steering/ # 引导文档目录\n product.md # 产品文档\n tech.md # 技术文档\n structure.md # 结构文档\n templates/ # 默认模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n## 工具引用\n\n### 主要工具\n\n| 工具名称 | 功能 | 源文件 |\n|---------|------|--------|\n| steering-guide | 加载引导文档工作流指令 | src/tools/steering-guide.ts |\n| spec-workflow-guide | 加载规格创建工作流指令 | src/tools/spec-workflow-guide.ts |\n| approvals | 管理审批工作流 | 工具模块 |\n\n### 工作流工具参数\n\n```typescript\n// steering-guide 工具\ninterface SteeringGuideParams {\n action: 'getInstructions' | 'execute';\n phase?: 'product' | 'tech' | 'structure';\n}\n\n// approvals 工具\ninterface ApprovalsParams {\n action: 'request' | 'status' | 'delete';\n filePath?: string;\n}\n\n// spec-workflow-guide 工具\ninterface SpecWorkflowParams {\n action: 'getInstructions' | 'execute';\n specName?: string;\n phase?: 'design' | 'tasks';\n}\n```\n\n## 任务解析器\n\n任务解析器（Task Parser）负责将任务文档解析为可执行的任务列表。\n\n### 解析流程\n\n```mermaid\ngraph LR\n A[tasks.md] --> B[task-parser.ts]\n B --> C{解析任务}\n C --> D[验证任务格式]\n D --> E[提取任务属性]\n E --> F[返回任务列表]\n```\n\n### 任务属性\n\n| 属性 | 说明 | 来源 |\n|-----|------|------|\n| id | 唯一标识符 | 文档解析 |\n| title | 任务标题 | 文档解析 |\n| description | 任务描述 | 文档解析 |\n| status | 执行状态 | 运行时更新 |\n| leverage | 杠杆值 | 用户指定 |\n\n资料来源：[src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n\n## 实现日志\n\n实现日志（Implementation Log）用于记录任务执行过程中的关键信息。\n\n### 日志条目结构\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n taskId: string;\n summary: string;\n filesModified: string[];\n filesCreated: string[];\n artifacts: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n statistics: {\n linesAdded: number;\n linesRemoved: number;\n };\n}\n```\n\n### 生成的报告格式\n\n实现日志支持导出为 Markdown 格式的报告，包含以下章节：\n\n- 实现摘要\n- 修改的文件列表\n- 创建的文件列表\n- 产物详情（API 端点、组件、函数、类、集成）\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## 接口选项\n\n规格工作流程提供两种用户界面：\n\n### 网页仪表盘\n\n- 默认端口：5000\n- 启动命令：`npx -y @pimzino/spec-workflow-mcp@latest --dashboard`\n- 访问地址：http://localhost:5000\n- 特点：集中管理，一个实例可供所有项目使用\n\n### VSCode 扩展\n\n- 集成到 VSCode 编辑器\n- 提供内联任务管理和审批功能\n- 适合 VSCode 用户\n\n## 配置\n\n### MCP 服务器配置\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n### 配置文件\n\n项目根目录下的 `config.example.toml` 提供了配置选项示例。\n\n## 许可证\n\n本项目采用 GPL-3.0 开源许可证。\n\n---\n\n\n\n## 审批系统\n\n### 相关页面\n\n相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n- [src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/dashboard_frontend/src/modules/approvals](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/approvals)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [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)\n \n\n# 审批系统\n\n## 概述\n\n审批系统（Approval System）是 spec-workflow-mcp 项目中用于管理和追踪文档审批流程的核心模块。该系统贯穿整个规范工作流，从产品文档、技术文档、结构文档到任务文档的创建和更新，都需要经过审批环节才能完成。\n\n审批系统的设计遵循以下核心原则：\n\n- **请求-审批-状态轮询**模式：每次文档创建或更新都需要发起审批请求，并通过轮询机制追踪审批状态\n- **批量操作支持**：支持多选模式下的批量批准或拒绝操作\n- **状态驱动的流程控制**：通过状态检查点（needs-revision/approved）决定下一步操作\n- **多端一致性**：VSCode 扩展和 Web Dashboard 提供统一的审批界面\n\n## 架构设计\n\n### 系统组件\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ 审批系统架构 │\n├─────────────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ VSCode │ │ Web │ │ MCP │ │\n│ │ 扩展 │ │ Dashboard │ │ Server │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │\n│ └────────────────┼────────────────┘ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ 审批存储层 │ │\n│ │ approval-storage.ts │ │\n│ └──────────┬──────────┘ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ 文件系统 │ │\n│ │ .spec-workflow/ │ │\n│ │ approvals/ │ │\n│ └─────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### 核心模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|---------|------|\n| 审批工具 | `src/tools/approvals.ts` | 提供 `request`、`status`、`delete` 等审批操作函数 |\n| 审批存储 | `src/dashboard/approval-storage.ts` | 管理审批记录的文件持久化 |\n| 审批页面 | `src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx` | Web Dashboard 审批 UI |\n| VSCode 组件 | `vscode-extension/src/webview/App.tsx` | VSCode 扩展内的审批卡片组件 |\n\n## 审批工作流\n\n### 完整状态流程\n\n```mermaid\ngraph TD\n Start([开始]) --> Request[发起审批请求]\n Request --> Status[轮询审批状态]\n Status --> Check{状态检查}\n Check -->|needs-revision| Update[根据用户评论更新文档]\n Update --> Request\n Check -->|approved| Clean[删除审批记录]\n Clean -->|success| Complete([流程完成])\n Clean -->|failed| Status\n Check -->|rejected| Rejected([审批拒绝])\n```\n\n### 各阶段的审批操作\n\n根据工作流定义，审批操作分为三种类型：\n\n| 操作类型 | 用途 | 触发条件 |\n|---------|------|---------|\n| `request` | 发起新的审批请求 | 文档创建或更新后 |\n| `status` | 轮询审批状态 | 请求后持续检查 |\n| `delete` | 删除已完成的审批记录 | 审批状态为 approved 后 |\n\n资料来源：[src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n\n### 各阶段的审批节点\n\n审批系统应用于以下工作流阶段：\n\n```mermaid\ngraph LR\n subgraph 产品文档阶段\n P1_Request[approvals
action: request]\n P1_Status[approvals
action: status]\n end\n \n subgraph 技术文档阶段\n P2_Request[approvals
action: request]\n P2_Status[approvals
action: status]\n end\n \n subgraph 结构文档阶段\n P3_Request[approvals
action: request]\n P3_Status[approvals
action: status]\n end\n \n subgraph 设计文档阶段\n D_Request[approvals
action: request]\n D_Status[approvals
action: status]\n end\n \n subgraph 任务阶段\n T_Request[approvals
action: request]\n T_Status[approvals
action: status]\n end\n```\n\n每个阶段的审批流程遵循相同的模式：创建文档 → 请求审批 → 轮询状态 → 根据结果更新或完成。\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n## 数据模型\n\n### 审批记录结构\n\n```typescript\ninterface Approval {\n id: string; // 唯一标识符\n title: string; // 审批标题\n description?: string; // 审批描述\n filePath?: string; // 相关文件路径（仅包含路径，不含内容）\n createdAt: Date | string; // 创建时间\n status: 'pending' | 'approved' | 'rejected' | 'needs-revision';\n category?: string; // 分类（用于过滤）\n}\n```\n\n### 审批状态枚举\n\n| 状态值 | 含义 | 后续操作 |\n|-------|------|---------|\n| `pending` | 待审批 | 等待用户响应 |\n| `approved` | 已批准 | 可删除记录，流程继续 |\n| `rejected` | 已拒绝 | 需要重新修改后再次提交 |\n| `needs-revision` | 需要修订 | 根据评论更新文档后重新提交 |\n\n资料来源：[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)\n\n## 前端组件\n\n### 审批卡片组件\n\n审批卡片是展示单个审批记录的核心组件，位于 VSCode 扩展的 Webview 中：\n\n```typescript\n// 卡片显示的信息\n- 标题 (title): 显示审批主题\n- 描述 (description): 可选的审批说明\n- 文件路径 (filePath): 以等宽字体显示的代码路径\n- 创建时间: 使用 formatDistanceToNow 格式化显示\n- 状态徽章: pending 状态显示待处理标识\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### 卡片操作按钮\n\n| 按钮 | 功能 | 状态 |\n|-----|------|-----|\n| 批准 (Approve) | 批准该审批请求 | 显示处理中状态 |\n| 拒绝 (Reject) | 拒绝该审批请求 | 显示处理中状态 |\n| 在编辑器中打开 | 查看审批文件内容 | - |\n\n### 批量操作\n\n审批系统支持多选模式下的批量操作：\n\n```typescript\n// 批量操作状态\ninterface BatchState {\n selectionMode: boolean; // 是否处于选择模式\n selectedApprovalIds: Set; // 已选中的审批 ID\n batchProcessing: boolean; // 是否正在处理\n pendingAction: 'approve' | 'reject' | null; // 待执行的批量操作\n batchResult: BatchApprovalResult | null; // 批量操作结果\n}\n```\n\n批量操作界面包含：\n\n1. **选择计数显示**：显示已选择的审批数量\n2. **清除选择按钮**：取消当前所有选择\n3. **批量批准按钮**：批准所有选中的审批\n4. **批量拒绝按钮**：拒绝所有选中的审批\n5. **结果提示**：显示操作成功或失败的数量统计\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### 审批页面组件\n\nWeb Dashboard 的审批页面（ApprovalsPage）提供更完整的功能：\n\n#### 筛选功能\n\n```typescript\n// 分类过滤\nconst [filterCategory, setFilterCategory] = useState('all');\n\n// URL 参数支持高亮显示特定审批\nconst [searchParams, setSearchParams] = useSearchParams();\nconst highlightedId = searchParams.get('id');\n```\n\n#### 模态框警告\n\n| 模态框 | 触发条件 | 用途 |\n|-------|---------|------|\n| 审批警告 | 批量操作前 | 确认批量操作的潜在影响 |\n| 修订警告 | 修订审批无评论时 | 提示用户添加修订说明 |\n\n资料来源：[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)\n\n## 存储机制\n\n### 审批文件存储\n\n审批记录存储在项目目录的 `.spec-workflow/approvals/` 目录下：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批记录存储目录\n archive/ # 已归档的规范\n specs/ # 规范文档\n steering/ # 指导文档\n templates/ # 模板\n user-templates/ # 用户自定义模板\n config.example.toml\n```\n\n### 文件操作流程\n\n1. **请求审批**：创建审批记录文件，记录请求信息和目标文件路径\n2. **状态管理**：通过文件系统状态或外部服务追踪审批状态\n3. **响应处理**：用户通过 VSCode 扩展或 Web Dashboard 进行响应\n4. **清理归档**：已批准的审批记录可被删除，相关文档移动到归档目录\n\n## 国际化支持\n\n审批系统支持多语言显示，关键翻译键位：\n\n| 翻译键 | 说明 |\n|-------|------|\n| `approvals.status.pending` | 待处理状态 |\n| `approvals.approve` | 批准按钮 |\n| `approvals.processing` | 处理中状态 |\n| `approvals.openInEditor` | 在编辑器中打开 |\n| `approvals.created` | 创建时间（带时间参数） |\n| `approvals.noPending` | 无待处理审批 |\n| `approvals.selectedCount` | 已选中数量 |\n| `approvals.clearSelection` | 清除选择 |\n| `approvalsPage.approvalWarning.message` | 审批警告消息 |\n| `approvalsPage.revision.noCommentsTitle` | 修订无评论标题 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n## API 接口\n\n### 审批相关 API\n\n| 接口名 | 功能 | 参数 |\n|-------|------|-----|\n| `approveRequest(id, response)` | 批准指定审批 | id: 审批ID, response: 响应内容 |\n| `rejectRequest(id, response)` | 拒绝指定审批 | id: 审批ID, response: 响应内容 |\n| `getApprovalContent(id)` | 获取审批内容 | id: 审批ID |\n| `approvalsActionBatch(ids, action)` | 批量操作 | ids: 审批ID数组, action: 操作类型 |\n| `approvalsUndoBatch(ids)` | 撤销批量操作 | ids: 审批ID数组 |\n\n### 状态轮询机制\n\n```typescript\n// 状态轮询流程\nasync function pollStatus(approvalId: string) {\n let status = await getApprovalStatus(approvalId);\n while (status === 'pending') {\n await sleep(1000); // 轮询间隔\n status = await getApprovalStatus(approvalId);\n }\n return status;\n}\n```\n\n## 样式与用户体验\n\n### 视觉设计\n\n审批卡片采用以下设计规范：\n\n```css\n/* 卡片容器 */\n.space-y-3: 元素间距 0.75rem\n\n/* 标题样式 */\n.font-medium: 中等字重\n.text-sm: 字体大小 14px\n.truncate: 文本溢出省略\n\n/* 状态徽章 */\n.variant: secondary\n.text-xs: 字体大小 12px\n\n/* 按钮样式 */\n.h-6: 高度 24px\n.px-2: 内边距水平 8px\n.text-xs: 字体大小 12px\n```\n\n### 时间显示\n\n创建时间使用 `formatDistanceToNow` 函数格式化，例如：\n\n- \"5 minutes ago\" → \"5分钟前\"\n- \"2 hours ago\" → \"2小时前\"\n- \"1 day ago\" → \"1天前\"\n\n## 与其他系统的集成\n\n### 规范工作流集成\n\n审批系统是规范工作流（Spec Workflow）的核心环节：\n\n```mermaid\ngraph TD\n subgraph 工作流阶段\n Create[创建文档] --> Approve[请求审批]\n Approve --> Poll[轮询状态]\n Poll --> Check{状态判断}\n Check -->|修订| Update[更新文档]\n Update --> Create\n Check -->|批准| Continue[继续下一阶段]\n Check -->|拒绝| Failed[流程失败]\n end\n```\n\n### 统计面板集成\n\n审批统计信息集成在 Dashboard 的统计面板中：\n\n| 统计项 | 字段 | 显示逻辑 |\n|-------|------|---------|\n| 待审批数量 | `approvals.length` | 大于0时显示警告色 |\n| 审批状态 | awaiting / allClear | 根据数量显示不同文案 |\n\n资料来源：[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)\n\n## 最佳实践\n\n### 发起审批\n\n1. 确保文档已完成编写并保存\n2. 提供清晰的审批标题和描述\n3. 在 `filePath` 中指定需要审批的文件路径\n\n### 审批响应\n\n1. 仔细阅读文档内容\n2. 批准时添加简短的响应说明\n3. 需要修订时提供具体的修改建议\n4. 避免无评论的修订操作\n\n### 批量操作\n\n1. 批量操作前确认所有选中项\n2. 注意系统警告提示\n3. 操作后检查结果反馈\n4. 及时撤销错误的批量操作\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 审批状态不更新 | 轮询间隔过长 | 检查状态更新机制 |\n| 批量操作失败 | 部分审批已处理 | 使用撤销功能恢复 |\n| 文件路径显示不正确 | 相对路径解析问题 | 使用绝对路径 |\n\n### 调试建议\n\n1. 检查浏览器控制台的 API 响应\n2. 验证 `.spec-workflow/approvals/` 目录权限\n3. 确认 MCP Server 连接状态\n4. 查看 Dashboard 日志输出\n\n---\n\n\n\n## 任务管理\n\n### 相关页面\n\n相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [vscode-extension/src/extension/utils/taskParser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts)\n- [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)\n- [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)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n\n \n\n# 任务管理\n\n## 概述\n\n任务管理是 spec-workflow-mcp 项目的核心功能模块，负责规范化和跟踪项目中的开发任务。该模块支持多状态流转、看板视图、实时进度统计以及任务元数据管理，为团队提供了清晰的任务可视化和管理能力。\n\n任务管理系统的核心设计目标包括：\n\n- **状态驱动的工作流**：通过明确的任务状态定义团队工作进度\n- **Markdown 格式兼容**：任务以 Markdown 复选框格式存储，便于版本控制\n- **多端一致性**：Web 仪表板和 VSCode 扩展共享同一任务状态管理逻辑\n- **阻塞机制**：支持标记任务阻塞原因，便于问题追踪\n\n资料来源：[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)\n\n---\n\n## 任务状态定义\n\n### 状态类型\n\n系统定义了四种互斥的任务状态：\n\n| 状态值 | 复选框标记 | 含义 | 视觉标识 |\n|--------|-----------|------|---------|\n| `pending` | 空格 ` ` | 待处理 | 默认灰色 |\n| `in-progress` | 短横 `-` | 进行中 | 橙色边框 |\n| `completed` | 小写 `x` | 已完成 | 绿色样式 |\n| `blocked` | 波浪 `~` | 已阻塞 | 红色边框 |\n\n资料来源：[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)\n\n### 状态转换规则\n\n```mermaid\nstateDiagram-v2\n [*] --> pending : 新建任务\n pending --> in-progress : 开始处理\n in-progress --> completed : 任务完成\n in-progress --> blocked : 发现阻塞\n blocked --> in-progress : 解除阻塞\n blocked --> pending : 回退待处理\n completed --> pending : 重新打开\n```\n\n状态转换时的处理逻辑：\n\n```typescript\n// 拦截 blocked 状态以记录原因\nif (newStatus === 'blocked') {\n setPendingBlockedTaskId(taskId);\n setKanbanBlockedReasonOpen(true);\n return;\n}\n```\n\n资料来源：[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)\n\n---\n\n## 任务数据模型\n\n### 核心字段\n\n```typescript\ninterface Task {\n id: string; // 任务唯一标识 (如 \"1.1\", \"2.3.1\")\n status: TaskStatus; // 当前状态\n completed?: boolean; // 是否已完成 (计算属性)\n inProgress?: boolean; // 是否进行中 (计算属性)\n blockedReason?: string; // 阻塞原因 (仅 blocked 状态)\n prompt?: string; // AI 执行提示词\n leverage?: string; // 复用/杠杆信息\n purposes?: string[]; // 任务目的列表\n requirements?: string[]; // 特殊需求列表\n isHeader?: boolean; // 是否为分组标题\n}\n```\n\n### 任务元数据展示\n\n看板卡片支持展示丰富的任务元数据：\n\n| 元数据字段 | 展示位置 | 样式特征 |\n|-----------|---------|---------|\n| 任务 ID | 卡片顶部 | 等宽字体，深色背景 |\n| Leverage | 青色标签 | 青色背景，等宽字体 |\n| Purposes | 绿色标签 | 列表形式展示 |\n| Requirements | 橙色标签 | 逗号分隔展示 |\n| AI Prompt | 可展开区域 | 带复制按钮 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n---\n\n## Markdown 格式解析\n\n### 任务格式规范\n\n任务以标准 Markdown 复选框语法存储：\n\n```markdown\n- [ ] 1.1 任务描述\n- [-] 1.2 进行中的任务\n- [x] 1.3 已完成任务\n- [~] 1.4 阻塞的任务 (原因在下一行)\n```\n\n解析器支持 `-` 和 `*` 两种列表标记符：\n\n```typescript\n// 正则匹配模式\nconst checkboxMatch = line.match(/^(\\s*)([-*])\\s+\\[([ x\\-~])\\]\\s+(.+)/);\n```\n\n资料来源：[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)\n\n### 状态更新机制\n\n```typescript\nexport function updateTaskStatus(\n content: string,\n taskId: string,\n newStatus: 'pending' | 'in-progress' | 'completed' | 'blocked',\n reason?: string\n): string {\n const statusMarker = newStatus === 'completed' ? 'x' :\n newStatus === 'in-progress' ? '-' :\n newStatus === 'blocked' ? '~' :\n ' ';\n // ... 遍历并更新匹配的任务行\n}\n```\n\n资料来源：[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)\n\n---\n\n## 看板视图\n\n### 布局结构\n\n```mermaid\ngraph TD\n subgraph 看板布局\n A[待处理列] --> B[进行中列]\n B --> C[已完成列]\n B --> D[已阻塞列]\n end\n subgraph 任务统计\n E[总任务数] --> F[完成率百分比]\n G[进度条组件] --> F\n end\n```\n\n### 任务卡片组件\n\n```typescript\n// KanbanTaskCard 核心交互\ninterface KanbanTaskCardProps {\n task: Task;\n isInProgress: boolean;\n copiedTaskId: string | null;\n onCopyTaskPrompt: () => void;\n onToggleExpand: () => void;\n}\n```\n\n关键交互特性：\n\n- **触摸优化**：最小点击目标 44x44 像素（WCAG AAA 标准）\n- **复制功能**：一键复制 AI Prompt 到剪贴板\n- **进行中指示**：橙色脉冲动画标识当前处理任务\n\n资料来源：[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)\n\n---\n\n## API 接口\n\n### 任务状态更新\n\n```\nPUT /specs/{specName}/tasks/{taskId}/status\n```\n\n**请求参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `specName` | string | 是 | 规格文档名称（URL 编码） |\n| `taskId` | string | 是 | 任务标识符（URL 编码） |\n| `status` | TaskStatus | 是 | 新状态值 |\n| `reason` | string | 否 | 阻塞原因（仅 blocked 时） |\n\n**响应结构：**\n\n```typescript\ninterface TaskStatusResponse {\n success: boolean;\n task: Task;\n progress: number; // 0-100 百分比\n}\n```\n\n资料来源：[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)\n\n### 进度查询\n\n```\nGET /specs/{specName}/tasks/progress\n```\n\n**返回数据：**\n\n```typescript\ninterface TaskProgress {\n total: number; // 总任务数\n completed: number; // 已完成数\n inProgress: string | null; // 当前进行中的任务ID\n progress: number; // 完成百分比\n taskList: Task[]; // 完整任务列表\n}\n```\n\n---\n\n## 实施日志管理\n\n### 日志条目结构\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n taskId: string;\n summary: string;\n filesModified: string[];\n filesCreated: string[];\n artifacts: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n statistics?: {\n linesAdded: number;\n linesRemoved: number;\n };\n}\n```\n\n### Markdown 导出格式\n\n实施日志支持导出为 Markdown 格式，便于文档化和分享：\n\n```markdown\n## Task Summary\n_任务摘要信息_\n\n---\n\n## Statistics\n- Lines Added: {count}\n- Lines Removed: {count}\n\n## Files Modified\n- file1.ts\n- file2.ts\n\n---\n\n## Artifacts\n\n### API Endpoints\n#### POST /api/resource\n- **Purpose:** 端点用途说明\n- **Location:** 文件路径\n\n### Components\n#### ComponentName\n- **Type:** 组件类型\n- **Purpose:** 组件用途\n```\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n---\n\n## 前端状态管理\n\n### 乐观更新策略\n\n任务状态更新采用乐观更新模式，先更新本地 UI 再同步服务器：\n\n```typescript\n// 标记待更新任务\npendingStatusUpdatesRef.current.add(taskId);\n\n// 乐观更新本地数据\nsetData((prevData: any) => {\n const updatedTaskList = prevData.taskList.map((t: any) =>\n t.id === taskId ? { \n ...t, \n status: newStatus, \n completed: newStatus === 'completed',\n inProgress: newStatus === 'in-progress',\n blockedReason: undefined \n } : t\n );\n return { ...prevData, taskList: updatedTaskList };\n});\n```\n\n资料来源：[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)\n\n### 剪贴板操作\n\n支持现代 Clipboard API 和传统 fallback 方案：\n\n```typescript\nfunction copyTaskPrompt(specName: string, task: any, onSuccess?, onFailure?) {\n const command = task.prompt || `Please work on task ${task.id} for spec \"${specName}\"`;\n \n // 现代 API\n if (navigator.clipboard?.writeText) {\n navigator.clipboard.writeText(command).then(() => onSuccess?.());\n } else {\n // 传统方案 (HTTP over LAN 等场景)\n fallbackCopy(command, onSuccess, onFailure);\n }\n}\n```\n\n资料来源：[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)\n\n---\n\n## 统计与可视化\n\n### 任务计数器\n\n```typescript\nconst taskCounts = {\n all: nonHeaderTasks.length,\n completed: nonHeaderTasks.filter(t => t.status === 'completed').length,\n 'in-progress': nonHeaderTasks.filter(t => t.status === 'in-progress').length,\n pending: nonHeaderTasks.filter(t => t.status === 'pending').length,\n blocked: nonHeaderTasks.filter(t => t.status === 'blocked').length,\n headers: tasks.filter(t => t.isHeader).length\n};\n```\n\n### 进度条组件\n\n进度百分比计算公式：\n\n```\nprogress = (completedTasks / totalTasks) * 100\n```\n\n显示时四舍五入至整数：\n\n```tsx\n{Math.round(taskData.progress)}%\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n---\n\n## 筛选与排序\n\n### 状态筛选\n\n| 筛选值 | 显示内容 |\n|--------|---------|\n| `all` | 所有任务 |\n| `pending` | 仅待处理 |\n| `in-progress` | 仅进行中 |\n| `completed` | 仅已完成 |\n| `blocked` | 仅已阻塞 |\n\n### 排序控制\n\n- **看板视图**：按状态列自动分组\n- **列表视图**：支持多维度排序（优先级、创建时间等）\n\n---\n\n## 最佳实践\n\n### 1. 阻塞原因记录\n\n当任务进入 `blocked` 状态时，应在弹窗中详细说明阻塞原因，便于团队协作排查问题。\n\n### 2. Prompt 规范\n\n每个任务应配置明确的 `prompt` 字段，为 AI 提供清晰的执行指令。\n\n### 3. Leverage 复用\n\n对于可复用的代码或组件，应在 `leverage` 字段中记录相关位置和说明。\n\n### 4. 实时同步\n\n多端操作时注意同步状态，避免冲突覆盖。\n\n---\n\n\n\n## Web 仪表板\n\n### 相关页面\n\n相关主题：[VSCode 扩展](#page-vscode-extension), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)\n- [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)\n- [src/dashboard_frontend/src/modules/pages](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages)\n- [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)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n \n\n# Web 仪表板\n\nWeb 仪表板是 spec-workflow-mcp 项目的核心可视化界面，为开发者提供图形化的项目状态监控、规范文档管理和任务追踪功能。仪表板通过 Web 界面形式呈现，允许用户在浏览器中直观地查看所有已连接项目的规格文档、审批状态和实现日志。\n\n## 功能概述\n\nWeb 仪表板的主要功能包括：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 项目概览 | 显示所有已连接项目的基本统计信息 |\n| 规格文档管理 | 列出活跃和已归档的规格文档 |\n| 任务追踪 | 展示每个规格文档的任务进度和状态 |\n| 审批管理 | 处理实现日志的审批流程 |\n| 自动清理 | 配置和管理自动化清理任务 |\n| 设置管理 | 仪表板全局配置和偏好设置 |\n\n资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()\n\n## 系统架构\n\n### 组件结构\n\nWeb 仪表板采用前后端分离的架构设计：\n\n```mermaid\ngraph TD\n A[Web 浏览器] --> B[Dashboard Frontend
React SPA]\n B --> C[Dashboard Backend
Express.js]\n C --> D[文件系统
.spec-workflow]\n E[多个项目 Workspace] --> D\n \n B --> F[API 模块
api.tsx]\n F --> C\n```\n\n前端部分位于 `src/dashboard_frontend/` 目录，使用 React 构建单页应用。主要页面组件包括：\n\n- **App.tsx** - 根组件，管理全局状态和页面路由\n- **SettingsPage.tsx** - 设置页面，管理自动化清理和偏好配置\n- **TasksPage.tsx** - 任务页面，展示任务详情和进度\n\n资料来源：[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)()\n\n### 部署架构\n\n仪表板支持多种部署方式：\n\n```mermaid\ngraph LR\n A[直接运行] --> B[npx --dashboard]\n C[Docker 容器] --> D[docker-compose]\n B --> E[http://localhost:5000]\n D --> E\n```\n\n## 核心页面\n\n### 项目概览页面\n\n概览页面展示当前选中项目的核心统计数据：\n\n| 统计项 | 说明 |\n|-------|------|\n| 活跃规格文档数 | 当前处于活跃状态的规格文档总数 |\n| 已完成规格文档数 | 已完成实现的规格文档数 |\n| 已归档规格文档数 | 归档的历史规格文档数 |\n| 任务完成率 | 已完成任务占总任务数的比例 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)()\n\n### 任务页面\n\n任务页面详细展示每个规格文档下定义的任务列表，支持以下功能：\n\n- **状态筛选** - 按 pending、in-progress、completed、blocked 状态筛选\n- **AI 提示词** - 显示任务关联的 AI 提示词内容\n- **杠杆值** - 显示任务的杠杆指数（leverage）\n- **进度追踪** - 实时更新任务完成进度\n\n```mermaid\ngraph TD\n A[获取任务列表] --> B{任务状态}\n B -->|pending| C[待处理]\n B -->|in-progress| D[进行中]\n B -->|completed| E[已完成]\n B -->|blocked| F[已阻塞]\n \n C --> G[状态更新 API]\n D --> G\n E --> G\n F --> G\n G --> H[更新任务状态]\n```\n\n资料来源：[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)()\n\n### 设置页面\n\n设置页面提供仪表板全局配置功能，包括自动化清理任务的配置：\n\n- 管理跨所有已连接项目运行的自动化清理作业\n- 配置清理频率和保留策略\n- 查看清理任务执行日志\n\n资料来源：[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)()\n\n## API 接口\n\n仪表板前端通过统一的 API 模块与后端通信：\n\n```typescript\n// 规格文档相关 API\ngetAllSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all`)\ngetAllArchivedSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all/archived`)\ngetSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${name}/tasks/progress`)\n\n// 任务状态管理\nupdateTaskStatus: (specName, taskId, status, reason?) => \n putJson(`/specs/${specName}/tasks/${taskId}/status`, { status, reason })\n\n// 审批相关 API\napprovalsAction: (id, action, body) => postJson(`/approvals/${id}/${action}`, body)\napprovalsActionBatch: (ids, action, response) => postJson(`/approvals/batch/${action}`, { ids, response })\napprovalsUndoBatch: (ids) => postJson(`/approvals/batch/undo`, { ids })\ngetApprovalContent: (id: string) => getJson(`/approvals/${id}/content`)\ngetApprovalSnapshots: (id: string) => getJson(`/approvals/${id}/snapshots`)\n```\n\n资料来源：[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)()\n\n## 部署配置\n\n### 环境变量\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `DASHBOARD_PORT` | `5000` | 仪表板运行端口 |\n| `SPEC_WORKFLOW_PATH` | `./workspace` | 项目工作区路径 |\n\n### Docker 部署\n\n使用 Docker Compose 部署是最推荐的方案：\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n自定义端口部署示例：\n\n```bash\ndocker run -p 8080:8080 \\\n -e DASHBOARD_PORT=8080 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n资料来源：[containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)()\n\n### 快速启动\n\n通过 npx 直接启动本地仪表板：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表板启动后可通过 http://localhost:5000 访问。\n\n> **注意**：仅需一个仪表板实例即可管理所有已连接项目，所有项目共享同一仪表板服务。\n\n资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()\n\n## 安全特性\n\nWeb 仪表板实现了企业级安全控制：\n\n| 安全特性 | 描述 |\n|---------|------|\n| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端 120 请求/分钟，自动清理过期连接 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者和结果 |\n| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n## 前端国际化\n\n仪表板支持多语言界面，使用 i18n 模块处理翻译资源：\n\n```typescript\n// 语言切换时自动更新\nt.changeLanguage(g) // g 为语言代码\n_.setLanguagePreference(g)\n```\n\n语言偏好设置会被持久化保存，用户下次访问时自动应用已选语言。\n\n## 与 VSCode 扩展的关系\n\nWeb 仪表板与 VSCode 扩展共用同一前端组件库和样式资源。编译后的静态资源位于 `vscode-extension/webview-dist/` 目录：\n\n| 文件 | 用途 |\n|-----|------|\n| `index.html` | VSCode 内嵌 WebView 入口 |\n| `main.js` | 编译后的主应用代码 |\n| `globals.css` | 全局样式定义 |\n| `comment-modal.html` | 注释弹窗页面 |\n\n这确保了仪表板界面与 VSCode 扩展内嵌 WebView 的一致用户体验。\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Dashboard as Web 仪表板\n participant Backend as 后端服务\n participant FS as 文件系统\n \n User->>Dashboard: 访问 http://localhost:5000\n Dashboard->>Backend: 请求项目列表\n Backend->>FS: 读取 .spec-workflow 配置\n FS-->>Backend: 返回项目元数据\n Backend-->>Dashboard: 返回统计数据\n Dashboard-->>User: 渲染项目概览\n \n User->>Dashboard: 选择规格文档\n Dashboard->>Backend: 获取任务列表\n Backend-->>Dashboard: 返回任务数据\n Dashboard-->>User: 渲染任务页面\n \n User->>Dashboard: 更新任务状态\n Dashboard->>Backend: PUT /specs/{name}/tasks/{id}/status\n Backend->>FS: 更新任务状态文件\n FS-->>Backend: 确认更新\n Backend-->>Dashboard: 返回更新结果\n```\n\n## 总结\n\nWeb 仪表板作为 spec-workflow-mcp 项目的核心用户界面，提供了一个集中化的可视化管理平台。它通过 RESTful API 与后端服务通信，支持多项目管理、任务追踪、审批流程和系统配置等完整功能。仪表板采用 Docker 容器化部署，配置简单快捷，同时具备企业级安全特性，适合团队协作环境使用。\n\n---\n\n\n\n## VSCode 扩展\n\n### 相关页面\n\n相关主题：[Web 仪表板](#page-dashboard), [安装配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vscode-extension/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n- [vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n- [vscode-extension/src/extension/providers/SidebarProvider.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)\n- [vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n- [vscode-extension/src/webview/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/comment-modal.html)\n- [vscode-extension/webview-dist/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)\n\n \n\n# VSCode 扩展\n\n## 概述\n\nVSCode 扩展是 spec-workflow-mcp 项目的重要组成部分，为 Visual Studio Code 用户提供原生的开发体验。通过该扩展，用户可以直接在 VSCode 编辑器中访问和管理项目规格文档、审批流程以及实现日志，无需切换到独立的 Web 仪表板。\n\n该扩展基于 VSCode Webview API 构建，采用 React 作为前端框架，实现了与核心工作流引擎的深度集成。扩展通过 MCP（Model Context Protocol）协议与后端服务通信，为用户提供实时的工作状态反馈和交互能力。\n\n扩展的主要设计目标是降低 AI 辅助开发的工作流门槛，让开发者能够在熟悉的 IDE 环境中完成从规格创建、审批到实现追踪的完整流程。\n\n## 架构设计\n\n### 整体架构\n\nVSCode 扩展采用前后端分离的架构模式，核心组件分为三个层次：\n\n```mermaid\ngraph TD\n A[VSCode 扩展宿主] --> B[Webview UI 层]\n A --> C[MCP 通信层]\n B <--> D[Webview 消息传递]\n C --> E[后端服务]\n D --> F[用户交互]\n```\n\n### 目录结构\n\n```\nvscode-extension/\n├── README.md # 扩展说明文档\n├── package.json # 扩展配置和依赖\n├── src/\n│ ├── extension/ # 扩展后端代码\n│ │ ├── providers/\n│ │ │ └── SidebarProvider.ts # 侧边栏提供者\n│ │ └── services/\n│ │ └── ApprovalEditorService.ts # 审批编辑器服务\n│ └── webview/ # Webview 前端代码\n│ ├── App.tsx # 主应用组件\n│ ├── comment-modal.html # 评论模态框 HTML\n│ └── components/\n│ └── LogEntryCard.tsx # 日志条目卡片组件\n└── webview-dist/ # 编译后的 Webview 资源\n ├── comment-modal.js # 评论模态框脚本\n ├── comment-modal.html # 评论模态框页面\n ├── globals.css # 全局样式\n └── i18n.js # 国际化脚本\n```\n\n资料来源：[vscode-extension/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n\n### Webview 消息通信机制\n\n扩展通过 VSCode 的 `postMessage` API 实现前端与后端的双向通信。当用户在 Webview 中执行操作时，消息被发送到扩展后端，后端处理请求后返回响应结果。这种模式确保了用户界面的流畅性，同时保持了与核心系统的同步。\n\nWebview 使用 `useEffect` 钩子监听来自扩展的消息，根据消息类型更新对应的 UI 状态。对于需要持久化的数据操作，扩展会通过 MCP 协议转发到后端服务进行处理。\n\n## 核心组件\n\n### SidebarProvider（侧边栏提供者）\n\n`SidebarProvider` 是 VSCode 扩展的核心入口点，负责管理侧边栏视图的生命周期。该提供者扩展自 VSCode 的 `TreeView` API，能够在活动栏中注册一个可折叠的视图区域。\n\n主要职责包括：\n\n- 初始化侧边栏视图结构\n- 注册命令和快捷键\n- 处理视图项的点击事件\n- 管理 Webview 面板的创建和销毁\n\n资料来源：[vscode-extension/src/extension/providers/SidebarProvider.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)\n\n### ApprovalEditorService（审批编辑器服务）\n\n`ApprovalEditorService` 负责处理审批相关的数据操作和服务调用。该服务封装了所有与审批流程相关的业务逻辑，包括审批请求的创建、提交、撤销以及历史记录的查看。\n\n服务层的设计遵循单一职责原则，将数据获取逻辑与 UI 层分离，使得组件可以专注于用户界面的渲染，而无需关心底层的数据获取机制。通过依赖注入模式，扩展可以更容易地进行单元测试和功能扩展。\n\n资料来源：[vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)\n\n### App.tsx（主应用组件）\n\n`App.tsx` 是 Webview 的根组件，负责协调各个子组件的渲染和状态管理。该组件使用 React Context API 共享全局状态，使得深层嵌套的组件也能方便地访问和更新应用状态。\n\n组件结构采用功能模块化的设计，主要区域包括：\n\n- 概览面板：显示项目统计信息\n- 规格列表：展示所有活跃和归档的规格文档\n- 任务视图：呈现规格关联的任务及其进度\n- 日志视图：展示实现日志条目\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### LogEntryCard 组件\n\n`LogEntryCard` 是一个专门用于展示实现日志条目的卡片组件。它将复杂的日志数据解析为用户友好的格式，支持多种内容的可视化展示。\n\n组件支持展示的内容类型：\n\n| 内容类型 | 描述 | 数据格式 |\n|---------|------|---------|\n| 文件修改 | 列出本次实现修改的文件 | 字符串数组 |\n| 文件创建 | 列出本次实现创建的文件 | 字符串数组 |\n| API 端点 | 记录 API 接口信息 | 对象数组 |\n| 组件 | 前端组件元数据 | 对象数组 |\n| 函数 | 函数定义和导出信息 | 对象数组 |\n| 类 | 类定义和方法信息 | 对象数组 |\n| 集成 | 前端后端集成信息 | 对象数组 |\n\n组件采用条件渲染策略，仅当对应类型的数据存在时才显示相应的区域。这种设计减少了不必要的 DOM 操作，提升了渲染性能。\n\n资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n\n## 功能特性\n\n### 规格文档管理\n\n扩展提供了完整的规格文档管理界面，用户可以：\n\n- 查看所有活跃规格的列表和状态\n- 浏览已归档规格的历史记录\n- 追踪每个规格关联的任务进度\n- 直接在 VSCode 中编辑规格内容\n\n规格列表采用卡片式布局，每个卡片显示规格名称、任务进度条和关键元数据。进度条使用颜色编码来区分完成状态，绿色表示已完成的任务数量，灰色表示总任务数量。\n\n### 任务追踪系统\n\n任务追踪功能集成在规格详情视图中，允许用户：\n\n- 查看任务的元数据，包括目的、需求和技术杠杆点\n- 展开和折叠 AI 提示内容\n- 复制任务提示用于其他场景\n- 追踪任务的完成状态\n\n任务视图支持展开/折叠交互，用户可以点击任务标题来显示或隐藏详细信息。这种交互模式在处理大量任务时特别有用，可以帮助用户专注于当前关注的内容。\n\n### 审批工作流\n\n审批功能通过专门的编辑器服务实现，支持以下操作：\n\n- 提交审批请求\n- 批准或拒绝申请\n- 批量处理多个审批请求\n- 查看审批历史快照\n- 比较不同版本之间的差异\n\n审批编辑器服务封装了所有与审批相关的数据操作，包括快照生成、版本比较和批量操作。这种封装确保了 UI 层可以专注于用户交互，而无需处理复杂的业务逻辑。\n\n### 实现日志查看\n\n实现日志功能允许用户回顾开发过程中的所有变更：\n\n- 按时间线查看日志条目\n- 查看每次实现修改和创建的文件\n- 了解 API 端点、组件、函数等代码工件\n- 追踪前后端集成的数据流\n\n日志条目卡片提供了丰富的信息展示，包括统计数据（新增/删除行数）、文件列表和各类代码工件。每个工件条目都包含名称、目的、位置等关键信息，便于开发者快速定位代码。\n\n### 评论模态框\n\n评论功能通过独立的模态框实现，用户可以在任何支持评论的上下文中添加评论。模态框采用独立的 HTML 页面加载，确保样式与 VSCode 主题一致。\n\n评论模态框的样式通过 CSS 变量与 VSCode 主题系统集成：\n\n```css\nbody {\n font-family: var(--vscode-font-family), -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;\n font-size: var(--vscode-font-size, 13px);\n color: var(--vscode-foreground);\n background: var(--vscode-editor-background);\n}\n```\n\n资料来源：[vscode-extension/src/webview/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/comment-modal.html)\n\n## 用户界面设计\n\n### 主题适配\n\n扩展完全支持 VSCode 的亮色和暗色主题。通过使用 CSS 变量，Webview 可以自动响应主题切换，无需编写额外的主题检测逻辑。所有文本颜色、背景颜色和边框颜色都基于 VSCode 提供的语义化变量定义。\n\n主要使用的 CSS 变量包括：\n\n- `var(--vscode-font-family)`：字体系列\n- `var(--vscode-font-size)`：字体大小\n- `var(--vscode-foreground)`：前景色\n- `var(--vscode-editor-background)`：编辑器背景色\n\n资料来源：[vscode-extension/webview-dist/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)\n\n### 国际化支持\n\n扩展内置了国际化支持，通过 `i18n.js` 模块提供多语言文本资源。用户界面中的所有可显示文本都通过翻译键引用，而非硬编码的字符串。这种设计使得扩展可以轻松支持新的语言环境。\n\n翻译键采用层级命名规范，例如 `overview.projectTitle` 表示概览面板的项目标题文本。\n\n### 响应式布局\n\nWebview 界面采用响应式设计，针对不同的面板宽度提供优化的布局：\n\n- 小屏幕：单列布局，元素垂直堆叠\n- 大屏幕：双列或多列布局，充分利用空间\n\n任务视图中的元素根据容器宽度自动调整字体大小和间距。图标、标签和内容区域都采用相对单位，确保在不同尺寸的视口中保持可读性。\n\n## 配置与安装\n\n### 安装方式\n\n用户可以通过 VSCode 扩展市场安装该扩展，或者通过命令行加载本地构建的扩展包。\n\nVSCode 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n### 扩展配置\n\n扩展支持通过 `package.json` 进行配置，包括：\n\n| 配置项 | 类型 | 描述 |\n|-------|------|------|\n| `displayName` | 字符串 | 扩展显示名称 |\n| `description` | 字符串 | 扩展功能描述 |\n| `version` | 字符串 | 扩展版本号 |\n| `engines` | 对象 | VSCode 引擎版本要求 |\n\n资料来源：[vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n\n## 开发指南\n\n### 本地开发\n\n扩展的开发环境配置遵循标准的 VSCode 扩展开发流程：\n\n```bash\n# 安装依赖\nnpm install\n\n# 在开发模式下运行\nnpm run dev\n\n# 构建生产版本\nnpm run build\n```\n\n开发模式下，扩展会自动监听源文件的变化并重新加载，无需手动重启 VSCode。\n\n### Webview 资源管理\n\nWebview 所需的静态资源（HTML、CSS、JavaScript）需要在 `webview-dist` 目录中预编译。开发流程中，这些资源由构建系统自动处理，但在发布前需要确保所有资源都已正确打包。\n\nWebview 的入口点通过 `comment-modal.html` 定义，该文件引用编译后的脚本和样式资源。\n\n### 消息协议\n\n扩展与 Webview 之间的消息采用以下协议格式：\n\n```typescript\ninterface WebviewMessage {\n type: string;\n payload?: any;\n requestId?: string;\n}\n```\n\n每条消息包含消息类型标识和可选的数据负载。对于需要响应的消息，Webview 应在处理完成后发送带有对应 `requestId` 的响应消息。\n\n## 相关资源\n\n- 主项目文档：[SPEC Workflow MCP 文档](../README.md)\n- 开发指南：[开发文档](../docs/DEVELOPMENT.md)\n- 工作流程：[工作流程指南](../docs/WORKFLOW.md)\n- 工具参考：[工具参考文档](../docs/TOOLS-REFERENCE.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Pimzino/spec-workflow-mcp\n\n摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory。\n\n## 1. 安装坑 · 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code\n\n## 3. 配置坑 · 来源证据：[Bug]: Bug Report for spec-workflow-mcp\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown\n\n\n",
"markdown_key": "spec-workflow-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1033865617",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Pimzino/spec-workflow-mcp"
},
{
"evidence_id": "art_1ff9aa6c5b634348a3e199239d5b262c",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Pimzino/spec-workflow-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "spec-workflow-mcp 说明书",
"toc": [
"https://github.com/Pimzino/spec-workflow-mcp 项目说明书",
"目录",
"项目概述",
"简介",
"核心功能",
"技术架构",
"部署方式",
"使用 Docker Compose（推荐）",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "b63e6cd8d6ed53bbc48fe93d634f7b548285762f",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/TROUBLESHOOTING.ar.md",
"docs/INTERFACES.zh.md",
"docs/DEVELOPMENT.ko.md",
"docs/PROMPTING-GUIDE.es.md",
"docs/DEVELOPMENT.it.md",
"docs/WORKFLOW.ar.md",
"docs/DEVELOPMENT.de.md",
"docs/TOOLS-REFERENCE.ar.md",
"docs/PROMPTING-GUIDE.md",
"docs/USER-GUIDE.ru.md",
"docs/TOOLS-REFERENCE.md",
"docs/PROMPTING-GUIDE.de.md",
"docs/TROUBLESHOOTING.es.md",
"docs/TOOLS-REFERENCE.ru.md",
"docs/TROUBLESHOOTING.md",
"docs/CONFIGURATION.zh.md",
"docs/PROMPTING-GUIDE.ar.md",
"docs/TROUBLESHOOTING.ko.md",
"docs/WORKFLOW.pt.md",
"docs/CONFIGURATION.ru.md",
"docs/INTERFACES.pt.md",
"docs/TROUBLESHOOTING.fr.md",
"docs/PROMPTING-GUIDE.ja.md",
"docs/TROUBLESHOOTING.de.md",
"docs/PROMPTING-GUIDE.ko.md",
"docs/PROMPTING-GUIDE.pt.md",
"docs/DEVELOPMENT.pt.md",
"docs/PROMPTING-GUIDE.ru.md",
"docs/INTERFACES.it.md",
"docs/PROMPTING-GUIDE.zh.md",
"docs/CONFIGURATION.fr.md",
"docs/INTERFACES.md",
"docs/TOOLS-REFERENCE.it.md",
"docs/DEVELOPMENT.fr.md",
"docs/CONFIGURATION.de.md",
"docs/WORKFLOW.ko.md",
"docs/TOOLS-REFERENCE.ko.md",
"docs/TROUBLESHOOTING.it.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @pimzino/spec-workflow-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @pimzino/spec-workflow-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/with-dashboard/plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx -y @pimzino/spec-workflow-mcp@latest --dashboard` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `claude mcp add spec-workflow cmd.exe /c \"npx @pimzino/spec-workflow-mcp@latest /path/to/your/project\"` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/with-dashboard/plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.claude-plugin/with-dashboard/plugin.json`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/with-dashboard/plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.claude-plugin/with-dashboard/plugin.json`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.claude-plugin/with-dashboard/plugin.json`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/with-dashboard/plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json` Claim：`clm_0008` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/with-dashboard/plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：381\n- 重要文件覆盖：40/381\n- 证据索引条目：80\n- 角色 / Skill 条目：73\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @pimzino/spec-workflow-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @pimzino/spec-workflow-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @pimzino/spec-workflow-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 73 个角色 / Skill / 项目文档条目。\n\n- **Technical Documentation**（project_doc）：Quick Reference : Jump to what you need most → Tools API api-reference.md Architecture architecture.md Developer Guide developer-guide.md Troubleshooting troubleshooting.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/technical-documentation/README.md`\n- **Contributing Guidelines**（project_doc）：Welcome! This guide will help you contribute effectively to the Spec Workflow MCP project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/technical-documentation/contributing.md`\n- **Spec Workflow MCP**（project_doc）：! npm version https://img.shields.io/npm/v/@pimzino/spec-workflow-mcp https://www.npmjs.com/package/@pimzino/spec-workflow-mcp ! VSCode Extension https://vsmarketplacebadges.dev/version-short/Pimzino.spec-workflow-mcp.svg https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Spec-Workflow MCP Docker Setup**（project_doc）：This directory contains Docker configuration files to run the Spec-Workflow MCP dashboard in a containerized environment. This setup provides isolation and easy deployment for the dashboard service. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`containers/README.md`\n- **Spec Workflow MCP Extension**（project_doc）：A VSCode extension that provides an integrated dashboard for managing Spec-Workflow MCP projects directly in your workspace. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`vscode-extension/README.md`\n- **دليل التكوين**（project_doc）：يغطي هذا الدليل جميع خيارات التكوين لـ Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.ar.md`\n- **Konfigurationsanleitung**（project_doc）：Diese Anleitung deckt alle Konfigurationsoptionen für Spec Workflow MCP ab. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.de.md`\n- **Guía de Configuración**（project_doc）：Esta guía cubre todas las opciones de configuración para Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.es.md`\n- **Guide de configuration**（project_doc）：Ce guide couvre toutes les options de configuration pour Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.fr.md`\n- **Guida alla Configurazione**（project_doc）：Questa guida copre tutte le opzioni di configurazione per Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.it.md`\n- **設定ガイド**（project_doc）：このガイドは、Spec Workflow MCPのすべての設定オプションをカバーしています。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.ja.md`\n- **구성 가이드**（project_doc）：이 가이드는 Spec Workflow MCP의 모든 구성 옵션을 다룹니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.ko.md`\n- **Configuration Guide**（project_doc）：This guide covers all configuration options for Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.md`\n- **Guia de Configuração**（project_doc）：Este guia cobre todas as opções de configuração para Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.pt.md`\n- **Руководство по конфигурации**（project_doc）：Это руководство охватывает все параметры конфигурации для Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.ru.md`\n- **配置指南**（project_doc）：选项 描述 示例 -------- ------------- --------- --help 显示详细使用信息 npx -y @pimzino/spec-workflow-mcp@latest --help --dashboard 运行纯仪表板模式（默认端口：5000） npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 指定自定义仪表板端口（1024-65535） npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/CONFIGURATION.zh.md`\n- **دليل التطوير**（project_doc）：يغطي هذا الدليل إعداد بيئة التطوير، وبناء المشروع، والمساهمة في الكود، وفهم هندسة Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.ar.md`\n- **Entwicklungsanleitung**（project_doc）：Diese Anleitung behandelt die Einrichtung einer Entwicklungsumgebung, das Erstellen des Projekts, das Beisteuern von Code und das Verständnis der Architektur von Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.de.md`\n- **Guía de Desarrollo**（project_doc）：Esta guía cubre la configuración de un entorno de desarrollo, construcción del proyecto, contribución de código y comprensión de la arquitectura de Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.es.md`\n- **Guide de développement**（project_doc）：Ce guide couvre la configuration d'un environnement de développement, la compilation du projet, la contribution de code et la compréhension de l'architecture de Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.fr.md`\n- **Guida allo Sviluppo**（project_doc）：Questa guida copre la configurazione di un ambiente di sviluppo, la compilazione del progetto, il contributo al codice e la comprensione dell'architettura di Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.it.md`\n- **開発ガイド**（project_doc）：このガイドでは、開発環境のセットアップ、プロジェクトのビルド、コードへの貢献、およびSpec Workflow MCPのアーキテクチャの理解について説明します。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.ja.md`\n- **개발 가이드**（project_doc）：이 가이드는 개발 환경 설정, 프로젝트 빌드, 코드 기여 및 Spec Workflow MCP의 아키텍처 이해를 다룹니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.ko.md`\n- **Development Guide**（project_doc）：This guide covers setting up a development environment, building the project, contributing code, and understanding the architecture of Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.md`\n- **Guia de Desenvolvimento**（project_doc）：Este guia cobre a configuração de um ambiente de desenvolvimento, construção do projeto, contribuição de código e compreensão da arquitetura do Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.pt.md`\n- **Руководство по разработке**（project_doc）：Это руководство охватывает настройку среды разработки, сборку проекта, внесение вклада в код и понимание архитектуры Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.ru.md`\n- **开发指南**（project_doc）：本指南涵盖设置开发环境、构建项目、贡献代码以及理解 Spec Workflow MCP 的架构。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/DEVELOPMENT.zh.md`\n- **دليل الواجهات**（project_doc）：يغطي هذا الدليل الواجهتين الأساسيتين لـ Spec Workflow MCP: لوحة تحكم الويب وإضافة VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.ar.md`\n- **Oberflächen-Leitfaden**（project_doc）：Dieser Leitfaden behandelt die beiden primären Oberflächen für Spec Workflow MCP: das Web-Dashboard und die VSCode Extension. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.de.md`\n- **Guía de Interfaces**（project_doc）：Esta guía cubre las dos interfaces principales para Spec Workflow MCP: el Panel de Control Web y la Extensión para VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.es.md`\n- **Guide des interfaces**（project_doc）：Ce guide couvre les deux interfaces principales de Spec Workflow MCP : le tableau de bord web et l'extension VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.fr.md`\n- **Guida alle Interfacce**（project_doc）：Questa guida copre le due interfacce principali per Spec Workflow MCP: la Dashboard Web e l'Estensione VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.it.md`\n- **インターフェースガイド**（project_doc）：このガイドは、Spec Workflow MCPの2つの主要インターフェースについて説明します：WebダッシュボードとVSCode拡張機能。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.ja.md`\n- **인터페이스 가이드**（project_doc）：이 가이드는 Spec Workflow MCP의 두 가지 주요 인터페이스인 웹 대시보드와 VSCode 확장 프로그램을 다룹니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.ko.md`\n- **Interfaces Guide**（project_doc）：This guide covers the two primary interfaces for Spec Workflow MCP: the Web Dashboard and the VSCode Extension. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.md`\n- **Guia de Interfaces**（project_doc）：Este guia cobre as duas interfaces principais para Spec Workflow MCP: o Dashboard Web e a Extensão VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.pt.md`\n- **Руководство по интерфейсам**（project_doc）：Это руководство охватывает два основных интерфейса для Spec Workflow MCP: веб-панель управления и расширение VSCode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.ru.md`\n- **界面指南**（project_doc）：本指南涵盖 Spec Workflow MCP 的两个主要界面：Web 仪表板和 VSCode 扩展。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/INTERFACES.zh.md`\n- **دليل الأوامر**（project_doc）：دليل شامل مع أمثلة وأفضل الممارسات للتفاعل مع Spec Workflow MCP من خلال مساعدي الذكاء الاصطناعي. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.ar.md`\n- **Prompting-Leitfaden**（project_doc）：Ein umfassender Leitfaden mit Beispielen und Best Practices für die Interaktion mit Spec Workflow MCP durch AI-Assistenten. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.de.md`\n- **Guía de Prompts**（project_doc）：Una guía completa con ejemplos y mejores prácticas para interactuar con Spec Workflow MCP a través de asistentes de IA. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.es.md`\n- **Guide de Prompting**（project_doc）：Un guide complet avec des exemples et des meilleures pratiques pour interagir avec Spec Workflow MCP via les assistants IA. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.fr.md`\n- **Guida ai Prompt**（project_doc）：Una guida completa con esempi e best practice per interagire con Spec Workflow MCP tramite assistenti AI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.it.md`\n- **プロンプティングガイド**（project_doc）：AIアシスタントを通じてSpec Workflow MCPと対話するための包括的なガイドで、例とベストプラクティスを掲載しています。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.ja.md`\n- **프롬프팅 가이드**（project_doc）：AI 어시스턴트를 통해 Spec Workflow MCP와 상호작용하기 위한 예제와 모범 사례가 포함된 종합 가이드입니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.ko.md`\n- **Prompting Guide**（project_doc）：A comprehensive guide with examples and best practices for interacting with Spec Workflow MCP through AI assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.md`\n- **Guia de Prompts**（project_doc）：Um guia abrangente com exemplos e melhores práticas para interagir com Spec Workflow MCP através de assistentes de IA. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.pt.md`\n- **Руководство по запросам**（project_doc）：Подробное руководство с примерами и лучшими практиками для взаимодействия с Spec Workflow MCP через AI-ассистентов. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.ru.md`\n- **提示指南**（project_doc）：一个全面的指南，包含通过 AI 助手与 Spec Workflow MCP 交互的示例和最佳实践。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PROMPTING-GUIDE.zh.md`\n- **مرجع الأدوات**（project_doc）：وثائق كاملة لجميع أدوات MCP المقدمة من Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.ar.md`\n- **Tools-Referenz**（project_doc）：Vollständige Dokumentation für alle MCP-Tools, die von Spec Workflow MCP bereitgestellt werden. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.de.md`\n- **Referencia de Herramientas**（project_doc）：Documentación completa para todas las herramientas MCP proporcionadas por Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.es.md`\n- **Référence des Outils**（project_doc）：Documentation complète pour tous les outils MCP fournis par Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.fr.md`\n- **Riferimento Strumenti**（project_doc）：Documentazione completa per tutti gli strumenti MCP forniti da Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.it.md`\n- **ツールリファレンス**（project_doc）：Spec Workflow MCPが提供するすべてのMCPツールの完全なドキュメント。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.ja.md`\n- **도구 참조**（project_doc）：Spec Workflow MCP에서 제공하는 모든 MCP 도구에 대한 완전한 문서입니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.ko.md`\n- **Tools Reference**（project_doc）：Complete documentation for all MCP tools provided by Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.md`\n- **Referência de Ferramentas**（project_doc）：Documentação completa para todas as ferramentas MCP fornecidas pelo Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.pt.md`\n- **Справочник инструментов**（project_doc）：Полная документация для всех инструментов MCP, предоставляемых Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.ru.md`\n- **工具参考**（project_doc）：Spec Workflow MCP 提供的所有 MCP 工具的完整文档。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TOOLS-REFERENCE.zh.md`\n- **دليل استكشاف الأخطاء وإصلاحها**（project_doc）：يساعدك هذا الدليل في حل المشكلات الشائعة مع Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.ar.md`\n- **Fehlerbehebungsanleitung**（project_doc）：Diese Anleitung hilft Ihnen, häufige Probleme mit Spec Workflow MCP zu lösen. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.de.md`\n- **Guía de Solución de Problemas**（project_doc）：Esta guía te ayuda a resolver problemas comunes con Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.es.md`\n- **Guide de Dépannage**（project_doc）：Ce guide vous aide à résoudre les problèmes courants avec Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.fr.md`\n- **Guida alla Risoluzione Problemi**（project_doc）：Questa guida ti aiuta a risolvere problemi comuni con Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.it.md`\n- **トラブルシューティングガイド**（project_doc）：Spec Workflow MCPに関する一般的な問題を解決するためのガイドです。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.ja.md`\n- **문제 해결 가이드**（project_doc）：이 가이드는 Spec Workflow MCP의 일반적인 문제를 해결하는 데 도움이 됩니다. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.ko.md`\n- **Troubleshooting Guide**（project_doc）：This guide helps you resolve common issues with Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.md`\n- **Guia de Solução de Problemas**（project_doc）：Este guia ajuda você a resolver problemas comuns com Spec Workflow MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.pt.md`\n- **Руководство по устранению неполадок**（project_doc）：Руководство по устранению неполадок 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.ru.md`\n- **故障排除指南**（project_doc）：检查安装 bash 验证 npm 包是否可访问 npx -y @pimzino/spec-workflow-mcp@latest --help 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/TROUBLESHOOTING.zh.md`\n- **دليل المستخدم**（project_doc）：دليل شامل لاستخدام Spec Workflow MCP للتطوير البرمجي بمساعدة الذكاء الاصطناعي. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/USER-GUIDE.ar.md`\n- **Benutzerhandbuch**（project_doc）：Ein umfassender Leitfaden zur Verwendung von Spec Workflow MCP für KI-gestützte Softwareentwicklung. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/USER-GUIDE.de.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Technical Documentation**（documentation）：Quick Reference : Jump to what you need most → Tools API api-reference.md Architecture architecture.md Developer Guide developer-guide.md Troubleshooting troubleshooting.md 证据：`docs/technical-documentation/README.md`\n- **Contributing Guidelines**（documentation）：Welcome! This guide will help you contribute effectively to the Spec Workflow MCP project. 证据：`docs/technical-documentation/contributing.md`\n- **Spec Workflow MCP**（documentation）：! npm version https://img.shields.io/npm/v/@pimzino/spec-workflow-mcp https://www.npmjs.com/package/@pimzino/spec-workflow-mcp ! VSCode Extension https://vsmarketplacebadges.dev/version-short/Pimzino.spec-workflow-mcp.svg https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp 证据：`README.md`\n- **Spec-Workflow MCP Docker Setup**（documentation）：This directory contains Docker configuration files to run the Spec-Workflow MCP dashboard in a containerized environment. This setup provides isolation and easy deployment for the dashboard service. 证据：`containers/README.md`\n- **Spec Workflow MCP Extension**（documentation）：A VSCode extension that provides an integrated dashboard for managing Spec-Workflow MCP projects directly in your workspace. 证据：`vscode-extension/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@pimzino/spec-workflow-mcp\", \"version\": \"2.2.7\", \"description\": \"MCP server for spec-driven development workflow with real-time web dashboard\", \"main\": \"dist/index.js\", \"type\": \"module\", \"bin\": { \"spec-workflow-mcp\": \"dist/index.js\" }, \"files\": \"dist/ / \", \"README.md\", \"CHANGELOG.md\", \"LICENSE\" , \"scripts\": { \"build\": \"npm run validate:i18n && npm run clean && tsc && npm run build:dashboard\", \"copy-static\": \"node scripts/copy-static.cjs\", \"dev\": \"tsx src/index.ts\", \"start\": \"node dist/index.js\", \"dev:dashboard\": \"vite --config src/dashboard frontend/vite.config.ts\", \"build:dashboard\": \"vite build --config src/dashboard frontend/vite.config.ts && npm run copy-static\", \"clean\": \"ri… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"spec-workflow-mcp\", \"displayName\": \"%displayName%\", \"description\": \"%description%\", \"version\": \"1.1.7\", \"publisher\": \"Pimzino\", \"license\": \"GPL-3.0\", \"icon\": \"icon.png\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Pimzino/spec-workflow-mcp.git\" }, \"engines\": { \"vscode\": \"^1.99.0\" }, \"categories\": \"Other\" , \"keywords\": \"spec\", \"workflow\", \"mcp\", \"dashboard\", \"project management\" , \"activationEvents\": \"onStartupFinished\" , \"main\": \"./dist/extension.js\", \"contributes\": { \"commands\": { \"command\": \"spec-workflow.openDashboard\", \"title\": \"%command.openDashboard%\", \"category\": \"Spec Workflow\" }, { \"command\": \"spec-workflow.refreshData\", \"title\": \"%command.refreshData%\", \"c… 证据：`vscode-extension/package.json`\n- **Marketplace**（structured_config）：{ \"name\": \"spec-workflow-mcp-marketplace\", \"owner\": { \"name\": \"Pimzino\" }, \"metadata\": { \"description\": \"Spec Workflow MCP provides structured spec-driven development with a sequential workflow Requirements → Design → Tasks , real-time web dashboard, and VSCode extension support. Includes human approval gates at each stage and project steering guidance.\" }, \"plugins\": { \"name\": \"spec-workflow-mcp\", \"version\": \"2.2.6\", \"description\": \"MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.\", \"author\": { \"name\": \"Pimzino\" }, \"license\": \"GPL-3.0\", \"homepage\": \"https://github.com/Pimzino/spec-workflow-mcp\", \"source\": \"./.claude-plugin\" }, { \"name\": \"… 证据：`.claude-plugin/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"spec-workflow-mcp\", \"version\": \"2.2.6\", \"description\": \"MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.\", \"author\": { \"name\": \"Pimzino\" }, \"homepage\": \"https://github.com/Pimzino/spec-workflow-mcp\", \"license\": \"GPL-3.0\" } 证据：`.claude-plugin/plugin.json`\n- **Plugin**（structured_config）：{ \"name\": \"spec-workflow-mcp-with-dashboard\", \"version\": \"2.2.6\", \"description\": \"MCP server with auto-started dashboard for structured spec-driven development.\", \"author\": { \"name\": \"Pimzino\" }, \"homepage\": \"https://github.com/Pimzino/spec-workflow-mcp\", \"license\": \"GPL-3.0\" } 证据：`.claude-plugin/with-dashboard/plugin.json`\n- **License**（source_file）：GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 证据：`LICENSE`\n- **License**（source_file）：GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 证据：`vscode-extension/LICENSE`\n- **دليل التكوين**（documentation）：يغطي هذا الدليل جميع خيارات التكوين لـ Spec Workflow MCP. 证据：`docs/CONFIGURATION.ar.md`\n- **Konfigurationsanleitung**（documentation）：Diese Anleitung deckt alle Konfigurationsoptionen für Spec Workflow MCP ab. 证据：`docs/CONFIGURATION.de.md`\n- **Guía de Configuración**（documentation）：Esta guía cubre todas las opciones de configuración para Spec Workflow MCP. 证据：`docs/CONFIGURATION.es.md`\n- **Guide de configuration**（documentation）：Ce guide couvre toutes les options de configuration pour Spec Workflow MCP. 证据：`docs/CONFIGURATION.fr.md`\n- **Guida alla Configurazione**（documentation）：Questa guida copre tutte le opzioni di configurazione per Spec Workflow MCP. 证据：`docs/CONFIGURATION.it.md`\n- **設定ガイド**（documentation）：このガイドは、Spec Workflow MCPのすべての設定オプションをカバーしています。 证据：`docs/CONFIGURATION.ja.md`\n- **구성 가이드**（documentation）：이 가이드는 Spec Workflow MCP의 모든 구성 옵션을 다룹니다. 证据：`docs/CONFIGURATION.ko.md`\n- **Configuration Guide**（documentation）：This guide covers all configuration options for Spec Workflow MCP. 证据：`docs/CONFIGURATION.md`\n- **Guia de Configuração**（documentation）：Este guia cobre todas as opções de configuração para Spec Workflow MCP. 证据：`docs/CONFIGURATION.pt.md`\n- **Руководство по конфигурации**（documentation）：Это руководство охватывает все параметры конфигурации для Spec Workflow MCP. 证据：`docs/CONFIGURATION.ru.md`\n- **配置指南**（documentation）：选项 描述 示例 -------- ------------- --------- --help 显示详细使用信息 npx -y @pimzino/spec-workflow-mcp@latest --help --dashboard 运行纯仪表板模式（默认端口：5000） npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 指定自定义仪表板端口（1024-65535） npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080 证据：`docs/CONFIGURATION.zh.md`\n- **دليل التطوير**（documentation）：يغطي هذا الدليل إعداد بيئة التطوير، وبناء المشروع، والمساهمة في الكود، وفهم هندسة Spec Workflow MCP. 证据：`docs/DEVELOPMENT.ar.md`\n- **Entwicklungsanleitung**（documentation）：Diese Anleitung behandelt die Einrichtung einer Entwicklungsumgebung, das Erstellen des Projekts, das Beisteuern von Code und das Verständnis der Architektur von Spec Workflow MCP. 证据：`docs/DEVELOPMENT.de.md`\n- **Guía de Desarrollo**（documentation）：Esta guía cubre la configuración de un entorno de desarrollo, construcción del proyecto, contribución de código y comprensión de la arquitectura de Spec Workflow MCP. 证据：`docs/DEVELOPMENT.es.md`\n- **Guide de développement**（documentation）：Ce guide couvre la configuration d'un environnement de développement, la compilation du projet, la contribution de code et la compréhension de l'architecture de Spec Workflow MCP. 证据：`docs/DEVELOPMENT.fr.md`\n- **Guida allo Sviluppo**（documentation）：Questa guida copre la configurazione di un ambiente di sviluppo, la compilazione del progetto, il contributo al codice e la comprensione dell'architettura di Spec Workflow MCP. 证据：`docs/DEVELOPMENT.it.md`\n- **開発ガイド**（documentation）：このガイドでは、開発環境のセットアップ、プロジェクトのビルド、コードへの貢献、およびSpec Workflow MCPのアーキテクチャの理解について説明します。 证据：`docs/DEVELOPMENT.ja.md`\n- **개발 가이드**（documentation）：이 가이드는 개발 환경 설정, 프로젝트 빌드, 코드 기여 및 Spec Workflow MCP의 아키텍처 이해를 다룹니다. 证据：`docs/DEVELOPMENT.ko.md`\n- **Development Guide**（documentation）：This guide covers setting up a development environment, building the project, contributing code, and understanding the architecture of Spec Workflow MCP. 证据：`docs/DEVELOPMENT.md`\n- **Guia de Desenvolvimento**（documentation）：Este guia cobre a configuração de um ambiente de desenvolvimento, construção do projeto, contribuição de código e compreensão da arquitetura do Spec Workflow MCP. 证据：`docs/DEVELOPMENT.pt.md`\n- **Руководство по разработке**（documentation）：Это руководство охватывает настройку среды разработки, сборку проекта, внесение вклада в код и понимание архитектуры Spec Workflow MCP. 证据：`docs/DEVELOPMENT.ru.md`\n- **开发指南**（documentation）：本指南涵盖设置开发环境、构建项目、贡献代码以及理解 Spec Workflow MCP 的架构。 证据：`docs/DEVELOPMENT.zh.md`\n- **دليل الواجهات**（documentation）：يغطي هذا الدليل الواجهتين الأساسيتين لـ Spec Workflow MCP: لوحة تحكم الويب وإضافة VSCode. 证据：`docs/INTERFACES.ar.md`\n- **Oberflächen-Leitfaden**（documentation）：Dieser Leitfaden behandelt die beiden primären Oberflächen für Spec Workflow MCP: das Web-Dashboard und die VSCode Extension. 证据：`docs/INTERFACES.de.md`\n- **Guía de Interfaces**（documentation）：Esta guía cubre las dos interfaces principales para Spec Workflow MCP: el Panel de Control Web y la Extensión para VSCode. 证据：`docs/INTERFACES.es.md`\n- **Guide des interfaces**（documentation）：Ce guide couvre les deux interfaces principales de Spec Workflow MCP : le tableau de bord web et l'extension VSCode. 证据：`docs/INTERFACES.fr.md`\n- **Guida alle Interfacce**（documentation）：Questa guida copre le due interfacce principali per Spec Workflow MCP: la Dashboard Web e l'Estensione VSCode. 证据：`docs/INTERFACES.it.md`\n- **インターフェースガイド**（documentation）：このガイドは、Spec Workflow MCPの2つの主要インターフェースについて説明します：WebダッシュボードとVSCode拡張機能。 证据：`docs/INTERFACES.ja.md`\n- **인터페이스 가이드**（documentation）：이 가이드는 Spec Workflow MCP의 두 가지 주요 인터페이스인 웹 대시보드와 VSCode 확장 프로그램을 다룹니다. 证据：`docs/INTERFACES.ko.md`\n- **Interfaces Guide**（documentation）：This guide covers the two primary interfaces for Spec Workflow MCP: the Web Dashboard and the VSCode Extension. 证据：`docs/INTERFACES.md`\n- **Guia de Interfaces**（documentation）：Este guia cobre as duas interfaces principais para Spec Workflow MCP: o Dashboard Web e a Extensão VSCode. 证据：`docs/INTERFACES.pt.md`\n- **Руководство по интерфейсам**（documentation）：Это руководство охватывает два основных интерфейса для Spec Workflow MCP: веб-панель управления и расширение VSCode. 证据：`docs/INTERFACES.ru.md`\n- **界面指南**（documentation）：本指南涵盖 Spec Workflow MCP 的两个主要界面：Web 仪表板和 VSCode 扩展。 证据：`docs/INTERFACES.zh.md`\n- **دليل الأوامر**（documentation）：دليل شامل مع أمثلة وأفضل الممارسات للتفاعل مع Spec Workflow MCP من خلال مساعدي الذكاء الاصطناعي. 证据：`docs/PROMPTING-GUIDE.ar.md`\n- **Prompting-Leitfaden**（documentation）：Ein umfassender Leitfaden mit Beispielen und Best Practices für die Interaktion mit Spec Workflow MCP durch AI-Assistenten. 证据：`docs/PROMPTING-GUIDE.de.md`\n- **Guía de Prompts**（documentation）：Una guía completa con ejemplos y mejores prácticas para interactuar con Spec Workflow MCP a través de asistentes de IA. 证据：`docs/PROMPTING-GUIDE.es.md`\n- **Guide de Prompting**（documentation）：Un guide complet avec des exemples et des meilleures pratiques pour interagir avec Spec Workflow MCP via les assistants IA. 证据：`docs/PROMPTING-GUIDE.fr.md`\n- **Guida ai Prompt**（documentation）：Una guida completa con esempi e best practice per interagire con Spec Workflow MCP tramite assistenti AI. 证据：`docs/PROMPTING-GUIDE.it.md`\n- **プロンプティングガイド**（documentation）：AIアシスタントを通じてSpec Workflow MCPと対話するための包括的なガイドで、例とベストプラクティスを掲載しています。 证据：`docs/PROMPTING-GUIDE.ja.md`\n- **프롬프팅 가이드**（documentation）：AI 어시스턴트를 통해 Spec Workflow MCP와 상호작용하기 위한 예제와 모범 사례가 포함된 종합 가이드입니다. 证据：`docs/PROMPTING-GUIDE.ko.md`\n- **Prompting Guide**（documentation）：A comprehensive guide with examples and best practices for interacting with Spec Workflow MCP through AI assistants. 证据：`docs/PROMPTING-GUIDE.md`\n- **Guia de Prompts**（documentation）：Um guia abrangente com exemplos e melhores práticas para interagir com Spec Workflow MCP através de assistentes de IA. 证据：`docs/PROMPTING-GUIDE.pt.md`\n- **Руководство по запросам**（documentation）：Подробное руководство с примерами и лучшими практиками для взаимодействия с Spec Workflow MCP через AI-ассистентов. 证据：`docs/PROMPTING-GUIDE.ru.md`\n- **提示指南**（documentation）：一个全面的指南，包含通过 AI 助手与 Spec Workflow MCP 交互的示例和最佳实践。 证据：`docs/PROMPTING-GUIDE.zh.md`\n- **مرجع الأدوات**（documentation）：وثائق كاملة لجميع أدوات MCP المقدمة من Spec Workflow MCP. 证据：`docs/TOOLS-REFERENCE.ar.md`\n- **Tools-Referenz**（documentation）：Vollständige Dokumentation für alle MCP-Tools, die von Spec Workflow MCP bereitgestellt werden. 证据：`docs/TOOLS-REFERENCE.de.md`\n- **Referencia de Herramientas**（documentation）：Documentación completa para todas las herramientas MCP proporcionadas por Spec Workflow MCP. 证据：`docs/TOOLS-REFERENCE.es.md`\n- **Référence des Outils**（documentation）：Documentation complète pour tous les outils MCP fournis par Spec Workflow MCP. 证据：`docs/TOOLS-REFERENCE.fr.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/technical-documentation/README.md`, `docs/technical-documentation/contributing.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/technical-documentation/README.md`, `docs/technical-documentation/contributing.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, src/index.ts, package.json\n- **快速开始**：importance `high`\n - source_paths: docs/USER-GUIDE.md, docs/PROMPTING-GUIDE.md, containers/example.mcp.json\n- **安装配置**：importance `high`\n - source_paths: docs/CONFIGURATION.md, src/config.ts, src/core/global-dir.ts\n- **系统架构**：importance `high`\n - source_paths: src/server.ts, src/dashboard/multi-server.ts, src/dashboard/watcher.ts, src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx\n- **文件结构**：importance `medium`\n - source_paths: docs/technical-documentation/file-structure.md, src/markdown/templates/design-template.md, src/markdown/templates/requirements-template.md, src/markdown/templates/tasks-template.md\n- **规格工作流程**：importance `high`\n - source_paths: docs/WORKFLOW.md, src/prompts/create-spec.ts, src/prompts/implement-task.ts, src/core/task-parser.ts\n- **审批系统**：importance `high`\n - source_paths: src/tools/approvals.ts, src/dashboard/approval-storage.ts, src/tools/steering-guide.ts, src/dashboard_frontend/src/modules/approvals\n- **任务管理**：importance `high`\n - source_paths: src/core/task-parser.ts, src/core/task-validator.ts, src/dashboard/implementation-log-manager.ts, src/tools/log-implementation.ts, src/dashboard_frontend/src/modules/components/KanbanBoard.tsx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `b63e6cd8d6ed53bbc48fe93d634f7b548285762f`\n- inspected_files: `package.json`, `README.md`, `docs/TROUBLESHOOTING.ar.md`, `docs/INTERFACES.zh.md`, `docs/DEVELOPMENT.ko.md`, `docs/PROMPTING-GUIDE.es.md`, `docs/DEVELOPMENT.it.md`, `docs/WORKFLOW.ar.md`, `docs/DEVELOPMENT.de.md`, `docs/TOOLS-REFERENCE.ar.md`, `docs/PROMPTING-GUIDE.md`, `docs/USER-GUIDE.ru.md`, `docs/TOOLS-REFERENCE.md`, `docs/PROMPTING-GUIDE.de.md`, `docs/TROUBLESHOOTING.es.md`, `docs/TOOLS-REFERENCE.ru.md`, `docs/TROUBLESHOOTING.md`, `docs/CONFIGURATION.zh.md`, `docs/PROMPTING-GUIDE.ar.md`, `docs/TROUBLESHOOTING.ko.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug]: Bug Report for spec-workflow-mcp\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: 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.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Pimzino/spec-workflow-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 来源证据：[Bug]: Bug Report for spec-workflow-mcp（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Pimzino/spec-workflow-mcp 项目说明书\n\n生成时间：2026-05-14 07:49:06 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [安装配置](#page-installation)\n- [系统架构](#page-architecture)\n- [文件结构](#page-file-structure)\n- [规格工作流程](#page-spec-workflow)\n- [审批系统](#page-approval-system)\n- [任务管理](#page-task-management)\n- [Web 仪表板](#page-dashboard)\n- [VSCode 扩展](#page-vscode-extension)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n- [vscode-extension/src/webview/index.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n- [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)\n \n\n# 项目概述\n\n## 简介\n\nspec-workflow-mcp 是一个基于 Model Context Protocol (MCP) 的开发工作流管理系统，旨在为 AI 辅助软件开发提供规范化的项目管理和协作框架。该项目通过 MCP 协议与各种 AI 工具（如 Cursor、Claude Desktop、VSCode 等）集成，帮助开发团队在 AI 驱动的开发环境中维护一致的规范、追踪任务进度、管理审批流程，并记录实现日志。\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 核心功能\n\n### MCP 协议集成\n\n作为 MCP 服务器运行，spec-workflow-mcp 提供了一套完整的工具集，使 AI 助手能够与本地项目进行深度交互。开发者可以通过简单的配置将项目目录与各种 AI 客户端连接，从而获得规范感知的工作流支持。\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### 规范文档管理\n\n项目支持创建和维护以下核心规范文档：\n\n| 文档类型 | 描述 | 位置 |\n|---------|------|------|\n| Specs | 软件规格说明文档 | `.spec-workflow/specs/` |\n| Steering | 方向指引文档（product.md、tech.md、structure.md） | `.spec-workflow/steering/` |\n| Templates | 文档模板 | `.spec-workflow/templates/` |\n| Approvals | 审批记录 | `.spec-workflow/approvals/` |\n| Archive | 归档文档 | `.spec-workflow/archive/` |\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n### 实现日志追踪\n\n系统会自动记录 AI 生成的代码变更，包括修改的文件、创建的文件、代码统计（新增/删除行数）以及生成的各类产物（API 端点、组件、函数、类、集成点等）。这一功能确保了开发过程的可追溯性，便于团队审查和回溯。\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## 技术架构\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[AI 客户端
Cursor/Claude Desktop/VSCode] -->|MCP 协议| B[spec-workflow-mcp
MCP Server]\n B --> C[规范存储层
.spec-workflow 目录]\n B --> D[Web Dashboard
端口 5000]\n B --> E[VSCode 扩展
内嵌 Webview]\n \n C --> F[Specs 文档]\n C --> G[Steering 文档]\n C --> H[Approvals 审批]\n C --> I[Archive 归档]\n C --> J[实现日志]\n \n D --> K[React 前端]\n E --> L[React Webview]\n```\n\n### 前端技术栈\n\n项目采用现代化的前端技术构建用户界面：\n\n- **React**: 核心 UI 框架\n- **TypeScript**: 类型安全保证\n- **Tailwind CSS**: 样式解决方案\n- **i18n 国际化**: 支持多语言切换\n\nVSCode 扩展的 Webview 使用独立的模块化架构，包含主入口文件、i18n 模块和全局样式资源。\n\n资料来源：[vscode-extension/src/webview/index.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n\n### REST API 架构\n\nDashboard 后端提供丰富的 REST API 端点，主要包括：\n\n| API 类别 | 端点模式 | 功能 |\n|---------|---------|------|\n| Specs | `GET/PUT /specs/:name` | 获取/更新规格文档 |\n| Tasks | `GET/PUT /specs/:name/tasks/:id/status` | 任务状态管理 |\n| Approvals | `POST /approvals/:id/:action` | 审批操作 |\n| Batch | `POST /approvals/batch/:action` | 批量审批 |\n| Snapshots | `GET /approvals/:id/snapshots/:version` | 版本快照 |\n\n资料来源：[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)\n\n## 部署方式\n\n### 标准部署\n\n项目支持通过 npx 直接运行，配置方式因客户端而异：\n\n**Cursor 配置示例：**\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n**Claude Desktop 配置：**\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Docker 容器部署\n\n项目提供完整的 Docker 支持，适合隔离部署场景：\n\n```bash\n# 使用 Docker Compose（推荐）\ncd containers\ndocker-compose up --build\n\n# 或使用 Docker CLI\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\nDashboard 访问地址：`http://localhost:5000`\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 安全特性\n\nspec-workflow-mcp 实现了企业级的安全控制措施：\n\n| 安全特性 | 描述 |\n|---------|------|\n| 本地绑定 | 默认绑定 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、动作和结果 |\n| 安全响应头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 项目结构\n\n### 典型项目目录布局\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档的规范文档\n specs/ # 活动规格文档\n steering/ # 方向指引文档\n templates/ # 文档模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n### 开发环境\n\n```bash\n# 安装依赖\nnpm install\n\n# 编译项目\nnpm run build\n\n# 开发模式运行\nnpm run dev\n```\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n## 许可协议\n\n本项目采用 GPL-3.0 开源许可证发布。\n\n资料来源：[README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [安装配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [docs/USER-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/USER-GUIDE.md)\n- [docs/PROMPTING-GUIDE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/PROMPTING-GUIDE.md)\n- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)\n- [containers/example.mcp.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/example.mcp.json)\n \n\n# 快速开始\n\n本页面提供 spec-workflow-mcp 项目的快速上手指南，帮助用户在最短时间内完成环境配置并开始使用规范驱动的工作流程。\n\n## 概述\n\nspec-workflow-mcp 是一个基于规范驱动（Specification-Driven）的开发工作流程管理工具，通过 MCP（Model Context Protocol）协议与 AI 工具集成，帮助开发团队在 AI 辅助环境下高效管理项目开发流程。\n\n快速开始指南旨在为用户提供：\n\n- 环境配置的最简路径\n- 与 AI 工具集成的标准方式\n- 界面选择与启动方法\n- 首个项目规范文档的创建流程\n\n资料来源：[README.md:1-50]()\n\n## 环境要求\n\n### 系统要求\n\n| 要求类型 | 最低版本 | 推荐版本 |\n|---------|---------|---------|\n| Node.js | 18.x | 20.x LTS |\n| npm | 9.x | 10.x |\n| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | macOS 14+ / Ubuntu 22.04+ / Windows 11 |\n\n### AI 工具兼容性\n\nspec-workflow-mcp 通过 MCP 协议与以下 AI 工具集成：\n\n- Claude Desktop\n- Cursor\n- VS Code (通过扩展)\n- 其他支持 MCP 协议的工具\n\n资料来源：[containers/example.mcp.json:1-30]()\n\n## 安装方式\n\n### 方式一：MCP 配置集成（推荐）\n\n将 spec-workflow-mcp 添加到 AI 工具的 MCP 配置中：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n> **注意**：将 `/path/to/your/project` 替换为实际项目路径。\n\n### 方式二：全局安装\n\n```bash\nnpm install -g @pimzino/spec-workflow-mcp\n```\n\n### 方式三：项目本地安装\n\n```bash\nnpm install @pimzino/spec-workflow-mcp\n```\n\n资料来源：[README.md:15-35]()\n\n## 界面选择\n\n根据使用场景，spec-workflow-mcp 提供两种界面选项：\n\n### Web 仪表盘\n\n适用于 CLI 用户和跨项目管理者。\n\n启动命令：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表盘访问地址：`http://localhost:5000`\n\n### VSCode 扩展\n\n适用于 VSCode 用户，提供无缝的编辑体验。\n\n安装方式：在 VSCode 扩展市场搜索 \"Spec Workflow\" 并安装。\n\n资料来源：[docs/INTERFACES.md:1-50]()\n\n## 项目初始化\n\n### 自动初始化\n\n首次使用 MCP 工具时，系统会自动创建 `.spec-workflow` 目录结构：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档规范存储\n specs/ # 规范文档存储\n steering/ # 指导文档存储\n templates/ # 规范模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置文件示例\n```\n\n### 配置文件\n\n复制并编辑配置文件：\n\n```bash\ncp .spec-workflow/config.example.toml .spec-workflow/config.toml\n```\n\n主要配置项：\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| `dashboard.port` | 仪表盘端口 | 5000 |\n| `dashboard.host` | 仪表盘主机 | localhost |\n| `specs.directory` | 规范文档目录 | specs |\n| `archive.enabled` | 是否启用归档 | true |\n\n资料来源：[docs/USER-GUIDE.md:10-80]()\n\n## 工作流程概览\n\n### 标准开发流程\n\n```mermaid\ngraph TD\n A[创建规范文档] --> B[定义任务清单]\n B --> C[AI 执行任务]\n C --> D{任务验证}\n D -->|通过| E[更新规范进度]\n D -->|失败| F[修订或重新执行]\n E --> G{所有任务完成?}\n G -->|否| B\n G -->|是| H[归档规范]\n F --> C\n```\n\n### 规范文档结构\n\n每个规范文档包含以下核心部分：\n\n1. **元数据**：名称、版本、状态\n2. **概述**：功能描述和目标\n3. **任务清单**：具体实现任务及状态\n4. **验收标准**：完成条件定义\n\n资料来源：[docs/PROMPTING-GUIDE.md:1-60]()\n\n## 首次使用指南\n\n### 步骤一：创建首个规范\n\n在 AI 对话中描述要实现的功能，系统将自动生成规范文档框架：\n\n```\n请帮我创建一个新的规范文档，用于实现用户认证功能。\n```\n\n### 步骤二：审查规范\n\n使用仪表盘或 VSCode 扩展查看生成的规范文档，确认任务分解正确。\n\n### 步骤三：执行任务\n\n按照任务清单逐项执行，AI 将根据规范要求辅助代码实现。\n\n### 步骤四：跟踪进度\n\n通过仪表盘的任务面板实时查看进度更新。\n\n### 步骤五：归档完成\n\n规范所有任务完成后，将规范移至归档目录保存。\n\n资料来源：[docs/USER-GUIDE.md:80-150]()\n\n## 常见问题\n\n### 问题一：仪表盘无法启动\n\n**解决方案**：\n\n```bash\n# 检查端口占用\nlsof -i :5000\n\n# 使用其他端口\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 5001\n```\n\n### 问题二：MCP 连接失败\n\n**解决方案**：\n\n1. 确认 Node.js 版本 >= 18.x\n2. 检查 MCP 配置文件语法\n3. 重启 AI 工具\n\n### 问题三：规范文档未自动创建\n\n**解决方案**：手动创建 `.spec-workflow` 目录结构，确保 `specs/` 子目录存在。\n\n资料来源：[docs/USER-GUIDE.md:150-200]()\n\n## 下一步\n\n完成快速开始后，建议继续阅读以下文档：\n\n- [用户指南](docs/USER-GUIDE.md) - 深入了解所有功能\n- [提示工程指南](docs/PROMPTING-GUIDE.md) - 优化 AI 交互\n- [接口指南](docs/INTERFACES.md) - 仪表盘和扩展详细说明\n- [开发指南](docs/DEVELOPMENT.md) - 参与项目开发\n\n---\n\n\n\n## 安装配置\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [README.ko.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n- [docs/CONFIGURATION.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md)\n- [src/config.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/config.ts)\n \n\n# 安装配置\n\n## 概述\n\nspec-workflow-mcp 是一个基于 MCP（Model Context Protocol）协议的 AI 辅助开发工作流工具。它通过标准化规范（spec）驱动的方式，帮助开发团队协调 AI 工具与人类开发者之间的协作。安装配置是整个系统的入口点，正确配置 MCP 服务器是将 spec-workflow 集成到现有开发环境的关键步骤。\n\n该工具支持多种主流 AI 编程工具的集成，包括 Claude Desktop、Claude Code CLI、Cline、Cursor、Continue 以及 VSCode 扩展程序。配置方式根据不同的客户端略有差异，但核心概念相同：启动 MCP 服务器并指向项目目录。\n\n## 项目目录结构\n\nspec-workflow-mcp 在项目根目录创建一个 `.spec-workflow` 隐藏目录，用于存储所有配置、规范文档和历史记录。\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批文件存储\n archive/ # 归档的规范文档\n specs/ # 规范文档主目录\n steering/ # 引导文件目录\n templates/ # 内置模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置文件模板\n```\n\n资料来源：[README.md:45-54]()\n\n`.spec-workflow` 目录结构设计遵循单一职责原则，每个子目录管理特定类型的数据。规范文档存储在 `specs/` 中，审批流程相关文件存储在 `approvals/`，而 `archive/` 用于存放已完成的规范文档以便追溯。\n\n## MCP 服务器配置\n\n### 核心配置参数\n\nMCP 服务器通过 `mcpServers` 配置节进行定义，主要参数如下：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| command | string | 是 | 执行命令，通常为 `npx` |\n| args | array | 是 | 命令参数数组 |\n| 路径参数 | string | 是 | 目标项目目录的绝对或相对路径 |\n\n标准的 npx 启动命令格式为：\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n}\n```\n\n资料来源：[README.md:18-24]()\n\n参数说明：\n- `-y` 标志用于跳过 npm 安装确认提示，实现更流畅的自动化安装流程\n- `@pimzino/spec-workflow-mcp@latest` 指定包名称和版本号\n- 最后一个参数是项目目录的绝对路径或相对路径\n\n### 各客户端配置方式\n\n#### Claude Desktop\n\nClaude Desktop 的配置文件位于 `claude_desktop_config.json`，配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n> **重要提示**：在启动 MCP 服务器之前，需要单独运行 `--dashboard` 命令启动仪表板。\n\n资料来源：[README.md:75-89]()\n\n#### Claude Code CLI\n\n对于 Claude Code CLI，需要使用 `mcp add` 命令添加服务器：\n\n```bash\nclaude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project\n```\n\n**关键要点**：\n- `-y` 标志用于跳过 npm 提示，确保自动化安装\n- `--` 分隔符确保路径参数被传递给 spec-workflow 脚本而非 npx\n\nWindows 用户如果上述命令不生效，可以使用替代方案：\n\n```bash\nclaude mcp add spec-workflow cmd.exe /c \"npx @pimzino/spec-workflow-mcp@latest /path/to/your/project\"\n```\n\n资料来源：[README.md:31-47]()\n\n#### Cline / Claude Dev\n\n在 Cline 或 Claude Dev 中添加 MCP 服务器配置：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:95-103]()\n\n#### Continue IDE Extension\n\nContinue 配置使用相同的 JSON 格式：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:107-115]()\n\n#### Cursor IDE\n\nCursor 的配置需添加到 `settings.json` 中：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n资料来源：[README.md:119-127]()\n\n#### Codex\n\nCodex 使用 TOML 格式配置文件，位于 `~/.codex/config.toml`：\n\n```toml\n[mcp_servers.spec-workflow]\ncommand = \"npx\"\nargs = [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n```\n\n资料来源：[README.md:140-144]()\n\n## 仪表板配置\n\n### Web 仪表板\n\nWeb 仪表板是 CLI 用户的推荐接口，启动命令：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表板默认运行在 `http://localhost:5000`。\n\n> **重要说明**：只需要一个仪表板实例，所有项目都连接到同一个仪表板。\n\n资料来源：[README.ko.md:22-29]()\n\n### Docker 部署\n\n对于隔离部署环境，spec-workflow-mcp 支持 Docker 容器化运行：\n\n#### 使用 Docker Compose（推荐方式）\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n#### 使用 Docker CLI\n\n```bash\n# 构建镜像\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\n\n# 运行容器\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\nDocker 部署会将容器内的 `/workspace/.spec-workflow` 目录映射到宿主机的 `./workspace/.spec-workflow`，确保数据持久化。\n\n资料来源：[README.md:146-157]()\n\n## 安全配置\n\n### 安全控制特性\n\nspec-workflow-mcp 包含企业级安全功能，适用于企业环境：\n\n| 安全特性 | 说明 |\n|---------|------|\n| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端每分钟 120 次请求，自动清理 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者、操作和结果 |\n| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n资料来源：[README.md:164-174]()\n\n### 本地绑定\n\n默认情况下，Web 仪表板仅监听 `127.0.0.1`（localhost），这确保了：\n- 只有本机浏览器可以访问仪表板\n- 外部网络无法连接到服务\n- 适用于开发和测试环境\n\n### 速率限制\n\n系统实现了请求速率限制机制：\n- 每分钟每客户端 120 个请求\n- 超过限制的请求会被拒绝\n- 自动清理过期记录以释放资源\n\n## 本地开发配置\n\n### 安装依赖\n\n```bash\nnpm install\n```\n\n资料来源：[README.md:60]()\n\n### 构建项目\n\n```bash\nnpm run build\n```\n\n构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist/` 目录。\n\n### 开发模式运行\n\n```bash\nnpm run dev\n```\n\n开发模式提供热重载功能，代码修改后自动重新编译和重启服务。\n\n资料来源：[README.md:61-67]()\n\n## 配置验证\n\n### 验证步骤\n\n1. **检查 MCP 服务器状态**：在对应的 AI 工具中确认 MCP 服务器已正确加载\n2. **验证仪表板连接**：访问 `http://localhost:5000` 确认 Web 仪表板可访问\n3. **检查项目目录**：确认 `.spec-workflow` 目录已在项目根目录创建\n4. **测试规范创建**：尝试创建一个新的规范文档验证写入权限\n\n### 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|---------|---------|\n| MCP 服务器无法启动 | npx 未安装或版本过旧 | 安装最新版本的 Node.js 和 npm |\n| 仪表板无法访问 | 端口 5000 被占用 | 更换端口或终止占用进程 |\n| 权限错误 | 项目目录不可写 | 检查目录权限设置 |\n| 路径解析失败 | 相对路径未正确解析 | 使用绝对路径替代相对路径 |\n\n## 扩展配置\n\n### VSCode 扩展配置\n\nVSCode 用户可以使用专门的扩展程序，获得更好的集成体验：\n\n```bash\n# 从 VSCode Marketplace 安装扩展\n# 然后在扩展设置中配置项目路径\n```\n\nVSCode 扩展提供了内联的用户界面，无需单独启动 Web 仪表板。\n\n资料来源：[README.ko.md:31-35]()\n\n### 多项目配置\n\nspec-workflow-mcp 支持同时管理多个项目：\n\n1. 每个项目需要独立的 `.spec-workflow` 目录\n2. 所有项目可以共享同一个仪表板实例\n3. 在 MCP 配置中使用不同的路径参数指向各项目\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow-project-a\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project-a\"]\n },\n \"spec-workflow-project-b\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project-b\"]\n }\n }\n}\n```\n\n## 配置架构图\n\n```mermaid\ngraph TD\n A[用户开发环境] --> B[AI 编程工具]\n B --> C[MCP 客户端]\n C --> D[MCP 服务器]\n D --> E[spec-workflow-mcp 核心]\n E --> F[.spec-workflow 目录]\n E --> G[Web 仪表板]\n E --> H[文件系统]\n \n F --> I[specs/ 规范文档]\n F --> J[approvals/ 审批]\n F --> K[archive/ 归档]\n F --> L[steering/ 引导]\n F --> M[templates/ 模板]\n \n G --> N[localhost:5000]\n \n style A fill:#e1f5fe\n style G fill:#fff3e0\n style F fill:#f3e5f5\n```\n\n## 下一步\n\n配置完成后，建议阅读以下文档：\n\n- [工作流指南](docs/WORKFLOW.md) - 开发工作流和最佳实践\n- [接口指南](docs/INTERFACES.md) - 仪表板和 VSCode 扩展详情\n- [工具参考](docs/TOOLS-REFERENCE.md) - 完整工具文档\n- [故障排除](docs/TROUBLESHOOTING.md) - 常见问题及解决方案\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[文件结构](#page-file-structure), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/server.ts)\n- [src/dashboard/multi-server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/multi-server.ts)\n- [src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n- [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)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [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)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n \n\n# 系统架构\n\n## 概述\n\nSpec-Workflow-MCP 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统，旨在为 AI 驱动的软件开发提供结构化的规格管理和实现跟踪能力。该系统采用模块化架构设计，支持多个项目连接至单一仪表板实例，实现跨项目的规格、任务和实施日志的统一管理。\n\n系统的核心设计理念是将 AI 开发过程的结构化，通过规格文档（Spec）、任务拆解、实施日志等机制，确保 AI 生成的代码与预期规格保持一致。\n\n## 整体架构\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n VSCode[VSCode 扩展]\n CLI[CLI 工具]\n 其他AI[其他 MCP 客户端]\n end\n \n subgraph \"核心服务层\"\n MCP[MCP 服务器]\n WS[WebSocket 服务]\n API[REST API 服务]\n end\n \n subgraph \"仪表板层\"\n Dashboard[Web 仪表板]\n Frontend[React 前端]\n end\n \n subgraph \"数据层\"\n FS[文件系统存储]\n LogDB[实施日志]\n Config[项目配置]\n end\n \n VSCode --> MCP\n CLI --> MCP\n 其他AI --> MCP\n \n MCP --> WS\n MCP --> FS\n MCP --> LogDB\n \n WS <--> Dashboard\n Dashboard --> Frontend\n \n Dashboard --> Config\n Frontend --> Config\n```\n\n## 核心组件\n\n### MCP 服务器\n\nMCP 服务器是系统的核心入口点，负责处理来自各种 AI 工具的请求。服务器启动时加载项目配置，建立文件系统监控，并注册 MCP 工具集。\n\n| 组件 | 说明 | 端口/路径 |\n|------|------|----------|\n| MCP Server | 处理 AI 工具请求的核心服务器 | 标准输入/输出 |\n| Dashboard Server | Web 仪表板服务器 | 5000 |\n| WebSocket Server | 实时通信服务 | 与仪表板共享端口 |\n\n服务器支持两种运行模式：独立 MCP 模式和仪表板模式。运行 MCP 模式时，服务器通过标准输入输出与 AI 客户端通信；运行仪表板模式时，启动 Web 服务器提供可视化界面。\n\n### 多服务器管理\n\n系统采用多服务器架构，允许连接多个项目至同一个仪表板实例：\n\n```mermaid\ngraph LR\n subgraph \"Dashboard Instance\"\n DM[仪表板管理器]\n CM[连接管理器]\n PM[项目管理器]\n end\n \n P1[项目 1]\n P2[项目 2]\n P3[项目 N]\n \n DM --> CM\n CM --> PM\n \n P1 <--> PM\n P2 <--> PM\n P3 <--> PM\n```\n\n每个连接的项目维护独立的配置和状态，仪表板通过项目标识符进行区分和路由。\n\n### 文件系统监控\n\n文件监控模块负责实时跟踪 `.spec-workflow` 目录下的变更：\n\n资料来源：[src/dashboard/watcher.ts]()\n\n| 功能 | 描述 |\n|------|------|\n| 规格监控 | 监听 specs 目录下的规格文件变更 |\n| 任务跟踪 | 监控任务状态文件的变化 |\n| 实施日志 | 记录文件创建和修改事件 |\n| 归档检测 | 检测已归档规格的状态变化 |\n\n文件变更通过 WebSocket 实时推送至前端界面，实现多客户端的状态同步。\n\n## 前端架构\n\n### Web 仪表板\n\nWeb 仪表板基于 React 构建，提供完整的项目管理和监控界面：\n\n```mermaid\ngraph TD\n App[主应用]\n Overview[概览页]\n Tasks[任务页]\n Logs[日志页]\n Settings[设置页]\n \n App --> Overview\n App --> Tasks\n App --> Logs\n App --> Settings\n \n Overview --> WS[WebSocket 连接]\n Tasks --> WS\n Logs --> WS\n \n WS --> Provider[WebSocket Provider]\n```\n\n#### 页面模块\n\n| 页面 | 功能 |\n|------|------|\n| 概览页 | 显示项目统计、规格完成度、任务进度 |\n| 任务页 | 看板和列表两种视图，支持状态筛选和排序 |\n| 日志页 | 展示实施日志，包括文件变更、统计信息、工件记录 |\n| 设置页 | 管理自动清理任务、API 端点配置 |\n\n### WebSocket 通信\n\nWebSocket 模块负责客户端与服务端之间的实时双向通信：\n\n资料来源：[src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx]()\n\n```mermaid\nsequenceDiagram\n participant Client as 前端客户端\n participant WS as WebSocket Provider\n participant Server as Dashboard Server\n \n Client->>WS: 建立连接\n WS->>Server: 初始化 WebSocket 连接\n \n Server->>WS: 连接状态更新\n WS->>Client: 状态同步\n \n loop 文件变更监控\n Server->>WS: 发送变更事件\n WS->>Client: 广播更新\n end\n \n Client->>WS: 发送操作请求\n WS->>Server: 转发请求\n```\n\nWebSocket Provider 维护连接状态，处理重连逻辑，并向下游组件提供状态更新上下文。\n\n### VSCode 扩展\n\nVSCode 扩展提供嵌入式开发体验：\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n```\n┌─────────────────────────────────────┐\n│ VSCode Extension │\n├─────────────────────────────────────┤\n│ Webview Container │\n│ ┌───────────────────────────────┐ │\n│ │ React Application │ │\n│ │ ├─ Overview Panel │ │\n│ │ ├─ Task List │ │\n│ │ ├─ Implementation Logs │ │\n│ │ └─ Settings │ │\n│ └───────────────────────────────┘ │\n├─────────────────────────────────────┤\n│ VSCode API Integration │\n│ ├─ File System Watcher │ │\n│ ├─ Status Bar Updates │ │\n│ └─ Command Palette │ │\n└─────────────────────────────────────┘\n```\n\n扩展通过 WebView 与主进程通信，利用 VSCode 原生 API 实现文件系统监控和 UI 集成。\n\n## 数据模型\n\n### 项目结构\n\n```\n项目根目录/\n .spec-workflow/\n approvals/ # 审批文件\n archive/ # 已归档规格\n specs/ # 规格文档\n steering/ # 方向性文档\n templates/ # 模板文件\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n### 实施日志条目\n\n系统记录每次规格实施的完整信息：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| timestamp | Date | 执行时间戳 |\n| specification | string | 关联规格 |\n| status | string | 执行状态 |\n| filesModified | string[] | 修改的文件列表 |\n| filesCreated | string[] | 创建的文件列表 |\n| statistics | object | 代码统计（行数增删等） |\n| artifacts | object | 工件记录 |\n\n### 工件类型\n\n| 类型 | 说明 |\n|------|------|\n| apiEndpoints | API 端点定义 |\n| components | UI 组件 |\n| functions | 函数定义 |\n| classes | 类定义 |\n| integrations | 集成点 |\n\n## 安全机制\n\n系统实现了企业级安全特性：\n\n```mermaid\ngraph LR\n subgraph \"安全层\"\n RATE[速率限制]\n CORS[CORS 保护]\n HEAD[安全头]\n LOG[审计日志]\n end\n \n Request[请求] --> RATE\n RATE --> CORS\n CORS --> HEAD\n HEAD --> LOG\n```\n\n| 安全功能 | 说明 |\n|----------|------|\n| 本地绑定 | 默认绑定至 127.0.0.1，防止网络暴露 |\n| 速率限制 | 每客户端 120 请求/分钟，自动清理 |\n| 审计日志 | 结构化 JSON 日志，记录时间戳、操作者、动作和结果 |\n| 安全头 | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| CORS 保护 | 限制跨域访问 |\n\n## 部署模式\n\n### Docker 部署\n\n系统支持 Docker 容器化部署：\n\n```dockerfile\n# 容器结构\n┌─────────────────────────────┐\n│ spec-workflow-mcp │\n├─────────────────────────────┤\n│ Node.js Runtime │\n│ ├─ Dashboard Server │\n│ ├─ WebSocket Server │\n│ └─ MCP Protocol Handler │\n└─────────────────────────────┘\n```\n\n容器部署命令：\n\n```bash\n# Docker Compose 方式\ncd containers\ndocker-compose up --build\n\n# Docker CLI 方式\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\ndocker run -p 5000:5000 -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" spec-workflow-mcp\n```\n\n### MCP 客户端集成\n\n系统作为 MCP 服务器运行，支持多种 AI 工具客户端：\n\n资料来源：[README.md]()\n\n| 客户端 | 配置方式 |\n|--------|----------|\n| Claude Desktop | settings.json |\n| Cline/Claude Dev | MCP 配置 |\n| Continue | MCP 配置 |\n| Cursor IDE | settings.json |\n| Codex | config.toml |\n\n## 实时同步机制\n\n```mermaid\ngraph TB\n subgraph \"变更源\"\n File[文件变更]\n User[用户操作]\n AI[AI 执行]\n end\n \n File --> Watcher[文件系统监控]\n User --> API[API 调用]\n AI --> MCP[MCP 执行]\n \n Watcher --> Event[变更事件]\n API --> Event\n MCP --> Event\n \n Event --> Broadcast[广播至所有客户端]\n \n Broadcast --> WS1[Dashboard 1]\n Broadcast --> WS2[Dashboard 2]\n Broadcast --> WS3[VSCode Extension]\n```\n\n所有连接至同一仪表板实例的客户端共享状态视图，确保多端操作的一致性。\n\n---\n\n\n\n## 文件结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [规格工作流程](#page-spec-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n- [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)\n- [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)\n- [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)\n \n\n# 文件结构\n\n## 概述\n\n`spec-workflow-mcp` 是一个基于 MCP（Model Context Protocol）的规格工作流管理系统。该项目采用**前后端分离架构**，包含核心业务逻辑层、仪表板前端以及 VSCode 扩展三大部分。文件结构设计遵循模块化原则，将核心功能、界面展示和编辑器扩展清晰地分离在不同的目录中。 资料来源：[README.fr.md:1-10]()\n\n## 顶层目录结构\n\n```\nspec-workflow-mcp/\n├── .spec-workflow/ # 项目规范配置目录\n├── src/ # 核心业务逻辑\n├── vscode-extension/ # VSCode 扩展\n├── vscode-extension/\n│ └── webview-dist/ # 构建产物\n├── src/dashboard_frontend/ # 仪表板前端\n└── docs/ # 文档\n```\n\n## `.spec-workflow/` 规范目录结构\n\n`.spec-workflow/` 目录是项目的工作空间根目录，包含了规格驱动的所有配置文件和文档模板。 资料来源：[README.fr.md:25-35]()\n\n| 目录名 | 用途 |\n|--------|------|\n| `approvals/` | 存放规格审批文件 |\n| `archive/` | 归档已完成或废弃的规格 |\n| `specs/` | 存放活跃的规格文档 |\n| `steering/` | 存放指导性文档 |\n| `templates/` | 系统内置模板 |\n| `user-templates/` | 用户自定义模板 |\n| `config.example.toml` | 配置文件示例 |\n\n## 核心业务逻辑层 (`src/`)\n\n`src/` 目录包含了系统的主要业务逻辑，采用 TypeScript 实现。\n\n### 核心模块 (`src/core/`)\n\n核心模块包含系统的基础功能组件：\n\n| 文件 | 职责 |\n|------|------|\n| `implementation-log-migrator.ts` | 实现日志的数据迁移和格式化转换 |\n\n### 仪表板模块 (`src/dashboard/`)\n\n仪表板模块负责实现日志管理和数据展示功能：\n\n| 文件 | 职责 |\n|------|------|\n| `implementation-log-manager.ts` | 实现日志的添加、查询、格式化和导出功能 |\n\n### Markdown 模板 (`src/markdown/templates/`)\n\n模板系统用于生成标准化的项目文档：\n\n| 模板文件 | 用途 |\n|----------|------|\n| `design-template.md` | 设计文档模板 |\n| `requirements-template.md` | 需求文档模板 |\n| `tasks-template.md` | 任务清单模板 |\n\n## 仪表板前端 (`src/dashboard_frontend/`)\n\n仪表板前端是一个独立的 Web 应用，提供图形化界面来管理规格工作流。\n\n### 页面模块 (`src/dashboard_frontend/src/modules/pages/`)\n\n| 页面文件 | 功能描述 |\n|----------|----------|\n| `TasksPage.tsx` | 任务管理页面，包含进度跟踪和任务列表展示 |\n| `LogsPage.tsx` | 实现日志页面，展示文件变更、创建和统计数据 |\n| `SteeringPage.tsx` | 指导文档页面，提供项目文档导航 |\n| `JobExecutionHistory.tsx` | 作业执行历史页面，记录批处理任务执行情况 |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[用户界面] --> B[任务页面 TasksPage]\n A --> C[日志页面 LogsPage]\n A --> D[指导页面 SteeringPage]\n A --> E[执行历史 JobExecutionHistory]\n B --> F[核心服务层]\n C --> F\n D --> F\n E --> F\n F --> G[spec-workflow 核心]\n G --> H[文件系统]\n```\n\n## VSCode 扩展 (`vscode-extension/`)\n\nVSCode 扩展为开发者提供了在编辑器内直接访问规格工作流的能力。\n\n### Web 视图源文件 (`vscode-extension/src/webview/`)\n\n| 文件/目录 | 用途 |\n|-----------|------|\n| `App.tsx` | 主应用组件，包含项目概览和任务列表 |\n| `index.html` | Web 视图入口 HTML |\n| `comment-modal.html` | 注释模态框 HTML |\n| `components/LogEntryCard.tsx` | 日志条目卡片组件 |\n\n### Web 视图组件关系\n\n```mermaid\ngraph LR\n A[index.html] --> B[main.tsx]\n A --> C[App.tsx]\n B --> D[React 应用挂载]\n C --> E[LogEntryCard]\n C --> F[任务列表]\n C --> G[项目统计]\n E --> H[ArtifactSection]\n```\n\n### 构建产物 (`vscode-extension/webview-dist/`)\n\n构建后的静态资源用于 VSCode 扩展的实际运行：\n\n| 文件 | 对应源文件 |\n|------|------------|\n| `index.html` | 编译后的主入口 |\n| `comment-modal.html` | 编译后的注释模态框 |\n| `main.js` | 打包后的主应用代码 |\n| `comment-modal.js` | 打包后的模态框代码 |\n| `globals.css` | 全局样式 |\n| `i18n.js` | 国际化资源 |\n\n## 实现日志数据结构\n\n系统通过 `ImplementationLogEntry` 接口管理实现日志，包含以下关键字段： 资料来源：[src/dashboard/implementation-log-manager.ts:1-20]()\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 日志唯一标识符 |\n| `timestamp` | Date | 创建时间戳 |\n| `summary` | string | 实现摘要 |\n| `statistics` | object | 代码统计信息（文件数、行数变更等） |\n| `filesModified` | string[] | 修改的文件列表 |\n| `filesCreated` | string[] | 创建的文件列表 |\n| `artifacts` | object | 生成的代码构件 |\n\n### Artifacts 子结构\n\n`artifacts` 对象包含多种代码构件类型的记录： 资料来源：[src/dashboard/implementation-log-manager.ts:30-60]()\n\n| 构件类型 | 字段说明 |\n|----------|----------|\n| `apiEndpoints` | API 端点：method、path、purpose、location、requestFormat、responseFormat |\n| `components` | 组件：name、type、purpose、location、props、exports |\n| `functions` | 函数：name、purpose、location、signature、isExported |\n| `classes` | 类：name、purpose、location、methods、isExported |\n| `integrations` | 集成：description、frontendComponent、backendEndpoint、dataFlow |\n\n## 前端组件架构\n\n### 任务页面组件 (`TasksPage.tsx`)\n\n任务页面负责展示和管理规格任务，包含以下核心功能： 资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx:1-50]()\n\n- **进度追踪**：显示任务完成百分比和总体进度条\n- **任务列表**：支持列表和网格视图切换\n- **元数据展示**：展示 Purpose、Requirements、Leverage、Prompt 等任务属性\n- **AI 提示词**：可展开的 AI 生成提示词查看器\n\n### 日志页面组件 (`LogsPage.tsx`)\n\n日志页面提供实现日志的详细查看功能： 资料来源：[src/dashboard_frontend/src/modules/pages/LogsPage.tsx:1-40]()\n\n- **统计数据**：文件变更数、净变更行数\n- **文件变更列表**：展示修改和创建的文件路径\n- **构件展示**：按类型分类展示生成的代码构件\n\n### 日志卡片组件 (`LogEntryCard.tsx`)\n\n日志条目卡片组件用于在 VSCode 扩展中渲染单个日志条目： 资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx:1-80]()\n\n```typescript\ninterface LogEntryCardProps {\n entry: ImplementationLogEntry;\n}\n```\n\n## 多语言支持\n\n项目包含国际化（i18n）支持，通过 `i18n.js` 模块提供多语言文本资源。已确认的语言版本包括：\n\n- 英语（默认）\n- 法语（`README.fr.md`）\n\n## 构建与部署\n\n### 前端构建\n\n```bash\nnpm install\nnpm run build\n```\n\n### VSCode 扩展构建\n\nVSCode 扩展的 Web 视图代码独立构建到 `webview-dist/` 目录，然后与扩展主体打包。 资料来源：[vscode-extension/webview-dist/index.html:1-20]()\n\n### 开发模式\n\n```bash\nnpm run dev\n```\n\n## 架构总览图\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[仪表板前端
React + TypeScript]\n B[VSCode 扩展 WebView]\n end\n \n subgraph 核心层\n C[实现日志管理
implementation-log-manager]\n D[日志迁移器
implementation-log-migrator]\n E[Markdown 模板系统]\n end\n \n subgraph 数据层\n F[.spec-workflow/ 目录]\n G[配置文件]\n end\n \n A --> C\n B --> C\n C --> D\n C --> F\n D --> F\n E --> F\n```\n\n## 总结\n\n`spec-workflow-mcp` 项目采用清晰的分层架构设计：\n\n1. **核心层** (`src/core/`) 提供业务逻辑和数据处理能力\n2. **仪表板层** (`src/dashboard/` + `src/dashboard_frontend/`) 提供独立的 Web 管理界面\n3. **扩展层** (`vscode-extension/`) 提供编辑器集成功能\n4. **模板层** (`src/markdown/templates/`) 确保文档标准化\n\n这种模块化设计使得系统各部分可以独立开发、测试和部署，同时保持良好的可维护性和可扩展性。\n\n---\n\n\n\n## 规格工作流程\n\n### 相关页面\n\n相关主题：[任务管理](#page-task-management), [审批系统](#page-approval-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/WORKFLOW.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/WORKFLOW.md)\n- [src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n- [src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n- [src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n \n\n# 规格工作流程\n\n## 概述\n\n规格工作流程（Spec Workflow）是 spec-workflow-mcp 项目的核心功能模块，为 AI 代码助手提供结构化的项目开发流程管理能力。该工作流程通过规范化的文档创建、审批和执行机制，帮助开发团队在 AI 辅助编程环境中保持开发目标的一致性和可追溯性。\n\n规格工作流程的主要目标是：\n\n- 在项目启动阶段建立清晰的产品愿景和技术架构\n- 将大型需求拆解为可执行的小粒度任务\n- 通过审批流程确保 AI 生成的内容符合预期\n- 记录实现过程中的关键产物，便于后续维护\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## 核心概念\n\n### 规格文档类型\n\n规格工作流程使用多种类型的文档来组织项目信息：\n\n| 文档类型 | 文件路径 | 用途 |\n|---------|---------|------|\n| 产品文档 | `.spec-workflow/steering/product.md` | 定义产品愿景、目标用户和关键特性 |\n| 技术文档 | `.spec-workflow/steering/tech.md` | 记录技术架构决策和技术栈 |\n| 结构文档 | `.spec-workflow/steering/structure.md` | 描述代码库组织结构和模块架构 |\n| 设计文档 | `.spec-workflow/specs/{name}/design.md` | 具体规格的设计说明 |\n| 任务文档 | `.spec-workflow/specs/{name}/tasks.md` | 将设计拆解为可执行任务 |\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### 模板系统\n\n系统支持自定义模板，允许用户覆盖默认模板行为：\n\n- 用户自定义模板优先：`.spec-workflow/user-templates/`\n- 默认模板：`.spec-workflow/templates/`\n\n支持的模板文件包括：`product-template.md`、`tech-template.md`、`structure-template.md`、`design-template.md`、`tasks-template.md`\n\n## 引导文档工作流程\n\n引导文档（Steering Documents）是项目的顶层规划文档，包括产品愿景、技术架构和代码结构三个核心文档。\n\n### 工作流程阶段\n\n引导文档工作流程分为三个阶段：\n\n```mermaid\ngraph TD\n Start([开始]) --> P1_Template[检查用户模板
user-templates/]\n P1_Template --> P1_Read{是否有自定义模板?}\n P1_Read -->|是| P1_Custom[读取自定义模板]\n P1_Read -->|否| P1_Default[读取默认模板
templates/]\n P1_Custom --> P1_Analyze[分析产品需求]\n P1_Default --> P1_Analyze\n P1_Analyze --> P1_Create[创建文件
steering/product.md]\n P1_Create --> P1_Approve[approvals
action: request
filePath only]\n P1_Approve --> P1_Status[approvals
action: status
轮询状态]\n P1_Status --> P1_Check{状态?}\n P1_Check -->|needs-revision| P1_Update[根据用户评论更新文档]\n P1_Update --> P1_Create\n P1_Check -->|approved| P1_Clean[approvals
action: delete]\n P1_Clean -->|失败| P1_Status\n P1_Clean -->|成功| P2_Template\n\n P2_Template --> P2_Read[检查技术模板]\n P2_Read --> P2_Analyze[分析技术栈]\n P2_Analyze --> P2_Create[创建文件
steering/tech.md]\n P2_Create --> P2_Approve[approvals
action: request]\n P2_Approve --> P2_Status[轮询状态]\n P2_Status --> P2_Check{状态?}\n P2_Check -->|needs-revision| P2_Update\n P2_Update --> P2_Create\n P2_Check -->|approved| P2_Clean[删除审批]\n P2_Clean -->|成功| P3_Template\n\n P3_Template --> P3_Read[检查结构模板]\n P3_Read --> P3_Analyze[分析代码结构]\n P3_Analyze --> P3_Create[创建文件
steering/structure.md]\n P3_Create --> P3_Approve[approvals
action: request]\n P3_Approve --> P3_Status[轮询状态]\n P3_Status --> P3_Check{状态?}\n P3_Check -->|needs-revision| P3_Update\n P3_Update --> P3_Create\n P3_Check -->|approved| P3_Clean\n P3_Clean -->|成功| Complete([引导文档完成])\n\n style Start fill:#e6f3ff\n style Complete fill:#e6f3ff\n style P1_Check fill:#ffe6e6\n style P2_Check fill:#ffe6e6\n style P3_Check fill:#ffe6e6\n```\n\n### 第一阶段：产品文档\n\n**目的**：定义愿景、目标和用户成果。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/product-template.md`\n- 读取模板：`.spec-workflow/templates/product-template.md`（无自定义模板时）\n- 创建文档：`.spec-workflow/steering/product.md`\n\n**流程**：\n\n1. 检查自定义模板\n2. 分析现有产品需求\n3. 创建 `product.md`\n4. 使用 approvals 工具请求审批\n5. 轮询审批状态直到 approved/needs-revision\n6. 若 needs-revision：根据评论更新文档，创建新审批\n7. 审批通过后：使用 approvals action:delete 删除审批记录\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### 第二阶段：技术文档\n\n**目的**：记录技术决策和架构设计。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/tech-template.md`\n- 读取模板：`.spec-workflow/templates/tech-template.md`\n- 创建文档：`.spec-workflow/steering/tech.md`\n\n**流程**：同产品文档阶段\n\n### 第三阶段：结构文档\n\n**目的**：映射代码库组织和模式。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/structure-template.md`\n- 读取模板：`.spec-workflow/templates/structure-template.md`\n- 创建文档：`.spec-workflow/steering/structure.md`\n\n## 规格创建工作流程\n\n规格创建工作流程用于生成具体的项目规格文档，包括设计文档和任务列表。\n\n### 工作流程阶段\n\n```mermaid\ngraph TD\n Start([开始]) --> P1_Template[检查设计模板]\n P1_Template --> P1_Read[读取模板内容]\n P1_Read --> P1_Analyze[分析需求]\n P1_Analyze --> P1_Create[创建文件
specs/{name}/design.md]\n P1_Create --> P1_Approve[请求审批]\n P1_Approve --> P1_Status[轮询状态]\n P1_Status --> P1_Check{状态?}\n P1_Check -->|needs-revision| P1_Update[更新文档]\n P1_Update --> P1_Create\n P1_Check -->|approved| P1_Clean[删除审批]\n P1_Clean -->|成功| P2_Ready\n\n P2_Ready([就绪]) --> P2_Template[检查任务模板]\n P2_Template --> P2_Break[将设计拆解为任务]\n P2_Break --> P2_Create[创建文件
specs/{name}/tasks.md]\n P2_Create --> P2_Approve[请求审批]\n P2_Approve --> P2_Status[轮询状态]\n P2_Status --> P2_Check{状态?}\n P2_Check -->|needs-revision| P2_Update[更新任务]\n P2_Update --> P2_Create\n P2_Check -->|approved| P2_Clean\n P2_Clean -->|成功| P3_Ready\n\n P3_Ready([就绪]) --> P3_Impl[执行任务实现]\n\n style Start fill:#e6f3ff\n style P3_Ready fill:#e6f3ff\n style P1_Check fill:#ffe6e6\n style P2_Check fill:#ffe6e6\n```\n\n### 第一阶段：设计文档\n\n**目的**：详细描述规格的设计方案。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/design-template.md`\n- 读取模板：`.spec-workflow/templates/design-template.md`\n- 创建文档：`.spec-workflow/specs/{name}/design.md`\n\n### 第二阶段：任务文档\n\n**目的**：将设计方案转换为可执行任务列表。\n\n**文件操作**：\n\n- 检查自定义模板：`.spec-workflow/user-templates/tasks-template.md`\n- 读取模板：`.spec-workflow/templates/tasks-template.md`\n- 创建文档：`.spec-workflow/specs/{name}/tasks.md`\n\n**任务拆解要求**：\n\n- 每个任务应具有清晰的完成标准\n- 任务之间应保持独立性\n- 明确任务的依赖关系\n\n资料来源：[src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n\n## 审批系统\n\n审批系统是规格工作流程的质量保障机制，确保 AI 生成的内容经过人工确认后再执行。\n\n### 审批操作\n\n| 操作 | 参数 | 说明 |\n|-----|------|------|\n| request | filePath | 创建新的审批请求 |\n| status | - | 查询当前审批状态 |\n| delete | - | 审批通过后删除记录 |\n\n### 审批状态\n\n| 状态 | 含义 | 后续操作 |\n|-----|------|---------|\n| pending | 等待审批 | 继续轮询 |\n| approved | 已批准 | 删除审批并继续下一步 |\n| needs-revision | 需要修改 | 根据评论更新文档，重新请求审批 |\n\n### 审批流程状态图\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: request\n Pending --> Approved: 用户批准\n Pending --> NeedsRevision: 用户要求修改\n NeedsRevision --> Pending: 更新后重新请求\n Approved --> [*]: delete\n NeedsRevision --> [*]: 取消\n```\n\n## 项目结构\n\n完整的项目结构如下：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批记录存储\n archive/ # 归档的规格文档\n specs/ # 规格文档目录\n {name}/\n design.md # 设计文档\n tasks.md # 任务文档\n steering/ # 引导文档目录\n product.md # 产品文档\n tech.md # 技术文档\n structure.md # 结构文档\n templates/ # 默认模板\n user-templates/ # 用户自定义模板\n config.example.toml # 配置示例\n```\n\n## 工具引用\n\n### 主要工具\n\n| 工具名称 | 功能 | 源文件 |\n|---------|------|--------|\n| steering-guide | 加载引导文档工作流指令 | src/tools/steering-guide.ts |\n| spec-workflow-guide | 加载规格创建工作流指令 | src/tools/spec-workflow-guide.ts |\n| approvals | 管理审批工作流 | 工具模块 |\n\n### 工作流工具参数\n\n```typescript\n// steering-guide 工具\ninterface SteeringGuideParams {\n action: 'getInstructions' | 'execute';\n phase?: 'product' | 'tech' | 'structure';\n}\n\n// approvals 工具\ninterface ApprovalsParams {\n action: 'request' | 'status' | 'delete';\n filePath?: string;\n}\n\n// spec-workflow-guide 工具\ninterface SpecWorkflowParams {\n action: 'getInstructions' | 'execute';\n specName?: string;\n phase?: 'design' | 'tasks';\n}\n```\n\n## 任务解析器\n\n任务解析器（Task Parser）负责将任务文档解析为可执行的任务列表。\n\n### 解析流程\n\n```mermaid\ngraph LR\n A[tasks.md] --> B[task-parser.ts]\n B --> C{解析任务}\n C --> D[验证任务格式]\n D --> E[提取任务属性]\n E --> F[返回任务列表]\n```\n\n### 任务属性\n\n| 属性 | 说明 | 来源 |\n|-----|------|------|\n| id | 唯一标识符 | 文档解析 |\n| title | 任务标题 | 文档解析 |\n| description | 任务描述 | 文档解析 |\n| status | 执行状态 | 运行时更新 |\n| leverage | 杠杆值 | 用户指定 |\n\n资料来源：[src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n\n## 实现日志\n\n实现日志（Implementation Log）用于记录任务执行过程中的关键信息。\n\n### 日志条目结构\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n taskId: string;\n summary: string;\n filesModified: string[];\n filesCreated: string[];\n artifacts: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n statistics: {\n linesAdded: number;\n linesRemoved: number;\n };\n}\n```\n\n### 生成的报告格式\n\n实现日志支持导出为 Markdown 格式的报告，包含以下章节：\n\n- 实现摘要\n- 修改的文件列表\n- 创建的文件列表\n- 产物详情（API 端点、组件、函数、类、集成）\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## 接口选项\n\n规格工作流程提供两种用户界面：\n\n### 网页仪表盘\n\n- 默认端口：5000\n- 启动命令：`npx -y @pimzino/spec-workflow-mcp@latest --dashboard`\n- 访问地址：http://localhost:5000\n- 特点：集中管理，一个实例可供所有项目使用\n\n### VSCode 扩展\n\n- 集成到 VSCode 编辑器\n- 提供内联任务管理和审批功能\n- 适合 VSCode 用户\n\n## 配置\n\n### MCP 服务器配置\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n### 配置文件\n\n项目根目录下的 `config.example.toml` 提供了配置选项示例。\n\n## 许可证\n\n本项目采用 GPL-3.0 开源许可证。\n\n---\n\n\n\n## 审批系统\n\n### 相关页面\n\n相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n- [src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/dashboard_frontend/src/modules/approvals](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/approvals)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [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)\n \n\n# 审批系统\n\n## 概述\n\n审批系统（Approval System）是 spec-workflow-mcp 项目中用于管理和追踪文档审批流程的核心模块。该系统贯穿整个规范工作流，从产品文档、技术文档、结构文档到任务文档的创建和更新，都需要经过审批环节才能完成。\n\n审批系统的设计遵循以下核心原则：\n\n- **请求-审批-状态轮询**模式：每次文档创建或更新都需要发起审批请求，并通过轮询机制追踪审批状态\n- **批量操作支持**：支持多选模式下的批量批准或拒绝操作\n- **状态驱动的流程控制**：通过状态检查点（needs-revision/approved）决定下一步操作\n- **多端一致性**：VSCode 扩展和 Web Dashboard 提供统一的审批界面\n\n## 架构设计\n\n### 系统组件\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ 审批系统架构 │\n├─────────────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ VSCode │ │ Web │ │ MCP │ │\n│ │ 扩展 │ │ Dashboard │ │ Server │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │\n│ └────────────────┼────────────────┘ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ 审批存储层 │ │\n│ │ approval-storage.ts │ │\n│ └──────────┬──────────┘ │\n│ ▼ │\n│ ┌─────────────────────┐ │\n│ │ 文件系统 │ │\n│ │ .spec-workflow/ │ │\n│ │ approvals/ │ │\n│ └─────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### 核心模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|---------|------|\n| 审批工具 | `src/tools/approvals.ts` | 提供 `request`、`status`、`delete` 等审批操作函数 |\n| 审批存储 | `src/dashboard/approval-storage.ts` | 管理审批记录的文件持久化 |\n| 审批页面 | `src/dashboard_frontend/src/modules/pages/ApprovalsPage.tsx` | Web Dashboard 审批 UI |\n| VSCode 组件 | `vscode-extension/src/webview/App.tsx` | VSCode 扩展内的审批卡片组件 |\n\n## 审批工作流\n\n### 完整状态流程\n\n```mermaid\ngraph TD\n Start([开始]) --> Request[发起审批请求]\n Request --> Status[轮询审批状态]\n Status --> Check{状态检查}\n Check -->|needs-revision| Update[根据用户评论更新文档]\n Update --> Request\n Check -->|approved| Clean[删除审批记录]\n Clean -->|success| Complete([流程完成])\n Clean -->|failed| Status\n Check -->|rejected| Rejected([审批拒绝])\n```\n\n### 各阶段的审批操作\n\n根据工作流定义，审批操作分为三种类型：\n\n| 操作类型 | 用途 | 触发条件 |\n|---------|------|---------|\n| `request` | 发起新的审批请求 | 文档创建或更新后 |\n| `status` | 轮询审批状态 | 请求后持续检查 |\n| `delete` | 删除已完成的审批记录 | 审批状态为 approved 后 |\n\n资料来源：[src/tools/spec-workflow-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-workflow-guide.ts)\n\n### 各阶段的审批节点\n\n审批系统应用于以下工作流阶段：\n\n```mermaid\ngraph LR\n subgraph 产品文档阶段\n P1_Request[approvals
action: request]\n P1_Status[approvals
action: status]\n end\n \n subgraph 技术文档阶段\n P2_Request[approvals
action: request]\n P2_Status[approvals
action: status]\n end\n \n subgraph 结构文档阶段\n P3_Request[approvals
action: request]\n P3_Status[approvals
action: status]\n end\n \n subgraph 设计文档阶段\n D_Request[approvals
action: request]\n D_Status[approvals
action: status]\n end\n \n subgraph 任务阶段\n T_Request[approvals
action: request]\n T_Status[approvals
action: status]\n end\n```\n\n每个阶段的审批流程遵循相同的模式：创建文档 → 请求审批 → 轮询状态 → 根据结果更新或完成。\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n## 数据模型\n\n### 审批记录结构\n\n```typescript\ninterface Approval {\n id: string; // 唯一标识符\n title: string; // 审批标题\n description?: string; // 审批描述\n filePath?: string; // 相关文件路径（仅包含路径，不含内容）\n createdAt: Date | string; // 创建时间\n status: 'pending' | 'approved' | 'rejected' | 'needs-revision';\n category?: string; // 分类（用于过滤）\n}\n```\n\n### 审批状态枚举\n\n| 状态值 | 含义 | 后续操作 |\n|-------|------|---------|\n| `pending` | 待审批 | 等待用户响应 |\n| `approved` | 已批准 | 可删除记录，流程继续 |\n| `rejected` | 已拒绝 | 需要重新修改后再次提交 |\n| `needs-revision` | 需要修订 | 根据评论更新文档后重新提交 |\n\n资料来源：[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)\n\n## 前端组件\n\n### 审批卡片组件\n\n审批卡片是展示单个审批记录的核心组件，位于 VSCode 扩展的 Webview 中：\n\n```typescript\n// 卡片显示的信息\n- 标题 (title): 显示审批主题\n- 描述 (description): 可选的审批说明\n- 文件路径 (filePath): 以等宽字体显示的代码路径\n- 创建时间: 使用 formatDistanceToNow 格式化显示\n- 状态徽章: pending 状态显示待处理标识\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### 卡片操作按钮\n\n| 按钮 | 功能 | 状态 |\n|-----|------|-----|\n| 批准 (Approve) | 批准该审批请求 | 显示处理中状态 |\n| 拒绝 (Reject) | 拒绝该审批请求 | 显示处理中状态 |\n| 在编辑器中打开 | 查看审批文件内容 | - |\n\n### 批量操作\n\n审批系统支持多选模式下的批量操作：\n\n```typescript\n// 批量操作状态\ninterface BatchState {\n selectionMode: boolean; // 是否处于选择模式\n selectedApprovalIds: Set; // 已选中的审批 ID\n batchProcessing: boolean; // 是否正在处理\n pendingAction: 'approve' | 'reject' | null; // 待执行的批量操作\n batchResult: BatchApprovalResult | null; // 批量操作结果\n}\n```\n\n批量操作界面包含：\n\n1. **选择计数显示**：显示已选择的审批数量\n2. **清除选择按钮**：取消当前所有选择\n3. **批量批准按钮**：批准所有选中的审批\n4. **批量拒绝按钮**：拒绝所有选中的审批\n5. **结果提示**：显示操作成功或失败的数量统计\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### 审批页面组件\n\nWeb Dashboard 的审批页面（ApprovalsPage）提供更完整的功能：\n\n#### 筛选功能\n\n```typescript\n// 分类过滤\nconst [filterCategory, setFilterCategory] = useState('all');\n\n// URL 参数支持高亮显示特定审批\nconst [searchParams, setSearchParams] = useSearchParams();\nconst highlightedId = searchParams.get('id');\n```\n\n#### 模态框警告\n\n| 模态框 | 触发条件 | 用途 |\n|-------|---------|------|\n| 审批警告 | 批量操作前 | 确认批量操作的潜在影响 |\n| 修订警告 | 修订审批无评论时 | 提示用户添加修订说明 |\n\n资料来源：[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)\n\n## 存储机制\n\n### 审批文件存储\n\n审批记录存储在项目目录的 `.spec-workflow/approvals/` 目录下：\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # 审批记录存储目录\n archive/ # 已归档的规范\n specs/ # 规范文档\n steering/ # 指导文档\n templates/ # 模板\n user-templates/ # 用户自定义模板\n config.example.toml\n```\n\n### 文件操作流程\n\n1. **请求审批**：创建审批记录文件，记录请求信息和目标文件路径\n2. **状态管理**：通过文件系统状态或外部服务追踪审批状态\n3. **响应处理**：用户通过 VSCode 扩展或 Web Dashboard 进行响应\n4. **清理归档**：已批准的审批记录可被删除，相关文档移动到归档目录\n\n## 国际化支持\n\n审批系统支持多语言显示，关键翻译键位：\n\n| 翻译键 | 说明 |\n|-------|------|\n| `approvals.status.pending` | 待处理状态 |\n| `approvals.approve` | 批准按钮 |\n| `approvals.processing` | 处理中状态 |\n| `approvals.openInEditor` | 在编辑器中打开 |\n| `approvals.created` | 创建时间（带时间参数） |\n| `approvals.noPending` | 无待处理审批 |\n| `approvals.selectedCount` | 已选中数量 |\n| `approvals.clearSelection` | 清除选择 |\n| `approvalsPage.approvalWarning.message` | 审批警告消息 |\n| `approvalsPage.revision.noCommentsTitle` | 修订无评论标题 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n## API 接口\n\n### 审批相关 API\n\n| 接口名 | 功能 | 参数 |\n|-------|------|-----|\n| `approveRequest(id, response)` | 批准指定审批 | id: 审批ID, response: 响应内容 |\n| `rejectRequest(id, response)` | 拒绝指定审批 | id: 审批ID, response: 响应内容 |\n| `getApprovalContent(id)` | 获取审批内容 | id: 审批ID |\n| `approvalsActionBatch(ids, action)` | 批量操作 | ids: 审批ID数组, action: 操作类型 |\n| `approvalsUndoBatch(ids)` | 撤销批量操作 | ids: 审批ID数组 |\n\n### 状态轮询机制\n\n```typescript\n// 状态轮询流程\nasync function pollStatus(approvalId: string) {\n let status = await getApprovalStatus(approvalId);\n while (status === 'pending') {\n await sleep(1000); // 轮询间隔\n status = await getApprovalStatus(approvalId);\n }\n return status;\n}\n```\n\n## 样式与用户体验\n\n### 视觉设计\n\n审批卡片采用以下设计规范：\n\n```css\n/* 卡片容器 */\n.space-y-3: 元素间距 0.75rem\n\n/* 标题样式 */\n.font-medium: 中等字重\n.text-sm: 字体大小 14px\n.truncate: 文本溢出省略\n\n/* 状态徽章 */\n.variant: secondary\n.text-xs: 字体大小 12px\n\n/* 按钮样式 */\n.h-6: 高度 24px\n.px-2: 内边距水平 8px\n.text-xs: 字体大小 12px\n```\n\n### 时间显示\n\n创建时间使用 `formatDistanceToNow` 函数格式化，例如：\n\n- \"5 minutes ago\" → \"5分钟前\"\n- \"2 hours ago\" → \"2小时前\"\n- \"1 day ago\" → \"1天前\"\n\n## 与其他系统的集成\n\n### 规范工作流集成\n\n审批系统是规范工作流（Spec Workflow）的核心环节：\n\n```mermaid\ngraph TD\n subgraph 工作流阶段\n Create[创建文档] --> Approve[请求审批]\n Approve --> Poll[轮询状态]\n Poll --> Check{状态判断}\n Check -->|修订| Update[更新文档]\n Update --> Create\n Check -->|批准| Continue[继续下一阶段]\n Check -->|拒绝| Failed[流程失败]\n end\n```\n\n### 统计面板集成\n\n审批统计信息集成在 Dashboard 的统计面板中：\n\n| 统计项 | 字段 | 显示逻辑 |\n|-------|------|---------|\n| 待审批数量 | `approvals.length` | 大于0时显示警告色 |\n| 审批状态 | awaiting / allClear | 根据数量显示不同文案 |\n\n资料来源：[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)\n\n## 最佳实践\n\n### 发起审批\n\n1. 确保文档已完成编写并保存\n2. 提供清晰的审批标题和描述\n3. 在 `filePath` 中指定需要审批的文件路径\n\n### 审批响应\n\n1. 仔细阅读文档内容\n2. 批准时添加简短的响应说明\n3. 需要修订时提供具体的修改建议\n4. 避免无评论的修订操作\n\n### 批量操作\n\n1. 批量操作前确认所有选中项\n2. 注意系统警告提示\n3. 操作后检查结果反馈\n4. 及时撤销错误的批量操作\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 审批状态不更新 | 轮询间隔过长 | 检查状态更新机制 |\n| 批量操作失败 | 部分审批已处理 | 使用撤销功能恢复 |\n| 文件路径显示不正确 | 相对路径解析问题 | 使用绝对路径 |\n\n### 调试建议\n\n1. 检查浏览器控制台的 API 响应\n2. 验证 `.spec-workflow/approvals/` 目录权限\n3. 确认 MCP Server 连接状态\n4. 查看 Dashboard 日志输出\n\n---\n\n\n\n## 任务管理\n\n### 相关页面\n\n相关主题：[规格工作流程](#page-spec-workflow), [Web 仪表板](#page-dashboard)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n- [vscode-extension/src/extension/utils/taskParser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/utils/taskParser.ts)\n- [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)\n- [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)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n\n \n\n# 任务管理\n\n## 概述\n\n任务管理是 spec-workflow-mcp 项目的核心功能模块，负责规范化和跟踪项目中的开发任务。该模块支持多状态流转、看板视图、实时进度统计以及任务元数据管理，为团队提供了清晰的任务可视化和管理能力。\n\n任务管理系统的核心设计目标包括：\n\n- **状态驱动的工作流**：通过明确的任务状态定义团队工作进度\n- **Markdown 格式兼容**：任务以 Markdown 复选框格式存储，便于版本控制\n- **多端一致性**：Web 仪表板和 VSCode 扩展共享同一任务状态管理逻辑\n- **阻塞机制**：支持标记任务阻塞原因，便于问题追踪\n\n资料来源：[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)\n\n---\n\n## 任务状态定义\n\n### 状态类型\n\n系统定义了四种互斥的任务状态：\n\n| 状态值 | 复选框标记 | 含义 | 视觉标识 |\n|--------|-----------|------|---------|\n| `pending` | 空格 ` ` | 待处理 | 默认灰色 |\n| `in-progress` | 短横 `-` | 进行中 | 橙色边框 |\n| `completed` | 小写 `x` | 已完成 | 绿色样式 |\n| `blocked` | 波浪 `~` | 已阻塞 | 红色边框 |\n\n资料来源：[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)\n\n### 状态转换规则\n\n```mermaid\nstateDiagram-v2\n [*] --> pending : 新建任务\n pending --> in-progress : 开始处理\n in-progress --> completed : 任务完成\n in-progress --> blocked : 发现阻塞\n blocked --> in-progress : 解除阻塞\n blocked --> pending : 回退待处理\n completed --> pending : 重新打开\n```\n\n状态转换时的处理逻辑：\n\n```typescript\n// 拦截 blocked 状态以记录原因\nif (newStatus === 'blocked') {\n setPendingBlockedTaskId(taskId);\n setKanbanBlockedReasonOpen(true);\n return;\n}\n```\n\n资料来源：[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)\n\n---\n\n## 任务数据模型\n\n### 核心字段\n\n```typescript\ninterface Task {\n id: string; // 任务唯一标识 (如 \"1.1\", \"2.3.1\")\n status: TaskStatus; // 当前状态\n completed?: boolean; // 是否已完成 (计算属性)\n inProgress?: boolean; // 是否进行中 (计算属性)\n blockedReason?: string; // 阻塞原因 (仅 blocked 状态)\n prompt?: string; // AI 执行提示词\n leverage?: string; // 复用/杠杆信息\n purposes?: string[]; // 任务目的列表\n requirements?: string[]; // 特殊需求列表\n isHeader?: boolean; // 是否为分组标题\n}\n```\n\n### 任务元数据展示\n\n看板卡片支持展示丰富的任务元数据：\n\n| 元数据字段 | 展示位置 | 样式特征 |\n|-----------|---------|---------|\n| 任务 ID | 卡片顶部 | 等宽字体，深色背景 |\n| Leverage | 青色标签 | 青色背景，等宽字体 |\n| Purposes | 绿色标签 | 列表形式展示 |\n| Requirements | 橙色标签 | 逗号分隔展示 |\n| AI Prompt | 可展开区域 | 带复制按钮 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n---\n\n## Markdown 格式解析\n\n### 任务格式规范\n\n任务以标准 Markdown 复选框语法存储：\n\n```markdown\n- [ ] 1.1 任务描述\n- [-] 1.2 进行中的任务\n- [x] 1.3 已完成任务\n- [~] 1.4 阻塞的任务 (原因在下一行)\n```\n\n解析器支持 `-` 和 `*` 两种列表标记符：\n\n```typescript\n// 正则匹配模式\nconst checkboxMatch = line.match(/^(\\s*)([-*])\\s+\\[([ x\\-~])\\]\\s+(.+)/);\n```\n\n资料来源：[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)\n\n### 状态更新机制\n\n```typescript\nexport function updateTaskStatus(\n content: string,\n taskId: string,\n newStatus: 'pending' | 'in-progress' | 'completed' | 'blocked',\n reason?: string\n): string {\n const statusMarker = newStatus === 'completed' ? 'x' :\n newStatus === 'in-progress' ? '-' :\n newStatus === 'blocked' ? '~' :\n ' ';\n // ... 遍历并更新匹配的任务行\n}\n```\n\n资料来源：[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)\n\n---\n\n## 看板视图\n\n### 布局结构\n\n```mermaid\ngraph TD\n subgraph 看板布局\n A[待处理列] --> B[进行中列]\n B --> C[已完成列]\n B --> D[已阻塞列]\n end\n subgraph 任务统计\n E[总任务数] --> F[完成率百分比]\n G[进度条组件] --> F\n end\n```\n\n### 任务卡片组件\n\n```typescript\n// KanbanTaskCard 核心交互\ninterface KanbanTaskCardProps {\n task: Task;\n isInProgress: boolean;\n copiedTaskId: string | null;\n onCopyTaskPrompt: () => void;\n onToggleExpand: () => void;\n}\n```\n\n关键交互特性：\n\n- **触摸优化**：最小点击目标 44x44 像素（WCAG AAA 标准）\n- **复制功能**：一键复制 AI Prompt 到剪贴板\n- **进行中指示**：橙色脉冲动画标识当前处理任务\n\n资料来源：[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)\n\n---\n\n## API 接口\n\n### 任务状态更新\n\n```\nPUT /specs/{specName}/tasks/{taskId}/status\n```\n\n**请求参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `specName` | string | 是 | 规格文档名称（URL 编码） |\n| `taskId` | string | 是 | 任务标识符（URL 编码） |\n| `status` | TaskStatus | 是 | 新状态值 |\n| `reason` | string | 否 | 阻塞原因（仅 blocked 时） |\n\n**响应结构：**\n\n```typescript\ninterface TaskStatusResponse {\n success: boolean;\n task: Task;\n progress: number; // 0-100 百分比\n}\n```\n\n资料来源：[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)\n\n### 进度查询\n\n```\nGET /specs/{specName}/tasks/progress\n```\n\n**返回数据：**\n\n```typescript\ninterface TaskProgress {\n total: number; // 总任务数\n completed: number; // 已完成数\n inProgress: string | null; // 当前进行中的任务ID\n progress: number; // 完成百分比\n taskList: Task[]; // 完整任务列表\n}\n```\n\n---\n\n## 实施日志管理\n\n### 日志条目结构\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n taskId: string;\n summary: string;\n filesModified: string[];\n filesCreated: string[];\n artifacts: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n statistics?: {\n linesAdded: number;\n linesRemoved: number;\n };\n}\n```\n\n### Markdown 导出格式\n\n实施日志支持导出为 Markdown 格式，便于文档化和分享：\n\n```markdown\n## Task Summary\n_任务摘要信息_\n\n---\n\n## Statistics\n- Lines Added: {count}\n- Lines Removed: {count}\n\n## Files Modified\n- file1.ts\n- file2.ts\n\n---\n\n## Artifacts\n\n### API Endpoints\n#### POST /api/resource\n- **Purpose:** 端点用途说明\n- **Location:** 文件路径\n\n### Components\n#### ComponentName\n- **Type:** 组件类型\n- **Purpose:** 组件用途\n```\n\n资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n---\n\n## 前端状态管理\n\n### 乐观更新策略\n\n任务状态更新采用乐观更新模式，先更新本地 UI 再同步服务器：\n\n```typescript\n// 标记待更新任务\npendingStatusUpdatesRef.current.add(taskId);\n\n// 乐观更新本地数据\nsetData((prevData: any) => {\n const updatedTaskList = prevData.taskList.map((t: any) =>\n t.id === taskId ? { \n ...t, \n status: newStatus, \n completed: newStatus === 'completed',\n inProgress: newStatus === 'in-progress',\n blockedReason: undefined \n } : t\n );\n return { ...prevData, taskList: updatedTaskList };\n});\n```\n\n资料来源：[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)\n\n### 剪贴板操作\n\n支持现代 Clipboard API 和传统 fallback 方案：\n\n```typescript\nfunction copyTaskPrompt(specName: string, task: any, onSuccess?, onFailure?) {\n const command = task.prompt || `Please work on task ${task.id} for spec \"${specName}\"`;\n \n // 现代 API\n if (navigator.clipboard?.writeText) {\n navigator.clipboard.writeText(command).then(() => onSuccess?.());\n } else {\n // 传统方案 (HTTP over LAN 等场景)\n fallbackCopy(command, onSuccess, onFailure);\n }\n}\n```\n\n资料来源：[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)\n\n---\n\n## 统计与可视化\n\n### 任务计数器\n\n```typescript\nconst taskCounts = {\n all: nonHeaderTasks.length,\n completed: nonHeaderTasks.filter(t => t.status === 'completed').length,\n 'in-progress': nonHeaderTasks.filter(t => t.status === 'in-progress').length,\n pending: nonHeaderTasks.filter(t => t.status === 'pending').length,\n blocked: nonHeaderTasks.filter(t => t.status === 'blocked').length,\n headers: tasks.filter(t => t.isHeader).length\n};\n```\n\n### 进度条组件\n\n进度百分比计算公式：\n\n```\nprogress = (completedTasks / totalTasks) * 100\n```\n\n显示时四舍五入至整数：\n\n```tsx\n{Math.round(taskData.progress)}%\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n---\n\n## 筛选与排序\n\n### 状态筛选\n\n| 筛选值 | 显示内容 |\n|--------|---------|\n| `all` | 所有任务 |\n| `pending` | 仅待处理 |\n| `in-progress` | 仅进行中 |\n| `completed` | 仅已完成 |\n| `blocked` | 仅已阻塞 |\n\n### 排序控制\n\n- **看板视图**：按状态列自动分组\n- **列表视图**：支持多维度排序（优先级、创建时间等）\n\n---\n\n## 最佳实践\n\n### 1. 阻塞原因记录\n\n当任务进入 `blocked` 状态时，应在弹窗中详细说明阻塞原因，便于团队协作排查问题。\n\n### 2. Prompt 规范\n\n每个任务应配置明确的 `prompt` 字段，为 AI 提供清晰的执行指令。\n\n### 3. Leverage 复用\n\n对于可复用的代码或组件，应在 `leverage` 字段中记录相关位置和说明。\n\n### 4. 实时同步\n\n多端操作时注意同步状态，避免冲突覆盖。\n\n---\n\n\n\n## Web 仪表板\n\n### 相关页面\n\n相关主题：[VSCode 扩展](#page-vscode-extension), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)\n- [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)\n- [src/dashboard_frontend/src/modules/pages](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages)\n- [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)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n \n\n# Web 仪表板\n\nWeb 仪表板是 spec-workflow-mcp 项目的核心可视化界面，为开发者提供图形化的项目状态监控、规范文档管理和任务追踪功能。仪表板通过 Web 界面形式呈现，允许用户在浏览器中直观地查看所有已连接项目的规格文档、审批状态和实现日志。\n\n## 功能概述\n\nWeb 仪表板的主要功能包括：\n\n| 功能模块 | 描述 |\n|---------|------|\n| 项目概览 | 显示所有已连接项目的基本统计信息 |\n| 规格文档管理 | 列出活跃和已归档的规格文档 |\n| 任务追踪 | 展示每个规格文档的任务进度和状态 |\n| 审批管理 | 处理实现日志的审批流程 |\n| 自动清理 | 配置和管理自动化清理任务 |\n| 设置管理 | 仪表板全局配置和偏好设置 |\n\n资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()\n\n## 系统架构\n\n### 组件结构\n\nWeb 仪表板采用前后端分离的架构设计：\n\n```mermaid\ngraph TD\n A[Web 浏览器] --> B[Dashboard Frontend
React SPA]\n B --> C[Dashboard Backend
Express.js]\n C --> D[文件系统
.spec-workflow]\n E[多个项目 Workspace] --> D\n \n B --> F[API 模块
api.tsx]\n F --> C\n```\n\n前端部分位于 `src/dashboard_frontend/` 目录，使用 React 构建单页应用。主要页面组件包括：\n\n- **App.tsx** - 根组件，管理全局状态和页面路由\n- **SettingsPage.tsx** - 设置页面，管理自动化清理和偏好配置\n- **TasksPage.tsx** - 任务页面，展示任务详情和进度\n\n资料来源：[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)()\n\n### 部署架构\n\n仪表板支持多种部署方式：\n\n```mermaid\ngraph LR\n A[直接运行] --> B[npx --dashboard]\n C[Docker 容器] --> D[docker-compose]\n B --> E[http://localhost:5000]\n D --> E\n```\n\n## 核心页面\n\n### 项目概览页面\n\n概览页面展示当前选中项目的核心统计数据：\n\n| 统计项 | 说明 |\n|-------|------|\n| 活跃规格文档数 | 当前处于活跃状态的规格文档总数 |\n| 已完成规格文档数 | 已完成实现的规格文档数 |\n| 已归档规格文档数 | 归档的历史规格文档数 |\n| 任务完成率 | 已完成任务占总任务数的比例 |\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)()\n\n### 任务页面\n\n任务页面详细展示每个规格文档下定义的任务列表，支持以下功能：\n\n- **状态筛选** - 按 pending、in-progress、completed、blocked 状态筛选\n- **AI 提示词** - 显示任务关联的 AI 提示词内容\n- **杠杆值** - 显示任务的杠杆指数（leverage）\n- **进度追踪** - 实时更新任务完成进度\n\n```mermaid\ngraph TD\n A[获取任务列表] --> B{任务状态}\n B -->|pending| C[待处理]\n B -->|in-progress| D[进行中]\n B -->|completed| E[已完成]\n B -->|blocked| F[已阻塞]\n \n C --> G[状态更新 API]\n D --> G\n E --> G\n F --> G\n G --> H[更新任务状态]\n```\n\n资料来源：[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)()\n\n### 设置页面\n\n设置页面提供仪表板全局配置功能，包括自动化清理任务的配置：\n\n- 管理跨所有已连接项目运行的自动化清理作业\n- 配置清理频率和保留策略\n- 查看清理任务执行日志\n\n资料来源：[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)()\n\n## API 接口\n\n仪表板前端通过统一的 API 模块与后端通信：\n\n```typescript\n// 规格文档相关 API\ngetAllSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all`)\ngetAllArchivedSpecDocuments: (name: string) => getJson(`${prefix}/specs/${name}/all/archived`)\ngetSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${name}/tasks/progress`)\n\n// 任务状态管理\nupdateTaskStatus: (specName, taskId, status, reason?) => \n putJson(`/specs/${specName}/tasks/${taskId}/status`, { status, reason })\n\n// 审批相关 API\napprovalsAction: (id, action, body) => postJson(`/approvals/${id}/${action}`, body)\napprovalsActionBatch: (ids, action, response) => postJson(`/approvals/batch/${action}`, { ids, response })\napprovalsUndoBatch: (ids) => postJson(`/approvals/batch/undo`, { ids })\ngetApprovalContent: (id: string) => getJson(`/approvals/${id}/content`)\ngetApprovalSnapshots: (id: string) => getJson(`/approvals/${id}/snapshots`)\n```\n\n资料来源：[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)()\n\n## 部署配置\n\n### 环境变量\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `DASHBOARD_PORT` | `5000` | 仪表板运行端口 |\n| `SPEC_WORKFLOW_PATH` | `./workspace` | 项目工作区路径 |\n\n### Docker 部署\n\n使用 Docker Compose 部署是最推荐的方案：\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n自定义端口部署示例：\n\n```bash\ndocker run -p 8080:8080 \\\n -e DASHBOARD_PORT=8080 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n资料来源：[containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)()\n\n### 快速启动\n\n通过 npx 直接启动本地仪表板：\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\n仪表板启动后可通过 http://localhost:5000 访问。\n\n> **注意**：仅需一个仪表板实例即可管理所有已连接项目，所有项目共享同一仪表板服务。\n\n资料来源：[docs/INTERFACES.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md)()\n\n## 安全特性\n\nWeb 仪表板实现了企业级安全控制：\n\n| 安全特性 | 描述 |\n|---------|------|\n| 本地绑定 | 默认绑定到 `127.0.0.1`，防止网络暴露 |\n| 速率限制 | 每客户端 120 请求/分钟，自动清理过期连接 |\n| 审计日志 | 结构化 JSON 日志，包含时间戳、操作者和结果 |\n| 安全响应头 | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |\n| CORS 保护 | 跨域资源共享控制 |\n\n## 前端国际化\n\n仪表板支持多语言界面，使用 i18n 模块处理翻译资源：\n\n```typescript\n// 语言切换时自动更新\nt.changeLanguage(g) // g 为语言代码\n_.setLanguagePreference(g)\n```\n\n语言偏好设置会被持久化保存，用户下次访问时自动应用已选语言。\n\n## 与 VSCode 扩展的关系\n\nWeb 仪表板与 VSCode 扩展共用同一前端组件库和样式资源。编译后的静态资源位于 `vscode-extension/webview-dist/` 目录：\n\n| 文件 | 用途 |\n|-----|------|\n| `index.html` | VSCode 内嵌 WebView 入口 |\n| `main.js` | 编译后的主应用代码 |\n| `globals.css` | 全局样式定义 |\n| `comment-modal.html` | 注释弹窗页面 |\n\n这确保了仪表板界面与 VSCode 扩展内嵌 WebView 的一致用户体验。\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Dashboard as Web 仪表板\n participant Backend as 后端服务\n participant FS as 文件系统\n \n User->>Dashboard: 访问 http://localhost:5000\n Dashboard->>Backend: 请求项目列表\n Backend->>FS: 读取 .spec-workflow 配置\n FS-->>Backend: 返回项目元数据\n Backend-->>Dashboard: 返回统计数据\n Dashboard-->>User: 渲染项目概览\n \n User->>Dashboard: 选择规格文档\n Dashboard->>Backend: 获取任务列表\n Backend-->>Dashboard: 返回任务数据\n Dashboard-->>User: 渲染任务页面\n \n User->>Dashboard: 更新任务状态\n Dashboard->>Backend: PUT /specs/{name}/tasks/{id}/status\n Backend->>FS: 更新任务状态文件\n FS-->>Backend: 确认更新\n Backend-->>Dashboard: 返回更新结果\n```\n\n## 总结\n\nWeb 仪表板作为 spec-workflow-mcp 项目的核心用户界面，提供了一个集中化的可视化管理平台。它通过 RESTful API 与后端服务通信，支持多项目管理、任务追踪、审批流程和系统配置等完整功能。仪表板采用 Docker 容器化部署，配置简单快捷，同时具备企业级安全特性，适合团队协作环境使用。\n\n---\n\n\n\n## VSCode 扩展\n\n### 相关页面\n\n相关主题：[Web 仪表板](#page-dashboard), [安装配置](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [vscode-extension/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n- [vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n- [vscode-extension/src/extension/providers/SidebarProvider.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)\n- [vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)\n- [vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n- [vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n- [vscode-extension/src/webview/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/comment-modal.html)\n- [vscode-extension/webview-dist/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)\n\n \n\n# VSCode 扩展\n\n## 概述\n\nVSCode 扩展是 spec-workflow-mcp 项目的重要组成部分，为 Visual Studio Code 用户提供原生的开发体验。通过该扩展，用户可以直接在 VSCode 编辑器中访问和管理项目规格文档、审批流程以及实现日志，无需切换到独立的 Web 仪表板。\n\n该扩展基于 VSCode Webview API 构建，采用 React 作为前端框架，实现了与核心工作流引擎的深度集成。扩展通过 MCP（Model Context Protocol）协议与后端服务通信，为用户提供实时的工作状态反馈和交互能力。\n\n扩展的主要设计目标是降低 AI 辅助开发的工作流门槛，让开发者能够在熟悉的 IDE 环境中完成从规格创建、审批到实现追踪的完整流程。\n\n## 架构设计\n\n### 整体架构\n\nVSCode 扩展采用前后端分离的架构模式，核心组件分为三个层次：\n\n```mermaid\ngraph TD\n A[VSCode 扩展宿主] --> B[Webview UI 层]\n A --> C[MCP 通信层]\n B <--> D[Webview 消息传递]\n C --> E[后端服务]\n D --> F[用户交互]\n```\n\n### 目录结构\n\n```\nvscode-extension/\n├── README.md # 扩展说明文档\n├── package.json # 扩展配置和依赖\n├── src/\n│ ├── extension/ # 扩展后端代码\n│ │ ├── providers/\n│ │ │ └── SidebarProvider.ts # 侧边栏提供者\n│ │ └── services/\n│ │ └── ApprovalEditorService.ts # 审批编辑器服务\n│ └── webview/ # Webview 前端代码\n│ ├── App.tsx # 主应用组件\n│ ├── comment-modal.html # 评论模态框 HTML\n│ └── components/\n│ └── LogEntryCard.tsx # 日志条目卡片组件\n└── webview-dist/ # 编译后的 Webview 资源\n ├── comment-modal.js # 评论模态框脚本\n ├── comment-modal.html # 评论模态框页面\n ├── globals.css # 全局样式\n └── i18n.js # 国际化脚本\n```\n\n资料来源：[vscode-extension/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n\n### Webview 消息通信机制\n\n扩展通过 VSCode 的 `postMessage` API 实现前端与后端的双向通信。当用户在 Webview 中执行操作时，消息被发送到扩展后端，后端处理请求后返回响应结果。这种模式确保了用户界面的流畅性，同时保持了与核心系统的同步。\n\nWebview 使用 `useEffect` 钩子监听来自扩展的消息，根据消息类型更新对应的 UI 状态。对于需要持久化的数据操作，扩展会通过 MCP 协议转发到后端服务进行处理。\n\n## 核心组件\n\n### SidebarProvider（侧边栏提供者）\n\n`SidebarProvider` 是 VSCode 扩展的核心入口点，负责管理侧边栏视图的生命周期。该提供者扩展自 VSCode 的 `TreeView` API，能够在活动栏中注册一个可折叠的视图区域。\n\n主要职责包括：\n\n- 初始化侧边栏视图结构\n- 注册命令和快捷键\n- 处理视图项的点击事件\n- 管理 Webview 面板的创建和销毁\n\n资料来源：[vscode-extension/src/extension/providers/SidebarProvider.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/providers/SidebarProvider.ts)\n\n### ApprovalEditorService（审批编辑器服务）\n\n`ApprovalEditorService` 负责处理审批相关的数据操作和服务调用。该服务封装了所有与审批流程相关的业务逻辑，包括审批请求的创建、提交、撤销以及历史记录的查看。\n\n服务层的设计遵循单一职责原则，将数据获取逻辑与 UI 层分离，使得组件可以专注于用户界面的渲染，而无需关心底层的数据获取机制。通过依赖注入模式，扩展可以更容易地进行单元测试和功能扩展。\n\n资料来源：[vscode-extension/src/extension/services/ApprovalEditorService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalEditorService.ts)\n\n### App.tsx（主应用组件）\n\n`App.tsx` 是 Webview 的根组件，负责协调各个子组件的渲染和状态管理。该组件使用 React Context API 共享全局状态，使得深层嵌套的组件也能方便地访问和更新应用状态。\n\n组件结构采用功能模块化的设计，主要区域包括：\n\n- 概览面板：显示项目统计信息\n- 规格列表：展示所有活跃和归档的规格文档\n- 任务视图：呈现规格关联的任务及其进度\n- 日志视图：展示实现日志条目\n\n资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n### LogEntryCard 组件\n\n`LogEntryCard` 是一个专门用于展示实现日志条目的卡片组件。它将复杂的日志数据解析为用户友好的格式，支持多种内容的可视化展示。\n\n组件支持展示的内容类型：\n\n| 内容类型 | 描述 | 数据格式 |\n|---------|------|---------|\n| 文件修改 | 列出本次实现修改的文件 | 字符串数组 |\n| 文件创建 | 列出本次实现创建的文件 | 字符串数组 |\n| API 端点 | 记录 API 接口信息 | 对象数组 |\n| 组件 | 前端组件元数据 | 对象数组 |\n| 函数 | 函数定义和导出信息 | 对象数组 |\n| 类 | 类定义和方法信息 | 对象数组 |\n| 集成 | 前端后端集成信息 | 对象数组 |\n\n组件采用条件渲染策略，仅当对应类型的数据存在时才显示相应的区域。这种设计减少了不必要的 DOM 操作，提升了渲染性能。\n\n资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n\n## 功能特性\n\n### 规格文档管理\n\n扩展提供了完整的规格文档管理界面，用户可以：\n\n- 查看所有活跃规格的列表和状态\n- 浏览已归档规格的历史记录\n- 追踪每个规格关联的任务进度\n- 直接在 VSCode 中编辑规格内容\n\n规格列表采用卡片式布局，每个卡片显示规格名称、任务进度条和关键元数据。进度条使用颜色编码来区分完成状态，绿色表示已完成的任务数量，灰色表示总任务数量。\n\n### 任务追踪系统\n\n任务追踪功能集成在规格详情视图中，允许用户：\n\n- 查看任务的元数据，包括目的、需求和技术杠杆点\n- 展开和折叠 AI 提示内容\n- 复制任务提示用于其他场景\n- 追踪任务的完成状态\n\n任务视图支持展开/折叠交互，用户可以点击任务标题来显示或隐藏详细信息。这种交互模式在处理大量任务时特别有用，可以帮助用户专注于当前关注的内容。\n\n### 审批工作流\n\n审批功能通过专门的编辑器服务实现，支持以下操作：\n\n- 提交审批请求\n- 批准或拒绝申请\n- 批量处理多个审批请求\n- 查看审批历史快照\n- 比较不同版本之间的差异\n\n审批编辑器服务封装了所有与审批相关的数据操作，包括快照生成、版本比较和批量操作。这种封装确保了 UI 层可以专注于用户交互，而无需处理复杂的业务逻辑。\n\n### 实现日志查看\n\n实现日志功能允许用户回顾开发过程中的所有变更：\n\n- 按时间线查看日志条目\n- 查看每次实现修改和创建的文件\n- 了解 API 端点、组件、函数等代码工件\n- 追踪前后端集成的数据流\n\n日志条目卡片提供了丰富的信息展示，包括统计数据（新增/删除行数）、文件列表和各类代码工件。每个工件条目都包含名称、目的、位置等关键信息，便于开发者快速定位代码。\n\n### 评论模态框\n\n评论功能通过独立的模态框实现，用户可以在任何支持评论的上下文中添加评论。模态框采用独立的 HTML 页面加载，确保样式与 VSCode 主题一致。\n\n评论模态框的样式通过 CSS 变量与 VSCode 主题系统集成：\n\n```css\nbody {\n font-family: var(--vscode-font-family), -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;\n font-size: var(--vscode-font-size, 13px);\n color: var(--vscode-foreground);\n background: var(--vscode-editor-background);\n}\n```\n\n资料来源：[vscode-extension/src/webview/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/comment-modal.html)\n\n## 用户界面设计\n\n### 主题适配\n\n扩展完全支持 VSCode 的亮色和暗色主题。通过使用 CSS 变量，Webview 可以自动响应主题切换，无需编写额外的主题检测逻辑。所有文本颜色、背景颜色和边框颜色都基于 VSCode 提供的语义化变量定义。\n\n主要使用的 CSS 变量包括：\n\n- `var(--vscode-font-family)`：字体系列\n- `var(--vscode-font-size)`：字体大小\n- `var(--vscode-foreground)`：前景色\n- `var(--vscode-editor-background)`：编辑器背景色\n\n资料来源：[vscode-extension/webview-dist/comment-modal.html](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/webview-dist/comment-modal.html)\n\n### 国际化支持\n\n扩展内置了国际化支持，通过 `i18n.js` 模块提供多语言文本资源。用户界面中的所有可显示文本都通过翻译键引用，而非硬编码的字符串。这种设计使得扩展可以轻松支持新的语言环境。\n\n翻译键采用层级命名规范，例如 `overview.projectTitle` 表示概览面板的项目标题文本。\n\n### 响应式布局\n\nWebview 界面采用响应式设计，针对不同的面板宽度提供优化的布局：\n\n- 小屏幕：单列布局，元素垂直堆叠\n- 大屏幕：双列或多列布局，充分利用空间\n\n任务视图中的元素根据容器宽度自动调整字体大小和间距。图标、标签和内容区域都采用相对单位，确保在不同尺寸的视口中保持可读性。\n\n## 配置与安装\n\n### 安装方式\n\n用户可以通过 VSCode 扩展市场安装该扩展，或者通过命令行加载本地构建的扩展包。\n\nVSCode 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"]\n }\n }\n}\n```\n\n### 扩展配置\n\n扩展支持通过 `package.json` 进行配置，包括：\n\n| 配置项 | 类型 | 描述 |\n|-------|------|------|\n| `displayName` | 字符串 | 扩展显示名称 |\n| `description` | 字符串 | 扩展功能描述 |\n| `version` | 字符串 | 扩展版本号 |\n| `engines` | 对象 | VSCode 引擎版本要求 |\n\n资料来源：[vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n\n## 开发指南\n\n### 本地开发\n\n扩展的开发环境配置遵循标准的 VSCode 扩展开发流程：\n\n```bash\n# 安装依赖\nnpm install\n\n# 在开发模式下运行\nnpm run dev\n\n# 构建生产版本\nnpm run build\n```\n\n开发模式下，扩展会自动监听源文件的变化并重新加载，无需手动重启 VSCode。\n\n### Webview 资源管理\n\nWebview 所需的静态资源（HTML、CSS、JavaScript）需要在 `webview-dist` 目录中预编译。开发流程中，这些资源由构建系统自动处理，但在发布前需要确保所有资源都已正确打包。\n\nWebview 的入口点通过 `comment-modal.html` 定义，该文件引用编译后的脚本和样式资源。\n\n### 消息协议\n\n扩展与 Webview 之间的消息采用以下协议格式：\n\n```typescript\ninterface WebviewMessage {\n type: string;\n payload?: any;\n requestId?: string;\n}\n```\n\n每条消息包含消息类型标识和可选的数据负载。对于需要响应的消息，Webview 应在处理完成后发送带有对应 `requestId` 的响应消息。\n\n## 相关资源\n\n- 主项目文档：[SPEC Workflow MCP 文档](../README.md)\n- 开发指南：[开发文档](../docs/DEVELOPMENT.md)\n- 工作流程：[工作流程指南](../docs/WORKFLOW.md)\n- 工具参考：[工具参考文档](../docs/TOOLS-REFERENCE.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Pimzino/spec-workflow-mcp\n\n摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory。\n\n## 1. 安装坑 · 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code\n\n## 3. 配置坑 · 来源证据：[Bug]: Bug Report for spec-workflow-mcp\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：Pimzino/spec-workflow-mcp\n\n摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory。\n\n## 1. 安装坑 · 来源证据：[Bug]: approval categoryName path traversal writes outside approvals directory\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: approval categoryName path traversal writes outside approvals directory\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8fb00e0913ae49789f067cb7a367e967 | https://github.com/Pimzino/spec-workflow-mcp/issues/220 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code\n\n## 3. 配置坑 · 来源证据：[Bug]: Bug Report for spec-workflow-mcp\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Bug Report for spec-workflow-mcp\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2224eccf9467459da3e19254a796753a | https://github.com/Pimzino/spec-workflow-mcp/issues/218 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_763384ba6d384832ada894b2c653b77b | https://github.com/Pimzino/spec-workflow-mcp/issues/201 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# spec-workflow-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 spec-workflow-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Spec Workflow MCP 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-installation：安装配置。围绕“安装配置”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-spec-workflow：规格工作流程。围绕“规格工作流程”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-installation\n输入：用户提供的“安装配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-spec-workflow\n输入：用户提供的“规格工作流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-installation：Step 3 必须围绕“安装配置”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-spec-workflow：Step 5 必须围绕“规格工作流程”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Pimzino/spec-workflow-mcp\n- https://github.com/Pimzino/spec-workflow-mcp#readme\n- README.md\n- src/index.ts\n- package.json\n- docs/USER-GUIDE.md\n- docs/PROMPTING-GUIDE.md\n- containers/example.mcp.json\n- docs/CONFIGURATION.md\n- src/config.ts\n- src/core/global-dir.ts\n- src/server.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 spec-workflow-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：Pimzino/spec-workflow-mcp\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest\n```\n\n来源：https://github.com/Pimzino/spec-workflow-mcp#readme\n\n## 来源\n\n- repo: https://github.com/Pimzino/spec-workflow-mcp\n- docs: https://github.com/Pimzino/spec-workflow-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_383337b344f24a1eb3768d462230fcb5"
}