Troubleshooting

大多数问题来自 local git hooks、缺失的 git notes，或 GitHub Pages 设置。

快速检查

1. 检查 local setup。

   npx agent-note status

2. 检查 commit 是否有 note。

   npx agent-note show

3. 检查 remote notes。

   git fetch origin refs/notes/agentnote:refs/notes/agentnote
   git notes --ref=agentnote show HEAD

从症状开始

症状	先看这里
PR Report 为空	确认 notes 已 push，且 workflow 拉取了完整 git history
期望的 prompt 没有显示	对比 compact 与 full
Dashboard 能打开，但 PR 没有数据	确认该 PR 的 notes 是否已经发布
git commit 没有创建 note	重新运行 init，并检查 status 中的 git: 行
Line Estimate 没有显示	确认 Agent 是否能提供足够的编辑证据

PR Report 为空

• PR branch 是在启用 Agent Note 后 push 的。
• remote 上存在 refs/notes/agentnote。
• actions/checkout 使用 fetch-depth: 0。
• PR 包含 agent 修改过文件的 commits。

如果 commit 中找不到 agent 修改过的已提交文件，Agent Note 不会写 note。

如果 header 显示 Total AI Ratio: — 和 Agent Note data: No tracked commits，表示 PR 有 commits，但没有找到这些 commit 的 Agent Note data。这不同于真正的 AI Ratio 0%。

Prompt 缺失

prompt selection 基于 commit-to-commit window，而不是整个 session。

• compact 优先显示解释 commit 所需的 prompt。
• full 显示所有保存的 prompt。
• 当前 commit 有自己的解释时，旧 task prompt 会被省略。
• 当文件名或 code identifier 能帮助理解短 prompt 时，会显示 📝 Context。

with:
  prompt_detail: full

Dashboard 没有数据

• GitHub Pages source 应为 GitHub Actions。
• workflow 必须以 dashboard: true 运行。
• 第一次 deploy 成功后会创建 /dashboard/。
• 如果 Pull Request Deploy 被阻止，open PR data 会在 merge 后显示。

注意

?pr=123 只有在该 PR 的 notes 已发布后才可用。

Dashboard 打开了错误的 PR

Dashboard 首页应显示共享历史，而不是强制跳转到 ?pr=。只有 PR Report 链接会附带当前 PR 的 ?pr=<number>。

如果旧的 Pages deploy 仍然跳转，请重新运行 Dashboard workflow，或等待 main 的下一次成功 deploy。

git commit 没有被追踪

npx agent-note status
npx agent-note init --agent claude

git hooks 是 .git/ 内的本地设置，因此每个 clone 都需要 init。

Line Estimate 没有显示

这通常是正常的。

• Claude Code 通常能提供 Line Estimate 所需的编辑证据。
• Codex CLI 只有在 transcript patch 数量匹配最终 commit diff 时才能估算行数。
• Cursor 只有在 edit 数量匹配，且最终文件仍匹配最后一次 AI edit 时才能估算行数。
• Gemini CLI 目前只显示文件级 AI Ratio。

当证据不足时，Agent Note 会回退到保守判定，而不是猜测。