@openprd/cli 0.1.1 → 0.1.8

package/.openprd/state/versions/v0003.json

@@ -0,0 +1,269 @@
+{
+  "versionNumber": 3,
+  "versionId": "v0003",
+  "createdAt": "2026-06-02 12:22:44",
+  "projectRoot": "/Users/chaojifeng/Projects/harness-engineer/openprd",
+  "workspaceRoot": "/Users/chaojifeng/Projects/harness-engineer/openprd/.openprd",
+  "schema": "prd-core",
+  "templatePack": "agent",
+  "productType": "agent",
+  "title": "OpenPrd 用户视角变化摘要",
+  "owner": "Codex",
+  "status": "synthesized",
+  "sections": {
+    "meta": {
+      "title": "OpenPrd 用户视角变化摘要",
+      "owner": "Codex",
+      "status": "clarifying",
+      "version": "v0003",
+      "productType": "agent",
+      "date": "2026-06-02"
+    },
+    "problem": {
+      "problemStatement": "OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道来维护当前版本号、版本内更新项，以及与 commit tag 的协同规则。结果是版本号已经在项目里被真实使用，却缺少一个本地真源来累计本版本的需求、Bug、handoff 摘要和最终发布说明。",
+      "whyNow": "用户已经确认，希望在现有短文案变化摘要的基础上，再补一个可选的项目级版本轨道：既能维护当前版本和版本内更新内容，也能在 commit 流里利用版本信息辅助打 tag，让 release notes、handoff 和外部同步有稳定来源。",
+      "evidence": []
+    },
+    "users": {
+      "primaryUsers": [
+        "维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer",
+        "使用 OpenPrd 执行任务并需要生成 commit、handoff 或版本说明的 Agent 使用者"
+      ],
+      "secondaryUsers": [],
+      "stakeholders": [
+        "阅读交付变更、提交说明和版本说明的项目负责人",
+        "需要快速判断这次改动是否值得合入或发布的协作者"
+      ]
+    },
+    "goals": {
+      "goals": [
+        "把用户可感知变化写法沉淀成 OpenPrd 的共享变化摘要 contract，而不是停留在单个 commit skill。",
+        "让 OpenPrd 在 loop commit、handoff / 版本说明、review 摘要三处都能输出更适合人阅读的变化说明。",
+        "保持 OpenPrd 现有 workflow、review gate 和高风险提交门禁不变，只升级表达层。"
+      ],
+      "successMetrics": [
+        "loop 默认 commit message 不再只输出 `Complete <task>` 这种执行口吻，而是优先输出短标题加动作词条目。",
+        "handoff 导出结果包含可直接复用的变化摘要或版本说明片段，便于人快速扫读。",
+        "review 摘要文案的标签和一句话说明更明显地站在用户视角表达新增、修复、优化、调整等变化。",
+        "完成后用单独 worker 跑一个样例项目，能看到这套变化摘要在真实任务中的输出效果。"
+      ],
+      "acceptanceGoals": [
+        "新增项目级 release/version ledger，支持 current version、版本状态和版本内变化项存储。",
+        "现有变化摘要层继续复用新增、修复、优化、调整、移除等短文案动作词，并能挂到具体项目版本下。",
+        "commit 流在启用版本轨道且用户明确执行时，可以读取当前版本并辅助创建或更新本地版本 tag；同版本多次提交时 tag 可移动到最新 commit。",
+        "README、skills、handoff/release 导出和测试同步说明版本轨道与 tag 协同规则。"
+      ]
+    },
+    "scope": {
+      "inScope": [
+        "新增可选的项目级 release/version ledger，用于维护当前版本号、版本状态和版本内更新项。",
+        "把现有变化摘要条目挂载到具体项目版本下，支持需求、Bug、handoff 摘要和 release notes 候选的累计。",
+        "扩展 commit 流，在版本轨道已启用且用户显式执行 commit 时读取当前版本，并辅助创建或更新本地版本 tag。",
+        "扩展 handoff、release notes 与后续外部同步出口，让它们可以从项目版本轨道导出版本内变化内容。",
+        "补充 README、skills、文档和测试，并验证项目版本轨道与短文案摘要的协同效果。"
+      ],
+      "outOfScope": [
+        "不把内部 PRD 版本 v000x 直接改造成项目发版号。",
+        "不强制所有项目都启用版本轨道；没有版本管理习惯的项目可以继续只用现有变化摘要能力。",
+        "不默认自动 push、自动发布或自动 force 更新远端 tag。",
+        "不要求替代团队已有的外部版本体系，只提供一个本地可维护、可导出的辅助真源。"
+      ]
+    },
+    "scenarios": {
+      "primaryFlows": [
+        "用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。",
+        "用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组织的变化摘要。",
+        "用户查看 review 评审摘要时，能先用短标签和一句话理解这次带来的用户可感知变化，而不是先读技术实现。"
+      ],
+      "edgeCases": [
+        "项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。",
+        "如果同一个版本下发生多次 commit，本地 tag 可以移动到最新 commit；但如果对应 tag 已经推到远端，继续移动会变成高风险操作。",
+        "有些项目只想维护版本说明，不想碰 git tag；版本轨道与 tag 辅助能力需要可分开启用。",
+        "如果用户在没有更新版本号的情况下继续提交，系统应把新变化继续累计到当前版本，而不是猜测用户要自动 bump 版本。"
+      ],
+      "failureModes": [
+        "commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等技术细节。",
+        "摘要为了好看而扭曲真实改动，把内部治理误写成用户可感知功能。",
+        "三处落点风格不一致，用户在 commit、handoff 和 review 里看到三套不同写法。"
+      ]
+    },
+    "requirements": {
+      "functional": [
+        "OpenPrd 提供可选的项目级 release/version ledger，支持记录 current version、版本状态和版本内变化项。",
+        "现有共享变化摘要规则支持把新增、修复、优化、调整、移除等条目关联到具体项目版本。",
+        "handoff 与 release notes 导出优先从项目版本轨道读取对应版本的变化条目。",
+        "当版本轨道已启用且用户通过 OpenPrd 显式执行 commit 时，commit 流可以读取当前版本号并辅助创建或更新本地版本 tag。",
+        "当用户未更新版本号时，后续变化默认继续累计到当前版本；当用户显式更新版本号后，新的变化进入下一个版本。"
+      ],
+      "nonFunctional": [
+        "新增能力保持命令兼容；已有显式 message 或自定义文案优先级不能被破坏。",
+        "formatter 只依赖本地上下文，不新增外部网络、第三方 API 或额外付费依赖。",
+        "输出在中英文混合项目里仍以当前用户语言为主，必要专有名词保持原样。"
+      ],
+      "businessRules": [
+        "内部 PRD 版本和项目 release 版本必须保持分层，不能共用一个字段。",
+        "项目 release 版本默认允许用户手动指定或手动修正；系统只做辅助，不替用户决定版本 bump。",
+        "同版本多次 commit 时，本地版本 tag 可以指向最新 commit，帮助界定本版本从上一个版本 tag 之后的提交范围。",
+        "如果目标版本 tag 已经存在于远端，系统不得默认覆盖；需要明确提示当前指向并等待用户决定。",
+        "版本说明继续优先使用新增、修复、优化、调整、移除等人类可读动作词，而不是直接复述 git 变更细节。"
+      ]
+    },
+    "businessGuardrails": {
+      "costDrivers": [
+        "无新增第三方付费调用成本；变化摘要完全基于本地上下文生成。"
+      ],
+      "usageLimits": [
+        "不引入新的用户额度或发布配额限制；沿用现有 commit / handoff 执行门禁。"
+      ],
+      "abusePrevention": [
+        "不把自动 push、自动 tag 或历史重写并入默认能力，避免摘要能力演变成高风险自动发布路径。"
+      ],
+      "monitoringSignals": [
+        "关注生成摘要是否频繁退回技术细节、是否在测试中出现失真或空摘要。"
+      ],
+      "alertThresholds": [
+        "如果三处输出中任一处无法生成可信摘要并持续回退，需要在测试中显式暴露。"
+      ],
+      "stopLossActions": [
+        "当上下文不足或摘要质量不可信时，回退到现有安全文案，不自动包装。"
+      ]
+    },
+    "constraints": {
+      "technical": [
+        "需要兼容现有 loop、handoff、review-presentation 和 html-artifacts 的调用契约。",
+        "需要在 dirty workspace 中做窄改动，避免误伤正在进行的 test-strategy-router 等历史工作。"
+      ],
+      "compliance": [],
+      "dependencies": [
+        "依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 handoff 导出流程。"
+      ]
+    },
+    "risks": {
+      "assumptions": [
+        "用户更看重人能快速扫懂的变化摘要，而不是技术完整性优先的底层说明。",
+        "三处落点可以共用一套核心 formatter，再按场景做轻量渲染差异。"
+      ],
+      "risks": [
+        "如果 formatter 规则过死，可能把一些纯技术任务描述得失真。",
+        "如果只改一处而没有共用 contract，后续很快会再次分叉。"
+      ],
+      "openQuestions": [
+        "版本轨道是否需要支持 Unreleased 这种未定版态，还是只维护一个明确 current version。",
+        "本地 tag 跟最新 commit 的策略是否只在未推远端前自动生效，还是需要更细的项目级配置。",
+        "Feishu 等外部同步出口首期是否只导出版本说明，不直接回写外部系统。"
+      ]
+    },
+    "handoff": {
+      "owner": "Codex",
+      "nextStep": "确认新的评审稿后生成 change 和 tasks，并按三处落点实现。",
+      "targetSystem": "OpenSpec"
+    },
+    "typeSpecific": {
+      "kind": "agent",
+      "title": "Agent 专项",
+      "fields": {
+        "humanAgentContract": "Agent 可以根据 task、handoff 和 review 上下文生成变化摘要草案，但不能把自动生成的摘要当成发布事实之外的营销文案；高风险提交行为仍遵守现有执行门禁。",
+        "autonomyBoundary": "Agent 可以修改 OpenPrd 的 formatter、skills、文档、测试和 worker 验证流程；不得自动推送、改写历史提交，或把 Feature Git Commit 的高风险 git 行为直接并入 OpenPrd 默认流。",
+        "toolBoundary": "仅使用本地 OpenPrd 代码、CLI、测试与 worker 会话完成实现和验证；本次不需要额外第三方文档调研。",
+        "stateModel": "共享变化摘要 contract 负责统一标题、动作词和描述规则；loop、handoff、review 三个调用面只做各自场景渲染与回退控制。",
+        "evalPlan": "先做本地单测和回归，再用 worker 在单独样例项目上跑一个最小任务，检查 commit、handoff 或 review 摘要输出是否符合预期。"
+      }
+    }
+  },
+  "reviewPresentation": {
+    "diagram": {
+      "type": "map"
+    },
+    "mapNodes": {
+      "problem": {
+        "title": "问题定义",
+        "text": "缺少项目级版本真源与tag协同"
+      },
+      "goal": {
+        "title": "版本轨道",
+        "text": "统一版本号、变化条目和tag"
+      },
+      "scope": {
+        "title": "四处落点",
+        "text": "ledger、commit、handoff、同步"
+      },
+      "flow": {
+        "title": "主流程",
+        "text": "版本累计变化，commit可挂tag"
+      },
+      "risk": {
+        "title": "主要风险",
+        "text": "远端tag覆盖和版本混用"
+      }
+    },
+    "panels": {
+      "flow": [
+        {
+          "summary": "新增轨道",
+          "detail": "项目可记录当前版本，并累计该版本内的需求、Bug和摘要。"
+        },
+        {
+          "summary": "关联提交",
+          "detail": "启用版本轨道后，commit 可读取当前版本并辅助挂本地 tag。"
+        },
+        {
+          "summary": "导出说明",
+          "detail": "handoff、版本说明和外部同步都可复用同一版本条目。"
+        }
+      ],
+      "function": [
+        {
+          "summary": "保留短文案",
+          "detail": "新增、修复、优化、调整、移除继续作为版本条目的默认动作词。"
+        },
+        {
+          "summary": "手动修正版",
+          "detail": "用户可以随时把当前版本从 0.1.23 调整到下一个版本。"
+        },
+        {
+          "summary": "同版续提",
+          "detail": "未切新版本时，后续提交继续累计到当前版本。"
+        }
+      ],
+      "guardrail": [
+        {
+          "summary": "分层版本",
+          "detail": "内部 PRD 版本 v000x 不直接等于项目发版号。"
+        },
+        {
+          "summary": "不强推送",
+          "detail": "不默认自动 push、发布或 force 更新远端 tag。"
+        },
+        {
+          "summary": "可分开启用",
+          "detail": "只想维护版本说明的项目可以不开 tag 辅助。"
+        }
+      ],
+      "risk": [
+        {
+          "summary": "远端冲突",
+          "detail": "同名 tag 已推到远端时，继续移动会变成高风险操作。"
+        },
+        {
+          "summary": "版本混用",
+          "detail": "若把 PRD 版本当发版号，会让 review 和 release 都变乱。"
+        },
+        {
+          "summary": "事实失真",
+          "detail": "变化条目归错版本，会让 handoff 和外部同步失真。"
+        }
+      ]
+    }
+  },
+  "workUnitId": "wu-20260602122244-78656aaf",
+  "targetRoot": "/Users/chaojifeng/Projects/harness-engineer/openprd",
+  "content": "# OpenPrd 用户视角变化摘要\n> 语言规则：默认用简体中文生成 PRD、spec、tasks 和用户可见说明；除 PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词外，其余内容优先写成简体中文。\n- 版本: v0003\n- 负责人: Codex\n- 产品类型: agent\n- 模板包: agent\n- 状态: synthesized\n- 生成时间: 2026-06-02 12:22:44\n## 元信息\n\n- 标题: OpenPrd 用户视角变化摘要\n- 负责人: Codex\n- 状态: clarifying\n- 版本: v0003\n- 产品类型: agent\n- 日期: 2026-06-02\n\n## 问题\n\n- 问题陈述: OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道来维护当前版本号、版本内更新项，以及与 commit tag 的协同规则。结果是版本号已经在项目里被真实使用，却缺少一个本地真源来累计本版本的需求、Bug、handoff 摘要和最终发布说明。\n- 为什么是现在: 用户已经确认，希望在现有短文案变化摘要的基础上，再补一个可选的项目级版本轨道：既能维护当前版本和版本内更新内容，也能在 commit 流里利用版本信息辅助打 tag，让 release notes、handoff 和外部同步有稳定来源。\n- 证据:\n  - 待补充\n\n## 用户与相关方\n\n- 主要用户:\n  - 维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer\n  - 使用 OpenPrd 执行任务并需要生成 commit、handoff 或版本说明的 Agent 使用者\n- 次要用户:\n  - 待补充\n- 相关方:\n  - 阅读交付变更、提交说明和版本说明的项目负责人\n  - 需要快速判断这次改动是否值得合入或发布的协作者\n\n## 目标与成功标准\n\n- 目标:\n  - 把用户可感知变化写法沉淀成 OpenPrd 的共享变化摘要 contract，而不是停留在单个 commit skill。\n  - 让 OpenPrd 在 loop commit、handoff / 版本说明、review 摘要三处都能输出更适合人阅读的变化说明。\n  - 保持 OpenPrd 现有 workflow、review gate 和高风险提交门禁不变，只升级表达层。\n- 成功指标:\n  - loop 默认 commit message 不再只输出 `Complete <task>` 这种执行口吻，而是优先输出短标题加动作词条目。\n  - handoff 导出结果包含可直接复用的变化摘要或版本说明片段，便于人快速扫读。\n  - review 摘要文案的标签和一句话说明更明显地站在用户视角表达新增、修复、优化、调整等变化。\n  - 完成后用单独 worker 跑一个样例项目，能看到这套变化摘要在真实任务中的输出效果。\n- 验收目标:\n  - 新增项目级 release/version ledger，支持 current version、版本状态和版本内变化项存储。\n  - 现有变化摘要层继续复用新增、修复、优化、调整、移除等短文案动作词，并能挂到具体项目版本下。\n  - commit 流在启用版本轨道且用户明确执行时，可以读取当前版本并辅助创建或更新本地版本 tag；同版本多次提交时 tag 可移动到最新 commit。\n  - README、skills、handoff/release 导出和测试同步说明版本轨道与 tag 协同规则。\n\n## 范围与非目标\n\n- 范围内:\n  - 新增可选的项目级 release/version ledger，用于维护当前版本号、版本状态和版本内更新项。\n  - 把现有变化摘要条目挂载到具体项目版本下，支持需求、Bug、handoff 摘要和 release notes 候选的累计。\n  - 扩展 commit 流，在版本轨道已启用且用户显式执行 commit 时读取当前版本，并辅助创建或更新本地版本 tag。\n  - 扩展 handoff、release notes 与后续外部同步出口，让它们可以从项目版本轨道导出版本内变化内容。\n  - 补充 README、skills、文档和测试，并验证项目版本轨道与短文案摘要的协同效果。\n- 范围外:\n  - 不把内部 PRD 版本 v000x 直接改造成项目发版号。\n  - 不强制所有项目都启用版本轨道；没有版本管理习惯的项目可以继续只用现有变化摘要能力。\n  - 不默认自动 push、自动发布或自动 force 更新远端 tag。\n  - 不要求替代团队已有的外部版本体系，只提供一个本地可维护、可导出的辅助真源。\n\n## 场景与流程\n\n- 主流程:\n  - 用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。\n  - 用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组织的变化摘要。\n  - 用户查看 review 评审摘要时，能先用短标签和一句话理解这次带来的用户可感知变化，而不是先读技术实现。\n- 边界情况:\n  - 项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。\n  - 如果同一个版本下发生多次 commit，本地 tag 可以移动到最新 commit；但如果对应 tag 已经推到远端，继续移动会变成高风险操作。\n  - 有些项目只想维护版本说明，不想碰 git tag；版本轨道与 tag 辅助能力需要可分开启用。\n  - 如果用户在没有更新版本号的情况下继续提交，系统应把新变化继续累计到当前版本，而不是猜测用户要自动 bump 版本。\n- 失败模式:\n  - commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等技术细节。\n  - 摘要为了好看而扭曲真实改动，把内部治理误写成用户可感知功能。\n  - 三处落点风格不一致，用户在 commit、handoff 和 review 里看到三套不同写法。\n\n## 可视化图表\n\n### 产品流程\n\n```mermaid\nflowchart LR\n  entry[\"入口触发<br/>用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。\"]\n  experience[\"产品内步骤<br/>用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组织的变化摘要。\"]\n  decision{\"决策点<br/>项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。\"}\n  success([\"成功结果<br/>loop 默认 commit message 不再只输出 'Complete task ' 这种执行口吻，而是优先输出短标题…\"])\n  failure[[\"失败与恢复<br/>commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等技术细节。\"]]\n  entry -->|\"用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd …\"| experience\n  experience -->|\"用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组…\"| decision\n  decision -->|\"把用户可感知变化写法沉淀成 OpenPrd 的共享变化摘要 contract，而不…\"| success\n  decision -.->|\"commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等…\"| failure\n```\n\n### 架构\n\n```mermaid\nflowchart LR\n  users[\"主要用户<br/>维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer · 使用 Open…\"]\n  subgraph solution[\"方案边界\"]\n    experience[\"Agent 运行层<br/>用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。 …\"]\n    core[\"核心产品逻辑<br/>OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道…\"]\n    integrations[\"依赖与集成<br/>依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 hand…\"]\n    governance[[\"约束与可靠性<br/>新增能力保持命令兼容；已有显式 message 或自定义文案优先级不能被破坏。 · formatter 只依赖本地上下文，不新…\"]]\n    delivery[\"验证与交接<br/>loop 默认 commit message 不再只输出 'Complete task ' 这种执行口吻，而是优先输出短标题…\"]\n  end\n  users -->|\"用户让 Agent 完成某个 task 并选择 commit 时，OpenPr…\"| experience\n  experience -->|\"产品动作与编排\"| core\n  core -->|\"依赖与外部服务\"| integrations\n  core -.->|\"策略、可靠性与合规\"| governance\n  core -->|\"成功标准与交接\"| delivery\n  integrations -->|\"运营就绪\"| delivery\n  governance -.->|\"评审与确认\"| delivery\n```\n\n## 需求\n\n- 功能需求:\n  - OpenPrd 提供可选的项目级 release/version ledger，支持记录 current version、版本状态和版本内变化项。\n  - 现有共享变化摘要规则支持把新增、修复、优化、调整、移除等条目关联到具体项目版本。\n  - handoff 与 release notes 导出优先从项目版本轨道读取对应版本的变化条目。\n  - 当版本轨道已启用且用户通过 OpenPrd 显式执行 commit 时，commit 流可以读取当前版本号并辅助创建或更新本地版本 tag。\n  - 当用户未更新版本号时，后续变化默认继续累计到当前版本；当用户显式更新版本号后，新的变化进入下一个版本。\n- 非功能需求:\n  - 新增能力保持命令兼容；已有显式 message 或自定义文案优先级不能被破坏。\n  - formatter 只依赖本地上下文，不新增外部网络、第三方 API 或额外付费依赖。\n  - 输出在中英文混合项目里仍以当前用户语言为主，必要专有名词保持原样。\n- 业务规则:\n  - 内部 PRD 版本和项目 release 版本必须保持分层，不能共用一个字段。\n  - 项目 release 版本默认允许用户手动指定或手动修正；系统只做辅助，不替用户决定版本 bump。\n  - 同版本多次 commit 时，本地版本 tag 可以指向最新 commit，帮助界定本版本从上一个版本 tag 之后的提交范围。\n  - 如果目标版本 tag 已经存在于远端，系统不得默认覆盖；需要明确提示当前指向并等待用户决定。\n  - 版本说明继续优先使用新增、修复、优化、调整、移除等人类可读动作词，而不是直接复述 git 变更细节。\n\n## 业务护栏\n\n- 成本来源:\n  - 无新增第三方付费调用成本；变化摘要完全基于本地上下文生成。\n- 额度与限制:\n  - 不引入新的用户额度或发布配额限制；沿用现有 commit / handoff 执行门禁。\n- 滥用防护:\n  - 不把自动 push、自动 tag 或历史重写并入默认能力，避免摘要能力演变成高风险自动发布路径。\n- 监控信号:\n  - 关注生成摘要是否频繁退回技术细节、是否在测试中出现失真或空摘要。\n- 报警阈值:\n  - 如果三处输出中任一处无法生成可信摘要并持续回退，需要在测试中显式暴露。\n- 止损动作:\n  - 当上下文不足或摘要质量不可信时，回退到现有安全文案，不自动包装。\n\n## 约束、依赖与风险\n\n- 技术约束:\n  - 需要兼容现有 loop、handoff、review-presentation 和 html-artifacts 的调用契约。\n  - 需要在 dirty workspace 中做窄改动，避免误伤正在进行的 test-strategy-router 等历史工作。\n- 合规要求:\n  - 待补充\n- 依赖:\n  - 依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 handoff 导出流程。\n- 假设:\n  - 用户更看重人能快速扫懂的变化摘要，而不是技术完整性优先的底层说明。\n  - 三处落点可以共用一套核心 formatter，再按场景做轻量渲染差异。\n- 风险:\n  - 如果 formatter 规则过死，可能把一些纯技术任务描述得失真。\n  - 如果只改一处而没有共用 contract，后续很快会再次分叉。\n- 开放问题:\n  - 版本轨道是否需要支持 Unreleased 这种未定版态，还是只维护一个明确 current version。\n  - 本地 tag 跟最新 commit 的策略是否只在未推远端前自动生效，还是需要更细的项目级配置。\n  - Feishu 等外部同步出口首期是否只导出版本说明，不直接回写外部系统。\n\n## 类型专项模块\n\n- 类型: Agent 专项\n- humanAgentContract: Agent 可以根据 task、handoff 和 review 上下文生成变化摘要草案，但不能把自动生成的摘要当成发布事实之外的营销文案；高风险提交行为仍遵守现有执行门禁。\n- autonomyBoundary: Agent 可以修改 OpenPrd 的 formatter、skills、文档、测试和 worker 验证流程；不得自动推送、改写历史提交，或把 Feature Git Commit 的高风险 git 行为直接并入 OpenPrd 默认流。\n- toolBoundary: 仅使用本地 OpenPrd 代码、CLI、测试与 worker 会话完成实现和验证；本次不需要额外第三方文档调研。\n- stateModel: 共享变化摘要 contract 负责统一标题、动作词和描述规则；loop、handoff、review 三个调用面只做各自场景渲染与回退控制。\n- evalPlan: 先做本地单测和回归，再用 worker 在单独样例项目上跑一个最小任务，检查 commit、handoff 或 review 摘要输出是否符合预期。\n\n## 交接\n\n- 负责人: Codex\n- 下一步: 确认新的评审稿后生成 change 和 tasks，并按三处落点实现。\n- 目标系统: OpenSpec\n",
+  "digest": "f1b18bc47cbd76f784b7682483eafa24eb02230e23189dad29a2202b61544918",
+  "reviewPresentationMeta": {
+    "validatedAt": "2026-06-02T04:23:28.482Z",
+    "source": "/tmp/openprd-v0003-review-presentation.json",
+    "presentationHash": "28234498b5654bffd5a595815c2c91c5930b7ce2a8fe467c8101c9b4658bbc8e",
+    "violationsHash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
+    "validator": "openprd review-presentation"
+  }
+}

package/.openprd/state/versions/v0003.md

@@ -0,0 +1,188 @@
+# OpenPrd 用户视角变化摘要
+> 语言规则：默认用简体中文生成 PRD、spec、tasks 和用户可见说明；除 PRD、OpenPrd、OpenSpec、API、SDK、CLI、TypeScript、JSON、HTTP、WebSocket、字段 key、命令名、品牌名、产品名和协议名等必要专有名词外，其余内容优先写成简体中文。
+- 版本: v0003
+- 负责人: Codex
+- 产品类型: agent
+- 模板包: agent
+- 状态: synthesized
+- 生成时间: 2026-06-02 12:22:44
+## 元信息
+
+- 标题: OpenPrd 用户视角变化摘要
+- 负责人: Codex
+- 状态: clarifying
+- 版本: v0003
+- 产品类型: agent
+- 日期: 2026-06-02
+
+## 问题
+
+- 问题陈述: OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道来维护当前版本号、版本内更新项，以及与 commit tag 的协同规则。结果是版本号已经在项目里被真实使用，却缺少一个本地真源来累计本版本的需求、Bug、handoff 摘要和最终发布说明。
+- 为什么是现在: 用户已经确认，希望在现有短文案变化摘要的基础上，再补一个可选的项目级版本轨道：既能维护当前版本和版本内更新内容，也能在 commit 流里利用版本信息辅助打 tag，让 release notes、handoff 和外部同步有稳定来源。
+- 证据:
+  - 待补充
+
+## 用户与相关方
+
+- 主要用户:
+  - 维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer
+  - 使用 OpenPrd 执行任务并需要生成 commit、handoff 或版本说明的 Agent 使用者
+- 次要用户:
+  - 待补充
+- 相关方:
+  - 阅读交付变更、提交说明和版本说明的项目负责人
+  - 需要快速判断这次改动是否值得合入或发布的协作者
+
+## 目标与成功标准
+
+- 目标:
+  - 把用户可感知变化写法沉淀成 OpenPrd 的共享变化摘要 contract，而不是停留在单个 commit skill。
+  - 让 OpenPrd 在 loop commit、handoff / 版本说明、review 摘要三处都能输出更适合人阅读的变化说明。
+  - 保持 OpenPrd 现有 workflow、review gate 和高风险提交门禁不变，只升级表达层。
+- 成功指标:
+  - loop 默认 commit message 不再只输出 `Complete <task>` 这种执行口吻，而是优先输出短标题加动作词条目。
+  - handoff 导出结果包含可直接复用的变化摘要或版本说明片段，便于人快速扫读。
+  - review 摘要文案的标签和一句话说明更明显地站在用户视角表达新增、修复、优化、调整等变化。
+  - 完成后用单独 worker 跑一个样例项目，能看到这套变化摘要在真实任务中的输出效果。
+- 验收目标:
+  - 新增项目级 release/version ledger，支持 current version、版本状态和版本内变化项存储。
+  - 现有变化摘要层继续复用新增、修复、优化、调整、移除等短文案动作词，并能挂到具体项目版本下。
+  - commit 流在启用版本轨道且用户明确执行时，可以读取当前版本并辅助创建或更新本地版本 tag；同版本多次提交时 tag 可移动到最新 commit。
+  - README、skills、handoff/release 导出和测试同步说明版本轨道与 tag 协同规则。
+
+## 范围与非目标
+
+- 范围内:
+  - 新增可选的项目级 release/version ledger，用于维护当前版本号、版本状态和版本内更新项。
+  - 把现有变化摘要条目挂载到具体项目版本下，支持需求、Bug、handoff 摘要和 release notes 候选的累计。
+  - 扩展 commit 流，在版本轨道已启用且用户显式执行 commit 时读取当前版本，并辅助创建或更新本地版本 tag。
+  - 扩展 handoff、release notes 与后续外部同步出口，让它们可以从项目版本轨道导出版本内变化内容。
+  - 补充 README、skills、文档和测试，并验证项目版本轨道与短文案摘要的协同效果。
+- 范围外:
+  - 不把内部 PRD 版本 v000x 直接改造成项目发版号。
+  - 不强制所有项目都启用版本轨道；没有版本管理习惯的项目可以继续只用现有变化摘要能力。
+  - 不默认自动 push、自动发布或自动 force 更新远端 tag。
+  - 不要求替代团队已有的外部版本体系，只提供一个本地可维护、可导出的辅助真源。
+
+## 场景与流程
+
+- 主流程:
+  - 用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。
+  - 用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组织的变化摘要。
+  - 用户查看 review 评审摘要时，能先用短标签和一句话理解这次带来的用户可感知变化，而不是先读技术实现。
+- 边界情况:
+  - 项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。
+  - 如果同一个版本下发生多次 commit，本地 tag 可以移动到最新 commit；但如果对应 tag 已经推到远端，继续移动会变成高风险操作。
+  - 有些项目只想维护版本说明，不想碰 git tag；版本轨道与 tag 辅助能力需要可分开启用。
+  - 如果用户在没有更新版本号的情况下继续提交，系统应把新变化继续累计到当前版本，而不是猜测用户要自动 bump 版本。
+- 失败模式:
+  - commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等技术细节。
+  - 摘要为了好看而扭曲真实改动，把内部治理误写成用户可感知功能。
+  - 三处落点风格不一致，用户在 commit、handoff 和 review 里看到三套不同写法。
+
+## 可视化图表
+
+### 产品流程
+
+```mermaid
+flowchart LR
+  entry["入口触发<br/>用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。"]
+  experience["产品内步骤<br/>用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组织的变化摘要。"]
+  decision{"决策点<br/>项目可能已经有自己的一套版本号规则，OpenPrd 需要允许手动修正当前版本号，而不是强推默认策略。"}
+  success(["成功结果<br/>loop 默认 commit message 不再只输出 'Complete task ' 这种执行口吻，而是优先输出短标题…"])
+  failure[["失败与恢复<br/>commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等技术细节。"]]
+  entry -->|"用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd …"| experience
+  experience -->|"用户导出 handoff 或版本说明时，可以直接看到一段按新增、修复、优化、调整组…"| decision
+  decision -->|"把用户可感知变化写法沉淀成 OpenPrd 的共享变化摘要 contract，而不…"| success
+  decision -.->|"commit、handoff 或 review 摘要仍泄露文件名、函数名、参数值等…"| failure
+```
+
+### 架构
+
+```mermaid
+flowchart LR
+  users["主要用户<br/>维护 OpenPrd CLI、skills 和 review 产物的 OpenPrd maintainer · 使用 Open…"]
+  subgraph solution["方案边界"]
+    experience["Agent 运行层<br/>用户让 Agent 完成某个 task 并选择 commit 时，OpenPrd 默认生成更适合人阅读的提交标题与变化条目。 …"]
+    core["核心产品逻辑<br/>OpenPrd 现在已经有内部 PRD 版本和用户视角变化摘要，但还没有一个可选的项目级 release/version 轨道…"]
+    integrations["依赖与集成<br/>依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 hand…"]
+    governance[["约束与可靠性<br/>新增能力保持命令兼容；已有显式 message 或自定义文案优先级不能被破坏。 · formatter 只依赖本地上下文，不新…"]]
+    delivery["验证与交接<br/>loop 默认 commit message 不再只输出 'Complete task ' 这种执行口吻，而是优先输出短标题…"]
+  end
+  users -->|"用户让 Agent 完成某个 task 并选择 commit 时，OpenPr…"| experience
+  experience -->|"产品动作与编排"| core
+  core -->|"依赖与外部服务"| integrations
+  core -.->|"策略、可靠性与合规"| governance
+  core -->|"成功标准与交接"| delivery
+  integrations -->|"运营就绪"| delivery
+  governance -.->|"评审与确认"| delivery
+```
+
+## 需求
+
+- 功能需求:
+  - OpenPrd 提供可选的项目级 release/version ledger，支持记录 current version、版本状态和版本内变化项。
+  - 现有共享变化摘要规则支持把新增、修复、优化、调整、移除等条目关联到具体项目版本。
+  - handoff 与 release notes 导出优先从项目版本轨道读取对应版本的变化条目。
+  - 当版本轨道已启用且用户通过 OpenPrd 显式执行 commit 时，commit 流可以读取当前版本号并辅助创建或更新本地版本 tag。
+  - 当用户未更新版本号时，后续变化默认继续累计到当前版本；当用户显式更新版本号后，新的变化进入下一个版本。
+- 非功能需求:
+  - 新增能力保持命令兼容；已有显式 message 或自定义文案优先级不能被破坏。
+  - formatter 只依赖本地上下文，不新增外部网络、第三方 API 或额外付费依赖。
+  - 输出在中英文混合项目里仍以当前用户语言为主，必要专有名词保持原样。
+- 业务规则:
+  - 内部 PRD 版本和项目 release 版本必须保持分层，不能共用一个字段。
+  - 项目 release 版本默认允许用户手动指定或手动修正；系统只做辅助，不替用户决定版本 bump。
+  - 同版本多次 commit 时，本地版本 tag 可以指向最新 commit，帮助界定本版本从上一个版本 tag 之后的提交范围。
+  - 如果目标版本 tag 已经存在于远端，系统不得默认覆盖；需要明确提示当前指向并等待用户决定。
+  - 版本说明继续优先使用新增、修复、优化、调整、移除等人类可读动作词，而不是直接复述 git 变更细节。
+
+## 业务护栏
+
+- 成本来源:
+  - 无新增第三方付费调用成本；变化摘要完全基于本地上下文生成。
+- 额度与限制:
+  - 不引入新的用户额度或发布配额限制；沿用现有 commit / handoff 执行门禁。
+- 滥用防护:
+  - 不把自动 push、自动 tag 或历史重写并入默认能力，避免摘要能力演变成高风险自动发布路径。
+- 监控信号:
+  - 关注生成摘要是否频繁退回技术细节、是否在测试中出现失真或空摘要。
+- 报警阈值:
+  - 如果三处输出中任一处无法生成可信摘要并持续回退，需要在测试中显式暴露。
+- 止损动作:
+  - 当上下文不足或摘要质量不可信时，回退到现有安全文案，不自动包装。
+
+## 约束、依赖与风险
+
+- 技术约束:
+  - 需要兼容现有 loop、handoff、review-presentation 和 html-artifacts 的调用契约。
+  - 需要在 dirty workspace 中做窄改动，避免误伤正在进行的 test-strategy-router 等历史工作。
+- 合规要求:
+  - 待补充
+- 依赖:
+  - 依赖现有 OpenPrd CLI、review-presentation、html-artifacts、loop 和 handoff 导出流程。
+- 假设:
+  - 用户更看重人能快速扫懂的变化摘要，而不是技术完整性优先的底层说明。
+  - 三处落点可以共用一套核心 formatter，再按场景做轻量渲染差异。
+- 风险:
+  - 如果 formatter 规则过死，可能把一些纯技术任务描述得失真。
+  - 如果只改一处而没有共用 contract，后续很快会再次分叉。
+- 开放问题:
+  - 版本轨道是否需要支持 Unreleased 这种未定版态，还是只维护一个明确 current version。
+  - 本地 tag 跟最新 commit 的策略是否只在未推远端前自动生效，还是需要更细的项目级配置。
+  - Feishu 等外部同步出口首期是否只导出版本说明，不直接回写外部系统。
+
+## 类型专项模块
+
+- 类型: Agent 专项
+- humanAgentContract: Agent 可以根据 task、handoff 和 review 上下文生成变化摘要草案，但不能把自动生成的摘要当成发布事实之外的营销文案；高风险提交行为仍遵守现有执行门禁。
+- autonomyBoundary: Agent 可以修改 OpenPrd 的 formatter、skills、文档、测试和 worker 验证流程；不得自动推送、改写历史提交，或把 Feature Git Commit 的高风险 git 行为直接并入 OpenPrd 默认流。
+- toolBoundary: 仅使用本地 OpenPrd 代码、CLI、测试与 worker 会话完成实现和验证；本次不需要额外第三方文档调研。
+- stateModel: 共享变化摘要 contract 负责统一标题、动作词和描述规则；loop、handoff、review 三个调用面只做各自场景渲染与回退控制。
+- evalPlan: 先做本地单测和回归，再用 worker 在单独样例项目上跑一个最小任务，检查 commit、handoff 或 review 摘要输出是否符合预期。
+
+## 交接
+
+- 负责人: Codex
+- 下一步: 确认新的评审稿后生成 change 和 tasks，并按三处落点实现。
+- 目标系统: OpenSpec