推理图谱协议 alxshelepenok/grove

Code grows. Context windows don't. Plant a Grove 🌳

Graph-driven Reasoning Over Verified Evidence. A formal workflow protocol designed to keep deep, long-running projects coherent across sessions, agents, and months.

长时间运行的智能体工作，失败方式是可以预料的：会话越滚越大，决策和假设慢慢滑出视野；智能体报告说活干完了，其实没干完；几个月后，代码库和任何人以为的样子都对不上，于是没人说得清某一行代码为什么存在。

Grove 适合推理密集、活不过一个会话的工作：长期重构、跨多个会话的功能、安全与合规任务——这类工作里每个结论都得留下审计痕迹。协议会挑出下一步做什么，你不用再对着每个新会话重新讲一遍项目。

它能给你什么：
- 原子级进展： 每个任务都经过机械验证，不是嘴上说说。
- 层级优先于压缩： 上下文严格结构化，绝不做有损摘要。
- 绝对可复现： 每个动作都有记录，任何步骤、决策、假设都能回放和追溯。
- 跨智能体接续： 智能体在目标中途停下，另一个客户端、另一个模型上的智能体可以从已验证状态接着干。
- 完全归属你： 每个目标、决策、任务、问题、假设都存在一张持久的历史图里，这张图完全属于你。
Grove 把规则作为确定性不变量，存进单个带校验和的 lockfile：智能体不能在没有可证伪证据的情况下宣称工作完成，不能启动未就绪的任务，也不能虚构进度。项目状态不靠有损的提示词压缩或摘要，而是放在带机器可校验边的类型化推理图里，每一步只拿到它需要的执行包，不多给一点。

支持 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline、GitHub Copilot，以及任何其他智能体。Grove 自带命令行、内置 MCP 服务器，还有可直接放入的智能体技能包，你可以立刻把它接进自己的工作区。

[!IMPORTANT]
关于下面展示的桌面应用，有几点说明。它的作用是让你一眼看清推理图、证据和项目健康状况，但目前仍是实验性的，还没在 macOS 上测试过。命令行和 MCP 服务器才是稳定、经过测试的接口。界面没有用任何 JavaScript 框架，主要是纯 HTML、CSS 和 Tauri，所以速度很快，推理图用 WebGL 渲染。

推理图，实时探索。

同一视图，143 个节点，含历史记录。

智能体处理一个工作项所需的全部内容，不多不少。

工作项从提案一路跟踪到完成。

每个领域的目标、工作与内容健康度。

按主题分组的工作，附带关键路径。

项目变大，智能体就丢上下文

长时间运行的智能体会患上上下文失忆。会话越拉越长，决策、假设和依赖关系就悄悄滑出视野。与之相关的另一种失败是自我汇报不可靠：智能体拿不出足够证据，却宣称工作已完成。这不是它在骗人，而是环境里没有任何东西拦得住它。

标准的任务跟踪工具天生信任执行者。人在 Jira 里勾上一个复选框，工作就算做完了。对人来说，这个默认值很合理。对自主智能体来说，这是一条静默的失败路径。过早宣布「完成」会在长会话里层层累积，最终变成结构性错误，直到代码库和任何人以为的样子都对不上，也没人说得清某一行代码为什么存在。

这不是纸上谈兵。Grove 从一个粗糙的 Markdown 假设起步，演化成一套协议，如今管理着 Merlin Guild——一个闭源生产项目，20 万行以上的 Rust 和 TypeScript，重度使用区块链与密码学。它能撑住规模，是因为这套协议不依赖智能体记住或正确遵守工作流。

用结构，而不是压缩

面对上下文失忆，最直觉的反应是加工具：摘要、压缩、检索。这些做法都在压缩上下文，而压缩会丢信息，同时指望丢掉的恰好不重要。

Grove 不压缩上下文，它给上下文搭结构。

项目演进过程中，工作被持续组织成领域、目标、问题、假设、决策和可执行的工作项。有了这层层级，智能体就能定位与当前步骤相关的上下文，不必反复把整个项目历史塞进上下文窗口。

结果不只是连续性更好，token 用量也降下来了。智能体不再为了弄清自己身在何处、当前任务为何存在，就加载一堆无关的项目上下文。

一条提示词，摸清整个代码库

把前沿模型指向一个原始代码库，再挂上 Grove，会发生什么？

没有协议时，智能体会草草扫一遍文件，编出一份快速摘要，走几步就迷失方向。有了 Grove，它会把整片地形测绘出来。在一次针对复杂代码库的真实测试中，一条提示词启动了一场长达 5 小时的自主 Discovery 会话。
智能体耗尽了上下文窗口上限，但换来一张完整填充的推理图：44 个 Area、47 个 Goal、89 个 Work item，瞄准测试覆盖缺口和逻辑缺陷。它没有丢出一份扁平的任务清单，而是把未解疑问正式声明为 Question，并把相关工作归入 Theme。

下面是启动这个项目所用的原始提示词：

加载 Grove 技能并连接 MCP 服务器。完整研读技能，理解协议约束。

你的目标是在整个代码库上跑完一轮完整的 Discovery 阶段。先不要写实现代码，你的任务是项目分析和图构建。

1. 把项目拆解为 Area。注意，单个 package 可能包含多个逻辑 Area。
2. 遍历每个 Area，创建 Goal，处理缺失的测试覆盖和明确的逻辑缺陷。
3. 为每个 Goal 创建 Work item，严格按 Grove 协议格式化。
4. 把相关工作归入 Theme。
5. 把未解疑问声明为 Question，必要时把架构选择正式化为 Decision。

因为 Grove 强制要求 Definition of Ready（DoR），智能体没法假装有进展。接下来一天里，智能体系统性地执行交付阶段，把 75 个任务推进到 Done。剩下的任务正确地卡在 proposed 或 ready 状态，等待人类回答智能体提出的阻塞性 Question。

一份项目状态，多个界面

记忆的单位不是对话，而是项目。
进展的单位不是智能体的声明，而是经过验证的证据。

Grove 用一套严格、机器强制的协议，取代客气的提示词指令。智能体通过命令行、MCP 和桌面界面与项目状态交互。协议本身强制规则：

- Work item 没有证据记录，就不能标记为 done。
- 每个前置条件未经机器验证，工作就不能开始。
- Goal 进度不能手动更新；fitness 增量在关闭时原子应用，要么全部生效，要么完全不生效。

状态要么满足协议，要么 Grove 拒绝推进。智能体不能只靠声称工作完成，就推进协议状态。

只给智能体需要的上下文

Grove 强制智能体把产品拆解为严格的类型化层级。规划上下文不再是一份原始任务清单，而是全部显式落在节点分类体系里。没有任何东西藏在旁路文档或智能体的内部状态中：

| 节点 | ID | 承载内容 |
| Area | A-NN | Goal 之上的永久范围骨架；永不归档。 |
| Goal | G-NN | 带可度量 fitness function 的成果。 |
| Theme | T-NN | 相关工作项的可选分组。 |
| Work | W-NN | 可执行单元，带 Definition of Ready + Definition of Done。 |
| Decision | D-NN | ADR：一旦接受便不可变，只能被取代，且必须记录理由。 |
| Question | Q-NN | 开放的未知项，主动声明，而不是假装它不存在。 |
| Assumption | B-NN | 可证伪的假设，带验证方法和结果。 |
| Discovery | Y-NN | 从已完成工作中提炼出的可复用、有证据支撑的知识。 |

带类型的边把这些节点连成一张图，块之间保持无环。有了这个结构，Grove 既能回答这个任务为什么存在？，也能回答改动它会影响什么？，而且不依赖智能体的内部状态。

图一旦建好，前面承诺的路由就变成机械操作。grove next 挑出当前步骤；grove packet 只输出这一步的上下文。无关内容进不了上下文窗口。

动一行代码之前，智能体先查询因果锥。grove packet W-NN --cone 会画出反向锥（必须先完成的一切，按拓扑收缩顺序）、正向锥（这一项改动后的爆炸半径），以及每个受影响目标的脆弱度评分。

把推理变成可复用的知识

Grove 给 AI 驱动的软件开发带来一套统一方法论，吸收了 Dual-Track Agile、Hypothesis-Driven Development、ADR、Continuous Discovery、Cynefin 和 Mikado 方法。这些影响被整合进单一工作流，围绕自主 LLM 智能体的约束来设计，并用机器可校验的不变量强制执行。

多数 AI 工作流都是迷你瀑布：先把一切写清楚，再把一切做出来。Grove 让发现和交付并行推进，两条轨道互相喂养：

- Discovery 接住开放的未知项，把它们变成可操作的东西。问题变成可证伪的假设；验证过的结果变成精选的发现。
- Delivery 执行就绪的工作项，在这些假设之上写出经过验证的代码。

两者的接缝是机械的。问题针对目标提出；假设指向工作并为其设闸；发现引导下一批目标；完成的工作又提炼回发现。当某个测试证伪了一条假设，计划立刻重塑；依赖它的工作不能建在已经垮掉的地基上。

知识有生命周期

Grove 不把蒸馏出的知识当作永久真理。随着项目演进，发现会过时；要重新启用一条发现，必须重新锚定。蒸馏债务会被跟踪，而不是悄悄累积；目标适配度则在每次关闭时重新推导。

每次变更之后，仪表盘反映的是协议的真实状态，而不是预期状态。Grove 假定项目一直在动：知识会变，假设会失效，未完成的推理会累积。协议让这些变化可见，而不是让它们消失在项目历史里。

协议背后的理念

- 发现与交付并行推进（双轨敏捷，Cagan）。只要还有未解决的问题、未验证的假设挡着，工作项就不能进入交付，必须先在做发现阶段解决。
- 每个可执行单元在写代码之前都要有明确的验收标准（HDD，就绪定义）。DoR 不是谁都能绕过的检查清单；它是命令行在每次 status=progress 状态转换时求值的布尔合取。
- 长期有效的设计选择是一等工件（ADR，Nygard）。决策一旦被接受就不可变。它们不能被悄悄修改，只能由新决策取代，并记录理由。
- 未解之谜是一等工件；智能体要声明它们，而不是假装知道（持续发现；Cynefin）。标记为 chaotic 的问题会中止智能体，需要人来解决。
- 假设是可证伪的门禁，不是注释。处于 invalidated_blocking 状态的假设会阻止任何依赖它的工作项进入就绪。智能体不能靠忽略它来继续推进。
- 重构使用 Mikado 风格的依赖图，区分因果、顺序、实现和探究。这样在动第一行代码之前，变更的影响范围就已经明确。
- 已验证的目标只在蒸馏之后归档：其中已验证的假设、已解答的问题、已接受的决策都成为发现（Y），即经过整理的领域公理，永不归档，并供给未来的信息包。
- 领域（A）是目标之上永久的范围骨架。每个目标只属于一个领域，由命令行在创建时强制（I₁₃）；领域永不归档，所以这套结构比任何单个目标活得更久。

超越规格驱动开发

规格驱动开发让规格变得明确。Grove 更进一步：它让开发过程本身可执行、可验证。

规格描述系统应该做什么。Grove 还额外建模了围绕它的工作状态：什么已被证明，什么被假设，什么被阻塞，什么已就绪，什么已完成，依据是什么证据。这些不是给智能体遵循的指令；它们是协议状态，决定智能体下一步被允许做什么。
工作流从文档驱动执行变成状态驱动执行。不再有一份规格说明能重新生成整个项目，每个功能也没有固定的瀑布流程。发现和交付持续进行，一旦某个假设被证伪，依赖图和执行计划随之改变。每次状态转换都由机制把关，而不是靠智能体自觉遵守流程。

规格说明依然有用。在 Grove 里，它们可以作为决策、验收标准，以及其他结构化项目知识，挂在工作项上。变的是由谁来强制执行：规格说明描述预期结果，协议决定项目能否推进。

让证据决定工作何时完成

任务连启动都要先通过 Definition of Ready。这是一个严格的布尔合取，由协议在每次 status=progress 转换时求值，不是谁都能跳过的检查清单。一旦就绪，Grove 会发出执行包：只包含这一步需要的上下文（工作项、验收标准、待解问题、假设链，以及约束它的决策），不多给。

关闭任务需要可证伪的证据：测试输出、commit hash、构建日志。自报的 finished 不予接受。转换到 done 是原子操作；目标适配度增量和状态重新推导在同一次写入中完成，否则全都不做。

版本化的推理，不只是版本化的代码

所有状态都存在 .grove/state.lock 里，这是一个面向行的文本文件，每次变更都会重写 SHA-256 校验和。任何手动编辑、乱跑的脚本或错误合并，都会在下一次协议操作时被发现，在文件修复之前，所有状态转换都被阻断。

锁文件可以放在项目仓库内部，让项目推理的历史与代码一同演进；也可以放在外部，单独一个目录或仓库。两种拓扑都支持。提交到版本控制后，锁文件的历史就成了项目推理的历史，而不只是代码的历史。

合并冲突与竞态

典型的竞态发生在两个分支各自推进项目状态时：

1. 分支 A 合并进 main，推进了项目状态。
2. 分支 B 创建得更早，仍带着之前的校验和。
3. 合并两个分支时校验和不匹配。

Grove 会检测出这种分歧，而不是默默接受不一致的状态。

解决方式是机械的：

1. 解决文本冲突，保留双方的记录。
2. 运行 grove repair --confirm，重新规范化并重新计算校验和。
3. 运行 grove check，暴露任何不变量违规。
4. 如果分支之间出现 ID 冲突，运行 grove renumber。

并行工作

对于并行 worktree，grove init --id-stride/--id-offset 会分配互不相交的 ID 区间，从一开始就避免冲突。
在同一台机器上，并发修改由独占 flock 保护，已认领的工作由会话 token 保护。

按设计，多台机器同时写同一个 lockfile 不在支持范围内。远程状态变更必须经由唯一的规范写入方，例如主 CI 智能体。

可执行的历史，而不只是审计轨迹

Git 给代码做版本管理。Grove 给产生代码的推理过程做版本管理。多数智能体框架和 SDD（Spec-Driven Development）工具在任务关闭的那一刻就丢掉了「为什么」。Grove 把每个动作记录进持久、可执行的日志，带来前所未有的能力：在项目决策层面完整撤销与重放。

每次修改都会向 .grove/journal.log 追加一行 JSON，包含命令、UTC 时间戳、写入它的会话 token，以及这次变更的精确逆操作。

{"v":1,"ts":"2026-07-19T12:35:19Z","cmd":"set","inv":{"op":"set_status_plain","id":"B-01","old_status":"testing"},"session":"host:0123456789abcdef"}

每条记录都自带逆操作，所以日志是可执行的。grove undo 按相反顺序重放这些逆操作，把状态精确还原到之前的样子，包括目标状态、fitness 增量和会话认领。Git 回滚实现；Grove 回滚假设、假设状态，以及支撑它的目标 fitness。

这解锁了真正的项目重放。你可以取 t=0 时的状态，重放日志，看清项目究竟如何变成现在这个样子。它相当于针对决策的 git blame：不只看到谁写了某行代码，而是回溯哪个假设得到验证、什么证据迫使转向、为什么选了某条具体路径。

日志还会记录智能体那些看不见的工作。当 Definition of Ready（DoR）守卫拒绝一次状态转换时，日志会记下失败的具体合取项。gate 运行、拒绝、撤销这类审计记录永远不会被反转，也永远不会被截断。这样记录下的是智能体尝试过什么，而不只是改了什么。

这条持久轨迹支撑 grove log 和 grove stats：重建周期时间、DoR 首次通过率，以及历史上任意时刻的内容健康度。它用纯 JSON 行写成，读取不需要任何特殊权限，可以作为原始素材，用来搭建你自己的指标，或对智能体失败模式做事后分析。

智能体消失时接着干

进行中的工作项带一个独占会话 token（只有认领它的会话才能修改它）。如果某个服务商在目标进行到一半时宕机，或者一次艰难的重构需要换个模型，另一台客户端上的另一个智能体可以通过 grove handoff 接手。也可以用 grove resume 接管会话。

所有推理和证据都在 lockfile 里，所以 grove next 和 grove packet 能瞬间重建工作上下文。不变量让新智能体保持诚实；其余进度无法造假。
智能体驱动开发的真正考验就在这里：智能体在目标中途停下时，下一个智能体接手项目，不用从聊天记录里重新拼出意图。

保留工作为何存在

结果不只是给智能体用的连续性，更是给项目负责人用的可解释性。

一项代码为何存在、依赖什么、建立在哪些假设上、有什么证据支撑它，这些在原始工作完成几个月后你依然答得上来。

快速上手

Grove 只需安装一次，之后作为项目的持久工作流层使用。

安装指南涵盖命令行、MCP 服务器、桌面应用和智能体技能包。然后在项目根目录运行 grove init，创建带校验和的状态文件。连接 MCP 服务器，添加已签名技能，用提示词模板引导第一个会话。此后，每个会话都由 grove next 驱动。

不确定 Grove 是否适合你的工作流？Gemini Notebook里有完整文档。先从一个简单问题入手，比如「Grove 如何阻止智能体在没有证据的情况下把工作标记为完成？」或「什么情况下 Grove 不适合我的项目？」

适用场景

当工作长期运行、推理密集、由自主智能体执行时，Grove 最有用。

安全与研究类工作流：安全工作跨越数月，靠假设推进：多数线索会死掉，少数成为关键路径。Grove 天然契合这种形态。每个关闭的条目都带证据，所以审计轨迹就是项目本身——只追加的日志、不可变的决策、绑定证据的关闭，无需单独的汇报流程就能回答「谁在何时基于什么得出结论」。优先级不再是感觉：关键路径、逐目标适配度、DoR 门禁正式决定下一步做什么。

架构与合规类工作：Grove 里的假设带验证方法和结果；决策带理由；发现把不变量锚定到具体表面。「我们是否仍满足 SLO」变成状态通过目标适配度指标回答的问题，「为什么这样构建」几个月后依然答得上来——每个架构选择都指向产生它的问题、假设和证据。

长期重构与跨会话功能：Mikado 式依赖图和因果锥让影响范围在第一次编辑前就明确，会话连续性让工作能挺过智能体和服务商的更换。

对于短命原型、单提示词任务，以及代码活不过会话的项目，Grove 通常不合适。

Grove 不是任务管理器、代码上下文工具或多智能体编排器。它是一套协议，为自主智能体维护经过验证的项目状态。

协议不变量

I₁: ∀ w ∈ W 且 status = progress，DoR(w) ≡ ⊤。
I₂: ∀ w 且 type = spike ∧ status = done，
produces(w) ⊆ D ∪ Q ∪ B ∪ Y ∧ produces(w) ≠ ∅。
I₃: ∀ w 且 status = done，∃ ev ∈ Evidence，satisfies(ev, AC(w))。
I₄: |{ w ∈ W : status(w) = progress }| ≤ WIP_LIMIT（默认 2）。
I₅: ∀ (n₁, blocks, n₂) ∈ E，terminal⁺(n₁) 先于 status(n₂) 可转为 progress。
I₆: ∀ t ∈ T，status(t) = done ⟺ ∀ w ∈ WI(t)，status(w) ∈ { done, rejected, archived }。
I₇: 图 (N, E ∩ (· × {blocks} × ·)) 是 DAG。
I₈: ∀ q ∈ Q 且 cynefin(q) = chaotic，状态只能由人转换。
I₉: ∀ w ∈ W 且 type = feature，DoR(w) ⇒ ∀ b ∈ BChain(w)，status(b) ∈ { validated, invalidated_acceptable }。
I₁₀: 状态转换 w → done 与把 fitness 增量应用到每个 g ∈ goals(w)、并重新推导 status(g) 是原子的。要么都成功，要么都不做。
除非增量在同一次调用中暂存（或自 w 上次状态变更以来已通过 grove fitness 预先暂存），否则命令行拒绝 status=done。
I₁₁: ∀ w ∈ W 且 status = progress，设置该状态的会话是唯一允许改动 w 的会话，直到 terminal(w) 或 w 离开 progress （例如 revert 或另一次受保护的状态变更）。持久化为头部属性 session 和 session_at（UTC）；check 拒绝缺失的 token （grove resume 会接管；见协议 §2.6）。
I₁₂: ∀ y ∈ Y：(≥1 条溯源边：(w, produces, y) ∨ (y, distills, d/q/b))
∧ (surface(y) ≠ ∅ ∨ why(y) ≠ ∅) ∧ tags(y) ≠ ∅（≥1 个术语表词条）。
任一项不满足时拒绝 proposed → active；stale → active 只能通过 grove revalidate 并支付新锚点来完成。
I₁₃: ∀ g ∈ G：∃ a ∈ A 且 area(g) = a.id，记录为必填的 area 字段，并在创建时强制（grove add g --area=A-NN）；重新分区用 grove set G-NN area=A-NN。锁中缺少 area 的目标属于违规，绝不静默修复。

带终止性：

terminal(w ∈ W) ⟺ status(w) ∈ { done, rejected, archived }
terminal⁺(g ∈ G) ⟺ status(g) = verified（对 blocks 边严格）
terminal(g ∈ G) ⟺ status(g) ∈ { verified, declined }
terminal(d ∈ D) ⟺ status(d) ∈ { accepted, rejected, superseded }
terminal(q ∈ Q) ⟺ status(q) ∈ { answered, deferred, dropped }
terminal(b ∈ B) ⟺ status(b) ∈ { validated, invalidated_acceptable, invalidated_blocking }
terminal(t ∈ T) ⟺ status(t) = done
terminal(y ∈ Y) ⟺ status(y) = superseded
terminal(a ∈ A) ⟺ ⊥（area 没有生命周期）

terminal⁺ 是用于 blocks 边的严格变体：declined 的目标不会解除依赖方的阻塞。其他关系使用宽松的 terminal。

assumptions(w) ≜ { b ∈ B | (b, targets, w) ∈ E }
BChain(w) ≜ assumptions(w) ∪ { b ∈ B | ∃ q, (q, asks, w) ∈ E ∧ (b, tests, q) ∈ E }
produces(w) ≜ { n ∈ D ∪ Q ∪ B ∪ Y | (w, produces, n) ∈ E }
goals(w) ≜ 记录在 w 的 goals 字段中
WI(t) ≜ { w ∈ W | theme(w) = t }

FAQ

状态文件是怎么工作的？ 所有状态都存在 .grove/state.lock 里。这是一个面向行的文本文件，每次写入都带 SHA-256 校验和。只要有人手动改动，下一次协议操作就会立刻发现，所有状态转换都会被拦住，直到文件修复为止。智能体从不直接读写这个文件，只通过 Grove 接口（命令行、MCP）与它交互。

这套设计让整个工作流可审计，也方便做 diff。每次转换都是一次原子写入。lockfile 可以提交到版本控制；它的历史就是项目推理的历史，而不只是代码的历史。

智能体怎样才能高效使用 Grove？需要读完整个技能，再往 lock 里写长篇大论吗？

No on both counts. The skill's index.md is the minimal safe contract - one screen, complete for operation; every other page is depth you open only when the task touches its topic. And when a command's shape is unclear, the CLI itself is the instructor: refusals like add g: --area is required or DoR ≢ ⊤; see grove dor W-NN say exactly what is missing. Even an agent that never opened the skill cannot corrupt state, because the invariants (DoR gates, evidence gates, the checksum) are enforced by the protocol, not by the document - partial reading degrades process quality, never integrity.

Writing works by compression, not by transcription. The agent deliberates in its own context for as long as it needs, then stores only the conclusions: one acceptance criterion per line, one sentence per hypothesis, a compact context/options block on a decision node. Dozens of small CLI calls are normal and cheap - they batch into a single shell invocation per node (add + fields + fitness). What never belongs in the lock is the reasoning itself: if a fact does not change what a future agent does, it is not recorded. And grove next / grove packet exist precisely so the agent never re-reads the state file to plan.

License

GNU Affero General Public License v3.0 (AGPL-3.0). Copyright (c) 2026 Alex Shelepenok. Free to use, study, modify, and redistribute under the license terms, including network use: offering Grove as a network service requires offering its source. See LICENSE for the full text.