logbook

logbook

编码 Agent 经常跳过 Git 历史记录。它内容庞大，随意截取一段可能会造成误解。

每项功能都由某个人添加，而此人可能读得懂代码，却不了解背后的决策：被重写过三次的模块、尝试后又撤销的方案、上个季度那个实际上跳过了测试的“修复”。新的 Agent 会话往往缺少这些决策背景。代码地图（Graphify 等）能告诉它们各处的位置，却无法告诉它们发生过什么。logbook 会挖掘现有的 Git 历史记录（最多读取最新的 20,000 条提交），并编写一层精简的回忆资料，供 Agent 按指示查阅。

npx -y @promptwheel/logbook init

一句话：它会读取历史记录、编写摘要，并在 Agent 配置（AGENTS.md、CLAUDE.md 或 .cursorrules）中添加历史工作流。

  1,326 commits · 322 files · 7.3 years · 354 authors

  ✓ wrote LOGBOOK.md     hotspots · do-not-retry · suppression ledger
  ✓ wrote events.jsonl   1,326 structured events
  ✓ wrote JOURNEY.md     the repo's story, told back to you

单个文件。零 npm 依赖。它绝不会触碰你的源代码或 Git 历史记录，也不会将任何仓库数据发送到你的机器之外——它只会写入自己的摘要文件（而 init 会在你的 Agent 配置中添加一个代码块）。

为什么叫“logbook”

因为你需要一份精简的索引，概览检测器能够还原的决策，而不必从图书馆里搬出所有书籍。在从 GitHub 排名前 2,500 的仓库中随机抽取的 400 个仓库样本里，34% 的完整日志超过了 150k-token 的上下文估算值。Logbook 会将这些记录整理成有界的摘要和可核验的线索；它并不声称能完整还原所有决策。

三种产物

文件	内容	面向对象
LOGBOOK.md	新会话所需的摘要：热点、切勿重试（已撤销的方案）、抑制记录（跳过测试或隐藏警告的情况）、断言弱化事件、脆弱区域	你的 Agent。将其放入上下文即可——CLAUDE.md 可以引用它
events.jsonl	每条已分析提交对应一个结构化事件：类型（源代码/测试/配置/文档）、新增/删除内容、差异中发现的抑制操作、断言变化	你的工具。数据层
JOURNEY.md	以英雄之旅的方式呈现仓库历史：召唤、跨越门槛、深渊、漫长寒冬、低声达成的交易	你。运行 logbook journey，即可查看彩色版本

用法

npx @promptwheel/logbook              # analyze the current repo
npx @promptwheel/logbook path/to/repo # or any repo
npx @promptwheel/logbook journey      # the story, in color (writes nothing)
npx @promptwheel/logbook journey --compare  # rank your almanac vs the top 2,500 GitHub repos
npx @promptwheel/logbook audit        # what is STILL suppressed in HEAD, and since when
npx @promptwheel/logbook doctor       # read-only artifact/wiring/skill/query health check
npx @promptwheel/logbook context --file path/to/file --revert  # bounded, paged query view
npx @promptwheel/logbook context --file src/a.ts --file src/b.ts # multi-path OR query
npx @promptwheel/logbook annotate SHA "why it happened" --by WHO   # persist WHY a commit happened
npx @promptwheel/logbook --json       # events to stdout (writes nothing)

# era-scoped archaeology
npx @promptwheel/logbook --since 2024-01-01 --until 2025-01-01

选项：-n/--max N（提交数量上限，默认 20000）· --compare · --out DIR · -q/--quiet

context 会保留经过筛选的 query 顺序，但会将其序列化为多个页面，每页最多包含 20 个事件且大小不超过 8 KiB，并附带不透明的 NEXT 游标和明确的 END complete。这是交付格式，不是相关性排序；需要原始 JSONL 接口时，请使用 query。游标与仓库 HEAD、筛选条件、分析窗口和有序事件集绑定；任何一项发生变化，都必须从第一页重新开始。重复使用 --file，可匹配触及任意指定路径的提交；其余筛选条件仍会与这些路径的并集组合。每个 NEXT 游标都要重复使用相同的筛选条件。在默认窗口的首次运行中，CLI 会在第一页之后创建或刷新 events.jsonl，以便后续 NEXT 页面复用扫描结果；它绝不会更改源代码或 Git 历史记录。非默认的 -n 或 --since/--until 时间窗口不会缓存，因此 CLI 的每一页都会重新扫描指定窗口。在测量的 7,123 个事件中，0.8 表示形式的字节数比原始行减少了 72.7%（方法与范围）。

台账采用批处理

耗时的部分（扫描 20k 个提交的差异）只运行一次，分窗口进行，并由所有使用方复用：如果存在 events.jsonl 且与 HEAD 匹配，就会立即加载；如果有新提交，只扫描并合并这些提交。在一个有 20k 个提交的仓库中测得：冷启动需 43s，磁盘上有上次运行结果时需 0.4s，在 MCP 会话中重复调用需 4ms。应急选项：LOGBOOK_NO_CACHE=1 强制完整重建；LOGBOOK_WINDOW=N 用于调整扫描窗口。

--compare 使用嵌入 CLI 的百分位表，该表来自对 2,500 个仓库的集群运行——仍然零依赖、零网络调用。

信任与诊断

Git 主题、路径、作者和注释均由仓库控制。Logbook 会原样存储事件记录，但在渲染 Markdown 或面向 Agent 的审计输出时会清理这些值，并将结果标记为不可信证据。生成文件会逐个原子替换；两个 Markdown 产物会携带相匹配的 HEAD、事件计数、范围和台账哈希记录，以此绑定 events.jsonl。多文件刷新并非事务性的，因此下次检查时会检测到中断的文件组。

当报告看起来过时时，或提交 Bug 时，运行只读 doctor：

npx -y @promptwheel/logbook@latest doctor

它会检查生成记录的新鲜度和台账完整性、当前的 Agent 接线配置（包括会覆盖配置的 AGENTS.override.md）、已安装的 Logbook 技能，以及一次真实路径查询。它不会单独对 Markdown 正文中的用户编辑内容进行哈希校验。它不会写入任何内容；检查失败时返回非零状态，并打印简洁报告，适合粘贴到 issue 或发布帖回复中。

将其接入你的 Agent

logbook init 会为你完成此操作。手动配置时，只需在 CLAUDE.md（或 AGENTS.md / .cursorrules）中添加一个代码块，让每个新会话都先读取历史记录：

## Repo memory
Before planning or editing:
1. Read LOGBOOK.md at the repo root completely before any history query.
2. If Historical signal is LOW, use it only as a hotspot map. Otherwise,
   inspect task-relevant do-not-retry entries and fragile areas.
3. For complete do-not-retry coverage, inspect all relevant paths:
   npx -y @promptwheel/logbook context --file path/to/file --revert
   Repeat --file for each other relevant path. If output says NEXT, repeat the
   identical filters with --cursor TOKEN until END complete before concluding.
4. Treat findings as leads, not verdicts. Verify claims with git show SHA and
   confirm that the constraint still applies to the current tree.
Refresh the record: npx -y @promptwheel/logbook
Check what is still silenced: npx -y @promptwheel/logbook audit
When you investigate WHY a listed commit happened and verify it in the
diffs, persist it (replace SHA, the sentence, and MODEL with your own
model name; never annotate guesses):
npx -y @promptwheel/logbook annotate SHA "one specific sentence" --by MODEL

接线会安装历史工作流，而不是依赖 Agent 自行发明流程。这仍然只是一条指令，并非保证；实际查阅情况仍不尽如人意，因此对于高风险工作，请确认 Agent 确实查阅了历史记录。

延迟补充信息：记录说明 WHAT，你的 Agent 会持续记录 WHY

台账可以告诉你某次重构被回滚了，却无法告诉你回滚原因是 webpack4 出了问题。你的 Agent 总会在任务首次遇到这次回滚时查明原因——annotate 会保留这一发现，而不是在会话结束时丢弃：

logbook annotate c08adc2 "WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation" --by claude

LOGBOOK.md 会立即更新（后续会话发现磁盘上已有新产物时，可能永远不会再次运行 CLI），且禁止重试条目会附上原因：

- 2024-09-15 c08adc2 revert useShallow refactor in #2701 (#2703)
  - why (inferred by claude, 2026-07-11): WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation

注释存放在 annotations.jsonl 中——以 sha 为键（不可变，因此不会因事实变化而过时），带有归属信息和日期，每个提交仅保留最后一次写入。它们是叠加在记录之上的判断，绝不会与记录混为一谈：确定性台账保持不变，原因会连同出处和免责声明一起呈现。在 A/B 基准测试中测得：logbook 中带有原因说明的 Agent 会在计划阶段将真实故障原因作为设计约束（读取 token 增加 +2%）；而未补充信息的 Agent 会计划开展调查，并且在 zustand 上猜错了原因。请注意：注释虽然不会作为事实失效，但会随着时间推移而不再适用——“导致 webpack4 出问题”这一原因在 webpack4 淘汰后就不再构成约束，因此始终会显示日期。提交此文件即可共享团队记忆，或将其加入 gitignore 以供个人使用。

审计：让考古结果变成待办清单

logbook audit 会将台账中的日期与 HEAD 中仍然成立的情况关联起来：

  describe.skip  test/express.static.js:137  since 2019-05-02 (7.2y)

  1 live suppression · oldest 7.2 years

这就是现状：它的静态文件测试套件已经被跳过七年。台账告诉你事情发生的时间；审计则告诉你它现在仍在发生。当某条抑制规则被移除后又重新添加时，审计还会显示这场斗争的记录：re-silenced ×3 (+-++--+)——有人一次又一次试图修复某个测试，却一次又一次败下阵来。

上下文经济性

在从排名前 2,500 的仓库中随机抽取的 400 个样本里，LOGBOOK.md 的中位长度为 约 1,000 个估算 token。样本中完整 git log 的中位长度是它的 82 倍，且有 34% 的样本超过 150k 个估算 token。只有当会话原本需要载入原始历史记录时，才可能节省这些上下文： docs/context-economics.md。

它真的会改变 Agent 的行为吗？

在经过筛选、历史记录密集的规划任务中，会——但有一个重要限制。在后来对十个新任务进行的测试中，这些任务较少依据历史记录进行筛选；与强有力的原始 Git 指令相比，打包的 Logbook 方案并未胜出（安全计划为 2/10，对比 3/10）。所有已知记录都已编入索引，但没有一条通过 Logbook 查询传递给 Agent，说明检索和使用是瓶颈。请参阅 docs/wrong-work-benchmark.md 中关于证据状态的说明。在最初的 A/B 测试中，某个 Agent 被要求规划 zustand 中的 useShallow 重构，却直接着手重试一项已于 2024 年合并后又回退的重构。同一个 Agent 在上下文中有 LOGBOOK.md 时，则从回退开始，根据勿重试清单推断出该仓库典型的失败类型，并计划先用测试复现此前的失败。完整对话记录：docs/does-it-change-agent-behavior.md。

在一项涵盖六个任务的内部实验中，研究人员刻意选择了历史记录密集的规划任务。未获提供历史记录的 Agent 在 6 个任务中有 4 个提出了已回退或已完成的工作；获得完整生成版 LOGBOOK.md 的 Agent 则在 6 个任务中一次也没有，代价是增加约 4.7k 个上下文 token。这项实验仅评估规划，由内部人员评分，且任务专门选取了包含历史陷阱的案例。方法与范围： docs/wrong-work-benchmark.md。

适用范围说明

• 这些发现只是线索，并非定论。抑制提交意味着“应该让人看看这里”，而非行为不端。大量删除断言通常是删除功能——会据此标记。
• 检测基于提交标题和差异内容进行正则匹配（沿用一项针对 Agent 编写代码的 1,800 个 PR 研究中经过校准的分类器）。它会漏掉巧妙的规避手段，也会误报一些无辜情况。对于一个零依赖、运行只需几秒的工具来说，这是合理的权衡——也体现了明确的分工：日志簿是廉价、确定性的回忆层；读取日志簿的 Agent 则是精确层，负责根据任务筛选线索。
• 它读取的是最终保留下来的内容。Squash 和 rebase 会抹去分支内的尝试（先尝试、后回退的改动在 squash 后的差异中净变化为零），未提交的实验则完全不可见。日志簿是对 Agent 在工作过程中记录日志的补充——annotate 正是为此而设的桥梁——并不能取而代之。
• 浅克隆会妨碍分析——日志簿会提示你运行 git fetch --unshallow。

日志簿负责记录；裁判负责评判

这个工具是一对工具中的一半。日志簿会告诉你某项测试在 3 月被跳过。promptwheel——裁判——则能证明今天的“胜利”究竟来自代码，还是来自对测试的修改。同一个问题的过去时与现在时：这真的带来了改进吗？

MIT。