理解检查点账本 benjis/agent-harness-comprehension

Agent Harness 理解层

一个面向编码智能体的实验性理解层。它在智能体工作时记录小型、结构化的检查点，将其保存在仅追加的账本中，并确定性地将当前结论与被取代的历史分开呈现。

该项目研究理解债务：即智能体改变软件的速度与人类建立关于该变更的准确、可用心智模型的速度之间的差距。

当前状态：人类理解实验尚未完成并已暂停。 工件门禁已通过，但首次遮蔽评审超时，并因聊天介导的文件访问无法支持持久导航和并排源码比较，而未产生可靠的评审决定。P01 尚未开始，研究者密钥仍处于关闭状态，也未产生任何条件层面或有效性结果。

当前方向

研究原型和冻结的外部运行仍然是可行性、阴性流行率结果、受控轨迹捕获、成本以及评审工作流失败的记录。它们并不能证明运行时或事后工件能够改善人类理解。

当前工作已转向单独的 Agentic Survivor Skills 仓库中的产品迭代。其 comprehension-sync 技能通过薄切片、重大决策暂停、直接源码访问和心智模型交接，在真实变更过程中保持人类与编码智能体对齐。这一方向受到此处观察到的形成性失败的启发；它并不是一项经过验证的干预结果。

被取代的运行时研究使用了三个匹配条件：

- 普通评审材料；
- 仅根据冻结的最终状态证据生成的事后指南；
- 使用相同最终状态模型加上合格语义检查点的运行时增强指南。

目前只有一名评审者可用。P02 打开了 9 个文件，耗时 1,420 秒，触及 1,200 秒上限，记录认知负荷为 7/7，并且未产生可靠的批准/拒绝决定。这是一个工作流结果，而不是支持任一遮蔽条件的证据。不要启动 P01、打开研究者密钥，或将冻结的数据包视为新的观察结果。任何未来的人类研究都需要另行预注册的方案，并具备正常的持久源码导航。

现有内容

- 一个基于公开生命周期、工具和命令 API 构建的 Pi 编码智能体扩展。
- 紧凑的自动执行事件，以及一个可由 LLM 调用的 record_comprehension_event 工具。
- 用于目标、假设、证据、决策、替代方案、失败、修订、约束、权衡、不变量和验证的类型化语义检查点。
- 一个仅追加的每会话 events.jsonl 账本，具有稳定 ID 和显式取代关系。
- 一个确定性的 mental-model.md 渲染器，以及 /comprehension 和 /comprehension-status。
- 针对模式、持久化、协调、渲染和扩展行为的聚焦 TypeScript 测试。
- 一个独立于 DSH 的 Ruby 评估测试框架，用于准备 ParcelFlow 任务、导入已完成的 Pi 运行、冻结已跟踪和未跟踪的更改、验证结构化产物、确定性地渲染匹配的指南、审计每一项声明、评估历史门控和混合条件价值门控、构建条件掩码数据包、记录评审会话，并生成形成性分析。

该原型不会捕获提示词、助手消息、原始工具输出、凭据或私密的思维链。源代码和观察到的行为仍然是权威依据。

仓库指南

- 研究 — 问题、假设、证据标准、范围和证伪标准。
- 实验协议 — 操作性产物审计、匹配条件、单一评审员程序，以及未来效能研究要求。
- 架构 — 已实现的 Pi 事件流、账本、对账、命令和数据边界。
- 路线图 — 当前证据门控以及有意推迟的内容。
- 评估测试框架 — 自包含的 Ruby 任务和研究命令。
- 仓库工作流 — 自动提交、文档新鲜度和研究诚信规则。

试用 Pi 原型

要求：Node.js 24.19 或更高版本，以及 Pi 0.84.x。

npm install
npm run check
pi -e ./src/index.ts

在会话期间：

- /comprehension 渲染当前的心智模型。
- /comprehension-status 显示事件计数、产物路径和持久化错误。

产物位于目标项目的本地目录中：

.pi/comprehension//events.jsonl
.pi/comprehension//mental-model.md

在审查安全和数据边界之前，请勿在敏感仓库上使用该原型。

运行评估检查

评估使用 Ruby 的标准库和 Git；它不需要 DeepSeek Harness 或早期的 DSH 实验仓库。

npm run test:evaluation

在准备真实任务工作区之前，请参阅评估指南。请将各个工作区、Pi 会话、运行目录、隐藏结果和评审员数据保留在本仓库之外。

实验沿革

这项工作始于 Agentic Survivor 的修订固定式代码阅读技能。那项工作建立了有用的证据纪律，但仅凭最终代码无法可靠地恢复失败路径或因果修订。后来的 DeepSeek Harness 实验探索了结算后证据包，而 Pi 原型通过更小的事件账本隔离了执行时捕获假设。Agentic Survivor 现在还包含 Comprehension Sync，这是一种受本项目形成性观察启发的实时人机协作工作流。
这些相关项目说明了产品与研究的沿革；它们都不是本仓库的运行时依赖，新技能的出现也不意味着本实验已经完成。

贡献

欢迎持怀疑态度的贡献：反例、测量设计、隐私审查、可移植性工作以及可复现的负面结果，与功能开发同样有价值。参见 CONTRIBUTING.md。

许可证

MIT。参见 LICENSE。