{
"canonical_name": "Fission-AI/OpenSpec",
"compilation_id": "pack_4043815702904c74a024ddd6f879f894",
"created_at": "2026-05-13T10:53:16.682530+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 `npm install -g @fission-ai/openspec@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": "npm install -g @fission-ai/openspec@latest",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_5fca58814d86463394995ec6a159ed26"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_2402bf5c472be4371984b8f412cc63c7",
"canonical_name": "Fission-AI/OpenSpec",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Fission-AI/OpenSpec",
"slug": "openspec",
"source_packet_id": "phit_57ee38eceb074f479dd359d04c2cbc29",
"source_validation_id": "dval_bf038cb8d2444b7e9b33261fa07cd526"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 3320,
"github_stars": 47431,
"one_liner_en": "Spec-driven development (SDD) for AI coding assistants.",
"one_liner_zh": "Spec-driven development (SDD) for AI coding assistants.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:coding, development, test"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "OpenSpec",
"title_zh": "OpenSpec 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "TDD Workflow",
"label_zh": "TDD 工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-tdd-workflow",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_57ee38eceb074f479dd359d04c2cbc29",
"page_model": {
"artifacts": {
"artifact_slug": "openspec",
"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": "npm install -g @fission-ai/openspec@latest",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/Fission-AI/OpenSpec#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"TDD 工作流",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Spec-driven development (SDD) for AI coding assistants."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：open:sync messed up my spec.md files",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：First steps don't work",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Profiles, Pi & Kiro Support",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_cb21ca0230d94a0daf4eb6cf43c4a361 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.2.0 - Profiles, Pi & Kiro Support",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.0 - New Tool Integrations",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_382a148d0b88420396bb7da33461ab12 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.3.0 - New Tool Integrations",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.3.1 - Path & Telemetry Fixes",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Incomplete artifacts marked as \"done\" after workflow interruption",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：OpenCode sync missing",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.22.0 - Project Configuration",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0 - The OPSX Release",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | 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:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 59,
"forks": 3320,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 47431
},
"source_url": "https://github.com/Fission-AI/OpenSpec",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Spec-driven development (SDD) for AI coding assistants.",
"title": "OpenSpec 能力包",
"trial_prompt": "# OpenSpec - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 OpenSpec 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Spec-driven development (SDD) for AI coding assistants. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：OpenSpec概述。围绕“OpenSpec概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与初始化。围绕“安装与初始化”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-change-workflow：变更工作流。围绕“变更工作流”模拟一次用户任务，不展示安装或运行结果。\n5. page-artifact-graph：工件图系统。围绕“工件图系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“OpenSpec概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与初始化”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-change-workflow\n输入：用户提供的“变更工作流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-artifact-graph\n输入：用户提供的“工件图系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“OpenSpec概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与初始化”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-change-workflow：Step 4 必须围绕“变更工作流”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-artifact-graph：Step 5 必须围绕“工件图系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Fission-AI/OpenSpec\n- https://github.com/Fission-AI/OpenSpec#readme\n- README.md\n- docs/concepts.md\n- docs/getting-started.md\n- docs/installation.md\n- src/core/init.ts\n- src/core/update.ts\n- package.json\n- src/index.ts\n- src/core/index.ts\n- src/core/command-generation/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 OpenSpec 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Protect OpenSpec from AI slop PRs（https://github.com/Fission-AI/OpenSpec/issues/1087）；github/github_issue: open:sync messed up my spec.md files（https://github.com/Fission-AI/OpenSpec/issues/911）；github/github_issue: Incomplete artifacts marked as \"done\" after workflow interruption（https://github.com/Fission-AI/OpenSpec/issues/1084）；github/github_issue: Support schema extension or partial overrides to avoid full shadowing of（https://github.com/Fission-AI/OpenSpec/issues/1074）；github/github_issue: [Feature Request/Suggestion] Extension to package for custom schemas, as（https://github.com/Fission-AI/OpenSpec/issues/1081）；github/github_issue: First steps don't work（https://github.com/Fission-AI/OpenSpec/issues/820）；github/github_issue: OpenCode sync missing（https://github.com/Fission-AI/OpenSpec/issues/1007）；github/github_release: v1.3.1 - Path & Telemetry Fixes（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1）；github/github_release: v1.3.0 - New Tool Integrations（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0）；github/github_release: v1.2.0 - Profiles, Pi & Kiro Support（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0）；github/github_release: v1.1.1 - OpenCode Command Fix（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.1）；github/github_release: v1.1.0 - Cross-Platform Fixes, Nix Improvements（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Protect OpenSpec from AI slop PRs",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1087"
},
{
"kind": "github_issue",
"source": "github",
"title": "open:sync messed up my spec.md files",
"url": "https://github.com/Fission-AI/OpenSpec/issues/911"
},
{
"kind": "github_issue",
"source": "github",
"title": "Incomplete artifacts marked as \"done\" after workflow interruption",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1084"
},
{
"kind": "github_issue",
"source": "github",
"title": "Support schema extension or partial overrides to avoid full shadowing of",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1074"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request/Suggestion] Extension to package for custom schemas, as",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1081"
},
{
"kind": "github_issue",
"source": "github",
"title": "First steps don't work",
"url": "https://github.com/Fission-AI/OpenSpec/issues/820"
},
{
"kind": "github_issue",
"source": "github",
"title": "OpenCode sync missing",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1007"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.1 - Path & Telemetry Fixes",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.0 - New Tool Integrations",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.0 - Profiles, Pi & Kiro Support",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.1.1 - OpenCode Command Fix",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.1.0 - Cross-Platform Fixes, Nix Improvements",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Spec-driven development (SDD) for AI coding assistants.",
"effort": "安装已验证",
"forks": 3320,
"icon": "code",
"name": "OpenSpec 能力包",
"risk": "可发布",
"slug": "openspec",
"stars": 47431,
"tags": [
"知识检索",
"知识库问答",
"TDD 工作流",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/Fission-AI/OpenSpec 项目说明书\n\n生成时间：2026-05-13 10:35:14 UTC\n\n## 目录\n\n- [OpenSpec概述](#page-overview)\n- [安装与初始化](#page-installation)\n- [系统架构](#page-architecture)\n- [核心模块详解](#page-core-modules)\n- [变更工作流](#page-change-workflow)\n- [工件图系统](#page-artifact-graph)\n- [AI工具集成](#page-ai-integration)\n- [CLI命令参考](#page-cli-commands)\n- [工作流模板](#page-workflow-templates)\n- [配置系统](#page-configuration)\n\n\n\n## OpenSpec概述\n\n### 相关页面\n\n相关主题：[安装与初始化](#page-installation), [系统架构](#page-architecture), [变更工作流](#page-change-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-merge-init-experimental/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-merge-init-experimental/design.md)\n- [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n \n\n# OpenSpec概述\n\n## 简介\n\nOpenSpec 是一个轻量级的规范（Specification）管理框架，专为 AI 编程助手设计。其核心目标是**在编写代码之前让人类和 AI 就需求规范达成一致**，从而提高 AI 代码助手的可预测性和可靠性。\n\n资料来源：[README.md:25-30]()\n\n### 设计理念\n\n| 理念 | 说明 |\n|------|------|\n| **Fluid not Rigid** | 灵活而非僵化，随时可更新工件 |\n| **Iterative not Waterfall** | 迭代而非瀑布式开发 |\n| **Easy not Complex** | 简单而非复杂 |\n| **Built for Brownfield not Just Greenfield** | 支持存量项目而非仅支持新项目 |\n| **Scalable** | 从个人项目到企业级均可使用 |\n\n资料来源：[README.md:72-78]()\n\n## 核心架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[用户/AI助手] --> B[OpenSpec CLI]\n B --> C[Change 目录]\n C --> D[proposal.md]\n C --> E[specs/]\n C --> F[design.md]\n C --> G[tasks.md]\n B --> H[Schema 系统]\n H --> I[模板定义]\n H --> J[工件序列]\n```\n\n### 工件类型\n\nOpenSpec 使用结构化的工件（Artifact）来组织变更：\n\n| 工件 | 文件 | 用途 |\n|------|------|------|\n| **Proposal** | `proposal.md` | 说明变更原因和内容 |\n| **Specs** | `specs/*.md` | 需求和场景定义 |\n| **Design** | `design.md` | 技术设计方案（可选） |\n| **Tasks** | `tasks.md` | 实现检查清单 |\n\n资料来源：[README.md:150-165]()\n\n## 工作流程\n\n### 标准工作流\n\n```mermaid\ngraph LR\n A[提出变更] --> B[编写规范]\n B --> C[设计方案]\n C --> D[创建任务]\n D --> E[实施任务]\n E --> F[归档变更]\n```\n\n#### 步骤 1：提出变更\n\n用户通过自然语言或斜杠命令提出变更需求：\n\n```\nYou: /opsx:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n```\n\n资料来源：[README.md:96-105]()\n\n#### 步骤 2：实施任务\n\n规范确认后开始实现：\n\n```\nYou: The specs look good. Let's implement this change.\nAI: I'll work through the tasks in the add-profile-filters change.\n *Implements tasks from openspec/changes/add-profile-filters/tasks.md*\n```\n\n资料来源：[README.md:140-145]()\n\n#### 步骤 3：归档变更\n\n实现完成后归档变更：\n\n```bash\nopenspec archive add-profile-filters --yes\n```\n\n归档后的变更会被移至 `openspec/changes/archive/-/` 目录。\n\n### 实验性工作流 (/opsx)\n\n新版实验性工作流提供更简化的命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:propose` | 创建新变更 |\n| `/opsx:continue` | 继续下一个工件 |\n| `/opsx:ff` | 快进到完成 |\n| `/opsx:verify` | 验证工件 |\n| `/opsx:bulk-archive` | 批量归档 |\n| `/opsx:onboard` | 新项目引导 |\n\n启用方式：`openspec experimental`\n\n资料来源：[README.md:85-92]()\n\n## 支持的工具\n\n### 原生斜杠命令支持\n\n| 工具 | 命令格式 | 配置目录 |\n|------|----------|----------|\n| **Claude Code** | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置支持 |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| **Cline** | Workflows | `.clinerules/workflows/openspec-*.md` |\n| **Kilo Code** | `/openspec-proposal.md` 等 | `.kilocode/workflows/` |\n| **Windsurf** | `/openspec-proposal` 等 | `.windsurf/workflows/` |\n\n资料来源：[README.md:40-70]()\n\n### AGENTS.md 兼容工具\n\n以下工具通过读取 `openspec/AGENTS.md` 自动发现工作流程：\n\n- Amp\n- Jules\n- 其他支持 AGENTS.md 约定的工具\n\n## 安装与配置\n\n### 系统要求\n\n- **Node.js**: >= 20.19.0\n\n资料来源：[README.md:107-108]()\n\n### 安装步骤\n\n#### 方式 A：npm 全局安装\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n验证安装：\n\n```bash\nopenspec --version\n```\n\n#### 方式 B：Nix 安装\n\n```bash\n# 直接运行\nnix run github:Fission-AI/OpenSpec -- init\n\n# 安装到用户 profile\nnix profile install github:Fission-AI/OpenSpec\n```\n\n#### 方式 C：pnpm/yarn/bun\n\nOpenSpec 同时支持 pnpm、yarn、bun 等包管理器。\n\n资料来源：[README.md:110-125]()\n\n### 初始化项目\n\n```bash\ncd your-project\nopenspec init\n```\n\n初始化后会创建基础目录结构：\n\n```\nopenspec/\n├── config.yaml # 项目配置\n├── specs/ # 规范源文件\n│ └── /\n│ └── spec.md\n└── changes/ # 变更目录\n```\n\n## CLI 命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `openspec init` | 初始化 OpenSpec |\n| `openspec list` | 查看活跃变更 |\n| `openspec view` | 交互式仪表板 |\n| `openspec show ` | 显示变更详情 |\n| `openspec validate ` | 检查规范格式 |\n| `openspec archive [--yes]` | 归档完成变更 |\n| `openspec config profile` | 选择工作流配置 |\n| `openspec update` | 更新配置文件 |\n| `openspec experimental` | 启用实验性功能 |\n\n资料来源：[README.md:155-165]()\n\n## 项目配置\n\n### config.yaml 结构\n\n```yaml\ncontext: |\n # 项目上下文信息\n # 将自动注入到所有工件中\n\nrules:\n proposal:\n - 遵循简洁原则\n specs:\n - 使用 WHEN/THEN 格式\n```\n\n### 上下文注入\n\n```bash\nopenspec instructions specs --change my-feature\n```\n\n输出包含：\n\n```markdown\n\n[项目上下文]\n\n\n\n- 特定工件的规则\n\n\n\n[Schema 模板]\n\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md:15-35]()\n\n## 规范格式\n\n### 需求格式\n\n```markdown\n### Requirement: <需求名称>\n系统应该在特定条件下执行特定行为。\n\n#### Scenario: <场景名称>\n- **WHEN** <触发条件>\n- **THEN** <预期结果>\n```\n\n**格式要求**：\n\n- 使用 SHALL/MUST 表示规范性需求\n- 场景标题必须使用 4 个 `#` (`####`)\n- 每个需求必须至少包含一个场景\n\n资料来源：[schemas/spec-driven/schema.yaml:1-25]()\n\n### MODIFIED 需求工作流\n\n修改现有需求时：\n\n1. 在原规范文件中定位需求\n2. 复制完整需求块\n3. 粘贴到 `## MODIFIED Requirements` 下\n4. 编辑以反映新行为\n\n```markdown\n## MODIFIED Requirements\n\n### Requirement: User can export data\nThe system SHALL allow users to export their data in CSV format.\n\n#### Scenario: Successful export\n- **WHEN** user clicks \"Export\" button\n- **THEN** system downloads a CSV file\n```\n\n## 变更目录结构\n\n### AI 创建的文件结构\n\n```\nopenspec/\n├── specs/\n│ └── auth/\n│ └── spec.md # 当前规范（源）\n└── changes/\n └── add-2fa/ # 变更目录\n ├── proposal.md # 变更原因\n ├── tasks.md # 实现检查清单\n ├── design.md # 技术决策（可选）\n └── specs/\n └── auth/\n └── spec.md # 增量规范\n```\n\n资料来源：[README.md:150-165]()\n\n## 遥测与隐私\n\nOpenSpec 收集**匿名使用统计**（可选退出）：\n\n- 仅收集命令名称和版本\n- 不收集参数、路径、内容或 PII\n- CI 环境中自动禁用\n\n**退出方式**：\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# 或\nexport DO_NOT_TRACK=1\n```\n\n## 开发指南\n\n### 本地开发\n\n```bash\n# 安装依赖\npnpm install\n\n# 构建\npnpm run build\n\n# 测试\npnpm test\n\n# 开发 CLI\npnpm run dev\n# 或\npnpm run dev:cli\n\n# 提交规范\ngit commit -m \"type(scope): subject\"\n```\n\n资料来源：[README.md:190-196]()\n\n## 工作空间功能\n\n### 多仓库支持\n\nOpenSpec 支持跨多个仓库的工作空间管理：\n\n```bash\nopenspec workspace explore \n```\n\n### 状态查询\n\n```bash\nopenspec status\nopenspec status --change integrate-docs\n```\n\n输出示例：\n\n```\nChange: integrate-docs\nScope: openspec, landing\nProposal: present\nDesign: present\nTasks: present\nReady for apply: yes/no\n```\n\n状态检查会捕获结构性问题：\n\n- `specs/` 下未知的仓库文件夹\n- 缺失的任务文件\n- 未确认的受影响仓库\n- 缺失的仓库链接或路径\n\n资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md:1-50]()\n\n## 总结\n\nOpenSpec 提供了一个轻量级但结构化的规范管理框架，其核心价值在于：\n\n1. **前置对齐**：在编码前达成共识\n2. **组织化**：每个变更都有独立文件夹\n3. **灵活性**：可随时更新工件，无需僵化的阶段门控\n4. **工具兼容性**：支持 25+ AI 编程助手\n\n无论是个人项目还是企业级开发，OpenSpec 都能帮助团队更高效、更可靠地进行 AI 辅助开发。\n\n---\n\n\n\n## 安装与初始化\n\n### 相关页面\n\n相关主题：[OpenSpec概述](#page-overview), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [src/core/init.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/init.ts)\n- [src/core/update.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/update.ts)\n- [package.json](https://github.com/Fission-AI/OpenSpec/blob/main/package.json)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n \n\n# 安装与初始化\n\n## 概述\n\nOpenSpec 是一个基于 AI 的规范框架，用于在 AI 编码助手项目中建立结构化的变更管理流程。安装与初始化是用户首次使用 OpenSpec 的关键步骤，涉及 CLI 工具安装、项目目录配置、配置文件生成以及与 AI 工具的集成设置。\n\n本章节详细说明 OpenSpec 的各种安装方式、系统要求、初始化流程以及配置选项，帮助用户快速上手并在团队中推广使用。\n\n## 系统要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 20.19.0 | 核心运行时环境 |\n| 包管理器 | npm/pnpm/yarn/bun/nix | 任选其一 |\n| 操作系统 |跨平台 | Linux、macOS、Windows |\n\n资料来源：[README.md:67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 安装方式\n\n### npm 全局安装\n\n通过 npm 将 OpenSpec 安装为全局 CLI 工具：\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n安装完成后验证版本：\n\n```bash\nopenspec --version\n```\n\n资料来源：[README.md:69-75](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### pnpm 安装\n\n```bash\npnpm add -g @fission-ai/openspec\n```\n\n### yarn 安装\n\n```bash\nyarn global add @fission-ai/openspec\n```\n\n### bun 安装\n\n```bash\nbun add -g @fission-ai/openspec\n```\n\n资料来源：[README.md:56](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### Nix 安装（无安装方式）\n\n对于使用 Nix 或 NixOS 的用户，可以直接运行而不安装：\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\n或安装到用户 profile：\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\n或添加到 `flake.nix` 的 inputs 中：\n\n```nix\ninputs.openspec.url = \"github:Fission-AI/OpenSpec\";\n```\n\n资料来源：[README.md:80-91](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 项目初始化流程\n\n### 基本初始化\n\n初始化是创建 OpenSpec 项目结构的核心步骤。在项目根目录下运行：\n\n```bash\ncd your-project\nopenspec init\n```\n\n该命令会创建以下目录结构：\n\n```\nproject-root/\n├── openspec/\n│ ├── config.yaml # 项目配置文件\n│ ├── specs/ # 规范文件目录\n│ │ └── /\n│ │ └── spec.md\n│ ├── AGENTS.md # AI 代理指令文件\n│ └── changes/ # 变更记录目录\n└── .openspec/ # 内部状态目录\n```\n\n### 交互式初始化选项\n\n初始化过程支持多种命令行参数：\n\n| 参数 | 说明 | 使用场景 |\n|------|------|----------|\n| `--yes` | 接受所有默认值，无需交互确认 | 自动化脚本、CI 环境 |\n| `--no-input` | 跳过所有提示，使用命令行参数 | 无人值守安装 |\n| `--force` | 强制覆盖已存在的 OpenSpec 目录 | 重新初始化 |\n| `--dry-run` | 预览将要创建的内容，不实际写入 | 测试配置 |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n\n### 初始化事务机制\n\nOpenSpec 使用原子化目录创建机制，包含事务回滚功能：\n\n```typescript\ninterface InitTransaction {\n createdPaths: string[];\n rollback(): Promise;\n commit(): Promise;\n}\n```\n\n**事务保障**：\n- 如果创建过程中失败，已创建的文件会被回滚清除\n- 防止部分安装导致的脏状态\n- 确保初始化要么完全成功，要么完全回滚\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:28-35](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n\n## 项目配置\n\n### config.yaml 结构\n\n初始化后生成的 `openspec/config.yaml` 是项目的核心配置文件：\n\n```yaml\nschema: spec-driven\ncontext:\n projectName: \"My Project\"\n techStack: []\n conventions: \"\"\nrules: {}\n```\n\n### 配置字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `schema` | string | 使用的 schema 名称，默认为 `spec-driven` |\n| `context.projectName` | string | 项目名称 |\n| `context.techStack` | string[] | 技术栈列表 |\n| `context.conventions` | string | 项目约定和规范 |\n| `rules` | object | 按 artifact 类型定义的规则 |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### 动态指令系统\n\n新版本 OpenSpec 采用三层指令架构：\n\n```mermaid\ngraph TD\n A[用户运行命令] --> B[Context 上下文层]\n A --> C[Rules 规则层]\n A --> D[Template 模板层]\n B --> E[config.yaml 项目背景]\n C --> F[Artifact-specific 约束]\n D --> G[Schema 定义的模板]\n E --> H[CLI 动态组装]\n F --> H\n G --> H\n H --> I[AI 接收实时指令]\n```\n\n**三层职责**：\n\n1. **Context（上下文）**：从 `config.yaml` 读取项目背景信息\n2. **Rules（规则）**：Artifact 特定的约束条件\n3. **Template（模板）**：Schema 定义的输出文件结构\n\n资料来源：[CHANGELOG.md:15-30](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n\n## Schema 管理\n\n### Schema 加载优先级\n\nOpenSpec 按以下顺序查找 Schema：\n\n| 优先级 | 位置 | 说明 |\n|--------|------|------|\n| 1 | `project/openspec/schemas//` | 项目本地自定义 |\n| 2 | `~/.local/share/openspec/schemas//` | 用户级别覆盖 |\n| 3 | `@fission-ai/openspec/schemas//` | 包内置（最低优先级） |\n\n项目本地的 Schema 会覆盖同名的内置 Schema，实现团队定制化。\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n### 查看可用 Schema\n\n```bash\nopenspec schemas\n```\n\n输出示例：\n\n```\nAvailable schemas:\n - spec-driven (built-in)\n - custom-schema (project)\n```\n\n## 更新与维护\n\n### 升级 CLI\n\n```bash\nnpm update -g @fission-ai/openspec\n```\n\n### 更新项目配置\n\n当 OpenSpec 发布新版本或项目结构需要同步时：\n\n```bash\nopenspec update\n```\n\n更新操作会：\n- 刷新 `openspec/AGENTS.md` 文件\n- 更新现有 artifact 模板\n- 清理过时的配置文件\n\n### 切换实验性工作流\n\n新版 OpenSpec 引入了基于 artifact 的实验性工作流：\n\n```bash\nopenspec experimental\n```\n\n实验性工作流提供以下命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:propose` | 创建新的变更提案 |\n| `/opsx:new` | 启动新变更 |\n| `/opsx:continue` | 逐步创建 artifact |\n| `/opsx:ff` | 快速推进变更 |\n| `/opsx:verify` | 验证变更完整性 |\n| `/opsx:bulk-archive` | 批量归档变更 |\n| `/opsx:onboard` | 新成员引导 |\n\n资料来源：[README.md:55-60](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### 配置文件选择\n\n查看当前使用的配置文件类型：\n\n```bash\nopenspec config profile\n```\n\n可选配置文件类型：\n- **旧版配置**：生成 CLAUDE.md、.cursorrules 等工具配置文件\n- **新版配置**：使用 openspec/AGENTS.md 和 config.yaml\n\n资料来源：[README.md:50-55](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 与 AI 工具集成\n\n### 支持的工具类型\n\n| 集成类型 | 工具示例 | 配置方式 |\n|----------|----------|----------|\n| 原生斜杠命令 | Claude Code, CodeBuddy | 内置支持 |\n| 配置文件 | Cursor, Windsurf | 生成 .cursorrules 等 |\n| 工作流文件 | Cline, Kilo Code | 生成 .clinerules 等 |\n\n### 主要支持的 AI 助手\n\n| 工具 | 命令格式 | 配置目录 |\n|------|----------|----------|\n| Claude Code | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置 |\n| Amazon Q Developer | `@openspec-proposal`, `@openspec-apply` | `.amazonq/prompts/` |\n| Cursor | 斜杠命令 | `.cursor/rules/` |\n| CodeBuddy | `/openspec:proposal` | `.codebuddy/commands/` |\n| Cline | 配置文件方式 | `.clinerules/workflows/` |\n\n资料来源：[README.md:99-130](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 安全性与最佳实践\n\n### 安全考量\n\n1. **路径遍历防护**：所有用户提供的路径都经过清理验证\n2. **文件权限检查**：写入前验证目录权限\n3. **现有文件保护**：未使用 `--force` 不会覆盖已有文件\n4. **模板注入防护**：用户输入在模板中被清理\n\n### 遥测数据收集\n\nOpenSpec 默认收集匿名使用统计：\n\n- 仅收集命令名称和版本号\n- 不收集参数、路径、内容或个人信息\n- CI 环境中自动禁用\n\n**禁用遥测**：\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# 或\nexport DO_NOT_TRACK=1\n```\n\n资料来源：[README.md:60-67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 快速入门工作流\n\n```mermaid\ngraph LR\n A[安装 CLI] --> B[初始化项目]\n B --> C[运行 openspec init]\n C --> D[配置 AI 助手]\n D --> E[使用 /opsx:propose 开始]\n E --> F[创建提案]\n F --> G[实现任务]\n G --> H[归档变更]\n```\n\n**标准快速入门步骤**：\n\n1. 安装 OpenSpec：`npm install -g @fission-ai/openspec@latest`\n2. 进入项目目录：`cd your-project`\n3. 初始化：`openspec init`\n4. 向 AI 助手发送指令：`/opsx:propose <你想要构建的功能>`\n\n资料来源：[README.md:68-78](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 常见问题\n\n### Q: Node.js 版本不满足要求\n\n```bash\n# 检查版本\nnode --version\n\n# 使用 nvm 升级\nnvm install 20.19.0\nnvm use 20.19.0\n```\n\n### Q: 初始化失败权限错误\n\n```bash\n# 检查目录权限\nls -la\n\n# 使用 sudo（不推荐）\nsudo openspec init\n```\n\n### Q: 想使用实验性工作流\n\n```bash\nopenspec experimental\n```\n\n### Q: 想要查看所有可用命令\n\n```bash\nopenspec --help\n```\n\n## 贡献开发\n\n如需为 OpenSpec 贡献代码：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Fission-AI/OpenSpec.git\ncd OpenSpec\n\n# 安装依赖\npnpm install\n\n# 构建项目\npnpm run build\n\n# 运行测试\npnpm test\n\n# 本地开发 CLI\npnpm run dev\n# 或\npnpm run dev:cli\n```\n\n提交代码使用 conventional commits 格式：`type(scope): subject`\n\n资料来源：[README.md:145-150](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心模块详解](#page-core-modules), [AI工具集成](#page-ai-integration), [工件图系统](#page-artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n- [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n \n\n# 系统架构\n\n## 概述\n\nOpenSpec 是一个轻量级的规范框架，专为 AI 编程助手设计。其核心目标是让人类开发者和 AI 在编写代码之前先就规范达成共识，从而提高代码质量和项目可预测性。\n\n**技术栈要求：**\n- Node.js 20.19.0 或更高版本\n- 支持 pnpm、yarn、bun、nix 等包管理器\n\n资料来源：[README.md:1]()\n\n## 核心架构分层\n\nOpenSpec 采用分层架构设计，主要分为以下几层：\n\n| 层级 | 职责 | 关键模块 |\n|------|------|----------|\n| CLI 层 | 命令行接口，接收用户指令 | 主入口、命令解析 |\n| 核心层 | 业务逻辑处理 | 模式管理、工件图、模板系统 |\n| 适配层 | 工具集成 | 斜杠命令生成、工具适配器 |\n\n```mermaid\ngraph TD\n A[用户/AI 助手] --> B[CLI 交互层]\n B --> C[核心业务层]\n C --> D[Schema 管理]\n C --> E[工件图引擎]\n C --> F[模板系统]\n D --> G[文件系统]\n E --> G\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]()\n\n## Schema 系统\n\n### Schema 分层结构\n\nOpenSpec 采用三级 Schema 存储策略，优先级从高到低：\n\n```mermaid\ngraph TD\n A[Schema 解析请求] --> B{检查项目目录}\n B -->|存在| C[openspec/schemas/]\n B -->|不存在| D{检查用户目录}\n D -->|存在| E[~/.local/share/openspec/schemas/]\n D -->|不存在| F[npm 包内置 schemas/]\n```\n\n| 层级 | 路径 | 说明 |\n|------|------|------|\n| 项目级 | `/openspec/schemas//` | 项目本地自定义模式 |\n| 用户级 | `~/.local/share/openspec/schemas//` | 用户级别的覆盖配置 |\n| 包级 | `/schemas//` | 包内置默认模式 |\n\n**优先级规则：** 当项目本地 schema 与内置 schema 名称相同时，项目本地版本优先。\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:3]()\n\n### Schema 解析顺序\n\n工件 Schema 的解析遵循明确的优先级顺序：\n\n1. `--schema` CLI 参数（显式覆盖）\n2. `openspec/changes//.openspec.yaml`（变更级别绑定）\n3. `openspec/config.yaml` 的 schema 字段（项目默认）\n4. `\"spec-driven\"`（硬编码回退值）\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:4]()\n\n## 工件图系统\n\n### 工件类型\n\nOpenSpec 定义了标准化工件类型，每个变更包含以下工件：\n\n| 工件 ID | 生成文件 | 依赖 | 说明 |\n|---------|----------|------|------|\n| proposal | proposal.md | 无 | 变更提案和动机 |\n| specs | specs/*.md | proposal | 需求规格说明 |\n| design | design.md | proposal, specs | 技术设计方案 |\n| tasks | tasks.md | specs, design | 实施任务清单 |\n| apply | - | 所有工件 | 应用/执行指令 |\n\n资料来源：[schemas/spec-driven/schema.yaml:1]()\n\n### 工件状态追踪\n\n工件图引擎负责追踪每个工件的状态，状态包括：\n\n- **ready**：可以开始创建\n- **blocked**：等待前置依赖完成\n- **done**：已完成\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n D --> E[apply]\n \n A --> C\n B --> D\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:5]()\n\n### 指令加载机制\n\n指令加载器负责组装动态指令，包含三个层次：\n\n1. **Context（上下文）**：来自 `config.yaml` 的项目背景信息\n2. **Rules（规则）**：工件特定的约束条件\n3. **Template（模板）**：输出文件的实际结构\n\n```typescript\n// 指令组装流程\nlet enrichedInstruction = '';\n\n// 添加上下文（所有工件）\nif (projectConfig?.context) {\n enrichedInstruction += `\\n${projectConfig.context}\\n\\n\\n`;\n}\n\n// 添加规则（仅限匹配的工件）\nconst rulesForArtifact = projectConfig?.rules?.[artifactId];\nif (rulesForArtifact) {\n enrichedInstruction += `\\n${rulesForArtifact.join('\\n')}\\n\\n\\n`;\n}\n\n// 添加原始模板\nenrichedInstruction += `\\n${baseInstructions.template}\\n`;\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1]()\n\n## 命令生成系统\n\n### 斜杠命令架构\n\nOpenSpec 通过适配器模式支持 25+ AI 工具的斜杠命令：\n\n```mermaid\ngraph TD\n A[TemplateManager] --> B[SlashCommandConfigurator]\n B --> C[Claude Code 适配器]\n B --> D[Cursor 适配器]\n B --> E[Codex 适配器]\n B --> F[其他工具适配器...]\n \n C --> G[.claude/commands/openspec/]\n D --> H[.cursor/commands/]\n E --> I[项目配置]\n```\n\n**命令命名约定：**\n- Claude Code：使用命名空间 `/openspec/proposal`、`/openspec/apply`\n- Cursor：使用扁平命名 `/openspec-proposal`\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n### 文件标记规范\n\n斜杠命令文件必须包含特定标记以确保可被正确识别和更新：\n\n```markdown\n---\n# Frontmatter（工具特定配置）\n---\n\n...命令正文内容...\n\n```\n\n**关键规则：**\n- 标记仅包裹 Markdown 正文内容\n- Frontmatter 必须位于标记之前\n- 避免在 YAML 块内插入标记\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n## 模板系统\n\n### 模板存储结构\n\n模板采用 Markdown 格式存储，结构清晰：\n\n```markdown\n---\nchange: \nartifact: \nschema: \noutput: \n---\n\n## Dependencies\n- [x] (依赖列表)\n\n## Next Steps\n下一步操作说明\n\n---\n\n[原始模板内容...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]()\n\n### 模板引擎特点\n\n| 特性 | 说明 |\n|------|------|\n| 无需模板引擎 | 使用简单字符串拼接 |\n| 上下文注入 | 在模板前添加上下文信息 |\n| 清晰分隔 | 保持模板和注入内容的边界 |\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]()\n\n## 工作流系统\n\n### 标准工作流程\n\n```mermaid\ngraph TD\n A[/opsx:propose] --> B[创建提案]\n B --> C[/opsx:continue]\n C --> D[创建 specs]\n D --> E[创建 design]\n E --> F[创建 tasks]\n F --> G[/opsx:apply]\n G --> H[执行任务]\n H --> I[/opsx:archive]\n I --> J[归档到 archive/]\n```\n\n### 动作命令映射\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:explore` | 在提交变更前思考和探索想法 |\n| `/opsx:new` | 开始一个新变更 |\n| `/opsx:continue` | 逐步创建工件（单步式） |\n| `/opsx:propose` | 创建完整的变更结构 |\n| `/opsx:ff` | 快进到下一个待处理的工件 |\n| `/opsx:verify` | 验证变更状态 |\n| `/opsx:bulk-archive` | 批量归档 |\n| `/opsx:onboard` | 新项目引导 |\n| `/opsx:archive` | 归档已完成的工作 |\n\n资料来源：[README.md:1]()\n\n## 项目配置\n\n### config.yaml 结构\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n 项目约定: ...\n\nschema: spec-driven # 默认 schema 名称\n\nrules:\n proposal: # 提案工件规则\n - Include risk assessment\n specs: # 规格工件规则\n - Use Given/When/Then format\n```\n\n### 配置注入格式\n\nOpenSpec 使用 XML 风格的标签进行配置注入：\n\n```xml\n\n技术栈: TypeScript, React\n\n\n\n- Include rollback plan\n\n\n\n## Summary\n...\n\n```\n\n**设计决策：**\n- 使用 XML 标签避免与 Markdown 内容冲突\n- 便于 AI 代理解析结构\n- 与代码库中特殊部分现有模式匹配\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:3]()\n\n## 变更目录结构\n\n每个变更创建独立的文件夹结构：\n\n```\nopenspec/\n├── config.yaml # 项目配置\n├── changes/\n│ ├── /\n│ │ ├── .openspec.yaml # 变更级别 schema 绑定\n│ │ ├── proposal.md # 提案文档\n│ │ ├── specs/ # 规格文档目录\n│ │ │ └── *.md\n│ │ ├── design.md # 设计文档\n│ │ └── tasks.md # 任务清单\n│ └── archive/ # 归档目录\n│ └── YYYY-MM-DD-/\n└── schemas/ # 项目本地 schemas\n └── /\n```\n\n**设计原则：**\n- 每个变更独立存放，职责清晰\n- 归档保留历史版本\n- 镜像 `.github/` 目录结构\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:2]()\n\n## CLI 命令参考\n\n### 核心命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec init` | 初始化项目 |\n| `openspec list` | 列出活跃变更 |\n| `openspec show ` | 显示变更详情 |\n| `openspec view` | 交互式仪表板 |\n| `openspec archive ` | 归档变更 |\n| `openspec config profile` | 配置工作流配置 |\n| `openspec experimental` | 启用实验性功能 |\n| `openspec instructions ` | 获取工件指令 |\n| `openspec schemas` | 管理 schemas |\n\n### Schema 管理命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec schema init ` | 创建新 schema |\n| `openspec schema which` | 显示当前 schema |\n| `openspec schema fork ` | 派生现有 schema |\n\n资料来源：[README.md:1]()\n\n## 安全与验证\n\n### 路径遍历防护\n\n所有用户提供的路径必须经过清理，防止路径遍历攻击。\n\n```typescript\n// 安全检查清单\n- 检查文件写入权限\n- 不使用 --force 标志不覆盖现有文件\n- 清理模板中的用户输入\n```\n\n### 初始化事务处理\n\n```typescript\ninterface InitTransaction {\n createdPaths: string[];\n rollback(): Promise; // 失败时回滚\n commit(): Promise; // 成功时提交\n}\n```\n\n**设计目标：**\n- 防止部分安装\n- 清晰的错误状态\n- 更好的用户体验\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]()\n\n## 扩展性设计\n\n### 社区 Schema\n\nOpenSpec 支持第三方 Schema 包分发，类似于 `github/spec-kit` 的扩展目录模式：\n\n```bash\n# 第三方 Schema 仓库结构\n/\n├── schemas/\n│ └── /\n│ ├── schema.yaml\n│ └── templates/\n└── README.md\n```\n\n### 适配器扩展\n\n新增工具支持只需实现适配器接口：\n\n```typescript\ninterface ToolAdapter {\n getTargets(): Array<{ path: string; kind: 'slash'; id: string }>;\n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n## 贡献指南\n\n| 操作 | 命令 |\n|------|------|\n| 安装依赖 | `pnpm install` |\n| 构建 | `pnpm run build` |\n| 测试 | `pnpm test` |\n| 本地开发 CLI | `pnpm run dev` 或 `pnpm run dev:cli` |\n| 提交规范 | 常规提交格式：`type(scope): subject` |\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 核心模块详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [变更工作流](#page-change-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts)\n- [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts)\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/template.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/template.ts)\n- [src/core/artifact-graph/context.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/context.ts)\n- [src/core/artifact-graph/instructions.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instructions.ts)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n \n\n# 核心模块详解\n\n## 概述\n\nOpenSpec 的核心模块围绕**变更工件图（Artifact Graph）** 构建，提供了从规范定义、工件管理到指令生成的完整技术栈。核心模块采用 TypeScript/Zod 实现类型安全，使用 YAML 定义规范结构，通过模块化设计支持多 schema 扩展。\n\n核心模块的架构设计遵循以下原则：\n\n- **无模板引擎依赖**：使用简单的字符串拼接实现上下文注入\n- **Schema 驱动的资源解析**：支持项目级、用户级、包级三层 Schema 解析顺序\n- **动态状态检测**：基于工件文件存在性自动判断阻塞状态\n- **Zod Schema 验证**：运行时类型检查确保数据完整性\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## 核心模块架构\n\n### 模块目录结构\n\n```\nsrc/core/artifact-graph/\n├── index.ts # 模块导出入口\n├── types.ts # 类型定义（Zod Schema）\n├── schema.ts # Schema YAML 解析器\n├── graph.ts # 工件图与拓扑排序\n├── state.ts # 状态检测逻辑\n├── template.ts # 模板加载器\n├── context.ts # ChangeContext 加载器\n└── instructions.ts # 指令丰富化与格式化\n```\n\n### 核心组件关系图\n\n```mermaid\ngraph TD\n A[Schema.yaml] -->|解析| B[ArtifactGraph]\n B -->|拓扑排序| C[getBuildOrder]\n B -->|状态检测| D[State Detection]\n D --> E{工件状态}\n \n F[Change Context] -->|注入| G[Instructions]\n H[Project Config] -->|上下文| G\n I[Template] -->|内容| G\n \n E -->|done/ready/blocked| J[Status Output]\n G -->|富化指令| K[Agent Output]\n```\n\n## Schema 系统\n\n### Schema 解析层级\n\nOpenSpec 采用三级 Schema 解析顺序，从高优先级到低优先级排列：\n\n| 优先级 | 来源 | 路径 |\n|--------|------|------|\n| 1 (最高) | 项目本地覆盖 | `/openspec/schemas//` |\n| 2 | 用户配置 | `~/.local/share/openspec/schemas//` |\n| 3 (最低) | 包内置 | `/schemas//` |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md]()\n\n### 工件依赖模型\n\n每个 Schema 定义一组工件及其依赖关系：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n template: \"proposal.md\"\n requires: []\n \n - id: specs\n generates: \"specs/*.md\"\n template: \"specs.md\"\n requires:\n - proposal\n \n - id: design\n generates: \"design.md\"\n template: \"design.md\"\n requires:\n - proposal\n - specs\n \n - id: tasks\n generates: \"tasks.md\"\n template: \"tasks.md\"\n requires:\n - specs\n - design\n```\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## 类型系统\n\n### 核心类型定义\n\n`types.ts` 使用 Zod 定义所有类型约束：\n\n```typescript\n// 工件定义 Schema\nconst ArtifactSchema = z.object({\n id: z.string(),\n generates: z.string(),\n template: z.string(),\n requires: z.array(z.string()),\n});\n\n// Schema YAML 主结构\nconst SchemaYamlSchema = z.object({\n name: z.string(),\n version: z.number(),\n artifacts: z.array(ArtifactSchema),\n});\n```\n\n### 运行时状态类型\n\n| 类型名 | 描述 | 结构 |\n|--------|------|------|\n| `CompletedSet` | 已完成工件集合 | `Set` |\n| `BlockedArtifacts` | 阻塞中的工件映射 | `Record` |\n| `ArtifactGraphResult` | 图操作返回结果 | 包含 `graph`、`buildOrder`、`artifacts` |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]()\n\n## 工件图核心\n\n### ArtifactGraph 类\n\n工件图类封装所有图相关操作：\n\n```typescript\nexport class ArtifactGraph {\n // 从 YAML 文件加载\n static fromYaml(path: string): ArtifactGraph;\n \n // 获取拓扑排序后的构建顺序\n getBuildOrder(): string[];\n \n // 获取单个工件定义\n getArtifact(id: string): ArtifactSchema | undefined;\n \n // 列出所有工件\n getAllArtifacts(): ArtifactSchema[];\n}\n```\n\n### 拓扑排序算法\n\n使用 Kahn 算法实现拓扑排序：\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n A --> C[design]\n B --> D[tasks]\n C --> D\n \n E[Kahn排序] --> F[proposal]\n F --> G[specs/design]\n G --> H[tasks]\n```\n\n**排序特性**：\n- 保证依赖永远在被依赖项之前\n- 循环依赖检测：`\"Cyclic dependency detected: A → B → C → A\"`\n- 无环图验证\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]()\n\n## Schema 解析器\n\n### schema.ts 功能\n\n| 功能 | 描述 |\n|------|------|\n| YAML 加载 | 使用 `fs.readFileSync` 读取并 `yaml.parse` |\n| Zod 验证 | `.safeParse()` 验证结构 |\n| 依赖引用验证 | 确保 `requires` 引用有效 artifact ID |\n| 重复 ID 检测 | 拒绝重复的 artifact ID |\n| 循环依赖检测 | 构建依赖图时检测环 |\n\n### 验证规则\n\n```typescript\n// 依赖引用验证伪代码\nfor (const artifact of artifacts) {\n for (const reqId of artifact.requires) {\n if (!artifacts.find(a => a.id === reqId)) {\n throw new Error(`Invalid reference: ${artifact.id} requires ${reqId}`);\n }\n }\n}\n```\n\n## 状态检测系统\n\n### 状态枚举\n\n| 状态 | 含义 | 触发条件 |\n|------|------|----------|\n| `done` | 已完成 | 工件文件存在 |\n| `ready` | 就绪可创建 | 所有依赖均为 `done` |\n| `blocked` | 阻塞 | 至少一个依赖为 `blocked` 或不存在 |\n\n### 状态输出格式\n\n```markdown\n## Change: add-auth (spec-driven)\n\n| Artifact | Status | Output |\n|----------|--------|--------|\n| proposal | done | proposal.md |\n| specs | ready | specs/*.md |\n| design | blocked (needs: proposal) | design.md |\n| tasks | blocked (needs: specs, design) | tasks.md |\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## 指令加载系统\n\n### 指令生成流程\n\n```mermaid\ngraph TD\n A[loadInstructions] --> B[resolveSchema]\n B --> C[loadTemplate]\n C --> D[loadChangeContext]\n D --> E[loadProjectConfig]\n E --> F[injectContext]\n F --> G[injectRules]\n G --> H[formatXML]\n H --> I[返回富化指令]\n```\n\n### 上下文注入格式\n\n```xml\n\nTech stack: TypeScript, React\nProject conventions: ...\n\n\n\n- Use Given/When/Then format for scenarios\n- Reference existing patterns before inventing new ones\n\n\n\n## Summary\n...\n\n```\n\n### 指令丰富化逻辑\n\n| 组件 | 注入位置 | 条件 |\n|------|----------|------|\n| `context` | 所有工件 | `projectConfig.context` 存在 |\n| `rules` | 特定工件 | `projectConfig.rules[artifactId]` 存在 |\n| `template` | 所有工件 | 始终 |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## 包路径解析\n\n### 跨环境路径解析\n\n```typescript\nfunction getPackageSchemasDir(): string {\n const currentFile = fileURLToPath(import.meta.url);\n // 从 src/core/artifact-graph/ 导航到包根目录\n return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');\n}\n```\n\n**设计决策**：\n- 使用 `import.meta.url` 而非硬编码路径\n- 适配 ESM 模块系统\n- 相对路径计算确保包内引用正确\n\n## 项目配置集成\n\n### 配置 Schema 验证\n\n项目配置文件 `openspec/config.yaml` 结构：\n\n```yaml\nschema: spec-driven # 默认 schema\ncontext: | # 注入到所有工件的上下文\n Tech stack: TypeScript\n Database: PostgreSQL\nrules: # 规则（按工件 ID）\n specs:\n - Use Given/When/Then format\n design:\n - Include rollback plan\n```\n\n### Schema 解析优先级\n\n```\n1. --schema CLI 参数 (最高优先级)\n2. .openspec.yaml (change 目录内)\n3. openspec/config.yaml schema 字段\n4. \"spec-driven\" (硬编码默认值)\n```\n\n## Schema 解析器详情\n\n### schema.ts 核心实现\n\n| 功能点 | 实现方式 |\n|--------|----------|\n| YAML 解析 | `yaml.parse(content)` |\n| 类型验证 | Zod `.safeParse()` |\n| 错误处理 | 自定义错误消息 |\n| 文件缓存 | 可选内存缓存 |\n\n### 循环依赖检测算法\n\n```typescript\nfunction detectCycles(artifacts: Artifact[]): string[] | null {\n const visited = new Set();\n const recursionStack = new Set();\n \n for (const artifact of artifacts) {\n if (hasCycle(artifact.id, artifacts, visited, recursionStack)) {\n return buildCyclePath(recursionStack);\n }\n }\n return null;\n}\n```\n\n## 状态检测实现\n\n### state.ts 文件结构\n\n```typescript\n// 状态检测核心逻辑\nexport interface StateDetectionResult {\n completed: CompletedSet;\n blocked: BlockedArtifacts;\n ready: string[];\n}\n\n// 文件存在性检查\nfunction checkArtifactExists(artifact: Artifact, changeDir: string): boolean {\n const path = path.join(changeDir, artifact.generates);\n return fs.existsSync(path);\n}\n```\n\n### 状态计算伪代码\n\n```typescript\nfunction detectState(graph: ArtifactGraph, changeDir: string): StateResult {\n const completed = new Set();\n const blocked: Record = {};\n const ready: string[] = [];\n \n for (const artifact of graph.getAllArtifacts()) {\n if (fileExists(artifact, changeDir)) {\n completed.add(artifact.id);\n } else if (canBuild(artifact, completed)) {\n ready.push(artifact.id);\n } else {\n blocked[artifact.id] = getMissingDeps(artifact, completed);\n }\n }\n \n return { completed, blocked, ready };\n}\n```\n\n## Apply 阶段支持\n\n### ApplyPhase Schema 扩展\n\n```yaml\nartifacts:\n - id: proposal\n # ...\napply:\n requires:\n - proposal\n - specs\n - design\n - tasks\n tracks: progress\n instruction: \"All artifacts complete. Proceed with implementation.\"\n```\n\n### 动态工件检测\n\n与硬编码路径不同，Apply 指令检查逻辑：\n\n```typescript\n// 从 schema 加载要求，而非硬编码\nconst schema = await resolveSchema(schemaName);\nconst applyConfig = schema.apply;\n\n// 动态检查所有要求的工件\nfor (const requiredId of applyConfig.requires) {\n if (!completed.has(requiredId)) {\n return { ready: false, missing: requiredId };\n }\n}\n```\n\n## 最佳实践\n\n### Schema 设计原则\n\n1. **最小依赖**：每个工件只依赖真正需要的前置项\n2. **清晰命名**：artifact ID 使用 kebab-case\n3. **模板分离**：每个 schema 拥有独立的 `templates/` 目录\n4. **版本控制**：schema.yaml 包含 version 字段便于迁移\n\n### 指令注入最佳实践\n\n| 场景 | 推荐做法 |\n|------|----------|\n| 项目级上下文 | 放在 `config.yaml.context` |\n| 工件特定规则 | 使用 `config.yaml.rules[artifactId]` |\n| 变更描述 | 使用 ChangeContext 文件 |\n| 避免冲突 | 使用 XML 标签 `` 而非 Markdown 标题 |\n\n### 错误处理\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| Schema 未找到 | 按优先级继续搜索下一级 |\n| YAML 解析失败 | 显示具体行号和错误 |\n| 循环依赖 | 终止并显示环路径 |\n| 验证失败 | 警告但不阻止操作 |\n\n## 总结\n\nOpenSpec 的核心模块通过**工件图（Artifact Graph）** 这一核心概念，将变更管理抽象为工件的有向无环图（DAG）。配合 Zod 类型系统、YAML Schema 定义和模块化的解析器架构，实现了：\n\n- **声明式规范**：通过 schema.yaml 定义工件结构和依赖\n- **运行时验证**：状态检测确保按序创建工件\n- **灵活扩展**：支持项目级、用户级、包级三层 Schema 定制\n- **上下文感知**：项目配置和变更上下文自动注入到指令中\n\n这套架构既保持了简单性（无模板引擎依赖），又提供了足够的灵活性来支持复杂的团队工作流程。\n\n---\n\n\n\n## 变更工作流\n\n### 相关页面\n\n相关主题：[工件图系统](#page-artifact-graph), [工作流模板](#page-workflow-templates), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/templates/workflows/propose.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/propose.ts)\n- [src/core/templates/workflows/apply-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/apply-change.ts)\n- [src/core/templates/workflows/archive-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts)\n- [src/core/parsers/change-parser.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/parsers/change-parser.ts)\n- [src/core/archive.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/archive.ts)\n- [src/commands/change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/change.ts)\n \n\n# 变更工作流\n\n## 概述\n\n变更工作流（Change Workflow）是 OpenSpec 框架的核心功能，它定义了一套标准化的流程，用于管理项目变更的生命周期。该工作流涵盖从变更提议、规格编写、设计文档、任务规划到实现完成并归档的全过程。\n\nOpenSpec 的变更工作流采用 **提案 → 应用 → 归档** 的三阶段模式，每个阶段都有明确的输入、输出和验收标准，确保人类开发者和 AI 助手之间能够高效协作。\n\n## 工作流架构\n\n### 整体流程图\n\n```mermaid\ngraph TD\n A[开始新变更] --> B{选择工具}\n B --> C[Claude Code]\n B --> D[Cursor]\n B --> E[VS Code]\n B --> F[其他工具]\n \n C --> G[/opsx:propose]\n D --> H[/openspec-proposal]\n E --> I[自然语言请求]\n F --> I\n \n G --> J[创建变更目录]\n H --> J\n I --> J\n \n J --> K[proposal.md]\n K --> L[specs/ 目录]\n L --> M[design.md]\n M --> N[tasks.md]\n N --> O{实现完成?}\n O -->|否| P[继续开发]\n P --> N\n O -->|是| Q[/opsx:archive]\n Q --> R[归档到 archive/]\n R --> S[更新主规格文档]\n \n style G fill:#e1f5fe\n style H fill:#e1f5fe\n style I fill:#fff3e0\n style Q fill:#c8e6c9\n```\n\n### 变更目录结构\n\n每个变更在 `openspec/changes/{change-id}/` 目录下创建完整的工作空间：\n\n| 文件/目录 | 说明 | 必需 |\n|-----------|------|------|\n| `proposal.md` | 变更提案，说明变更原因和目标 | ✓ |\n| `design.md` | 技术设计方案 | 可选 |\n| `tasks.md` | 实现任务清单 | ✓ |\n| `specs/` | 规格变更增量文件 | 可选 |\n\n归档后，变更目录移至 `openspec/changes/archive/{date}-{change-id}/`。\n\n## 提案阶段（Propose）\n\n### 触发方式\n\n不同 AI 工具通过不同的命令触发提案创建：\n\n| 工具类型 | 命令格式 | 说明 |\n|----------|----------|------|\n| Claude Code | `/opsx:propose ` | 使用斜杠命令 |\n| Cursor | `/openspec-proposal ` | 扁平化前缀命名 |\n| 其他工具 | 自然语言请求 | \"创建一个 OpenSpec 提案\" |\n\n### 提案模板内容\n\n提案文件包含以下标准结构：\n\n```yaml\n---\nproposal\ncategory: OpenSpec\ndescription: Scaffold a new OpenSpec change and validate strictly.\n---\n```\n\n模板内容需包含：\n- **Guardrails（防护规则）**：1-2 个澄清问题\n- **Minimal-complexity rules（最小复杂度规则）**\n- **Step list（步骤列表）**：针对提案阶段的操作指令\n- **Pointers（指针）**：指向 `openspec show`、`openspec list` 等命令\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md]()\n\n### 提案生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant AI as AI 助手\n participant CLI as OpenSpec CLI\n \n User->>AI: /opsx:propose add-dark-mode\n AI->>CLI: 解析命令\n CLI->>AI: 返回指令模板\n AI->>AI: 创建变更目录结构\n AI->>AI: 生成 proposal.md\n AI->>AI: 生成 specs/ 目录\n AI->>AI: 生成 design.md\n AI->>AI: 生成 tasks.md\n AI->>User: 变更已创建\n```\n\n## 规格阶段（Specs）\n\n### 规格文件格式\n\n规格文件使用 Markdown 格式，遵循严格的头部层级结构：\n\n```markdown\n## ADDED Requirements\n\n### Requirement: <需求名称>\n<需求描述，使用 SHALL/MUST 描述规范>\n\n#### Scenario: <场景名称>\n- **WHEN** <触发条件>\n- **THEN** <预期结果>\n- **AND** <附加结果>\n```\n\n### 关键格式要求\n\n| 要求 | 说明 | 重要性 |\n|------|------|--------|\n| 需求头部 | 使用 `### Requirement:` | 必须 |\n| 规范语气 | 使用 SHALL/MUST，避免 should/may | 必须 |\n| 场景头部 | 必须使用 `#### Scenario:`（4个#） | 关键 |\n| 场景格式 | 使用 `- **WHEN**` / `- **THEN**` 格式 | 必须 |\n\n> ⚠️ **常见错误**：使用 3 个 `#` 或使用列表格式会导致场景解析失败。\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n### 规格操作类型\n\n规格变更支持以下操作类型：\n\n| 操作 | 说明 | 示例 |\n|------|------|------|\n| `ADDED` | 新增需求 | 添加新功能 |\n| `MODIFIED` | 修改现有需求 | 更改现有行为 |\n| `REMOVED` | 删除需求 | 移除废弃功能 |\n| `RENAMED` | 重命名需求 | 迁移命名 |\n\n### MODIFIED 工作流\n\n修改现有需求时，必须遵循以下步骤：\n\n1. 在 `openspec/specs//spec.md` 中定位现有需求\n2. 复制**完整**的需求块（从 `### Requirement:` 到所有场景）\n3. 粘贴到 `## MODIFIED Requirements` 下并编辑\n4. 确保头部文本完全匹配（忽略空白差异）\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## 应用阶段（Apply）\n\n### 触发方式\n\n| 工具 | 命令格式 |\n|------|----------|\n| Claude Code | `/opsx:apply ` |\n| Cursor | `/openspec-apply ` |\n| 其他 | 自然语言请求 |\n\n### 应用指令生成\n\n应用阶段指令的生成遵循以下流程：\n\n```mermaid\ngraph TD\n A[用户请求应用] --> B[加载变更元数据]\n B --> C[检查 design.md 是否存在]\n C --> D[检查 tasks.md 是否存在]\n D --> E[构建上下文文件列表]\n E --> F[生成应用指令]\n F --> G[返回指令给 AI]\n G --> H[AI 执行任务]\n H --> I[标记完成的任务]\n```\n\n### 应用指令结构\n\n```typescript\n{\n instruction: \"执行以下任务的指令\",\n contextFiles: [\n \"proposal.md\",\n \"design.md\",\n \"tasks.md\",\n \"specs/**/*.md\"\n ],\n tracks: [\"Task 1.1 ✓\", \"Task 1.2 ✓\", ...]\n}\n```\n\n## 归档阶段（Archive）\n\n### 归档流程\n\n```mermaid\ngraph LR\n A[openspec/changes/{id}/] --> B[验证所有任务完成]\n B --> C{验证通过?}\n C -->|是| D[移动到 archive/]\n C -->|否| E[返回错误信息]\n D --> F[按日期命名子目录]\n D --> G[更新主规格文档]\n```\n\n### 归档命令\n\n```bash\n# 标准归档\nopenspec archive \n\n# 非交互式归档（跳过确认）\nopenspec archive --yes\n\n# 缩写形式\nopenspec archive -y\n```\n\n### 带参数的归档\n\n部分工具支持传入变更 ID 参数：\n\n```bash\n/openspec:archive \n```\n\n参数处理逻辑：\n1. 验证 `$ARGUMENTS` 占位符是否存在\n2. 解析传入的变更 ID\n3. 使用 `openspec list` 验证变更存在\n4. 执行归档操作\n\n资料来源：[openspec/changes/archive/2025-10-22-add-archive-command-arguments/tasks.md]()\n\n### 归档后操作\n\n归档完成后，系统自动执行以下操作：\n\n1. 将变更目录移动到 `openspec/changes/archive/{YYYY-MM-DD}-{change-id}/`\n2. 从规格增量文件中提取变更，更新到主规格文档\n3. 从任务列表中移除已完成的变更\n\n## CLI 命令参考\n\n### 变更管理命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec list` | 列出活跃的变更 |\n| `openspec show ` | 显示变更详情 |\n| `openspec validate ` | 验证规格格式和结构 |\n| `openspec archive [--yes]` | 归档完成的变更 |\n\n### 查看命令选项\n\n```bash\n# 查看变更详情\nopenspec show \n\n# JSON 格式输出（仅显示增量）\nopenspec show --json --deltas-only\n\n# 严格验证模式\nopenspec validate --strict\n```\n\n## 工具支持矩阵\n\n| 工具 | 提案命令 | 应用命令 | 归档命令 |\n|------|----------|----------|----------|\n| Claude Code | `/opsx:propose` | `/opsx:apply` | `/opsx:archive` |\n| Cursor | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` |\n| Roo Code | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` |\n| CodeBuddy | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` |\n| Windsurf | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` |\n| Kilo Code | `/openspec-proposal.md` | `/openspec-apply.md` | `/openspec-archive.md` |\n| 其他 | 自然语言 | 自然语言 | 自然语言 |\n\n> 注：Kilo Code 会自动发现团队工作流，命令需保存为 `.kilocode/workflows/` 下的 Markdown 文件。\n\n## 最佳实践\n\n### 1. 变更命名规范\n\n- 使用 kebab-case 格式：`add-dark-mode`、`fix-auth-bug`\n- 简洁明了，反映变更本质\n- 避免使用 `new-feature`、`update-1` 等模糊名称\n\n### 2. 规格编写要点\n\n- 每个需求必须有至少一个场景\n- 场景描述需具体、可测试\n- 使用 Gherkin 语法（Given/When/Then）保持一致性\n\n### 3. 任务拆解建议\n\n- 任务粒度适中，便于进度跟踪\n- 包含验证步骤，确保实现正确\n- 标记依赖关系，合理安排执行顺序\n\n### 4. 变更周期管理\n\n```mermaid\ngraph TD\n A[提案] --> B{规格评审}\n B -->|通过| C[设计]\n B -->|不通过| A\n C --> D{设计评审}\n D -->|通过| E[任务规划]\n D -->|不通过| C\n E --> F[实现]\n F --> G{测试}\n G -->|通过| H[归档]\n G -->|失败| F\n```\n\n## 常见问题排查\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| \"变更必须有至少一个增量\" | `specs/` 目录不存在或为空 | 确保 `specs/` 目录包含 `.md` 文件 |\n| \"需求必须有至少一个场景\" | 场景格式错误 | 检查使用 `#### Scenario:`（4个#） |\n| 场景解析静默失败 | 头部格式不正确 | 使用 `openspec show --json --deltas-only` 调试 |\n| 归档失败 | 存在未完成任务 | 完成所有任务或使用 `--skip-checks` |\n\n---\n\n\n\n## 工件图系统\n\n### 相关页面\n\n相关主题：[变更工作流](#page-change-workflow), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts)\n- [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts)\n- [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts)\n \n\n# 工件图系统\n\n## 概述\n\n工件图系统（Artifact Graph System）是 OpenSpec 的核心子系统，负责管理软件开发变更中的工件（Artifact）及其依赖关系。该系统通过图结构建模工件的创建顺序、依赖状态和生成路径，实现动态指令生成和状态追踪。\n\n**核心能力：**\n\n- 将工件定义为节点，依赖关系定义为边，构建有向无环图（DAG）\n- 基于拓扑排序确定工件创建顺序\n- 实时检测工件完成状态（已完成、就绪、阻塞）\n- 动态加载模式匹配的指令模板\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 架构设计\n\n### 系统分层\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n CLI[CLI 命令]\n Workflow[工作流模板]\n end\n \n subgraph \"核心层\"\n IG[工件图]\n IL[指令加载器]\n ST[状态追踪]\n RS[模式解析]\n end\n \n subgraph \"数据层\"\n YAML[Schema YAML]\n TMPL[模板文件]\n CFG[项目配置]\n end\n \n CLI --> IG\n CLI --> IL\n Workflow --> IL\n IG --> IL\n IG --> ST\n IG --> RS\n RS --> YAML\n IL --> TMPL\n IL --> CFG\n \n style IG fill:#e1f5fe\n style IL fill:#e8f5e8\n style ST fill:#fff3e0\n style RS fill:#f3e5f5\n```\n\n### 目录结构\n\n```\nsrc/core/artifact-graph/\n├── index.ts # 公共导出\n├── types.ts # Zod 类型定义和接口\n├── graph.ts # ArtifactGraph 类\n├── state.ts # 状态检测逻辑\n├── resolver.ts # Schema 解析（全局 → 内置）\n├── instruction-loader.ts # 模板加载与指令丰富\n├── outputs.ts # 输出格式化\n└── schemas/ # 内置模式定义\n ├── spec-driven.yaml\n └── tdd.yaml\n```\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 核心类型定义\n\n### Schema 结构\n\n模式（Schema）是定义工件及其依赖关系的 YAML 配置文件，位于 `src/core/artifact-graph/types.ts`。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `name` | string | 模式名称 |\n| `version` | number | 模式版本 |\n| `description` | string | 模式描述 |\n| `artifacts` | Artifact[] | 工件定义数组 |\n| `apply` | ApplyPhase | 可选的 apply 阶段配置 |\n\n**Artifact 对象结构：**\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `id` | string | 工件唯一标识符 |\n| `generates` | string | 生成的文件路径 |\n| `template` | string | 模板文件路径（相对） |\n| `requires` | string[] | 前置依赖工件 ID |\n| `description` | string | 工件描述 |\n\n资料来源：[src/core/artifact-graph/types.ts](src/core/artifact-graph/types.ts)\n\n### 运行时状态类型\n\n```typescript\n// 已完成的工件 ID 集合\ntype CompletedSet = Set;\n\n// 阻塞工件：artifact → 未满足的依赖列表\ntype BlockedArtifacts = Map;\n\n// 工件图结果\ninterface ArtifactGraphResult {\n completed: string[]; // 已完成的工件\n ready: string[]; // 就绪可创建的工件\n blocked: BlockedArtifacts; // 阻塞的工件及其原因\n buildOrder: string[]; // 构建顺序（拓扑排序结果）\n}\n```\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 工件图类\n\n`ArtifactGraph` 类是系统的核心组件，位于 `src/core/artifact-graph/graph.ts`。\n\n### 主要方法\n\n| 方法 | 返回值 | 功能描述 |\n|------|--------|----------|\n| `fromYaml(path)` | `ArtifactGraph` | 从 Schema YAML 文件加载工件图 |\n| `getBuildOrder()` | `string[]` | 获取拓扑排序后的工件顺序 |\n| `getArtifact(id)` | `Artifact \\| undefined` | 获取单个工件定义 |\n| `getAllArtifacts()` | `Artifact[]` | 获取所有工件定义 |\n\n### 拓扑排序算法\n\n系统使用 **Kahn算法**（Kahn's Algorithm）进行拓扑排序：\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n \n style A fill:#4caf50\n style B fill:#ffeb3b\n style C fill:#ffeb3b\n style D fill:#ff9800\n```\n\n**算法特点：**\n\n- 自动检测循环依赖，检测到时抛出明确错误\n- 错误格式：`Cyclic dependency detected: A → B → C → A`\n- 返回的顺序保证所有依赖在依赖者之前\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n---\n\n## 状态检测\n\n状态检测模块负责判断工件的就绪状态，位于 `src/core/artifact-graph/state.ts`。\n\n### 检测逻辑\n\n```mermaid\ngraph TD\n START[检查工件] --> IS_BLOCKED{是否有未完成的依赖?}\n IS_BLOCKED -->|是| MISSING[标记为 blocked]\n IS_BLOCKED -->|否| HAS_OUTPUT{输出文件是否存在?}\n HAS_OUTPUT -->|是| COMPLETED[标记为 completed]\n HAS_OUTPUT -->|否| READY[标记为 ready]\n \n style COMPLETED fill:#4caf50\n style READY fill:#ffeb3b\n style MISSING fill:#ff9800\n```\n\n### 状态类型\n\n| 状态 | 描述 | 条件 |\n|------|------|------|\n| `completed` | 已完成 | 所有前置依赖完成且输出文件存在 |\n| `ready` | 就绪 | 所有前置依赖完成但输出文件不存在 |\n| `blocked` | 阻塞 | 存在未完成的前置依赖 |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n---\n\n## Schema 解析\n\nSchema 解析器负责定位和加载模式定义，位于 `src/core/artifact-graph/resolver.ts`。\n\n### 解析路径优先级\n\n```mermaid\ngraph TD\n REQ[请求加载 Schema] --> GLOBAL{检查全局覆盖}\n GLOBAL -->|存在| GLOBAL_LOAD[加载全局 Schema]\n GLOBAL -->|不存在| BUILTIN{检查内置 Schema}\n BUILTIN -->|存在| BUILTIN_LOAD[加载内置 Schema]\n BUILTIN -->|不存在| ERROR[抛出错误]\n \n GLOBAL_LOAD --> RESULT[返回 Schema]\n BUILTIN_LOAD --> RESULT\n \n style GLOBAL_LOAD fill:#e1f5fe\n style BUILTIN_LOAD fill:#e8f5e8\n style ERROR fill:#ffcdd2\n```\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `${XDG_DATA_HOME}/openspec/schemas//schema.yaml` | 用户全局覆盖 |\n| 2 | `/schemas//schema.yaml` | 包内置 Schema |\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md](openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md)\n\n### 内置 Schema 示例\n\n**spec-driven 模式**（默认）：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n requires: []\n - id: specs\n generates: \"specs.md\"\n requires: [proposal]\n - id: design\n generates: \"design.md\"\n requires: [specs]\n - id: tasks\n generates: \"tasks.md\"\n requires: [specs, design]\napply:\n requires: [tasks]\n instruction: \"Read context files, work through pending tasks\"\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](schemas/spec-driven/schema.yaml)\n\n---\n\n## 指令加载器\n\n指令加载器负责将工件模板与变更上下文结合，生成最终指令，位于 `src/core/artifact-graph/instruction-loader.ts`。\n\n### 变更上下文\n\n```typescript\ninterface ChangeContext {\n changeName: string; // 变更名称\n changeDir: string; // 变更目录路径\n schemaName: string; // 使用的模式名\n graph: ArtifactGraph; // 工件图实例\n completed: CompletedSet; // 已完成工件集合\n}\n```\n\n### 指令结构\n\n```mermaid\ngraph LR\n TMPL[模板] --> CTX[上下文注入]\n RULES[规则] --> RULES_INJ[规则注入]\n CTX --> OUTPUT[最终指令]\n RULES_INJ --> OUTPUT\n \n style CTX fill:#e8f5e8\n style OUTPUT fill:#e1f5fe\n```\n\n### 输出格式\n\n生成的指令包含以下 XML 标签结构：\n\n| 标签 | 内容 | 说明 |\n|------|------|------|\n| `` | 工件元信息 | 包含 id, change, schema 属性 |\n| `` | 任务描述 | 要创建的工件说明 |\n| `` | 项目上下文 | 来自 config.yaml 的背景信息 |\n| `` | 约束规则 | 特定工件的行为约束 |\n| `` | 模板内容 | Schema 中定义的文件结构 |\n\n资料来源：[src/commands/workflow/instructions.ts](src/commands/workflow/instructions.ts)\n\n---\n\n## 项目配置集成\n\n工件图系统与项目配置（`config.yaml`）集成，支持上下文注入和规则约束。\n\n### 配置结构\n\n```yaml\nschema: spec-driven # 默认使用的 Schema\ncontext: | # 项目背景信息\n - 技术栈：Node.js, TypeScript\n - 代码风格：Google TypeScript Style Guide\nrules: # 工件特定规则\n specs:\n - 使用 Given/When/Then 格式编写场景\n - 每个需求必须有至少一个测试场景\n design:\n - 包含 API 接口设计\n - 包含数据库 schema 变更\n```\n\n### 规则验证\n\n规则在指令加载时进行惰性验证，确保：\n\n- 规则引用的工件 ID 存在于 Schema 中\n- 警告信息仅显示一次（会话级缓存）\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](openspec/changes/archive/2026-02-17-project-config/design.md)\n\n---\n\n## 使用示例\n\n### 1. 加载工件图\n\n```typescript\nimport { ArtifactGraph } from './core/artifact-graph';\n\nconst graph = ArtifactGraph.fromYaml('/path/to/spec-driven/schema.yaml');\nconst buildOrder = graph.getBuildOrder();\n// ['proposal', 'specs', 'design', 'tasks']\n```\n\n### 2. 获取工件状态\n\n```typescript\nimport { detectCompleted } from './core/artifact-graph/state';\n\nconst completed = detectCompleted(\n graph,\n '/path/to/change',\n ['proposal', 'specs'] // 已完成的工件\n);\n// 返回: { completed: [...], ready: [...], blocked: {...} }\n```\n\n### 3. 生成指令\n\n```typescript\nimport { loadInstructions } from './core/artifact-graph/instruction-loader';\n\nconst instructions = loadInstructions('add-auth', 'specs');\n// 输出包含 , , 的完整指令\n```\n\n---\n\n## 设计决策\n\n### 决策 1：纯函数优于类\n\n遵循 `resolver.ts` 和 `state.ts` 的模式，使用纯函数和简单接口：\n\n- 优点：无状态、易测试、无隐藏依赖\n- 缺点：需要显式传递上下文\n\n### 决策 2：无模板引擎\n\n采用简单的字符串拼接进行上下文注入：\n\n- 优点：无外部依赖、行为可预测\n- 缺点：复杂模板逻辑受限\n\n### 决策 3：Schema 目录化\n\nSchema 采用自包含目录结构：\n\n```\nschemas//\n├── schema.yaml\n└── templates/\n └── *.md\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md](openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md)\n\n---\n\n## 相关文档\n\n- [Getting Started](docs/getting-started.md) - 快速入门指南\n- [Workflows](docs/workflows.md) - 工作流程组合与模式\n- [Customization](docs/customization.md) - 自定义配置与社区 Schema\n\n---\n\n\n\n## AI工具集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n- [openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n \n\n# AI工具集成\n\n## 概述\n\nOpenSpec 的 AI工具集成系统是一套统一框架，用于将 OpenSpec 工作流程（提案、应用、归档）与多种 AI 编码助手深度整合。通过为每个受支持的 AI 工具生成专用的斜杠命令（Slash Commands）文件，开发者可以在任何主流 AI 辅助编程环境中使用一致的操作方式发起和管理 OpenSpec 变更。\n\n核心设计原则：\n\n- **模板驱动**：命令体内容从共享模板生成，保持跨工具一致性\n- **最小适配**：每个工具只需添加特有的 frontmatter 和路径配置\n- **幂等性**：支持重复初始化而不破坏现有文件\n- **按需更新**：更新时仅刷新已存在的文件，不创建新的\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 支持的AI工具\n\nOpenSpec 目前支持以下 AI 编程助手的斜杠命令集成：\n\n| 工具 | 命令前缀 | 存储目录 | 命令示例 |\n|------|---------|---------|---------|\n| **Amazon Q Developer** | `@openspec-` | `.amazonq/prompts/` | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` |\n| **Antigravity** | `/openspec-` | `.agent/workflows/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| **Auggie (Augment CLI)** | `/openspec-` | `.augment/commands/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| **Claude Code** | `/openspec:` | `.claude/commands/openspec/` | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |\n| **Cline** | 斜杠命令 | `.clinerules/workflows/` | `openspec-proposal.md`, `openspec-apply.md`, `openspec-archive.md` |\n| **CodeBuddy Code (CLI)** | `/openspec:` | `.codebuddy/commands/` | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |\n| **Cursor** | `/openspec-` | `.cursor/commands/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n\n资料来源：[README.md:支持AI工具列表](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 核心架构\n\n### 组件结构\n\n```\nsrc/core/command-generation/\n├── registry.ts # 命令注册表，定义所有工具的配置\n├── generator.ts # 命令文件生成器\n├── types.ts # 类型定义\n└── adapters/\n └── index.ts # 工具特定适配器\n```\n\n架构采用适配器模式，每个 AI 工具对应一个适配器，负责处理：\n\n- 目录结构创建\n- 文件命名规则\n- Frontmatter 格式\n- 命令体包装\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:设计理念](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[openspec init] --> B{检测已安装工具}\n B -->|Claude Code| C[生成 .claude/commands/openspec/]\n B -->|Cursor| D[生成 .cursor/commands/]\n B -->|其他工具| E[生成对应目录结构]\n C --> F[复制共享模板]\n D --> F\n E --> F\n F --> G[添加工具特定 frontmatter]\n G --> H[验证标记位置]\n H --> I[初始化完成]\n \n J[openspec update] --> K[扫描已存在的命令文件]\n K --> L{每个已存在文件}\n L -->|更新| M[仅刷新标记内内容]\n L -->|跳过| N[不创建新文件]\n M --> O[报告更新结果]\n```\n\n## 命令文件格式\n\n### 标准结构\n\n每个斜杠命令文件遵循统一的 Markdown 格式：\n\n```markdown\n---\n# Frontmatter（工具特定）\nname: proposal\ndescription: 创建 OpenSpec 提案\ncategory: OpenSpec\n---\n\n...命令体内容...\n\n```\n\n关键规则：\n\n- **标记位置**：`` 和 `` 必须包裹 Markdown 正文内容\n- **禁止嵌套**：标记不得出现在 frontmatter 内部，以免 YAML 解析错误\n- **内容来源**：命令体从共享模板提取，保持所有工具一致\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:标记位置](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### 工具命名约定\n\n| 工具 | 文件命名 | 命令内命名空间 |\n|------|---------|--------------|\n| Claude Code | `proposal.md` | `/openspec:proposal` |\n| Cursor | `openspec-proposal.md` | `/openspec-proposal` |\n| Amazon Q | `openspec-proposal.md` | `@openspec-proposal` |\n| Codex | `openspec-proposal.md` | - (全局目录) |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:命令命名与UX](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 实现细节\n\n### 模板管理\n\n模板系统通过 `TemplateManager` 集中管理所有命令模板：\n\n```typescript\n// 模板提取逻辑\nfunction extractTemplateSnippets(source: string): string {\n // 从 openspec/README.md 提取权威片段\n return conciseInstructions;\n}\n```\n\n模板包含：\n\n1. **守卫规则**：1-2 个澄清问题；遵循最小复杂度规则；Node 项目使用 `pnpm`\n2. **步骤列表**：根据工作流阶段（proposal/apply/archive）定制的步骤\n3. **验证命令**：`openspec validate` 用于严格检查\n4. **故障排除**：指向 `openspec show`、`openspec list` 的指针\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:模板内容](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### SlashCommandConfigurator\n\n核心配置器类管理每个工具的多文件生成：\n\n```typescript\ninterface SlashCommandConfigurator {\n getTargets(): Array<{\n path: string;\n kind: 'slash';\n id: string;\n }>;\n \n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:设计理念](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 幂等性与创建规则\n\n### Init 操作\n\n| 行为 | 说明 |\n|------|-----|\n| 首次运行 | 为选定工具创建全部命令文件 |\n| 后续运行 | 对已存在的文件执行无操作（幂等） |\n| 目录创建 | 由 configurator 负责创建嵌套目录 |\n\n### Update 操作\n\n| 行为 | 说明 |\n|------|-----|\n| 已存在文件 | 仅刷新标记内内容 |\n| 不存在文件 | 跳过，不创建新文件 |\n| 日志报告 | 按文件报告更新结果 |\n\n```mermaid\ngraph LR\n A[update 命令] --> B{文件存在?}\n B -->|是| C[刷新 OPENSPEC 标记内容]\n B -->|否| D[跳过]\n C --> E[记录更新成功]\n D --> F[记录跳过]\n E --> G[显示汇总]\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:幂等性与创建规则](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 测试策略\n\n### 金快照测试\n\n为每个工具的生成文件维护金快照：\n\n```typescript\ndescribe('Slash Command Generation', () => {\n it('generates correct frontmatter + markers + body for Claude Code', () => {\n const result = generateForTool('claude-code');\n expect(result).toMatchSnapshot();\n });\n});\n```\n\n### 标记位置验证\n\n```typescript\ndescribe('Marker Placement', () => {\n it('never places markers inside frontmatter', () => {\n const content = generateForTool('cursor');\n const frontmatterEnd = content.indexOf('---', 4);\n const markerStart = content.indexOf('');\n \n expect(markerStart).toBeGreaterThan(frontmatterEnd);\n });\n});\n```\n\n测试覆盖场景：\n\n- 缺失标记的恢复行为\n- 重复标记的处理\n- 各种 frontmatter 格式兼容\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:测试策略](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 使用方式\n\n### 初始化集成\n\n```bash\n# 在项目根目录运行\nopenspec init\n\n# 或指定特定工具\nopenspec init --tools claude,cursor\n```\n\n### 更新命令文件\n\n```bash\n# 刷新所有已存在的斜杠命令\nopenspec update\n\n# 刷新特定工具\nopenspec update --tools codex\n```\n\n### 手动使用\n\n```text\nYou: /openspec:proposal add-user-auth\n\nAI: I'll create an OpenSpec proposal for adding user authentication.\n *Creates: openspec/changes/add-user-auth/proposal.md*\n```\n\n资料来源：[README.md:命令参考](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 社区扩展\n\n第三方可以通过独立仓库分发自定义 schema 包，类似于 [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) 的方式扩展 OpenSpec。\n\n查看[自定义文档](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md#community-schemas)了解社区 schema 目录。\n\n## 相关文档\n\n- [开始使用](docs/getting-started.md) - 首次使用指南\n- [工作流](docs/workflows.md) - 组合与模式\n- [命令参考](docs/commands.md) - 斜杠命令与技能\n- [CLI 参考](docs/cli.md) - 终端命令完整参考\n- [支持工具](docs/supported-tools.md) - 工具集成与安装路径\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[工作流模板](#page-workflow-templates), [安装与初始化](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/cli/index.ts)\n- [src/commands/change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/change.ts)\n- [src/commands/spec.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/spec.ts)\n- [src/commands/validate.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/validate.ts)\n- [src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n- [src/commands/completion.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/completion.ts)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n \n\n# CLI命令参考\n\n## 概述\n\nOpenSpec CLI 是项目的核心命令行工具，提供了一套完整的命令集用于管理项目规格、工作流程和变更过程。CLI 采用模块化架构设计，通过子命令模式组织功能，支持交互式操作和脚本化使用两种模式。\n\nCLI 的主要职责包括：\n\n- 初始化 OpenSpec 项目结构\n- 创建和管理变更（changes）\n- 验证规格文档格式和结构\n- 生成和应用 AI 指令\n- 管理配置和方案（schemas）\n\n## 命令架构\n\nOpenSpec CLI 采用树形命令结构，通过 `openspec` 主命令调用各类子命令和子组。以下是完整的命令层次结构：\n\n```mermaid\ngraph TD\n A[openspec] --> B[change 子命令组]\n A --> C[spec 子命令组]\n A --> D[config 子命令组]\n A --> E[schema 子命令组]\n A --> F[validate]\n A --> F2[view]\n A --> F3[list]\n A --> F4[instructions]\n A --> F5[status]\n A --> F6[next]\n A --> F7[templates]\n A --> F8[init]\n A --> F9[update]\n A --> F10[archive]\n A --> F11[completion]\n \n B --> B1[new]\n B --> B2[show]\n B --> B3[list]\n B --> B4[archive]\n \n C --> C1[show]\n C --> C2[list]\n C --> C3[validate]\n \n D --> D1[show]\n D --> D2[init]\n \n E --> E1[init]\n E --> E2[list]\n E --> E3[which]\n E --> E4[fork]\n```\n\n## 全局选项\n\n所有 OpenSpec 命令支持以下全局选项：\n\n| 选项 | 简写 | 描述 | 默认值 |\n|------|------|------|--------|\n| `--help` | `-h` | 显示帮助信息 | - |\n| `--version` | `-V` | 显示版本号 | - |\n| `--json` | - | 以 JSON 格式输出结果 | `false` |\n| `--no-color` | - | 禁用彩色输出 | `false` |\n| `--cwd ` | - | 指定工作目录 | 当前目录 |\n\n## 变更管理命令\n\n变更（Change）是 OpenSpec 工作流程的核心概念，每个变更代表一个需要实现的功能或修复。\n\n### change new - 创建新变更\n\n创建新的变更目录和基础文件结构。\n\n```bash\nopenspec change new [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | 变更名称，使用 kebab-case 格式 |\n\n**可选参数：**\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定使用的 schema，默认使用 `openspec/config.yaml` 中的配置 |\n| `--yes` / `-y` | 跳过确认提示 |\n| `--no-input` | 非交互模式 |\n\n**示例：**\n\n```bash\n# 创建新变更\nopenspec change new add-dark-mode\n\n# 指定 schema\nopenspec change new add-auth --schema tdd\n\n# 非交互模式\nopenspec change new fix-login-bug --yes\n```\n\n创建完成后会生成以下文件结构：\n\n```\nopenspec/changes//\n├── proposal.md # 变更提案\n├── specs/ # 规格文档目录\n├── design.md # 技术设计方案\n├── tasks.md # 实现任务清单\n└── .openspec.yaml # 变更元数据\n```\n\n### change show - 查看变更详情\n\n显示指定变更的详细信息，包括各制品的状态和内容。\n\n```bash\nopenspec change show [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--artifacts` | 仅显示制品列表 |\n| `--details` | 显示完整内容 |\n\n### change list - 列出所有变更\n\n列出所有活跃的变更（未归档）。\n\n```bash\nopenspec change list [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n| `--archived` | 显示已归档的变更 |\n\n### change archive - 归档变更\n\n将完成的变更移动到归档目录。\n\n```bash\nopenspec change archive [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--yes` / `-y` | 跳过确认提示 |\n\n归档后的变更会被移动到 `openspec/changes/archive/` 目录。\n\n## 制品工作流命令\n\n制品（Artifact）是 OpenSpec 方案定义的核心产物，每个制品有独立的状态和依赖关系。\n\n### status - 查看制品状态\n\n显示变更中所有制品的状态和依赖关系。\n\n```bash\nopenspec status [options]\n```\n\n**输出格式示例：**\n\n| 制品 | 状态 | 输出路径 |\n|------|------|----------|\n| proposal | ✅ done | proposal.md |\n| specs | ✅ ready | specs/*.md |\n| design | 🔒 blocked | design.md |\n| tasks | 🔒 blocked | tasks.md |\n\n**状态说明：**\n\n- `done` - 制品已完成\n- `ready` - 制品可以开始\n- `blocked` - 等待依赖制品完成\n\n### next - 查看下一个可执行制品\n\n显示当前可以开始工作的制品列表。\n\n```bash\nopenspec next [options]\n```\n\n### instructions - 获取 AI 指令\n\n为指定制品生成 AI 助手指令。\n\n```bash\nopenspec instructions --change [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | 制品名称（如 proposal, specs, design, tasks） |\n\n| 选项 | 描述 |\n|------|------|\n| `--change ` | 变更名称（必需） |\n| `--context` | 包含上下文信息 |\n| `--rules` | 包含规则信息 |\n\n**输出示例：**\n\n```xml\n\nTech stack: TypeScript, React\n\n\n\n- Use Given/When/Then format for scenarios\n- Reference existing patterns before inventing new ones\n\n\n\n[Schema's template content]\n\n```\n\n### templates - 查看模板\n\n显示指定制品的模板内容。\n\n```bash\nopenspec templates [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定 schema |\n\n## 规格命令\n\n规格（Spec）命令用于管理和验证项目规格文档。\n\n### spec show - 显示规格\n\n显示指定规格文档的内容。\n\n```bash\nopenspec spec show [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n\n### spec list - 列出规格\n\n列出所有已定义的规格。\n\n```bash\nopenspec spec list [options]\n```\n\n### spec validate - 验证规格\n\n验证规格文档的格式和结构。\n\n```bash\nopenspec spec validate [spec-name] [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--strict` | 严格模式检查 |\n\n## 配置命令\n\n配置命令用于管理项目级配置。\n\n### config show - 显示配置\n\n显示当前项目的 OpenSpec 配置。\n\n```bash\nopenspec config show [options]\n```\n\n### config init - 初始化配置\n\n创建项目配置文件。\n\n```bash\nopenspec config init [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 设置默认 schema |\n| `--context ` | 设置项目上下文 |\n| `--yes` / `-y` | 跳过确认提示 |\n\n## Schema 管理命令\n\nSchema 定义了制品的结构、工作流程和验证规则。\n\n### schema init - 创建新 Schema\n\n创建新的 schema 方案。\n\n```bash\nopenspec schema init [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | Schema 名称（kebab-case 格式） |\n\n| 选项 | 描述 |\n|------|------|\n| `--description ` | Schema 描述 |\n| `--artifacts ` | 制品列表（逗号分隔） |\n| `--default` | 设置为默认 schema |\n| `--force` | 强制覆盖 |\n\n**示例：**\n\n```bash\n# 交互式创建\nopenspec schema init my-schema\n\n# 非交互式创建\nopenspec schema init tdd --description \"Test-driven development workflow\" --artifacts \"proposal,specs,tests,design,tasks\" --default\n```\n\n### schema list - 列出 Schema\n\n列出所有可用的 schema。\n\n```bash\nopenspec schema list [options]\n```\n\n### schema which - 显示当前 Schema\n\n显示当前变更或项目使用的 schema。\n\n```bash\nopenspec schema which [change-name] [options]\n```\n\n### schema fork - 派生 Schema\n\n从现有 schema 派生新的 schema。\n\n```bash\nopenspec schema fork --name [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--name ` | 新 schema 名称（必需） |\n| `--destination ` | 自定义输出路径 |\n| `--force` | 强制覆盖 |\n\n## 项目命令\n\n### init - 初始化项目\n\n在当前目录初始化 OpenSpec 项目结构。\n\n```bash\nopenspec init [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定默认 schema |\n| `--skip-git` | 跳过 git 初始化 |\n| `--yes` / `-y` | 跳过确认提示 |\n\n初始化后生成的文件结构：\n\n```\n├── openspec/\n│ ├── config.yaml # 项目配置\n│ ├── specs/ # 规格目录\n│ │ └── / # 能力子目录\n│ │ └── spec.md\n│ └── changes/ # 变更目录\n│ └── archive/ # 归档目录\n├── AGENTS.md # AI 助手说明\n└── CLAUDE.md # Claude Code 集成\n```\n\n### view - 可视化仪表板\n\n启动交互式命令行仪表板查看项目状态。\n\n```bash\nopenspec view [options]\n```\n\n### list - 列出变更\n\n显示所有活跃变更的概览。\n\n```bash\nopenspec list [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n\n### archive - 归档变更\n\n归档指定的变更。\n\n```bash\nopenspec archive [options]\n```\n\n### validate - 验证变更\n\n验证变更文档的格式和结构。\n\n```bash\nopenspec validate [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--strict` | 严格模式 |\n\n### update - 更新配置\n\n刷新 AI 工具的斜杠命令配置文件。\n\n```bash\nopenspec update [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--tools ` | 指定要更新的工具（逗号分隔） |\n\n## Shell 补全\n\n生成 shell 补全脚本以支持命令自动补全。\n\n```bash\nopenspec completion [options]\n```\n\n| 参数 | 支持的 Shell |\n|------|-------------|\n| `` | bash, zsh, fish, powershell |\n\n**安装示例：**\n\n```bash\n# Bash\nopenspec completion bash >> ~/.bashrc\n\n# Zsh\nopenspec completion zsh >> ~/.zshrc\n\n# Fish\nopenspec completion fish > ~/.config/fish/completions/openspec.fish\n```\n\n## 工作流程示例\n\n### 完整变更工作流程\n\n```mermaid\ngraph LR\n A[1. openspec change new
add-login-feature] --> B[2. 创建制品]\n B --> C[3. openspec instructions
proposal --change
add-login-feature]\n C --> D[4. AI 生成 proposal.md]\n D --> E[5. openspec instructions
specs --change
add-login-feature]\n E --> F[6. AI 生成 specs]\n F --> G[7. openspec instructions
design --change
add-login-feature]\n G --> H[8. AI 生成 design.md]\n H --> I[9. openspec instructions
tasks --change
add-login-feature]\n I --> J[10. AI 生成 tasks.md]\n J --> K[11. openspec archive
add-login-feature]\n```\n\n### Schema 创建工作流程\n\n```bash\n# 1. 创建新 schema\nopenspec schema init tdd \\\n --description \"Test-driven development workflow\" \\\n --artifacts \"proposal,specs,tests,design,tasks\" \\\n --default\n\n# 2. 在新变更中使用\nopenspec change new feature-x --schema tdd\n\n# 3. 派生自定义 schema\nopenspec schema fork tdd --name my-tdd\n```\n\n## 错误处理\n\nCLI 命令可能返回以下常见错误：\n\n| 错误代码 | 描述 | 解决方案 |\n|---------|------|----------|\n| `ENOENT` | 变更不存在 | 检查变更名称，使用 `openspec list` 查看可用变更 |\n| `EEXIST` | 文件已存在 | 使用 `--force` 选项或删除现有文件 |\n| `EINVALID_NAME` | 无效的变更/Schema 名称 | 使用 kebab-case 格式 |\n| `ENO_SCHEMA` | Schema 不存在 | 检查 schema 名称，使用 `openspec schema list` |\n\n## 资料来源\n\n- 命令架构设计：README.md\n- 变更管理命令：openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md\n- Schema 管理：openspec/changes/archive/2026-02-17-schema-management-cli/tasks.md\n- 配置系统：openspec/changes/archive/2026-02-17-project-config/design.md\n- 制品工作流：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md\n\n---\n\n\n\n## 工作流模板\n\n### 相关页面\n\n相关主题：[变更工作流](#page-change-workflow), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/templates/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/index.ts)\n- [src/core/templates/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/types.ts)\n- [src/core/templates/workflows/propose.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/propose.ts)\n- [src/core/templates/workflows/apply-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/apply-change.ts)\n- [src/core/templates/workflows/continue-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/continue-change.ts)\n- [src/core/templates/workflows/ff-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/ff-change.ts)\n- [src/core/templates/workflows/verify-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/verify-change.ts)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n \n\n# 工作流模板\n\n## 概述\n\n工作流模板是 OpenSpec 框架中用于标准化 AI 代理与用户之间交互的核心组件。它们定义了从项目构思到实现完成的完整开发周期中的各个阶段指导。OpenSpec 采用**流体而非僵化**的哲学，工作流模板允许团队在任何阶段灵活更新产物，无需严格的阶段门控。\n\n工作流模板系统的主要作用包括：\n\n- **标准化交互模式**：为 AI 代理提供一致的指令格式和执行步骤\n- **阶段引导**：将复杂项目分解为可管理的阶段（提议、规格说明、设计、任务、实现、验证）\n- **工具集成**：支持 20+ AI 助手通过斜杠命令进行交互\n- **工件驱动**：每个变更（change）拥有独立的文件夹，包含提议、规格说明、设计和任务\n\n资料来源：[docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n\n## 工作流类型\n\nOpenSpec 定义了六种核心工作流类型，每种工作流对应项目开发周期的不同阶段：\n\n| 工作流类型 | 用途 | 触发方式 |\n|------------|------|----------|\n| `propose` | 创建新功能的提议 | `/opsx:propose` |\n| `apply` | 开始实现已批准的变更 | `/opsx:apply` |\n| `continue` | 继续进行中的工作 | `/opsx:continue` |\n| `ff` | 快速跟进当前任务 | `/opsx:ff` |\n| `verify` | 验证实现是否符合规格 | `/opsx:verify` |\n| `bulk-archive` | 批量归档已完成的变更 | `/opsx:bulk-archive` |\n| `onboard` | 新成员入门引导 | `/opsx:onboard` |\n\n资料来源：[src/core/templates/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/index.ts)\n\n## 工作流执行流程\n\n### 标准开发周期\n\n```mermaid\ngraph TD\n A[用户发起需求] --> B[Propose 工作流]\n B --> C[创建变更文件夹]\n C --> D[生成 Proposal]\n D --> E[用户确认提议]\n E --> F[Apply 工作流]\n F --> G[规格说明 & 设计]\n G --> H[Continue 工作流]\n H --> I[任务执行]\n I --> J[Verify 工作流]\n J --> K{验证通过?}\n K -->|是| L[归档变更]\n K -->|否| H\n L --> M[项目更新完成]\n```\n\n### 工作流切换流程\n\n```mermaid\nstateDiagram-v2\n [*] --> Propose: 用户输入需求\n Propose --> Apply: 规格确认\n Apply --> Continue: 开始实现\n Continue --> Verify: 任务完成\n Verify --> Continue: 需要修改\n Verify --> Archive: 验证通过\n Archive --> Propose: 新需求\n```\n\n资料来源：[docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n\n## 提议工作流 (Propose)\n\n提议工作流是项目开发的起点，用于在编写任何代码之前对齐需求。\n\n### 执行步骤\n\n提议工作流包含以下标准步骤：\n\n1. **理解需求**：AI 代理确认理解用户的需求描述\n2. **澄清问题**：如有必要，提出 1-2 个澄清性问题\n3. **遵循复杂度规则**：遵循最小复杂度原则，使用 `pnpm` 作为包管理器\n4. **创建变更结构**：创建 `openspec/changes//` 目录\n5. **生成提议文件**：创建 `proposal.md` 文档\n6. **验证**：运行验证命令确保结构正确\n7. **确认**：等待用户确认后再继续\n\n### 提议文件格式\n\n提议文件包含以下标准结构：\n\n```markdown\n---\nchange: \ncategory: \ndescription: <简短描述>\n---\n\n[提议内容...]\n\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 应用工作流 (Apply)\n\n应用工作流在提议被批准后触发，用于准备实现阶段。\n\n### 模式选择\n\nOpenSpec 支持两种应用模式：\n\n| 模式 | 命令 | 说明 |\n|------|------|------|\n| 精简模式 | `/opsx:propose` | 仅包含提议工作流 |\n| 扩展模式 | `/opsx:new` | 包含完整工作流（propose, apply, continue, ff, verify） |\n\n### 执行流程\n\n1. **加载变更**：读取已批准的提议\n2. **解析规格**：加载关联的规格说明文档\n3. **构建上下文**：生成实施指令，包含：\n - 项目上下文信息\n - 特定工件规则\n - 模板内容\n4. **提供下一步指导**：列出可执行的任务\n\n### Schema 感知\n\n应用工作流采用 Schema 感知的指令生成方式，从 schema 定义中读取 `apply.requires` 来确定必需存在的工件，并动态检查工件存在性。\n\n资料来源：[openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md)\n\n## 继续工作流 (Continue)\n\n继续工作流用于在实现过程中继续工作，适用于任务中断后的恢复或增量开发。\n\n### 使用场景\n\n- 长时间任务的中断恢复\n- 团队成员接手他人工作\n- 跨会话的连续开发\n\n### 指令结构\n\n```typescript\ninterface ContinueInstructions {\n change: string;\n artifact: string | null;\n schema: string;\n output: string;\n instruction: string;\n}\n```\n\n资料来源：[src/core/templates/workflows/continue-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/continue-change.ts)\n\n## 快速跟进工作流 (Fast Forward)\n\n快速跟进工作流旨在加速当前任务的执行，适用于明确的短期目标。\n\n### 设计原则\n\n- **简单直接**：跳过不必要的确认步骤\n- **目标导向**：专注于当前任务的完成\n- **上下文保持**：维护之前的工作上下文\n\n## 验证工作流 (Verify)\n\n验证工作流用于确认实现是否符合规格说明。\n\n### 验证内容\n\n| 验证项 | 说明 |\n|--------|------|\n| 工件完整性 | 所有必需的规格文档是否存在 |\n| 场景覆盖 | 每个需求是否有对应的场景 |\n| 实现一致性 | 代码实现是否与规格描述匹配 |\n| 格式规范 | 文档格式是否符合要求 |\n\n### 验证规则\n\n规格说明中的关键格式要求：\n\n- 每个需求使用 `### Requirement: ` 标记\n- 使用 SHALL/MUST 表示规范性要求（避免 should/may）\n- 每个场景使用 `#### Scenario: ` 格式\n- 场景必须使用**精确的四个井号**（`####`），使用三个井号或项目符号将静默失败\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## 模板数据结构\n\n### 核心类型定义\n\n```typescript\ninterface WorkflowTemplate {\n id: WorkflowType;\n name: string;\n description: string;\n instruction: string;\n nextSteps?: string[];\n}\n\ninterface WorkflowContext {\n change: string;\n artifact?: string;\n schema: string;\n output: string;\n}\n```\n\n### 指令格式\n\n工作流生成的指令采用 XML 风格标签包裹的格式：\n\n```xml\n\n[项目上下文信息]\n\n\n\n- 规则1\n- 规则2\n\n\n\n[模板内容]\n\n```\n\n**Context 部分**：注入项目级上下文，适用于所有工件\n\n**Rules 部分**：仅注入匹配当前工件类型的规则\n\n**Template 部分**：原始模板内容\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## 工件与工作流关系\n\n### Schema 驱动的工件定义\n\nOpenSpec 使用 Schema YAML 定义工件及其依赖关系：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: proposal.md\n requires: []\n \n - id: specs\n generates: specs/*.md\n requires: [proposal]\n \n - id: design\n generates: design.md\n requires: [proposal]\n \n - id: tasks\n generates: tasks.md\n requires: [specs, design]\n```\n\n### 工件状态检测\n\n```mermaid\ngraph LR\n A[检查工件文件] --> B{文件存在?}\n B -->|是| C[状态: done]\n B -->|否| D{依赖满足?}\n D -->|是| E[状态: ready]\n D -->|否| F[状态: blocked]\n```\n\n工件状态类型：\n\n| 状态 | 含义 | 条件 |\n|------|------|------|\n| `done` | 已完成 | 对应文件存在 |\n| `ready` | 就绪 | 依赖项已满足，文件待创建 |\n| `blocked` | 阻塞 | 依赖项未满足 |\n| `in_progress` | 进行中 | 文件存在但未完成 |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n## 配置与扩展\n\n### 项目配置\n\n工作流模板通过 `openspec/config.yaml` 进行项目级配置：\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n \nrules:\n specs:\n - Use Given/When/Then format\n design:\n - Include rollback plan\n \nschema: spec-driven\n```\n\n### Schema 存储位置\n\nOpenSpec 支持三级 Schema 存储：\n\n1. **项目本地**：`openspec/schemas//`\n2. **用户覆盖**：`~/.local/share/openspec/schemas//`\n3. **内置包**：`node_modules/@fission-ai/openspec/schemas//`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n## CLI 命令参考\n\n### 工作流相关命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec init` | 初始化项目配置 |\n| `openspec update` | 刷新产物文件 |\n| `openspec list` | 列出活跃变更 |\n| `openspec view` | 交互式仪表板 |\n| `openspec show ` | 显示变更详情 |\n| `openspec config profile` | 选择工作流配置文件 |\n| `openspec experimental` | 启用实验性工作流 |\n\n### 斜杠命令\n\n支持斜杠命令的工具（Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode）可直接使用：\n\n```\n/opsx:propose \n/opsx:apply \n/opsx:continue\n/opsx:ff\n/opsx:verify\n/opsx:bulk-archive\n/opsx:onboard\n```\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 最佳实践\n\n### 工作流选择指南\n\n1. **新功能开发**：使用 `propose` → `apply` → `continue` → `verify` 完整流程\n2. **小改动**：使用精简模式，直接从提议到实现\n3. **验证阶段**：在每次提交前运行 `verify` 工作流\n4. **归档管理**：完成变更后使用 `bulk-archive` 清理旧变更\n\n### 模板定制建议\n\n- 保持模板简洁，避免过度指令\n- 在 `config.yaml` 中定义项目级规则\n- 使用 Schema 定制工件类型和依赖关系\n- 定期归档完成的变更以保持仓库整洁\n\n## 总结\n\n工作流模板是 OpenSpec 框架的核心抽象，它将项目开发的复杂过程分解为可管理、可重复的阶段。通过工件驱动的架构和灵活的模板系统，团队可以保持对项目需求和实现的一致理解，同时支持与多种 AI 工具的无缝集成。工作流模板的流体设计确保团队能够根据项目需求灵活调整，而非被僵化的流程所束缚。\n\n---\n\n\n\n## 配置系统\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n- [src/core/global-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/global-config.ts)\n- [src/core/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts)\n- [src/core/config-schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config-schema.ts)\n- [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n- [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n- [openspec/config.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/config.yaml)\n \n\n# 配置系统\n\nOpenSpec 的配置系统为团队提供了统一的项目级配置管理能力，支持 schema 选择、上下文注入、规则定制等功能。该系统通过 `openspec/config.yaml` 文件集中管理配置，使所有成员自动获得一致的开发指南和规范要求。\n\n## 系统架构\n\n配置系统采用分层架构设计，区分全局配置与项目配置两个层级。全局配置位于用户主目录的固定位置，用于存储用户级别的偏好设置；项目配置则位于每个仓库的 `openspec/config.yaml`，用于定义团队共识的开发规范。\n\n```mermaid\ngraph TD\n A[CLI 命令] --> B{配置解析层}\n B --> C[全局配置
~/.config/openspec/config.yaml]\n B --> D[项目配置
openspec/config.yaml]\n B --> E[变更元数据
.openspec.yaml]\n B --> F[CLI 参数]\n \n C --> G[Schema 解析器]\n D --> G\n E --> G\n F --> G\n \n G --> H[Instruction Loader]\n H --> I[上下文注入
<context>]\n H --> J[规则注入
<rules>]\n H --> K[模板输出
<template>]\n```\n\n## 配置类型\n\n### 全局配置\n\n全局配置存储在用户主目录的 OpenSpec 配置目录中，适用于用户个人的偏好设置。当前实现中，全局配置主要用于用户级别的路径和默认行为管理。\n\n```typescript\n// 资料来源：src/core/global-config.ts\nexport function getGlobalConfigPath(): string {\n const home = os.homedir();\n return path.join(home, '.config', 'openspec', 'config.yaml');\n}\n```\n\n### 项目配置\n\n项目配置通过 `openspec/config.yaml` 文件管理，是配置系统的核心组成部分。该文件定义了项目使用的 schema、上下文信息、以及针对不同 artifact 的规则。\n\n```yaml\n# 资料来源：openspec/config.yaml\nschema: spec-driven\ncontext: |\n Tech stack: TypeScript, React, Node.js\n Team conventions: PR requires 2 approvals\n\nrules:\n proposal:\n - Include impact analysis\n - Reference related issues\n specs:\n - Use Given/When/Then format\n - Every requirement needs scenarios\n```\n\n## Schema 解析机制\n\n### 解析优先级\n\nOpenSpec 采用明确的优先级顺序解析 schema，确保最具体的配置优先生效：\n\n```mermaid\ngraph LR\n A[1. CLI --schema 参数] -->|最高优先级| Z[最终 Schema]\n B[2. 变更元数据
.openspec.yaml] -->|次高| Z\n C[3. 项目配置
openspec/config.yaml] -->|项目默认| Z\n D[4. 硬编码默认值
spec-driven] -->|最低优先级| Z\n```\n\n1. **CLI 参数**：`--schema ` 显式指定的 schema 拥有最高优先级\n2. **变更元数据**：每个变更目录下的 `.openspec.yaml` 中的 schema 字段\n3. **项目配置**：`openspec/config.yaml` 中定义的 schema 作为项目默认值\n4. **硬编码默认值**：若以上均未指定，使用 `spec-driven` 作为 fallback\n\n```typescript\n// 资料来源：src/core/project-config.ts\nexport function resolveSchemaForChange(\n changeName: string,\n cliSchema?: string\n): string {\n // 1. CLI flag wins\n if (cliSchema) {\n return cliSchema;\n }\n\n // 2. Change metadata (.openspec.yaml)\n const metadata = readChangeMetadata(changeName);\n if (metadata?.schema) {\n return metadata.schema;\n }\n\n // 3. Project config\n const projectConfig = readProjectConfig();\n if (projectConfig?.schema) {\n return projectConfig.schema;\n }\n\n // 4. Hardcoded default\n return 'spec-driven';\n}\n```\n\n### Schema 存储位置\n\nSchema 文件可从三个位置加载，优先级依次递减：\n\n| 位置 | 路径 | 用途 |\n|------|------|------|\n| 项目本地 | `/openspec/schemas//` | 团队自定义 schema |\n| 用户覆盖 | `~/.local/share/openspec/schemas//` | 用户个性化调整 |\n| 包内置 | `/schemas//` | 框架自带 schema |\n\n```mermaid\ngraph TD\n A[Schema 解析请求] --> B{查找项目本地}\n B -->|存在| C[使用项目本地版本]\n B -->|不存在| D{查找用户覆盖}\n D -->|存在| E[使用用户覆盖版本]\n D -->|不存在| F{查找包内置}\n F -->|存在| G[使用包内置版本]\n F -->|不存在| H[错误：Schema 不存在]\n```\n\n**冲突处理原则**：若项目本地 schema 与内置 schema 名称相同，项目本地版本会覆盖（shadow）内置版本，这是有意为之的设计，允许团队自定义内置行为同时保持命名一致性。\n\n## 上下文与规则注入\n\n### 注入格式\n\n配置系统使用 XML 风格标签将上下文和规则注入到生成的 artifacts 中：\n\n```xml\n\n[项目上下文内容]\n\n\n\n- [规则1]\n- [规则2]\n\n\n\n[原始模板内容]\n\n```\n\n这种格式选择基于以下考虑：清晰的边界分隔符避免与 Markdown 内容冲突，便于 AI Agent 解析结构，同时保持良好的可读性。\n\n### 上下文注入（Context）\n\n上下文信息会自动添加到**所有 artifacts** 的说明中，用于向 AI 提供项目级背景知识：\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React, Node.js\n API conventions: RESTful, JWT auth\n Team size: 5 developers\n```\n\n生成的 artifacts 会包含：\n\n```xml\n\nTech stack: TypeScript, React, Node.js\nAPI conventions: RESTful, JWT auth\nTeam size: 5 developers\n\n\n\n## Summary\n...\n\n```\n\n### 规则注入（Rules）\n\n规则配置针对**特定 artifact 类型**生效，仅当加载对应 artifact 的说明时才会注入：\n\n```yaml\nrules:\n proposal:\n - Include impact analysis\n - Reference related issues\n specs:\n - Use Given/When/Then format\n - Every requirement needs scenarios\n design:\n - Include rollback plan\n```\n\n```bash\n# 获取 specs artifact 的说明（包含 rules）\nopenspec instructions specs --change my-feature\n# 输出包含 、 和 \n\n# 获取 design artifact 的说明（不包含 rules）\nopenspec instructions design --change my-feature\n# 输出包含 和 ，无 \n```\n\n### 规则验证\n\n规则配置中的 artifact ID 会进行懒加载验证，验证时机在 instruction 加载时而非 config 加载时，这样可以避免循环依赖并提供更好的用户体验。\n\n```typescript\n// 资料来源：openspec/changes/archive/2026-02-17-project-config/design.md\n// 验证时机选择理由：\n// 1. Schema 在 config 加载时未知（循环依赖）\n// 2. 用户实际使用功能时显示警告更友好\n// 3. 警告信息按会话缓存避免重复提示\n```\n\n## 配置验证\n\n### Schema 名称验证\n\n系统会验证配置中引用的 schema 名称是否有效：\n\n```typescript\n// 资料来源：src/core/project-config.ts\nexport function validateProjectConfig(config: ProjectConfig): ValidationResult {\n // ... 验证逻辑\n \n const allSchemas = [...builtIn, ...projectLocal];\n if (config.schema && !allSchemas.includes(config.schema)) {\n return {\n valid: false,\n error: `Invalid schema: ${config.schema}`,\n hint: `Built-in: ${builtIn.join(', ')}\\nProject-local: ${projectLocal.join(', ')}`\n };\n }\n}\n```\n\n### 错误消息格式\n\n验证失败时的错误消息包含以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| `valid` | 验证是否通过 |\n| `error` | 具体错误描述 |\n| `hint` | 修复建议和可用选项列表 |\n\n```json\n{\n \"valid\": false,\n \"error\": \"Invalid schema: custom-schema\",\n \"hint\": \"Available schemas:\\n Built-in: spec-driven, tdd\\n Project-local: (none found)\\n\\nFix: Edit openspec/config.yaml and change 'schema: custom-schema' to a valid schema name\"\n}\n```\n\n## 团队协作\n\n### 共享配置\n\n配置文件的协作流程如下：\n\n```bash\n# 提交配置到版本控制\ngit add openspec/config.yaml\ngit commit -m \"Add project config with context and rules\"\n\n# 团队成员自动获得相同的上下文和规则\n```\n\n所有团队成员克隆仓库后会立即获得相同的项目上下文和规范要求，无需手动同步或口头传达。\n\n### 配置迁移\n\n旧的 `openspec/project.md` 文件不会自动删除，系统会提示用户手动迁移内容到 `config.yaml` 的 `context:` 字段：\n\n```\nopenspec/project.md still exists - migrate content to config.yaml's context: field, then delete\n```\n\n手动迁移的原因：\n- `project.md` 可能包含用户编写的详细文档\n- 自动压缩为 `context` 字段需要 LLM 协助\n- 避免意外丢失有价值的内容\n\n## 命令行集成\n\n配置系统与 CLI 命令深度集成：\n\n| 命令 | 配置影响 |\n|------|----------|\n| `openspec init` | 创建初始 `config.yaml` |\n| `openspec instructions ` | 使用 config 中的 context 和 rules |\n| `openspec create ` | 使用 config 中的 schema |\n| `openspec validate` | 验证 config 的 schema 是否有效 |\n\n```bash\n# 使用项目配置的 schema 创建变更\nopenspec create add-auth\n\n# 使用显式 schema 覆盖项目配置\nopenspec create add-auth --schema tdd\n\n# 验证配置有效性\nopenspec validate\n```\n\n## 最佳实践\n\n### 配置组织建议\n\n1. **保持 context 简洁**：context 字段应保持简洁精炼，避免冗长的说明文字\n2. **规则按 artifact 分类**：将规则按对应的 artifact 类型组织，便于理解和维护\n3. **使用具体场景描述**：规则应描述具体场景而非抽象原则\n\n### 示例配置\n\n```yaml\n# openspec/config.yaml\nschema: spec-driven\n\ncontext: |\n Tech stack: TypeScript, React 18, Node.js 20\n API: RESTful with JWT authentication\n Testing: Vitest + React Testing Library\n Deployment: Docker, Kubernetes\n\nrules:\n proposal:\n - Include estimated effort (hours)\n - Reference related issues or PRs\n specs:\n - Use Given/When/Then format\n - Minimum one scenario per requirement\n - Reference existing patterns before inventing new ones\n design:\n - Include error handling strategy\n - Document API contracts with examples\n```\n\n## 相关资源\n\n- [自定义文档](docs/customization.md) - 包含社区 schema 和扩展配置\n- [Schema 开发指南](openspec/changes/archive/2026-02-17-project-local-schemas/design.md) - 如何创建项目本地 schema\n- [项目配置提案](openspec/changes/archive/2026-02-17-project-config/proposal.md) - 配置系统设计背景\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Fission-AI/OpenSpec\n\n摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas。\n\n## 1. 配置坑 · 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 维护坑 · 来源证据：open:sync messed up my spec.md files\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：First steps don't work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v1.2.0 - Profiles, Pi & Kiro Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Profiles, Pi & Kiro Support\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cb21ca0230d94a0daf4eb6cf43c4a361 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v1.3.0 - New Tool Integrations\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.0 - New Tool Integrations\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_382a148d0b88420396bb7da33461ab12 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：OpenCode sync missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：v0.22.0 - Project Configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：v1.0.0 - The OPSX Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\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:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 运行坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在安全注意事项\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:1032459340 | https://github.com/Fission-AI/OpenSpec | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Protect OpenSpec from AI slop PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect OpenSpec from AI slop PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a941eca296774492b16583764132d1f8 | https://github.com/Fission-AI/OpenSpec/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcb3cf5661b4a19862619c854eb531d | https://github.com/Fission-AI/OpenSpec/issues/1081 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 维护坑 · 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:1032459340 | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | release_recency=unknown\n\n\n",
"markdown_key": "openspec",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1032459340",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Fission-AI/OpenSpec"
},
{
"evidence_id": "art_0e5fb41928564ab8a00958a4bad4e970",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Fission-AI/OpenSpec#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "OpenSpec 说明书",
"toc": [
"https://github.com/Fission-AI/OpenSpec 项目说明书",
"目录",
"OpenSpec概述",
"简介",
"核心架构",
"工作流程",
"支持的工具",
"安装与配置",
"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": "053d8a59d587f3c027a06ad80503a6b43d4f2a92",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/customization.md",
"docs/migration-guide.md",
"docs/concepts.md",
"docs/cli.md",
"docs/opsx.md",
"docs/commands.md",
"docs/getting-started.md",
"docs/installation.md",
"docs/workflows.md",
"docs/multi-language.md",
"docs/supported-tools.md",
"src/index.ts",
"src/cli/index.ts",
"src/prompts/searchable-multi-select.ts",
"src/telemetry/index.ts",
"src/telemetry/config.ts",
"src/ui/welcome-screen.ts",
"src/ui/ascii-patterns.ts",
"src/utils/item-discovery.ts",
"src/utils/change-metadata.ts",
"src/utils/command-references.ts",
"src/utils/task-progress.ts",
"src/utils/shell-detection.ts",
"src/utils/index.ts",
"src/utils/match.ts",
"src/utils/change-utils.ts",
"src/utils/interactive.ts",
"src/utils/file-system.ts",
"src/core/view.ts",
"src/core/update.ts",
"src/core/config-prompts.ts",
"src/core/list.ts",
"src/core/profiles.ts",
"src/core/index.ts",
"src/core/profile-sync-drift.ts",
"src/core/config.ts",
"src/core/migration.ts"
],
"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": "# @fission-ai/openspec - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @fission-ai/openspec 编译的 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_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @fission-ai/openspec@latest` 证据：`README.md` Claim：`clm_0003` 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_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` 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 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`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_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` 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- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：706\n- 重要文件覆盖：40/706\n- 证据索引条目：79\n- 角色 / Skill 条目：78\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请基于 @fission-ai/openspec 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @fission-ai/openspec 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 @fission-ai/openspec 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 78 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：This directory is managed by Changesets https://github.com/changesets/changesets . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Dev Container Setup**（project_doc）：This directory contains the VS Code dev container configuration for OpenSpec development. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.devcontainer/README.md`\n- **Agents**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **See it in action**（project_doc）：! Stars https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars https://github.com/Fission-AI/OpenSpec/stargazers ! Downloads https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo https://www.npmjs.com/package/@fission-ai/openspec ! Contributors https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors https://g… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **OpenSpec Scripts**（project_doc）：Utility scripts for OpenSpec maintenance and development. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/README.md`\n- **Github Workflows**（project_doc）：Test GitHub Actions workflows locally using act https://nektosact.com/ : 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/README.md`\n- **OpenSpec Instructions**（project_doc）：This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/specs/openspec-docs/README.md`\n- **opencode-command-references**（project_doc）：Transform /opsx: to /opsx- in both commands and skills for OpenCode 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2026-01-30-opencode-command-references/README.md`\n- **add-kimi-cli-skills-only-support**（project_doc）：Add Kimi CLI as a supported skills-only tool without a command adapter 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/README.md`\n- **Workspace Reimplementation Roadmap**（project_doc）：This change is the continuity layer for reimplementing workspace support across multiple sessions and branches. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/workspace-reimplementation-roadmap/README.md`\n- **CLI Reference**（project_doc）：The OpenSpec CLI openspec provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands like /opsx:propose documented in Commands commands.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cli.md`\n- **Commands**（project_doc）：This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface e.g., Claude Code, Cursor, Windsurf . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/commands.md`\n- **Concepts**（project_doc）：This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see Getting Started getting-started.md and Workflows workflows.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts.md`\n- **Customization**（project_doc）：OpenSpec provides three levels of customization: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/customization.md`\n- **Getting Started**（project_doc）：This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the main README ../README.md quick-start . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started.md`\n- **Installation**（project_doc）：- Node.js 20.19.0 or higher — Check your version: node --version 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/installation.md`\n- **Migrating to OPSX**（project_doc）：This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration-guide.md`\n- **Multi-Language Guide**（project_doc）：Configure OpenSpec to generate artifacts in languages other than English. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/multi-language.md`\n- **OPSX Workflow**（project_doc）：Feedback welcome on Discord https://discord.gg/YctCnvvshC . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/opsx.md`\n- **Supported Tools**（project_doc）：OpenSpec works with many AI coding assistants. When you run openspec init , OpenSpec configures selected tools using your active profile/workflow selection and delivery mode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/supported-tools.md`\n- **Workflows**（project_doc）：This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see Getting Started getting-started.md . For command reference, see Commands commands.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflows.md`\n- **Clarify Bun Node Runtime**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/clarify-bun-node-runtime.md`\n- **New Features**（project_doc）：- Kimi CLI support — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using .kimi/skills/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/kind-rings-notice.md`\n- **New Features**（project_doc）：- Include the sync workflow in the default core profile so new installs generate /opsx:sync skills and commands by default. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/sync-default-core.md`\n- **@fission-ai/openspec**（project_doc）：- 995 https://github.com/Fission-AI/OpenSpec/pull/995 d1f3861 https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137 Thanks @TabishB https://github.com/TabishB ! - Bug Fixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Maintainers**（project_doc）：People who maintain and guide OpenSpec. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`MAINTAINERS.md`\n- **OpenSpec**（project_doc）：Spec-driven development for AI coding assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_OLD.md`\n- **Workspace Reimplementation Direction**（project_doc）：Workspace Reimplementation Direction 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`WORKSPACE_REIMPLEMENTATION_DIRECTION.md`\n- **Workspace Reimplementation Start Here**（project_doc）：Workspace Reimplementation Start Here 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`WORKSPACE_REIMPLEMENTATION_START_HERE.md`\n- **OpenSpec Parallel Delta Remediation Plan**（project_doc）：OpenSpec Parallel Delta Remediation Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec-parallel-merge-plan.md`\n- **Implementation Order and Dependencies**（project_doc）：Implementation Order and Dependencies 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/IMPLEMENTATION_ORDER.md`\n- **Add Artifact Regeneration Support**（project_doc）：Currently, there is no way to regenerate artifacts in the OPSX workflow: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-artifact-regeneration-support/proposal.md`\n- **Why**（project_doc）：Parallel changes often touch the same capabilities and cli-init / cli-update behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Metadata Scaffolding Change creation workflows SHALL support optional dependency metadata for new or split changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/change-creation/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Metadata Model The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Planning Commands The change CLI SHALL provide commands for dependency-aware sequencing of active changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/cli-change/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack-Aware Change Planning Conventions OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/openspec-conventions/spec.md`\n- **1. Metadata Model**（project_doc）：- 1.1 Add optional stack metadata fields dependsOn , provides , requires , touches , parent to change metadata schema - 1.2 Keep metadata backward compatible for existing changes without new fields - 1.3 Add tests for valid/invalid metadata and schema evolution behavior 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/tasks.md`\n- **Context**（project_doc）：OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/design.md`\n- **Why**（project_doc）：OpenSpec installation paths are currently inconsistent: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/proposal.md`\n- **MODIFIED Requirements**（project_doc）：Requirement: AIToolOption skillsDir field The AIToolOption interface SHALL include scope support metadata in addition to path metadata. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/ai-tool-paths/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Install scope configuration via profile flow The config profile workflow SHALL allow users to configure install scope preference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-config/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Init install scope selection The init command SHALL support install scope selection for generated artifacts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-init/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Update install scope selection The update command SHALL support install scope selection for sync operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-update/spec.md`\n- **MODIFIED Requirements**（project_doc）：Requirement: ToolCommandAdapter interface The system SHALL provide install-context-aware command path resolution. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/command-generation/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Install scope field in global config The global config schema SHALL include install scope preference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/global-config/spec.md`\n- **Purpose**（project_doc）：Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/installation-scope/spec.md`\n- **1. Global Config + Validation**（project_doc）：- 1.1 Add installScope global project to GlobalConfig with explicit global default for newly created configs - 1.2 Update config schema validation and known-key checks to include install scope - 1.3 Add schema-evolution tests ensuring missing installScope in legacy configs resolves to effective project until explicit migration - 1.4 Extend openspec config list output to show install scope and source explicit , new-d… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/tasks.md`\n- **Why**（project_doc）：We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-qa-smoke-harness/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Makefile QA Entry Point 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md`\n- **Why**（project_doc）：OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Command surface capability resolution The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Delivery sync by command surface capability The update command SHALL synchronize artifacts using each configured tool's command surface capability. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md`\n- **0. Stacking Coordination**（project_doc）：- 0.1 Rebase this change on latest main before implementation - 0.2 If simplify-skill-installation is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement - 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket \"commands = remove all skills\" rule - 0.4 If add-global-install-scope is merged, verify combined scope × delivery × command… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/tasks.md`\n- **Technical Design**（project_doc）：Simplicity First - No version tracking - always update when commanded - Full replacement for OpenSpec-managed files only e.g., openspec/README.md - Marker-based updates for user-owned files e.g., CLAUDE.md - Templates bundled with package - no network required - Minimal error handling - only check prerequisites 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/design.md`\n- **Add Update Command**（project_doc）：Users need a way to update their local OpenSpec instructions README.md and CLAUDE.md when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/proposal.md`\n- **Update Command Specification**（project_doc）：As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md`\n- **Implementation Tasks**（project_doc）：1. Update Command Implementation - x 1.1 Create src/core/update.ts with UpdateCommand class - x 1.2 Check if openspec directory exists use FileSystemUtils.directoryExists - x 1.3 Write readmeTemplate to openspec/README.md using FileSystemUtils.writeFile - x 1.4 Update CLAUDE.md using markers via FileSystemUtils.updateFileWithMarkers and TemplateManager.getClaudeTemplate - x 1.5 Display ASCII-safe success message: Up… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/tasks.md`\n- **Add List Command to OpenSpec CLI**（project_doc）：Developers need visibility into available changes and their status to understand the project's evolution and pending work. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/proposal.md`\n- **List Command Specification**（project_doc）：The openspec list command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/specs/cli-list/spec.md`\n- **Implementation Tasks**（project_doc）：1. Core Implementation - x 1.1 Create src/core/list.ts with list logic - x 1.1.1 Implement directory scanning exclude archive/ - x 1.1.2 Implement task counting from tasks.md files - x 1.1.3 Format output as simple table - x 1.2 Add list command to CLI in src/cli/index.ts - x 1.2.1 Register openspec list command - x 1.2.2 Connect to list.ts implementation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/tasks.md`\n- **Technical Design**（project_doc）：TypeScript Configuration - Strict mode : Enable all strict type checking for better AI understanding - Target : ES2022 for modern JavaScript features - Module : ES2022 for modern ESM support - Module Resolution : Node for proper package resolution - Output : dist/ directory for compiled JavaScript - Source Maps : Enable for debugging TypeScript directly - Declaration Files : Generate .d.ts files for type definitions… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/design.md`\n- **Initialize TypeScript Project**（project_doc）：Why The OpenSpec project needs a proper TypeScript foundation to build the minimal CLI that helps developers set up OpenSpec file structures and keep AI instructions updated. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/proposal.md`\n- **Tasks**（project_doc）：1. Project Configuration - x 1.1 Create package.json with project metadata, scripts, and ESM configuration - x 1.2 Configure TypeScript with tsconfig.json for ESM output - x 1.3 Add .gitignore for Node.js/TypeScript projects - x 1.4 Set Node.js engine requirement to =20.19.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/tasks.md`\n- **Technical Design for Init Command**（project_doc）：The init command follows a modular architecture with clear separation of concerns: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/design.md`\n- **Add Init Command for OpenSpec**（project_doc）：Projects need a simple way to adopt OpenSpec conventions. Currently, users must manually create the directory structure and understand all the conventions, which creates friction for adoption. An init command would enable instant OpenSpec setup with proper structure and guidance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/proposal.md`\n- **CLI Init Specification**（project_doc）：The openspec init command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/specs/cli-init/spec.md`\n- **Implementation Tasks for Init Command**（project_doc）：Implementation Tasks for Init Command 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/tasks.md`\n- **Adopt Future State Storage for OpenSpec Changes**（project_doc）：Adopt Future State Storage for OpenSpec Changes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/proposal.md`\n- **OpenSpec Conventions Specification**（project_doc）：OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/specs/openspec-conventions/spec.md`\n- **Implementation Tasks**（project_doc）：1. Update Core Documentation - x 1.1 Update openspec/README.md section on \"Creating a Change Proposal\" - x Replace patches/ with specs/ in directory structure - x Update step 3 to show storing complete future state - x Remove diff syntax instructions +/- prefixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/tasks.md`\n- **Add Complexity Management Guidelines**（project_doc）：Add Complexity Management Guidelines 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/proposal.md`\n- **Implementation Tasks**（project_doc）：1. Update OpenSpec README - x 1.1 Add \"Start Simple\" section after Core Principle - x 1.2 Add complexity triggers to \"When to Create Change Proposals\" section - x 1.3 Update AI workflow guidance to emphasize minimal implementations 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/tasks.md`\n- **Why**（project_doc）：Why Need a command to archive completed changes to the archive folder with proper date prefixing, following OpenSpec conventions. Currently changes must be manually moved and renamed. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/proposal.md`\n- **CLI Archive Command Specification**（project_doc）：Purpose The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/specs/cli-archive/spec.md`\n- **Implementation Tasks**（project_doc）：1. Core Implementation - 1.1 Create src/core/archive.ts with ArchiveCommand class - 1.1.1 Implement change selection interactive if not provided - 1.1.2 Implement incomplete task checking from tasks.md - 1.1.3 Implement confirmation prompt for incomplete tasks - 1.1.4 Implement spec update functionality - 1.1.4.1 Detect specs in change directory - 1.1.4.2 Compare with existing main specs - 1.1.4.3 Display summary of… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/tasks.md`\n- **Add Diff Command to OpenSpec CLI**（project_doc）：Developers need to easily view differences between proposed spec changes and current specs without manually comparing files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-diff-command/proposal.md`\n- **CLI Diff Command Specification**（project_doc）：The openspec diff command provides developers with a visual comparison between proposed spec changes and the current deployed specs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-diff-command/specs/cli-diff/spec.md`\n\n## 证据索引\n\n- 共索引 79 条证据。\n\n- **Changesets**（documentation）：This directory is managed by Changesets https://github.com/changesets/changesets . 证据：`.changeset/README.md`\n- **Dev Container Setup**（documentation）：This directory contains the VS Code dev container configuration for OpenSpec development. 证据：`.devcontainer/README.md`\n- **See it in action**（documentation）：! Stars https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars https://github.com/Fission-AI/OpenSpec/stargazers ! Downloads https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo https://www.npmjs.com/package/@fission-ai/openspec ! Contributors https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors https://github.com/Fission-AI/OpenSpec/graphs/contributors 证据：`README.md`\n- **OpenSpec Scripts**（documentation）：Utility scripts for OpenSpec maintenance and development. 证据：`scripts/README.md`\n- **Github Workflows**（documentation）：Test GitHub Actions workflows locally using act https://nektosact.com/ : 证据：`.github/workflows/README.md`\n- **OpenSpec Instructions**（documentation）：This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects. 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/specs/openspec-docs/README.md`\n- **opencode-command-references**（documentation）：Transform /opsx: to /opsx- in both commands and skills for OpenCode 证据：`openspec/changes/archive/2026-01-30-opencode-command-references/README.md`\n- **add-kimi-cli-skills-only-support**（documentation）：Add Kimi CLI as a supported skills-only tool without a command adapter 证据：`openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/README.md`\n- **Workspace Reimplementation Roadmap**（documentation）：This change is the continuity layer for reimplementing workspace support across multiple sessions and branches. 证据：`openspec/changes/workspace-reimplementation-roadmap/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@fission-ai/openspec\", \"version\": \"1.3.1\", \"description\": \"AI-native system for spec-driven development\", \"keywords\": \"openspec\", \"specs\", \"cli\", \"ai\", \"development\" , \"homepage\": \"https://github.com/Fission-AI/OpenSpec\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Fission-AI/OpenSpec\" }, \"license\": \"MIT\", \"author\": \"OpenSpec Contributors\", \"type\": \"module\", \"publishConfig\": { \"access\": \"public\" }, \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"bin\": { \"openspec\": \"./bin/openspec.js\" }, \"files\": \"dist\", \"bin\", \"schemas\", \"scripts/postinstall.js\", \"!dist/ / .test.js\", \"!dist/ / tests \", \"!dist/ / .map\" , \"scripts\": { \"lint\": \"esl… 证据：`package.json`\n- **License**（source_file）：Copyright c 2024 OpenSpec Contributors 证据：`LICENSE`\n- **CLI Reference**（documentation）：The OpenSpec CLI openspec provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands like /opsx:propose documented in Commands commands.md . 证据：`docs/cli.md`\n- **Commands**（documentation）：This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface e.g., Claude Code, Cursor, Windsurf . 证据：`docs/commands.md`\n- **Concepts**（documentation）：This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see Getting Started getting-started.md and Workflows workflows.md . 证据：`docs/concepts.md`\n- **Customization**（documentation）：OpenSpec provides three levels of customization: 证据：`docs/customization.md`\n- **Getting Started**（documentation）：This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the main README ../README.md quick-start . 证据：`docs/getting-started.md`\n- **Installation**（documentation）：- Node.js 20.19.0 or higher — Check your version: node --version 证据：`docs/installation.md`\n- **Migrating to OPSX**（documentation）：This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility. 证据：`docs/migration-guide.md`\n- **Multi-Language Guide**（documentation）：Configure OpenSpec to generate artifacts in languages other than English. 证据：`docs/multi-language.md`\n- **OPSX Workflow**（documentation）：Feedback welcome on Discord https://discord.gg/YctCnvvshC . 证据：`docs/opsx.md`\n- **Supported Tools**（documentation）：OpenSpec works with many AI coding assistants. When you run openspec init , OpenSpec configures selected tools using your active profile/workflow selection and delivery mode. 证据：`docs/supported-tools.md`\n- **Workflows**（documentation）：This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see Getting Started getting-started.md . For command reference, see Commands commands.md . 证据：`docs/workflows.md`\n- **Clarify Bun Node Runtime**（documentation）：--- --- 证据：`.changeset/clarify-bun-node-runtime.md`\n- **New Features**（documentation）：- Kimi CLI support — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using .kimi/skills/ 证据：`.changeset/kind-rings-notice.md`\n- **New Features**（documentation）：- Include the sync workflow in the default core profile so new installs generate /opsx:sync skills and commands by default. 证据：`.changeset/sync-default-core.md`\n- **@fission-ai/openspec**（documentation）：- 995 https://github.com/Fission-AI/OpenSpec/pull/995 d1f3861 https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137 Thanks @TabishB https://github.com/TabishB ! - Bug Fixes 证据：`CHANGELOG.md`\n- **Maintainers**（documentation）：People who maintain and guide OpenSpec. 证据：`MAINTAINERS.md`\n- **OpenSpec**（documentation）：Spec-driven development for AI coding assistants. 证据：`README_OLD.md`\n- **Workspace Reimplementation Direction**（documentation）：Workspace Reimplementation Direction 证据：`WORKSPACE_REIMPLEMENTATION_DIRECTION.md`\n- **Workspace Reimplementation Start Here**（documentation）：Workspace Reimplementation Start Here 证据：`WORKSPACE_REIMPLEMENTATION_START_HERE.md`\n- **OpenSpec Parallel Delta Remediation Plan**（documentation）：OpenSpec Parallel Delta Remediation Plan 证据：`openspec-parallel-merge-plan.md`\n- **Implementation Order and Dependencies**（documentation）：Implementation Order and Dependencies 证据：`openspec/changes/IMPLEMENTATION_ORDER.md`\n- **Add Artifact Regeneration Support**（documentation）：Currently, there is no way to regenerate artifacts in the OPSX workflow: 证据：`openspec/changes/add-artifact-regeneration-support/proposal.md`\n- **Why**（documentation）：Parallel changes often touch the same capabilities and cli-init / cli-update behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order. 证据：`openspec/changes/add-change-stacking-awareness/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Metadata Scaffolding Change creation workflows SHALL support optional dependency metadata for new or split changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/change-creation/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Metadata Model The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships. 证据：`openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Planning Commands The change CLI SHALL provide commands for dependency-aware sequencing of active changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/cli-change/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack-Aware Change Planning Conventions OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/openspec-conventions/spec.md`\n- **1. Metadata Model**（documentation）：- 1.1 Add optional stack metadata fields dependsOn , provides , requires , touches , parent to change metadata schema - 1.2 Keep metadata backward compatible for existing changes without new fields - 1.3 Add tests for valid/invalid metadata and schema evolution behavior 证据：`openspec/changes/add-change-stacking-awareness/tasks.md`\n- **Context**（documentation）：OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable. 证据：`openspec/changes/add-global-install-scope/design.md`\n- **Why**（documentation）：OpenSpec installation paths are currently inconsistent: 证据：`openspec/changes/add-global-install-scope/proposal.md`\n- **MODIFIED Requirements**（documentation）：Requirement: AIToolOption skillsDir field The AIToolOption interface SHALL include scope support metadata in addition to path metadata. 证据：`openspec/changes/add-global-install-scope/specs/ai-tool-paths/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Install scope configuration via profile flow The config profile workflow SHALL allow users to configure install scope preference. 证据：`openspec/changes/add-global-install-scope/specs/cli-config/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Init install scope selection The init command SHALL support install scope selection for generated artifacts. 证据：`openspec/changes/add-global-install-scope/specs/cli-init/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Update install scope selection The update command SHALL support install scope selection for sync operations. 证据：`openspec/changes/add-global-install-scope/specs/cli-update/spec.md`\n- **MODIFIED Requirements**（documentation）：Requirement: ToolCommandAdapter interface The system SHALL provide install-context-aware command path resolution. 证据：`openspec/changes/add-global-install-scope/specs/command-generation/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Install scope field in global config The global config schema SHALL include install scope preference. 证据：`openspec/changes/add-global-install-scope/specs/global-config/spec.md`\n- **Purpose**（documentation）：Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics. 证据：`openspec/changes/add-global-install-scope/specs/installation-scope/spec.md`\n- **1. Global Config + Validation**（documentation）：- 1.1 Add installScope global project to GlobalConfig with explicit global default for newly created configs - 1.2 Update config schema validation and known-key checks to include install scope - 1.3 Add schema-evolution tests ensuring missing installScope in legacy configs resolves to effective project until explicit migration - 1.4 Extend openspec config list output to show install scope and source explicit , new-default , legacy-default 证据：`openspec/changes/add-global-install-scope/tasks.md`\n- **Why**（documentation）：We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX. 证据：`openspec/changes/add-qa-smoke-harness/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Makefile QA Entry Point 证据：`openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md`\n- **Why**（documentation）：OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools. 证据：`openspec/changes/add-tool-command-surface-capabilities/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Command surface capability resolution The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference. 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Delivery sync by command surface capability The update command SHALL synchronize artifacts using each configured tool's command surface capability. 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md`\n- **0. Stacking Coordination**（documentation）：- 0.1 Rebase this change on latest main before implementation - 0.2 If simplify-skill-installation is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement - 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket \"commands = remove all skills\" rule - 0.4 If add-global-install-scope is merged, verify combined scope × delivery × command-surface behavior remains deterministic 证据：`openspec/changes/add-tool-command-surface-capabilities/tasks.md`\n- **Technical Design**（documentation）：Simplicity First - No version tracking - always update when commanded - Full replacement for OpenSpec-managed files only e.g., openspec/README.md - Marker-based updates for user-owned files e.g., CLAUDE.md - Templates bundled with package - no network required - Minimal error handling - only check prerequisites 证据：`openspec/changes/archive/2025-01-11-add-update-command/design.md`\n- **Add Update Command**（documentation）：Users need a way to update their local OpenSpec instructions README.md and CLAUDE.md when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions. 证据：`openspec/changes/archive/2025-01-11-add-update-command/proposal.md`\n- **Update Command Specification**（documentation）：As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions. 证据：`openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md`\n- **Implementation Tasks**（documentation）：1. Update Command Implementation - x 1.1 Create src/core/update.ts with UpdateCommand class - x 1.2 Check if openspec directory exists use FileSystemUtils.directoryExists - x 1.3 Write readmeTemplate to openspec/README.md using FileSystemUtils.writeFile - x 1.4 Update CLAUDE.md using markers via FileSystemUtils.updateFileWithMarkers and TemplateManager.getClaudeTemplate - x 1.5 Display ASCII-safe success message: Updated OpenSpec instructions 证据：`openspec/changes/archive/2025-01-11-add-update-command/tasks.md`\n- **Add List Command to OpenSpec CLI**（documentation）：Developers need visibility into available changes and their status to understand the project's evolution and pending work. 证据：`openspec/changes/archive/2025-01-13-add-list-command/proposal.md`\n- 其余 19 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `.devcontainer/README.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `.devcontainer/README.md`, `AGENTS.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- **OpenSpec概述**：importance `high`\n - source_paths: README.md, docs/concepts.md, docs/getting-started.md\n- **安装与初始化**：importance `high`\n - source_paths: docs/installation.md, src/core/init.ts, src/core/update.ts, package.json\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/core/index.ts, src/core/command-generation/index.ts, src/core/artifact-graph/index.ts, tsconfig.json\n- **核心模块详解**：importance `medium`\n - source_paths: src/core/schemas/base.schema.ts, src/core/schemas/change.schema.ts, src/core/schemas/spec.schema.ts, src/core/parsers/markdown-parser.ts, src/core/parsers/spec-structure.ts\n- **变更工作流**：importance `high`\n - source_paths: src/core/templates/workflows/propose.ts, src/core/templates/workflows/apply-change.ts, src/core/templates/workflows/archive-change.ts, src/core/parsers/change-parser.ts, src/core/archive.ts\n- **工件图系统**：importance `high`\n - source_paths: src/core/artifact-graph/graph.ts, src/core/artifact-graph/instruction-loader.ts, src/core/artifact-graph/outputs.ts, src/core/artifact-graph/resolver.ts, src/core/artifact-graph/state.ts\n- **AI工具集成**：importance `high`\n - source_paths: src/core/command-generation/registry.ts, src/core/command-generation/generator.ts, src/core/command-generation/types.ts, src/core/command-generation/adapters/index.ts, docs/supported-tools.md\n- **CLI命令参考**：importance `high`\n - source_paths: src/cli/index.ts, src/commands/change.ts, src/commands/spec.ts, src/commands/validate.ts, src/commands/config.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `053d8a59d587f3c027a06ad80503a6b43d4f2a92`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/customization.md`, `docs/migration-guide.md`, `docs/concepts.md`, `docs/cli.md`, `docs/opsx.md`, `docs/commands.md`, `docs/getting-started.md`, `docs/installation.md`, `docs/workflows.md`, `docs/multi-language.md`, `docs/supported-tools.md`, `src/index.ts`, `src/cli/index.ts`, `src/prompts/searchable-multi-select.ts`, `src/telemetry/index.ts`, `src/telemetry/config.ts`, `src/ui/welcome-screen.ts`\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: 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：open:sync messed up my spec.md files\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：First steps don't work\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v1.2.0 - Profiles, Pi & Kiro Support\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Profiles, Pi & Kiro Support\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_cb21ca0230d94a0daf4eb6cf43c4a361 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.3.0 - New Tool Integrations\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.0 - New Tool Integrations\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_382a148d0b88420396bb7da33461ab12 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：OpenCode sync missing\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.22.0 - Project Configuration\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\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项目：Fission-AI/OpenSpec\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 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：open:sync messed up my spec.md files（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：First steps don't work（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.2.0 - Profiles, Pi & Kiro Support（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\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/Fission-AI/OpenSpec 项目说明书\n\n生成时间：2026-05-13 10:35:14 UTC\n\n## 目录\n\n- [OpenSpec概述](#page-overview)\n- [安装与初始化](#page-installation)\n- [系统架构](#page-architecture)\n- [核心模块详解](#page-core-modules)\n- [变更工作流](#page-change-workflow)\n- [工件图系统](#page-artifact-graph)\n- [AI工具集成](#page-ai-integration)\n- [CLI命令参考](#page-cli-commands)\n- [工作流模板](#page-workflow-templates)\n- [配置系统](#page-configuration)\n\n\n\n## OpenSpec概述\n\n### 相关页面\n\n相关主题：[安装与初始化](#page-installation), [系统架构](#page-architecture), [变更工作流](#page-change-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-merge-init-experimental/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-merge-init-experimental/design.md)\n- [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n \n\n# OpenSpec概述\n\n## 简介\n\nOpenSpec 是一个轻量级的规范（Specification）管理框架，专为 AI 编程助手设计。其核心目标是**在编写代码之前让人类和 AI 就需求规范达成一致**，从而提高 AI 代码助手的可预测性和可靠性。\n\n资料来源：[README.md:25-30]()\n\n### 设计理念\n\n| 理念 | 说明 |\n|------|------|\n| **Fluid not Rigid** | 灵活而非僵化，随时可更新工件 |\n| **Iterative not Waterfall** | 迭代而非瀑布式开发 |\n| **Easy not Complex** | 简单而非复杂 |\n| **Built for Brownfield not Just Greenfield** | 支持存量项目而非仅支持新项目 |\n| **Scalable** | 从个人项目到企业级均可使用 |\n\n资料来源：[README.md:72-78]()\n\n## 核心架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[用户/AI助手] --> B[OpenSpec CLI]\n B --> C[Change 目录]\n C --> D[proposal.md]\n C --> E[specs/]\n C --> F[design.md]\n C --> G[tasks.md]\n B --> H[Schema 系统]\n H --> I[模板定义]\n H --> J[工件序列]\n```\n\n### 工件类型\n\nOpenSpec 使用结构化的工件（Artifact）来组织变更：\n\n| 工件 | 文件 | 用途 |\n|------|------|------|\n| **Proposal** | `proposal.md` | 说明变更原因和内容 |\n| **Specs** | `specs/*.md` | 需求和场景定义 |\n| **Design** | `design.md` | 技术设计方案（可选） |\n| **Tasks** | `tasks.md` | 实现检查清单 |\n\n资料来源：[README.md:150-165]()\n\n## 工作流程\n\n### 标准工作流\n\n```mermaid\ngraph LR\n A[提出变更] --> B[编写规范]\n B --> C[设计方案]\n C --> D[创建任务]\n D --> E[实施任务]\n E --> F[归档变更]\n```\n\n#### 步骤 1：提出变更\n\n用户通过自然语言或斜杠命令提出变更需求：\n\n```\nYou: /opsx:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n```\n\n资料来源：[README.md:96-105]()\n\n#### 步骤 2：实施任务\n\n规范确认后开始实现：\n\n```\nYou: The specs look good. Let's implement this change.\nAI: I'll work through the tasks in the add-profile-filters change.\n *Implements tasks from openspec/changes/add-profile-filters/tasks.md*\n```\n\n资料来源：[README.md:140-145]()\n\n#### 步骤 3：归档变更\n\n实现完成后归档变更：\n\n```bash\nopenspec archive add-profile-filters --yes\n```\n\n归档后的变更会被移至 `openspec/changes/archive/-/` 目录。\n\n### 实验性工作流 (/opsx)\n\n新版实验性工作流提供更简化的命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:propose` | 创建新变更 |\n| `/opsx:continue` | 继续下一个工件 |\n| `/opsx:ff` | 快进到完成 |\n| `/opsx:verify` | 验证工件 |\n| `/opsx:bulk-archive` | 批量归档 |\n| `/opsx:onboard` | 新项目引导 |\n\n启用方式：`openspec experimental`\n\n资料来源：[README.md:85-92]()\n\n## 支持的工具\n\n### 原生斜杠命令支持\n\n| 工具 | 命令格式 | 配置目录 |\n|------|----------|----------|\n| **Claude Code** | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置支持 |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| **Cline** | Workflows | `.clinerules/workflows/openspec-*.md` |\n| **Kilo Code** | `/openspec-proposal.md` 等 | `.kilocode/workflows/` |\n| **Windsurf** | `/openspec-proposal` 等 | `.windsurf/workflows/` |\n\n资料来源：[README.md:40-70]()\n\n### AGENTS.md 兼容工具\n\n以下工具通过读取 `openspec/AGENTS.md` 自动发现工作流程：\n\n- Amp\n- Jules\n- 其他支持 AGENTS.md 约定的工具\n\n## 安装与配置\n\n### 系统要求\n\n- **Node.js**: >= 20.19.0\n\n资料来源：[README.md:107-108]()\n\n### 安装步骤\n\n#### 方式 A：npm 全局安装\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n验证安装：\n\n```bash\nopenspec --version\n```\n\n#### 方式 B：Nix 安装\n\n```bash\n# 直接运行\nnix run github:Fission-AI/OpenSpec -- init\n\n# 安装到用户 profile\nnix profile install github:Fission-AI/OpenSpec\n```\n\n#### 方式 C：pnpm/yarn/bun\n\nOpenSpec 同时支持 pnpm、yarn、bun 等包管理器。\n\n资料来源：[README.md:110-125]()\n\n### 初始化项目\n\n```bash\ncd your-project\nopenspec init\n```\n\n初始化后会创建基础目录结构：\n\n```\nopenspec/\n├── config.yaml # 项目配置\n├── specs/ # 规范源文件\n│ └── /\n│ └── spec.md\n└── changes/ # 变更目录\n```\n\n## CLI 命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `openspec init` | 初始化 OpenSpec |\n| `openspec list` | 查看活跃变更 |\n| `openspec view` | 交互式仪表板 |\n| `openspec show ` | 显示变更详情 |\n| `openspec validate ` | 检查规范格式 |\n| `openspec archive [--yes]` | 归档完成变更 |\n| `openspec config profile` | 选择工作流配置 |\n| `openspec update` | 更新配置文件 |\n| `openspec experimental` | 启用实验性功能 |\n\n资料来源：[README.md:155-165]()\n\n## 项目配置\n\n### config.yaml 结构\n\n```yaml\ncontext: |\n # 项目上下文信息\n # 将自动注入到所有工件中\n\nrules:\n proposal:\n - 遵循简洁原则\n specs:\n - 使用 WHEN/THEN 格式\n```\n\n### 上下文注入\n\n```bash\nopenspec instructions specs --change my-feature\n```\n\n输出包含：\n\n```markdown\n\n[项目上下文]\n\n\n\n- 特定工件的规则\n\n\n\n[Schema 模板]\n\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md:15-35]()\n\n## 规范格式\n\n### 需求格式\n\n```markdown\n### Requirement: <需求名称>\n系统应该在特定条件下执行特定行为。\n\n#### Scenario: <场景名称>\n- **WHEN** <触发条件>\n- **THEN** <预期结果>\n```\n\n**格式要求**：\n\n- 使用 SHALL/MUST 表示规范性需求\n- 场景标题必须使用 4 个 `#` (`####`)\n- 每个需求必须至少包含一个场景\n\n资料来源：[schemas/spec-driven/schema.yaml:1-25]()\n\n### MODIFIED 需求工作流\n\n修改现有需求时：\n\n1. 在原规范文件中定位需求\n2. 复制完整需求块\n3. 粘贴到 `## MODIFIED Requirements` 下\n4. 编辑以反映新行为\n\n```markdown\n## MODIFIED Requirements\n\n### Requirement: User can export data\nThe system SHALL allow users to export their data in CSV format.\n\n#### Scenario: Successful export\n- **WHEN** user clicks \"Export\" button\n- **THEN** system downloads a CSV file\n```\n\n## 变更目录结构\n\n### AI 创建的文件结构\n\n```\nopenspec/\n├── specs/\n│ └── auth/\n│ └── spec.md # 当前规范（源）\n└── changes/\n └── add-2fa/ # 变更目录\n ├── proposal.md # 变更原因\n ├── tasks.md # 实现检查清单\n ├── design.md # 技术决策（可选）\n └── specs/\n └── auth/\n └── spec.md # 增量规范\n```\n\n资料来源：[README.md:150-165]()\n\n## 遥测与隐私\n\nOpenSpec 收集**匿名使用统计**（可选退出）：\n\n- 仅收集命令名称和版本\n- 不收集参数、路径、内容或 PII\n- CI 环境中自动禁用\n\n**退出方式**：\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# 或\nexport DO_NOT_TRACK=1\n```\n\n## 开发指南\n\n### 本地开发\n\n```bash\n# 安装依赖\npnpm install\n\n# 构建\npnpm run build\n\n# 测试\npnpm test\n\n# 开发 CLI\npnpm run dev\n# 或\npnpm run dev:cli\n\n# 提交规范\ngit commit -m \"type(scope): subject\"\n```\n\n资料来源：[README.md:190-196]()\n\n## 工作空间功能\n\n### 多仓库支持\n\nOpenSpec 支持跨多个仓库的工作空间管理：\n\n```bash\nopenspec workspace explore \n```\n\n### 状态查询\n\n```bash\nopenspec status\nopenspec status --change integrate-docs\n```\n\n输出示例：\n\n```\nChange: integrate-docs\nScope: openspec, landing\nProposal: present\nDesign: present\nTasks: present\nReady for apply: yes/no\n```\n\n状态检查会捕获结构性问题：\n\n- `specs/` 下未知的仓库文件夹\n- 缺失的任务文件\n- 未确认的受影响仓库\n- 缺失的仓库链接或路径\n\n资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md:1-50]()\n\n## 总结\n\nOpenSpec 提供了一个轻量级但结构化的规范管理框架，其核心价值在于：\n\n1. **前置对齐**：在编码前达成共识\n2. **组织化**：每个变更都有独立文件夹\n3. **灵活性**：可随时更新工件，无需僵化的阶段门控\n4. **工具兼容性**：支持 25+ AI 编程助手\n\n无论是个人项目还是企业级开发，OpenSpec 都能帮助团队更高效、更可靠地进行 AI 辅助开发。\n\n---\n\n\n\n## 安装与初始化\n\n### 相关页面\n\n相关主题：[OpenSpec概述](#page-overview), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [src/core/init.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/init.ts)\n- [src/core/update.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/update.ts)\n- [package.json](https://github.com/Fission-AI/OpenSpec/blob/main/package.json)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n \n\n# 安装与初始化\n\n## 概述\n\nOpenSpec 是一个基于 AI 的规范框架，用于在 AI 编码助手项目中建立结构化的变更管理流程。安装与初始化是用户首次使用 OpenSpec 的关键步骤，涉及 CLI 工具安装、项目目录配置、配置文件生成以及与 AI 工具的集成设置。\n\n本章节详细说明 OpenSpec 的各种安装方式、系统要求、初始化流程以及配置选项，帮助用户快速上手并在团队中推广使用。\n\n## 系统要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 20.19.0 | 核心运行时环境 |\n| 包管理器 | npm/pnpm/yarn/bun/nix | 任选其一 |\n| 操作系统 |跨平台 | Linux、macOS、Windows |\n\n资料来源：[README.md:67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 安装方式\n\n### npm 全局安装\n\n通过 npm 将 OpenSpec 安装为全局 CLI 工具：\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n安装完成后验证版本：\n\n```bash\nopenspec --version\n```\n\n资料来源：[README.md:69-75](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### pnpm 安装\n\n```bash\npnpm add -g @fission-ai/openspec\n```\n\n### yarn 安装\n\n```bash\nyarn global add @fission-ai/openspec\n```\n\n### bun 安装\n\n```bash\nbun add -g @fission-ai/openspec\n```\n\n资料来源：[README.md:56](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### Nix 安装（无安装方式）\n\n对于使用 Nix 或 NixOS 的用户，可以直接运行而不安装：\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\n或安装到用户 profile：\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\n或添加到 `flake.nix` 的 inputs 中：\n\n```nix\ninputs.openspec.url = \"github:Fission-AI/OpenSpec\";\n```\n\n资料来源：[README.md:80-91](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 项目初始化流程\n\n### 基本初始化\n\n初始化是创建 OpenSpec 项目结构的核心步骤。在项目根目录下运行：\n\n```bash\ncd your-project\nopenspec init\n```\n\n该命令会创建以下目录结构：\n\n```\nproject-root/\n├── openspec/\n│ ├── config.yaml # 项目配置文件\n│ ├── specs/ # 规范文件目录\n│ │ └── /\n│ │ └── spec.md\n│ ├── AGENTS.md # AI 代理指令文件\n│ └── changes/ # 变更记录目录\n└── .openspec/ # 内部状态目录\n```\n\n### 交互式初始化选项\n\n初始化过程支持多种命令行参数：\n\n| 参数 | 说明 | 使用场景 |\n|------|------|----------|\n| `--yes` | 接受所有默认值，无需交互确认 | 自动化脚本、CI 环境 |\n| `--no-input` | 跳过所有提示，使用命令行参数 | 无人值守安装 |\n| `--force` | 强制覆盖已存在的 OpenSpec 目录 | 重新初始化 |\n| `--dry-run` | 预览将要创建的内容，不实际写入 | 测试配置 |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n\n### 初始化事务机制\n\nOpenSpec 使用原子化目录创建机制，包含事务回滚功能：\n\n```typescript\ninterface InitTransaction {\n createdPaths: string[];\n rollback(): Promise;\n commit(): Promise;\n}\n```\n\n**事务保障**：\n- 如果创建过程中失败，已创建的文件会被回滚清除\n- 防止部分安装导致的脏状态\n- 确保初始化要么完全成功，要么完全回滚\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:28-35](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n\n## 项目配置\n\n### config.yaml 结构\n\n初始化后生成的 `openspec/config.yaml` 是项目的核心配置文件：\n\n```yaml\nschema: spec-driven\ncontext:\n projectName: \"My Project\"\n techStack: []\n conventions: \"\"\nrules: {}\n```\n\n### 配置字段说明\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `schema` | string | 使用的 schema 名称，默认为 `spec-driven` |\n| `context.projectName` | string | 项目名称 |\n| `context.techStack` | string[] | 技术栈列表 |\n| `context.conventions` | string | 项目约定和规范 |\n| `rules` | object | 按 artifact 类型定义的规则 |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### 动态指令系统\n\n新版本 OpenSpec 采用三层指令架构：\n\n```mermaid\ngraph TD\n A[用户运行命令] --> B[Context 上下文层]\n A --> C[Rules 规则层]\n A --> D[Template 模板层]\n B --> E[config.yaml 项目背景]\n C --> F[Artifact-specific 约束]\n D --> G[Schema 定义的模板]\n E --> H[CLI 动态组装]\n F --> H\n G --> H\n H --> I[AI 接收实时指令]\n```\n\n**三层职责**：\n\n1. **Context（上下文）**：从 `config.yaml` 读取项目背景信息\n2. **Rules（规则）**：Artifact 特定的约束条件\n3. **Template（模板）**：Schema 定义的输出文件结构\n\n资料来源：[CHANGELOG.md:15-30](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n\n## Schema 管理\n\n### Schema 加载优先级\n\nOpenSpec 按以下顺序查找 Schema：\n\n| 优先级 | 位置 | 说明 |\n|--------|------|------|\n| 1 | `project/openspec/schemas//` | 项目本地自定义 |\n| 2 | `~/.local/share/openspec/schemas//` | 用户级别覆盖 |\n| 3 | `@fission-ai/openspec/schemas//` | 包内置（最低优先级） |\n\n项目本地的 Schema 会覆盖同名的内置 Schema，实现团队定制化。\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n### 查看可用 Schema\n\n```bash\nopenspec schemas\n```\n\n输出示例：\n\n```\nAvailable schemas:\n - spec-driven (built-in)\n - custom-schema (project)\n```\n\n## 更新与维护\n\n### 升级 CLI\n\n```bash\nnpm update -g @fission-ai/openspec\n```\n\n### 更新项目配置\n\n当 OpenSpec 发布新版本或项目结构需要同步时：\n\n```bash\nopenspec update\n```\n\n更新操作会：\n- 刷新 `openspec/AGENTS.md` 文件\n- 更新现有 artifact 模板\n- 清理过时的配置文件\n\n### 切换实验性工作流\n\n新版 OpenSpec 引入了基于 artifact 的实验性工作流：\n\n```bash\nopenspec experimental\n```\n\n实验性工作流提供以下命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:propose` | 创建新的变更提案 |\n| `/opsx:new` | 启动新变更 |\n| `/opsx:continue` | 逐步创建 artifact |\n| `/opsx:ff` | 快速推进变更 |\n| `/opsx:verify` | 验证变更完整性 |\n| `/opsx:bulk-archive` | 批量归档变更 |\n| `/opsx:onboard` | 新成员引导 |\n\n资料来源：[README.md:55-60](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### 配置文件选择\n\n查看当前使用的配置文件类型：\n\n```bash\nopenspec config profile\n```\n\n可选配置文件类型：\n- **旧版配置**：生成 CLAUDE.md、.cursorrules 等工具配置文件\n- **新版配置**：使用 openspec/AGENTS.md 和 config.yaml\n\n资料来源：[README.md:50-55](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 与 AI 工具集成\n\n### 支持的工具类型\n\n| 集成类型 | 工具示例 | 配置方式 |\n|----------|----------|----------|\n| 原生斜杠命令 | Claude Code, CodeBuddy | 内置支持 |\n| 配置文件 | Cursor, Windsurf | 生成 .cursorrules 等 |\n| 工作流文件 | Cline, Kilo Code | 生成 .clinerules 等 |\n\n### 主要支持的 AI 助手\n\n| 工具 | 命令格式 | 配置目录 |\n|------|----------|----------|\n| Claude Code | `/openspec:propose`, `/openspec:apply`, `/openspec:archive` | 内置 |\n| Amazon Q Developer | `@openspec-proposal`, `@openspec-apply` | `.amazonq/prompts/` |\n| Cursor | 斜杠命令 | `.cursor/rules/` |\n| CodeBuddy | `/openspec:proposal` | `.codebuddy/commands/` |\n| Cline | 配置文件方式 | `.clinerules/workflows/` |\n\n资料来源：[README.md:99-130](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 安全性与最佳实践\n\n### 安全考量\n\n1. **路径遍历防护**：所有用户提供的路径都经过清理验证\n2. **文件权限检查**：写入前验证目录权限\n3. **现有文件保护**：未使用 `--force` 不会覆盖已有文件\n4. **模板注入防护**：用户输入在模板中被清理\n\n### 遥测数据收集\n\nOpenSpec 默认收集匿名使用统计：\n\n- 仅收集命令名称和版本号\n- 不收集参数、路径、内容或个人信息\n- CI 环境中自动禁用\n\n**禁用遥测**：\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# 或\nexport DO_NOT_TRACK=1\n```\n\n资料来源：[README.md:60-67](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 快速入门工作流\n\n```mermaid\ngraph LR\n A[安装 CLI] --> B[初始化项目]\n B --> C[运行 openspec init]\n C --> D[配置 AI 助手]\n D --> E[使用 /opsx:propose 开始]\n E --> F[创建提案]\n F --> G[实现任务]\n G --> H[归档变更]\n```\n\n**标准快速入门步骤**：\n\n1. 安装 OpenSpec：`npm install -g @fission-ai/openspec@latest`\n2. 进入项目目录：`cd your-project`\n3. 初始化：`openspec init`\n4. 向 AI 助手发送指令：`/opsx:propose <你想要构建的功能>`\n\n资料来源：[README.md:68-78](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 常见问题\n\n### Q: Node.js 版本不满足要求\n\n```bash\n# 检查版本\nnode --version\n\n# 使用 nvm 升级\nnvm install 20.19.0\nnvm use 20.19.0\n```\n\n### Q: 初始化失败权限错误\n\n```bash\n# 检查目录权限\nls -la\n\n# 使用 sudo（不推荐）\nsudo openspec init\n```\n\n### Q: 想使用实验性工作流\n\n```bash\nopenspec experimental\n```\n\n### Q: 想要查看所有可用命令\n\n```bash\nopenspec --help\n```\n\n## 贡献开发\n\n如需为 OpenSpec 贡献代码：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Fission-AI/OpenSpec.git\ncd OpenSpec\n\n# 安装依赖\npnpm install\n\n# 构建项目\npnpm run build\n\n# 运行测试\npnpm test\n\n# 本地开发 CLI\npnpm run dev\n# 或\npnpm run dev:cli\n```\n\n提交代码使用 conventional commits 格式：`type(scope): subject`\n\n资料来源：[README.md:145-150](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心模块详解](#page-core-modules), [AI工具集成](#page-ai-integration), [工件图系统](#page-artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n- [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n \n\n# 系统架构\n\n## 概述\n\nOpenSpec 是一个轻量级的规范框架，专为 AI 编程助手设计。其核心目标是让人类开发者和 AI 在编写代码之前先就规范达成共识，从而提高代码质量和项目可预测性。\n\n**技术栈要求：**\n- Node.js 20.19.0 或更高版本\n- 支持 pnpm、yarn、bun、nix 等包管理器\n\n资料来源：[README.md:1]()\n\n## 核心架构分层\n\nOpenSpec 采用分层架构设计，主要分为以下几层：\n\n| 层级 | 职责 | 关键模块 |\n|------|------|----------|\n| CLI 层 | 命令行接口，接收用户指令 | 主入口、命令解析 |\n| 核心层 | 业务逻辑处理 | 模式管理、工件图、模板系统 |\n| 适配层 | 工具集成 | 斜杠命令生成、工具适配器 |\n\n```mermaid\ngraph TD\n A[用户/AI 助手] --> B[CLI 交互层]\n B --> C[核心业务层]\n C --> D[Schema 管理]\n C --> E[工件图引擎]\n C --> F[模板系统]\n D --> G[文件系统]\n E --> G\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]()\n\n## Schema 系统\n\n### Schema 分层结构\n\nOpenSpec 采用三级 Schema 存储策略，优先级从高到低：\n\n```mermaid\ngraph TD\n A[Schema 解析请求] --> B{检查项目目录}\n B -->|存在| C[openspec/schemas/]\n B -->|不存在| D{检查用户目录}\n D -->|存在| E[~/.local/share/openspec/schemas/]\n D -->|不存在| F[npm 包内置 schemas/]\n```\n\n| 层级 | 路径 | 说明 |\n|------|------|------|\n| 项目级 | `/openspec/schemas//` | 项目本地自定义模式 |\n| 用户级 | `~/.local/share/openspec/schemas//` | 用户级别的覆盖配置 |\n| 包级 | `/schemas//` | 包内置默认模式 |\n\n**优先级规则：** 当项目本地 schema 与内置 schema 名称相同时，项目本地版本优先。\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:3]()\n\n### Schema 解析顺序\n\n工件 Schema 的解析遵循明确的优先级顺序：\n\n1. `--schema` CLI 参数（显式覆盖）\n2. `openspec/changes//.openspec.yaml`（变更级别绑定）\n3. `openspec/config.yaml` 的 schema 字段（项目默认）\n4. `\"spec-driven\"`（硬编码回退值）\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:4]()\n\n## 工件图系统\n\n### 工件类型\n\nOpenSpec 定义了标准化工件类型，每个变更包含以下工件：\n\n| 工件 ID | 生成文件 | 依赖 | 说明 |\n|---------|----------|------|------|\n| proposal | proposal.md | 无 | 变更提案和动机 |\n| specs | specs/*.md | proposal | 需求规格说明 |\n| design | design.md | proposal, specs | 技术设计方案 |\n| tasks | tasks.md | specs, design | 实施任务清单 |\n| apply | - | 所有工件 | 应用/执行指令 |\n\n资料来源：[schemas/spec-driven/schema.yaml:1]()\n\n### 工件状态追踪\n\n工件图引擎负责追踪每个工件的状态，状态包括：\n\n- **ready**：可以开始创建\n- **blocked**：等待前置依赖完成\n- **done**：已完成\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n D --> E[apply]\n \n A --> C\n B --> D\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:5]()\n\n### 指令加载机制\n\n指令加载器负责组装动态指令，包含三个层次：\n\n1. **Context（上下文）**：来自 `config.yaml` 的项目背景信息\n2. **Rules（规则）**：工件特定的约束条件\n3. **Template（模板）**：输出文件的实际结构\n\n```typescript\n// 指令组装流程\nlet enrichedInstruction = '';\n\n// 添加上下文（所有工件）\nif (projectConfig?.context) {\n enrichedInstruction += `\\n${projectConfig.context}\\n\\n\\n`;\n}\n\n// 添加规则（仅限匹配的工件）\nconst rulesForArtifact = projectConfig?.rules?.[artifactId];\nif (rulesForArtifact) {\n enrichedInstruction += `\\n${rulesForArtifact.join('\\n')}\\n\\n\\n`;\n}\n\n// 添加原始模板\nenrichedInstruction += `\\n${baseInstructions.template}\\n`;\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1]()\n\n## 命令生成系统\n\n### 斜杠命令架构\n\nOpenSpec 通过适配器模式支持 25+ AI 工具的斜杠命令：\n\n```mermaid\ngraph TD\n A[TemplateManager] --> B[SlashCommandConfigurator]\n B --> C[Claude Code 适配器]\n B --> D[Cursor 适配器]\n B --> E[Codex 适配器]\n B --> F[其他工具适配器...]\n \n C --> G[.claude/commands/openspec/]\n D --> H[.cursor/commands/]\n E --> I[项目配置]\n```\n\n**命令命名约定：**\n- Claude Code：使用命名空间 `/openspec/proposal`、`/openspec/apply`\n- Cursor：使用扁平命名 `/openspec-proposal`\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n### 文件标记规范\n\n斜杠命令文件必须包含特定标记以确保可被正确识别和更新：\n\n```markdown\n---\n# Frontmatter（工具特定配置）\n---\n\n...命令正文内容...\n\n```\n\n**关键规则：**\n- 标记仅包裹 Markdown 正文内容\n- Frontmatter 必须位于标记之前\n- 避免在 YAML 块内插入标记\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n## 模板系统\n\n### 模板存储结构\n\n模板采用 Markdown 格式存储，结构清晰：\n\n```markdown\n---\nchange: \nartifact: \nschema: \noutput: \n---\n\n## Dependencies\n- [x] (依赖列表)\n\n## Next Steps\n下一步操作说明\n\n---\n\n[原始模板内容...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]()\n\n### 模板引擎特点\n\n| 特性 | 说明 |\n|------|------|\n| 无需模板引擎 | 使用简单字符串拼接 |\n| 上下文注入 | 在模板前添加上下文信息 |\n| 清晰分隔 | 保持模板和注入内容的边界 |\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:4]()\n\n## 工作流系统\n\n### 标准工作流程\n\n```mermaid\ngraph TD\n A[/opsx:propose] --> B[创建提案]\n B --> C[/opsx:continue]\n C --> D[创建 specs]\n D --> E[创建 design]\n E --> F[创建 tasks]\n F --> G[/opsx:apply]\n G --> H[执行任务]\n H --> I[/opsx:archive]\n I --> J[归档到 archive/]\n```\n\n### 动作命令映射\n\n| 命令 | 功能 |\n|------|------|\n| `/opsx:explore` | 在提交变更前思考和探索想法 |\n| `/opsx:new` | 开始一个新变更 |\n| `/opsx:continue` | 逐步创建工件（单步式） |\n| `/opsx:propose` | 创建完整的变更结构 |\n| `/opsx:ff` | 快进到下一个待处理的工件 |\n| `/opsx:verify` | 验证变更状态 |\n| `/opsx:bulk-archive` | 批量归档 |\n| `/opsx:onboard` | 新项目引导 |\n| `/opsx:archive` | 归档已完成的工作 |\n\n资料来源：[README.md:1]()\n\n## 项目配置\n\n### config.yaml 结构\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n 项目约定: ...\n\nschema: spec-driven # 默认 schema 名称\n\nrules:\n proposal: # 提案工件规则\n - Include risk assessment\n specs: # 规格工件规则\n - Use Given/When/Then format\n```\n\n### 配置注入格式\n\nOpenSpec 使用 XML 风格的标签进行配置注入：\n\n```xml\n\n技术栈: TypeScript, React\n\n\n\n- Include rollback plan\n\n\n\n## Summary\n...\n\n```\n\n**设计决策：**\n- 使用 XML 标签避免与 Markdown 内容冲突\n- 便于 AI 代理解析结构\n- 与代码库中特殊部分现有模式匹配\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:3]()\n\n## 变更目录结构\n\n每个变更创建独立的文件夹结构：\n\n```\nopenspec/\n├── config.yaml # 项目配置\n├── changes/\n│ ├── /\n│ │ ├── .openspec.yaml # 变更级别 schema 绑定\n│ │ ├── proposal.md # 提案文档\n│ │ ├── specs/ # 规格文档目录\n│ │ │ └── *.md\n│ │ ├── design.md # 设计文档\n│ │ └── tasks.md # 任务清单\n│ └── archive/ # 归档目录\n│ └── YYYY-MM-DD-/\n└── schemas/ # 项目本地 schemas\n └── /\n```\n\n**设计原则：**\n- 每个变更独立存放，职责清晰\n- 归档保留历史版本\n- 镜像 `.github/` 目录结构\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:2]()\n\n## CLI 命令参考\n\n### 核心命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec init` | 初始化项目 |\n| `openspec list` | 列出活跃变更 |\n| `openspec show ` | 显示变更详情 |\n| `openspec view` | 交互式仪表板 |\n| `openspec archive ` | 归档变更 |\n| `openspec config profile` | 配置工作流配置 |\n| `openspec experimental` | 启用实验性功能 |\n| `openspec instructions ` | 获取工件指令 |\n| `openspec schemas` | 管理 schemas |\n\n### Schema 管理命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec schema init ` | 创建新 schema |\n| `openspec schema which` | 显示当前 schema |\n| `openspec schema fork ` | 派生现有 schema |\n\n资料来源：[README.md:1]()\n\n## 安全与验证\n\n### 路径遍历防护\n\n所有用户提供的路径必须经过清理，防止路径遍历攻击。\n\n```typescript\n// 安全检查清单\n- 检查文件写入权限\n- 不使用 --force 标志不覆盖现有文件\n- 清理模板中的用户输入\n```\n\n### 初始化事务处理\n\n```typescript\ninterface InitTransaction {\n createdPaths: string[];\n rollback(): Promise; // 失败时回滚\n commit(): Promise; // 成功时提交\n}\n```\n\n**设计目标：**\n- 防止部分安装\n- 清晰的错误状态\n- 更好的用户体验\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1]()\n\n## 扩展性设计\n\n### 社区 Schema\n\nOpenSpec 支持第三方 Schema 包分发，类似于 `github/spec-kit` 的扩展目录模式：\n\n```bash\n# 第三方 Schema 仓库结构\n/\n├── schemas/\n│ └── /\n│ ├── schema.yaml\n│ └── templates/\n└── README.md\n```\n\n### 适配器扩展\n\n新增工具支持只需实现适配器接口：\n\n```typescript\ninterface ToolAdapter {\n getTargets(): Array<{ path: string; kind: 'slash'; id: string }>;\n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1]()\n\n## 贡献指南\n\n| 操作 | 命令 |\n|------|------|\n| 安装依赖 | `pnpm install` |\n| 构建 | `pnpm run build` |\n| 测试 | `pnpm test` |\n| 本地开发 CLI | `pnpm run dev` 或 `pnpm run dev:cli` |\n| 提交规范 | 常规提交格式：`type(scope): subject` |\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 核心模块详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [变更工作流](#page-change-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts)\n- [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts)\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/template.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/template.ts)\n- [src/core/artifact-graph/context.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/context.ts)\n- [src/core/artifact-graph/instructions.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instructions.ts)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n \n\n# 核心模块详解\n\n## 概述\n\nOpenSpec 的核心模块围绕**变更工件图（Artifact Graph）** 构建，提供了从规范定义、工件管理到指令生成的完整技术栈。核心模块采用 TypeScript/Zod 实现类型安全，使用 YAML 定义规范结构，通过模块化设计支持多 schema 扩展。\n\n核心模块的架构设计遵循以下原则：\n\n- **无模板引擎依赖**：使用简单的字符串拼接实现上下文注入\n- **Schema 驱动的资源解析**：支持项目级、用户级、包级三层 Schema 解析顺序\n- **动态状态检测**：基于工件文件存在性自动判断阻塞状态\n- **Zod Schema 验证**：运行时类型检查确保数据完整性\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## 核心模块架构\n\n### 模块目录结构\n\n```\nsrc/core/artifact-graph/\n├── index.ts # 模块导出入口\n├── types.ts # 类型定义（Zod Schema）\n├── schema.ts # Schema YAML 解析器\n├── graph.ts # 工件图与拓扑排序\n├── state.ts # 状态检测逻辑\n├── template.ts # 模板加载器\n├── context.ts # ChangeContext 加载器\n└── instructions.ts # 指令丰富化与格式化\n```\n\n### 核心组件关系图\n\n```mermaid\ngraph TD\n A[Schema.yaml] -->|解析| B[ArtifactGraph]\n B -->|拓扑排序| C[getBuildOrder]\n B -->|状态检测| D[State Detection]\n D --> E{工件状态}\n \n F[Change Context] -->|注入| G[Instructions]\n H[Project Config] -->|上下文| G\n I[Template] -->|内容| G\n \n E -->|done/ready/blocked| J[Status Output]\n G -->|富化指令| K[Agent Output]\n```\n\n## Schema 系统\n\n### Schema 解析层级\n\nOpenSpec 采用三级 Schema 解析顺序，从高优先级到低优先级排列：\n\n| 优先级 | 来源 | 路径 |\n|--------|------|------|\n| 1 (最高) | 项目本地覆盖 | `/openspec/schemas//` |\n| 2 | 用户配置 | `~/.local/share/openspec/schemas//` |\n| 3 (最低) | 包内置 | `/schemas//` |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md]()\n\n### 工件依赖模型\n\n每个 Schema 定义一组工件及其依赖关系：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n template: \"proposal.md\"\n requires: []\n \n - id: specs\n generates: \"specs/*.md\"\n template: \"specs.md\"\n requires:\n - proposal\n \n - id: design\n generates: \"design.md\"\n template: \"design.md\"\n requires:\n - proposal\n - specs\n \n - id: tasks\n generates: \"tasks.md\"\n template: \"tasks.md\"\n requires:\n - specs\n - design\n```\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## 类型系统\n\n### 核心类型定义\n\n`types.ts` 使用 Zod 定义所有类型约束：\n\n```typescript\n// 工件定义 Schema\nconst ArtifactSchema = z.object({\n id: z.string(),\n generates: z.string(),\n template: z.string(),\n requires: z.array(z.string()),\n});\n\n// Schema YAML 主结构\nconst SchemaYamlSchema = z.object({\n name: z.string(),\n version: z.number(),\n artifacts: z.array(ArtifactSchema),\n});\n```\n\n### 运行时状态类型\n\n| 类型名 | 描述 | 结构 |\n|--------|------|------|\n| `CompletedSet` | 已完成工件集合 | `Set` |\n| `BlockedArtifacts` | 阻塞中的工件映射 | `Record` |\n| `ArtifactGraphResult` | 图操作返回结果 | 包含 `graph`、`buildOrder`、`artifacts` |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]()\n\n## 工件图核心\n\n### ArtifactGraph 类\n\n工件图类封装所有图相关操作：\n\n```typescript\nexport class ArtifactGraph {\n // 从 YAML 文件加载\n static fromYaml(path: string): ArtifactGraph;\n \n // 获取拓扑排序后的构建顺序\n getBuildOrder(): string[];\n \n // 获取单个工件定义\n getArtifact(id: string): ArtifactSchema | undefined;\n \n // 列出所有工件\n getAllArtifacts(): ArtifactSchema[];\n}\n```\n\n### 拓扑排序算法\n\n使用 Kahn 算法实现拓扑排序：\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n A --> C[design]\n B --> D[tasks]\n C --> D\n \n E[Kahn排序] --> F[proposal]\n F --> G[specs/design]\n G --> H[tasks]\n```\n\n**排序特性**：\n- 保证依赖永远在被依赖项之前\n- 循环依赖检测：`\"Cyclic dependency detected: A → B → C → A\"`\n- 无环图验证\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md]()\n\n## Schema 解析器\n\n### schema.ts 功能\n\n| 功能 | 描述 |\n|------|------|\n| YAML 加载 | 使用 `fs.readFileSync` 读取并 `yaml.parse` |\n| Zod 验证 | `.safeParse()` 验证结构 |\n| 依赖引用验证 | 确保 `requires` 引用有效 artifact ID |\n| 重复 ID 检测 | 拒绝重复的 artifact ID |\n| 循环依赖检测 | 构建依赖图时检测环 |\n\n### 验证规则\n\n```typescript\n// 依赖引用验证伪代码\nfor (const artifact of artifacts) {\n for (const reqId of artifact.requires) {\n if (!artifacts.find(a => a.id === reqId)) {\n throw new Error(`Invalid reference: ${artifact.id} requires ${reqId}`);\n }\n }\n}\n```\n\n## 状态检测系统\n\n### 状态枚举\n\n| 状态 | 含义 | 触发条件 |\n|------|------|----------|\n| `done` | 已完成 | 工件文件存在 |\n| `ready` | 就绪可创建 | 所有依赖均为 `done` |\n| `blocked` | 阻塞 | 至少一个依赖为 `blocked` 或不存在 |\n\n### 状态输出格式\n\n```markdown\n## Change: add-auth (spec-driven)\n\n| Artifact | Status | Output |\n|----------|--------|--------|\n| proposal | done | proposal.md |\n| specs | ready | specs/*.md |\n| design | blocked (needs: proposal) | design.md |\n| tasks | blocked (needs: specs, design) | tasks.md |\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## 指令加载系统\n\n### 指令生成流程\n\n```mermaid\ngraph TD\n A[loadInstructions] --> B[resolveSchema]\n B --> C[loadTemplate]\n C --> D[loadChangeContext]\n D --> E[loadProjectConfig]\n E --> F[injectContext]\n F --> G[injectRules]\n G --> H[formatXML]\n H --> I[返回富化指令]\n```\n\n### 上下文注入格式\n\n```xml\n\nTech stack: TypeScript, React\nProject conventions: ...\n\n\n\n- Use Given/When/Then format for scenarios\n- Reference existing patterns before inventing new ones\n\n\n\n## Summary\n...\n\n```\n\n### 指令丰富化逻辑\n\n| 组件 | 注入位置 | 条件 |\n|------|----------|------|\n| `context` | 所有工件 | `projectConfig.context` 存在 |\n| `rules` | 特定工件 | `projectConfig.rules[artifactId]` 存在 |\n| `template` | 所有工件 | 始终 |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## 包路径解析\n\n### 跨环境路径解析\n\n```typescript\nfunction getPackageSchemasDir(): string {\n const currentFile = fileURLToPath(import.meta.url);\n // 从 src/core/artifact-graph/ 导航到包根目录\n return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');\n}\n```\n\n**设计决策**：\n- 使用 `import.meta.url` 而非硬编码路径\n- 适配 ESM 模块系统\n- 相对路径计算确保包内引用正确\n\n## 项目配置集成\n\n### 配置 Schema 验证\n\n项目配置文件 `openspec/config.yaml` 结构：\n\n```yaml\nschema: spec-driven # 默认 schema\ncontext: | # 注入到所有工件的上下文\n Tech stack: TypeScript\n Database: PostgreSQL\nrules: # 规则（按工件 ID）\n specs:\n - Use Given/When/Then format\n design:\n - Include rollback plan\n```\n\n### Schema 解析优先级\n\n```\n1. --schema CLI 参数 (最高优先级)\n2. .openspec.yaml (change 目录内)\n3. openspec/config.yaml schema 字段\n4. \"spec-driven\" (硬编码默认值)\n```\n\n## Schema 解析器详情\n\n### schema.ts 核心实现\n\n| 功能点 | 实现方式 |\n|--------|----------|\n| YAML 解析 | `yaml.parse(content)` |\n| 类型验证 | Zod `.safeParse()` |\n| 错误处理 | 自定义错误消息 |\n| 文件缓存 | 可选内存缓存 |\n\n### 循环依赖检测算法\n\n```typescript\nfunction detectCycles(artifacts: Artifact[]): string[] | null {\n const visited = new Set();\n const recursionStack = new Set();\n \n for (const artifact of artifacts) {\n if (hasCycle(artifact.id, artifacts, visited, recursionStack)) {\n return buildCyclePath(recursionStack);\n }\n }\n return null;\n}\n```\n\n## 状态检测实现\n\n### state.ts 文件结构\n\n```typescript\n// 状态检测核心逻辑\nexport interface StateDetectionResult {\n completed: CompletedSet;\n blocked: BlockedArtifacts;\n ready: string[];\n}\n\n// 文件存在性检查\nfunction checkArtifactExists(artifact: Artifact, changeDir: string): boolean {\n const path = path.join(changeDir, artifact.generates);\n return fs.existsSync(path);\n}\n```\n\n### 状态计算伪代码\n\n```typescript\nfunction detectState(graph: ArtifactGraph, changeDir: string): StateResult {\n const completed = new Set();\n const blocked: Record = {};\n const ready: string[] = [];\n \n for (const artifact of graph.getAllArtifacts()) {\n if (fileExists(artifact, changeDir)) {\n completed.add(artifact.id);\n } else if (canBuild(artifact, completed)) {\n ready.push(artifact.id);\n } else {\n blocked[artifact.id] = getMissingDeps(artifact, completed);\n }\n }\n \n return { completed, blocked, ready };\n}\n```\n\n## Apply 阶段支持\n\n### ApplyPhase Schema 扩展\n\n```yaml\nartifacts:\n - id: proposal\n # ...\napply:\n requires:\n - proposal\n - specs\n - design\n - tasks\n tracks: progress\n instruction: \"All artifacts complete. Proceed with implementation.\"\n```\n\n### 动态工件检测\n\n与硬编码路径不同，Apply 指令检查逻辑：\n\n```typescript\n// 从 schema 加载要求，而非硬编码\nconst schema = await resolveSchema(schemaName);\nconst applyConfig = schema.apply;\n\n// 动态检查所有要求的工件\nfor (const requiredId of applyConfig.requires) {\n if (!completed.has(requiredId)) {\n return { ready: false, missing: requiredId };\n }\n}\n```\n\n## 最佳实践\n\n### Schema 设计原则\n\n1. **最小依赖**：每个工件只依赖真正需要的前置项\n2. **清晰命名**：artifact ID 使用 kebab-case\n3. **模板分离**：每个 schema 拥有独立的 `templates/` 目录\n4. **版本控制**：schema.yaml 包含 version 字段便于迁移\n\n### 指令注入最佳实践\n\n| 场景 | 推荐做法 |\n|------|----------|\n| 项目级上下文 | 放在 `config.yaml.context` |\n| 工件特定规则 | 使用 `config.yaml.rules[artifactId]` |\n| 变更描述 | 使用 ChangeContext 文件 |\n| 避免冲突 | 使用 XML 标签 `` 而非 Markdown 标题 |\n\n### 错误处理\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| Schema 未找到 | 按优先级继续搜索下一级 |\n| YAML 解析失败 | 显示具体行号和错误 |\n| 循环依赖 | 终止并显示环路径 |\n| 验证失败 | 警告但不阻止操作 |\n\n## 总结\n\nOpenSpec 的核心模块通过**工件图（Artifact Graph）** 这一核心概念，将变更管理抽象为工件的有向无环图（DAG）。配合 Zod 类型系统、YAML Schema 定义和模块化的解析器架构，实现了：\n\n- **声明式规范**：通过 schema.yaml 定义工件结构和依赖\n- **运行时验证**：状态检测确保按序创建工件\n- **灵活扩展**：支持项目级、用户级、包级三层 Schema 定制\n- **上下文感知**：项目配置和变更上下文自动注入到指令中\n\n这套架构既保持了简单性（无模板引擎依赖），又提供了足够的灵活性来支持复杂的团队工作流程。\n\n---\n\n\n\n## 变更工作流\n\n### 相关页面\n\n相关主题：[工件图系统](#page-artifact-graph), [工作流模板](#page-workflow-templates), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/templates/workflows/propose.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/propose.ts)\n- [src/core/templates/workflows/apply-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/apply-change.ts)\n- [src/core/templates/workflows/archive-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts)\n- [src/core/parsers/change-parser.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/parsers/change-parser.ts)\n- [src/core/archive.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/archive.ts)\n- [src/commands/change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/change.ts)\n \n\n# 变更工作流\n\n## 概述\n\n变更工作流（Change Workflow）是 OpenSpec 框架的核心功能，它定义了一套标准化的流程，用于管理项目变更的生命周期。该工作流涵盖从变更提议、规格编写、设计文档、任务规划到实现完成并归档的全过程。\n\nOpenSpec 的变更工作流采用 **提案 → 应用 → 归档** 的三阶段模式，每个阶段都有明确的输入、输出和验收标准，确保人类开发者和 AI 助手之间能够高效协作。\n\n## 工作流架构\n\n### 整体流程图\n\n```mermaid\ngraph TD\n A[开始新变更] --> B{选择工具}\n B --> C[Claude Code]\n B --> D[Cursor]\n B --> E[VS Code]\n B --> F[其他工具]\n \n C --> G[/opsx:propose]\n D --> H[/openspec-proposal]\n E --> I[自然语言请求]\n F --> I\n \n G --> J[创建变更目录]\n H --> J\n I --> J\n \n J --> K[proposal.md]\n K --> L[specs/ 目录]\n L --> M[design.md]\n M --> N[tasks.md]\n N --> O{实现完成?}\n O -->|否| P[继续开发]\n P --> N\n O -->|是| Q[/opsx:archive]\n Q --> R[归档到 archive/]\n R --> S[更新主规格文档]\n \n style G fill:#e1f5fe\n style H fill:#e1f5fe\n style I fill:#fff3e0\n style Q fill:#c8e6c9\n```\n\n### 变更目录结构\n\n每个变更在 `openspec/changes/{change-id}/` 目录下创建完整的工作空间：\n\n| 文件/目录 | 说明 | 必需 |\n|-----------|------|------|\n| `proposal.md` | 变更提案，说明变更原因和目标 | ✓ |\n| `design.md` | 技术设计方案 | 可选 |\n| `tasks.md` | 实现任务清单 | ✓ |\n| `specs/` | 规格变更增量文件 | 可选 |\n\n归档后，变更目录移至 `openspec/changes/archive/{date}-{change-id}/`。\n\n## 提案阶段（Propose）\n\n### 触发方式\n\n不同 AI 工具通过不同的命令触发提案创建：\n\n| 工具类型 | 命令格式 | 说明 |\n|----------|----------|------|\n| Claude Code | `/opsx:propose ` | 使用斜杠命令 |\n| Cursor | `/openspec-proposal ` | 扁平化前缀命名 |\n| 其他工具 | 自然语言请求 | \"创建一个 OpenSpec 提案\" |\n\n### 提案模板内容\n\n提案文件包含以下标准结构：\n\n```yaml\n---\nproposal\ncategory: OpenSpec\ndescription: Scaffold a new OpenSpec change and validate strictly.\n---\n```\n\n模板内容需包含：\n- **Guardrails（防护规则）**：1-2 个澄清问题\n- **Minimal-complexity rules（最小复杂度规则）**\n- **Step list（步骤列表）**：针对提案阶段的操作指令\n- **Pointers（指针）**：指向 `openspec show`、`openspec list` 等命令\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md]()\n\n### 提案生成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant AI as AI 助手\n participant CLI as OpenSpec CLI\n \n User->>AI: /opsx:propose add-dark-mode\n AI->>CLI: 解析命令\n CLI->>AI: 返回指令模板\n AI->>AI: 创建变更目录结构\n AI->>AI: 生成 proposal.md\n AI->>AI: 生成 specs/ 目录\n AI->>AI: 生成 design.md\n AI->>AI: 生成 tasks.md\n AI->>User: 变更已创建\n```\n\n## 规格阶段（Specs）\n\n### 规格文件格式\n\n规格文件使用 Markdown 格式，遵循严格的头部层级结构：\n\n```markdown\n## ADDED Requirements\n\n### Requirement: <需求名称>\n<需求描述，使用 SHALL/MUST 描述规范>\n\n#### Scenario: <场景名称>\n- **WHEN** <触发条件>\n- **THEN** <预期结果>\n- **AND** <附加结果>\n```\n\n### 关键格式要求\n\n| 要求 | 说明 | 重要性 |\n|------|------|--------|\n| 需求头部 | 使用 `### Requirement:` | 必须 |\n| 规范语气 | 使用 SHALL/MUST，避免 should/may | 必须 |\n| 场景头部 | 必须使用 `#### Scenario:`（4个#） | 关键 |\n| 场景格式 | 使用 `- **WHEN**` / `- **THEN**` 格式 | 必须 |\n\n> ⚠️ **常见错误**：使用 3 个 `#` 或使用列表格式会导致场景解析失败。\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n### 规格操作类型\n\n规格变更支持以下操作类型：\n\n| 操作 | 说明 | 示例 |\n|------|------|------|\n| `ADDED` | 新增需求 | 添加新功能 |\n| `MODIFIED` | 修改现有需求 | 更改现有行为 |\n| `REMOVED` | 删除需求 | 移除废弃功能 |\n| `RENAMED` | 重命名需求 | 迁移命名 |\n\n### MODIFIED 工作流\n\n修改现有需求时，必须遵循以下步骤：\n\n1. 在 `openspec/specs//spec.md` 中定位现有需求\n2. 复制**完整**的需求块（从 `### Requirement:` 到所有场景）\n3. 粘贴到 `## MODIFIED Requirements` 下并编辑\n4. 确保头部文本完全匹配（忽略空白差异）\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## 应用阶段（Apply）\n\n### 触发方式\n\n| 工具 | 命令格式 |\n|------|----------|\n| Claude Code | `/opsx:apply ` |\n| Cursor | `/openspec-apply ` |\n| 其他 | 自然语言请求 |\n\n### 应用指令生成\n\n应用阶段指令的生成遵循以下流程：\n\n```mermaid\ngraph TD\n A[用户请求应用] --> B[加载变更元数据]\n B --> C[检查 design.md 是否存在]\n C --> D[检查 tasks.md 是否存在]\n D --> E[构建上下文文件列表]\n E --> F[生成应用指令]\n F --> G[返回指令给 AI]\n G --> H[AI 执行任务]\n H --> I[标记完成的任务]\n```\n\n### 应用指令结构\n\n```typescript\n{\n instruction: \"执行以下任务的指令\",\n contextFiles: [\n \"proposal.md\",\n \"design.md\",\n \"tasks.md\",\n \"specs/**/*.md\"\n ],\n tracks: [\"Task 1.1 ✓\", \"Task 1.2 ✓\", ...]\n}\n```\n\n## 归档阶段（Archive）\n\n### 归档流程\n\n```mermaid\ngraph LR\n A[openspec/changes/{id}/] --> B[验证所有任务完成]\n B --> C{验证通过?}\n C -->|是| D[移动到 archive/]\n C -->|否| E[返回错误信息]\n D --> F[按日期命名子目录]\n D --> G[更新主规格文档]\n```\n\n### 归档命令\n\n```bash\n# 标准归档\nopenspec archive \n\n# 非交互式归档（跳过确认）\nopenspec archive --yes\n\n# 缩写形式\nopenspec archive -y\n```\n\n### 带参数的归档\n\n部分工具支持传入变更 ID 参数：\n\n```bash\n/openspec:archive \n```\n\n参数处理逻辑：\n1. 验证 `$ARGUMENTS` 占位符是否存在\n2. 解析传入的变更 ID\n3. 使用 `openspec list` 验证变更存在\n4. 执行归档操作\n\n资料来源：[openspec/changes/archive/2025-10-22-add-archive-command-arguments/tasks.md]()\n\n### 归档后操作\n\n归档完成后，系统自动执行以下操作：\n\n1. 将变更目录移动到 `openspec/changes/archive/{YYYY-MM-DD}-{change-id}/`\n2. 从规格增量文件中提取变更，更新到主规格文档\n3. 从任务列表中移除已完成的变更\n\n## CLI 命令参考\n\n### 变更管理命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec list` | 列出活跃的变更 |\n| `openspec show ` | 显示变更详情 |\n| `openspec validate ` | 验证规格格式和结构 |\n| `openspec archive [--yes]` | 归档完成的变更 |\n\n### 查看命令选项\n\n```bash\n# 查看变更详情\nopenspec show \n\n# JSON 格式输出（仅显示增量）\nopenspec show --json --deltas-only\n\n# 严格验证模式\nopenspec validate --strict\n```\n\n## 工具支持矩阵\n\n| 工具 | 提案命令 | 应用命令 | 归档命令 |\n|------|----------|----------|----------|\n| Claude Code | `/opsx:propose` | `/opsx:apply` | `/opsx:archive` |\n| Cursor | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` |\n| Roo Code | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` |\n| CodeBuddy | `/openspec/proposal` | `/openspec/apply` | `/openspec/archive` |\n| Windsurf | `/openspec-proposal` | `/openspec-apply` | `/openspec-archive` |\n| Kilo Code | `/openspec-proposal.md` | `/openspec-apply.md` | `/openspec-archive.md` |\n| 其他 | 自然语言 | 自然语言 | 自然语言 |\n\n> 注：Kilo Code 会自动发现团队工作流，命令需保存为 `.kilocode/workflows/` 下的 Markdown 文件。\n\n## 最佳实践\n\n### 1. 变更命名规范\n\n- 使用 kebab-case 格式：`add-dark-mode`、`fix-auth-bug`\n- 简洁明了，反映变更本质\n- 避免使用 `new-feature`、`update-1` 等模糊名称\n\n### 2. 规格编写要点\n\n- 每个需求必须有至少一个场景\n- 场景描述需具体、可测试\n- 使用 Gherkin 语法（Given/When/Then）保持一致性\n\n### 3. 任务拆解建议\n\n- 任务粒度适中，便于进度跟踪\n- 包含验证步骤，确保实现正确\n- 标记依赖关系，合理安排执行顺序\n\n### 4. 变更周期管理\n\n```mermaid\ngraph TD\n A[提案] --> B{规格评审}\n B -->|通过| C[设计]\n B -->|不通过| A\n C --> D{设计评审}\n D -->|通过| E[任务规划]\n D -->|不通过| C\n E --> F[实现]\n F --> G{测试}\n G -->|通过| H[归档]\n G -->|失败| F\n```\n\n## 常见问题排查\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| \"变更必须有至少一个增量\" | `specs/` 目录不存在或为空 | 确保 `specs/` 目录包含 `.md` 文件 |\n| \"需求必须有至少一个场景\" | 场景格式错误 | 检查使用 `#### Scenario:`（4个#） |\n| 场景解析静默失败 | 头部格式不正确 | 使用 `openspec show --json --deltas-only` 调试 |\n| 归档失败 | 存在未完成任务 | 完成所有任务或使用 `--skip-checks` |\n\n---\n\n\n\n## 工件图系统\n\n### 相关页面\n\n相关主题：[变更工作流](#page-change-workflow), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts)\n- [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts)\n- [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/types.ts)\n \n\n# 工件图系统\n\n## 概述\n\n工件图系统（Artifact Graph System）是 OpenSpec 的核心子系统，负责管理软件开发变更中的工件（Artifact）及其依赖关系。该系统通过图结构建模工件的创建顺序、依赖状态和生成路径，实现动态指令生成和状态追踪。\n\n**核心能力：**\n\n- 将工件定义为节点，依赖关系定义为边，构建有向无环图（DAG）\n- 基于拓扑排序确定工件创建顺序\n- 实时检测工件完成状态（已完成、就绪、阻塞）\n- 动态加载模式匹配的指令模板\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 架构设计\n\n### 系统分层\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n CLI[CLI 命令]\n Workflow[工作流模板]\n end\n \n subgraph \"核心层\"\n IG[工件图]\n IL[指令加载器]\n ST[状态追踪]\n RS[模式解析]\n end\n \n subgraph \"数据层\"\n YAML[Schema YAML]\n TMPL[模板文件]\n CFG[项目配置]\n end\n \n CLI --> IG\n CLI --> IL\n Workflow --> IL\n IG --> IL\n IG --> ST\n IG --> RS\n RS --> YAML\n IL --> TMPL\n IL --> CFG\n \n style IG fill:#e1f5fe\n style IL fill:#e8f5e8\n style ST fill:#fff3e0\n style RS fill:#f3e5f5\n```\n\n### 目录结构\n\n```\nsrc/core/artifact-graph/\n├── index.ts # 公共导出\n├── types.ts # Zod 类型定义和接口\n├── graph.ts # ArtifactGraph 类\n├── state.ts # 状态检测逻辑\n├── resolver.ts # Schema 解析（全局 → 内置）\n├── instruction-loader.ts # 模板加载与指令丰富\n├── outputs.ts # 输出格式化\n└── schemas/ # 内置模式定义\n ├── spec-driven.yaml\n └── tdd.yaml\n```\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 核心类型定义\n\n### Schema 结构\n\n模式（Schema）是定义工件及其依赖关系的 YAML 配置文件，位于 `src/core/artifact-graph/types.ts`。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `name` | string | 模式名称 |\n| `version` | number | 模式版本 |\n| `description` | string | 模式描述 |\n| `artifacts` | Artifact[] | 工件定义数组 |\n| `apply` | ApplyPhase | 可选的 apply 阶段配置 |\n\n**Artifact 对象结构：**\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `id` | string | 工件唯一标识符 |\n| `generates` | string | 生成的文件路径 |\n| `template` | string | 模板文件路径（相对） |\n| `requires` | string[] | 前置依赖工件 ID |\n| `description` | string | 工件描述 |\n\n资料来源：[src/core/artifact-graph/types.ts](src/core/artifact-graph/types.ts)\n\n### 运行时状态类型\n\n```typescript\n// 已完成的工件 ID 集合\ntype CompletedSet = Set;\n\n// 阻塞工件：artifact → 未满足的依赖列表\ntype BlockedArtifacts = Map;\n\n// 工件图结果\ninterface ArtifactGraphResult {\n completed: string[]; // 已完成的工件\n ready: string[]; // 就绪可创建的工件\n blocked: BlockedArtifacts; // 阻塞的工件及其原因\n buildOrder: string[]; // 构建顺序（拓扑排序结果）\n}\n```\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md)\n\n---\n\n## 工件图类\n\n`ArtifactGraph` 类是系统的核心组件，位于 `src/core/artifact-graph/graph.ts`。\n\n### 主要方法\n\n| 方法 | 返回值 | 功能描述 |\n|------|--------|----------|\n| `fromYaml(path)` | `ArtifactGraph` | 从 Schema YAML 文件加载工件图 |\n| `getBuildOrder()` | `string[]` | 获取拓扑排序后的工件顺序 |\n| `getArtifact(id)` | `Artifact \\| undefined` | 获取单个工件定义 |\n| `getAllArtifacts()` | `Artifact[]` | 获取所有工件定义 |\n\n### 拓扑排序算法\n\n系统使用 **Kahn算法**（Kahn's Algorithm）进行拓扑排序：\n\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n \n style A fill:#4caf50\n style B fill:#ffeb3b\n style C fill:#ffeb3b\n style D fill:#ff9800\n```\n\n**算法特点：**\n\n- 自动检测循环依赖，检测到时抛出明确错误\n- 错误格式：`Cyclic dependency detected: A → B → C → A`\n- 返回的顺序保证所有依赖在依赖者之前\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n---\n\n## 状态检测\n\n状态检测模块负责判断工件的就绪状态，位于 `src/core/artifact-graph/state.ts`。\n\n### 检测逻辑\n\n```mermaid\ngraph TD\n START[检查工件] --> IS_BLOCKED{是否有未完成的依赖?}\n IS_BLOCKED -->|是| MISSING[标记为 blocked]\n IS_BLOCKED -->|否| HAS_OUTPUT{输出文件是否存在?}\n HAS_OUTPUT -->|是| COMPLETED[标记为 completed]\n HAS_OUTPUT -->|否| READY[标记为 ready]\n \n style COMPLETED fill:#4caf50\n style READY fill:#ffeb3b\n style MISSING fill:#ff9800\n```\n\n### 状态类型\n\n| 状态 | 描述 | 条件 |\n|------|------|------|\n| `completed` | 已完成 | 所有前置依赖完成且输出文件存在 |\n| `ready` | 就绪 | 所有前置依赖完成但输出文件不存在 |\n| `blocked` | 阻塞 | 存在未完成的前置依赖 |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n---\n\n## Schema 解析\n\nSchema 解析器负责定位和加载模式定义，位于 `src/core/artifact-graph/resolver.ts`。\n\n### 解析路径优先级\n\n```mermaid\ngraph TD\n REQ[请求加载 Schema] --> GLOBAL{检查全局覆盖}\n GLOBAL -->|存在| GLOBAL_LOAD[加载全局 Schema]\n GLOBAL -->|不存在| BUILTIN{检查内置 Schema}\n BUILTIN -->|存在| BUILTIN_LOAD[加载内置 Schema]\n BUILTIN -->|不存在| ERROR[抛出错误]\n \n GLOBAL_LOAD --> RESULT[返回 Schema]\n BUILTIN_LOAD --> RESULT\n \n style GLOBAL_LOAD fill:#e1f5fe\n style BUILTIN_LOAD fill:#e8f5e8\n style ERROR fill:#ffcdd2\n```\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `${XDG_DATA_HOME}/openspec/schemas//schema.yaml` | 用户全局覆盖 |\n| 2 | `/schemas//schema.yaml` | 包内置 Schema |\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md](openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md)\n\n### 内置 Schema 示例\n\n**spec-driven 模式**（默认）：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n requires: []\n - id: specs\n generates: \"specs.md\"\n requires: [proposal]\n - id: design\n generates: \"design.md\"\n requires: [specs]\n - id: tasks\n generates: \"tasks.md\"\n requires: [specs, design]\napply:\n requires: [tasks]\n instruction: \"Read context files, work through pending tasks\"\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](schemas/spec-driven/schema.yaml)\n\n---\n\n## 指令加载器\n\n指令加载器负责将工件模板与变更上下文结合，生成最终指令，位于 `src/core/artifact-graph/instruction-loader.ts`。\n\n### 变更上下文\n\n```typescript\ninterface ChangeContext {\n changeName: string; // 变更名称\n changeDir: string; // 变更目录路径\n schemaName: string; // 使用的模式名\n graph: ArtifactGraph; // 工件图实例\n completed: CompletedSet; // 已完成工件集合\n}\n```\n\n### 指令结构\n\n```mermaid\ngraph LR\n TMPL[模板] --> CTX[上下文注入]\n RULES[规则] --> RULES_INJ[规则注入]\n CTX --> OUTPUT[最终指令]\n RULES_INJ --> OUTPUT\n \n style CTX fill:#e8f5e8\n style OUTPUT fill:#e1f5fe\n```\n\n### 输出格式\n\n生成的指令包含以下 XML 标签结构：\n\n| 标签 | 内容 | 说明 |\n|------|------|------|\n| `` | 工件元信息 | 包含 id, change, schema 属性 |\n| `` | 任务描述 | 要创建的工件说明 |\n| `` | 项目上下文 | 来自 config.yaml 的背景信息 |\n| `` | 约束规则 | 特定工件的行为约束 |\n| `` | 模板内容 | Schema 中定义的文件结构 |\n\n资料来源：[src/commands/workflow/instructions.ts](src/commands/workflow/instructions.ts)\n\n---\n\n## 项目配置集成\n\n工件图系统与项目配置（`config.yaml`）集成，支持上下文注入和规则约束。\n\n### 配置结构\n\n```yaml\nschema: spec-driven # 默认使用的 Schema\ncontext: | # 项目背景信息\n - 技术栈：Node.js, TypeScript\n - 代码风格：Google TypeScript Style Guide\nrules: # 工件特定规则\n specs:\n - 使用 Given/When/Then 格式编写场景\n - 每个需求必须有至少一个测试场景\n design:\n - 包含 API 接口设计\n - 包含数据库 schema 变更\n```\n\n### 规则验证\n\n规则在指令加载时进行惰性验证，确保：\n\n- 规则引用的工件 ID 存在于 Schema 中\n- 警告信息仅显示一次（会话级缓存）\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](openspec/changes/archive/2026-02-17-project-config/design.md)\n\n---\n\n## 使用示例\n\n### 1. 加载工件图\n\n```typescript\nimport { ArtifactGraph } from './core/artifact-graph';\n\nconst graph = ArtifactGraph.fromYaml('/path/to/spec-driven/schema.yaml');\nconst buildOrder = graph.getBuildOrder();\n// ['proposal', 'specs', 'design', 'tasks']\n```\n\n### 2. 获取工件状态\n\n```typescript\nimport { detectCompleted } from './core/artifact-graph/state';\n\nconst completed = detectCompleted(\n graph,\n '/path/to/change',\n ['proposal', 'specs'] // 已完成的工件\n);\n// 返回: { completed: [...], ready: [...], blocked: {...} }\n```\n\n### 3. 生成指令\n\n```typescript\nimport { loadInstructions } from './core/artifact-graph/instruction-loader';\n\nconst instructions = loadInstructions('add-auth', 'specs');\n// 输出包含 , , 的完整指令\n```\n\n---\n\n## 设计决策\n\n### 决策 1：纯函数优于类\n\n遵循 `resolver.ts` 和 `state.ts` 的模式，使用纯函数和简单接口：\n\n- 优点：无状态、易测试、无隐藏依赖\n- 缺点：需要显式传递上下文\n\n### 决策 2：无模板引擎\n\n采用简单的字符串拼接进行上下文注入：\n\n- 优点：无外部依赖、行为可预测\n- 缺点：复杂模板逻辑受限\n\n### 决策 3：Schema 目录化\n\nSchema 采用自包含目录结构：\n\n```\nschemas//\n├── schema.yaml\n└── templates/\n └── *.md\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md](openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md)\n\n---\n\n## 相关文档\n\n- [Getting Started](docs/getting-started.md) - 快速入门指南\n- [Workflows](docs/workflows.md) - 工作流程组合与模式\n- [Customization](docs/customization.md) - 自定义配置与社区 Schema\n\n---\n\n\n\n## AI工具集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n- [openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n \n\n# AI工具集成\n\n## 概述\n\nOpenSpec 的 AI工具集成系统是一套统一框架，用于将 OpenSpec 工作流程（提案、应用、归档）与多种 AI 编码助手深度整合。通过为每个受支持的 AI 工具生成专用的斜杠命令（Slash Commands）文件，开发者可以在任何主流 AI 辅助编程环境中使用一致的操作方式发起和管理 OpenSpec 变更。\n\n核心设计原则：\n\n- **模板驱动**：命令体内容从共享模板生成，保持跨工具一致性\n- **最小适配**：每个工具只需添加特有的 frontmatter 和路径配置\n- **幂等性**：支持重复初始化而不破坏现有文件\n- **按需更新**：更新时仅刷新已存在的文件，不创建新的\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 支持的AI工具\n\nOpenSpec 目前支持以下 AI 编程助手的斜杠命令集成：\n\n| 工具 | 命令前缀 | 存储目录 | 命令示例 |\n|------|---------|---------|---------|\n| **Amazon Q Developer** | `@openspec-` | `.amazonq/prompts/` | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` |\n| **Antigravity** | `/openspec-` | `.agent/workflows/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| **Auggie (Augment CLI)** | `/openspec-` | `.augment/commands/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| **Claude Code** | `/openspec:` | `.claude/commands/openspec/` | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |\n| **Cline** | 斜杠命令 | `.clinerules/workflows/` | `openspec-proposal.md`, `openspec-apply.md`, `openspec-archive.md` |\n| **CodeBuddy Code (CLI)** | `/openspec:` | `.codebuddy/commands/` | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |\n| **Cursor** | `/openspec-` | `.cursor/commands/` | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n\n资料来源：[README.md:支持AI工具列表](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 核心架构\n\n### 组件结构\n\n```\nsrc/core/command-generation/\n├── registry.ts # 命令注册表，定义所有工具的配置\n├── generator.ts # 命令文件生成器\n├── types.ts # 类型定义\n└── adapters/\n └── index.ts # 工具特定适配器\n```\n\n架构采用适配器模式，每个 AI 工具对应一个适配器，负责处理：\n\n- 目录结构创建\n- 文件命名规则\n- Frontmatter 格式\n- 命令体包装\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:设计理念](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[openspec init] --> B{检测已安装工具}\n B -->|Claude Code| C[生成 .claude/commands/openspec/]\n B -->|Cursor| D[生成 .cursor/commands/]\n B -->|其他工具| E[生成对应目录结构]\n C --> F[复制共享模板]\n D --> F\n E --> F\n F --> G[添加工具特定 frontmatter]\n G --> H[验证标记位置]\n H --> I[初始化完成]\n \n J[openspec update] --> K[扫描已存在的命令文件]\n K --> L{每个已存在文件}\n L -->|更新| M[仅刷新标记内内容]\n L -->|跳过| N[不创建新文件]\n M --> O[报告更新结果]\n```\n\n## 命令文件格式\n\n### 标准结构\n\n每个斜杠命令文件遵循统一的 Markdown 格式：\n\n```markdown\n---\n# Frontmatter（工具特定）\nname: proposal\ndescription: 创建 OpenSpec 提案\ncategory: OpenSpec\n---\n\n...命令体内容...\n\n```\n\n关键规则：\n\n- **标记位置**：`` 和 `` 必须包裹 Markdown 正文内容\n- **禁止嵌套**：标记不得出现在 frontmatter 内部，以免 YAML 解析错误\n- **内容来源**：命令体从共享模板提取，保持所有工具一致\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:标记位置](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### 工具命名约定\n\n| 工具 | 文件命名 | 命令内命名空间 |\n|------|---------|--------------|\n| Claude Code | `proposal.md` | `/openspec:proposal` |\n| Cursor | `openspec-proposal.md` | `/openspec-proposal` |\n| Amazon Q | `openspec-proposal.md` | `@openspec-proposal` |\n| Codex | `openspec-proposal.md` | - (全局目录) |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:命令命名与UX](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 实现细节\n\n### 模板管理\n\n模板系统通过 `TemplateManager` 集中管理所有命令模板：\n\n```typescript\n// 模板提取逻辑\nfunction extractTemplateSnippets(source: string): string {\n // 从 openspec/README.md 提取权威片段\n return conciseInstructions;\n}\n```\n\n模板包含：\n\n1. **守卫规则**：1-2 个澄清问题；遵循最小复杂度规则；Node 项目使用 `pnpm`\n2. **步骤列表**：根据工作流阶段（proposal/apply/archive）定制的步骤\n3. **验证命令**：`openspec validate` 用于严格检查\n4. **故障排除**：指向 `openspec show`、`openspec list` 的指针\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:模板内容](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### SlashCommandConfigurator\n\n核心配置器类管理每个工具的多文件生成：\n\n```typescript\ninterface SlashCommandConfigurator {\n getTargets(): Array<{\n path: string;\n kind: 'slash';\n id: string;\n }>;\n \n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:设计理念](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 幂等性与创建规则\n\n### Init 操作\n\n| 行为 | 说明 |\n|------|-----|\n| 首次运行 | 为选定工具创建全部命令文件 |\n| 后续运行 | 对已存在的文件执行无操作（幂等） |\n| 目录创建 | 由 configurator 负责创建嵌套目录 |\n\n### Update 操作\n\n| 行为 | 说明 |\n|------|-----|\n| 已存在文件 | 仅刷新标记内内容 |\n| 不存在文件 | 跳过，不创建新文件 |\n| 日志报告 | 按文件报告更新结果 |\n\n```mermaid\ngraph LR\n A[update 命令] --> B{文件存在?}\n B -->|是| C[刷新 OPENSPEC 标记内容]\n B -->|否| D[跳过]\n C --> E[记录更新成功]\n D --> F[记录跳过]\n E --> G[显示汇总]\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:幂等性与创建规则](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 测试策略\n\n### 金快照测试\n\n为每个工具的生成文件维护金快照：\n\n```typescript\ndescribe('Slash Command Generation', () => {\n it('generates correct frontmatter + markers + body for Claude Code', () => {\n const result = generateForTool('claude-code');\n expect(result).toMatchSnapshot();\n });\n});\n```\n\n### 标记位置验证\n\n```typescript\ndescribe('Marker Placement', () => {\n it('never places markers inside frontmatter', () => {\n const content = generateForTool('cursor');\n const frontmatterEnd = content.indexOf('---', 4);\n const markerStart = content.indexOf('');\n \n expect(markerStart).toBeGreaterThan(frontmatterEnd);\n });\n});\n```\n\n测试覆盖场景：\n\n- 缺失标记的恢复行为\n- 重复标记的处理\n- 各种 frontmatter 格式兼容\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:测试策略](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 使用方式\n\n### 初始化集成\n\n```bash\n# 在项目根目录运行\nopenspec init\n\n# 或指定特定工具\nopenspec init --tools claude,cursor\n```\n\n### 更新命令文件\n\n```bash\n# 刷新所有已存在的斜杠命令\nopenspec update\n\n# 刷新特定工具\nopenspec update --tools codex\n```\n\n### 手动使用\n\n```text\nYou: /openspec:proposal add-user-auth\n\nAI: I'll create an OpenSpec proposal for adding user authentication.\n *Creates: openspec/changes/add-user-auth/proposal.md*\n```\n\n资料来源：[README.md:命令参考](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## 社区扩展\n\n第三方可以通过独立仓库分发自定义 schema 包，类似于 [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) 的方式扩展 OpenSpec。\n\n查看[自定义文档](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md#community-schemas)了解社区 schema 目录。\n\n## 相关文档\n\n- [开始使用](docs/getting-started.md) - 首次使用指南\n- [工作流](docs/workflows.md) - 组合与模式\n- [命令参考](docs/commands.md) - 斜杠命令与技能\n- [CLI 参考](docs/cli.md) - 终端命令完整参考\n- [支持工具](docs/supported-tools.md) - 工具集成与安装路径\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[工作流模板](#page-workflow-templates), [安装与初始化](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/cli/index.ts)\n- [src/commands/change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/change.ts)\n- [src/commands/spec.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/spec.ts)\n- [src/commands/validate.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/validate.ts)\n- [src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n- [src/commands/completion.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/completion.ts)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n \n\n# CLI命令参考\n\n## 概述\n\nOpenSpec CLI 是项目的核心命令行工具，提供了一套完整的命令集用于管理项目规格、工作流程和变更过程。CLI 采用模块化架构设计，通过子命令模式组织功能，支持交互式操作和脚本化使用两种模式。\n\nCLI 的主要职责包括：\n\n- 初始化 OpenSpec 项目结构\n- 创建和管理变更（changes）\n- 验证规格文档格式和结构\n- 生成和应用 AI 指令\n- 管理配置和方案（schemas）\n\n## 命令架构\n\nOpenSpec CLI 采用树形命令结构，通过 `openspec` 主命令调用各类子命令和子组。以下是完整的命令层次结构：\n\n```mermaid\ngraph TD\n A[openspec] --> B[change 子命令组]\n A --> C[spec 子命令组]\n A --> D[config 子命令组]\n A --> E[schema 子命令组]\n A --> F[validate]\n A --> F2[view]\n A --> F3[list]\n A --> F4[instructions]\n A --> F5[status]\n A --> F6[next]\n A --> F7[templates]\n A --> F8[init]\n A --> F9[update]\n A --> F10[archive]\n A --> F11[completion]\n \n B --> B1[new]\n B --> B2[show]\n B --> B3[list]\n B --> B4[archive]\n \n C --> C1[show]\n C --> C2[list]\n C --> C3[validate]\n \n D --> D1[show]\n D --> D2[init]\n \n E --> E1[init]\n E --> E2[list]\n E --> E3[which]\n E --> E4[fork]\n```\n\n## 全局选项\n\n所有 OpenSpec 命令支持以下全局选项：\n\n| 选项 | 简写 | 描述 | 默认值 |\n|------|------|------|--------|\n| `--help` | `-h` | 显示帮助信息 | - |\n| `--version` | `-V` | 显示版本号 | - |\n| `--json` | - | 以 JSON 格式输出结果 | `false` |\n| `--no-color` | - | 禁用彩色输出 | `false` |\n| `--cwd ` | - | 指定工作目录 | 当前目录 |\n\n## 变更管理命令\n\n变更（Change）是 OpenSpec 工作流程的核心概念，每个变更代表一个需要实现的功能或修复。\n\n### change new - 创建新变更\n\n创建新的变更目录和基础文件结构。\n\n```bash\nopenspec change new [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | 变更名称，使用 kebab-case 格式 |\n\n**可选参数：**\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定使用的 schema，默认使用 `openspec/config.yaml` 中的配置 |\n| `--yes` / `-y` | 跳过确认提示 |\n| `--no-input` | 非交互模式 |\n\n**示例：**\n\n```bash\n# 创建新变更\nopenspec change new add-dark-mode\n\n# 指定 schema\nopenspec change new add-auth --schema tdd\n\n# 非交互模式\nopenspec change new fix-login-bug --yes\n```\n\n创建完成后会生成以下文件结构：\n\n```\nopenspec/changes//\n├── proposal.md # 变更提案\n├── specs/ # 规格文档目录\n├── design.md # 技术设计方案\n├── tasks.md # 实现任务清单\n└── .openspec.yaml # 变更元数据\n```\n\n### change show - 查看变更详情\n\n显示指定变更的详细信息，包括各制品的状态和内容。\n\n```bash\nopenspec change show [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--artifacts` | 仅显示制品列表 |\n| `--details` | 显示完整内容 |\n\n### change list - 列出所有变更\n\n列出所有活跃的变更（未归档）。\n\n```bash\nopenspec change list [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n| `--archived` | 显示已归档的变更 |\n\n### change archive - 归档变更\n\n将完成的变更移动到归档目录。\n\n```bash\nopenspec change archive [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--yes` / `-y` | 跳过确认提示 |\n\n归档后的变更会被移动到 `openspec/changes/archive/` 目录。\n\n## 制品工作流命令\n\n制品（Artifact）是 OpenSpec 方案定义的核心产物，每个制品有独立的状态和依赖关系。\n\n### status - 查看制品状态\n\n显示变更中所有制品的状态和依赖关系。\n\n```bash\nopenspec status [options]\n```\n\n**输出格式示例：**\n\n| 制品 | 状态 | 输出路径 |\n|------|------|----------|\n| proposal | ✅ done | proposal.md |\n| specs | ✅ ready | specs/*.md |\n| design | 🔒 blocked | design.md |\n| tasks | 🔒 blocked | tasks.md |\n\n**状态说明：**\n\n- `done` - 制品已完成\n- `ready` - 制品可以开始\n- `blocked` - 等待依赖制品完成\n\n### next - 查看下一个可执行制品\n\n显示当前可以开始工作的制品列表。\n\n```bash\nopenspec next [options]\n```\n\n### instructions - 获取 AI 指令\n\n为指定制品生成 AI 助手指令。\n\n```bash\nopenspec instructions --change [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | 制品名称（如 proposal, specs, design, tasks） |\n\n| 选项 | 描述 |\n|------|------|\n| `--change ` | 变更名称（必需） |\n| `--context` | 包含上下文信息 |\n| `--rules` | 包含规则信息 |\n\n**输出示例：**\n\n```xml\n\nTech stack: TypeScript, React\n\n\n\n- Use Given/When/Then format for scenarios\n- Reference existing patterns before inventing new ones\n\n\n\n[Schema's template content]\n\n```\n\n### templates - 查看模板\n\n显示指定制品的模板内容。\n\n```bash\nopenspec templates [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定 schema |\n\n## 规格命令\n\n规格（Spec）命令用于管理和验证项目规格文档。\n\n### spec show - 显示规格\n\n显示指定规格文档的内容。\n\n```bash\nopenspec spec show [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n\n### spec list - 列出规格\n\n列出所有已定义的规格。\n\n```bash\nopenspec spec list [options]\n```\n\n### spec validate - 验证规格\n\n验证规格文档的格式和结构。\n\n```bash\nopenspec spec validate [spec-name] [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--strict` | 严格模式检查 |\n\n## 配置命令\n\n配置命令用于管理项目级配置。\n\n### config show - 显示配置\n\n显示当前项目的 OpenSpec 配置。\n\n```bash\nopenspec config show [options]\n```\n\n### config init - 初始化配置\n\n创建项目配置文件。\n\n```bash\nopenspec config init [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 设置默认 schema |\n| `--context ` | 设置项目上下文 |\n| `--yes` / `-y` | 跳过确认提示 |\n\n## Schema 管理命令\n\nSchema 定义了制品的结构、工作流程和验证规则。\n\n### schema init - 创建新 Schema\n\n创建新的 schema 方案。\n\n```bash\nopenspec schema init [options]\n```\n\n| 参数 | 描述 |\n|------|------|\n| `` | Schema 名称（kebab-case 格式） |\n\n| 选项 | 描述 |\n|------|------|\n| `--description ` | Schema 描述 |\n| `--artifacts ` | 制品列表（逗号分隔） |\n| `--default` | 设置为默认 schema |\n| `--force` | 强制覆盖 |\n\n**示例：**\n\n```bash\n# 交互式创建\nopenspec schema init my-schema\n\n# 非交互式创建\nopenspec schema init tdd --description \"Test-driven development workflow\" --artifacts \"proposal,specs,tests,design,tasks\" --default\n```\n\n### schema list - 列出 Schema\n\n列出所有可用的 schema。\n\n```bash\nopenspec schema list [options]\n```\n\n### schema which - 显示当前 Schema\n\n显示当前变更或项目使用的 schema。\n\n```bash\nopenspec schema which [change-name] [options]\n```\n\n### schema fork - 派生 Schema\n\n从现有 schema 派生新的 schema。\n\n```bash\nopenspec schema fork --name [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--name ` | 新 schema 名称（必需） |\n| `--destination ` | 自定义输出路径 |\n| `--force` | 强制覆盖 |\n\n## 项目命令\n\n### init - 初始化项目\n\n在当前目录初始化 OpenSpec 项目结构。\n\n```bash\nopenspec init [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--schema ` | 指定默认 schema |\n| `--skip-git` | 跳过 git 初始化 |\n| `--yes` / `-y` | 跳过确认提示 |\n\n初始化后生成的文件结构：\n\n```\n├── openspec/\n│ ├── config.yaml # 项目配置\n│ ├── specs/ # 规格目录\n│ │ └── / # 能力子目录\n│ │ └── spec.md\n│ └── changes/ # 变更目录\n│ └── archive/ # 归档目录\n├── AGENTS.md # AI 助手说明\n└── CLAUDE.md # Claude Code 集成\n```\n\n### view - 可视化仪表板\n\n启动交互式命令行仪表板查看项目状态。\n\n```bash\nopenspec view [options]\n```\n\n### list - 列出变更\n\n显示所有活跃变更的概览。\n\n```bash\nopenspec list [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | JSON 格式输出 |\n\n### archive - 归档变更\n\n归档指定的变更。\n\n```bash\nopenspec archive [options]\n```\n\n### validate - 验证变更\n\n验证变更文档的格式和结构。\n\n```bash\nopenspec validate [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--strict` | 严格模式 |\n\n### update - 更新配置\n\n刷新 AI 工具的斜杠命令配置文件。\n\n```bash\nopenspec update [options]\n```\n\n| 选项 | 描述 |\n|------|------|\n| `--tools ` | 指定要更新的工具（逗号分隔） |\n\n## Shell 补全\n\n生成 shell 补全脚本以支持命令自动补全。\n\n```bash\nopenspec completion [options]\n```\n\n| 参数 | 支持的 Shell |\n|------|-------------|\n| `` | bash, zsh, fish, powershell |\n\n**安装示例：**\n\n```bash\n# Bash\nopenspec completion bash >> ~/.bashrc\n\n# Zsh\nopenspec completion zsh >> ~/.zshrc\n\n# Fish\nopenspec completion fish > ~/.config/fish/completions/openspec.fish\n```\n\n## 工作流程示例\n\n### 完整变更工作流程\n\n```mermaid\ngraph LR\n A[1. openspec change new
add-login-feature] --> B[2. 创建制品]\n B --> C[3. openspec instructions
proposal --change
add-login-feature]\n C --> D[4. AI 生成 proposal.md]\n D --> E[5. openspec instructions
specs --change
add-login-feature]\n E --> F[6. AI 生成 specs]\n F --> G[7. openspec instructions
design --change
add-login-feature]\n G --> H[8. AI 生成 design.md]\n H --> I[9. openspec instructions
tasks --change
add-login-feature]\n I --> J[10. AI 生成 tasks.md]\n J --> K[11. openspec archive
add-login-feature]\n```\n\n### Schema 创建工作流程\n\n```bash\n# 1. 创建新 schema\nopenspec schema init tdd \\\n --description \"Test-driven development workflow\" \\\n --artifacts \"proposal,specs,tests,design,tasks\" \\\n --default\n\n# 2. 在新变更中使用\nopenspec change new feature-x --schema tdd\n\n# 3. 派生自定义 schema\nopenspec schema fork tdd --name my-tdd\n```\n\n## 错误处理\n\nCLI 命令可能返回以下常见错误：\n\n| 错误代码 | 描述 | 解决方案 |\n|---------|------|----------|\n| `ENOENT` | 变更不存在 | 检查变更名称，使用 `openspec list` 查看可用变更 |\n| `EEXIST` | 文件已存在 | 使用 `--force` 选项或删除现有文件 |\n| `EINVALID_NAME` | 无效的变更/Schema 名称 | 使用 kebab-case 格式 |\n| `ENO_SCHEMA` | Schema 不存在 | 检查 schema 名称，使用 `openspec schema list` |\n\n## 资料来源\n\n- 命令架构设计：README.md\n- 变更管理命令：openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md\n- Schema 管理：openspec/changes/archive/2026-02-17-schema-management-cli/tasks.md\n- 配置系统：openspec/changes/archive/2026-02-17-project-config/design.md\n- 制品工作流：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md\n\n---\n\n\n\n## 工作流模板\n\n### 相关页面\n\n相关主题：[变更工作流](#page-change-workflow), [CLI命令参考](#page-cli-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/templates/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/index.ts)\n- [src/core/templates/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/types.ts)\n- [src/core/templates/workflows/propose.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/propose.ts)\n- [src/core/templates/workflows/apply-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/apply-change.ts)\n- [src/core/templates/workflows/continue-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/continue-change.ts)\n- [src/core/templates/workflows/ff-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/ff-change.ts)\n- [src/core/templates/workflows/verify-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/verify-change.ts)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n \n\n# 工作流模板\n\n## 概述\n\n工作流模板是 OpenSpec 框架中用于标准化 AI 代理与用户之间交互的核心组件。它们定义了从项目构思到实现完成的完整开发周期中的各个阶段指导。OpenSpec 采用**流体而非僵化**的哲学，工作流模板允许团队在任何阶段灵活更新产物，无需严格的阶段门控。\n\n工作流模板系统的主要作用包括：\n\n- **标准化交互模式**：为 AI 代理提供一致的指令格式和执行步骤\n- **阶段引导**：将复杂项目分解为可管理的阶段（提议、规格说明、设计、任务、实现、验证）\n- **工具集成**：支持 20+ AI 助手通过斜杠命令进行交互\n- **工件驱动**：每个变更（change）拥有独立的文件夹，包含提议、规格说明、设计和任务\n\n资料来源：[docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n\n## 工作流类型\n\nOpenSpec 定义了六种核心工作流类型，每种工作流对应项目开发周期的不同阶段：\n\n| 工作流类型 | 用途 | 触发方式 |\n|------------|------|----------|\n| `propose` | 创建新功能的提议 | `/opsx:propose` |\n| `apply` | 开始实现已批准的变更 | `/opsx:apply` |\n| `continue` | 继续进行中的工作 | `/opsx:continue` |\n| `ff` | 快速跟进当前任务 | `/opsx:ff` |\n| `verify` | 验证实现是否符合规格 | `/opsx:verify` |\n| `bulk-archive` | 批量归档已完成的变更 | `/opsx:bulk-archive` |\n| `onboard` | 新成员入门引导 | `/opsx:onboard` |\n\n资料来源：[src/core/templates/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/index.ts)\n\n## 工作流执行流程\n\n### 标准开发周期\n\n```mermaid\ngraph TD\n A[用户发起需求] --> B[Propose 工作流]\n B --> C[创建变更文件夹]\n C --> D[生成 Proposal]\n D --> E[用户确认提议]\n E --> F[Apply 工作流]\n F --> G[规格说明 & 设计]\n G --> H[Continue 工作流]\n H --> I[任务执行]\n I --> J[Verify 工作流]\n J --> K{验证通过?}\n K -->|是| L[归档变更]\n K -->|否| H\n L --> M[项目更新完成]\n```\n\n### 工作流切换流程\n\n```mermaid\nstateDiagram-v2\n [*] --> Propose: 用户输入需求\n Propose --> Apply: 规格确认\n Apply --> Continue: 开始实现\n Continue --> Verify: 任务完成\n Verify --> Continue: 需要修改\n Verify --> Archive: 验证通过\n Archive --> Propose: 新需求\n```\n\n资料来源：[docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n\n## 提议工作流 (Propose)\n\n提议工作流是项目开发的起点，用于在编写任何代码之前对齐需求。\n\n### 执行步骤\n\n提议工作流包含以下标准步骤：\n\n1. **理解需求**：AI 代理确认理解用户的需求描述\n2. **澄清问题**：如有必要，提出 1-2 个澄清性问题\n3. **遵循复杂度规则**：遵循最小复杂度原则，使用 `pnpm` 作为包管理器\n4. **创建变更结构**：创建 `openspec/changes//` 目录\n5. **生成提议文件**：创建 `proposal.md` 文档\n6. **验证**：运行验证命令确保结构正确\n7. **确认**：等待用户确认后再继续\n\n### 提议文件格式\n\n提议文件包含以下标准结构：\n\n```markdown\n---\nchange: \ncategory: \ndescription: <简短描述>\n---\n\n[提议内容...]\n\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## 应用工作流 (Apply)\n\n应用工作流在提议被批准后触发，用于准备实现阶段。\n\n### 模式选择\n\nOpenSpec 支持两种应用模式：\n\n| 模式 | 命令 | 说明 |\n|------|------|------|\n| 精简模式 | `/opsx:propose` | 仅包含提议工作流 |\n| 扩展模式 | `/opsx:new` | 包含完整工作流（propose, apply, continue, ff, verify） |\n\n### 执行流程\n\n1. **加载变更**：读取已批准的提议\n2. **解析规格**：加载关联的规格说明文档\n3. **构建上下文**：生成实施指令，包含：\n - 项目上下文信息\n - 特定工件规则\n - 模板内容\n4. **提供下一步指导**：列出可执行的任务\n\n### Schema 感知\n\n应用工作流采用 Schema 感知的指令生成方式，从 schema 定义中读取 `apply.requires` 来确定必需存在的工件，并动态检查工件存在性。\n\n资料来源：[openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md)\n\n## 继续工作流 (Continue)\n\n继续工作流用于在实现过程中继续工作，适用于任务中断后的恢复或增量开发。\n\n### 使用场景\n\n- 长时间任务的中断恢复\n- 团队成员接手他人工作\n- 跨会话的连续开发\n\n### 指令结构\n\n```typescript\ninterface ContinueInstructions {\n change: string;\n artifact: string | null;\n schema: string;\n output: string;\n instruction: string;\n}\n```\n\n资料来源：[src/core/templates/workflows/continue-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/continue-change.ts)\n\n## 快速跟进工作流 (Fast Forward)\n\n快速跟进工作流旨在加速当前任务的执行，适用于明确的短期目标。\n\n### 设计原则\n\n- **简单直接**：跳过不必要的确认步骤\n- **目标导向**：专注于当前任务的完成\n- **上下文保持**：维护之前的工作上下文\n\n## 验证工作流 (Verify)\n\n验证工作流用于确认实现是否符合规格说明。\n\n### 验证内容\n\n| 验证项 | 说明 |\n|--------|------|\n| 工件完整性 | 所有必需的规格文档是否存在 |\n| 场景覆盖 | 每个需求是否有对应的场景 |\n| 实现一致性 | 代码实现是否与规格描述匹配 |\n| 格式规范 | 文档格式是否符合要求 |\n\n### 验证规则\n\n规格说明中的关键格式要求：\n\n- 每个需求使用 `### Requirement: ` 标记\n- 使用 SHALL/MUST 表示规范性要求（避免 should/may）\n- 每个场景使用 `#### Scenario: ` 格式\n- 场景必须使用**精确的四个井号**（`####`），使用三个井号或项目符号将静默失败\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## 模板数据结构\n\n### 核心类型定义\n\n```typescript\ninterface WorkflowTemplate {\n id: WorkflowType;\n name: string;\n description: string;\n instruction: string;\n nextSteps?: string[];\n}\n\ninterface WorkflowContext {\n change: string;\n artifact?: string;\n schema: string;\n output: string;\n}\n```\n\n### 指令格式\n\n工作流生成的指令采用 XML 风格标签包裹的格式：\n\n```xml\n\n[项目上下文信息]\n\n\n\n- 规则1\n- 规则2\n\n\n\n[模板内容]\n\n```\n\n**Context 部分**：注入项目级上下文，适用于所有工件\n\n**Rules 部分**：仅注入匹配当前工件类型的规则\n\n**Template 部分**：原始模板内容\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## 工件与工作流关系\n\n### Schema 驱动的工件定义\n\nOpenSpec 使用 Schema YAML 定义工件及其依赖关系：\n\n```yaml\nname: spec-driven\nversion: 1\nartifacts:\n - id: proposal\n generates: proposal.md\n requires: []\n \n - id: specs\n generates: specs/*.md\n requires: [proposal]\n \n - id: design\n generates: design.md\n requires: [proposal]\n \n - id: tasks\n generates: tasks.md\n requires: [specs, design]\n```\n\n### 工件状态检测\n\n```mermaid\ngraph LR\n A[检查工件文件] --> B{文件存在?}\n B -->|是| C[状态: done]\n B -->|否| D{依赖满足?}\n D -->|是| E[状态: ready]\n D -->|否| F[状态: blocked]\n```\n\n工件状态类型：\n\n| 状态 | 含义 | 条件 |\n|------|------|------|\n| `done` | 已完成 | 对应文件存在 |\n| `ready` | 就绪 | 依赖项已满足，文件待创建 |\n| `blocked` | 阻塞 | 依赖项未满足 |\n| `in_progress` | 进行中 | 文件存在但未完成 |\n\n资料来源：[openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md)\n\n## 配置与扩展\n\n### 项目配置\n\n工作流模板通过 `openspec/config.yaml` 进行项目级配置：\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n \nrules:\n specs:\n - Use Given/When/Then format\n design:\n - Include rollback plan\n \nschema: spec-driven\n```\n\n### Schema 存储位置\n\nOpenSpec 支持三级 Schema 存储：\n\n1. **项目本地**：`openspec/schemas//`\n2. **用户覆盖**：`~/.local/share/openspec/schemas//`\n3. **内置包**：`node_modules/@fission-ai/openspec/schemas//`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n## CLI 命令参考\n\n### 工作流相关命令\n\n| 命令 | 说明 |\n|------|------|\n| `openspec init` | 初始化项目配置 |\n| `openspec update` | 刷新产物文件 |\n| `openspec list` | 列出活跃变更 |\n| `openspec view` | 交互式仪表板 |\n| `openspec show