GitButler Agentlog Skill 实战指南用but agentlog快速恢复分支上的 Agent 工作上下文【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler导读当你在一个 GitButler 分支上继续工作时最大的信息损耗往往不在 git 历史里而在上一次 Agent 到底讨论过什么、计划过什么、改过哪些文件这类过程性上下文中。GitButler 仓库中的crates/but-agentlog模块提供了一个专门的命令行工具but agentlog它从 AgentCodex / Claude的会话转录中捕获、索引、脱敏并按分支 / Review / Change三类目标建立关联再通过skim速览与show下钻两个核心命令让你在几秒钟内回答这个分支上之前发生了什么。本文以 crates/but-agentlog/skill/SKILL.md 为骨架结合该模块的 Rust 源码完整讲解but agentlog的命令体系、输出语义、目标发现机制、隐私脱敏设计与最佳实践。读完本文你将掌握一套先 skim 定向、再按需 show 下钻的标准工作流并能读懂工具背后的存储与关联原理。一、什么是 Agentlog为分支恢复过程上下文GitButler 的 Agentlog 是对 Agent 工作会话session的捕获与检索系统。与git log展示结果提交不同but agentlog回答的是这类问题这个分支的上下文是什么这个分支之前做了什么恢复分支上下文这里之前有哪些 Agent 工作SKILL.md 中明确给出了触发场景与边界只要用户是在问上下文、历史、先前工作或分支跟进branch catch-up就应该优先使用but agentlog而不是通用的git branch/git diff检查。如果通用 GitButler CLI Skill 与本 Skill 同时适用则 agentlog 负责发现与恢复discovery通用 Skill 只负责提交、推送、分支、diff 等版本控制操作。注意区分skim提供的是压缩后的回合turn历史它包含所有相关会话与回合但每个回合都是摘要形式不是完整转录。这是理解整个工具语义的关键前提。二、核心数据模型Session / Turn / Record / Target从源码结构看agentlog 的数据模型围绕四个层级组织对应 capture.rs、transcript.rs 与 gitmeta 子模块层级含义关键字段源码中可见Session会话一次完整的 Agent 工作会话session_key、statuslocal-only/published、updated_at、turn_count、record_count、latest_captured_at、related_turn_keysTurn回合会话内的一个用户-助手交互轮次turn_key、turn_index、captured_at、record_count、tool_counts、latest_user_preview、latest_assistant_previewRecord记录回合内的单条消息 / 工具调用turn_record_index、source_record_index、timestamp、kind、role、text、tool_name、tool_input、source_recordTarget目标关联的 GitButler 对象branchref:refs/heads/...、reviewgitbutler-review:/pull-request:、changegitbutler-change:关于会话身份session_key与source_key由 Agent 名与转录来源身份会话 ID 或转录文件路径经 SHA-256 哈希截断生成形如sha256-16字节hex见 capture.rs。支持两种 Agentcodex与claude见 agent.rs。三、命令总览but agentlog的子命令but agentlog的命令行入口定义在 cli.rs核心子命令如下子命令用途示例hook从 hook 输入捕获 Agent 转录内部/高级用法通常由集成调用but agentlog hook --agent claudeskim速览与某目标相关的所有会话与回合but agentlog skimshow下钻查看某个会话或单个回合but agentlog show session --limit 20publish将本地私有会话共享为可发布的元数据but agentlog publish main/publish review idsync同步 GitMeta 元数据隐藏命令通常自动触发but agentlog sync其中publish支持--dry-run参数可先预览将共享多少会话、多少回合而不实际改动元数据cli.rs。SKILL.md 的用户工作流并不直接操作hook/publish/sync这些命令由捕获与共享管线驱动用户日常面对的是skim与show。四、核心工作流先 Skim 定向再按需 Show 下钻SKILL.md 为 Agent 规定了一条强约束的调用顺序这是整个 Skill 的骨架用skim开场做定向orientation只要先前工作可能影响下一步行动就从skim开始。把skim当作压缩的回合历史所有相关会话与回合都在但每个回合是摘要不是完整转录。能轻量回答就停下如果skim已足以支撑一个轻量状态回答直接总结并停止。有歧义才下钻仅当skim含糊、缺少理由why或需要精确证据时才下钻。下钻的标准路径先用--json重跑skim拿到session_key/turn_key再用show。用show session-key获取回合级上下文。只有需要精确细节的回合才用show session-key --turn turn-key。4.1 Skim表格目录式的速览# 自动发现当前应用的 GitButler 分支推荐起点 but agentlog skim # 显式指定目标 but agentlog skim branch branch-name-or-ref but agentlog skim review review-id-or-pull-request-key but agentlog skim change change-id-or-key # 需要精确句柄做下钻时使用 JSON 输出 but --json agentlog skimskim的语义是完整但压缩它包含每个相关会话、以及这些会话中的每个回合按时间顺序排列但每个回合只展示摘要。它的输出结构见 skim.rs形如Skim for branch ref:refs/heads/main Sessions: showing 1 related sessions, 2 turns total, 2 directly related turns. Session #1: 2 turns, 3 records, latest 2026-05-07T10:00:00.000Z status: local-only - #0 2026-05-07T09:00:00.000Z records2 related user: initial setup - assistant: implemented the branch scaffolding - #1 2026-05-07T10:00:00.000Z records1 related assistant: tests added and passing This is a skim: all related sessions and turns, abbreviated. For exact detail, use but agentlog show session --turn turn from JSON output.在源码中skim还会根据预览文本自动给回合打标签skim.rs例如包含 implemented / added / created 标记为implemented包含 decision / decided / pick / chose 标记为decided包含 review / findings / subagent 标记为reviewed包含 test / check / validation 标记为tested此外还有renamed、installed、next等标签。4.2 Show回合级与记录级下钻# 查看整个会话回合粒度 but agentlog show session-key --limit 20 # 查看单个回合记录粒度 but agentlog show session-key --turn turn-key --limit 20不带--turn时show在回合粒度上回答这个会话里发生了什么带--turn时它展示该回合内部的精确记录。默认 limit 均为 20源码常量DEFAULT_TIMELINE_LIMIT与DEFAULT_RECORD_LIMIT见 cli.rs只有当当前窗口漏掉了相关回合或铺垫信息时才需要调大--limit。4.3 关键规则不要把 git 命令当第一选择SKILL.md 特别强调普通的分支恢复场景不要先跑git branch --show-current或git status直接运行but agentlog skimskim会自己完成 GitButler 分支发现。只有当目标发现失败时才用but status检查 GitButler 状态而非 git 原生命令。此外不要把普通 Git 的gitbutler/workspace分支当作 agentlog 的查询目标——它是内部工作区分支不是业务上下文。五、目标发现Target Discovery自动还是显式当用户说当前分支或未给出显式目标时运行but agentlog skim工具内部通过but --json status读取当前已应用的 GitButler 分支名并将其规范化为ref:refs/heads/name形式见 skim.rs 的resolve_default_branch_target。显式目标的规范化规则见 cli.rs目标类型输入示例规范化后的 target_keyBranchmainref:refs/heads/mainBranchref:refs/heads/mainref:refs/heads/main原样保留Review42gitbutler-review:42Reviewpull-request:ref:refs/heads/main#42原样保留Changechange-abcgitbutler-change:change-abc从 environment.rs 可以看到捕获阶段还会做观察性目标推导读取工作区workspace中的 stacks、branches、reviews、changes并在 HEAD 指向本地分支时自动推导 PR 关联——因此即使分支元数据缺失只要 forge 缓存里有对应 PR该 PR 也会被记录为 review 目标。六、阅读 Skim 输出字段语义SKILL.md 给出了skim输出的核心字段清单target_kind与target_key本次速览使用的目标类型与规范键。sessions按时间顺序排列的相关会话包含数量统计与预览。coverage展示了多少会话、多少回合以及直接相关的回合总数showing_sessions、showing_turns、related_turn_count。sessions[].turns每个会话内的全部回合按顺序排列包含标签与预览。从 skim.rs 的序列化结构看每个会话还带statuslocal-only或published、updated_at、record_count等字段每个回合带related布尔值标记该回合是否被索引为直接相关、tool_names、labels、previews。如果skim已足够回答轻量问题直接总结并停止如果含糊或缺失为什么就用 JSON 句柄下钻show。请记住skim的输出是压缩的完整历史不是完整转录——总结时应当说我 skim 了完整回合历史的压缩形式而不是声称恢复了完整上下文。七、阅读 Show 输出字段语义7.1 会话级不带--turnbut agentlog show session-key --limit 20用于回答这个会话在回合粒度上发生了什么。核心字段见 cli.rs 的时间线渲染coverage返回的回合数与总回合数showing_turns/total_turns。turn_key用于show --turn下钻的句柄。turn_index回合在会话中的顺序号。capture_kindbackfill回填或incremental增量。record_count水合hydrate记录之前的回合大小。source_record_index_range该回合覆盖的 provider/source 索引范围。observed_targets该回合中观察到的目标。latest_user_preview/latest_assistant_preview紧凑的定向预览。tool_counts工具调用/结果的次数与工具名列表。人类可读输出形如1 of 3 turns for sha256-xxxx #0 turn-key 2026-05-07T09:00:00.000Z records2 envcomplete user: implement the feature assistant: planning done7.2 回合级带--turnbut agentlog show session-key --turn turn-key --limit 20用于回答一个回合内部到底发生了什么。核心记录字段coverage返回的记录数与回合内总记录数showing_records/total_records。turn_record_index记录在回合内的顺序。source_record_index可用的原始 provider/source 索引。timestamp、kind、role、text消息/工具的定向信息。tool_name与tool_input工具详情存在时。source_record脱敏后的存储 provider 信封用于底层调试。从 cli.rs 的记录渲染可以看出每条记录以#turn_record_index timestamp kind role或tool_name 预览的形式输出预览截断到 120 字符。八、数据从哪来捕获、环境快照与关联判定8.1 捕获链路but agentlog hook接收 JSON 输入含transcript_path与可选cwd读取 Agent 转录文件后解析为批处理capture.rs。若批处理中没有可捕获记录则跳过否则以Agent 名 会话 ID或转录文件路径的 SHA-256 哈希生成session_key与source_key随后在捕获锁capture lock保护下写入 GitMeta并触发一次异步sync。8.2 环境快照每次捕获都会生成一份环境观察environment.rs包含snapshot_statuscomplete/partial/failed。worktree工作区变更文件路径列表排序去重最多 256 个路径超出标记files_truncated。stacksGitButler 分支栈快照每个分支含key、name、reviews、commits每个提交含id、关联的change键与文件路径哈希。注意两个有意的边界提交文件路径只在每个分支最近 32 个提交MAX_COMMIT_SNAPSHOTS_PER_BRANCH内捕获以控制同步载荷工作区路径用 SHA-256 前 16 字节指纹path_fingerprint而非原文参与提交关联比较。8.3 关联判定怎么知道这个会话与这个分支有关gitmeta/read.rs是关联判定的核心。它通过目标索引status_index_key存储命中{session_key, turn_key}集合找到候选再逐条验证直接观察该回合的observed_targets中是否包含目标键read.rs。会话级关联会话的associated-targets是否覆盖目标。目标活动推断连续两个环境快照之间上一回合工作区中脏的文件出现在下一回合目标分支上的新提交中即判定存在实际编辑活动environment_promotes_worktree_to_targetread.rs。在多分支工作区中还要求这些脏文件确实由本会话编辑过避免把共享工作区的脏状态错误记到并发会话头上。工具活动证据转录记录中识别文件编辑类工具apply_patch、edit_file、write_file、str_replace、Edit、MultiEdit、Write等见 read.rs并提取其中的文件路径哈希作为编辑证据。因此skim的匹配结果应被理解为相关证据related evidence而非归属ownership——这也是 SKILL.md 要求措辞为 session related to branch X via turn Y 而不是 session for branch X 的原因。九、隐私与脱敏捕获即脱敏agentlog 在存储阶段就进行脱敏处理redaction.rs确保同步出去的元数据不携带敏感信息敏感字段名token、secret、password、passphrase、privatekey、accesskey、authorization、api key、cookie、credential、uuid、id、path、branch等含*_id、*-uuid后缀对应的值整体替换为[REDACTED:entropy]或[REDACTED:path]。高熵字符串疑似密钥/口令长度 ≥ 20 且熵值超阈值被识别并脱敏。本地绝对路径、带特殊字符的路径不会被当作公开仓库路径is_public_repo_pathenvironment.rs防止泄露机器路径信息。同样skim的人类可读输出默认不打印完整的session_key/turn_keySHA-256 句柄只在--json输出中保留以便下钻这一行为有专门测试保障见 cli.rs。在向用户总结时这些句柄也应保持内部使用除非用户要求证据句柄或需要传给后续命令。十、分享与同步Publish 与 Syncbut agentlog publish把仅本地的会话元数据共享出去供协作者或后续会话读取but agentlog publish main but agentlog publish branch main but agentlog publish review id but agentlog publish change id # 预演只报告将共享什么不实际改动 but agentlog publish main --dry-runpublish会先查询所有local-only的关联会话若存在则将它们共享随后同步 GitMeta 元数据--dry-run只生成报告而不写入任何共享键测试 cli.rs 验证了 dry-run 不产生会话索引与载荷键且本地元数据原样保留。sync通常由捕获管线异步触发spawn_agentlog_sync用于刷新元数据一致性。十一、与 Agent 集成的 Skill 元数据仓库中还提供了两种 Agent 平台的技能声明SKILL.md 的 frontmatter 声明了触发短语get context for branch、catch up on this branch、recover branch context、what prior agent work happened here并指明应优先于通用 git 分支/diff 检查使用。openai.yaml 为 OpenAI 风格 Agent 提供display_name、short_description与default_prompt同样要求先运行but agentlog skim仅在需要精确下钻时才使用--jsonshow。这两个文件共同说明了本 Skill 的定位它是 GitButler 生态中Agent 工作记忆的恢复通道与butCLI 的版本控制能力互补而非竞争。十二、最佳实践速查先定向后载荷永远从skim开始不要一上来就show或 dump 转录。能停则停轻量状态问题用skim回答后直接收尾。下钻要克制只有skim太薄、含糊、缺为什么、或用户要求做出/验证重要结论时才show。不 dump 转录需要会话细节时先show session --limit 20并总结预览而不是把每条记录都倒出来。证据化措辞说会话经由回合 Y 与分支 X 相关不说该会话属于分支 X。句柄内部化session_key/turn_key默认不展示仅在用户要求证据句柄或后续命令需要时使用。回填的代价意识--limit只在当前窗口漏掉目标回合时才增大避免一次拉取过深。总结but agentlog把Agent 上次在这条分支上干了什么从不可检索的转录文件变成了有索引、有目标关联、有脱敏保障的结构化查询。它的设计哲学贯穿于 SKILL.md 与 cli.rs、skim.rs、environment.rs、gitmeta/read.rs、redaction.rs 等源码中skim 是完整但压缩的目录show 是按需展开的细节git 命令永远不是恢复 Agent 上下文的第一选择。无论你是在 GitButler 中接手一条陌生分支还是让 Agent 在长时间会话后继续工作这条先 skim、后 show、按需 JSON的路径都能帮你以最小的成本找回最关键的过程上下文。【免费下载链接】gitbutlerThe GitButler version control client, backed by Git, powered by Tauri/Rust/Svelte项目地址: https://gitcode.com/GitHub_Trending/gi/gitbutler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考