Light-skills架构深度解析:总控1+常驻5+主线13+工程IP4的分层设计原理
Light-skills架构深度解析:总控1+常驻5+主线13+工程IP4的分层设计原理
Light-skills 是一套面向科研、竞赛与创新项目的 AI 全流程技能包(AI skill pack),为 Claude Code、Codex、OpenCode 提供 23 个开箱即用的技能。它的架构被清晰地分成"总控 1 + 常驻 5 + 主线 13 + 工程 IP 4"四层,本文带你拆解:为什么这么分层,每一层各解决什么问题,以及它如何把"AI 的直觉"变成"可机检的闸门"。
为什么要把技能包拆成 4 层?
先想一个痛点:让 AI"从头跑到尾"做科研,最常见的翻车是——长项目丢线(不知道做到哪了)、AI 自评自夸("这步完成了")、替用户拍板(选错方向、投错期刊)。
Light-skills 的答案是把 23 个技能按"确定性工作的归属"分成四层(架构总览见 skills/README.md,设计真相源是 docs/design/orchestrator-spec.md):
| 层级 | 数量 | 技能 | 一句话职责 |
|---|---|---|---|
| 🧭 总控 | 1 | light-orchestrator |
状态检测、技能路由、闸门聚合、回炉建议 |
| 🔬 主线 | 13 | literature-search → review-rebuttal |
科研 DAG:从查文献到回复审稿 |
| 📌 常驻 | 5 | memory-pm 等 |
横切 overlay,贯穿所有阶段 |
| 🏗️ 工程 IP | 4 | frontend-design 等 |
DAG 之外,按需交接 |
核心原则只有一条:确定性的脏活交给脚本和机读门,需要判断的决策停下来问人。
总控 1:orchestrator 是"台账 + 裁判",不是"导演"
七种状态入库检测:先搞清楚"项目现在在哪"
总控接手任何项目的第一步不是干活,而是用 lifecycle.py 做 intake 分类,把项目归入 7 种状态之一(定义见 SKILL.md):
| 状态 | 含义 | 总控行为 |
|---|---|---|
new |
全新项目 | 只提议需要的阶段,战略选择问用户 |
resume |
接续旧项目 | 信 passport 台账而非聊天记忆 |
partial / dirty |
部分完成 / 有未提交改动 | 保护用户改动,不擅自变更 |
failed / stale |
门失败 / 上游文件变了 | 读阻断证据,算最小重验范围 |
delivered |
已交付 | 校验完整交付包,请用户验收 |
状态不是"我觉得",而是证据锚定的:.light/passport.yaml 是唯一 pipeline 状态(schema 为 light.passport.v3,起点模板见 passport.v3.yaml),其中 state_hash 是状态体的 SHA-256,inputs_fingerprint 哈希的是文件字节而非修改时间——上游文件一变,依赖它的下游阶段自动标记 stale,但不会误伤独立的并行分支。
ASK / ACT / NEVER:总控的三条决策纪律
这是整个架构的灵魂(完整定义见 orchestrator-spec.md 决策契约):
- ✅ ACT(自己做):读项目状态、跑机读闸门、算输入指纹、生成产物草稿、写台账(先 dry-run 预览)。
- 🧑 ASK(停下问人):研究方向、idea 定稿、方案定型、venue 选择、是否回炉——总控给"推荐 + 理由 + 备选 + 后果",然后停下。
- 🚫 NEVER(绝不自主):绝不替用户定方向/venue;绝不口头宣称"门过了"(必须机读门 exit code + 用户确认);绝不编造引用、数字、结果,查不到就写
unknown;绝不静默回炉或覆盖用户未提交改动。
这九条 NON-NEGOTIABLE 边界原文写在 SKILL.md,是总控的"宪法"。
主线 13:一条可审计的科研 DAG
13 个阶段与并行分支
主线是 13 个按依赖关系组织的阶段(完整技能一览):
1 literature-search ─┬→ 2 data-engineering ─┐
└→ 3 idea-generation ⇄ 4 idea-critique
5 research-plan → 6 experiment-coding → 7 result-analysis
7 ─┬→ 8 paper-writing ─┬→ 10 citation ─┐
└→ 9 figure ─────────┴→ 11 typesetting
11 → 12 venue-matching → 13 review-rebuttal
几个值得注意的设计点:
- 按需裁剪:不是每个项目都跑满 13 阶段,只激活需要的链路;
- 并行 fork-join:阶段 7 之后,
figure与citation并行推进、在typesetting处汇合,互不阻塞; - 阶段 12 不是门而是用户决策点:投哪个期刊/会议是战略决定,必须由人拍板。
按根因回炉:back-edge 与 2 轮配额
门失败时,总控不会"原地重试",而是用 reroute.py 把失败映射到根因阶段——比如拒稿因实验(13→5)、claim 无证据(8→7)、图把不显著结果当主图(9→7)(根因路由表见 orchestrator-spec.md)。
但注意:reroute 永远只是建议。只有用户明确授权后,才通过 passport.py 的 add-back-edge 写入回边记录(带根因、证据指针、授权 ID)。且同阶段最多 2 轮返修(revision_rounds 跨会话不重置),配额耗尽就转为"已知局限"如实记录——防止无限刷新的"回炉洗白"。
机读闸门与五种证据状态
STAGE_GATES 覆盖阶段 2–11 与 13,每个阶段对应真实的"producer/script 契约":数据泄漏、p-hacking、幻觉引用、claim 无证据、图表截轴……critical fail 直接 exit 1 阻断推进(聚合器是 run_checkpoint.py,写回台账必须带时间戳与内容哈希)。
全仓证据状态只允许五种:VERIFIED / PLANNED / UNKNOWN / UNAVAILABLE / FAILED。没有"差不多""应该可以"——文件存在≠交付,缺工具就标 UNAVAILABLE,不假装成功。
常驻 5:横切所有阶段的 overlay
这 5 个技能不是 DAG 节点,而是挂在每个确认点上的横切层:
| 技能 | 角色 | 是否产 findings |
|---|---|---|
| light-memory-pm | 项目卡、决策日志、版本史、跨对话交接 | 按需(台账自洽检查) |
| light-project-structure | 项目树搭建与治理 | 否(off-DAG) |
| light-consistency | 术语/指标/创新点跨材料一致性门 | 是,附着当前 checkpoint |
| light-research-ethics | 授权、知情同意、数据边界红线门 | 是,附着当前 checkpoint |
| light-file-reading | 论文/表格/图片/项目文件的读取理解 | 否(off-DAG) |
为什么放常驻而不是主线?因为"一致性检查""伦理红线""读文件"在任何阶段都可能需要,放进序列就会变成死板的流程。另外在 Claude Code 中,SessionStart hook 会注入常驻纪律(4200 字符)+ 续接报告(5400 字符),实现"新会话零成本续接";Codex/OpenCode 走同一套 resume 实现。
工程 IP 4:DAG 之外的按需交接
light-frontend-design、light-system-design、light-patent-disclosure、light-software-copyright 这四个技能刻意不进 STAGE_GATES/ROUTES,不产科研 findings:
- 项目需要 demo 页面或软件架构时才拉
frontend-design/system-design; - 需要专利交底或软著材料时才拉
patent-disclosure/ software-copyright,且只做材料整理,不替代法律意见。
这样做的好处是"科研主线"与"工程转化"解耦:成果可以被项目引用,但永远不会污染科研 DAG 的状态机。
_shared 契约层:把"说过的话"变成"机检的门"
四个层之下还有一块地基:_shared/ 是跨技能契约层,技能之间靠结构化产物交接,而不是聊天总结。核心契约见 契约一览表:
| 契约 | 作用 |
|---|---|
| findings_schema.py | 统一的 Finding/Gate 报告,支持 SARIF 导出 |
| gate_runner.py | 多闸门聚合,异常转 critical fail 不静默 |
| evidence_contract.py | 证据强度 → 措辞档位(中英双语,对齐 GRADE) |
| semantic_sim.py | 三档降级相似度,用于 idea 撞车检测 |
| visual_qa.py | 图表几何检测 + WCAG 对比度门 |
设计哲学很克制:裸模型本来就会说"措辞别太满、对比度够吗",Light-skills 的价值不是"知道这些",而是把它们落成可机检、可阻断、可复用的确定性门。全部纯 Python 标准库实现,三客户端共用,Round 3 发布闸门 165/165 selftest 通过(记录见 docs/e2e/round3-release-gate.md)。
四层如何协作:一次"拒稿回炉"的完整链路
把四层串起来看一个真实场景:
- 主线:阶段 13
review-rebuttal发现审稿人以"实验不足"拒稿,checkpoint 判定 fail; - 总控:
reroute.py输出建议回边13→5(根因是研究计划),呈现证据定位、推荐理由、下游 stale 影响,停下等用户; - 用户授权后
add-back-edge写入回边,revision_rounds+1; - 常驻:
consistency回扫确认回边后术语/指标一致,memory-pm把决策与轮次记入台账; - 再跑门:阶段 5 重新过 checkpoint,stale 传播标记需重验的下游,直到用户
authorize-delivery验收交付。
全程总控不替人做任何一个判断,但确定性的部分(读状态、跑门、算哈希、记台账)全部自己干净利落做完。
快速上手:3 条命令开始用 Light-skills
环境要求:Python 3.10+(Windows 建议设置 PYTHONUTF8=1),LaTeX/R 为可选增强。
# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/li/Light-skills
cd Light-skills
# 2. 一键生成三客户端技能发现入口(.agents/.claude/.opencode)
python scripts/bootstrap_agent_skills.py --mode auto --force
# 3. 检查安装是否合规(不写入)
python scripts/bootstrap_agent_skills.py --check-only
安装脚本会做兼容性硬门校验(SKILL.md 存在、frontmatter 合法、name 与目录一致等),说明见 docs/compatibility/agent-client-compatibility.md。装好后,一个常见入口 prompt 是:
/light-orchestrator 我想把这个方向做成可投稿英文论文。请先问必要问题,再拆阶段、产物、风险和用户确认点。
更多完整示例可参考端到端演示 examples/e2e-research-demo/ 与 LaTeX 论文 Demo projects/photocatalytic-dye-kinetics-study/。
总结:四条分层设计原则
- 🧭 确定性交给脚本,判断交给人——ASK / ACT / NEVER 是总控的脊柱;
- 🔒 状态必须证据锚定——passport + SHA-256 + 文件字节指纹,不靠记忆;
- 🔁 按根因回炉,且有配额——back-edge 定向到根因阶段,最多 2 轮,耗尽转已知局限;
- 🤝 诚实降级——五种证据状态,
UNAVAILABLE不伪装成"没发现"。
想深入细节,可以从 总控 SKILL.md、orchestrator 设计 spec 和 v1.0.0 发布说明 三个文件开始读起。



