@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

package/.agents/orchestration/expert-dispatch-spec.md

@@ -1,155 +1,155 @@
----
-id: expert-dispatch-spec
-name: 专家派发载荷规范
-status: active
-owner: task-orchestrator
-description: 定义当前运行态如何生成并更新当前专家执行载荷，使 run（运行编排） 能稳定衔接到专家实际执行。
----
-
-# 专家派发载荷规范
-
-> **Profile 驱动说明（V1）**：本规范中的示例以 `frontend-implementer` 作为实现角色。实际派发时，`expert.id` 应根据当前 profile 的 `implementation_role` 动态填入（`frontend-implementer` / `backend-implementer` / `tooling-implementer`）。
->
-> **多 profile 说明**：当 manifest 使用 `profiles` 数组时（如 `["vue", "nestjs"]`），`task-orchestrator` 须先通过"路径前缀匹配"确定本次变更属于哪个子包，再取对应 profile 的 `implementation_role` 作为 `expert.id`。
-
-## 1. 目的
-
-这份规范解决的问题是：
-
-> `run-state（运行状态）` 已经落盘，但系统还需要一份由 `task-orchestrator（任务主代理）` 明确产出的“当前专家可执行载荷”。
-
-因此当前推荐形态是：
-
-- `task-orchestrator（任务主代理）` 负责理解任务、选择角色、裁剪上下文、决定技能
-- 本地工具只负责校验和落盘 `expert-dispatch（专家派发载荷）`
-
-## 2. 推荐落盘位置
-
-当前阶段使用两处落盘：
-
-- `.ai-spec/internal/current-dispatch.json`
-- `.ai-spec/internal/dispatches/<run-id>/<dispatch-id>.json`
-
-其中：
-
-- `internal/current-dispatch.json`
-  - 始终表示“当前这一轮应该交给谁执行”
-- `internal/dispatches/<run-id>/`
-  - 记录本次运行历史上生成过哪些专家执行载荷
-
-## 3. 最小结构
-
-```json
-{
-  "schema_version": 1,
-  "kind": "expert-dispatch",
-  "dispatch_id": "2026-03-31T15-10-00-000Z__frontend-implementer",
-  "generated_at": "2026-03-31T15:10:00.000Z",
-  "run_id": "run_20260331_151000_abcd",
-  "status": "running",
-  "role": {
-    "id": "frontend-implementer",
-    "name": "前端实现专家",
-    "source": ".agents/roles/common/frontend-implementer.md",
-    "preferred_skills": ["execute-task", "create-component"]
-  },
-  "task": {
-    "raw_goal": "创建一个商品组件",
-    "change_id": "add-product-card"
-  },
-  "flow": {
-    "id": "prd-to-delivery"
-  },
-  "execution": {
-    "profile": "vue",
-    "current_role": "frontend-implementer",
-    "next_role": "code-guardian",
-    "pending_gate": null,
-    "expected_output": ["完成组件实现"],
-    "skills": [
-      {
-        "id": "create-component",
-        "installed": true,
-        "path": ".agents/skills/create-component/SKILL.md"
-      }
-    ]
-  },
-  "anchor": {
-    "kind": "task-anchor"
-  },
-  "instructions": {
-    "source": ".agents/roles/common/frontend-implementer.md",
-    "markdown": "# 前端实现专家 ..."
-  }
-}
-```
-
-## 4. 推荐接入方式
-
-当前最稳的接入方式是：
-
-```bash
-ai-spec-auto expert-dispatch apply --payload ./.ai-spec/internal/tmp/current-dispatch.json
-```
-
-或：
-
-```bash
-cat ./.ai-spec/internal/tmp/current-dispatch.json | ai-spec-auto expert-dispatch apply --stdin
-```
-
-也就是说：
-
-- `expert-dispatch（专家派发载荷）` 的内容由 `task-orchestrator（任务主代理）` 产出
-- `bin/` 只做校验、补齐时间戳和 ID、落盘
-- 对 `prd-to-delivery（需求到交付）`，`task.change_id` 必须随派发一起下发，不能丢
-- `requirement-analyst（需求解析专家）` 的 `expected_output` 必须显式包含 `proposal.md` 与 `tasks.md`
-- `code-guardian（规范守护者）` 的 `expected_output` 必须显式包含 `checklist.md` 与 `iterations.md`
-
-推荐在以下动作后由 `task-orchestrator（任务主代理）` 再次产出新的当前派发：
-
-- `bootstrap（首轮桥接）`
-- `handoff（交接）`
-- `approve（审批）`
-- `resume（恢复）`
-
-推荐在以下终态动作后清理当前派发：
-
-- `complete（完成）`
-- `fail（失败）`
-- `cancel（取消）`
-
-## 5. 一句话约束
-
-> `expert-dispatch（专家派发载荷）` 应由 `task-orchestrator（任务主代理）` 产出，本地只负责校验与落盘；不要让本地脚本替代 `task-orchestrator（任务主代理）` 做角色理解、技能选择和上下文裁剪。
-
-补充：
-
-- 若当前流程是 `prd-to-delivery（需求到交付）` 且目标角色是 `requirement-analyst / frontend-implementer / code-guardian`，则 `task.change_id` 缺失应视为非法派发
-
-## 6. 多 profile 下的角色选择规则
-
-当 `.ai-spec/manifest.json` 的 `profiles` 为数组时，`task-orchestrator` 按以下逻辑确定 `expert.id`：
-
-1. 检查本次任务涉及的文件路径列表
-2. 将路径与 `manifest.packages[].path` 逐一做**前缀匹配**
-3. 命中某子包 → 取该子包对应 profile 的 `implementation_role`（从 `profiles.json` 查询）
-4. 多个文件跨多个子包 → 按主体变更量所在子包决定，或拆成多轮派发
-5. 无法匹配任何子包（如根目录配置文件修改）→ 优先使用 `code-guardian` 角色处理，不要猜测技术栈
-
-**示例（vue + nestjs）**：
-
-```
-packages/front/src/components/Foo.vue  → profile: vue  → implementation_role: frontend-implementer
-packages/server/src/user/user.service.ts → profile: nestjs → implementation_role: backend-implementer
-```
-
-`execution.profile` 字段应填写本次实际生效的 profile（非数组，填具体值）：
-
-```json
-"execution": {
-  "profile": "nestjs",
-  "current_role": "backend-implementer",
-  ...
-}
-```
+---
+id: expert-dispatch-spec
+name: 专家派发载荷规范
+status: active
+owner: task-orchestrator
+description: 定义当前运行态如何生成并更新当前专家执行载荷，使 run（运行编排） 能稳定衔接到专家实际执行。
+---
+
+# 专家派发载荷规范
+
+> **Profile 驱动说明（V1）**：本规范中的示例以 `frontend-implementer` 作为实现角色。实际派发时，`expert.id` 应根据当前 profile 的 `implementation_role` 动态填入（`frontend-implementer` / `backend-implementer` / `tooling-implementer`）。
+>
+> **多 profile 说明**：当 manifest 使用 `profiles` 数组时（如 `["vue", "nestjs"]`），`task-orchestrator` 须先通过"路径前缀匹配"确定本次变更属于哪个子包，再取对应 profile 的 `implementation_role` 作为 `expert.id`。
+
+## 1. 目的
+
+这份规范解决的问题是：
+
+> `run-state（运行状态）` 已经落盘，但系统还需要一份由 `task-orchestrator（任务主代理）` 明确产出的“当前专家可执行载荷”。
+
+因此当前推荐形态是：
+
+- `task-orchestrator（任务主代理）` 负责理解任务、选择角色、裁剪上下文、决定技能
+- 本地工具只负责校验和落盘 `expert-dispatch（专家派发载荷）`
+
+## 2. 推荐落盘位置
+
+当前阶段使用两处落盘：
+
+- `.ai-spec/internal/current-dispatch.json`
+- `.ai-spec/internal/dispatches/<run-id>/<dispatch-id>.json`
+
+其中：
+
+- `internal/current-dispatch.json`
+  - 始终表示“当前这一轮应该交给谁执行”
+- `internal/dispatches/<run-id>/`
+  - 记录本次运行历史上生成过哪些专家执行载荷
+
+## 3. 最小结构
+
+```json
+{
+  "schema_version": 1,
+  "kind": "expert-dispatch",
+  "dispatch_id": "2026-03-31T15-10-00-000Z__frontend-implementer",
+  "generated_at": "2026-03-31T15:10:00.000Z",
+  "run_id": "run_20260331_151000_abcd",
+  "status": "running",
+  "role": {
+    "id": "frontend-implementer",
+    "name": "前端实现专家",
+    "source": ".agents/roles/common/frontend-implementer.md",
+    "preferred_skills": ["execute-task", "create-component"]
+  },
+  "task": {
+    "raw_goal": "创建一个商品组件",
+    "change_id": "add-product-card"
+  },
+  "flow": {
+    "id": "prd-to-delivery"
+  },
+  "execution": {
+    "profile": "vue",
+    "current_role": "frontend-implementer",
+    "next_role": "code-guardian",
+    "pending_gate": null,
+    "expected_output": ["完成组件实现"],
+    "skills": [
+      {
+        "id": "create-component",
+        "installed": true,
+        "path": ".agents/skills/create-component/SKILL.md"
+      }
+    ]
+  },
+  "anchor": {
+    "kind": "task-anchor"
+  },
+  "instructions": {
+    "source": ".agents/roles/common/frontend-implementer.md",
+    "markdown": "# 前端实现专家 ..."
+  }
+}
+```
+
+## 4. 推荐接入方式
+
+当前最稳的接入方式是：
+
+```bash
+ai-spec-auto expert-dispatch apply --payload ./.ai-spec/internal/tmp/current-dispatch.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-dispatch.json | ai-spec-auto expert-dispatch apply --stdin
+```
+
+也就是说：
+
+- `expert-dispatch（专家派发载荷）` 的内容由 `task-orchestrator（任务主代理）` 产出
+- `bin/` 只做校验、补齐时间戳和 ID、落盘
+- 对 `prd-to-delivery（需求到交付）`，`task.change_id` 必须随派发一起下发，不能丢
+- `requirement-analyst（需求解析专家）` 的 `expected_output` 必须显式包含 `proposal.md` 与 `tasks.md`
+- `code-guardian（规范守护者）` 的 `expected_output` 必须显式包含 `checklist.md` 与 `iterations.md`
+
+推荐在以下动作后由 `task-orchestrator（任务主代理）` 再次产出新的当前派发：
+
+- `bootstrap（首轮桥接）`
+- `handoff（交接）`
+- `approve（审批）`
+- `resume（恢复）`
+
+推荐在以下终态动作后清理当前派发：
+
+- `complete（完成）`
+- `fail（失败）`
+- `cancel（取消）`
+
+## 5. 一句话约束
+
+> `expert-dispatch（专家派发载荷）` 应由 `task-orchestrator（任务主代理）` 产出，本地只负责校验与落盘；不要让本地脚本替代 `task-orchestrator（任务主代理）` 做角色理解、技能选择和上下文裁剪。
+
+补充：
+
+- 若当前流程是 `prd-to-delivery（需求到交付）` 且目标角色是 `requirement-analyst / frontend-implementer / code-guardian`，则 `task.change_id` 缺失应视为非法派发
+
+## 6. 多 profile 下的角色选择规则
+
+当 `.ai-spec/manifest.json` 的 `profiles` 为数组时，`task-orchestrator` 按以下逻辑确定 `expert.id`：
+
+1. 检查本次任务涉及的文件路径列表
+2. 将路径与 `manifest.packages[].path` 逐一做**前缀匹配**
+3. 命中某子包 → 取该子包对应 profile 的 `implementation_role`（从 `profiles.json` 查询）
+4. 多个文件跨多个子包 → 按主体变更量所在子包决定，或拆成多轮派发
+5. 无法匹配任何子包（如根目录配置文件修改）→ 优先使用 `code-guardian` 角色处理，不要猜测技术栈
+
+**示例（vue + nestjs）**：
+
+```
+packages/front/src/components/Foo.vue  → profile: vue  → implementation_role: frontend-implementer
+packages/server/src/user/user.service.ts → profile: nestjs → implementation_role: backend-implementer
+```
+
+`execution.profile` 字段应填写本次实际生效的 profile（非数组，填具体值）：
+
+```json
+"execution": {
+  "profile": "nestjs",
+  "current_role": "backend-implementer",
+  ...
+}
+```

package/.agents/orchestration/expert-executor-spec.md

@@ -1,84 +1,84 @@
----
-id: expert-executor-spec
-name: 单轮专家执行器规范
-status: active
-owner: task-orchestrator
-description: 定义如何消费 current-dispatch（当前专家派发载荷），为当前专家生成单轮执行载荷，不自动递归推进下一轮。
----
-
-# 单轮专家执行器规范
-
-## 1. 目的
-
-这份规范解决的问题是：
-
-> 当前系统已经有 `run-state（运行状态）` 和 `expert-dispatch（专家派发载荷）`，但还需要一份由“当前专家”明确产出的“本轮执行输入”。
-
-因此当前阶段的最小实现是：
-
-- 当前专家负责产出 `expert-execution（专家执行载荷）`
-- 本地工具默认负责校验和落盘
-- 当显式启用 `--advance-runtime` 时，本地工具还会把本轮执行稳定映射到运行态更新
-- Phase A（第一步） 只到执行载荷
-- Phase B（第二步） 可额外落盘 `runtime-action（运行动作）` 草案
-- 不自动递归跑完整链
-
-## 2. 当前支持角色
-
-Phase A（第一步） 当前只要求支持 3 个角色：
-
-- `requirement-analyst（需求解析专家）`
-- `frontend-implementer（前端实现专家）`
-- `code-guardian（规范守护者）`
-
-## 3. 推荐落盘位置
-
-- `.ai-spec/internal/current-execution.json`
-- `.ai-spec/internal/current-execution.md`
-- `.ai-spec/internal/executions/<run-id>/<execution-id>.json`
-- `.ai-spec/internal/executions/<run-id>/<execution-id>.md`
-
-## 4. 推荐接入方式
-
-当前最稳的接入方式是：
-
-```bash
-ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json
-```
-
-或：
-
-```bash
-cat ./.ai-spec/internal/tmp/current-execution.json | ai-spec-auto expert-executor apply --stdin
-```
-
-如果当前环境希望把执行语义和运行态直接接通，可显式启用：
-
-```bash
-ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json --advance-runtime
-```
-
-此时工具会：
-
-- 识别 `requirement-analyst -> propose`
-- 识别 `frontend-implementer -> apply`
-- 识别 `code-guardian -> verify`
-- 优先读取 `.agents/registry/roles.json` 中的动作与交接约定，代码内置映射只作保底
-- 校验对应 OpenSpec 产物
-- 在确定的流转场景下生成并应用最小 `runtime-action（运行动作）`
-
-Phase B（第二步） 仍支持继续落盘 `runtime-action（运行动作）` 草案：
-
-```bash
-ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
-```
-
-如需直接提交到运行态：
-
-```bash
-ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
-```
-
-## 5. 一句话约束
-
-> `expert-executor（专家执行器）` 不应替当前专家做技能选择、执行推理和下一步动作判断；它可以在显式授权下推进最小运行态，但仍不负责自动生成下一轮 `expert-dispatch（专家派发载荷）`。
+---
+id: expert-executor-spec
+name: 单轮专家执行器规范
+status: active
+owner: task-orchestrator
+description: 定义如何消费 current-dispatch（当前专家派发载荷），为当前专家生成单轮执行载荷，不自动递归推进下一轮。
+---
+
+# 单轮专家执行器规范
+
+## 1. 目的
+
+这份规范解决的问题是：
+
+> 当前系统已经有 `run-state（运行状态）` 和 `expert-dispatch（专家派发载荷）`，但还需要一份由“当前专家”明确产出的“本轮执行输入”。
+
+因此当前阶段的最小实现是：
+
+- 当前专家负责产出 `expert-execution（专家执行载荷）`
+- 本地工具默认负责校验和落盘
+- 当显式启用 `--advance-runtime` 时，本地工具还会把本轮执行稳定映射到运行态更新
+- Phase A（第一步） 只到执行载荷
+- Phase B（第二步） 可额外落盘 `runtime-action（运行动作）` 草案
+- 不自动递归跑完整链
+
+## 2. 当前支持角色
+
+Phase A（第一步） 当前只要求支持 3 个角色：
+
+- `requirement-analyst（需求解析专家）`
+- `frontend-implementer（前端实现专家）`
+- `code-guardian（规范守护者）`
+
+## 3. 推荐落盘位置
+
+- `.ai-spec/internal/current-execution.json`
+- `.ai-spec/internal/current-execution.md`
+- `.ai-spec/internal/executions/<run-id>/<execution-id>.json`
+- `.ai-spec/internal/executions/<run-id>/<execution-id>.md`
+
+## 4. 推荐接入方式
+
+当前最稳的接入方式是：
+
+```bash
+ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-execution.json | ai-spec-auto expert-executor apply --stdin
+```
+
+如果当前环境希望把执行语义和运行态直接接通，可显式启用：
+
+```bash
+ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json --advance-runtime
+```
+
+此时工具会：
+
+- 识别 `requirement-analyst -> propose`
+- 识别 `frontend-implementer -> apply`
+- 识别 `code-guardian -> verify`
+- 优先读取 `.agents/registry/roles.json` 中的动作与交接约定，代码内置映射只作保底
+- 校验对应 OpenSpec 产物
+- 在确定的流转场景下生成并应用最小 `runtime-action（运行动作）`
+
+Phase B（第二步） 仍支持继续落盘 `runtime-action（运行动作）` 草案：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+```
+
+如需直接提交到运行态：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
+```
+
+## 5. 一句话约束
+
+> `expert-executor（专家执行器）` 不应替当前专家做技能选择、执行推理和下一步动作判断；它可以在显式授权下推进最小运行态，但仍不负责自动生成下一轮 `expert-dispatch（专家派发载荷）`。

package/.agents/orchestration/expert-runtime-action-spec.md

@@ -1,73 +1,73 @@
----
-id: expert-runtime-action-spec
-name: 单轮专家运行动作产出规范
-status: active
-owner: task-orchestrator
-description: 定义如何把 task-orchestrator（任务主代理） 产出的 task-orchestrator-runtime-action（主代理运行动作载荷）稳定落到 .ai-spec/，但不自动推进到下一轮。
----
-
-# 单轮专家运行动作产出规范
-
-## 1. 目的
-
-这份规范约束的是 Phase B（第二步）：
-
-> 当 `task-orchestrator（任务主代理）` 已经明确给出“当前专家这一轮结束后建议做什么”时，本地需要一层稳定工具把这份 `runtime-action（运行动作）` 落到 `.ai-spec/`。
-
-这一步只负责：
-
-- 校验 `task-orchestrator-runtime-action（主代理运行动作载荷）`
-- 落盘到 `.ai-spec/internal/current-runtime-action.json`
-
-这一步不负责：
-
-- 自动推理该动作
-- 默认不自动执行该动作
-- 自动递归推进下一轮
-
-## 2. 推荐落盘位置
-
-- `.ai-spec/internal/current-runtime-action.json`
-- `.ai-spec/internal/current-runtime-action.md`
-- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.json`
-- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.md`
-
-## 3. 当前最小命令
-
-```bash
-ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
-```
-
-或：
-
-```bash
-cat ./.ai-spec/internal/tmp/current-runtime-action.json | ai-spec-auto expert-executor apply-action --stdin
-```
-
-如果当前环境已经确认由 `expert-executor（专家执行器）` 负责把动作提交到运行态，可显式启用：
-
-```bash
-ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
-```
-
-补充约束：
-
-- `run_id` 缺省时允许从 `.ai-spec/current-run.json` 自动补齐
-- `complete` 会被视作 OpenSpec 的 `archive` 语义收尾，但运行态仍落为 `complete`
-
-## 4. 与 Phase C（第三步） 的边界
-
-当前这一步只做：
-
-- 记录标准 `task-orchestrator-runtime-action（主代理运行动作载荷）`
-
-当前这一步不做：
-
-- 默认不自动调用 `task-orchestrator-adapter（自动执行适配层）`
-- 不自动递归推进下一轮
-- 不自动连跑完整专家链
-- 不自动生成下一轮 `expert-dispatch（专家派发载荷）`
-
-## 5. 一句话要求
-
-> Phase B（第二步） 允许系统记录“下一步动作草案”，也允许在显式授权下把它提交到运行态；但动作本身仍必须由 `task-orchestrator（任务主代理）` 明确产出，不能由本地脚本代替 `task-orchestrator（任务主代理）` 推理。
+---
+id: expert-runtime-action-spec
+name: 单轮专家运行动作产出规范
+status: active
+owner: task-orchestrator
+description: 定义如何把 task-orchestrator（任务主代理） 产出的 task-orchestrator-runtime-action（主代理运行动作载荷）稳定落到 .ai-spec/，但不自动推进到下一轮。
+---
+
+# 单轮专家运行动作产出规范
+
+## 1. 目的
+
+这份规范约束的是 Phase B（第二步）：
+
+> 当 `task-orchestrator（任务主代理）` 已经明确给出“当前专家这一轮结束后建议做什么”时，本地需要一层稳定工具把这份 `runtime-action（运行动作）` 落到 `.ai-spec/`。
+
+这一步只负责：
+
+- 校验 `task-orchestrator-runtime-action（主代理运行动作载荷）`
+- 落盘到 `.ai-spec/internal/current-runtime-action.json`
+
+这一步不负责：
+
+- 自动推理该动作
+- 默认不自动执行该动作
+- 自动递归推进下一轮
+
+## 2. 推荐落盘位置
+
+- `.ai-spec/internal/current-runtime-action.json`
+- `.ai-spec/internal/current-runtime-action.md`
+- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.json`
+- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.md`
+
+## 3. 当前最小命令
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-runtime-action.json | ai-spec-auto expert-executor apply-action --stdin
+```
+
+如果当前环境已经确认由 `expert-executor（专家执行器）` 负责把动作提交到运行态，可显式启用：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
+```
+
+补充约束：
+
+- `run_id` 缺省时允许从 `.ai-spec/current-run.json` 自动补齐
+- `complete` 会被视作 OpenSpec 的 `archive` 语义收尾，但运行态仍落为 `complete`
+
+## 4. 与 Phase C（第三步） 的边界
+
+当前这一步只做：
+
+- 记录标准 `task-orchestrator-runtime-action（主代理运行动作载荷）`
+
+当前这一步不做：
+
+- 默认不自动调用 `task-orchestrator-adapter（自动执行适配层）`
+- 不自动递归推进下一轮
+- 不自动连跑完整专家链
+- 不自动生成下一轮 `expert-dispatch（专家派发载荷）`
+
+## 5. 一句话要求
+
+> Phase B（第二步） 允许系统记录“下一步动作草案”，也允许在显式授权下把它提交到运行态；但动作本身仍必须由 `task-orchestrator（任务主代理）` 明确产出，不能由本地脚本代替 `task-orchestrator（任务主代理）` 推理。