okr-role-run

name	okr-role-run
description	Execute a specified DoWithOKR role or role KR while preserving upper-level mapping, evidence, and status updates.

OKR Role Run

输入参数

参数	类型	必填	说明
role	string	是	目标角色名（如"BE 后端开发工程师"、"ArchD 技术总监"、"PD 产品总监"）
kr	string	否	KR 编号（如"BE-KR2"），不指定则执行该角色全部 KR

参数解析规则

• 从用户消息中提取角色名作为 role，提取 KR 编号作为 kr。
• 如果用户未指定角色，提示补充："请指定要执行的角色，如：BE 后端开发工程师"。
• kr 缺省时执行该角色所有 KR。
• 支持组合指定：role + kr 定位到具体角色的具体 KR。
• 示例：执行后端开发 → role = "BE 后端开发工程师", kr = 空
• 示例：跑一下 BE-KR2 → role = 从层级 OKR 中反查, kr = "BE-KR2"
• 示例：执行技术总监的 KR1 → role = "ArchD 技术总监", kr = "ARCHD-KR1"

前置条件

• 需要：目标角色名或 KR 编号（从用户输入中解析）。
• 需要：已确认的层级 OKR 和状态看板。
• 缺失处理：
  • 未指定角色 → 提示用户指定角色名或 KR 编号，例如"请指定要执行的角色，如：BE 后端开发工程师"。
  • 缺少层级 OKR → 提示先运行 okr-planner。
  • 缺少状态看板 → 提示先运行 okr-planner 或 okr-execution-plan。

Role Preamble（角色上下文加载）

角色启动时必须完成以下上下文加载，建立完整的 OKR 环境感知后再进入执行。

状态文件读取

• 读取 .okr/active.md。
  • 文件不存在 → 提示用户先运行 okr-gm。
  • 缺少 ## 层级 OKR 区块 → 提示用户先运行 okr-planner。
• 读取 .okr/status.md。
  • 文件不存在 → 提示用户先运行 okr-planner 或 okr-execution-plan 生成初始看板。
• 从 ## 层级 OKR 中定位目标角色和 KR，提取上级映射链（如 BE-KR1 → ARCHD-KR1 → GM-KR1）。
• 从 status.md 中读取目标 KR 当前状态。
• 读取 .okr/active.md 中的 ## 交付验证计划 区块（如存在），提取目标 KR 的验收标准、验证方法和证据类型。
• 读取 .okr/wisdom/{role}.md（如存在），获取角色的专业知识和历史教训，作为执行的先验知识。
• 读取 .okr/evidence/{KR-ID}.md（如存在），获取该 KR 已有的证据记录。

上下文摘要输出

状态文件读取完成后，必须输出结构化的角色上下文摘要，确认执行目标：

### 角色上下文

- 角色: {role}
- 目标 KR: {KR-ID} — {KR 内容}
- 上级映射: {KR-ID} → {上级 KR-ID} → {GM KR-ID}
- 验收标准:
  1. {标准 1}
  2. {标准 2}
  ...
- 当前状态: {从 status.md 读取}
- 上游依赖: {上级 KR 状态，已完成/进行中/未开始}
- 历史经验: {从 wisdom 提取 1-3 条关键条目，无则显示"首次执行，无历史经验"}
- 已有证据: {已有 N 条证据 / 无}

上下文摘要是角色执行的"仪表盘"——后续所有决策和自检都以此为锚点。

执行规则

• 用于执行某个角色或某个角色 KR。
• 执行前必须展示上级映射，例如 BE-KR1 -> ARCHD-KR1 -> GM-KR1。
• 执行中只处理该角色职责范围内的内容。
• 执行中面临技术选型、范围判断、质量取舍、时间权衡等决策时，必须回答："此决策对应 KR: {KR-ID}，服务于验收标准: {具体标准}"。如果无法回答，属于范围蔓延，应停止并输出偏离说明（参考 ../../references/decision-anchor-spec.md）。
• 执行过程中持续进行偏离检测：范围蔓延 → 停止重新规划；越界操作 → 标记阻塞交由对应角色；时间超限 → 评估最小可行交付。
• 跳过上游角色时，提示风险但不强制阻止。
• 完成后必须更新状态：未开始、进行中、阻塞、已完成、放弃。

执行步骤

1. 解析用户输入，确定目标：
   • 指定角色名（如"BE 后端开发工程师"）→ 执行该角色所有 KR。
   • 指定 KR 编号（如"BE-KR2"）→ 只执行该 KR。
   • 指定角色 + KR（如"技术总监下面后端开发的 KR2"）→ 定位并执行。
2. 输出角色上下文摘要（Role Preamble 中定义的格式）：
   • 角色名、目标 KR、上级映射链。
   • 验收标准（逐条列出）。
   • 当前状态（从 status.md 读取）。
   • 上游依赖状态（上级 KR 是否已完成）。
   • 角色 wisdom 摘要（如存在）：展示相关专业知识和历史教训。
   • 已有证据（如存在）。
3. 检查上游依赖：
   • 上游 KR 已完成 → 正常执行。
   • 上游 KR 未完成 → 提示风险（"上游 ARCHD-KR1 尚未完成，继续执行可能产出不完整"），但不强制阻止。
4. 角色自主交付：
   • 角色读取 KR 内容和验收标准后，自主决定实现路径。系统不规定步骤顺序。
   • 以下角色职责描述仅作为能力参考，不作为执行约束：
     • PD 产品总监：管理产品方向，协调 PM、UI、TW 的产出，确保产品方案完整。
     • PM 产品经理：输出用户流程、权限矩阵、验收标准等文档。
     • UI 设计师：输出 UI 设计稿、交互规范、视觉标准。
     • ArchD 技术总监：输出技术方案、接口设计、数据模型等。
     • BE 后端开发工程师：实现 API、数据模型、业务逻辑，产出代码和测试。
     • FE 前端开发工程师：实现页面、状态管理、交互，产出代码和截图。
     • QA 测试工程师：编写测试用例、执行测试、记录结果。
     • TW 文档专家/DX：输出 README、示例、安装和故障排查文档。
     • 其他角色（DevOps、SEC）：按其职责定义执行。
   • 角色有权选择自己认为最优的技术方案、实现路径和工具链。
   • 角色自主决定实现路径，但每个关键决策必须锚定 KR 验收标准（参考 ../../references/decision-anchor-spec.md）。决策锚点格式："选择 {方案}，因为它有利于达成 {KR-ID} 的 {验收标准}"。
   • 角色在执行过程中可调用外部技能辅助完成 KR（参考 ../../references/skill-invocation-spec.md）。调用前必须通过三问检查（目的、证据、职责），调用时携带 OKR 上下文，调用后将产出记录为证据。调用范围须符合角色-技能权限矩阵。
5. 交付自检：
   • 执行完成后，角色按验收标准逐条自检（如有交付验证计划）。
   • 输出标准化自检报告表格：

     | 验收标准 | 达标情况 | 证据 | 差距说明 |
     | --- | --- | --- | --- |
     | {标准} | ✅ 达标 / ⚠️ 部分达标 / ❌ 未达标 | {证据引用} | {差距或 -} |
     

   • 达标情况枚举：
     • ✅ 达标：完全满足验收标准。
     • ⚠️ 部分达标：核心功能完成但指标未完全达到。
     • ❌ 未达标：关键项缺失或严重不足。
   • 自检结果与 KR 状态映射：
     • 全部 ✅ → 状态改为"已完成"。
     • 存在 ⚠️ 但无 ❌ → 状态保持"进行中"，标注差距和补救计划。
     • 存在 ❌ → 状态改为"阻塞"，说明阻塞原因和建议。
   • 无交付验证计划时，按 KR 的质量指标进行基础自检，同样使用上述表格格式。
6. 收集执行证据（参考 ../../references/evidence-spec.md）：
   • 扫描 git diff --name-only 获取本次执行新增或修改的文件列表，记录为 文件 类型证据。
   • 如果执行过程中产生了 git commit，记录 commit hash 为 commit 类型证据。
   • 如果执行了测试命令，捕获测试通过/失败结果，记录为 测试 类型证据。
   • PD、PM、TW 等角色产出的文档，记录为 文档 类型证据。
   • FE 前端角色产出的 UI 截图，记录为 截图 类型证据。
   • 如果执行过程中调用了外部技能（参考 ../../references/skill-invocation-spec.md），将外部技能的关键产出记录为对应类型的证据。
7. 写入证据文件 .okr/evidence/{KR-ID}.md：
   • 文件不存在 → 创建，写入标题 # {KR-ID} 证据 和表头 | 类型 | 路径/引用 | 说明 | 时间 |。
   • 文件已存在 → 追加新证据行，不覆盖历史条目。
   • 每条证据一行，时间格式 YYYY-MM-DD。
8. 更新 .okr/status.md 中对应 KR 的证据列：
   • 格式：[N 条](.okr/evidence/{KR-ID}.md)，N 为该 KR 当前证据总条目数。
   • 无证据时显示 无。
9. 更新状态文件。

输出格式

输出角色执行报告。

必须包含：

• 角色
• 执行 KR
• 上级映射
• 交付物（描述实际交付了什么，而非做了什么步骤）
• 自检结果（每条验收标准的达标情况：达标 / 部分达标 / 未达标）
• 证据
• 状态
• 下一步

异常处理

• 目标角色不在角色树中：提示用户检查角色名，展示当前角色树供选择。
• 目标 KR 已标记为"已完成"：提示用户该 KR 已完成，询问是否重新执行。
• 目标 KR 状态为"阻塞"：展示阻塞原因，建议先解决阻塞再执行。
• 执行过程中发现需求超出角色职责：停止执行，提示该部分应由其他角色负责。
• 偏离检测触发：输出偏离警告（格式参考 ../../references/decision-anchor-spec.md），按偏离类型执行对应处理规则（范围蔓延 → 停止重新规划；越界操作 → 标记阻塞；时间超限 → 评估降级）。

产出写入

• 更新 .okr/status.md：
  • 修改目标 KR 行的状态、进展、证据和下一步字段。
  • 更新 frontmatter：last_updated、updated_by: okr-role-run。
• 写入 .okr/evidence/{KR-ID}.md（格式参考 ../../references/evidence-spec.md）：
  • 文件不存在 → 创建，写入 # {KR-ID} 证据 标题和 | 类型 | 路径/引用 | 说明 | 时间 | 表头。
  • 文件已存在 → 在表格末尾追加新证据行，保留历史条目。
  • 证据类型必须使用枚举值：文件、commit、测试、截图、日志、文档。
  • 更新 status.md 中对应 KR 的证据列为 [N 条](.okr/evidence/{KR-ID}.md)。
• 更新 .okr/active.md frontmatter：
  • 根据执行进度更新 current_act（如从 M2 进入 M3）。
  • 更新 last_updated、updated_by: okr-role-run。