light-orchestrator

# 编排器（Orchestrator）

把"组合调用链路"从声明式描述变成可执行流程：规划阶段、调用技能、卡住检查点、记台账、断点续跑。它不亲自干活（写作、画图、分析都交给对应技能），只负责**调度、把关、恢复上下文与阶段交接**。

## 何时启动

**启动 pipeline**（任务跨 ≥3 个阶段、或用户明确要"全流程/从X做到Y"）：
- "从这个数据集做到一篇论文" / "把这个想法做成投稿" / "帮我把项目从头跑到投稿"。
- 用户给了原始材料（数据/想法）并要一个跨阶段的终产物（论文/申报书/答辩）。

**启动断点恢复**（即使当前只剩单一动作，也先恢复状态）：
- "继续" / "刚断了" / "接着来" / "接手 Claude/Codex/Hermes" / "恢复上下文" / "上次做到哪"。
- 用户说上一个 agent 一直断、让你找对话记录、继续某个长期项目。

**不启动**（直接路由到单技能，别用重流程拖累轻任务）：
- "改一下这段摘要" → m07 section/abstract 模式。
- "画张柱状图" → m11。
- "查这几条引用" → m10。
- 任何单一阶段、能一个技能闭环的任务。

判据：**这个任务需要跨技能交接产物或恢复旧状态吗？** 需要→orchestrator；不需要→单技能。

## 0. 断点恢复协议（用户说“继续/刚断了”时先做）

不要凭印象继续。先做最小恢复探针拼出"当前事实状态"再行动（六探针全文见 `references/checkpoints.md`「断点恢复探针」节）：

1. **工作区与版本**：`git status --short`、`git log --oneline -5`、当前分支/remote；有 GitHub remote 再读最近 CI（`gh run list`）。
2. **当前任务单**：读 Todo 工具状态；没有则从 passport/db09/最近提交重建。
3. **项目台账**：优先读 `.light/passport.yaml`；没有则读 db09 项目卡/decision_log/version_history。
4. **对话/外部交接**：仅当①用户给出对话记录路径②缓存路径/会话标题/项目 slug 与当前仓库或 db09 项目名明确匹配时才检索 transcript，限定当前项目关键词；无法证明相关标 `transcript: unavailable`，不猜不存在的记录、不读无关项目会话。
5. **产物与脏文件**：读 manifest/plan/diff/未提交文件，判断"已完成未提交/已提交未推送/已推送等 CI/CI 失败待修"。
6. **恢复摘要**：继续前内部形成五项事实——`当前阶段/已完成/未完成/阻塞风险/下一步最小动作`；下一步有副作用（提交/推送/重写历史/删除）按范围纪律确认。

某探针（gh/CI/todo/transcript）不可用就标 `unavailable`，用其余可用证据继续，不当硬阻断。**恢复时严禁**：只凭聊天记忆说"应该到 X 了"（必须有 git/passport/db09/todo/CI 证据）；重跑已完成阶段（除非用户要求或产物失效）；看到未提交改动直接覆盖（先读 diff 辨本轮遗留还是用户新改）。

## 1. 规划 pipeline

按任务目标，从 CONVENTIONS 第 6 节的阶段主线裁出一条链（不是每次都全跑）。常见链见 `references/pipelines.md`。规划产出一张**阶段计划表**，每阶段都必须写清：调用哪个技能、输入、预期产出、落盘位置、检查点类型。

计划表模板：

| 阶段 | 技能 | 输入 | 产出/落盘 | 检查点 |
|---|---|---|---|---|
| 调研 | m01 literature-search | 用户问题 + db01/db03 背景 | `docs/literature_review.md` / 文献表 | ✓ 来源可核 |
| 方案 | m05 research-plan | 通过审查的 idea | `PROJECT_PLAN.md` / `experiments/experiment_matrix.md` | ✓ 可执行 |

原则：先把计划表给用户确认再开跑；如果用户说“继续刚才的任务”，只需恢复并继续当前阶段，不要重新规划整条链。

## 2. 阶段输入输出契约

跨技能交接必须有可落盘工件，不能只靠一句聊天总结。**工件命名的单一真相源是 CONVENTIONS §6.1 阶段工件契约表**，逐阶段"上游输入→标准产物/handoff artifact→下游"的执行视角镜像表见 `references/pipelines.md`「阶段工件契约」节（与 CONVENTIONS §6.1 不一致以后者为准）。项目已有约定时以项目约定为准，但必须在 passport 里记录路径。

每个阶段结束时，把"产物路径 + 验证输出摘要 + 下一阶段输入"写入 `.light/passport.yaml`；缺工件就不能声称该阶段完成。

## 3. 逐阶段执行 + 检查点

每个阶段：调用对应技能 → 产出落台账 → 过该阶段检查点 → 才进下一阶段。两类检查点（详见 `references/checkpoints.md`）：

- **决策点 🧑**：需要用户选分支才能继续。如 m04 idea 不过关（打回 m03 还是放行？）、投哪个 venue、用哪种输出格式。**不替用户决定。**
- **确认点 ✓**：机器先验证（跑 a08 self-review / a07 consistency / a10 research-ethics 闸门），出报告 → 用户确认 → 推进。**诚信门不达标默认阻断**，不静默跳过；同一阶段最多 2 轮整体返修（细则见 `references/checkpoints.md`），仍不达标的转为“已知局限”如实记录，而非假装修好。

确认点的证据必须是新鲜的：当前轮命令输出、文件 diff、CI run、脚本 selftest、人工确认记录之一；不能只写“已检查”。**m13 投稿决策点**:venue 计量(IF/分区/h_index/被引)须为当轮新鲜证据(venue_signal.py 实时输出),**db09 decision_log/project_card 内的 venue 快照不算新鲜证据**,投稿决策前必须重核、冲突信在线。

**阶段切换默认触发会话衔接（T3）**：每过一个检查点、进入新阶段前，按 §5 主动留衔接卡 + 打印启动提示词，不等上下文耗尽。

## 4. 维护产物台账

全程维护一份**产物台账**（passport），记录每阶段：产出了什么、过了哪些闸门、哪些标了 GAP、用户在决策点选了什么。格式与存储位置见 `references/passport.md`（固定存项目根目录 `.light/passport.yaml`）。启动时先查该文件是否存在——存在即续跑、不存在即新建。台账纳入 a02 memory-pm 的项目记忆，**任务中断后可据此续跑**。

台账最小更新规则：
- 每完成一个阶段，当场追加，不攒到最后补。
- 每个 artifact 写相对项目根目录的路径。
- gate 写 PASS/FAIL/WARN 和证据来源。
- 用户决策写 `choice` 与 `by: user`。
- GAP / known_limitations 如实记录。

> **下游消费**：各阶段 `artifacts:` 路径并集是 a07 consistency「变更广播」回扫的**权威"已产出材料"清单**（定义/术语一改，a07 对这份清单逐项回扫防过期）。故 artifact 路径必须及时、准确——漏登记的产物 a07 扫不到。无 passport 的轻项目，a07 退回读 db09 `version_history.md`。

## 5. 阶段交接输出（handoff → 会话衔接协议两件套）

长任务每次暂停、提交、等待用户/CI/实验、或上下文可能压缩前，必须主动交接（CONVENTIONS §9 的 T1/T2/T3 触发）。**交接格式收编为 a02 会话衔接协议的两件套，本技能不再自带摘要格式**（避免口径分裂）：

1. **衔接卡落盘**：按 a02 `light-memory-pm/templates/handoff_card.md` 填好，存项目根 `.light/handoff/S<NN>-<slug>.md`（与 `.light/passport.yaml` 同级，`<NN>` 两位递增，`parent_session` 接上一张卡）。卡里"当前阶段/已完成/工作区状态/下一步/阻塞/必读文件/禁止"即原 handoff 摘要的全部字段。
2. **打印启动提示词**：按 a02 `light-memory-pm/templates/handoff_prompt.md` 填值后打印在聊天里，用户复制→新开对话→粘贴即续。

落盘细节、四类触发判据、自包含/自传播原则见 a02 `light-memory-pm/references/session_handoff.md` 与 CONVENTIONS §9。无项目目录的轻对话只打印提示词、不落卡。

用户后续说"继续"时，先读最新衔接卡作为入口，但**不能把衔接卡当作当前事实**；仍要刷新 `git status`、todo、passport/db09、CI/远端等当前证据。没有衔接卡才退回 §0「断点恢复协议」。

## 边界（重要）

- 编排器**不绕过任何常驻闸门**。self-review / consistency / research-ethics / tool-selection 在每个阶段照常后台生效。
- 编排器**不替用户做研究决策**。idea 选哪个、结论怎么定、投哪里——都是决策点，交用户拍板。这条边界（"可借鉴 ARS 的调度形态，但不接管研究判断"）的设计决策记录见仓库 `docs/design/2026-06-08-ars-borrow-boundary.md`（仅在仓库内，未随安装分发）。
- 分级原则：大任务上完整 pipeline，小任务直接单技能。宁可少编排，不可为编排而编排。
- 断点恢复不是“重新做一遍”。已验证、已提交、已入 passport 的阶段默认不重做；若当前 diff、依赖、远端状态或 CI 显示证据已失效，只重验受影响的最小范围；只在证据失效、用户要求或下游发现矛盾时回滚。

## 自检清单

- [ ] 是否先判断该任务该 pipeline、单技能，还是断点恢复？
- [ ] 若是“继续/刚断了”，是否读了 git/todo/passport/db09/CI 等证据？
- [ ] 是否明确当前阶段、已完成、未完成、下一步最小动作？
- [ ] 是否为每个跨技能交接产物写了落盘路径？
- [ ] 是否在决策点停下让用户选，而不是替用户决定？
- [ ] 是否在确认点给出真实验证证据，而不是口头说通过？
- [ ] 是否更新 `.light/passport.yaml`，并在暂停/阶段切换/上下文将尽时按 §5 留下衔接卡 + 启动提示词，保证下次能续接？