把系统的骨架显式化

系统真正的行为——队列消费、定时器、重试链、状态机,以及 CLI / 管线跑一趟就结束的那些执行路径——散落在代码各处,没有任何地方端到端地说清它应该做什么、也没有任何地方证明它现在还做得到。loopgraph 把这个形状写成一个显式、权威的模型:系统应有的骨架。代码于是成为骨架的投影——这翻转了三件事:

• 看得懂。 骨架是一张可读的地图,而一堆代码不是——人和 agent 读地图,而不是每次都从头逆向。
• 放心重构。 因为代码只是骨架的投影,你可以随便重写、甚至整段重新生成;conformance 会证明重写后依然合骨架。骨架稳定,代码流动——甚至可丢弃。
• 不漂移。 每次 PR 拿投影(代码)对着骨架校验;每个 gap 都是代码欠模型的一笔账。

防漂移只是地板,不是天花板:真正的目标是一个你能看懂、能重塑的系统,站在一副始终为真的骨架上。

怎么运作

模型是结构化的——Loop、Flow、Junction、Scenario——用 YAML 表达,并钉在真实代码符号上(path#symbol)。每次 PR 跑一遍确定性门禁拿代码对着它校验,loopgraph conformance 给每个建模行为打 met / partial / gap,并点名缺的到底是什么——一个测试、一个场景、一个锚点:

和描述性 code-graph 的区别

描述性 code-graph 是从代码里算出来的,所以它永远说不出"代码错了"——它只能告诉你代码是什么。loopgraph 持有一个独立的事实源,三个方向去校验,而且方向永不反转:

• reconcile — 代码 → 模型:代码里有、模型漏登记的信号(队列、定时器、轮询器)。
• coverage — 模型自检:模型有多少真被绑到了代码上。
• conformance — 模型 → 代码:履约成绩单,给每个节点打分并点名缺口。

因为模型是权威,每个 gap 都是实现欠模型的一笔账——这正是"从代码算出来"的图结构上抓不到的漂移。

什么情况不适合

建模是有成本的,不是哪里都划算。loopgraph 的价值在看不清、且出错代价高的地方——后台机制、跨组件交接、多步旅程。以下场景是亏本买卖:

• 纯函数库(日期工具、校验器)——代码本身已经把行为说清楚了,测试也已经钉住了。建模只是把一眼可读的东西重述一遍。
• 没有跨组件交接、也没有多步状态推进的薄 CRUD / 胶水层——一次读写要么成功要么失败,压根没有"形状"需要守。
• 马上要删掉或整体重写的代码——模型还没开始产生价值就先过期了。

一句话判据:新人光读代码会不会理解错? 不会,就别建模。

快速开始

npx loopgraph init          # model 骨架 + agent 指令套件 + /loopgraph skill 前门
npx loopgraph check . --repo-root . --strict-anchors   # 确定性门禁(亚秒级、零 LLM)
npx loopgraph conformance . --repo-root .              # met / partial / gap 履约成绩单
npx loopgraph graph . --repo-root .                    # 自包含、按履约状态上色的 HTML

init 写出 .loopgraph/ 骨架和一套 agent 指令套件:你仓库里的 coding agent 照它发现行为、起草模型。草案由你审核,未核实不落库。

命令

| 命令 | 做什么 | 会挂 PR 吗 | | --- | --- | --- | | check | 确定性门禁:schema、引用完整性、图无环、锚点存在性、canonical-writer 不变量(纯 AST)。--diff 增量。 | 会——唯一的 gate | | conformance | 模型 → 代码成绩单:每节点 met / partial / gap + 缺口 | advisory | | reconcile | 代码 → 模型:代码里模型漏登记的信号 | advisory | | coverage | 模型自检:多少节点真被锚定 | advisory | | backtest | 提交侧回测:最近 N 个改了 .ts/.tsx 的提交里,多少命中了模型锚定的文件 | advisory | | graph | 整张模型的自包含、按履约状态上色的 HTML | — | | overview | 交互式系统地图——点任意 loop 看它在做什么、代码在哪、履约状态 | — | | snapshot | nightly 全量快照 + 漂移报告 | 永不进门禁 | | impact <id> | 改这里会牵动什么 | — | | mcp | stdio MCP server,让 agent 查模型切片,替代全量读 spec | — |

模型长什么样

# .loopgraph/model/loops/*.yaml — 一个后台控制循环(示例为虚构系统)
- id: L1
  kind: loop
  title: Order 状态机
  boundary: "pending → processing → shipped/cancelled;cancelled 为终态"
  owner: packages/orders
  anchors: ["packages/orders/src/order-service.ts#OrderService"]  # 钉在真实代码符号上
  consumes_queues: ["order:process"]                              # 按名对账生产/消费分离
  scenarios: [GWT-A1-001]                                         # GWT 场景,verified_by 指向真实测试

一个完全没有后台 loop 的仓库——CLI、构建工具、一次性管线——直接给旅程本身建模:

# .loopgraph/model/flows/*.yaml — 自己带代码绑定的旅程
- id: C1
  kind: flow
  shape: anchored                            # 直接钉到代码(对应 composed:由其他节点组成)
  title: 安装一个 skill
  anchors: ["src/install.ts#install"]        # 与 loop 同样的钉法
  scenarios: [GWT-C1-001]

Loop、Flow(端到端链路)、Junction(跨循环风险点)、Scenario(GWT)、debt 基线(只减不增)——全部 YAML、file-per-node,由 loopgraph check 机器校验。

发现靠 LLM,防腐靠引擎

找出值得建模的行为是 LLM 的活;让模型保持诚实是引擎的活。agent 套件随附四遍扫描方法论(召回两类候选——自主推进的 loop 与一次性执行路径 → 三判据证伪 → 组合 → trace 升维),由 coding agent 离线执行。引擎只负责核实锚点、拦截漂移——门禁本身永不调 LLM、不碰网络、不执行你的代码。

设计红线

• 门禁零 LLM、零网络、零代码执行——快、便宜、可复现、可解释。
• 缓存零正确性依赖(cold == warm 逐字节一致)。
• 快照 / 漂移报告(T2)永不进 PR 门禁。
• 模型新增须过锚点核实;发现层(LLM)只产草案,落库须经维护者核实。

适配器——开放基础设施

包里不含任何适配器。你的仓库拥有一个小的、同步的抽取器,放在 .loopgraph/adapter/,读你这套技术栈的实现信号(队列名、定时器、轮询器)。加 --strict-adapter 让缺适配器直接挂 CI,而不是静默跳过;让 init 生成的 CI 锁定 loopgraph 版本而非浮动 @latest——这样某个新版本就没法在绿灯下悄悄改变门禁语义。

参与贡献

见 CONTRIBUTING.md —— 按 CI 顺序跑的本地门禁、stacked PR 的坑 (squash 合并 base 会把子 PR 送到不是 main 的地方,且哪里都不报错)、以及新增锚点字段时的 扇出契约。

License

见 package.json。