Light-skills架构深度解析:总控1+常驻5+主线13+工程IP4的分层设计原理

原创2026-10-28 12:58:301,979 阅读

Light-skills架构深度解析:总控1+常驻5+主线13+工程IP4的分层设计原理

Light-skills 是一套面向科研、竞赛与创新项目的 AI 全流程技能包(AI skill pack),为 Claude Code、Codex、OpenCode 提供 23 个开箱即用的技能。它的架构被清晰地分成"总控 1 + 常驻 5 + 主线 13 + 工程 IP 4"四层,本文带你拆解:为什么这么分层,每一层各解决什么问题,以及它如何把"AI 的直觉"变成"可机检的闸门"。

Light-skills 科研全流程 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 不是门而是用户决策点:投哪个期刊/会议是战略决定,必须由人拍板。

Light-skills 图表技能程序化生成的科研图九宫格展示

按根因回炉: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 的状态机。

Light-skills 排版技能输出的 LaTeX 论文预览

_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)。

四层如何协作:一次"拒稿回炉"的完整链路

把四层串起来看一个真实场景:

  1. 主线:阶段 13 review-rebuttal 发现审稿人以"实验不足"拒稿,checkpoint 判定 fail;
  2. 总控:reroute.py 输出建议回边 13→5(根因是研究计划),呈现证据定位、推荐理由、下游 stale 影响,停下等用户;
  3. 用户授权后 add-back-edge 写入回边,revision_rounds +1;
  4. 常驻:consistency 回扫确认回边后术语/指标一致,memory-pm 把决策与轮次记入台账;
  5. 再跑门:阶段 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 我想把这个方向做成可投稿英文论文。请先问必要问题,再拆阶段、产物、风险和用户确认点。

Light-skills 实验编码与结果分析技能输出的动力学拟合图示例

更多完整示例可参考端到端演示 examples/e2e-research-demo/ 与 LaTeX 论文 Demo projects/photocatalytic-dye-kinetics-study/。

总结:四条分层设计原则

  1. 🧭 确定性交给脚本,判断交给人——ASK / ACT / NEVER 是总控的脊柱;
  2. 🔒 状态必须证据锚定——passport + SHA-256 + 文件字节指纹,不靠记忆;
  3. 🔁 按根因回炉,且有配额——back-edge 定向到根因阶段,最多 2 轮,耗尽转已知局限;
  4. 🤝 诚实降级——五种证据状态,UNAVAILABLE 不伪装成"没发现"。

想深入细节,可以从 总控 SKILL.md、orchestrator 设计 spec 和 v1.0.0 发布说明 三个文件开始读起。

登录后查看全文
Light-Science