Light-skills 总控 light-orchestrator 实战指南:13 阶段 DAG 如何拆解研究流程并锁定用户确认点
Light-skills 总控 light-orchestrator 实战指南:13 阶段 DAG 如何拆解研究流程并锁定用户确认点
Light-skills 是一个面向科研、竞赛与创新项目的 AI 全流程技能包,其中的总控技能 light-orchestrator 把整条研究流程拆解为 13 阶段 DAG(有向无环图):从文献检索一路到审稿回复,每个阶段都设有可机读的质量门,在方向选择、idea 定稿、投稿与交付等关键节点停下,锁定用户确认点后再推进。本文带你完整看懂这套"总控大脑"如何运转。
一、light-orchestrator 是什么:科研全流程的"总控大脑"
Light-skills 共含 23 个技能,架构为 1 个总控 + 5 个常驻技能 + 13 个主线技能 + 4 个工程/IP 技能(见 skills/README.md)。总控 light-orchestrator 自己不做具体研究,而是负责三件事:
- 统筹路由:按依赖关系把任务派给 13 个主线技能,不越俎代庖;
- 状态记账:用唯一台账
.light/passport.yaml记录"现在到底走到哪一步、哪步验过、哪步陈旧"; - 守住红线:把"AI 不擅长拍板的决策"降级为"机读质量门 + 问你",绝不替用户决定方向、idea、投稿目标和交付。
它的完整行为契约写在 skills/light-orchestrator/SKILL.md,设计原理可深入阅读 docs/design/orchestrator-spec.md。
13 阶段 DAG 全景
研究主线是一条带编号的 DAG,可按项目需求裁剪,不必每次全跑:
| 阶段 | 技能 | 干什么 |
|---|---|---|
| 1 | literature-search | 文献检索策略、证据地图 |
| 2 | data-engineering | 数据质量、泄漏与可行性检查 |
| 3 | idea-generation | 生成候选研究 idea |
| 4 | idea-critique | 批判创新性、可证伪性与致命缺陷 |
| 5 | research-plan | 实验矩阵、对照与失败树 |
| 6 | experiment-coding | 可复现实验代码与配置 |
| 7 | result-analysis | 统计分析、证据强度评估 |
| 8 | paper-writing | 基于证据组织论文结构 |
| 9 | figure | 程序化生成论文图表 |
| 10 | citation | 引用真实性与 DOI 核查 |
| 11 | typesetting | LaTeX 编译与投稿前格式检查 |
| 12 | venue-matching | 期刊/会议匹配与风险排名 |
| 13 | review-rebuttal | 审稿意见分解与回复规划 |
其中阶段 7 之后 DAG 分叉:7 同时喂给 8(写作)和 9(图表),8 又喂给 9 和 10(引用),9 与 10 两条并行分支在 11(排版)汇合——这正是 DAG 中典型的 fork/join 结构,依赖关系由 integration-contract.json 机读定义。下图是示例项目沿这条链路产出的科研图表画廊(examples/e2e-research-demo/):
注意:5 个常驻技能(memory-pm、project-structure、consistency、research-ethics、file-reading)和 4 个工程/IP 技能(frontend-design、system-design、patent-disclosure、software-copyright)不占阶段编号,它们以横切 overlay 或 off-DAG 方式挂载,不会被塞进科学 DAG。
二、质量门 checkpoint:每个阶段都有机读"验收"
总控不靠"我觉得这步完成了"推进流程。每个阶段跑完后,用检查点脚本聚合该阶段的机读结果(light.findings.v1):
python skills/light-orchestrator/scripts/run_checkpoint.py \
--file .light/passport.yaml --stage 8 \
--findings findings.json --ts 2026-07-04T10:00:00+08:00
关键规则(见 SKILL.md):
- 出现 critical 问题时退出码为 1,确定性阻断推进;
- 写回台账必须带新鲜时间戳和内容哈希,禁止无时间戳的
--write; - 证据状态只允许五种:
VERIFIED、PLANNED、UNKNOWN、UNAVAILABLE、FAILED,不许混淆; - 阶段 1 只产下游信号,阶段 12 是"用户决策包"而非确认门——投稿目标永远由你选。
各阶段挂的门举例:数据工程查 split_leakage(数据泄漏)与 data_feasibility(可行性),结果分析查 stat_validity(统计有效性),论文写作查 claim_evidence(claim 必须有证据)与 overclaim(禁止过度宣称),排版查 compile 与 desk_reject。完整门表见 orchestrator-resource-map.md。
三、用户确认点:哪些事总控必须停下来问你
这是 light-orchestrator 最有"人味"的设计。它把动作分为三类:
决策点(ASK,停下问你) 🧭 ——呈现"推荐 + 理由 + 备选 + 每项后果",然后等你拍板:
| 确认点 | 为什么必须你定 |
|---|---|
| 研究方向选择 | 押上数月时间,AI 不能替你选 |
| idea 定稿 / 回炉重提 | 创新性判断易错,需人确认 |
| 研究方案授权 | 对照是否公平、假设是否可证伪 |
| 回炉路由决策 | 回哪个根因阶段,或带病推进 |
| venue 选择 + 是否投稿 | 不可逆的战略性动作 |
| 最终交付验收 | 文件齐全 ≠ 已交付 |
执行项(ACT,自己默默做):读状态、跑门、算指纹、stale-check、生成报告草稿——这些确定性脏活不打扰你。
NEVER 红线(绝不自主):绝不自称"门过了"、绝不编造引用或数据、绝不静默回炉或静默带病推进、绝不覆盖你未提交的改动。
还有一道"高风险动作闸":远程执行、付费、发布/投稿、删除、不可逆操作,必须先过 decision_checkpoint.py 生成决策检查点,拿到你的授权 ID 才允许执行——user_decision_needed=false 也不能绕过这道门。
四、失败了怎么办:按根因"回炉",且最多两轮
检查点失败时,总控用 reroute.py 做根因路由:它只产建议,绝不自动执行。规范回边表如下:
| 触发 | 根因阶段 | 回边 |
|---|---|---|
| idea 撞车/无创新 | idea-generation | 4→3 |
| 结果不可复现/bug | experiment-coding | 7→6 |
| 结果不支撑假设 | research-plan | 7→5 |
| claim 无证据 | result-analysis | 8→7 |
| 图把不显著当主图 | result-analysis | 9→7 |
| 拒稿(创新性/实验/写作) | 3 / 5 / 8 | 13→3 / 13→5 / 13→8 |
两道防线锁住"返工通胀":
- 授权门槛:只有你明确授权后,才执行
passport.py add-back-edge --authorization-id ...把回边写入台账; - 返修配额:同一根因阶段最多 2 轮返修,跨会话从台账读取已用轮次、不能刷新;用满后改为"转已知局限如实记录",不假装修好。
一次真实的完整生命周期(E2E 记录见 docs/e2e/orchestrator-round2.md)长这样:
阶段 8 论文写作用了 "significantly outperforms" 但没有逐 claim 证据绑定 →
claim_evidence门 critical → checkpoint 退出码 1,阶段 8 记为gate_failed→ reroute 建议 8→7(配额 0/2)→ 停下问用户 → 用户回复"授权",带回边落账,阶段 7 置needs_rework(1/2)→ 重做分析、措辞降级为 "may suggest" → checkpoint 全过 → 上游数据变化让阶段 8 被判stale,重验后转fresh→ 再次停下,用户授权后执行authorize-delivery→DELIVERED✅
五、passport 台账:跨会话断点恢复,交接零成本
.light/passport.yaml 是唯一的流水线状态权威(schema:light.passport.v3,模板见 passport.v3.yaml)。它用 state_hash(SHA-256)和 inputs_fingerprint(按文件字节而非 mtime)保证状态可验证。
每次接手项目,先跑 intake 分类,把项目归入 7 种主状态之一:
python skills/light-orchestrator/scripts/lifecycle.py intake --root <project-root>
| 状态 | 含义 | 总控行为 |
|---|---|---|
new / resume |
新项目 / 恢复中 | 裁剪流水线提议 / 按 next_action 继续 |
partial / dirty |
部分交付 / 有未提交改动 | 找下一依赖就绪节点 / 保护你的改动不动 |
failed / stale |
门失败 / 上游内容变化 | 读阻断证据再建议回炉 / 只重验受影响的下游闭包 |
delivered |
已交付 | 核验交付包后请你验收 |
上游文件一变,依赖它的下游阶段自动变 stale,但不会连坐无关的并行分支;交接卡(handoff)与 passport 哈希绑定,哈希变了旧交接立即失效——所以"换个会话、换台机器、甚至换人"接手都能从证据锚定的位置无缝续跑。
六、快速上手 light-orchestrator
git clone https://gitcode.com/gh_mirrors/li/Light-skills
cd Light-skills
# 生成技能发现入口(以 Claude Code 为例)
python scripts/bootstrap_agent_skills.py --targets claude --mode auto --force
# 对任意科研项目做状态分类
python skills/light-orchestrator/scripts/lifecycle.py intake --root <project-root>
之后在项目对话中直接说"继续 / 恢复 / 交付",总控就会按 intake 状态走恢复流程。常驻注入配置(SessionStart hook 等)见 skills/light-orchestrator/resident/INSTALL.md。
七、延伸阅读与文件导航
- 总控行为契约:skills/light-orchestrator/SKILL.md
- 设计真相源(含院士视角的需求深挖与 ASK/ACT/NEVER 契约):docs/design/orchestrator-spec.md
- 23 技能角色/gate/route 机读契约:skills/light-orchestrator/references/integration-contract.json
- Round 2 集成验收与 E2E 证据:docs/e2e/orchestrator-round2.md
- 核心脚本:lifecycle.py · passport.py · run_checkpoint.py · reroute.py · workflow_ledger.py · execution_mode.py
一句话总结:light-orchestrator 不是"更快的全自动总指挥",而是一位在对的地方停下来和你一起想、把不可逆决定权留给你的总控——确定性的脏活它自己干净利落地做掉,AI 结构性不擅长的判断则一律降级为"机读门 + 问你"。

