{ "canonical_name": "Pimzino/spec-workflow-mcp", "compilation_id": "pack_8849472f61c64aaabd7b14a47aaf1443", "created_at": "2026-05-16T13:12:22.382533+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": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "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": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "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": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Pimzino/spec-workflow-mcp.\n\nProject:\n- Name: spec-workflow-mcp\n- Repository: https://github.com/Pimzino/spec-workflow-mcp\n- Summary: Spec Workflow MCP\n- Host target: mcp_host, claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Spec Workflow MCP\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Spec Workflow MCP\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. project-structure: Project Structure. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-server: MCP Server Implementation. Produce one small intermediate artifact and wait for confirmation.\n5. spec-management: Spec Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- src/tools/index.ts\n- src/prompts/index.ts\n- vscode-extension/package.json\n- containers/docker-compose.yml\n- src/server.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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": [ "浏览器 Agent", "网页任务自动化", "结构化数据提取", "节点式流程编排", "开源工具" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/Pimzino/spec-workflow-mcp 项目说明书\n\n生成时间：2026-05-16 13:11:01 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [System Architecture](#architecture)\n- [MCP Server Implementation](#mcp-server)\n- [Spec Management](#spec-management)\n- [Approval Workflow System](#approval-workflow)\n- [Steering Documents](#steering-documents)\n- [Web Dashboard](#web-dashboard)\n- [VSCode Extension](#vscode-extension)\n- [Docker Deployment](#docker-deployment)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [src/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/index.ts)\n- [package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/package.json)\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
\n\n# Getting Started\n\nA comprehensive guide to setting up and running the Spec-Workflow MCP server for AI-assisted specification-based development workflows.\n\n## Overview\n\nSpec-Workflow MCP is a Model Context Protocol (MCP) server that enables AI coding assistants to work with structured specifications. It provides a systematic approach to development by maintaining specs, tracking tasks, managing approvals, and logging implementation details.\n\n**Key Capabilities:**\n- Specification management with version control and approval workflows\n- Task tracking and progress monitoring\n- Implementation logging for code artifacts\n- Integration with multiple AI coding tools (Claude Desktop, Cursor, VSCode, etc.)\n- Web dashboard and VSCode extension for visualization\n\n## Prerequisites\n\nBefore installation, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Node.js | ≥ 18.0.0 | Required for npm execution |\n| npm | ≥ 9.0.0 | For package management |\n| Git | Any recent version | For version control integration |\n| Docker | ≥ 20.10.0 | Optional, for containerized deployment |\n| Docker Compose | ≥ 2.0.0 | Optional, for multi-container setups |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Quick Setup via npx\n\nThe simplest way to get started is using npx, which downloads and executes the package without global installation:\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project\n```\n\n**Command Arguments:**\n| Argument | Description | Required |\n|----------|-------------|----------|\n| `/path/to/your/project` | Absolute path to your project directory | Yes |\n\n资料来源：[README.md:1-20](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Method 2: Global Installation\n\nFor persistent installation across sessions:\n\n```bash\nnpm install -g @pimzino/spec-workflow-mcp\n```\n\nThen execute:\n```bash\nspec-workflow-mcp /path/to/your/project\n```\n\n### Method 3: Docker Deployment\n\nFor isolated, containerized deployment:\n\n```bash\n# Using Docker Compose (recommended)\ncd containers\ndocker-compose up --build\n\n# Or using 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\nThe dashboard becomes available at: `http://localhost:5000`\n\n资料来源：[README.md:85-95](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## MCP Server Configuration\n\nAfter installation, configure the MCP server for your preferred AI coding tool.\n\n### Claude Desktop\n\nAdd to `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> **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.\n\n资料来源：[README.md:55-70](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Claude Code CLI\n\n```bash\nclaude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project\n```\n\n**Windows Alternative:**\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:35-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Cursor IDE\n\nAdd to your Cursor settings (`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### VSCode (Cline/Claude Dev)\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### Continue IDE Extension\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### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_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### Codex\n\nAdd to `~/.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### OpenCode\n\nAdd to `opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"spec-workflow\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"],\n \"enabled\": true\n }\n }\n}\n```\n\n资料来源：[README.md:100-145](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Choosing Your Interface\n\nSpec-Workflow MCP offers two interfaces for interacting with specifications. Choose based on your workflow.\n\n### Option A: Web Dashboard\n\n**Recommended for:** CLI users, team collaboration, remote access\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\nAccess the dashboard at: `http://localhost:5000`\n\n**Key Features:**\n- Real-time task progress visualization\n- Specification document management\n- Approval workflow interface\n- Implementation artifact tracking\n- Project statistics dashboard\n\n> **Note:** Only one dashboard instance is needed. All projects connect to the same dashboard.\n\n资料来源：[README.ko.md:20-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n\n### Option B: VSCode Extension\n\n**Recommended for:** VSCode users, integrated workflow, inline annotations\n\nThe VSCode extension provides:\n- Inline spec annotations in code\n- Task status indicators\n- Quick actions for spec management\n- Integrated approval interface\n\n资料来源：[README.ko.md:30-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n\n## Project Structure\n\nAfter initialization, Spec-Workflow creates a `.spec-workflow` directory with the following structure:\n\n```\nyour-project/\n├── .spec-workflow/\n│ ├── approvals/ # Pending approval documents\n│ ├── archive/ # Archived specifications\n│ ├── specs/ # Active specifications\n│ ├── steering/ # Steering/prompt documents\n│ ├── templates/ # Built-in templates\n│ ├── user-templates/ # Custom user templates\n│ └── config.example.toml # Configuration template\n```\n\n| Directory | Purpose |\n|-----------|---------|\n| `approvals/` | Stores documents pending review and approval |\n| `archive/` | Contains superseded/archived specifications |\n| `specs/` | Active specification documents |\n| `steering/` | AI steering prompts and guidelines |\n| `templates/` | Reusable specification templates |\n| `user-templates/` | Custom templates created by users |\n\n资料来源：[README.md:20-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Development Setup\n\nFor contributing to the project or running from source:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Available npm Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compiles TypeScript to JavaScript |\n| `npm run dev` | Runs in development mode with hot reload |\n| `npm test` | Runs the test suite |\n| `npm run lint` | Lints code for style and errors |\n\n资料来源：[README.fr.md:25-40](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[AI Coding Assistant] -->|MCP Protocol| B[Spec-Workflow MCP Server]\n B --> C[.spec-workflow Directory]\n C --> D[Specs]\n C --> E[Tasks]\n C --> F[Approvals]\n C --> G[Implementation Logs]\n \n H[Web Dashboard] <-->|HTTP API| B\n I[VSCode Extension] <-->|VSCode API| B\n \n J[Project Files] -->|Read/Write| B\n \n style B fill:#e1f5fe\n style H fill:#fff3e0\n style I fill:#e8f5e9\n```\n\n## Security Features\n\nSpec-Workflow MCP includes enterprise-grade security controls:\n\n| Feature | Description |\n|---------|-------------|\n| **Localhost Binding** | Binds to `127.0.0.1` by default, preventing network exposure |\n| **Rate Limiting** | 120 requests/minute per client with automatic cleanup |\n| **Audit Logging** | Structured JSON logs with timestamp, actor, action, and result |\n| **Security Headers** | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| **CORS Protection** | Configurable cross-origin request policies |\n\n资料来源：[README.md:100-115](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph LR\n A[Install MCP Server] --> B[Configure AI Tool]\n B --> C[Initialize Project]\n C --> D[Create Specification]\n D --> E[AI Generates Code]\n E --> F[Review & Approve]\n F --> G[Implementation Logged]\n \n style A fill:#ffcdd2\n style D fill:#fff9c4\n style F fill:#c8e6c9\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue: Dashboard not accessible**\n- Ensure port 5000 is available\n- Check if another instance is running\n- Verify firewall settings\n\n**Issue: MCP server connection failed**\n- Verify the project path is absolute, not relative\n- Check that Node.js version meets requirements\n- Ensure the npx cache is up to date: `npx -y`\n\n**Issue: Permissions error with .spec-workflow directory**\n- Ensure the directory has appropriate read/write permissions\n- On Linux/Mac: `chmod -R 755 .spec-workflow`\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/TROUBLESHOOTING.md)\n\n## Next Steps\n\nAfter completing the getting started guide:\n\n1. **Create your first specification** using the spec template\n2. **Explore the dashboard** at `http://localhost:5000`\n3. **Review documentation:**\n - [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup\n - [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation\n - [Prompting Guide](docs/PROMPTING-GUIDE.md) - Advanced prompting examples\n - [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details\n\n## License\n\nSpec-Workflow MCP is released under the **GPL-3.0** license.\n\n资料来源：[README.md:45-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [src/markdown/templates/structure-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\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- [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
\n\n# Project Structure\n\n## Overview\n\nThe spec-workflow-mcp project is a Model Context Protocol (MCP) server that provides AI-powered specification-driven development workflow management. The project is organized into multiple subsystems that work together to enable seamless specification management, task tracking, and approval workflows for development projects.\n\n## High-Level Architecture\n\nThe project follows a modular architecture with three main interface options:\n\n```mermaid\ngraph TD\n A[AI Tools / LLM Clients] -->|MCP Protocol| B[MCP Server]\n B --> C[Core Engine]\n B --> D[Dashboard Backend]\n B --> E[Dashboard Frontend]\n B --> F[VSCode Extension]\n \n C -->|File System| G[.spec-workflow/]\n D --> G\n G --> H[specs/]\n G --> I[approvals/]\n G --> J[archive/]\n G --> K[steering/]\n G --> L[templates/]\n```\n\n## Directory Structure\n\nThe `.spec-workflow` directory is created within your project and contains all specification-related data:\n\n```plaintext\nyour-project/\n .spec-workflow/\n approvals/ # Pending approval items\n archive/ # Archived specifications\n specs/ # Active specification documents\n steering/ # Steering/prompting files\n templates/ # Default templates\n user-templates/ # User-defined templates\n config.example.toml # Configuration file template\n```\n\n## Core Components\n\n### MCP Server (`src/`)\n\nThe MCP server is the central component that exposes tools and resources to AI clients. It handles:\n\n- Specification document parsing and management\n- Task status tracking\n- Approval workflow execution\n- Implementation logging\n\n### Dashboard Backend\n\nThe backend provides REST API endpoints for the web dashboard:\n\n| Endpoint Pattern | Purpose |\n|------------------|---------|\n| `/api/specs/{name}` | Get spec document details |\n| `/api/specs/{name}/tasks/progress` | Get task progress for a spec |\n| `/api/specs/{name}/tasks/{taskId}/status` | Update task status |\n| `/api/approvals/{id}/{action}` | Perform approval actions |\n| `/api/approvals/batch/{action}` | Batch approval operations |\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx:1-20](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)\n\n### Dashboard Frontend\n\nThe web dashboard is a React-based interface located at `src/dashboard_frontend/`. It provides pages for:\n\n- **TasksPage** - View and manage tasks within specifications\n- **SettingsPage** - Configure automated cleanup jobs\n- **JobExecutionHistory** - View historical job executions\n\n#### Frontend API Integration\n\nThe frontend uses typed API calls to communicate with the backend:\n\n```typescript\nconst api = {\n getSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${encodeURIComponent(name)}/tasks/progress`),\n updateTaskStatus: (specName: string, taskId: string, status: 'pending' | 'in-progress' | 'completed' | 'blocked', reason?: string) =>\n putJson(`${prefix}/specs/${encodeURIComponent(specName)}/tasks/${encodeURIComponent(taskId)}/status`, { status, ...(reason && { reason }) }),\n approvalsAction: (id, action, body) => postJson(`${prefix}/approvals/${encodeURIComponent(id)}/${action}`, body),\n};\n```\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx:5-8](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)\n\n### VSCode Extension\n\nThe VSCode extension (`vscode-extension/`) provides an integrated experience within the VSCode editor. It includes:\n\n- **Webview-based UI** - React components rendered in VSCode\n- **App Component** - Main application entry point\n- **LogEntryCard Component** - Displays implementation log entries\n\n#### Webview Structure\n\n```mermaid\ngraph LR\n A[index.html] --> B[main.tsx]\n B --> C[App.tsx]\n C --> D[TasksPage]\n C --> E[SettingsPage]\n C --> F[LogEntryCard]\n```\n\nThe extension uses a webview to render the dashboard UI, with localization support through i18n modules.\n\n资料来源：[vscode-extension/src/webview/index.html:1-15](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n\n## Implementation Log System\n\nThe implementation log tracks code artifacts and changes made during development:\n\n```mermaid\ngraph TD\n A[Implementation Entry] --> B[Statistics]\n A --> C[Files Modified]\n A --> D[Files Created]\n A --> E[Artifacts]\n \n E --> E1[API Endpoints]\n E --> E2[Components]\n E --> E3[Functions]\n E --> E4[Classes]\n E --> E5[Integrations]\n```\n\n### Artifact Types\n\n| Type | Properties | Description |\n|------|------------|-------------|\n| apiEndpoints | method, path, purpose, location, requestFormat, responseFormat | HTTP API endpoints |\n| components | name, type, purpose, location, props, exports | UI/components |\n| functions | name, purpose, location, signature, isExported | Code functions |\n| classes | name, purpose, location, methods, isExported | Code classes |\n| integrations | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx:30-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n\n## Development Workflow Structure\n\n```mermaid\ngraph LR\n A[Create Spec] --> B[Generate Tasks]\n B --> C[Implement Code]\n C --> D[Log Artifacts]\n D --> E[Request Approval]\n E --> F[Approve/Request Changes]\n F -->|Approve| G[Archive Spec]\n F -->|Changes| C\n```\n\n### Template System\n\nTemplates define the structure of specification documents. The project includes:\n\n- **structure-template.md** - Defines code organization patterns\n- **user-templates/** - Custom user-defined templates\n\n#### Template Sections\n\nThe structure template includes guidelines for:\n\n1. **File Organization** - How to structure code files\n2. **Function/Method Organization** - Patterns for function design\n3. **Code Organization Principles** - Single responsibility, modularity, testability\n4. **Module Boundaries** - Defining inter-module interactions\n5. **Code Size Guidelines** - Limits for file and function sizes\n\n资料来源：[src/markdown/templates/structure-template.md:1-60](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\n\n## Configuration\n\nThe project uses TOML configuration files. The example configuration template is located at:\n\n```\n.spec-workflow/config.example.toml\n```\n\nConfiguration options include:\n- Dashboard connection settings\n- Cleanup job schedules\n- Template preferences\n- Approval workflow settings\n\n## Project Statistics Display\n\nThe dashboard displays project statistics including:\n\n| Metric | Description |\n|--------|-------------|\n| activeSpecs | Total active specification documents |\n| completedSpecs | Successfully completed specifications |\n| archivedSpecs | Archived/old specifications |\n| totalSpecs | All specifications count |\n| totalTasks | Total tasks across all specs |\n| completedTasks | Completed tasks count |\n\nThese statistics are aggregated from the `.spec-workflow` directory and displayed in both the web dashboard and VSCode extension.\n\n资料来源：[vscode-extension/src/webview/App.tsx:10-40](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n## Summary\n\nThe spec-workflow-mcp project is organized into distinct layers:\n\n1. **Core Layer** - MCP server handles AI tool interactions\n2. **Backend Layer** - REST API for dashboard operations\n3. **Frontend Layer** - Web dashboard and VSCode extension\n4. **Data Layer** - File-based storage in `.spec-workflow/`\n\nThis separation of concerns allows the project to serve multiple interfaces while maintaining a single source of truth for specification data.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Server Implementation](#mcp-server), [Web Dashboard](#web-dashboard), [Spec Management](#spec-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/server.ts) - **未在当前上下文提供**\n- [src/core/project-registry.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/project-registry.ts) - **未在当前上下文提供**\n- [src/dashboard/multi-server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/multi-server.ts) - **未在当前上下文提供**\n- [src/dashboard/project-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/project-manager.ts) - **未在当前上下文提供**\n- [src/core/global-dir.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/global-dir.ts) - **未在当前上下文提供**\n\n> ⚠️ **注意**: 指定的核心架构源文件（server.ts, project-registry.ts, multi-server.ts, project-manager.ts, global-dir.ts）在当前上下文中不可用。以下内容基于 README 文档、API 客户端代码和前端组件的有限片段综合得出。如需完整准确的架构文档，请确保提供上述源文件。\n\n
\n\n# System Architecture\n\n## Overview\n\nThe Spec-Workflow MCP (Model Context Protocol) system is designed as a bridge between AI coding assistants and structured software development workflows. It provides a specification-driven approach to managing software development tasks, approvals, and implementation tracking.\n\nThe architecture follows a multi-tier design with distinct components for MCP protocol handling, project management, dashboard services, and frontend interfaces.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n VSCode[VSCode Extension]\n CLI[Claude CLI]\n Desktop[Claude Desktop]\n end\n\n subgraph \"MCP Server Layer\"\n MCPServer[MCP Server]\n Tools[Tool Handlers]\n end\n\n subgraph \"Dashboard Layer\"\n Dashboard[Web Dashboard]\n MultiServer[Multi-Server Manager]\n ProjectManager[Project Manager]\n end\n\n subgraph \"Core Services\"\n Registry[Project Registry]\n GlobalDir[Global Directory]\n ApprovalEngine[Approval Engine]\n end\n\n subgraph \"Storage Layer\"\n SpecWorkflowDir[.spec-workflow/]\n Config[Config Files]\n Specs[Specs Data]\n Approvals[Approvals]\n end\n\n VSCode <--> MCPServer\n CLI <--> MCPServer\n Desktop <--> MCPServer\n \n MCPServer <--> Dashboard\n Dashboard <--> Registry\n Dashboard <--> ProjectManager\n ProjectManager <--> GlobalDir\n Registry <--> SpecWorkflowDir\n ApprovalEngine <--> SpecWorkflowDir\n```\n\n## Core Components\n\n### MCP Server (`src/server.ts`)\n\nThe MCP server acts as the central protocol handler that bridges AI tools with the spec workflow system.\n\n| Component | Purpose |\n|-----------|---------|\n| Protocol Handler | Processes MCP requests and responses |\n| Tool Registry | Manages available MCP tools |\n| Request Router | Routes requests to appropriate handlers |\n| Response Formatter | Formats tool outputs for AI consumption |\n\n资料来源：[README.md]() (MCP configuration documentation)\n\n### Project Registry (`src/core/project-registry.ts`)\n\nThe project registry maintains a centralized record of all projects connected to the spec workflow system.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| projectId | string | Unique project identifier |\n| path | string | Absolute path to project root |\n| config | Config | Project-specific configuration |\n| lastAccess | timestamp | Last activity timestamp |\n\n资料来源：[README.md]() (project structure documentation)\n\n### Dashboard Multi-Server Manager (`src/dashboard/multi-server.ts`)\n\nManages multiple MCP server instances and provides centralized coordination.\n\n```mermaid\ngraph LR\n A[Dashboard UI] --> B[Multi-Server Manager]\n B --> C[Server 1]\n B --> D[Server 2]\n B --> N[Server N]\n \n C --> E[Project 1]\n D --> F[Project 2]\n N --> G[Project N]\n```\n\n### Project Manager (`src/dashboard/project-manager.ts`)\n\nHandles project lifecycle operations including initialization, status tracking, and data synchronization.\n\n| Method | Description |\n|--------|-------------|\n| initializeProject() | Sets up .spec-workflow directory |\n| getProjectStats() | Retrieves project metrics |\n| syncProject() | Synchronizes project state |\n| archiveProject() | Archives completed projects |\n\n### Global Directory (`src/core/global-dir.ts`)\n\nProvides cross-project data management and shared resources.\n\nThe global directory stores shared configuration and data at:\n```\n~/.spec-workflow/\n```\n\n资料来源：[README.md]() (project structure documentation)\n\n## Directory Structure\n\nEach project managed by spec-workflow follows a standardized directory layout:\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # Approval requests and responses\n archive/ # Archived specifications\n specs/ # Active specifications\n steering/ # Steering configurations\n templates/ # Specification templates\n user-templates/ # Custom user templates\n config.example.toml # Example configuration\n```\n\n资料来源：[README.md]() (project structure documentation)\n\n## Dashboard Architecture\n\nThe dashboard provides a web-based interface for managing specs and tasks across connected projects.\n\n### Frontend Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| UI Framework | React | Component rendering |\n| API Client | TypeScript | Backend communication |\n| Styling | Tailwind CSS | Responsive design |\n| Internationalization | i18n | Multi-language support |\n\n资料来源：[vscode-extension/src/webview/App.tsx](), [src/dashboard_frontend/src/modules/api/api.tsx]()\n\n### Backend Services\n\n| Service | Port | Description |\n|---------|------|-------------|\n| Dashboard Server | 5000 | Main dashboard web server |\n| API Endpoints | /api/* | REST API for spec management |\n\nThe dashboard binds to `127.0.0.1` by default to prevent network exposure.\n\n资料来源：[README.md]() (security documentation)\n\n## API Architecture\n\n```mermaid\ngraph TD\n subgraph \"API Client (Frontend)\"\n TasksPage[TasksPage]\n SettingsPage[SettingsPage]\n end\n\n subgraph \"API Endpoints\"\n GET_SPECS[GET /specs/:name/all]\n UPDATE_TASK[PUT /specs/:name/tasks/:id/status]\n APPROVALS[POST /approvals/:id/:action]\n end\n\n TasksPage --> GET_SPECS\n SettingsPage --> UPDATE_TASK\n TasksPage --> APPROVALS\n```\n\n### Key API Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/specs/:name/all` | GET | Fetch all spec documents |\n| `/specs/:name/archived` | GET | Fetch archived specs |\n| `/specs/:name/tasks/progress` | GET | Get task progress statistics |\n| `/specs/:name/tasks/:id/status` | PUT | Update task status |\n| `/approvals/:id/:action` | POST | Process approval action |\n| `/approvals/batch/:action` | POST | Batch approval operations |\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx]()\n\n## Security Architecture\n\nThe system implements enterprise-grade security controls suitable for corporate environments.\n\n| Security Feature | Implementation | Purpose |\n|-----------------|----------------|---------|\n| Localhost Binding | `127.0.0.1` default | Prevent network exposure |\n| Rate Limiting | 120 req/min per client | Prevent abuse |\n| Audit Logging | JSON structured logs | Track all operations |\n| Security Headers | CSP, X-Frame-Options | Browser protection |\n| CORS Protection | Configurable origins | Cross-origin control |\n\n资料来源：[README.md]() (security documentation)\n\n## Deployment Options\n\n### Docker Deployment\n\n```mermaid\ngraph LR\n A[Docker Compose] --> B[Dashboard Container]\n B --> C[spec-workflow data]\n D[Projects] --> C\n```\n\n```bash\n# Using Docker Compose\ncd containers\ndocker-compose up --build\n\n# Dashboard available at http://localhost:5000\n```\n\n### MCP Client Integration\n\n| Client | Configuration Method |\n|--------|---------------------|\n| VSCode (Augment) | `settings.json` MCP servers |\n| Claude Code CLI | `claude mcp add` command |\n| Claude Desktop | `claude_desktop_config.json` |\n| Codex | `~/.codex/config.toml` |\n\n资料来源：[README.md]() (MCP integration documentation)\n\n## Implementation Log System\n\nThe implementation log tracks all changes made during development.\n\n```mermaid\ngraph TD\n A[Implementation Entry] --> B[Files Modified]\n A --> C[Files Created]\n A --> D[Artifacts]\n D --> E[API Endpoints]\n D --> F[Components]\n D --> G[Functions]\n D --> H[Classes]\n D --> I[Integrations]\n```\n\n### Log Entry Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| id | string | Unique entry identifier |\n| timestamp | Date | Entry creation time |\n| description | string | Summary of changes |\n| filesModified | string[] | List of modified files |\n| filesCreated | string[] | List of created files |\n| artifacts | Artifacts | Structured artifact data |\n\n资料来源：[src/dashboard/implementation-log-manager.ts](), [src/core/implementation-log-migrator.ts]()\n\n## Task Management Flow\n\n```mermaid\ngraph TD\n A[Create Task] --> B[pending]\n B --> C{inProgress?}\n C -->|Yes| D[in-progress]\n C -->|No| E[blocked]\n D --> F{Completed?}\n F -->|Yes| G[completed]\n F -->|No| D\n E --> H{Blocked Reason Required}\n H --> I[Save Blocked Reason]\n I --> B\n```\n\n### Task States\n\n| State | Description |\n|-------|-------------|\n| `pending` | Task created but not started |\n| `in-progress` | Task actively being worked on |\n| `completed` | Task finished successfully |\n| `blocked` | Task paused due to dependency |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx]()\n\n## Configuration Schema\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project\"]\n }\n }\n}\n```\n\n### Project Configuration (`config.toml`)\n\n| Section | Key | Type | Description |\n|---------|-----|------|-------------|\n| general | workspace | string | Project root path |\n| general | language | string | Primary language |\n| dashboard | port | number | Dashboard server port |\n| dashboard | host | string | Bind address |\n| cleanup | enabled | boolean | Auto cleanup toggle |\n| cleanup | schedule | string | Cron schedule |\n\n## Summary\n\nThe spec-workflow-mcp architecture provides:\n\n1. **Protocol Bridge**: Seamless MCP integration with AI coding tools\n2. **Specification-Driven Workflow**: Structured approach to software development\n3. **Multi-Project Management**: Centralized dashboard for all projects\n4. **Enterprise Security**: Production-ready security controls\n5. **Flexible Deployment**: Docker and native deployment options\n\nThis architecture enables teams to maintain consistent development practices while leveraging AI assistance throughout the development lifecycle.\n\n---\n\n\n\n## MCP Server Implementation\n\n### 相关页面\n\n相关主题：[Approval Workflow System](#approval-workflow), [Spec Management](#spec-management), [Steering Documents](#steering-documents)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/index.ts)\n- [src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n- [src/tools/spec-status.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-status.ts)\n- [src/tools/log-implementation.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/log-implementation.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- [src/prompts/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/index.ts)\n
\n\n# MCP Server Implementation\n\n## Overview\n\nThe MCP Server Implementation provides a Model Context Protocol (MCP) server that integrates the spec-workflow system into AI coding assistants. It exposes structured tools that AI agents can invoke to manage specification-driven development workflows, including approvals, spec tracking, and implementation logging.\n\n**Purpose:**\n- Bridge AI coding assistants with the spec-workflow specification management system\n- Enable AI agents to create, review, and update specification documents\n- Provide human-in-the-loop approval workflows for AI-generated code\n- Track implementation progress across multiple specification phases\n\n**Scope:**\nThe server operates as a local MCP server that connects to a project directory, providing tools for steering documentation, spec creation, approval management, and implementation logging. It works alongside a dashboard server for human review and approval.\n\n## Architecture\n\n### System Components\n\nThe MCP server architecture consists of three interconnected layers:\n\n```mermaid\ngraph TD\n A[\"AI Coding Assistant
(Cline, Cursor, VS Code)\"] --> B[\"MCP Server
(spec-workflow-mcp)\"]\n B --> C[\"Dashboard Server
(Port 5000)\"]\n B --> D[\"Project Directory
(.spec-workflow)\"]\n C --> D\n \n B --> E[\"Tools\"]\n E --> E1[\"approvals\"]\n E --> E2[\"spec-status\"]\n E --> E3[\"spec-workflow-guide\"]\n E --> E4[\"steering-guide\"]\n E --> E5[\"log-implementation\"]\n E --> E6[\"prompt-generation\"]\n```\n\n### MCP Server Entry Point\n\nThe server is initialized in `src/index.ts` and configured via command-line arguments. The primary execution path:\n\n1. Parse command-line arguments for project path and mode\n2. Initialize the MCP server with stdio transport\n3. Register all available tools and resources\n4. Begin message processing loop\n\n**Configuration Example:**\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:1]()\n\n> **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.\n\n## Available Tools\n\n### Tool Overview\n\n| Tool Name | Purpose | Key Actions |\n|-----------|---------|-------------|\n| `approvals` | Manage approval workflows | request, status, delete |\n| `spec-status` | Track specification states | get, update |\n| `spec-workflow-guide` | Load spec workflow instructions | N/A (resource loader) |\n| `steering-guide` | Load steering workflow instructions | N/A (resource loader) |\n| `log-implementation` | Record implementation artifacts | create, list, update |\n| `prompt-generation` | Generate workflow prompts | N/A (resource loader) |\n\n### Approvals Tool\n\nThe approvals tool manages the human-in-the-loop approval workflow. All AI-generated specs require explicit human approval before proceeding.\n\n**Actions:**\n\n| Action | Parameters | Description |\n|--------|------------|-------------|\n| `request` | `filePath` | Request approval for a specific file |\n| `status` | `approvalId` | Check current status of an approval request |\n| `delete` | `approvalId` | Remove approval after acceptance/rejection |\n\n**Workflow Integration:**\n\n```mermaid\ngraph LR\n A[AI Creates Spec] --> B[Request Approval]\n B --> C{Human Reviews}\n C -->|Approved| D[Delete Approval]\n C -->|Needs Revision| E[AI Updates Spec]\n E --> B\n D --> F[Proceed to Implementation]\n```\n\n**Approval Status States:**\n\n| Status | Meaning |\n|--------|---------|\n| `pending` | Awaiting human review |\n| `approved` | Human accepted the specification |\n| `needs-revision` | Human requested changes |\n| `rejected` | Human rejected the specification |\n\n资料来源：[src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n\n### Spec Status Tool\n\nThe spec-status tool tracks the lifecycle state of individual specifications.\n\n**Supported States:**\n\n| State | Description |\n|-------|-------------|\n| `draft` | Initial creation phase |\n| `in-progress` | Actively being implemented |\n| `review` | Under human review |\n| `approved` | Approved and ready for next phase |\n| `completed` | Fully implemented |\n| `archived` | Moved to archive |\n\n**Operations:**\n- Query current status of any spec\n- Update status after phase transitions\n- Retrieve history of status changes\n\n资料来源：[src/tools/spec-status.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-status.ts)\n\n### Spec Workflow Guide\n\nProvides structured guidance for the specification creation workflow. The guide defines a 4-phase process:\n\n```mermaid\ngraph TD\n P1[Phase 1: Design] --> P2[Phase 2: Spec]\n P2 --> P3[Phase 3: Tasks]\n P3 --> P4[Phase 4: Implementation]\n \n P1 --> P1A[product.md]\n P2 --> P2A[design.md]\n P3 --> P3A[tasks.md]\n P4 --> P4A[Code Files]\n```\n\n**Phase Details:**\n\n| Phase | Document | Template | Output Location |\n|-------|----------|----------|-----------------|\n| 1 | Product | product-template.md | .spec-workflow/steering/ |\n| 2 | Design | design-template.md | .spec-workflow/specs/{name}/ |\n| 3 | Tasks | tasks-template.md | .spec-workflow/specs/{name}/ |\n| 4 | Implementation | N/A | Project root |\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### Steering Guide\n\nDefines the steering documentation workflow for project-wide guidance:\n\n**Steering Phases:**\n\n| Phase | Purpose | Document | Template |\n|-------|---------|----------|----------|\n| 1 | Product Vision | product.md | product-template.md |\n| 2 | Technology | tech.md | tech-template.md |\n| 3 | Structure | structure.md | structure-template.md |\n\n**Template Resolution:**\n\n```mermaid\ngraph TD\n A[Need Template] --> B{user-templates exist?}\n B -->|Yes| C[Use user-templates]\n B -->|No| D[Use templates]\n C --> E[Load Template]\n D --> E\n```\n\nTemplates are resolved first from `.spec-workflow/user-templates/` directory, falling back to `.spec-workflow/templates/` if no custom templates exist.\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### Log Implementation Tool\n\nRecords and tracks implementation artifacts generated during the coding phase. Enables the AI to maintain a structured record of what was built.\n\n**Artifact Types:**\n\n| Type | Fields | Description |\n|------|--------|-------------|\n| `apiEndpoints` | method, path, purpose, location | REST API definitions |\n| `components` | name, type, purpose, location, props | UI/functional components |\n| `functions` | name, purpose, location, signature, isExported | Code functions |\n| `classes` | name, purpose, location, methods, isExported | Class definitions |\n| `integrations` | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n**Implementation Log Entry Structure:**\n\n```typescript\ninterface ImplementationLogEntry {\n timestamp: string;\n specName: string;\n filesCreated: string[];\n filesModified: 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资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## Workflow Integration\n\n### Initialization Sequence\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant MCP\n participant AI\n \n User->>Dashboard: Start dashboard (port 5000)\n User->>MCP: Start MCP server with project path\n User->>AI: Configure AI client with MCP\n AI->>MCP: List available tools\n MCP-->>AI: Return tool definitions\n AI->>MCP: Call steering-guide\n MCP-->>AI: Return workflow instructions\n AI->>MCP: Create spec via prompts\n AI->>MCP: Request approval\n MCP->>Dashboard: Store approval request\n User->>Dashboard: Review and approve\n Dashboard->>MCP: Update approval status\n MCP-->>AI: Approval granted\n```\n\n### Client Configuration\n\nThe MCP server supports multiple AI coding assistant clients:\n\n| Client | Configuration Location | Notes |\n|--------|----------------------|-------|\n| Claude Desktop | claude_desktop_config.json | Run dashboard first |\n| Cline | mcp_settings.json | Direct npx execution |\n| Claude Dev | mcp_settings.json | Direct npx execution |\n| Continue | config.json | MCP server array |\n| Cursor | settings.json | User settings |\n\n资料来源：[README.md:1]()\n\n## Dashboard Server Integration\n\nThe dashboard server runs independently on port 5000 and provides:\n\n- **Approval Management UI**: Review pending approvals with file diffs\n- **Spec Overview**: View all specs and their current states\n- **Statistics Dashboard**: Track progress across specs and tasks\n- **Implementation Logs**: Browse logged implementation artifacts\n\n**Single Instance Model:**\n\n> **Note:** Only one dashboard instance is required. All projects connect to the same dashboard server.\n\n```bash\n# Start dashboard\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n\n# Dashboard accessible at http://localhost:5000\n```\n\n资料来源：[README.md:1]()\n\n## Project Directory Structure\n\nThe MCP server expects and manages the following directory structure within each project:\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # Active approval requests\n archive/ # Completed/archived specs\n specs/ # Individual spec directories\n {spec-name}/\n design.md\n tasks.md\n steering/ # Project-level steering docs\n product.md\n tech.md\n structure.md\n templates/ # Default templates\n user-templates/ # Project-specific custom templates\n config.example.toml\n```\n\n## Prompt Generation\n\nThe prompt-generation resource provides AI-usable prompts for each workflow phase, enabling consistent spec creation behavior.\n\n**Prompt Categories:**\n\n| Category | Purpose |\n|----------|---------|\n| spec-creation | Guide spec document creation |\n| task-breakdown | Convert specs to implementable tasks |\n| implementation | Guide code implementation |\n| review | Facilitate human review |\n\n资料来源：[src/prompts/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/index.ts)\n\n## Error Handling\n\nThe MCP server implements several error handling strategies:\n\n| Scenario | Handling |\n|----------|----------|\n| Dashboard unavailable | Continue without real-time sync |\n| Approval delete fails | Stop workflow, return to polling |\n| Template not found | Fall back to default templates |\n| Invalid spec state | Return error, require correction |\n| File system errors | Return detailed error message |\n\n**Critical Workflow Constraint:**\n\nIf approval deletion fails after acceptance, the workflow **must stop** and return to polling status. The implementation cannot proceed until the approval cleanup succeeds.\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n## Development\n\n### Building the Server\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Source Organization\n\n| Path | Purpose |\n|------|---------|\n| src/index.ts | Main entry point, MCP server initialization |\n| src/tools/*.ts | Tool implementations |\n| src/prompts/*.ts | Prompt generation utilities |\n| src/dashboard/*.ts | Dashboard server components |\n| src/dashboard_frontend/*.tsx | Dashboard React components |\n\n## Summary\n\nThe MCP Server Implementation provides a comprehensive bridge between AI coding assistants and the spec-workflow specification management system. By exposing structured tools for approvals, spec tracking, implementation logging, and workflow guidance, it enables AI agents to participate in human-controlled development workflows while maintaining full transparency and auditability of all generated artifacts.\n\n---\n\n\n\n## Spec Management\n\n### 相关页面\n\n相关主题：[Approval Workflow System](#approval-workflow), [Steering Documents](#steering-documents), [MCP Server Implementation](#mcp-server)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n- [src/core/parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/parser.ts)\n- [src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n- [src/core/task-validator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-validator.ts)\n- [src/markdown/templates/requirements-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/requirements-template.md)\n- [src/markdown/templates/design-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/design-template.md)\n- [src/markdown/templates/tasks-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/tasks-template.md)\n- [src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n
\n\n# Spec Management\n\n## Overview\n\nSpec Management is the core system within spec-workflow-mcp that enables structured project specification, task planning, and implementation tracking. This system provides a standardized approach to converting project ideas into actionable, trackable implementation tasks through a Markdown-based specification document format.\n\nThe spec management system serves as the foundation for the entire workflow, bridging the gap between high-level project requirements and concrete implementation tasks. It ensures that every feature or change is properly documented, validated, and tracked throughout its lifecycle.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User] --> B[Spec Creation]\n B --> C[Spec Templates]\n C --> D[Requirements Template]\n C --> E[Design Template]\n C --> F[Tasks Template]\n D --> G[Core Parser]\n E --> G\n F --> H[Task Parser]\n G --> I[Spec Document]\n H --> J[Task Validation]\n J --> K[Task Status Tracking]\n I --> L[Dashboard / VSCode Extension]\n K --> L\n```\n\n## Spec Document Structure\n\n### Directory Layout\n\nSpecs are stored within each project's `.spec-workflow` directory following a standardized structure:\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.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n### Specification Components\n\nEach specification document is composed of multiple template sections that capture different aspects of the project requirements.\n\n| Component | Purpose | File Pattern |\n|-----------|---------|--------------|\n| Requirements | Define what needs to be built | `requirements-template.md` |\n| Design | Document architectural decisions | `design-template.md` |\n| Tasks | Break down implementation steps | `tasks-template.md` |\n\n## Requirements Template\n\nThe requirements template establishes the foundation of a specification by capturing the essential \"what\" of the feature or change.\n\n### Key Sections\n\nThe requirements template includes structured fields for:\n\n- **Title and Description**: Clear identification of the feature\n- **Purpose**: The motivation behind the feature\n- **Leverage**: Existing code, patterns, or systems to build upon\n- **Requirements**: Specific constraints and conditions that must be met\n- **Acceptance Criteria**: Measurable outcomes that define success\n\n资料来源：[src/markdown/templates/requirements-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/requirements-template.md)\n\n### Purpose Field\n\nThe `purposes` array captures multiple reasons for a given feature:\n\n```typescript\n// Task structure showing purposes field\ninterface Task {\n purposes: string[];\n requirements: string[];\n leverage?: string;\n prompt?: string;\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## Design Template\n\nThe design template documents the \"how\" of implementation, capturing architectural decisions and technical approach.\n\n### Structure\n\nThe design template typically includes:\n\n- **Code Organization**: Guidelines for file and module structure\n- **Module Boundaries**: Defining how different parts interact\n- **Function/Method Organization**: Patterns for organizing code logic\n- **Code Size Guidelines**: Limits on file and function complexity\n\n资料来源：[src/markdown/templates/design-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/design-template.md)\n\n### Design Principles\n\nThe template enforces several key principles:\n\n| Principle | Description |\n|-----------|-------------|\n| Single Responsibility | Each file should have one clear purpose |\n| Modularity | Code organized into reusable modules |\n| Testability | Structure code to be easily testable |\n| Consistency | Follow patterns established in the codebase |\n\n## Tasks Template\n\nThe tasks template breaks down the implementation into granular, actionable items that can be tracked and completed independently.\n\n### Task Properties\n\nEach task within the tasks template supports the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | string | Unique identifier for the task |\n| `status` | enum | Current state: `pending`, `in-progress`, `completed`, `blocked` |\n| `completed` | boolean | Whether task is finished |\n| `inProgress` | boolean | Whether task is currently being worked on |\n| `purposes` | string[] | Array of purpose descriptions |\n| `requirements` | string[] | Specific requirements for this task |\n| `leverage` | string | Existing code/patterns to leverage |\n| `prompt` | string | AI prompt associated with task |\n| `isHeader` | boolean | Whether task is a section header |\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## Spec Parsing System\n\n### Core Parser\n\nThe core parser (`src/core/parser.ts`) is responsible for reading and interpreting spec documents, extracting structured data from Markdown content.\n\n```mermaid\ngraph LR\n A[Markdown Spec File] --> B[Core Parser]\n B --> C[Extracted Metadata]\n B --> D[Tasks Array]\n B --> E[Requirements]\n B --> F[Design Decisions]\n```\n\n资料来源：[src/core/parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/parser.ts)\n\n### Task Parser\n\nThe task parser (`src/core/task-parser.ts`) specializes in extracting and organizing task information from the tasks section of spec documents.\n\n**Capabilities:**\n- Extract task ID and status\n- Parse purpose and requirements arrays\n- Handle nested task hierarchies\n- Support both ordered and unordered task formats\n\n资料来源：[src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n\n### Task Validator\n\nThe task validator (`src/core/task-validator.ts`) ensures that parsed tasks meet the required structural and content requirements.\n\n**Validation Checks:**\n- Required fields presence\n- Status value validity\n- Purpose array non-empty\n- Requirement completeness\n\n资料来源：[src/core/task-validator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-validator.ts)\n\n## Task Status Workflow\n\n### State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress : Start Work\n InProgress --> Completed : Finish Task\n InProgress --> Blocked : Encounter Blocker\n Blocked --> InProgress : Resolve Blocker\n Completed --> [*]\n Blocked --> [*] : Cancel Task\n```\n\n### Status Transitions API\n\n```typescript\nupdateTaskStatus: (\n specName: string, \n taskId: string, \n status: 'pending' | 'in-progress' | 'completed' | 'blocked', \n reason?: string\n) => void\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `specName` | string | Yes | Name of the specification |\n| `taskId` | string | Yes | Unique task identifier |\n| `status` | enum | Yes | New status value |\n| `reason` | string | No | Reason for status change (especially for blocked) |\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## Implementation Tracking\n\n### Implementation Log Entry Structure\n\nAs tasks are completed, the system tracks implementation artifacts through the ImplementationLogManager:\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: Date;\n filesModified: string[];\n filesCreated: string[];\n statistics: {\n linesAdded: number;\n linesRemoved: number;\n };\n artifacts?: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n}\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### Artifact Types\n\n| Artifact Type | Properties | Description |\n|--------------|------------|-------------|\n| `apiEndpoints` | method, path, purpose, location, requestFormat, responseFormat | REST API endpoints created |\n| `components` | name, type, purpose, location, props, exports | UI/components created |\n| `functions` | name, purpose, location, signature, isExported | Functions implemented |\n| `classes` | name, purpose, location, methods, isExported | Classes implemented |\n| `integrations` | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n资料来源：[src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n\n## Dashboard Integration\n\n### Project Statistics\n\nThe dashboard provides an overview of spec and task progress:\n\n| Metric | Description |\n|--------|-------------|\n| `activeSpecs` | Total number of active specifications |\n| `completedSpecs` | Specifications with all tasks completed |\n| `archivedSpecs` | Specifications moved to archive |\n| `totalSpecs` | Total specs (active + archived) |\n| `totalTasks` | Total tasks across all specs |\n| `completedTasks` | Tasks marked as completed |\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### Spec Operations\n\nThe dashboard supports the following operations:\n\n| Operation | Endpoint | Description |\n|-----------|----------|-------------|\n| View Spec | `/specs/{name}` | Retrieve spec document |\n| View All Documents | `/specs/{name}/all` | Get all spec-related documents |\n| Archive Spec | `/specs/{name}/archive` | Move spec to archive |\n| Unarchive Spec | `/specs/{name}/unarchive` | Restore from archive |\n| Get Tasks Progress | `/specs/{name}/tasks/progress` | Calculate task completion percentage |\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### Task Progress Calculation\n\n```typescript\nconst progress = spec.taskProgress?.total\n ? Math.round((spec.taskProgress.completed / spec.taskProgress.total) * 100)\n : 0;\n```\n\n资料来源：[src/dashboard_frontend/src/modules/pages/SpecsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/SpecsPage.tsx)\n\n## Steering Documents\n\nSteering documents provide project-level guidance and are managed separately from individual specs:\n\n| Document Type | Purpose |\n|--------------|---------|\n| Steering Docs | Project-level architectural decisions and direction |\n| User Templates | Customizable templates for organization-specific needs |\n| Standard Templates | Built-in templates for common spec patterns |\n\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## AI Integration\n\n### Spec Creation Prompts\n\nThe system uses structured prompts for AI-assisted spec creation:\n\n```typescript\ninterface CreateSpecInput {\n featureName: string;\n description: string;\n leverage?: string;\n requirements?: string[];\n}\n```\n\n资料来源：[src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n\n### Task Implementation Prompts\n\nWhen implementing tasks, the AI receives contextual information including:\n\n- Task purposes and requirements\n- Leverage information (existing code to build upon)\n- Design guidelines from the spec\n- Implementation log context\n\n```typescript\ninterface ImplementTaskInput {\n task: Task;\n spec: Spec;\n leverage: string;\n context: ImplementationLogEntry[];\n}\n```\n\n资料来源：[src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n\n## Execution History\n\nThe system tracks job executions for auditing and debugging purposes:\n\n| Field | Description |\n|-------|-------------|\n| `itemsDeleted` | Number of items removed during execution |\n| `duration` | Execution time in milliseconds |\n| `error` | Error message if execution failed |\n\n```typescript\n// Duration formatting\n{(execution.duration / 1000).toFixed(2)}s\n```\n\n资料来源：[src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx)\n\n### Execution Statistics\n\n| Metric | Description |\n|--------|-------------|\n| `totalExecutions` | Total number of execution runs |\n| `successRate` | Percentage of successful executions |\n\n## Best Practices\n\n### Writing Effective Specs\n\n1. **Clear Purpose Statements**: Each task should have at least one well-defined purpose\n2. **Leverage Existing Code**: Always reference existing patterns or utilities to build upon\n3. **Measurable Requirements**: Requirements should be verifiable and testable\n4. **Appropriate Granularity**: Tasks should be small enough to complete in one session\n\n### Task Naming Conventions\n\n- Use descriptive task IDs\n- Group related tasks under section headers\n- Mark section headers with `isHeader: true`\n- Keep task titles concise but informative\n\n### Progress Tracking\n\n- Update task status promptly when work begins\n- Use the blocked status with reasons when encountering obstacles\n- Review implementation logs regularly to ensure accuracy\n\n---\n\n\n\n## Approval Workflow System\n\n### 相关页面\n\n相关主题：[Spec Management](#spec-management), [Web Dashboard](#web-dashboard), [VSCode Extension](#vscode-extension)\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/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\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/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/DashboardStatistics.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/DashboardStatistics.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
\n\n# Approval Workflow System\n\n## Overview\n\nThe Approval Workflow System is a core component of the spec-workflow-mcp project that enforces structured document review and revision processes. It ensures that all specifications, designs, and implementation tasks undergo explicit human approval before proceeding to subsequent phases.\n\n**Key Responsibilities:**\n- Managing approval requests with associated metadata (title, description, file path)\n- Tracking approval status through polling mechanisms\n- Enforcing sequential workflow progression (no phase skipping)\n- Blocking operations when approvals fail or cleanup is unsuccessful\n- Providing cross-platform interfaces (web dashboard and VS Code extension)\n\n**资料来源：**\n[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n[src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"Client Interfaces\"\n VSCODE[VS Code Extension]\n DASHBOARD[Web Dashboard]\n end\n\n subgraph \"Core Services\"\n APPROVALS[approvals Tool]\n WATCHER[File Watcher]\n STORAGE[Approval Storage]\n end\n\n subgraph \"Data Layer\"\n APPROVALS_DIR[.spec-workflow/approvals/]\n end\n\n VSCODE --> |API calls| APPROVALS\n DASHBOARD --> |API calls| APPROVALS\n APPROVALS --> STORAGE\n STORAGE --> APPROVALS_DIR\n WATCHER --> |File monitoring| APPROVALS_DIR\n WATCHER --> |Events| STORAGE\n```\n\n### Technology Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Client UI | React + TypeScript | Dashboard and VS Code webview |\n| State Management | React Hooks | Local UI state |\n| Communication | VS Code API / WebSocket | Real-time updates |\n| Persistence | JSON Files | Approval records storage |\n| Monitoring | Node.js fs.watch | Directory change detection |\n\n**资料来源：**\n[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx:1-100)\n[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n\n---\n\n## Approval Lifecycle\n\n### State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: request action\n Pending --> Approved: User approves\n Pending --> NeedsRevision: User requests changes\n Approved --> Deleted: delete action (success)\n NeedsRevision --> Pending: User re-submits\n Deleted --> [*]\n Deleted --> Pending: delete action fails\n```\n\n### Workflow Phases\n\nEach workflow phase follows an identical approval pattern:\n\n| Phase | Document Type | File Path |\n|-------|--------------|-----------|\n| Phase 1 | Product Document | `.spec-workflow/steering/product.md` |\n| Phase 2 | Tech Document | `.spec-workflow/steering/tech.md` |\n| Phase 3 | Structure Document | `.spec-workflow/steering/structure.md` |\n\n**Steering Workflow Phase Pattern:**\n\n```mermaid\ngraph TD\n START[Phase Start] --> TEMPLATE[Check user-templates first,
then read template]\n TEMPLATE --> ANALYZE[Analyze content]\n ANALYZE --> CREATE[Create document file]\n CREATE --> APPROVE[Request approval
approvals action: request]\n APPROVE --> STATUS[Poll status
approvals action: status]\n STATUS --> CHECK{Status?}\n CHECK -->|needs-revision| UPDATE[Update document
using user comments]\n UPDATE --> CREATE\n CHECK -->|approved| CLEAN[Delete approval
approvals action: delete]\n CLEAN -->|success| NEXT[Next Phase]\n CLEAN -->|failed| STATUS\n \n style START fill:#e6f3ff\n style CHECK fill:#ffe6e6\n style NEXT fill:#e6f3ff\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## Approvals Tool API\n\n### Tool Actions\n\nThe `approvals` tool supports three primary actions:\n\n| Action | Parameters | Description |\n|--------|------------|-------------|\n| `request` | `title`, `description?`, `filePath` | Create new approval request |\n| `status` | `approvalId?` | Check approval status (polling) |\n| `delete` | `approvalId` | Remove approval after completion |\n\n### Request Action Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | `\"request\"` | Yes | Operation to perform |\n| `title` | `string` | Yes | Approval request title |\n| `description` | `string` | No | Detailed description |\n| `filePath` | `string` | Yes | Path to the document under review |\n\n### Usage Example\n\n```typescript\n// Request approval for a document\nconst approvalRequest = await tool.call({\n action: \"request\",\n title: \"Product Vision Document\",\n description: \"Initial product document for review\",\n filePath: \".spec-workflow/steering/product.md\"\n});\n\n// Poll for status until resolved\nlet status = await tool.call({ action: \"status\", approvalId: approvalRequest.id });\nwhile (status === \"pending\" || status === \"in_progress\") {\n await sleep(2000);\n status = await tool.call({ action: \"status\", approvalId: approvalRequest.id });\n}\n\n// Delete after successful approval\nawait tool.call({ action: \"delete\", approvalId: approvalRequest.id });\n```\n\n**资料来源：**\n[src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n\n---\n\n## Data Models\n\n### Approval Record Schema\n\n```typescript\ninterface Approval {\n id: string; // Unique identifier (UUID)\n title: string; // Display title\n description?: string; // Optional description\n filePath: string; // Path to document under review\n status: ApprovalStatus; // Current state\n createdAt: Date; // Creation timestamp\n updatedAt: Date; // Last modification timestamp\n response?: string; // Approval response message\n requestedBy?: string; // User who requested approval\n}\n\ntype ApprovalStatus = \"pending\" | \"approved\" | \"needs-revision\" | \"rejected\";\n```\n\n### Storage Location\n\nApprovals are persisted as JSON files in the `.spec-workflow/approvals/` directory:\n\n```\n.spec-workflow/\n└── approvals/\n ├── {uuid}.json # Individual approval records\n └── archive/ # Archived approvals (completed)\n```\n\n**资料来源：**\n[src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n\n---\n\n## UI Components\n\n### VS Code Extension Dashboard\n\nThe VS Code extension provides an integrated sidebar for managing approvals:\n\n**Features:**\n- Real-time approval list with pending count badge\n- Individual action buttons (Approve, Request Changes, View in Editor)\n- Batch selection mode for bulk operations\n- Selection counter and clear selection functionality\n- Translation support (i18n)\n\n**UI Layout:**\n\n```tsx\n// Approval card structure\n\n \n
\n

{approval.title}

\n {t('approvals.status.pending')}\n
\n \n \n {approval.description &&

{approval.description}

}\n {approval.filePath &&

{approval.filePath}

}\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:1-80)\n\n### Web Dashboard Statistics\n\nThe web dashboard displays approval statistics:\n\n```tsx\n
\n
\n {approvals.length}\n
\n
\n {approvals.length > 0 \n ? t('stats.approvals.awaiting') \n : t('stats.approvals.allClear')}\n
\n
\n```\n\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## Critical Workflow Rules\n\nThe approval system enforces strict rules that must be followed:\n\n| Rule | Description | Consequence if Violated |\n|------|-------------|-------------------------|\n| **Sequential Phases** | Complete phases in order | Workflow blocked |\n| **Blocking Cleanup** | Approval delete must succeed | Next phase blocked |\n| **No Verbal Approval** | Dashboard/VS Code only | Not accepted |\n| **No Proceed on \"approved\"** | Check system status only | Invalid workflow |\n| **Two-phase completion** | Approved status + successful cleanup | Incomplete transition |\n\n### Blocking Conditions\n\n```typescript\n// CRITICAL: Must have approved status AND successful cleanup before next phase\nif (status !== \"approved\") {\n return { success: false, error: \"Approval not granted\" };\n}\n\nconst deleteResult = await approvals({ action: \"delete\", approvalId });\nif (!deleteResult.success) {\n return { success: false, error: \"Cleanup failed - blocking next phase\" };\n}\n\n// Proceed to next phase...\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## File Watcher Integration\n\nThe approval system integrates with the file watcher for real-time updates:\n\n```mermaid\ngraph LR\n A[File System Event] --> B[watcher.ts]\n B --> C{Event Type}\n C -->|approval_created| D[Update UI]\n C -->|approval_deleted| E[Refresh List]\n C -->|approval_updated| F[Sync Status]\n```\n\n**Watched Events:**\n- File creation in `.spec-workflow/approvals/`\n- File modification\n- File deletion\n\n**资料来源：**\n[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n\n---\n\n## Internationalization\n\nThe approval system supports 11 languages with i18n keys:\n\n| Key | English | Japanese | Chinese |\n|-----|---------|----------|---------|\n| `approvals.status.pending` | Pending | 保留中 | 待处理 |\n| `approvals.approve` | Approve | 承認 | 批准 |\n| `approvals.reject` | Request Changes | 変更依頼 | 请求更改 |\n| `approvals.noPending` | No pending approvals | 承認待ちなし | 无待批准项 |\n| `approvals.selectedCount` | {count} selected | {count}件選択 | 已选择 {count} 项 |\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## Implementation Log Integration\n\nWhen tasks are implemented following approval, the system tracks artifacts:\n\n```typescript\n// Artifacts tracked in implementation logs\ninterface Artifacts {\n apiEndpoints: APIEndpoint[];\n components: Component[];\n filesCreated: string[];\n filesModified: string[];\n}\n\n// Example artifact recording\nmarkdown += `### API Endpoints\\n\\n`;\nartifacts.apiEndpoints.forEach(api => {\n markdown += `#### ${api.method} ${api.path}\\n`;\n markdown += `- **Purpose:** ${api.purpose}\\n`;\n markdown += `- **Location:** ${api.location}\\n`;\n});\n```\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## Best Practices\n\n1. **Always poll for status** - Never assume immediate approval\n2. **Handle cleanup failures** - Block workflow on delete failures\n3. **Use file paths only** - Approval requests should contain paths, not content\n4. **Wait for full resolution** - Both approval AND cleanup must complete\n5. **Provide clear titles** - Help reviewers quickly identify documents\n\n---\n\n## Related Documentation\n\n- [Workflow Process](docs/WORKFLOW.md) - Complete workflow guidelines\n- [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details\n- [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation\n- [Development Guide](docs/DEVELOPMENT.md) - Contributing and setup\n\n---\n\n\n\n## Steering Documents\n\n### 相关页面\n\n相关主题：[Spec Management](#spec-management), [Approval Workflow System](#approval-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/create-steering-doc.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-steering-doc.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/markdown/templates/product-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/product-template.md)\n- [src/markdown/templates/tech-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/tech-template.md)\n- [src/markdown/templates/structure-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\n
\n\n# Steering Documents\n\n## Overview\n\nSteering Documents are foundational markdown files that guide the development process by defining the product vision, technical architecture, and codebase organization. They serve as the single source of truth for maintaining alignment between development decisions and project goals.\n\nThe Steering Documents system consists of three core documents that work together to provide comprehensive guidance for the project.\n\n## Document Types\n\n### 1. Product Vision Document (`product.md`)\n\nThe product document defines the **what** and **why** of the project.\n\n| Section | Purpose |\n|---------|---------|\n| Product Vision | High-level description of the product's purpose and value proposition |\n| Target Users | Identification of primary and secondary user groups |\n| Key Features | Core functionality that delivers value to users |\n| Business Objectives | Goals and metrics that measure project success |\n\n**Template Location:** `src/markdown/templates/product-template.md`\n\n### 2. Technical Architecture Document (`tech.md`)\n\nThe tech document defines the **how** of the technical implementation.\n\n| Section | Purpose |\n|---------|---------|\n| Technology Stack | Programming languages, frameworks, and tools used |\n| Architecture Decisions | Key technical choices and their rationale |\n| Development Principles | Standards and practices for code quality |\n| Dependencies | External libraries and services integrated |\n\n**Template Location:** `src/markdown/templates/tech-template.md`\n\n### 3. Codebase Structure Document (`structure.md`)\n\nThe structure document defines the **where** of code organization.\n\n| Section | Purpose |\n|---------|---------|\n| Directory Structure | High-level organization of project folders |\n| Module Architecture | How code is partitioned into logical units |\n| Key Files | Important files and their responsibilities |\n| Module Relationships | Dependencies between different parts of the codebase |\n\n**Template Location:** `src/markdown/templates/structure-template.md`\n\n## Workflow\n\n```mermaid\ngraph TD\n A[Create/Update Steering Documents] --> B{Document Type}\n B -->|product.md| C[Define Vision & Features]\n B -->|tech.md| D[Document Architecture]\n B -->|structure.md| E[Map Codebase Organization]\n \n C --> F[Review with AI Assistant]\n D --> F\n E --> F\n \n F --> G[Store in Project Root]\n G --> H[Reference During Development]\n```\n\n## Steering Guide Tool\n\nThe `steering-guide.ts` module provides the core functionality for managing steering documents.\n\n**Location:** `src/tools/steering-guide.ts`\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `createSteeringDocument()` | Generate new steering documents from templates |\n| `updateSteeringDocument()` | Modify existing documents with new information |\n| `validateSteeringDocument()` | Ensure document structure matches template |\n| `getSteeringDocument()` | Retrieve document content for reference |\n\n### Configuration Options\n\n```typescript\ninterface SteeringConfig {\n outputDir: string; // Directory for steering documents\n templateDir: string; // Location of markdown templates\n autoSync: boolean; // Auto-sync with project changes\n validationLevel: 'strict' | 'loose' | 'none';\n}\n```\n\n## Document Templates\n\n### Product Template Structure\n\n```markdown\n# Product Vision\n[High-level product description]\n\n# Target Users\n[User personas and use cases]\n\n# Key Features\n- Feature 1\n- Feature 2\n\n# Business Objectives\n[Success metrics and goals]\n```\n\n### Tech Template Structure\n\n```markdown\n# Technology Stack\n[Languages, frameworks, tools]\n\n# Architecture Decisions\n[Key technical decisions]\n\n# Development Principles\n[Code standards and practices]\n```\n\n### Structure Template Structure\n\n```markdown\n# Directory Structure\n[Folder organization]\n\n# Module Architecture\n[Code partitioning]\n\n# Key Files\n[Important file responsibilities]\n```\n\n## Integration with VSCode Extension\n\nThe VSCode extension provides a user interface for managing steering documents.\n\n**Location:** `vscode-extension/src/webview/App.tsx`\n\n### Steering Tab Features\n\n```typescript\ninterface SteeringDocument {\n name: 'product' | 'tech' | 'structure';\n exists: boolean;\n lastModified?: Date;\n path: string;\n}\n```\n\n| Feature | Description |\n|---------|-------------|\n| Document List | Display all three steering documents with status |\n| Last Modified | Show when each document was last updated |\n| Open Document | Quick access to view/edit documents |\n| Copy Instructions | Copy AI assistant prompt for document creation |\n\n### User Interface Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant VSCode as VSCode Extension\n participant FS as File System\n \n User->>VSCode: Open Steering Tab\n VSCode->>FS: Check document existence\n FS-->>VSCode: Return file metadata\n VSCode-->>User: Display document list\n \n User->>VSCode: Copy creation instructions\n VSCode->>User: Copy prompt to clipboard\n \n User->>VSCode: Click \"Open\" on document\n VSCode->>FS: Open file in editor\n```\n\n## Implementation Log Integration\n\nSteering documents are referenced in the implementation log system.\n\n**Location:** `src/dashboard/implementation-log-manager.ts`\n\nThe implementation log can include references to steering documents as part of task completion records, linking development work back to the guiding documents.\n\n## Best Practices\n\n1. **Keep Documents Updated**: Review and update steering documents when significant changes occur\n2. **Consistent Location**: Always store in project root for easy access\n3. **Version Control**: Track changes to steering documents in version history\n4. **AI Reference**: Use documents as context for AI-assisted development\n\n## File Reference Summary\n\n| Document | Template Path | Output Location |\n|----------|---------------|-----------------|\n| product.md | src/markdown/templates/product-template.md | Project root |\n| tech.md | src/markdown/templates/tech-template.md | Project root |\n| structure.md | src/markdown/templates/structure-template.md | Project root |\n\n## Related Components\n\n- **Prompt Generator:** `src/prompts/create-steering-doc.ts` - Generates prompts for AI document creation\n- **Steering Guide:** `src/tools/steering-guide.ts` - Core tool for document management\n- **VSCode Extension:** `vscode-extension/src/webview/App.tsx` - UI for document interaction\n- **Dashboard Frontend:** `src/dashboard_frontend/src/modules/pages/SteeringPage.tsx` - Web dashboard integration\n\n---\n\n\n\n## Web Dashboard\n\n### 相关页面\n\n相关主题：[VSCode Extension](#vscode-extension), [Docker Deployment](#docker-deployment), [System Architecture](#architecture)\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/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\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/ws/WebSocketProvider.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx)\n- [src/dashboard_frontend/src/modules/mdx-editor/MDXEditorWrapper.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/mdx-editor/MDXEditorWrapper.tsx)\n- [src/dashboard_frontend/src/i18n.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/i18n.ts)\n- [containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml)\n
\n\n# Web Dashboard\n\nThe Web Dashboard is the primary user interface for the spec-workflow-mcp system. It provides a real-time, visual interface for monitoring project specifications, tracking task progress, reviewing implementation logs, and managing automated workflows across all connected projects.\n\n## Overview\n\nThe dashboard serves as a centralized monitoring and management hub that complements the MCP (Model Context Protocol) server functionality. While the MCP server handles code execution and specification enforcement, the dashboard offers:\n\n- **Real-time monitoring** of spec files and implementation progress\n- **Visual task tracking** with filtering and completion indicators\n- **Implementation log visualization** with file change statistics\n- **Automated cleanup job management** with execution history\n- **Multi-project support** via WebSocket connections\n\nThe dashboard runs as a separate service (default port 5000) and communicates with connected projects through a file-watching system and WebSocket connections 资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Browser Client] <-->|HTTP/WebSocket| B[Dashboard Server :5000]\n B <-->|File System Events| C[.spec-workflow Directory]\n B <-->|WebSocket| D[VSCode Extension Webview]\n C <-->|File Watching| E[Project Specs]\n C <-->|File Watching| F[Steering Documents]\n C <-->|File Watching| G[Implementation Logs]\n```\n\n### Frontend Architecture\n\nThe dashboard frontend is a React-based single-page application located in `src/dashboard_frontend/`. It uses a modular structure:\n\n```\nsrc/dashboard_frontend/\n├── src/\n│ ├── modules/\n│ │ ├── app/App.tsx # Main application shell\n│ │ ├── pages/ # Page components\n│ │ │ ├── SettingsPage.tsx\n│ │ │ ├── TasksPage.tsx\n│ │ │ ├── LogsPage.tsx\n│ │ │ └── JobExecutionHistory.tsx\n│ │ ├── ws/ # WebSocket integration\n│ │ │ └── WebSocketProvider.tsx\n│ │ └── mdx-editor/ # MDX editing capabilities\n│ │ └── MDXEditorWrapper.tsx\n│ └── i18n.ts # Internationalization\n```\n\nThe `WebSocketProvider` establishes and maintains a persistent connection to the dashboard server, enabling real-time updates without page refreshes 资料来源：[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\n### Backend Server\n\nThe server is implemented in `src/server.ts` and provides:\n\n- Express.js HTTP server for static file serving\n- WebSocket server for real-time client communication\n- File system watcher integration\n- REST API endpoints for project data retrieval\n\n## Pages and Features\n\n### Overview Page\n\nThe landing page displays project statistics aggregated from all connected projects:\n\n| Metric | Description |\n|--------|-------------|\n| Active Specs | Number of currently active specification files |\n| Archived Specs | Count of completed/archived specifications |\n| Total Specs | Overall count of specification documents |\n| Tasks | Completed vs total tasks with progress percentage |\n\nThe overview uses progress bars to visualize completion status and shows recent activity feed 资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx).\n\n### Tasks Page\n\nThe tasks page provides comprehensive task management capabilities:\n\n- **Filtering controls** for narrowing down task lists\n- **View mode switcher** between list and other display formats\n- **Progress visualization** with percentage indicators\n- **Task status indicators** (in-progress, blocked, completed)\n\nTasks display metadata including leverage scores and AI prompts when available, with expandable sections for detailed information 资料来源：[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### Logs Page\n\nImplementation logs are displayed with comprehensive statistics:\n\n```mermaid\ngraph LR\n A[File Change Event] --> B[Log Entry Created]\n B --> C[Statistics Calculated]\n C --> D[Markdown Rendered]\n D --> E[Client Displayed]\n```\n\nLog entries include:\n\n- **Statistics**: Lines added/removed, files changed, net change\n- **Files Modified**: List with syntax-highlighted file paths\n- **Files Created**: Newly created files in the project\n- **Artifacts**: API endpoints, components, functions, and classes documented during implementation\n\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\n### Settings Page\n\nThe settings page manages automated cleanup jobs:\n\n- Section-based layout with expandable/collapsible panels\n- Job configuration controls\n- Loading states with spinner indicators\n- Error handling with styled alert boxes\n\nThe automated cleanup section allows management of jobs that run across all connected projects 资料来源：[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### Job Execution History\n\nA dedicated panel displays execution statistics:\n\n| Metric | Description |\n|--------|-------------|\n| Total Runs | Number of job executions |\n| Success Rate | Percentage of successful runs with color coding |\n\nSuccess rates are color-coded: green for 100%, yellow for 50-99%, and red for below 50% 资料来源：[src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx).\n\n## Real-time Updates\n\n### WebSocket Communication\n\nThe dashboard uses WebSocket for bidirectional real-time communication:\n\n1. **Connection establishment**: Client connects to `/ws` endpoint\n2. **Project updates**: Server pushes spec and task changes immediately\n3. **Language preferences**: Users can change language with instant UI update\n\nThe WebSocket provider handles message routing and maintains connection state:\n\n```typescript\n// Message types supported\ntype MessageType = \n | 'specs-updated' // Spec files changed\n | 'tasks-updated' // Task status changed\n | 'language-changed' // UI language update\n```\n\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\n### File Watching\n\nThe watcher system monitors the `.spec-workflow` directory:\n\n```mermaid\nsequenceDiagram\n participant FS as File System\n participant Watcher as Watcher Service\n participant Server as Dashboard Server\n participant WS as WebSocket Clients\n \n FS->>Watcher: File change detected\n Watcher->>Server: Process change\n Server->>WS: Broadcast update\n WS->>Client: Trigger re-render\n```\n\nWhen spec files, steering documents, or implementation logs change, the watcher triggers updates to all connected clients 资料来源：[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts).\n\n## Internationalization\n\nThe dashboard supports multiple languages through `src/dashboard_frontend/src/i18n.ts`. All user-facing strings are externalized and can be translated. Language changes are propagated to all connected clients via WebSocket.\n\nSupported translations in the repository include:\n\n- English (default)\n- Korean (README.ko.md)\n- French (README.fr.md)\n- German\n- Portuguese\n- Russian\n- Italian\n- Arabic\n\n## MDX Editor Integration\n\nThe `MDXEditorWrapper` component provides in-browser editing capabilities for specification documents. This allows users to:\n\n- Edit spec files directly in the browser\n- Preview rendered markdown\n- Auto-save changes to the file system\n\n## Deployment Options\n\n### Standalone Server\n\nStart the dashboard with the `--dashboard` flag:\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\nThe server binds to `127.0.0.1:5000` by default, preventing network exposure 资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n### Docker Deployment\n\nDocker deployment provides isolated execution:\n\n```yaml\n# containers/docker-compose.yml\nservices:\n dashboard:\n build: \n context: .\n dockerfile: containers/Dockerfile\n ports:\n - \"5000:5000\"\n volumes:\n - ./workspace/.spec-workflow:/workspace/.spec-workflow:rw\n```\n\n资料来源：[containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml).\n\n## Security Features\n\nThe dashboard implements enterprise-grade security:\n\n| Feature | Implementation |\n|---------|----------------|\n| Localhost Binding | Binds to `127.0.0.1` by default |\n| Rate Limiting | 120 requests/minute per client |\n| Security Headers | X-Content-Type-Options, X-Frame-Options, CSP |\n| CORS Protection | Restricted cross-origin access |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n## VSCode Extension Integration\n\nThe VSCode extension embeds the dashboard as a webview, providing:\n\n- In-editor dashboard access\n- Seamless integration with the development environment\n- Real-time updates within VSCode\n\nThe webview uses the same React components as the standalone dashboard but is packaged for VSCode's webview API 资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx).\n\n## Configuration\n\nThe dashboard behavior is configured through the project's `.spec-workflow/config.toml`:\n\n```toml\n[dashboard]\nport = 5000\nhost = \"127.0.0.1\"\n```\n\nMultiple projects can connect to a single dashboard instance, allowing centralized monitoring across a development environment.\n\n---\n\n\n\n## VSCode Extension\n\n### 相关页面\n\n相关主题：[Web Dashboard](#web-dashboard), [Approval Workflow System](#approval-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n- [vscode-extension/src/extension.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension.ts)\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/ApprovalCommandService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalCommandService.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/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n
\n\n# VSCode Extension\n\n## Overview\n\nThe spec-workflow-mcp VSCode Extension provides an integrated development experience for managing specification-based workflows directly within Visual Studio Code. It serves as the recommended interface option for VSCode users, offering a native sidebar panel, approval management tools, and real-time project monitoring capabilities.\n\n资料来源：[vscode-extension/README.md]()\n\n### Purpose and Scope\n\nThe extension complements the CLI-based web dashboard by providing:\n\n- **Inline project management** - View and manage specs without leaving the editor\n- **Approval workflow integration** - Review, approve, or reject specification changes\n- **Task tracking** - Monitor implementation progress across specs and tasks\n- **Implementation logging** - Track code artifacts generated during development\n- **Multi-project support** - Connect to multiple specification projects simultaneously\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n## Architecture\n\n### Component Overview\n\nThe extension follows a modular architecture with clear separation between VSCode integration layers and UI components.\n\n```mermaid\ngraph TD\n subgraph \"VSCode Host Layer\"\n EXT[extension.ts]\n SIDEBAR[SidebarProvider]\n CMDS[ApprovalCommandService]\n EDITOR[ApprovalEditorService]\n end\n \n subgraph \"Webview Layer\"\n APP[App.tsx]\n LOGS[LogsPage]\n TASKS[TasksPage]\n CARDS[LogEntryCard]\n MODAL[comment-modal]\n end\n \n subgraph \"Communication\"\n MSG[vscode.postMessage]\n EVENTS[Event System]\n end\n \n EXT --> SIDEBAR\n SIDEBAR --> MSG\n MSG --> APP\n APP --> LOGS\n APP --> TASKS\n APP --> CARDS\n LOGS --> MODAL\n CARDS --> MODAL\n \n CMDS --> EVENTS\n EDITOR --> EVENTS\n EVENTS --> MSG\n```\n\n### Directory Structure\n\n```\nvscode-extension/\n├── package.json # Extension manifest and configuration\n├── src/\n│ ├── extension.ts # Entry point, registers commands and providers\n│ ├── extension/\n│ │ ├── providers/\n│ │ │ └── SidebarProvider.ts # Sidebar webview container management\n│ │ └── services/\n│ │ ├── ApprovalCommandService.ts # Command execution logic\n│ │ └── ApprovalEditorService.ts # Editor-related operations\n│ └── webview/\n│ ├── App.tsx # Main webview application\n│ ├── components/\n│ │ └── LogEntryCard.tsx # Implementation log entry display\n│ ├── pages/\n│ │ ├── LogsPage.tsx # Implementation logs view\n│ │ └── TasksPage.tsx # Task management view\n│ ├── comment-modal.tsx # Comment input modal\n│ ├── comment-modal.html # Modal HTML template\n│ └── globals.css # Global styles\n└── webview-dist/ # Compiled webview assets\n ├── comment-modal.js\n ├── i18n.js\n └── globals.css\n```\n\n资料来源：[vscode-extension/package.json]()\n\n## Core Components\n\n### Extension Entry Point\n\nThe `extension.ts` file serves as the main entry point for the VSCode extension. It performs the following initialization tasks:\n\n1. **Command Registration** - Registers VSCode commands for approval actions\n2. **Sidebar Provider Registration** - Establishes the sidebar webview container\n3. **Event Listeners** - Sets up communication between VSCode and webviews\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n### SidebarProvider\n\nThe `SidebarProvider` class manages the lifecycle of the sidebar webview panel.\n\n| Method | Purpose |\n|--------|---------|\n| `resolveWebviewView()` | Initializes and configures the webview |\n| `dispose()` | Cleans up resources when sidebar closes |\n| `postMessage()` | Sends messages to the webview |\n| `handleMessage()` | Processes messages from webview |\n\nThe provider implements the `WebviewViewProvider` interface and creates a webview with:\n\n- **Local resource roots** - Access to extension's local file resources\n- **Scripts enabled** - JavaScript execution for interactivity\n- **State persistence** - Maintains view state across sessions\n\n资料来源：[vscode-extension/src/extension/providers/SidebarProvider.ts]()\n\n### ApprovalCommandService\n\nThis service handles command execution related to the approval workflow system.\n\n| Method | Description |\n|--------|-------------|\n| `executeCommand()` | Executes registered VSCode commands |\n| `getApprovalList()` | Retrieves pending approvals |\n| `submitApproval()` | Submits approval decision |\n| `submitRejection()` | Submits rejection with reason |\n| `undoDecision()` | Reverts previous approval/rejection |\n\n资料来源：[vscode-extension/src/extension/services/ApprovalCommandService.ts]()\n\n### ApprovalEditorService\n\nThe `ApprovalEditorService` manages editor-related operations for reviewing specification changes.\n\n| Method | Purpose |\n|--------|---------|\n| `openDiffViewer()` | Opens built-in diff editor for spec comparisons |\n| `getCurrentDocument()` | Retrieves active document content |\n| `highlightChanges()` | Applies decorations to changed regions |\n| `createSnapshot()` | Creates versioned snapshots of spec state |\n\n资料来源：[vscode-extension/src/extension/services/ApprovalEditorService.ts]()\n\n## Webview UI\n\n### App Component\n\nThe `App.tsx` serves as the main container for the sidebar webview, organizing content into logical sections.\n\n```typescript\ninterface ProjectStats {\n activeSpecs: number; // Total specs in active development\n completedSpecs: number; // Fully approved specs\n archivedSpecs: number; // Archived specifications\n totalSpecs: number; // Combined total\n totalTasks: number; // All tasks across specs\n completedTasks: number; // Completed implementation tasks\n}\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n### Project Overview Card\n\nDisplays aggregate statistics about the connected project:\n\n- **Active Specs** - Shows `completedSpecs / activeSpecs` ratio\n- **Archived Specs** - Count of archived specifications\n- **Total Specs** - Combined specification count\n- **Tasks** - Shows `completedTasks / totalTasks` progress\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n### TasksPage\n\nThe tasks view renders individual specification tasks with the following metadata:\n\n| Field | Description | UI Indicator |\n|-------|-------------|--------------|\n| `purposes` | List of task objectives | Bullet list |\n| `requirements` | Technical requirements | Orange label |\n| `leverage` | Code patterns to reuse | Cyan badge |\n| `prompt` | AI instruction text | Collapsible section |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx]()\n\n### LogEntryCard\n\nDisplays implementation log entries with artifact tracking:\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n message: 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资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx]()\n\n### Artifact Sections\n\nEach artifact type has a dedicated display section:\n\n| Artifact Type | Icon | Color | Properties Displayed |\n|--------------|------|-------|----------------------|\n| API Endpoints | GlobeAltIcon | Blue | Method, Path, Purpose, Location, Formats |\n| Components | CubeIcon | Purple | Name, Type, Purpose, Props, Exports |\n| Functions | CodeBracketSquareIcon | Green | Name, Purpose, Location, Signature, Exported |\n| Classes | CircleStackIcon | Orange | Name, Purpose, Location, Methods, Exported |\n| Integrations | LinkIcon | - | Description, Frontend, Backend, Data Flow |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/LogsPage.tsx]()\n\n### Comment Modal\n\nThe comment modal provides a dialog for adding notes to approvals:\n\n**HTML Template Structure:**\n```html\n\n\n\n \n \n Add Comment\n\n\n
\n \n\n\n```\n\n**Compiled Version:**\n```html\n\n\n\n```\n\n资料来源：[vscode-extension/src/webview/comment-modal.html]()\n资料来源：[vscode-extension/webview-dist/comment-modal.html]()\n\n## Communication Protocol\n\n### Message Flow\n\nThe extension uses VSCode's `postMessage` API for bidirectional communication between the host and webview.\n\n```mermaid\nsequenceDiagram\n participant User\n participant Webview\n participant VSCode\n participant Backend\n \n User->>Webview: Click action\n Webview->>VSCode: postMessage({ type, payload })\n VSCode->>Backend: HTTP API call\n Backend-->>VSCode: JSON response\n VSCode-->>Webview: WebviewPanel.webview.postMessage()\n Webview-->>User: Updated UI\n```\n\n### Message Types\n\n| Direction | Message Type | Purpose |\n|-----------|--------------|---------|\n| Webview → VSCode | `OPEN_APPROVAL` | Open approval detail view |\n| Webview → VSCode | `SUBMIT_DECISION` | Submit approval/rejection |\n| Webview → VSCode | `ADD_COMMENT` | Add comment to approval |\n| VSCode → Webview | `UPDATE_STATS` | Refresh project statistics |\n| VSCode → Webview | `APPROVAL_UPDATED` | Approval state change notification |\n\n## Configuration\n\n### Extension Settings\n\nThe extension supports project-specific configuration through TOML files:\n\n```toml\n# .spec-workflow/config.example.toml\n[project]\nname = \"my-project\"\ndashboard_url = \"http://localhost:5000\"\nauto_refresh = true\nrefresh_interval = 30\n```\n\n### VSCode Configuration\n\n```json\n{\n \"spec-workflow.projectPath\": \"/path/to/project\",\n \"spec-workflow.dashboardUrl\": \"http://localhost:5000\",\n \"spec-workflow.autoRefresh\": true\n}\n```\n\n## Integration with Dashboard\n\nThe VSCode extension operates independently from the web dashboard while sharing the same backend API:\n\n```mermaid\ngraph LR\n subgraph \"Development Environment\"\n VSCODE[VSCode Extension]\n WEBVIEW[Sidebar Webview]\n end\n \n subgraph \"Backend Services\"\n API[REST API]\n FILES[File System]\n end\n \n VSCODE --> API\n WEBVIEW --> API\n API --> FILES\n \n subgraph \"Optional Services\"\n DASHBOARD[Web Dashboard]\n end\n \n API <--> DASHBOARD\n```\n\n**Key Points:**\n- Only one dashboard instance is needed per machine\n- All projects connect to the same dashboard\n- VSCode extension can work standalone with direct file access\n- Approval actions sync across both interfaces\n\n资料来源：[vscode-extension/README.md]()\n\n## Installation\n\n### From VSCode Marketplace\n\n1. Open VSCode\n2. Navigate to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)\n3. Search for \"spec-workflow\"\n4. Click Install\n\n### From Command Line\n\n```bash\ncode --install-extension pimzino.spec-workflow\n```\n\n### Configuration Required\n\nAfter installation, configure the project path in VSCode settings:\n\n```json\n{\n \"spec-workflow.projectPath\": \"/absolute/path/to/your/project\"\n}\n```\n\n资料来源：[vscode-extension/README.md]()\n\n## Feature Comparison\n\n| Feature | Web Dashboard | VSCode Extension |\n|---------|--------------|------------------|\n| Interface | Browser-based | Native sidebar |\n| Launch command | `npx @pimzino/spec-workflow-mcp@latest --dashboard` | VSCode Extension button |\n| Approval management | Full support | Full support |\n| Task viewing | Yes | Yes |\n| Implementation logs | Yes | Yes |\n| Inline editing | Limited | Yes |\n| Editor integration | No | Yes (diff viewer) |\n| Project switching | URL-based | Dropdown menu |\n\n## Extension Commands\n\nThe extension registers the following VSCode commands:\n\n| Command ID | Description | Shortcut |\n|------------|-------------|----------|\n| `spec-workflow.refresh` | Refresh project data | `Ctrl+Shift+R` |\n| `spec-workflow.openDashboard` | Open web dashboard | `Ctrl+Shift+D` |\n| `spec-workflow.approveAll` | Approve all pending specs | - |\n| `spec-workflow.showApproval` | Show approval detail | - |\n| `spec-workflow.addComment` | Add comment to selection | - |\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n## Dependencies\n\nThe extension depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@vscode/webview-ui-toolkit` | ^1.2.0 | Webview UI components |\n| `@spec-workflow/core` | workspace:* | Core shared logic |\n| `react` | ^18.2.0 | UI framework |\n| `tailwindcss` | ^3.4.0 | Styling |\n\n资料来源：[vscode-extension/package.json]()\n\n## Troubleshooting\n\n### Sidebar Not Loading\n\n1. Verify project path is correctly configured\n2. Check that `.spec-workflow/` directory exists in project root\n3. Run \"Developer: Reload Window\" command\n\n### API Connection Errors\n\n1. Ensure web dashboard is running (if using shared backend)\n2. Check `spec-workflow.dashboardUrl` setting\n3. Verify network connectivity\n\n### Webview Scripts Blocked\n\nThe webview requires script execution. If scripts are blocked:\n\n1. Check `webview.csp` setting in VSCode\n2. Ensure no security policies are preventing execution\n\n资料来源：[vscode-extension/README.md]()\n\n\n---\n\n\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[Web Dashboard](#web-dashboard)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this documentation page:\n\n- [containers/Dockerfile](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/Dockerfile)\n- [containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n- [containers/DOCKER_USAGE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/DOCKER_USAGE.md)\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n
\n\n# Docker Deployment\n\n## Overview\n\nThe spec-workflow-mcp project provides a containerized dashboard deployment option for isolated and secure execution in Docker environments. This deployment method is designed for users who prefer not to install Node.js locally or require a self-contained, portable solution for running the specification workflow management system.\n\nThe Docker deployment bundles the Node.js runtime (version 24-alpine), the dashboard application, and all required dependencies into a single image that can be run consistently across different host systems.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User Host Machine] -->|HTTP Requests| B[Docker Container]\n B -->|Port Mapping| C[Dashboard Application]\n C -->|Volume Mount| D[.spec-workflow Directory]\n \n E[Docker Networking] -->|Security Control| F[127.0.0.1:5000:5000]\n E -->|Optional External| G[0.0.0.0:5000:5000]\n \n style C fill:#f9f,stroke:#333,stroke-width:2px\n style D fill:#ff9,stroke:#333,stroke-width:2px\n```\n\n### Container Components\n\n| Component | Description |\n|-----------|-------------|\n| **Base Image** | `node:24-alpine` - Minimal Node.js runtime |\n| **Application User** | `node` (UID 1000) - Non-root execution |\n| **Dashboard Port** | 5000 (default) - Internal container port |\n| **State Directory** | `/workspace/.spec-workflow` - Project state location |\n| **Audit Log** | `/.spec-workflow/audit.log` - JSON logging |\n\n## Quick Start\n\n### Building the Image\n\n```bash\n# Build using Docker CLI\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\n\n# Verify the image was created\ndocker images spec-workflow-mcp\n```\n\n### Running the Container\n\n```bash\n# Basic run with default settings\ndocker run -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\nThe dashboard becomes accessible at: `http://localhost:5000` 资料来源：[README.md:1-10]()\n\n## Docker Compose Deployment\n\nDocker Compose is the recommended deployment method as it provides additional security hardening and simplified management.\n\n### Default Configuration\n\nCreate a `.env` file for environment configuration:\n\n```bash\n# .env file\nDASHBOARD_PORT=5000\nSPEC_WORKFLOW_PATH=./workspace\n```\n\nStart the dashboard:\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n### Management Commands\n\n```bash\n# Start in detached mode\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop the dashboard\ndocker-compose down\n\n# Rebuild and restart\ndocker-compose up --build\n```\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Default (Docker) | Description |\n|----------|------------------|-------------|\n| `DASHBOARD_PORT` | `5000` | Port on which the dashboard runs |\n| `DASHBOARD_HOST` | `127.0.0.1` | Host IP for port binding |\n| `SPEC_WORKFLOW_PATH` | `/workspace` | Path to project directory (inside container) |\n| `SPEC_WORKFLOW_BIND_ADDRESS` | `0.0.0.0` | IP address to bind inside container |\n| `SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS` | `true` | External access control |\n| `SPEC_WORKFLOW_RATE_LIMIT_ENABLED` | `true` | Enable/disable rate limiting |\n| `SPEC_WORKFLOW_CORS_ENABLED` | `true` | Enable/disable CORS |\n| `SPEC_WORKFLOW_HOME` | - | Global state directory for sandboxed environments |\n\n资料来源：[containers/README.md:80-100]()\n\n### Custom Port Configuration\n\n```bash\n# Using Docker CLI\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### Volume Mounts\n\nThe dashboard requires read-write access to the `.spec-workflow` directory:\n\n```bash\n-v \"/path/to/project/.spec-workflow:/workspace/.spec-workflow:rw\"\n```\n\n**Important Notes:**\n- The volume mount must be read-write (`:rw`) for the dashboard to function properly\n- Only the `.spec-workflow` directory needs to be mounted\n- The directory will be created automatically if it doesn't exist 资料来源：[containers/README.md:60-70]()\n\n## Security Features\n\n### Implemented Security Controls\n\nThe Docker image includes enterprise-grade security features suitable for corporate environments:\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| **Non-root User** | ✅ Enabled | Runs as `node` user (UID 1000) |\n| **Rate Limiting** | ✅ Enabled | 120 requests/minute per client |\n| **Audit Logging** | ✅ Enabled | JSON logs with 30-day retention |\n| **Security Headers** | ✅ Enabled | XSS, clickjacking, MIME sniffing protection |\n| **CORS Protection** | ✅ Enabled | Localhost origins only by default |\n| **Localhost Binding** | ✅ Default | `127.0.0.1:5000:5000` in docker-compose |\n| **Read-only Filesystem** | ✅ Available | `read_only: true` in compose |\n| **Capability Dropping** | ✅ Enabled | All Linux capabilities dropped |\n\n### Network Security Models\n\n```mermaid\ngraph LR\n A[Localhost Only] -->|127.0.0.1:5000:5000| B[Recommended - Secure]\n C[Network Access] -->|0.0.0.0:5000:5000| D[Available - Requires Firewall]\n```\n\n**Option 1: Localhost Only (Secure Default)**\n\nThe default `docker-compose.yml` uses localhost-only port mapping:\n\n```yaml\nports:\n - \"127.0.0.1:5000:5000\" # Only accessible from host machine\n```\n\nOr with Docker CLI:\n\n```bash\ndocker run -p 127.0.0.1:5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n**Option 2: Network Access (Exposes to Network)**\n\n```bash\ndocker run -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n⚠️ **Security Warning:** This configuration exposes the dashboard to your network. The application displays a security warning in the logs. Only use when necessary and ensure proper network security measures (firewall, VPN) are in place. 资料来源：[containers/README.md:110-140]()\n\n### Docker Compose Security Hardening\n\nThe provided `docker-compose.yml` includes additional security settings:\n\n```yaml\n# Read-only root filesystem\nread_only: true\n\n# Drop all Linux capabilities\ncap_drop:\n - ALL\n\n# Prevent privilege escalation\nsecurity_opt:\n - no-new-privileges:true\n\n# Resource limits (prevent DoS)\ndeploy:\n resources:\n limits:\n cpus: '1.0'\n memory: 512M\n```\n\n### Best Practices\n\n1. **Use localhost port mapping** when possible (`127.0.0.1:5000:5000`)\n2. **Never expose to public internet** without proper authentication/firewall\n3. **Keep rate limiting enabled** in production\n4. **Use the provided docker-compose.yml** for security hardening\n5. **Run as non-root user** (default in the image)\n6. **Mount volumes read-write only when necessary** 资料来源：[containers/README.md:150-165]()\n\n## Audit Logging\n\nAll API requests are logged to a structured JSON audit log for compliance and debugging.\n\n### Log Location\n\n```\n/.spec-workflow/audit.log\n```\n\n### Log Format\n\n```json\n{\n \"timestamp\": \"2025-12-06T10:30:45.123Z\",\n \"actor\": \"127.0.0.1\",\n \"action\": \"GET /api/projects/list\",\n \"resource\": \"/api/projects/list\",\n \"result\": \"success\",\n \"details\": {\n \"statusCode\": 200,\n \"duration\": 45,\n \"userAgent\": \"Mozilla/5.0...\"\n }\n}\n```\n\n### Viewing Logs\n\n```bash\n# View recent logs\ntail -f .spec-workflow/audit.log\n\n# Parse as JSON (requires jq)\ncat .spec-workflow/audit.log | jq '.'\n\n# Filter by result\ncat .spec-workflow/audit.log | jq 'select(.result == \"denied\")'\n```\n\n## Advanced Configuration\n\n### Auto-Restart on Failure\n\n```bash\ndocker run -d \\\n --name spec-workflow-dashboard \\\n --restart unless-stopped \\\n -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n### Health Checks\n\nThe dashboard does not currently include built-in health checks. You can verify connectivity manually:\n\n```bash\ncurl http://localhost:5000\n```\n\n### Testing the Docker Image\n\nA comprehensive test script validates Docker image configurations:\n\n```bash\n# From the containers directory\n./test-docker.sh\n```\n\n| Test | Description |\n|------|-------------|\n| **Image Build** | Verifies the Docker image builds successfully |\n| **Docker Default Config** | Tests app binding to 0.0.0.0, Docker exposing to localhost |\n| **Security Check** | Verifies app-level security block |\n| **Network Exposure** | Tests full network port mapping |\n| **Rate Limiting** | Verifies rate limiting configuration |\n| **Non-Root User** | Confirms container runs as non-privileged user |\n| **Custom Port** | Tests custom port configuration |\n\n资料来源：[README.md:50-75]()\n\n## Troubleshooting\n\n### Container Does Not Start\n\n**Error:** Container exits immediately after starting\n\n**Solutions:**\n- Check logs: `docker logs `\n- Verify volume mount path exists and is correct\n- Ensure port 5000 (or your configured port) is not already in use\n\n### Cannot Connect to Dashboard\n\n**Error:** Unable to access `http://localhost:5000`\n\n**Solutions:**\n- Verify container is running: `docker ps`\n- Check port is properly mapped: `docker port `\n- Ensure firewall allows connections on the port\n\n### Build Fails\n\n**Error:** Build fails with COPY or dependency errors\n\n**Solutions:**\n- Build from repository root: `docker build -f containers/Dockerfile -t spec-workflow-mcp .`\n- Verify all source files are present\n- Confirm `package.json` and `package-lock.json` exist 资料来源：[containers/README.md:40-60]()\n\n### Inspecting the Container\n\n```bash\n# View container details\ndocker inspect \n\n# Access container shell\ndocker exec -it /bin/sh\n```\n\n## External Access with Authentication\n\nThe dashboard does not include built-in authentication. For external access scenarios, use a reverse proxy:\n\n### nginx with Basic Auth\n\n```nginx\nserver {\n listen 443 ssl;\n server_name dashboard.example.com;\n \n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n \n auth_basic \"Dashboard Access\";\n auth_basic_user_file /etc/nginx/.htpasswd;\n \n location / {\n proxy_pass http://127.0.0.1:5000;\n }\n}\n```\n\n## Sandbox Environments\n\nFor sandboxed environments (e.g., Codex CLI with `sandbox_mode=workspace-write`) where `$HOME` is read-only, use the `SPEC_WORKFLOW_HOME` environment variable to redirect global state files to a writable location:\n\n```bash\nSPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace\n```\n\nThis approach works similarly in Docker:\n\n```bash\ndocker run -p 5000:5000 \\\n -e SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp \\\n -v \"/path/to/project:/workspace\" \\\n spec-workflow-mcp\n```\n\n资料来源：[README.md:100-110]()\n\n## Security Comparison Table\n\n| Security Feature | Docker CLI Default | Docker Compose | Notes |\n|-----------------|-------------------|----------------|-------|\n| Port Binding | `5000:5000` (exposed) | `127.0.0.1:5000:5000` (localhost) | Compose is more secure |\n| Root Filesystem | Read-write | Read-only (`read_only: true`) | Prevents container escape |\n| Capabilities | Default | Dropped (`cap_drop: ALL`) | Reduces attack surface |\n| Privilege Escalation | Allowed | Blocked (`no-new-privileges`) | Hardens against exploits |\n| Resource Limits | None | CPU/Memory limits | Prevents DoS |\n\n## See Also\n\n- [Configuration Guide](../docs/CONFIGURATION.md) - Additional configuration options\n- [Interfaces Guide](../docs/INTERFACES.md) - Dashboard and VSCode extension details\n- [Development Guide](../docs/DEVELOPMENT.md) - Local development setup\n- [Troubleshooting](../docs/TROUBLESHOOTING.md) - Common issues and solutions\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 项目说明书", "目录", "Getting Started", "Overview", "Prerequisites", "Installation Methods", "Using Docker Compose (recommended)", "Or using Docker CLI", "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- **Getting Started**：importance `high`\n - source_paths: README.md, src/index.ts, package.json\n- **Project Structure**：importance `high`\n - source_paths: src/index.ts, src/tools/index.ts, src/prompts/index.ts, vscode-extension/package.json, containers/docker-compose.yml\n- **System Architecture**：importance `high`\n - source_paths: src/server.ts, src/core/project-registry.ts, src/dashboard/multi-server.ts, src/dashboard/project-manager.ts, src/core/global-dir.ts\n- **MCP Server Implementation**：importance `high`\n - source_paths: src/index.ts, src/tools/approvals.ts, src/tools/spec-status.ts, src/tools/log-implementation.ts, src/tools/steering-guide.ts\n- **Spec Management**：importance `high`\n - source_paths: src/prompts/create-spec.ts, src/core/parser.ts, src/core/task-parser.ts, src/core/task-validator.ts, src/markdown/templates/requirements-template.md\n- **Approval Workflow System**：importance `high`\n - source_paths: src/tools/approvals.ts, src/dashboard/approval-storage.ts, src/dashboard/watcher.ts, src/tools/steering-guide.ts\n- **Steering Documents**：importance `medium`\n - source_paths: src/prompts/create-steering-doc.ts, src/tools/steering-guide.ts, src/markdown/templates/product-template.md, src/markdown/templates/tech-template.md, src/markdown/templates/structure-template.md\n- **Web Dashboard**：importance `high`\n - source_paths: src/server.ts, src/dashboard/watcher.ts, src/dashboard_frontend/src/modules/app/App.tsx, src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx, src/dashboard_frontend/src/modules/mdx-editor/MDXEditorWrapper.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-16 13:11:01 UTC\n\n## 目录\n\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [System Architecture](#architecture)\n- [MCP Server Implementation](#mcp-server)\n- [Spec Management](#spec-management)\n- [Approval Workflow System](#approval-workflow)\n- [Steering Documents](#steering-documents)\n- [Web Dashboard](#web-dashboard)\n- [VSCode Extension](#vscode-extension)\n- [Docker Deployment](#docker-deployment)\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [src/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/index.ts)\n- [package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/package.json)\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
\n\n# Getting Started\n\nA comprehensive guide to setting up and running the Spec-Workflow MCP server for AI-assisted specification-based development workflows.\n\n## Overview\n\nSpec-Workflow MCP is a Model Context Protocol (MCP) server that enables AI coding assistants to work with structured specifications. It provides a systematic approach to development by maintaining specs, tracking tasks, managing approvals, and logging implementation details.\n\n**Key Capabilities:**\n- Specification management with version control and approval workflows\n- Task tracking and progress monitoring\n- Implementation logging for code artifacts\n- Integration with multiple AI coding tools (Claude Desktop, Cursor, VSCode, etc.)\n- Web dashboard and VSCode extension for visualization\n\n## Prerequisites\n\nBefore installation, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Node.js | ≥ 18.0.0 | Required for npm execution |\n| npm | ≥ 9.0.0 | For package management |\n| Git | Any recent version | For version control integration |\n| Docker | ≥ 20.10.0 | Optional, for containerized deployment |\n| Docker Compose | ≥ 2.0.0 | Optional, for multi-container setups |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Quick Setup via npx\n\nThe simplest way to get started is using npx, which downloads and executes the package without global installation:\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project\n```\n\n**Command Arguments:**\n| Argument | Description | Required |\n|----------|-------------|----------|\n| `/path/to/your/project` | Absolute path to your project directory | Yes |\n\n资料来源：[README.md:1-20](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Method 2: Global Installation\n\nFor persistent installation across sessions:\n\n```bash\nnpm install -g @pimzino/spec-workflow-mcp\n```\n\nThen execute:\n```bash\nspec-workflow-mcp /path/to/your/project\n```\n\n### Method 3: Docker Deployment\n\nFor isolated, containerized deployment:\n\n```bash\n# Using Docker Compose (recommended)\ncd containers\ndocker-compose up --build\n\n# Or using 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\nThe dashboard becomes available at: `http://localhost:5000`\n\n资料来源：[README.md:85-95](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## MCP Server Configuration\n\nAfter installation, configure the MCP server for your preferred AI coding tool.\n\n### Claude Desktop\n\nAdd to `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> **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.\n\n资料来源：[README.md:55-70](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Claude Code CLI\n\n```bash\nclaude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project\n```\n\n**Windows Alternative:**\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:35-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n### Cursor IDE\n\nAdd to your Cursor settings (`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### VSCode (Cline/Claude Dev)\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### Continue IDE Extension\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### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_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### Codex\n\nAdd to `~/.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### OpenCode\n\nAdd to `opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"spec-workflow\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/your/project\"],\n \"enabled\": true\n }\n }\n}\n```\n\n资料来源：[README.md:100-145](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Choosing Your Interface\n\nSpec-Workflow MCP offers two interfaces for interacting with specifications. Choose based on your workflow.\n\n### Option A: Web Dashboard\n\n**Recommended for:** CLI users, team collaboration, remote access\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\nAccess the dashboard at: `http://localhost:5000`\n\n**Key Features:**\n- Real-time task progress visualization\n- Specification document management\n- Approval workflow interface\n- Implementation artifact tracking\n- Project statistics dashboard\n\n> **Note:** Only one dashboard instance is needed. All projects connect to the same dashboard.\n\n资料来源：[README.ko.md:20-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n\n### Option B: VSCode Extension\n\n**Recommended for:** VSCode users, integrated workflow, inline annotations\n\nThe VSCode extension provides:\n- Inline spec annotations in code\n- Task status indicators\n- Quick actions for spec management\n- Integrated approval interface\n\n资料来源：[README.ko.md:30-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.ko.md)\n\n## Project Structure\n\nAfter initialization, Spec-Workflow creates a `.spec-workflow` directory with the following structure:\n\n```\nyour-project/\n├── .spec-workflow/\n│ ├── approvals/ # Pending approval documents\n│ ├── archive/ # Archived specifications\n│ ├── specs/ # Active specifications\n│ ├── steering/ # Steering/prompt documents\n│ ├── templates/ # Built-in templates\n│ ├── user-templates/ # Custom user templates\n│ └── config.example.toml # Configuration template\n```\n\n| Directory | Purpose |\n|-----------|---------|\n| `approvals/` | Stores documents pending review and approval |\n| `archive/` | Contains superseded/archived specifications |\n| `specs/` | Active specification documents |\n| `steering/` | AI steering prompts and guidelines |\n| `templates/` | Reusable specification templates |\n| `user-templates/` | Custom templates created by users |\n\n资料来源：[README.md:20-35](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Development Setup\n\nFor contributing to the project or running from source:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Available npm Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compiles TypeScript to JavaScript |\n| `npm run dev` | Runs in development mode with hot reload |\n| `npm test` | Runs the test suite |\n| `npm run lint` | Lints code for style and errors |\n\n资料来源：[README.fr.md:25-40](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[AI Coding Assistant] -->|MCP Protocol| B[Spec-Workflow MCP Server]\n B --> C[.spec-workflow Directory]\n C --> D[Specs]\n C --> E[Tasks]\n C --> F[Approvals]\n C --> G[Implementation Logs]\n \n H[Web Dashboard] <-->|HTTP API| B\n I[VSCode Extension] <-->|VSCode API| B\n \n J[Project Files] -->|Read/Write| B\n \n style B fill:#e1f5fe\n style H fill:#fff3e0\n style I fill:#e8f5e9\n```\n\n## Security Features\n\nSpec-Workflow MCP includes enterprise-grade security controls:\n\n| Feature | Description |\n|---------|-------------|\n| **Localhost Binding** | Binds to `127.0.0.1` by default, preventing network exposure |\n| **Rate Limiting** | 120 requests/minute per client with automatic cleanup |\n| **Audit Logging** | Structured JSON logs with timestamp, actor, action, and result |\n| **Security Headers** | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |\n| **CORS Protection** | Configurable cross-origin request policies |\n\n资料来源：[README.md:100-115](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph LR\n A[Install MCP Server] --> B[Configure AI Tool]\n B --> C[Initialize Project]\n C --> D[Create Specification]\n D --> E[AI Generates Code]\n E --> F[Review & Approve]\n F --> G[Implementation Logged]\n \n style A fill:#ffcdd2\n style D fill:#fff9c4\n style F fill:#c8e6c9\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue: Dashboard not accessible**\n- Ensure port 5000 is available\n- Check if another instance is running\n- Verify firewall settings\n\n**Issue: MCP server connection failed**\n- Verify the project path is absolute, not relative\n- Check that Node.js version meets requirements\n- Ensure the npx cache is up to date: `npx -y`\n\n**Issue: Permissions error with .spec-workflow directory**\n- Ensure the directory has appropriate read/write permissions\n- On Linux/Mac: `chmod -R 755 .spec-workflow`\n\n资料来源：[docs/TROUBLESHOOTING.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/docs/TROUBLESHOOTING.md)\n\n## Next Steps\n\nAfter completing the getting started guide:\n\n1. **Create your first specification** using the spec template\n2. **Explore the dashboard** at `http://localhost:5000`\n3. **Review documentation:**\n - [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup\n - [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation\n - [Prompting Guide](docs/PROMPTING-GUIDE.md) - Advanced prompting examples\n - [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details\n\n## License\n\nSpec-Workflow MCP is released under the **GPL-3.0** license.\n\n资料来源：[README.md:45-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n\n---\n\n\n\n## Project Structure\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n- [src/markdown/templates/structure-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\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- [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
\n\n# Project Structure\n\n## Overview\n\nThe spec-workflow-mcp project is a Model Context Protocol (MCP) server that provides AI-powered specification-driven development workflow management. The project is organized into multiple subsystems that work together to enable seamless specification management, task tracking, and approval workflows for development projects.\n\n## High-Level Architecture\n\nThe project follows a modular architecture with three main interface options:\n\n```mermaid\ngraph TD\n A[AI Tools / LLM Clients] -->|MCP Protocol| B[MCP Server]\n B --> C[Core Engine]\n B --> D[Dashboard Backend]\n B --> E[Dashboard Frontend]\n B --> F[VSCode Extension]\n \n C -->|File System| G[.spec-workflow/]\n D --> G\n G --> H[specs/]\n G --> I[approvals/]\n G --> J[archive/]\n G --> K[steering/]\n G --> L[templates/]\n```\n\n## Directory Structure\n\nThe `.spec-workflow` directory is created within your project and contains all specification-related data:\n\n```plaintext\nyour-project/\n .spec-workflow/\n approvals/ # Pending approval items\n archive/ # Archived specifications\n specs/ # Active specification documents\n steering/ # Steering/prompting files\n templates/ # Default templates\n user-templates/ # User-defined templates\n config.example.toml # Configuration file template\n```\n\n## Core Components\n\n### MCP Server (`src/`)\n\nThe MCP server is the central component that exposes tools and resources to AI clients. It handles:\n\n- Specification document parsing and management\n- Task status tracking\n- Approval workflow execution\n- Implementation logging\n\n### Dashboard Backend\n\nThe backend provides REST API endpoints for the web dashboard:\n\n| Endpoint Pattern | Purpose |\n|------------------|---------|\n| `/api/specs/{name}` | Get spec document details |\n| `/api/specs/{name}/tasks/progress` | Get task progress for a spec |\n| `/api/specs/{name}/tasks/{taskId}/status` | Update task status |\n| `/api/approvals/{id}/{action}` | Perform approval actions |\n| `/api/approvals/batch/{action}` | Batch approval operations |\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx:1-20](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)\n\n### Dashboard Frontend\n\nThe web dashboard is a React-based interface located at `src/dashboard_frontend/`. It provides pages for:\n\n- **TasksPage** - View and manage tasks within specifications\n- **SettingsPage** - Configure automated cleanup jobs\n- **JobExecutionHistory** - View historical job executions\n\n#### Frontend API Integration\n\nThe frontend uses typed API calls to communicate with the backend:\n\n```typescript\nconst api = {\n getSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${encodeURIComponent(name)}/tasks/progress`),\n updateTaskStatus: (specName: string, taskId: string, status: 'pending' | 'in-progress' | 'completed' | 'blocked', reason?: string) =>\n putJson(`${prefix}/specs/${encodeURIComponent(specName)}/tasks/${encodeURIComponent(taskId)}/status`, { status, ...(reason && { reason }) }),\n approvalsAction: (id, action, body) => postJson(`${prefix}/approvals/${encodeURIComponent(id)}/${action}`, body),\n};\n```\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx:5-8](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/api/api.tsx)\n\n### VSCode Extension\n\nThe VSCode extension (`vscode-extension/`) provides an integrated experience within the VSCode editor. It includes:\n\n- **Webview-based UI** - React components rendered in VSCode\n- **App Component** - Main application entry point\n- **LogEntryCard Component** - Displays implementation log entries\n\n#### Webview Structure\n\n```mermaid\ngraph LR\n A[index.html] --> B[main.tsx]\n B --> C[App.tsx]\n C --> D[TasksPage]\n C --> E[SettingsPage]\n C --> F[LogEntryCard]\n```\n\nThe extension uses a webview to render the dashboard UI, with localization support through i18n modules.\n\n资料来源：[vscode-extension/src/webview/index.html:1-15](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/index.html)\n\n## Implementation Log System\n\nThe implementation log tracks code artifacts and changes made during development:\n\n```mermaid\ngraph TD\n A[Implementation Entry] --> B[Statistics]\n A --> C[Files Modified]\n A --> D[Files Created]\n A --> E[Artifacts]\n \n E --> E1[API Endpoints]\n E --> E2[Components]\n E --> E3[Functions]\n E --> E4[Classes]\n E --> E5[Integrations]\n```\n\n### Artifact Types\n\n| Type | Properties | Description |\n|------|------------|-------------|\n| apiEndpoints | method, path, purpose, location, requestFormat, responseFormat | HTTP API endpoints |\n| components | name, type, purpose, location, props, exports | UI/components |\n| functions | name, purpose, location, signature, isExported | Code functions |\n| classes | name, purpose, location, methods, isExported | Code classes |\n| integrations | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx:30-50](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/components/LogEntryCard.tsx)\n\n## Development Workflow Structure\n\n```mermaid\ngraph LR\n A[Create Spec] --> B[Generate Tasks]\n B --> C[Implement Code]\n C --> D[Log Artifacts]\n D --> E[Request Approval]\n E --> F[Approve/Request Changes]\n F -->|Approve| G[Archive Spec]\n F -->|Changes| C\n```\n\n### Template System\n\nTemplates define the structure of specification documents. The project includes:\n\n- **structure-template.md** - Defines code organization patterns\n- **user-templates/** - Custom user-defined templates\n\n#### Template Sections\n\nThe structure template includes guidelines for:\n\n1. **File Organization** - How to structure code files\n2. **Function/Method Organization** - Patterns for function design\n3. **Code Organization Principles** - Single responsibility, modularity, testability\n4. **Module Boundaries** - Defining inter-module interactions\n5. **Code Size Guidelines** - Limits for file and function sizes\n\n资料来源：[src/markdown/templates/structure-template.md:1-60](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\n\n## Configuration\n\nThe project uses TOML configuration files. The example configuration template is located at:\n\n```\n.spec-workflow/config.example.toml\n```\n\nConfiguration options include:\n- Dashboard connection settings\n- Cleanup job schedules\n- Template preferences\n- Approval workflow settings\n\n## Project Statistics Display\n\nThe dashboard displays project statistics including:\n\n| Metric | Description |\n|--------|-------------|\n| activeSpecs | Total active specification documents |\n| completedSpecs | Successfully completed specifications |\n| archivedSpecs | Archived/old specifications |\n| totalSpecs | All specifications count |\n| totalTasks | Total tasks across all specs |\n| completedTasks | Completed tasks count |\n\nThese statistics are aggregated from the `.spec-workflow` directory and displayed in both the web dashboard and VSCode extension.\n\n资料来源：[vscode-extension/src/webview/App.tsx:10-40](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx)\n\n## Summary\n\nThe spec-workflow-mcp project is organized into distinct layers:\n\n1. **Core Layer** - MCP server handles AI tool interactions\n2. **Backend Layer** - REST API for dashboard operations\n3. **Frontend Layer** - Web dashboard and VSCode extension\n4. **Data Layer** - File-based storage in `.spec-workflow/`\n\nThis separation of concerns allows the project to serve multiple interfaces while maintaining a single source of truth for specification data.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[MCP Server Implementation](#mcp-server), [Web Dashboard](#web-dashboard), [Spec Management](#spec-management)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/server.ts) - **未在当前上下文提供**\n- [src/core/project-registry.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/project-registry.ts) - **未在当前上下文提供**\n- [src/dashboard/multi-server.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/multi-server.ts) - **未在当前上下文提供**\n- [src/dashboard/project-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/project-manager.ts) - **未在当前上下文提供**\n- [src/core/global-dir.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/global-dir.ts) - **未在当前上下文提供**\n\n> ⚠️ **注意**: 指定的核心架构源文件（server.ts, project-registry.ts, multi-server.ts, project-manager.ts, global-dir.ts）在当前上下文中不可用。以下内容基于 README 文档、API 客户端代码和前端组件的有限片段综合得出。如需完整准确的架构文档，请确保提供上述源文件。\n\n
\n\n# System Architecture\n\n## Overview\n\nThe Spec-Workflow MCP (Model Context Protocol) system is designed as a bridge between AI coding assistants and structured software development workflows. It provides a specification-driven approach to managing software development tasks, approvals, and implementation tracking.\n\nThe architecture follows a multi-tier design with distinct components for MCP protocol handling, project management, dashboard services, and frontend interfaces.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n VSCode[VSCode Extension]\n CLI[Claude CLI]\n Desktop[Claude Desktop]\n end\n\n subgraph \"MCP Server Layer\"\n MCPServer[MCP Server]\n Tools[Tool Handlers]\n end\n\n subgraph \"Dashboard Layer\"\n Dashboard[Web Dashboard]\n MultiServer[Multi-Server Manager]\n ProjectManager[Project Manager]\n end\n\n subgraph \"Core Services\"\n Registry[Project Registry]\n GlobalDir[Global Directory]\n ApprovalEngine[Approval Engine]\n end\n\n subgraph \"Storage Layer\"\n SpecWorkflowDir[.spec-workflow/]\n Config[Config Files]\n Specs[Specs Data]\n Approvals[Approvals]\n end\n\n VSCode <--> MCPServer\n CLI <--> MCPServer\n Desktop <--> MCPServer\n \n MCPServer <--> Dashboard\n Dashboard <--> Registry\n Dashboard <--> ProjectManager\n ProjectManager <--> GlobalDir\n Registry <--> SpecWorkflowDir\n ApprovalEngine <--> SpecWorkflowDir\n```\n\n## Core Components\n\n### MCP Server (`src/server.ts`)\n\nThe MCP server acts as the central protocol handler that bridges AI tools with the spec workflow system.\n\n| Component | Purpose |\n|-----------|---------|\n| Protocol Handler | Processes MCP requests and responses |\n| Tool Registry | Manages available MCP tools |\n| Request Router | Routes requests to appropriate handlers |\n| Response Formatter | Formats tool outputs for AI consumption |\n\n资料来源：[README.md]() (MCP configuration documentation)\n\n### Project Registry (`src/core/project-registry.ts`)\n\nThe project registry maintains a centralized record of all projects connected to the spec workflow system.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| projectId | string | Unique project identifier |\n| path | string | Absolute path to project root |\n| config | Config | Project-specific configuration |\n| lastAccess | timestamp | Last activity timestamp |\n\n资料来源：[README.md]() (project structure documentation)\n\n### Dashboard Multi-Server Manager (`src/dashboard/multi-server.ts`)\n\nManages multiple MCP server instances and provides centralized coordination.\n\n```mermaid\ngraph LR\n A[Dashboard UI] --> B[Multi-Server Manager]\n B --> C[Server 1]\n B --> D[Server 2]\n B --> N[Server N]\n \n C --> E[Project 1]\n D --> F[Project 2]\n N --> G[Project N]\n```\n\n### Project Manager (`src/dashboard/project-manager.ts`)\n\nHandles project lifecycle operations including initialization, status tracking, and data synchronization.\n\n| Method | Description |\n|--------|-------------|\n| initializeProject() | Sets up .spec-workflow directory |\n| getProjectStats() | Retrieves project metrics |\n| syncProject() | Synchronizes project state |\n| archiveProject() | Archives completed projects |\n\n### Global Directory (`src/core/global-dir.ts`)\n\nProvides cross-project data management and shared resources.\n\nThe global directory stores shared configuration and data at:\n```\n~/.spec-workflow/\n```\n\n资料来源：[README.md]() (project structure documentation)\n\n## Directory Structure\n\nEach project managed by spec-workflow follows a standardized directory layout:\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # Approval requests and responses\n archive/ # Archived specifications\n specs/ # Active specifications\n steering/ # Steering configurations\n templates/ # Specification templates\n user-templates/ # Custom user templates\n config.example.toml # Example configuration\n```\n\n资料来源：[README.md]() (project structure documentation)\n\n## Dashboard Architecture\n\nThe dashboard provides a web-based interface for managing specs and tasks across connected projects.\n\n### Frontend Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| UI Framework | React | Component rendering |\n| API Client | TypeScript | Backend communication |\n| Styling | Tailwind CSS | Responsive design |\n| Internationalization | i18n | Multi-language support |\n\n资料来源：[vscode-extension/src/webview/App.tsx](), [src/dashboard_frontend/src/modules/api/api.tsx]()\n\n### Backend Services\n\n| Service | Port | Description |\n|---------|------|-------------|\n| Dashboard Server | 5000 | Main dashboard web server |\n| API Endpoints | /api/* | REST API for spec management |\n\nThe dashboard binds to `127.0.0.1` by default to prevent network exposure.\n\n资料来源：[README.md]() (security documentation)\n\n## API Architecture\n\n```mermaid\ngraph TD\n subgraph \"API Client (Frontend)\"\n TasksPage[TasksPage]\n SettingsPage[SettingsPage]\n end\n\n subgraph \"API Endpoints\"\n GET_SPECS[GET /specs/:name/all]\n UPDATE_TASK[PUT /specs/:name/tasks/:id/status]\n APPROVALS[POST /approvals/:id/:action]\n end\n\n TasksPage --> GET_SPECS\n SettingsPage --> UPDATE_TASK\n TasksPage --> APPROVALS\n```\n\n### Key API Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/specs/:name/all` | GET | Fetch all spec documents |\n| `/specs/:name/archived` | GET | Fetch archived specs |\n| `/specs/:name/tasks/progress` | GET | Get task progress statistics |\n| `/specs/:name/tasks/:id/status` | PUT | Update task status |\n| `/approvals/:id/:action` | POST | Process approval action |\n| `/approvals/batch/:action` | POST | Batch approval operations |\n\n资料来源：[src/dashboard_frontend/src/modules/api/api.tsx]()\n\n## Security Architecture\n\nThe system implements enterprise-grade security controls suitable for corporate environments.\n\n| Security Feature | Implementation | Purpose |\n|-----------------|----------------|---------|\n| Localhost Binding | `127.0.0.1` default | Prevent network exposure |\n| Rate Limiting | 120 req/min per client | Prevent abuse |\n| Audit Logging | JSON structured logs | Track all operations |\n| Security Headers | CSP, X-Frame-Options | Browser protection |\n| CORS Protection | Configurable origins | Cross-origin control |\n\n资料来源：[README.md]() (security documentation)\n\n## Deployment Options\n\n### Docker Deployment\n\n```mermaid\ngraph LR\n A[Docker Compose] --> B[Dashboard Container]\n B --> C[spec-workflow data]\n D[Projects] --> C\n```\n\n```bash\n# Using Docker Compose\ncd containers\ndocker-compose up --build\n\n# Dashboard available at http://localhost:5000\n```\n\n### MCP Client Integration\n\n| Client | Configuration Method |\n|--------|---------------------|\n| VSCode (Augment) | `settings.json` MCP servers |\n| Claude Code CLI | `claude mcp add` command |\n| Claude Desktop | `claude_desktop_config.json` |\n| Codex | `~/.codex/config.toml` |\n\n资料来源：[README.md]() (MCP integration documentation)\n\n## Implementation Log System\n\nThe implementation log tracks all changes made during development.\n\n```mermaid\ngraph TD\n A[Implementation Entry] --> B[Files Modified]\n A --> C[Files Created]\n A --> D[Artifacts]\n D --> E[API Endpoints]\n D --> F[Components]\n D --> G[Functions]\n D --> H[Classes]\n D --> I[Integrations]\n```\n\n### Log Entry Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| id | string | Unique entry identifier |\n| timestamp | Date | Entry creation time |\n| description | string | Summary of changes |\n| filesModified | string[] | List of modified files |\n| filesCreated | string[] | List of created files |\n| artifacts | Artifacts | Structured artifact data |\n\n资料来源：[src/dashboard/implementation-log-manager.ts](), [src/core/implementation-log-migrator.ts]()\n\n## Task Management Flow\n\n```mermaid\ngraph TD\n A[Create Task] --> B[pending]\n B --> C{inProgress?}\n C -->|Yes| D[in-progress]\n C -->|No| E[blocked]\n D --> F{Completed?}\n F -->|Yes| G[completed]\n F -->|No| D\n E --> H{Blocked Reason Required}\n H --> I[Save Blocked Reason]\n I --> B\n```\n\n### Task States\n\n| State | Description |\n|-------|-------------|\n| `pending` | Task created but not started |\n| `in-progress` | Task actively being worked on |\n| `completed` | Task finished successfully |\n| `blocked` | Task paused due to dependency |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx]()\n\n## Configuration Schema\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"spec-workflow\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@pimzino/spec-workflow-mcp@latest\", \"/path/to/project\"]\n }\n }\n}\n```\n\n### Project Configuration (`config.toml`)\n\n| Section | Key | Type | Description |\n|---------|-----|------|-------------|\n| general | workspace | string | Project root path |\n| general | language | string | Primary language |\n| dashboard | port | number | Dashboard server port |\n| dashboard | host | string | Bind address |\n| cleanup | enabled | boolean | Auto cleanup toggle |\n| cleanup | schedule | string | Cron schedule |\n\n## Summary\n\nThe spec-workflow-mcp architecture provides:\n\n1. **Protocol Bridge**: Seamless MCP integration with AI coding tools\n2. **Specification-Driven Workflow**: Structured approach to software development\n3. **Multi-Project Management**: Centralized dashboard for all projects\n4. **Enterprise Security**: Production-ready security controls\n5. **Flexible Deployment**: Docker and native deployment options\n\nThis architecture enables teams to maintain consistent development practices while leveraging AI assistance throughout the development lifecycle.\n\n---\n\n\n\n## MCP Server Implementation\n\n### 相关页面\n\n相关主题：[Approval Workflow System](#approval-workflow), [Spec Management](#spec-management), [Steering Documents](#steering-documents)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/index.ts)\n- [src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n- [src/tools/spec-status.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-status.ts)\n- [src/tools/log-implementation.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/log-implementation.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- [src/prompts/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/index.ts)\n
\n\n# MCP Server Implementation\n\n## Overview\n\nThe MCP Server Implementation provides a Model Context Protocol (MCP) server that integrates the spec-workflow system into AI coding assistants. It exposes structured tools that AI agents can invoke to manage specification-driven development workflows, including approvals, spec tracking, and implementation logging.\n\n**Purpose:**\n- Bridge AI coding assistants with the spec-workflow specification management system\n- Enable AI agents to create, review, and update specification documents\n- Provide human-in-the-loop approval workflows for AI-generated code\n- Track implementation progress across multiple specification phases\n\n**Scope:**\nThe server operates as a local MCP server that connects to a project directory, providing tools for steering documentation, spec creation, approval management, and implementation logging. It works alongside a dashboard server for human review and approval.\n\n## Architecture\n\n### System Components\n\nThe MCP server architecture consists of three interconnected layers:\n\n```mermaid\ngraph TD\n A[\"AI Coding Assistant
(Cline, Cursor, VS Code)\"] --> B[\"MCP Server
(spec-workflow-mcp)\"]\n B --> C[\"Dashboard Server
(Port 5000)\"]\n B --> D[\"Project Directory
(.spec-workflow)\"]\n C --> D\n \n B --> E[\"Tools\"]\n E --> E1[\"approvals\"]\n E --> E2[\"spec-status\"]\n E --> E3[\"spec-workflow-guide\"]\n E --> E4[\"steering-guide\"]\n E --> E5[\"log-implementation\"]\n E --> E6[\"prompt-generation\"]\n```\n\n### MCP Server Entry Point\n\nThe server is initialized in `src/index.ts` and configured via command-line arguments. The primary execution path:\n\n1. Parse command-line arguments for project path and mode\n2. Initialize the MCP server with stdio transport\n3. Register all available tools and resources\n4. Begin message processing loop\n\n**Configuration Example:**\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:1]()\n\n> **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.\n\n## Available Tools\n\n### Tool Overview\n\n| Tool Name | Purpose | Key Actions |\n|-----------|---------|-------------|\n| `approvals` | Manage approval workflows | request, status, delete |\n| `spec-status` | Track specification states | get, update |\n| `spec-workflow-guide` | Load spec workflow instructions | N/A (resource loader) |\n| `steering-guide` | Load steering workflow instructions | N/A (resource loader) |\n| `log-implementation` | Record implementation artifacts | create, list, update |\n| `prompt-generation` | Generate workflow prompts | N/A (resource loader) |\n\n### Approvals Tool\n\nThe approvals tool manages the human-in-the-loop approval workflow. All AI-generated specs require explicit human approval before proceeding.\n\n**Actions:**\n\n| Action | Parameters | Description |\n|--------|------------|-------------|\n| `request` | `filePath` | Request approval for a specific file |\n| `status` | `approvalId` | Check current status of an approval request |\n| `delete` | `approvalId` | Remove approval after acceptance/rejection |\n\n**Workflow Integration:**\n\n```mermaid\ngraph LR\n A[AI Creates Spec] --> B[Request Approval]\n B --> C{Human Reviews}\n C -->|Approved| D[Delete Approval]\n C -->|Needs Revision| E[AI Updates Spec]\n E --> B\n D --> F[Proceed to Implementation]\n```\n\n**Approval Status States:**\n\n| Status | Meaning |\n|--------|---------|\n| `pending` | Awaiting human review |\n| `approved` | Human accepted the specification |\n| `needs-revision` | Human requested changes |\n| `rejected` | Human rejected the specification |\n\n资料来源：[src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n\n### Spec Status Tool\n\nThe spec-status tool tracks the lifecycle state of individual specifications.\n\n**Supported States:**\n\n| State | Description |\n|-------|-------------|\n| `draft` | Initial creation phase |\n| `in-progress` | Actively being implemented |\n| `review` | Under human review |\n| `approved` | Approved and ready for next phase |\n| `completed` | Fully implemented |\n| `archived` | Moved to archive |\n\n**Operations:**\n- Query current status of any spec\n- Update status after phase transitions\n- Retrieve history of status changes\n\n资料来源：[src/tools/spec-status.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/spec-status.ts)\n\n### Spec Workflow Guide\n\nProvides structured guidance for the specification creation workflow. The guide defines a 4-phase process:\n\n```mermaid\ngraph TD\n P1[Phase 1: Design] --> P2[Phase 2: Spec]\n P2 --> P3[Phase 3: Tasks]\n P3 --> P4[Phase 4: Implementation]\n \n P1 --> P1A[product.md]\n P2 --> P2A[design.md]\n P3 --> P3A[tasks.md]\n P4 --> P4A[Code Files]\n```\n\n**Phase Details:**\n\n| Phase | Document | Template | Output Location |\n|-------|----------|----------|-----------------|\n| 1 | Product | product-template.md | .spec-workflow/steering/ |\n| 2 | Design | design-template.md | .spec-workflow/specs/{name}/ |\n| 3 | Tasks | tasks-template.md | .spec-workflow/specs/{name}/ |\n| 4 | Implementation | N/A | Project root |\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### Steering Guide\n\nDefines the steering documentation workflow for project-wide guidance:\n\n**Steering Phases:**\n\n| Phase | Purpose | Document | Template |\n|-------|---------|----------|----------|\n| 1 | Product Vision | product.md | product-template.md |\n| 2 | Technology | tech.md | tech-template.md |\n| 3 | Structure | structure.md | structure-template.md |\n\n**Template Resolution:**\n\n```mermaid\ngraph TD\n A[Need Template] --> B{user-templates exist?}\n B -->|Yes| C[Use user-templates]\n B -->|No| D[Use templates]\n C --> E[Load Template]\n D --> E\n```\n\nTemplates are resolved first from `.spec-workflow/user-templates/` directory, falling back to `.spec-workflow/templates/` if no custom templates exist.\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n### Log Implementation Tool\n\nRecords and tracks implementation artifacts generated during the coding phase. Enables the AI to maintain a structured record of what was built.\n\n**Artifact Types:**\n\n| Type | Fields | Description |\n|------|--------|-------------|\n| `apiEndpoints` | method, path, purpose, location | REST API definitions |\n| `components` | name, type, purpose, location, props | UI/functional components |\n| `functions` | name, purpose, location, signature, isExported | Code functions |\n| `classes` | name, purpose, location, methods, isExported | Class definitions |\n| `integrations` | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n**Implementation Log Entry Structure:**\n\n```typescript\ninterface ImplementationLogEntry {\n timestamp: string;\n specName: string;\n filesCreated: string[];\n filesModified: 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资料来源：[src/dashboard/implementation-log-manager.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/implementation-log-manager.ts)\n\n## Workflow Integration\n\n### Initialization Sequence\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant MCP\n participant AI\n \n User->>Dashboard: Start dashboard (port 5000)\n User->>MCP: Start MCP server with project path\n User->>AI: Configure AI client with MCP\n AI->>MCP: List available tools\n MCP-->>AI: Return tool definitions\n AI->>MCP: Call steering-guide\n MCP-->>AI: Return workflow instructions\n AI->>MCP: Create spec via prompts\n AI->>MCP: Request approval\n MCP->>Dashboard: Store approval request\n User->>Dashboard: Review and approve\n Dashboard->>MCP: Update approval status\n MCP-->>AI: Approval granted\n```\n\n### Client Configuration\n\nThe MCP server supports multiple AI coding assistant clients:\n\n| Client | Configuration Location | Notes |\n|--------|----------------------|-------|\n| Claude Desktop | claude_desktop_config.json | Run dashboard first |\n| Cline | mcp_settings.json | Direct npx execution |\n| Claude Dev | mcp_settings.json | Direct npx execution |\n| Continue | config.json | MCP server array |\n| Cursor | settings.json | User settings |\n\n资料来源：[README.md:1]()\n\n## Dashboard Server Integration\n\nThe dashboard server runs independently on port 5000 and provides:\n\n- **Approval Management UI**: Review pending approvals with file diffs\n- **Spec Overview**: View all specs and their current states\n- **Statistics Dashboard**: Track progress across specs and tasks\n- **Implementation Logs**: Browse logged implementation artifacts\n\n**Single Instance Model:**\n\n> **Note:** Only one dashboard instance is required. All projects connect to the same dashboard server.\n\n```bash\n# Start dashboard\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n\n# Dashboard accessible at http://localhost:5000\n```\n\n资料来源：[README.md:1]()\n\n## Project Directory Structure\n\nThe MCP server expects and manages the following directory structure within each project:\n\n```\nyour-project/\n .spec-workflow/\n approvals/ # Active approval requests\n archive/ # Completed/archived specs\n specs/ # Individual spec directories\n {spec-name}/\n design.md\n tasks.md\n steering/ # Project-level steering docs\n product.md\n tech.md\n structure.md\n templates/ # Default templates\n user-templates/ # Project-specific custom templates\n config.example.toml\n```\n\n## Prompt Generation\n\nThe prompt-generation resource provides AI-usable prompts for each workflow phase, enabling consistent spec creation behavior.\n\n**Prompt Categories:**\n\n| Category | Purpose |\n|----------|---------|\n| spec-creation | Guide spec document creation |\n| task-breakdown | Convert specs to implementable tasks |\n| implementation | Guide code implementation |\n| review | Facilitate human review |\n\n资料来源：[src/prompts/index.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/index.ts)\n\n## Error Handling\n\nThe MCP server implements several error handling strategies:\n\n| Scenario | Handling |\n|----------|----------|\n| Dashboard unavailable | Continue without real-time sync |\n| Approval delete fails | Stop workflow, return to polling |\n| Template not found | Fall back to default templates |\n| Invalid spec state | Return error, require correction |\n| File system errors | Return detailed error message |\n\n**Critical Workflow Constraint:**\n\nIf approval deletion fails after acceptance, the workflow **must stop** and return to polling status. The implementation cannot proceed until the approval cleanup succeeds.\n\n资料来源：[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n\n## Development\n\n### Building the Server\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n```\n\n### Source Organization\n\n| Path | Purpose |\n|------|---------|\n| src/index.ts | Main entry point, MCP server initialization |\n| src/tools/*.ts | Tool implementations |\n| src/prompts/*.ts | Prompt generation utilities |\n| src/dashboard/*.ts | Dashboard server components |\n| src/dashboard_frontend/*.tsx | Dashboard React components |\n\n## Summary\n\nThe MCP Server Implementation provides a comprehensive bridge between AI coding assistants and the spec-workflow specification management system. By exposing structured tools for approvals, spec tracking, implementation logging, and workflow guidance, it enables AI agents to participate in human-controlled development workflows while maintaining full transparency and auditability of all generated artifacts.\n\n---\n\n\n\n## Spec Management\n\n### 相关页面\n\n相关主题：[Approval Workflow System](#approval-workflow), [Steering Documents](#steering-documents), [MCP Server Implementation](#mcp-server)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n- [src/core/parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/parser.ts)\n- [src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n- [src/core/task-validator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-validator.ts)\n- [src/markdown/templates/requirements-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/requirements-template.md)\n- [src/markdown/templates/design-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/design-template.md)\n- [src/markdown/templates/tasks-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/tasks-template.md)\n- [src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n
\n\n# Spec Management\n\n## Overview\n\nSpec Management is the core system within spec-workflow-mcp that enables structured project specification, task planning, and implementation tracking. This system provides a standardized approach to converting project ideas into actionable, trackable implementation tasks through a Markdown-based specification document format.\n\nThe spec management system serves as the foundation for the entire workflow, bridging the gap between high-level project requirements and concrete implementation tasks. It ensures that every feature or change is properly documented, validated, and tracked throughout its lifecycle.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User] --> B[Spec Creation]\n B --> C[Spec Templates]\n C --> D[Requirements Template]\n C --> E[Design Template]\n C --> F[Tasks Template]\n D --> G[Core Parser]\n E --> G\n F --> H[Task Parser]\n G --> I[Spec Document]\n H --> J[Task Validation]\n J --> K[Task Status Tracking]\n I --> L[Dashboard / VSCode Extension]\n K --> L\n```\n\n## Spec Document Structure\n\n### Directory Layout\n\nSpecs are stored within each project's `.spec-workflow` directory following a standardized structure:\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.fr.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.fr.md)\n\n### Specification Components\n\nEach specification document is composed of multiple template sections that capture different aspects of the project requirements.\n\n| Component | Purpose | File Pattern |\n|-----------|---------|--------------|\n| Requirements | Define what needs to be built | `requirements-template.md` |\n| Design | Document architectural decisions | `design-template.md` |\n| Tasks | Break down implementation steps | `tasks-template.md` |\n\n## Requirements Template\n\nThe requirements template establishes the foundation of a specification by capturing the essential \"what\" of the feature or change.\n\n### Key Sections\n\nThe requirements template includes structured fields for:\n\n- **Title and Description**: Clear identification of the feature\n- **Purpose**: The motivation behind the feature\n- **Leverage**: Existing code, patterns, or systems to build upon\n- **Requirements**: Specific constraints and conditions that must be met\n- **Acceptance Criteria**: Measurable outcomes that define success\n\n资料来源：[src/markdown/templates/requirements-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/requirements-template.md)\n\n### Purpose Field\n\nThe `purposes` array captures multiple reasons for a given feature:\n\n```typescript\n// Task structure showing purposes field\ninterface Task {\n purposes: string[];\n requirements: string[];\n leverage?: string;\n prompt?: string;\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## Design Template\n\nThe design template documents the \"how\" of implementation, capturing architectural decisions and technical approach.\n\n### Structure\n\nThe design template typically includes:\n\n- **Code Organization**: Guidelines for file and module structure\n- **Module Boundaries**: Defining how different parts interact\n- **Function/Method Organization**: Patterns for organizing code logic\n- **Code Size Guidelines**: Limits on file and function complexity\n\n资料来源：[src/markdown/templates/design-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/design-template.md)\n\n### Design Principles\n\nThe template enforces several key principles:\n\n| Principle | Description |\n|-----------|-------------|\n| Single Responsibility | Each file should have one clear purpose |\n| Modularity | Code organized into reusable modules |\n| Testability | Structure code to be easily testable |\n| Consistency | Follow patterns established in the codebase |\n\n## Tasks Template\n\nThe tasks template breaks down the implementation into granular, actionable items that can be tracked and completed independently.\n\n### Task Properties\n\nEach task within the tasks template supports the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | string | Unique identifier for the task |\n| `status` | enum | Current state: `pending`, `in-progress`, `completed`, `blocked` |\n| `completed` | boolean | Whether task is finished |\n| `inProgress` | boolean | Whether task is currently being worked on |\n| `purposes` | string[] | Array of purpose descriptions |\n| `requirements` | string[] | Specific requirements for this task |\n| `leverage` | string | Existing code/patterns to leverage |\n| `prompt` | string | AI prompt associated with task |\n| `isHeader` | boolean | Whether task is a section header |\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## Spec Parsing System\n\n### Core Parser\n\nThe core parser (`src/core/parser.ts`) is responsible for reading and interpreting spec documents, extracting structured data from Markdown content.\n\n```mermaid\ngraph LR\n A[Markdown Spec File] --> B[Core Parser]\n B --> C[Extracted Metadata]\n B --> D[Tasks Array]\n B --> E[Requirements]\n B --> F[Design Decisions]\n```\n\n资料来源：[src/core/parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/parser.ts)\n\n### Task Parser\n\nThe task parser (`src/core/task-parser.ts`) specializes in extracting and organizing task information from the tasks section of spec documents.\n\n**Capabilities:**\n- Extract task ID and status\n- Parse purpose and requirements arrays\n- Handle nested task hierarchies\n- Support both ordered and unordered task formats\n\n资料来源：[src/core/task-parser.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-parser.ts)\n\n### Task Validator\n\nThe task validator (`src/core/task-validator.ts`) ensures that parsed tasks meet the required structural and content requirements.\n\n**Validation Checks:**\n- Required fields presence\n- Status value validity\n- Purpose array non-empty\n- Requirement completeness\n\n资料来源：[src/core/task-validator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/task-validator.ts)\n\n## Task Status Workflow\n\n### State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress : Start Work\n InProgress --> Completed : Finish Task\n InProgress --> Blocked : Encounter Blocker\n Blocked --> InProgress : Resolve Blocker\n Completed --> [*]\n Blocked --> [*] : Cancel Task\n```\n\n### Status Transitions API\n\n```typescript\nupdateTaskStatus: (\n specName: string, \n taskId: string, \n status: 'pending' | 'in-progress' | 'completed' | 'blocked', \n reason?: string\n) => void\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `specName` | string | Yes | Name of the specification |\n| `taskId` | string | Yes | Unique task identifier |\n| `status` | enum | Yes | New status value |\n| `reason` | string | No | Reason for status change (especially for blocked) |\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## Implementation Tracking\n\n### Implementation Log Entry Structure\n\nAs tasks are completed, the system tracks implementation artifacts through the ImplementationLogManager:\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: Date;\n filesModified: string[];\n filesCreated: string[];\n statistics: {\n linesAdded: number;\n linesRemoved: number;\n };\n artifacts?: {\n apiEndpoints?: ApiEndpoint[];\n components?: Component[];\n functions?: Function[];\n classes?: Class[];\n integrations?: Integration[];\n };\n}\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### Artifact Types\n\n| Artifact Type | Properties | Description |\n|--------------|------------|-------------|\n| `apiEndpoints` | method, path, purpose, location, requestFormat, responseFormat | REST API endpoints created |\n| `components` | name, type, purpose, location, props, exports | UI/components created |\n| `functions` | name, purpose, location, signature, isExported | Functions implemented |\n| `classes` | name, purpose, location, methods, isExported | Classes implemented |\n| `integrations` | description, frontendComponent, backendEndpoint, dataFlow | Integration points |\n\n资料来源：[src/core/implementation-log-migrator.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/core/implementation-log-migrator.ts)\n\n## Dashboard Integration\n\n### Project Statistics\n\nThe dashboard provides an overview of spec and task progress:\n\n| Metric | Description |\n|--------|-------------|\n| `activeSpecs` | Total number of active specifications |\n| `completedSpecs` | Specifications with all tasks completed |\n| `archivedSpecs` | Specifications moved to archive |\n| `totalSpecs` | Total specs (active + archived) |\n| `totalTasks` | Total tasks across all specs |\n| `completedTasks` | Tasks marked as completed |\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### Spec Operations\n\nThe dashboard supports the following operations:\n\n| Operation | Endpoint | Description |\n|-----------|----------|-------------|\n| View Spec | `/specs/{name}` | Retrieve spec document |\n| View All Documents | `/specs/{name}/all` | Get all spec-related documents |\n| Archive Spec | `/specs/{name}/archive` | Move spec to archive |\n| Unarchive Spec | `/specs/{name}/unarchive` | Restore from archive |\n| Get Tasks Progress | `/specs/{name}/tasks/progress` | Calculate task completion percentage |\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### Task Progress Calculation\n\n```typescript\nconst progress = spec.taskProgress?.total\n ? Math.round((spec.taskProgress.completed / spec.taskProgress.total) * 100)\n : 0;\n```\n\n资料来源：[src/dashboard_frontend/src/modules/pages/SpecsPage.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/SpecsPage.tsx)\n\n## Steering Documents\n\nSteering documents provide project-level guidance and are managed separately from individual specs:\n\n| Document Type | Purpose |\n|--------------|---------|\n| Steering Docs | Project-level architectural decisions and direction |\n| User Templates | Customizable templates for organization-specific needs |\n| Standard Templates | Built-in templates for common spec patterns |\n\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## AI Integration\n\n### Spec Creation Prompts\n\nThe system uses structured prompts for AI-assisted spec creation:\n\n```typescript\ninterface CreateSpecInput {\n featureName: string;\n description: string;\n leverage?: string;\n requirements?: string[];\n}\n```\n\n资料来源：[src/prompts/create-spec.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-spec.ts)\n\n### Task Implementation Prompts\n\nWhen implementing tasks, the AI receives contextual information including:\n\n- Task purposes and requirements\n- Leverage information (existing code to build upon)\n- Design guidelines from the spec\n- Implementation log context\n\n```typescript\ninterface ImplementTaskInput {\n task: Task;\n spec: Spec;\n leverage: string;\n context: ImplementationLogEntry[];\n}\n```\n\n资料来源：[src/prompts/implement-task.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/implement-task.ts)\n\n## Execution History\n\nThe system tracks job executions for auditing and debugging purposes:\n\n| Field | Description |\n|-------|-------------|\n| `itemsDeleted` | Number of items removed during execution |\n| `duration` | Execution time in milliseconds |\n| `error` | Error message if execution failed |\n\n```typescript\n// Duration formatting\n{(execution.duration / 1000).toFixed(2)}s\n```\n\n资料来源：[src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx)\n\n### Execution Statistics\n\n| Metric | Description |\n|--------|-------------|\n| `totalExecutions` | Total number of execution runs |\n| `successRate` | Percentage of successful executions |\n\n## Best Practices\n\n### Writing Effective Specs\n\n1. **Clear Purpose Statements**: Each task should have at least one well-defined purpose\n2. **Leverage Existing Code**: Always reference existing patterns or utilities to build upon\n3. **Measurable Requirements**: Requirements should be verifiable and testable\n4. **Appropriate Granularity**: Tasks should be small enough to complete in one session\n\n### Task Naming Conventions\n\n- Use descriptive task IDs\n- Group related tasks under section headers\n- Mark section headers with `isHeader: true`\n- Keep task titles concise but informative\n\n### Progress Tracking\n\n- Update task status promptly when work begins\n- Use the blocked status with reasons when encountering obstacles\n- Review implementation logs regularly to ensure accuracy\n\n---\n\n\n\n## Approval Workflow System\n\n### 相关页面\n\n相关主题：[Spec Management](#spec-management), [Web Dashboard](#web-dashboard), [VSCode Extension](#vscode-extension)\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/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\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/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/DashboardStatistics.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/DashboardStatistics.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
\n\n# Approval Workflow System\n\n## Overview\n\nThe Approval Workflow System is a core component of the spec-workflow-mcp project that enforces structured document review and revision processes. It ensures that all specifications, designs, and implementation tasks undergo explicit human approval before proceeding to subsequent phases.\n\n**Key Responsibilities:**\n- Managing approval requests with associated metadata (title, description, file path)\n- Tracking approval status through polling mechanisms\n- Enforcing sequential workflow progression (no phase skipping)\n- Blocking operations when approvals fail or cleanup is unsuccessful\n- Providing cross-platform interfaces (web dashboard and VS Code extension)\n\n**资料来源：**\n[src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n[src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"Client Interfaces\"\n VSCODE[VS Code Extension]\n DASHBOARD[Web Dashboard]\n end\n\n subgraph \"Core Services\"\n APPROVALS[approvals Tool]\n WATCHER[File Watcher]\n STORAGE[Approval Storage]\n end\n\n subgraph \"Data Layer\"\n APPROVALS_DIR[.spec-workflow/approvals/]\n end\n\n VSCODE --> |API calls| APPROVALS\n DASHBOARD --> |API calls| APPROVALS\n APPROVALS --> STORAGE\n STORAGE --> APPROVALS_DIR\n WATCHER --> |File monitoring| APPROVALS_DIR\n WATCHER --> |Events| STORAGE\n```\n\n### Technology Stack\n\n| Layer | Technology | Purpose |\n|-------|------------|---------|\n| Client UI | React + TypeScript | Dashboard and VS Code webview |\n| State Management | React Hooks | Local UI state |\n| Communication | VS Code API / WebSocket | Real-time updates |\n| Persistence | JSON Files | Approval records storage |\n| Monitoring | Node.js fs.watch | Directory change detection |\n\n**资料来源：**\n[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx:1-100)\n[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n\n---\n\n## Approval Lifecycle\n\n### State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: request action\n Pending --> Approved: User approves\n Pending --> NeedsRevision: User requests changes\n Approved --> Deleted: delete action (success)\n NeedsRevision --> Pending: User re-submits\n Deleted --> [*]\n Deleted --> Pending: delete action fails\n```\n\n### Workflow Phases\n\nEach workflow phase follows an identical approval pattern:\n\n| Phase | Document Type | File Path |\n|-------|--------------|-----------|\n| Phase 1 | Product Document | `.spec-workflow/steering/product.md` |\n| Phase 2 | Tech Document | `.spec-workflow/steering/tech.md` |\n| Phase 3 | Structure Document | `.spec-workflow/steering/structure.md` |\n\n**Steering Workflow Phase Pattern:**\n\n```mermaid\ngraph TD\n START[Phase Start] --> TEMPLATE[Check user-templates first,
then read template]\n TEMPLATE --> ANALYZE[Analyze content]\n ANALYZE --> CREATE[Create document file]\n CREATE --> APPROVE[Request approval
approvals action: request]\n APPROVE --> STATUS[Poll status
approvals action: status]\n STATUS --> CHECK{Status?}\n CHECK -->|needs-revision| UPDATE[Update document
using user comments]\n UPDATE --> CREATE\n CHECK -->|approved| CLEAN[Delete approval
approvals action: delete]\n CLEAN -->|success| NEXT[Next Phase]\n CLEAN -->|failed| STATUS\n \n style START fill:#e6f3ff\n style CHECK fill:#ffe6e6\n style NEXT fill:#e6f3ff\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## Approvals Tool API\n\n### Tool Actions\n\nThe `approvals` tool supports three primary actions:\n\n| Action | Parameters | Description |\n|--------|------------|-------------|\n| `request` | `title`, `description?`, `filePath` | Create new approval request |\n| `status` | `approvalId?` | Check approval status (polling) |\n| `delete` | `approvalId` | Remove approval after completion |\n\n### Request Action Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | `\"request\"` | Yes | Operation to perform |\n| `title` | `string` | Yes | Approval request title |\n| `description` | `string` | No | Detailed description |\n| `filePath` | `string` | Yes | Path to the document under review |\n\n### Usage Example\n\n```typescript\n// Request approval for a document\nconst approvalRequest = await tool.call({\n action: \"request\",\n title: \"Product Vision Document\",\n description: \"Initial product document for review\",\n filePath: \".spec-workflow/steering/product.md\"\n});\n\n// Poll for status until resolved\nlet status = await tool.call({ action: \"status\", approvalId: approvalRequest.id });\nwhile (status === \"pending\" || status === \"in_progress\") {\n await sleep(2000);\n status = await tool.call({ action: \"status\", approvalId: approvalRequest.id });\n}\n\n// Delete after successful approval\nawait tool.call({ action: \"delete\", approvalId: approvalRequest.id });\n```\n\n**资料来源：**\n[src/tools/approvals.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/approvals.ts)\n\n---\n\n## Data Models\n\n### Approval Record Schema\n\n```typescript\ninterface Approval {\n id: string; // Unique identifier (UUID)\n title: string; // Display title\n description?: string; // Optional description\n filePath: string; // Path to document under review\n status: ApprovalStatus; // Current state\n createdAt: Date; // Creation timestamp\n updatedAt: Date; // Last modification timestamp\n response?: string; // Approval response message\n requestedBy?: string; // User who requested approval\n}\n\ntype ApprovalStatus = \"pending\" | \"approved\" | \"needs-revision\" | \"rejected\";\n```\n\n### Storage Location\n\nApprovals are persisted as JSON files in the `.spec-workflow/approvals/` directory:\n\n```\n.spec-workflow/\n└── approvals/\n ├── {uuid}.json # Individual approval records\n └── archive/ # Archived approvals (completed)\n```\n\n**资料来源：**\n[src/dashboard/approval-storage.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/approval-storage.ts)\n\n---\n\n## UI Components\n\n### VS Code Extension Dashboard\n\nThe VS Code extension provides an integrated sidebar for managing approvals:\n\n**Features:**\n- Real-time approval list with pending count badge\n- Individual action buttons (Approve, Request Changes, View in Editor)\n- Batch selection mode for bulk operations\n- Selection counter and clear selection functionality\n- Translation support (i18n)\n\n**UI Layout:**\n\n```tsx\n// Approval card structure\n\n \n
\n

{approval.title}

\n {t('approvals.status.pending')}\n
\n \n \n {approval.description &&

{approval.description}

}\n {approval.filePath &&

{approval.filePath}

}\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:1-80)\n\n### Web Dashboard Statistics\n\nThe web dashboard displays approval statistics:\n\n```tsx\n
\n
\n {approvals.length}\n
\n
\n {approvals.length > 0 \n ? t('stats.approvals.awaiting') \n : t('stats.approvals.allClear')}\n
\n
\n```\n\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## Critical Workflow Rules\n\nThe approval system enforces strict rules that must be followed:\n\n| Rule | Description | Consequence if Violated |\n|------|-------------|-------------------------|\n| **Sequential Phases** | Complete phases in order | Workflow blocked |\n| **Blocking Cleanup** | Approval delete must succeed | Next phase blocked |\n| **No Verbal Approval** | Dashboard/VS Code only | Not accepted |\n| **No Proceed on \"approved\"** | Check system status only | Invalid workflow |\n| **Two-phase completion** | Approved status + successful cleanup | Incomplete transition |\n\n### Blocking Conditions\n\n```typescript\n// CRITICAL: Must have approved status AND successful cleanup before next phase\nif (status !== \"approved\") {\n return { success: false, error: \"Approval not granted\" };\n}\n\nconst deleteResult = await approvals({ action: \"delete\", approvalId });\nif (!deleteResult.success) {\n return { success: false, error: \"Cleanup failed - blocking next phase\" };\n}\n\n// Proceed to next phase...\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## File Watcher Integration\n\nThe approval system integrates with the file watcher for real-time updates:\n\n```mermaid\ngraph LR\n A[File System Event] --> B[watcher.ts]\n B --> C{Event Type}\n C -->|approval_created| D[Update UI]\n C -->|approval_deleted| E[Refresh List]\n C -->|approval_updated| F[Sync Status]\n```\n\n**Watched Events:**\n- File creation in `.spec-workflow/approvals/`\n- File modification\n- File deletion\n\n**资料来源：**\n[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\n\n---\n\n## Internationalization\n\nThe approval system supports 11 languages with i18n keys:\n\n| Key | English | Japanese | Chinese |\n|-----|---------|----------|---------|\n| `approvals.status.pending` | Pending | 保留中 | 待处理 |\n| `approvals.approve` | Approve | 承認 | 批准 |\n| `approvals.reject` | Request Changes | 変更依頼 | 请求更改 |\n| `approvals.noPending` | No pending approvals | 承認待ちなし | 无待批准项 |\n| `approvals.selectedCount` | {count} selected | {count}件選択 | 已选择 {count} 项 |\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## Implementation Log Integration\n\nWhen tasks are implemented following approval, the system tracks artifacts:\n\n```typescript\n// Artifacts tracked in implementation logs\ninterface Artifacts {\n apiEndpoints: APIEndpoint[];\n components: Component[];\n filesCreated: string[];\n filesModified: string[];\n}\n\n// Example artifact recording\nmarkdown += `### API Endpoints\\n\\n`;\nartifacts.apiEndpoints.forEach(api => {\n markdown += `#### ${api.method} ${api.path}\\n`;\n markdown += `- **Purpose:** ${api.purpose}\\n`;\n markdown += `- **Location:** ${api.location}\\n`;\n});\n```\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## Best Practices\n\n1. **Always poll for status** - Never assume immediate approval\n2. **Handle cleanup failures** - Block workflow on delete failures\n3. **Use file paths only** - Approval requests should contain paths, not content\n4. **Wait for full resolution** - Both approval AND cleanup must complete\n5. **Provide clear titles** - Help reviewers quickly identify documents\n\n---\n\n## Related Documentation\n\n- [Workflow Process](docs/WORKFLOW.md) - Complete workflow guidelines\n- [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details\n- [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation\n- [Development Guide](docs/DEVELOPMENT.md) - Contributing and setup\n\n---\n\n\n\n## Steering Documents\n\n### 相关页面\n\n相关主题：[Spec Management](#spec-management), [Approval Workflow System](#approval-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/prompts/create-steering-doc.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/prompts/create-steering-doc.ts)\n- [src/tools/steering-guide.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/tools/steering-guide.ts)\n- [src/markdown/templates/product-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/product-template.md)\n- [src/markdown/templates/tech-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/tech-template.md)\n- [src/markdown/templates/structure-template.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/markdown/templates/structure-template.md)\n
\n\n# Steering Documents\n\n## Overview\n\nSteering Documents are foundational markdown files that guide the development process by defining the product vision, technical architecture, and codebase organization. They serve as the single source of truth for maintaining alignment between development decisions and project goals.\n\nThe Steering Documents system consists of three core documents that work together to provide comprehensive guidance for the project.\n\n## Document Types\n\n### 1. Product Vision Document (`product.md`)\n\nThe product document defines the **what** and **why** of the project.\n\n| Section | Purpose |\n|---------|---------|\n| Product Vision | High-level description of the product's purpose and value proposition |\n| Target Users | Identification of primary and secondary user groups |\n| Key Features | Core functionality that delivers value to users |\n| Business Objectives | Goals and metrics that measure project success |\n\n**Template Location:** `src/markdown/templates/product-template.md`\n\n### 2. Technical Architecture Document (`tech.md`)\n\nThe tech document defines the **how** of the technical implementation.\n\n| Section | Purpose |\n|---------|---------|\n| Technology Stack | Programming languages, frameworks, and tools used |\n| Architecture Decisions | Key technical choices and their rationale |\n| Development Principles | Standards and practices for code quality |\n| Dependencies | External libraries and services integrated |\n\n**Template Location:** `src/markdown/templates/tech-template.md`\n\n### 3. Codebase Structure Document (`structure.md`)\n\nThe structure document defines the **where** of code organization.\n\n| Section | Purpose |\n|---------|---------|\n| Directory Structure | High-level organization of project folders |\n| Module Architecture | How code is partitioned into logical units |\n| Key Files | Important files and their responsibilities |\n| Module Relationships | Dependencies between different parts of the codebase |\n\n**Template Location:** `src/markdown/templates/structure-template.md`\n\n## Workflow\n\n```mermaid\ngraph TD\n A[Create/Update Steering Documents] --> B{Document Type}\n B -->|product.md| C[Define Vision & Features]\n B -->|tech.md| D[Document Architecture]\n B -->|structure.md| E[Map Codebase Organization]\n \n C --> F[Review with AI Assistant]\n D --> F\n E --> F\n \n F --> G[Store in Project Root]\n G --> H[Reference During Development]\n```\n\n## Steering Guide Tool\n\nThe `steering-guide.ts` module provides the core functionality for managing steering documents.\n\n**Location:** `src/tools/steering-guide.ts`\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `createSteeringDocument()` | Generate new steering documents from templates |\n| `updateSteeringDocument()` | Modify existing documents with new information |\n| `validateSteeringDocument()` | Ensure document structure matches template |\n| `getSteeringDocument()` | Retrieve document content for reference |\n\n### Configuration Options\n\n```typescript\ninterface SteeringConfig {\n outputDir: string; // Directory for steering documents\n templateDir: string; // Location of markdown templates\n autoSync: boolean; // Auto-sync with project changes\n validationLevel: 'strict' | 'loose' | 'none';\n}\n```\n\n## Document Templates\n\n### Product Template Structure\n\n```markdown\n# Product Vision\n[High-level product description]\n\n# Target Users\n[User personas and use cases]\n\n# Key Features\n- Feature 1\n- Feature 2\n\n# Business Objectives\n[Success metrics and goals]\n```\n\n### Tech Template Structure\n\n```markdown\n# Technology Stack\n[Languages, frameworks, tools]\n\n# Architecture Decisions\n[Key technical decisions]\n\n# Development Principles\n[Code standards and practices]\n```\n\n### Structure Template Structure\n\n```markdown\n# Directory Structure\n[Folder organization]\n\n# Module Architecture\n[Code partitioning]\n\n# Key Files\n[Important file responsibilities]\n```\n\n## Integration with VSCode Extension\n\nThe VSCode extension provides a user interface for managing steering documents.\n\n**Location:** `vscode-extension/src/webview/App.tsx`\n\n### Steering Tab Features\n\n```typescript\ninterface SteeringDocument {\n name: 'product' | 'tech' | 'structure';\n exists: boolean;\n lastModified?: Date;\n path: string;\n}\n```\n\n| Feature | Description |\n|---------|-------------|\n| Document List | Display all three steering documents with status |\n| Last Modified | Show when each document was last updated |\n| Open Document | Quick access to view/edit documents |\n| Copy Instructions | Copy AI assistant prompt for document creation |\n\n### User Interface Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant VSCode as VSCode Extension\n participant FS as File System\n \n User->>VSCode: Open Steering Tab\n VSCode->>FS: Check document existence\n FS-->>VSCode: Return file metadata\n VSCode-->>User: Display document list\n \n User->>VSCode: Copy creation instructions\n VSCode->>User: Copy prompt to clipboard\n \n User->>VSCode: Click \"Open\" on document\n VSCode->>FS: Open file in editor\n```\n\n## Implementation Log Integration\n\nSteering documents are referenced in the implementation log system.\n\n**Location:** `src/dashboard/implementation-log-manager.ts`\n\nThe implementation log can include references to steering documents as part of task completion records, linking development work back to the guiding documents.\n\n## Best Practices\n\n1. **Keep Documents Updated**: Review and update steering documents when significant changes occur\n2. **Consistent Location**: Always store in project root for easy access\n3. **Version Control**: Track changes to steering documents in version history\n4. **AI Reference**: Use documents as context for AI-assisted development\n\n## File Reference Summary\n\n| Document | Template Path | Output Location |\n|----------|---------------|-----------------|\n| product.md | src/markdown/templates/product-template.md | Project root |\n| tech.md | src/markdown/templates/tech-template.md | Project root |\n| structure.md | src/markdown/templates/structure-template.md | Project root |\n\n## Related Components\n\n- **Prompt Generator:** `src/prompts/create-steering-doc.ts` - Generates prompts for AI document creation\n- **Steering Guide:** `src/tools/steering-guide.ts` - Core tool for document management\n- **VSCode Extension:** `vscode-extension/src/webview/App.tsx` - UI for document interaction\n- **Dashboard Frontend:** `src/dashboard_frontend/src/modules/pages/SteeringPage.tsx` - Web dashboard integration\n\n---\n\n\n\n## Web Dashboard\n\n### 相关页面\n\n相关主题：[VSCode Extension](#vscode-extension), [Docker Deployment](#docker-deployment), [System Architecture](#architecture)\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/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts)\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/ws/WebSocketProvider.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx)\n- [src/dashboard_frontend/src/modules/mdx-editor/MDXEditorWrapper.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/mdx-editor/MDXEditorWrapper.tsx)\n- [src/dashboard_frontend/src/i18n.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/i18n.ts)\n- [containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml)\n
\n\n# Web Dashboard\n\nThe Web Dashboard is the primary user interface for the spec-workflow-mcp system. It provides a real-time, visual interface for monitoring project specifications, tracking task progress, reviewing implementation logs, and managing automated workflows across all connected projects.\n\n## Overview\n\nThe dashboard serves as a centralized monitoring and management hub that complements the MCP (Model Context Protocol) server functionality. While the MCP server handles code execution and specification enforcement, the dashboard offers:\n\n- **Real-time monitoring** of spec files and implementation progress\n- **Visual task tracking** with filtering and completion indicators\n- **Implementation log visualization** with file change statistics\n- **Automated cleanup job management** with execution history\n- **Multi-project support** via WebSocket connections\n\nThe dashboard runs as a separate service (default port 5000) and communicates with connected projects through a file-watching system and WebSocket connections 资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Browser Client] <-->|HTTP/WebSocket| B[Dashboard Server :5000]\n B <-->|File System Events| C[.spec-workflow Directory]\n B <-->|WebSocket| D[VSCode Extension Webview]\n C <-->|File Watching| E[Project Specs]\n C <-->|File Watching| F[Steering Documents]\n C <-->|File Watching| G[Implementation Logs]\n```\n\n### Frontend Architecture\n\nThe dashboard frontend is a React-based single-page application located in `src/dashboard_frontend/`. It uses a modular structure:\n\n```\nsrc/dashboard_frontend/\n├── src/\n│ ├── modules/\n│ │ ├── app/App.tsx # Main application shell\n│ │ ├── pages/ # Page components\n│ │ │ ├── SettingsPage.tsx\n│ │ │ ├── TasksPage.tsx\n│ │ │ ├── LogsPage.tsx\n│ │ │ └── JobExecutionHistory.tsx\n│ │ ├── ws/ # WebSocket integration\n│ │ │ └── WebSocketProvider.tsx\n│ │ └── mdx-editor/ # MDX editing capabilities\n│ │ └── MDXEditorWrapper.tsx\n│ └── i18n.ts # Internationalization\n```\n\nThe `WebSocketProvider` establishes and maintains a persistent connection to the dashboard server, enabling real-time updates without page refreshes 资料来源：[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\n### Backend Server\n\nThe server is implemented in `src/server.ts` and provides:\n\n- Express.js HTTP server for static file serving\n- WebSocket server for real-time client communication\n- File system watcher integration\n- REST API endpoints for project data retrieval\n\n## Pages and Features\n\n### Overview Page\n\nThe landing page displays project statistics aggregated from all connected projects:\n\n| Metric | Description |\n|--------|-------------|\n| Active Specs | Number of currently active specification files |\n| Archived Specs | Count of completed/archived specifications |\n| Total Specs | Overall count of specification documents |\n| Tasks | Completed vs total tasks with progress percentage |\n\nThe overview uses progress bars to visualize completion status and shows recent activity feed 资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx).\n\n### Tasks Page\n\nThe tasks page provides comprehensive task management capabilities:\n\n- **Filtering controls** for narrowing down task lists\n- **View mode switcher** between list and other display formats\n- **Progress visualization** with percentage indicators\n- **Task status indicators** (in-progress, blocked, completed)\n\nTasks display metadata including leverage scores and AI prompts when available, with expandable sections for detailed information 资料来源：[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### Logs Page\n\nImplementation logs are displayed with comprehensive statistics:\n\n```mermaid\ngraph LR\n A[File Change Event] --> B[Log Entry Created]\n B --> C[Statistics Calculated]\n C --> D[Markdown Rendered]\n D --> E[Client Displayed]\n```\n\nLog entries include:\n\n- **Statistics**: Lines added/removed, files changed, net change\n- **Files Modified**: List with syntax-highlighted file paths\n- **Files Created**: Newly created files in the project\n- **Artifacts**: API endpoints, components, functions, and classes documented during implementation\n\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\n### Settings Page\n\nThe settings page manages automated cleanup jobs:\n\n- Section-based layout with expandable/collapsible panels\n- Job configuration controls\n- Loading states with spinner indicators\n- Error handling with styled alert boxes\n\nThe automated cleanup section allows management of jobs that run across all connected projects 资料来源：[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### Job Execution History\n\nA dedicated panel displays execution statistics:\n\n| Metric | Description |\n|--------|-------------|\n| Total Runs | Number of job executions |\n| Success Rate | Percentage of successful runs with color coding |\n\nSuccess rates are color-coded: green for 100%, yellow for 50-99%, and red for below 50% 资料来源：[src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx).\n\n## Real-time Updates\n\n### WebSocket Communication\n\nThe dashboard uses WebSocket for bidirectional real-time communication:\n\n1. **Connection establishment**: Client connects to `/ws` endpoint\n2. **Project updates**: Server pushes spec and task changes immediately\n3. **Language preferences**: Users can change language with instant UI update\n\nThe WebSocket provider handles message routing and maintains connection state:\n\n```typescript\n// Message types supported\ntype MessageType = \n | 'specs-updated' // Spec files changed\n | 'tasks-updated' // Task status changed\n | 'language-changed' // UI language update\n```\n\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\n### File Watching\n\nThe watcher system monitors the `.spec-workflow` directory:\n\n```mermaid\nsequenceDiagram\n participant FS as File System\n participant Watcher as Watcher Service\n participant Server as Dashboard Server\n participant WS as WebSocket Clients\n \n FS->>Watcher: File change detected\n Watcher->>Server: Process change\n Server->>WS: Broadcast update\n WS->>Client: Trigger re-render\n```\n\nWhen spec files, steering documents, or implementation logs change, the watcher triggers updates to all connected clients 资料来源：[src/dashboard/watcher.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/src/dashboard/watcher.ts).\n\n## Internationalization\n\nThe dashboard supports multiple languages through `src/dashboard_frontend/src/i18n.ts`. All user-facing strings are externalized and can be translated. Language changes are propagated to all connected clients via WebSocket.\n\nSupported translations in the repository include:\n\n- English (default)\n- Korean (README.ko.md)\n- French (README.fr.md)\n- German\n- Portuguese\n- Russian\n- Italian\n- Arabic\n\n## MDX Editor Integration\n\nThe `MDXEditorWrapper` component provides in-browser editing capabilities for specification documents. This allows users to:\n\n- Edit spec files directly in the browser\n- Preview rendered markdown\n- Auto-save changes to the file system\n\n## Deployment Options\n\n### Standalone Server\n\nStart the dashboard with the `--dashboard` flag:\n\n```bash\nnpx -y @pimzino/spec-workflow-mcp@latest --dashboard\n```\n\nThe server binds to `127.0.0.1:5000` by default, preventing network exposure 资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n### Docker Deployment\n\nDocker deployment provides isolated execution:\n\n```yaml\n# containers/docker-compose.yml\nservices:\n dashboard:\n build: \n context: .\n dockerfile: containers/Dockerfile\n ports:\n - \"5000:5000\"\n volumes:\n - ./workspace/.spec-workflow:/workspace/.spec-workflow:rw\n```\n\n资料来源：[containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml).\n\n## Security Features\n\nThe dashboard implements enterprise-grade security:\n\n| Feature | Implementation |\n|---------|----------------|\n| Localhost Binding | Binds to `127.0.0.1` by default |\n| Rate Limiting | 120 requests/minute per client |\n| Security Headers | X-Content-Type-Options, X-Frame-Options, CSP |\n| CORS Protection | Restricted cross-origin access |\n\n资料来源：[README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md).\n\n## VSCode Extension Integration\n\nThe VSCode extension embeds the dashboard as a webview, providing:\n\n- In-editor dashboard access\n- Seamless integration with the development environment\n- Real-time updates within VSCode\n\nThe webview uses the same React components as the standalone dashboard but is packaged for VSCode's webview API 资料来源：[vscode-extension/src/webview/App.tsx](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/webview/App.tsx).\n\n## Configuration\n\nThe dashboard behavior is configured through the project's `.spec-workflow/config.toml`:\n\n```toml\n[dashboard]\nport = 5000\nhost = \"127.0.0.1\"\n```\n\nMultiple projects can connect to a single dashboard instance, allowing centralized monitoring across a development environment.\n\n---\n\n\n\n## VSCode Extension\n\n### 相关页面\n\n相关主题：[Web Dashboard](#web-dashboard), [Approval Workflow System](#approval-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [vscode-extension/package.json](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/package.json)\n- [vscode-extension/src/extension.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension.ts)\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/ApprovalCommandService.ts](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/src/extension/services/ApprovalCommandService.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/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/vscode-extension/README.md)\n
\n\n# VSCode Extension\n\n## Overview\n\nThe spec-workflow-mcp VSCode Extension provides an integrated development experience for managing specification-based workflows directly within Visual Studio Code. It serves as the recommended interface option for VSCode users, offering a native sidebar panel, approval management tools, and real-time project monitoring capabilities.\n\n资料来源：[vscode-extension/README.md]()\n\n### Purpose and Scope\n\nThe extension complements the CLI-based web dashboard by providing:\n\n- **Inline project management** - View and manage specs without leaving the editor\n- **Approval workflow integration** - Review, approve, or reject specification changes\n- **Task tracking** - Monitor implementation progress across specs and tasks\n- **Implementation logging** - Track code artifacts generated during development\n- **Multi-project support** - Connect to multiple specification projects simultaneously\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n## Architecture\n\n### Component Overview\n\nThe extension follows a modular architecture with clear separation between VSCode integration layers and UI components.\n\n```mermaid\ngraph TD\n subgraph \"VSCode Host Layer\"\n EXT[extension.ts]\n SIDEBAR[SidebarProvider]\n CMDS[ApprovalCommandService]\n EDITOR[ApprovalEditorService]\n end\n \n subgraph \"Webview Layer\"\n APP[App.tsx]\n LOGS[LogsPage]\n TASKS[TasksPage]\n CARDS[LogEntryCard]\n MODAL[comment-modal]\n end\n \n subgraph \"Communication\"\n MSG[vscode.postMessage]\n EVENTS[Event System]\n end\n \n EXT --> SIDEBAR\n SIDEBAR --> MSG\n MSG --> APP\n APP --> LOGS\n APP --> TASKS\n APP --> CARDS\n LOGS --> MODAL\n CARDS --> MODAL\n \n CMDS --> EVENTS\n EDITOR --> EVENTS\n EVENTS --> MSG\n```\n\n### Directory Structure\n\n```\nvscode-extension/\n├── package.json # Extension manifest and configuration\n├── src/\n│ ├── extension.ts # Entry point, registers commands and providers\n│ ├── extension/\n│ │ ├── providers/\n│ │ │ └── SidebarProvider.ts # Sidebar webview container management\n│ │ └── services/\n│ │ ├── ApprovalCommandService.ts # Command execution logic\n│ │ └── ApprovalEditorService.ts # Editor-related operations\n│ └── webview/\n│ ├── App.tsx # Main webview application\n│ ├── components/\n│ │ └── LogEntryCard.tsx # Implementation log entry display\n│ ├── pages/\n│ │ ├── LogsPage.tsx # Implementation logs view\n│ │ └── TasksPage.tsx # Task management view\n│ ├── comment-modal.tsx # Comment input modal\n│ ├── comment-modal.html # Modal HTML template\n│ └── globals.css # Global styles\n└── webview-dist/ # Compiled webview assets\n ├── comment-modal.js\n ├── i18n.js\n └── globals.css\n```\n\n资料来源：[vscode-extension/package.json]()\n\n## Core Components\n\n### Extension Entry Point\n\nThe `extension.ts` file serves as the main entry point for the VSCode extension. It performs the following initialization tasks:\n\n1. **Command Registration** - Registers VSCode commands for approval actions\n2. **Sidebar Provider Registration** - Establishes the sidebar webview container\n3. **Event Listeners** - Sets up communication between VSCode and webviews\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n### SidebarProvider\n\nThe `SidebarProvider` class manages the lifecycle of the sidebar webview panel.\n\n| Method | Purpose |\n|--------|---------|\n| `resolveWebviewView()` | Initializes and configures the webview |\n| `dispose()` | Cleans up resources when sidebar closes |\n| `postMessage()` | Sends messages to the webview |\n| `handleMessage()` | Processes messages from webview |\n\nThe provider implements the `WebviewViewProvider` interface and creates a webview with:\n\n- **Local resource roots** - Access to extension's local file resources\n- **Scripts enabled** - JavaScript execution for interactivity\n- **State persistence** - Maintains view state across sessions\n\n资料来源：[vscode-extension/src/extension/providers/SidebarProvider.ts]()\n\n### ApprovalCommandService\n\nThis service handles command execution related to the approval workflow system.\n\n| Method | Description |\n|--------|-------------|\n| `executeCommand()` | Executes registered VSCode commands |\n| `getApprovalList()` | Retrieves pending approvals |\n| `submitApproval()` | Submits approval decision |\n| `submitRejection()` | Submits rejection with reason |\n| `undoDecision()` | Reverts previous approval/rejection |\n\n资料来源：[vscode-extension/src/extension/services/ApprovalCommandService.ts]()\n\n### ApprovalEditorService\n\nThe `ApprovalEditorService` manages editor-related operations for reviewing specification changes.\n\n| Method | Purpose |\n|--------|---------|\n| `openDiffViewer()` | Opens built-in diff editor for spec comparisons |\n| `getCurrentDocument()` | Retrieves active document content |\n| `highlightChanges()` | Applies decorations to changed regions |\n| `createSnapshot()` | Creates versioned snapshots of spec state |\n\n资料来源：[vscode-extension/src/extension/services/ApprovalEditorService.ts]()\n\n## Webview UI\n\n### App Component\n\nThe `App.tsx` serves as the main container for the sidebar webview, organizing content into logical sections.\n\n```typescript\ninterface ProjectStats {\n activeSpecs: number; // Total specs in active development\n completedSpecs: number; // Fully approved specs\n archivedSpecs: number; // Archived specifications\n totalSpecs: number; // Combined total\n totalTasks: number; // All tasks across specs\n completedTasks: number; // Completed implementation tasks\n}\n```\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n### Project Overview Card\n\nDisplays aggregate statistics about the connected project:\n\n- **Active Specs** - Shows `completedSpecs / activeSpecs` ratio\n- **Archived Specs** - Count of archived specifications\n- **Total Specs** - Combined specification count\n- **Tasks** - Shows `completedTasks / totalTasks` progress\n\n资料来源：[vscode-extension/src/webview/App.tsx]()\n\n### TasksPage\n\nThe tasks view renders individual specification tasks with the following metadata:\n\n| Field | Description | UI Indicator |\n|-------|-------------|--------------|\n| `purposes` | List of task objectives | Bullet list |\n| `requirements` | Technical requirements | Orange label |\n| `leverage` | Code patterns to reuse | Cyan badge |\n| `prompt` | AI instruction text | Collapsible section |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/TasksPage.tsx]()\n\n### LogEntryCard\n\nDisplays implementation log entries with artifact tracking:\n\n```typescript\ninterface ImplementationLogEntry {\n id: string;\n timestamp: string;\n message: 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资料来源：[vscode-extension/src/webview/components/LogEntryCard.tsx]()\n\n### Artifact Sections\n\nEach artifact type has a dedicated display section:\n\n| Artifact Type | Icon | Color | Properties Displayed |\n|--------------|------|-------|----------------------|\n| API Endpoints | GlobeAltIcon | Blue | Method, Path, Purpose, Location, Formats |\n| Components | CubeIcon | Purple | Name, Type, Purpose, Props, Exports |\n| Functions | CodeBracketSquareIcon | Green | Name, Purpose, Location, Signature, Exported |\n| Classes | CircleStackIcon | Orange | Name, Purpose, Location, Methods, Exported |\n| Integrations | LinkIcon | - | Description, Frontend, Backend, Data Flow |\n\n资料来源：[src/dashboard_frontend/src/modules/pages/LogsPage.tsx]()\n\n### Comment Modal\n\nThe comment modal provides a dialog for adding notes to approvals:\n\n**HTML Template Structure:**\n```html\n\n\n\n \n \n Add Comment\n\n\n
\n \n\n\n```\n\n**Compiled Version:**\n```html\n\n\n\n```\n\n资料来源：[vscode-extension/src/webview/comment-modal.html]()\n资料来源：[vscode-extension/webview-dist/comment-modal.html]()\n\n## Communication Protocol\n\n### Message Flow\n\nThe extension uses VSCode's `postMessage` API for bidirectional communication between the host and webview.\n\n```mermaid\nsequenceDiagram\n participant User\n participant Webview\n participant VSCode\n participant Backend\n \n User->>Webview: Click action\n Webview->>VSCode: postMessage({ type, payload })\n VSCode->>Backend: HTTP API call\n Backend-->>VSCode: JSON response\n VSCode-->>Webview: WebviewPanel.webview.postMessage()\n Webview-->>User: Updated UI\n```\n\n### Message Types\n\n| Direction | Message Type | Purpose |\n|-----------|--------------|---------|\n| Webview → VSCode | `OPEN_APPROVAL` | Open approval detail view |\n| Webview → VSCode | `SUBMIT_DECISION` | Submit approval/rejection |\n| Webview → VSCode | `ADD_COMMENT` | Add comment to approval |\n| VSCode → Webview | `UPDATE_STATS` | Refresh project statistics |\n| VSCode → Webview | `APPROVAL_UPDATED` | Approval state change notification |\n\n## Configuration\n\n### Extension Settings\n\nThe extension supports project-specific configuration through TOML files:\n\n```toml\n# .spec-workflow/config.example.toml\n[project]\nname = \"my-project\"\ndashboard_url = \"http://localhost:5000\"\nauto_refresh = true\nrefresh_interval = 30\n```\n\n### VSCode Configuration\n\n```json\n{\n \"spec-workflow.projectPath\": \"/path/to/project\",\n \"spec-workflow.dashboardUrl\": \"http://localhost:5000\",\n \"spec-workflow.autoRefresh\": true\n}\n```\n\n## Integration with Dashboard\n\nThe VSCode extension operates independently from the web dashboard while sharing the same backend API:\n\n```mermaid\ngraph LR\n subgraph \"Development Environment\"\n VSCODE[VSCode Extension]\n WEBVIEW[Sidebar Webview]\n end\n \n subgraph \"Backend Services\"\n API[REST API]\n FILES[File System]\n end\n \n VSCODE --> API\n WEBVIEW --> API\n API --> FILES\n \n subgraph \"Optional Services\"\n DASHBOARD[Web Dashboard]\n end\n \n API <--> DASHBOARD\n```\n\n**Key Points:**\n- Only one dashboard instance is needed per machine\n- All projects connect to the same dashboard\n- VSCode extension can work standalone with direct file access\n- Approval actions sync across both interfaces\n\n资料来源：[vscode-extension/README.md]()\n\n## Installation\n\n### From VSCode Marketplace\n\n1. Open VSCode\n2. Navigate to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)\n3. Search for \"spec-workflow\"\n4. Click Install\n\n### From Command Line\n\n```bash\ncode --install-extension pimzino.spec-workflow\n```\n\n### Configuration Required\n\nAfter installation, configure the project path in VSCode settings:\n\n```json\n{\n \"spec-workflow.projectPath\": \"/absolute/path/to/your/project\"\n}\n```\n\n资料来源：[vscode-extension/README.md]()\n\n## Feature Comparison\n\n| Feature | Web Dashboard | VSCode Extension |\n|---------|--------------|------------------|\n| Interface | Browser-based | Native sidebar |\n| Launch command | `npx @pimzino/spec-workflow-mcp@latest --dashboard` | VSCode Extension button |\n| Approval management | Full support | Full support |\n| Task viewing | Yes | Yes |\n| Implementation logs | Yes | Yes |\n| Inline editing | Limited | Yes |\n| Editor integration | No | Yes (diff viewer) |\n| Project switching | URL-based | Dropdown menu |\n\n## Extension Commands\n\nThe extension registers the following VSCode commands:\n\n| Command ID | Description | Shortcut |\n|------------|-------------|----------|\n| `spec-workflow.refresh` | Refresh project data | `Ctrl+Shift+R` |\n| `spec-workflow.openDashboard` | Open web dashboard | `Ctrl+Shift+D` |\n| `spec-workflow.approveAll` | Approve all pending specs | - |\n| `spec-workflow.showApproval` | Show approval detail | - |\n| `spec-workflow.addComment` | Add comment to selection | - |\n\n资料来源：[vscode-extension/src/extension.ts]()\n\n## Dependencies\n\nThe extension depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@vscode/webview-ui-toolkit` | ^1.2.0 | Webview UI components |\n| `@spec-workflow/core` | workspace:* | Core shared logic |\n| `react` | ^18.2.0 | UI framework |\n| `tailwindcss` | ^3.4.0 | Styling |\n\n资料来源：[vscode-extension/package.json]()\n\n## Troubleshooting\n\n### Sidebar Not Loading\n\n1. Verify project path is correctly configured\n2. Check that `.spec-workflow/` directory exists in project root\n3. Run \"Developer: Reload Window\" command\n\n### API Connection Errors\n\n1. Ensure web dashboard is running (if using shared backend)\n2. Check `spec-workflow.dashboardUrl` setting\n3. Verify network connectivity\n\n### Webview Scripts Blocked\n\nThe webview requires script execution. If scripts are blocked:\n\n1. Check `webview.csp` setting in VSCode\n2. Ensure no security policies are preventing execution\n\n资料来源：[vscode-extension/README.md]()\n\n\n---\n\n\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[Web Dashboard](#web-dashboard)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this documentation page:\n\n- [containers/Dockerfile](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/Dockerfile)\n- [containers/docker-compose.yml](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/docker-compose.yml)\n- [containers/README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/README.md)\n- [containers/DOCKER_USAGE.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/containers/DOCKER_USAGE.md)\n- [README.md](https://github.com/Pimzino/spec-workflow-mcp/blob/main/README.md)\n
\n\n# Docker Deployment\n\n## Overview\n\nThe spec-workflow-mcp project provides a containerized dashboard deployment option for isolated and secure execution in Docker environments. This deployment method is designed for users who prefer not to install Node.js locally or require a self-contained, portable solution for running the specification workflow management system.\n\nThe Docker deployment bundles the Node.js runtime (version 24-alpine), the dashboard application, and all required dependencies into a single image that can be run consistently across different host systems.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User Host Machine] -->|HTTP Requests| B[Docker Container]\n B -->|Port Mapping| C[Dashboard Application]\n C -->|Volume Mount| D[.spec-workflow Directory]\n \n E[Docker Networking] -->|Security Control| F[127.0.0.1:5000:5000]\n E -->|Optional External| G[0.0.0.0:5000:5000]\n \n style C fill:#f9f,stroke:#333,stroke-width:2px\n style D fill:#ff9,stroke:#333,stroke-width:2px\n```\n\n### Container Components\n\n| Component | Description |\n|-----------|-------------|\n| **Base Image** | `node:24-alpine` - Minimal Node.js runtime |\n| **Application User** | `node` (UID 1000) - Non-root execution |\n| **Dashboard Port** | 5000 (default) - Internal container port |\n| **State Directory** | `/workspace/.spec-workflow` - Project state location |\n| **Audit Log** | `/.spec-workflow/audit.log` - JSON logging |\n\n## Quick Start\n\n### Building the Image\n\n```bash\n# Build using Docker CLI\ndocker build -f containers/Dockerfile -t spec-workflow-mcp .\n\n# Verify the image was created\ndocker images spec-workflow-mcp\n```\n\n### Running the Container\n\n```bash\n# Basic run with default settings\ndocker run -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\nThe dashboard becomes accessible at: `http://localhost:5000` 资料来源：[README.md:1-10]()\n\n## Docker Compose Deployment\n\nDocker Compose is the recommended deployment method as it provides additional security hardening and simplified management.\n\n### Default Configuration\n\nCreate a `.env` file for environment configuration:\n\n```bash\n# .env file\nDASHBOARD_PORT=5000\nSPEC_WORKFLOW_PATH=./workspace\n```\n\nStart the dashboard:\n\n```bash\ncd containers\ndocker-compose up --build\n```\n\n### Management Commands\n\n```bash\n# Start in detached mode\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop the dashboard\ndocker-compose down\n\n# Rebuild and restart\ndocker-compose up --build\n```\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Default (Docker) | Description |\n|----------|------------------|-------------|\n| `DASHBOARD_PORT` | `5000` | Port on which the dashboard runs |\n| `DASHBOARD_HOST` | `127.0.0.1` | Host IP for port binding |\n| `SPEC_WORKFLOW_PATH` | `/workspace` | Path to project directory (inside container) |\n| `SPEC_WORKFLOW_BIND_ADDRESS` | `0.0.0.0` | IP address to bind inside container |\n| `SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS` | `true` | External access control |\n| `SPEC_WORKFLOW_RATE_LIMIT_ENABLED` | `true` | Enable/disable rate limiting |\n| `SPEC_WORKFLOW_CORS_ENABLED` | `true` | Enable/disable CORS |\n| `SPEC_WORKFLOW_HOME` | - | Global state directory for sandboxed environments |\n\n资料来源：[containers/README.md:80-100]()\n\n### Custom Port Configuration\n\n```bash\n# Using Docker CLI\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### Volume Mounts\n\nThe dashboard requires read-write access to the `.spec-workflow` directory:\n\n```bash\n-v \"/path/to/project/.spec-workflow:/workspace/.spec-workflow:rw\"\n```\n\n**Important Notes:**\n- The volume mount must be read-write (`:rw`) for the dashboard to function properly\n- Only the `.spec-workflow` directory needs to be mounted\n- The directory will be created automatically if it doesn't exist 资料来源：[containers/README.md:60-70]()\n\n## Security Features\n\n### Implemented Security Controls\n\nThe Docker image includes enterprise-grade security features suitable for corporate environments:\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| **Non-root User** | ✅ Enabled | Runs as `node` user (UID 1000) |\n| **Rate Limiting** | ✅ Enabled | 120 requests/minute per client |\n| **Audit Logging** | ✅ Enabled | JSON logs with 30-day retention |\n| **Security Headers** | ✅ Enabled | XSS, clickjacking, MIME sniffing protection |\n| **CORS Protection** | ✅ Enabled | Localhost origins only by default |\n| **Localhost Binding** | ✅ Default | `127.0.0.1:5000:5000` in docker-compose |\n| **Read-only Filesystem** | ✅ Available | `read_only: true` in compose |\n| **Capability Dropping** | ✅ Enabled | All Linux capabilities dropped |\n\n### Network Security Models\n\n```mermaid\ngraph LR\n A[Localhost Only] -->|127.0.0.1:5000:5000| B[Recommended - Secure]\n C[Network Access] -->|0.0.0.0:5000:5000| D[Available - Requires Firewall]\n```\n\n**Option 1: Localhost Only (Secure Default)**\n\nThe default `docker-compose.yml` uses localhost-only port mapping:\n\n```yaml\nports:\n - \"127.0.0.1:5000:5000\" # Only accessible from host machine\n```\n\nOr with Docker CLI:\n\n```bash\ndocker run -p 127.0.0.1:5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n**Option 2: Network Access (Exposes to Network)**\n\n```bash\ndocker run -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n⚠️ **Security Warning:** This configuration exposes the dashboard to your network. The application displays a security warning in the logs. Only use when necessary and ensure proper network security measures (firewall, VPN) are in place. 资料来源：[containers/README.md:110-140]()\n\n### Docker Compose Security Hardening\n\nThe provided `docker-compose.yml` includes additional security settings:\n\n```yaml\n# Read-only root filesystem\nread_only: true\n\n# Drop all Linux capabilities\ncap_drop:\n - ALL\n\n# Prevent privilege escalation\nsecurity_opt:\n - no-new-privileges:true\n\n# Resource limits (prevent DoS)\ndeploy:\n resources:\n limits:\n cpus: '1.0'\n memory: 512M\n```\n\n### Best Practices\n\n1. **Use localhost port mapping** when possible (`127.0.0.1:5000:5000`)\n2. **Never expose to public internet** without proper authentication/firewall\n3. **Keep rate limiting enabled** in production\n4. **Use the provided docker-compose.yml** for security hardening\n5. **Run as non-root user** (default in the image)\n6. **Mount volumes read-write only when necessary** 资料来源：[containers/README.md:150-165]()\n\n## Audit Logging\n\nAll API requests are logged to a structured JSON audit log for compliance and debugging.\n\n### Log Location\n\n```\n/.spec-workflow/audit.log\n```\n\n### Log Format\n\n```json\n{\n \"timestamp\": \"2025-12-06T10:30:45.123Z\",\n \"actor\": \"127.0.0.1\",\n \"action\": \"GET /api/projects/list\",\n \"resource\": \"/api/projects/list\",\n \"result\": \"success\",\n \"details\": {\n \"statusCode\": 200,\n \"duration\": 45,\n \"userAgent\": \"Mozilla/5.0...\"\n }\n}\n```\n\n### Viewing Logs\n\n```bash\n# View recent logs\ntail -f .spec-workflow/audit.log\n\n# Parse as JSON (requires jq)\ncat .spec-workflow/audit.log | jq '.'\n\n# Filter by result\ncat .spec-workflow/audit.log | jq 'select(.result == \"denied\")'\n```\n\n## Advanced Configuration\n\n### Auto-Restart on Failure\n\n```bash\ndocker run -d \\\n --name spec-workflow-dashboard \\\n --restart unless-stopped \\\n -p 5000:5000 \\\n -v \"./workspace/.spec-workflow:/workspace/.spec-workflow:rw\" \\\n spec-workflow-mcp\n```\n\n### Health Checks\n\nThe dashboard does not currently include built-in health checks. You can verify connectivity manually:\n\n```bash\ncurl http://localhost:5000\n```\n\n### Testing the Docker Image\n\nA comprehensive test script validates Docker image configurations:\n\n```bash\n# From the containers directory\n./test-docker.sh\n```\n\n| Test | Description |\n|------|-------------|\n| **Image Build** | Verifies the Docker image builds successfully |\n| **Docker Default Config** | Tests app binding to 0.0.0.0, Docker exposing to localhost |\n| **Security Check** | Verifies app-level security block |\n| **Network Exposure** | Tests full network port mapping |\n| **Rate Limiting** | Verifies rate limiting configuration |\n| **Non-Root User** | Confirms container runs as non-privileged user |\n| **Custom Port** | Tests custom port configuration |\n\n资料来源：[README.md:50-75]()\n\n## Troubleshooting\n\n### Container Does Not Start\n\n**Error:** Container exits immediately after starting\n\n**Solutions:**\n- Check logs: `docker logs `\n- Verify volume mount path exists and is correct\n- Ensure port 5000 (or your configured port) is not already in use\n\n### Cannot Connect to Dashboard\n\n**Error:** Unable to access `http://localhost:5000`\n\n**Solutions:**\n- Verify container is running: `docker ps`\n- Check port is properly mapped: `docker port `\n- Ensure firewall allows connections on the port\n\n### Build Fails\n\n**Error:** Build fails with COPY or dependency errors\n\n**Solutions:**\n- Build from repository root: `docker build -f containers/Dockerfile -t spec-workflow-mcp .`\n- Verify all source files are present\n- Confirm `package.json` and `package-lock.json` exist 资料来源：[containers/README.md:40-60]()\n\n### Inspecting the Container\n\n```bash\n# View container details\ndocker inspect \n\n# Access container shell\ndocker exec -it /bin/sh\n```\n\n## External Access with Authentication\n\nThe dashboard does not include built-in authentication. For external access scenarios, use a reverse proxy:\n\n### nginx with Basic Auth\n\n```nginx\nserver {\n listen 443 ssl;\n server_name dashboard.example.com;\n \n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n \n auth_basic \"Dashboard Access\";\n auth_basic_user_file /etc/nginx/.htpasswd;\n \n location / {\n proxy_pass http://127.0.0.1:5000;\n }\n}\n```\n\n## Sandbox Environments\n\nFor sandboxed environments (e.g., Codex CLI with `sandbox_mode=workspace-write`) where `$HOME` is read-only, use the `SPEC_WORKFLOW_HOME` environment variable to redirect global state files to a writable location:\n\n```bash\nSPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace\n```\n\nThis approach works similarly in Docker:\n\n```bash\ndocker run -p 5000:5000 \\\n -e SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp \\\n -v \"/path/to/project:/workspace\" \\\n spec-workflow-mcp\n```\n\n资料来源：[README.md:100-110]()\n\n## Security Comparison Table\n\n| Security Feature | Docker CLI Default | Docker Compose | Notes |\n|-----------------|-------------------|----------------|-------|\n| Port Binding | `5000:5000` (exposed) | `127.0.0.1:5000:5000` (localhost) | Compose is more secure |\n| Root Filesystem | Read-write | Read-only (`read_only: true`) | Prevents container escape |\n| Capabilities | Default | Dropped (`cap_drop: ALL`) | Reduces attack surface |\n| Privilege Escalation | Allowed | Blocked (`no-new-privileges`) | Hardens against exploits |\n| Resource Limits | None | CPU/Memory limits | Prevents DoS |\n\n## See Also\n\n- [Configuration Guide](../docs/CONFIGURATION.md) - Additional configuration options\n- [Interfaces Guide](../docs/INTERFACES.md) - Dashboard and VSCode extension details\n- [Development Guide](../docs/DEVELOPMENT.md) - Local development setup\n- [Troubleshooting](../docs/TROUBLESHOOTING.md) - Common issues and solutions\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Pimzino/spec-workflow-mcp.\n\nProject:\n- Name: spec-workflow-mcp\n- Repository: https://github.com/Pimzino/spec-workflow-mcp\n- Summary: Spec Workflow MCP\n- Host target: mcp_host, claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Spec Workflow MCP\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Spec Workflow MCP\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n2. project-structure: Project Structure. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-server: MCP Server Implementation. Produce one small intermediate artifact and wait for confirmation.\n5. spec-management: Spec Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- src/tools/index.ts\n- src/prompts/index.ts\n- vscode-extension/package.json\n- containers/docker-compose.yml\n- src/server.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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" }