AI代理决策日志指南Whiteboard的Trace系统如何捕获、搜索并引用Agent会话【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboardWhiteboard是一个开源的“深思熟虑的软件设计画布”它的Trace 系统专门为一件事而生把AI 代理Agent会话变成一份可捕获、可搜索、可引用的决策日志。当你或团队用 AI 编码代理写代码时Whiteboard 会在会话生命周期内自动记录每一次用户提问、代理思考与工具调用并把这些记录与 Git 提交绑定——未来任何人包括你自己都能回溯到“这行代码为什么被这样写”的那一刻。️ 为什么需要 AI 代理决策日志AI 代理改完代码后往往只留下一段对话记录散落在各个工具的会话历史里几周后就没人记得这段逻辑是代理基于什么上下文写出来的它当时尝试过哪些方案、为什么放弃哪次会话产出了这个提交Whiteboard 的 Trace 系统把这些会话变成结构化证据每个事件都有编号每个提交都能反查到产生它的会话让 AI 参与的开发过程第一次具备了“可审计性”。 捕获生命周期钩子如何记录 Agent 会话一次会话的三个关键事件Trace 系统不侵入代理本身而是在会话的三个节点“打卡”SessionStart会话开始、UserPromptSubmit你提交提示词、SessionEnd会话结束。每次打卡都会携带会话 ID供后续把会话与代码改动关联起来。自动适配主流 AI 编码工具Whiteboard 为四款主流代理工具内置了钩子安装器Claude Code写入~/.claude/settings.json、Codex写入~/.codex/config.toml、OpenCode 和 Pi写入各自的插件/扩展文件。安装是幂等的——重复执行不会产生重复配置也不会破坏你自己写的其它钩子。相关实现见 agent-trace-hooks.ts。记录同步先授权再上传捕获的完整会话记录默认只保存在本机。只有当你对某个仓库显式授权whiteboard trace allow .后记录才会同步到你选定的存储S3/R2 对象桶或托管存储。你可以随时用whiteboard trace status查看上传状态、用whiteboard trace deny撤销授权。存储解析与授权逻辑位于 trace-storage/ 目录。 对新手来说可以这样理解捕获是本地行为同步是授权行为两者互不干扰——即使从未配置远程存储本地搜索和提交关联也完全可用。 搜索从提交到会话的三级回溯Trace 系统最巧妙的地方是它回答“这个提交是谁哪个代理会话写的”时有一条三级兜底链见 trace-read.ts提交尾注trailer代理写入的提交会附带Agent-Session: id尾注这是最快、最可靠的线索存储索引若尾注缺失例如经过 squash 合并被改写则查询存储端的提交索引PR 扫描索引也没有时按提交信息中的 PR 编号回扫该 PR 分支上的尾注。对应的 CLI 命令非常直观whiteboard trace list --commit sha列出某个提交关联的所有代理会话whiteboard trace blame file -L start,end对文件行号做“blame”但查到的是决策它的会话而不只是最后改动的提交。 引用把会话事件变成可追溯证据拉取到本地语料库确认会话 ID 后一条命令即可把完整转录含子代理 trace拉取并规范化到本地语料库whiteboard trace pull --agent-session session-id --json命令返回的paths数组给出每个规范化文件的绝对路径布局为owner/repo/session/main.jsonl每个子代理一个同名文件。精确引用session / trace / event 三级定位每条事件都能用“会话 ID trace 名 事件编号”唯一定位whiteboard trace show session-id --event n --json返回的 JSON 中自带trace_quote_props字段可以直接作为引用凭据嵌入你的评审意见。内置的“证据规则”Whiteboard 甚至把如何引用 trace 写成了一份可执行的调查手册 trace-archaeology.md其中几条原则值得所有 AI 使用者借鉴trace 是历史证据不是当前规范——解释前务必核对当前代码引用事件时给出 session / trace / event 三级定位符引用现状时给出提交号与行号溯源缺失就如实报告绝不编造解释。 架构一览模块职责路径捕获与钩子会话生命周期记录、钩子安装/卸载packages/trace-core/src/读取与搜索提交/会话/blame 查询、缓存新鲜度管理trace-read.ts存储契约CLI 与托管存储间共享的 schema、大小限制、路由packages/trace-protocol/README.md调查手册面向 AI 的溯源与引用规范trace-archaeology.md小结Whiteboard 的 Trace 系统补齐了 AI 辅助开发中缺失的一环决策日志。它用轻量钩子捕获会话、用 Git 尾注锚定来源、用三级兜底保证可搜索性并让每条事件都能被精确引用。如果你的团队正在把 AI 代理纳入正式开发流程这套“捕获 → 搜索 → 引用”的闭环值得纳入你的工具清单。【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考