工作原理

这一页解释 report 背后的机制：哪些内容在 local 被收集，哪些内容会变成 git note，以及这些 data 如何进入 PR Report 和 Dashboard。使用 Agent Note 不需要记住所有细节，但当结果不符合预期时，这里是可以回看的 model。

数据流

1. Prompt向 coding agent 发出请求

hooks 会记录 prompt 和 turn id。

2. EditAI 更新文件

hooks 或 transcripts 会记录发生变化的文件，以及用于 attribution 的线索。

3. Commit写入 note

当 session 有可记录 data 时，git commit 会注入 trailer 并写入 git note。

4. Share随代码共享

git push 会把 refs/notes/agentnote 发送到 remote。

只要生成的 git hook 已安装，大多数仓库里就继续正常使用 git commit 和 git push 即可。Cursor 也能从本地 transcript 恢复 prompt / response，对 git hook 不可用的环境也能继续跟踪 commit。

存储

第 1 层：本地临时数据

.git/agentnote/sessions/ 中的会话数据。这里保存 prompts、changes 和 blob hashes 对应的 JSONL 文件。每次 commit 后都会 rotate，不会被 push。

第 2 层：Git Notes

refs/notes/agentnote 中的永久记录。每个 commit 一个 JSON。可 push、可 fetch、可与团队共享。

会话文件

文件	用途
`prompts.jsonl`	每行一个 prompt，并带有 turn 编号
`changes.jsonl`	AI 编辑过的文件，以及 post-edit blob hashes
`pre_blobs.jsonl`	每次 AI edit 之前的文件状态
`heartbeat`	会话活动时间戳
`turn`	每次 prompt 递增的单调计数器

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "实现 JWT auth middleware",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "上一条 response 解释了为什么这个 middleware 需要修改。" }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "我会创建这个 middleware...",
      "files_touched": ["src/auth.ts"],
      "tools": ["Edit"]
    }
  ],
  "files": [
    { "path": "src/auth.ts", "by_ai": true },
    { "path": "CHANGELOG.md", "by_ai": false }
  ],
  "attribution": {
    "ai_ratio": 73,
    "method": "line",
    "lines": { "ai_added": 146, "total_added": 200, "deleted": 12 }
  }
}

Attribution 模式

Claude Code

通常是 line-level。Agent Note 会比较每次 AI edit 前后的文件状态，再把之后出现的人类 edit 从最终 diff 里扣掉。

Codex CLI

起点是 file-level。只有 transcript 中的 patch 计数与最终 commit diff 一致时，才会升到 line-level。

Cursor

起点是 file-level。只有 edit 计数匹配，并且最终文件仍与最后一次 AI edit 一致时，才会升到 line-level。

Gemini CLI

通过 hooks 和 transcript 解析记录 prompt / response 与 file-level attribution。暂时还没有 line-level 归因。

`📝 Context` 的收集方式

📝 Context 是只用于展示的补充说明，用来帮助理解 continue 或 做下一个 这类很短的 prompt。它不会改变 attribution。

Agent Note Dashboard showing Context before a short prompt

reference context 来自上一条 response。只有当上一条 response 提到最终 diff 中的 file path、file name 或 code identifier 时才会使用。
scope context 来自当前 response。只有当 response 开头明确说明本次工作范围时才会使用。
Agent Note 不会只根据 yes、continue、お願いします 这类短确认来选择 Context。如果没有具体的 file 或 code 线索，就不会添加 Context。
Context 永远不会改变 files_touched、prompt ownership、AI Ratio、attribution method，也不会影响是否保存 git note。

Agent Note vs Entire

Agent Note 和 Entire 解决的是相关但不同的问题。

Agent Note 将 git commit 与产生该 commit 的 AI 对话关联起来。Entire 是更广义的 checkpoint product，包含 rewind / resume workflow。
Agent Note 将永久记录保存在 refs/notes/agentnote；临时 session 文件保留在 .git/agentnote/ 下。Entire 以 checkpoint metadata 和 hosted web application 为中心。
Agent Note 的 Dashboard 是基于 git notes 的 optional static GitHub Pages。即使没有 hosted service，也可以继续使用 Agent Note。
Agent Note 不尝试恢复旧的 workspace state。它专注于 reviewability：commit 为什么变化、哪些 prompt 参与其中，以及 diff 中有多少是 AI-authored。

Session 生命周期

事件	发生的事情
SessionStart	创建 session 目录并写入 heartbeat
UserPromptSubmit	追加 prompt、增加 turn counter，并轮换 logs
PreToolUse Edit/Write	同步捕获 pre-edit blob hash
PostToolUse Edit/Write	捕获 post-edit blob hash 和文件路径
Stop	记录 stop 事件（heartbeat 保持活跃 —— Stop = response 结束，不是 session 结束）

Git Notes

Git notes 不会出现在 branch 列表、GitHub UI 或 CI 中，但依然可以 push 和 fetch。

# 与团队共享
git push origin refs/notes/agentnote

# 从 remote 获取
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# 查看 note
git notes --ref=agentnote show <commit>