前面在 bensz channel，我们从《开源新项目 BAC：给 AI 编程一个篡改可发现的贡献记录》聊起，接着在《让人类贡献不再隐形，账本也更扛造了》里补上人类输入和写入可靠性，再用《部署更稳妥，也更认真地追问贡献记录的价值》讨论部署与实际用途。到了 10 月 4 日那篇《贡献账本走进 VS Code，查看器安装与使用指南》，BAC 终于有了一个可以直接点开阅读的编辑器入口。这几篇连起来，其实一直围绕同一件事：让人和 AI 一起做过的工作，日后还能讲得清楚。今天接着往下聊：有了查看器之后，怎样让它真正适合每天打开、每次提交前都顺手看一眼？

这轮更新最值得关注的，是 VS Code 查看器可以从源代码管理直接打开账本版本，并且在常用的双侧比较中，默认只展示真正发生变化的贡献记录。几千条共同历史先收起来，这次新增了什么、旧记录有没有变化，直接摆在眼前。与此同时，人类输入也能留下更完整的意图摘要，把“我让 AI 做什么、只同意做到哪一步”说得更具体。对已经积累了一段时间 .bac 的小伙伴，这两项变化都很实用。

先把版本交代清楚：截至 2026 年 11 月 1 日核对，以上篇文章的发布时间为界，主分支新增 3 个 commit，正式发布了 v1.3.6、v1.3.7 两个版本。Python 包目前是 1.3.7，插件 BAC Contribution Ledger 则是独立版本 0.1.3；本次查询也确认，Marketplace 已经上架 0.1.3，PyPI 已提供 1.3.7。已经装过上一期版本的朋友，可以直接往下看更新方法。

1 提交前看账本，终于更像是在看“这次改了什么”

1.1 从源代码管理直接点开，左右版本各归各位

上一期的查看器已经可以在“Git 变化”页面选择比较范围，也能通过右键命令发起比较。这次先补上了一个日常开发里很自然的动作：在 VS Code 左侧的源代码管理面板，直接点击 .bac 的更改条目。

过去的 0.1.0、0.1.1，对这个入口传来的 Git 版本资源支持不完整，可能在打开查看器之前就报错。v1.3.6 配套的插件 0.1.2 修好了这条路径，能够读取 HEAD、暂存区以及合并阶段的账本版本。你从哪个版本点进来，就阅读那个版本；读取失败时，会解释缺失版本、冲突或其他错误的原因。

这里有两个最常用的入口。**“更改”通常比较暂存区基线与当前工作区，适合看还没暂存的内容；“暂存的更改”**比较 HEAD 与暂存区，适合检查准备放进下一次提交的内容。HEAD 可以理解为当前最近一次提交，暂存区则是已经选好、准备提交的那一份。

举个很常见的例子：你把一轮代码和账本都暂存了，AI 随后又跑了一次测试、追加了工具记录。点开“更改”里的 .bac，就能核对这条后来产生的记录；再看“暂存的更改”，检查已经准备提交的那份账本。代码准备提交哪一版，贡献记录也能跟着检查哪一版，这件事终于顺起来了。

每一侧都会标明自己的版本来源，历史侧关联文件的打开操作也会跟随相应 Git 版本。回看旧账本时，能继续打开那个版本的关联代码，复盘就少了一层“我现在看到的究竟是哪一份”的猜测。

1.2 共同历史收起来，把注意力留给变化

v1.3.7 配套的插件 0.1.3，进一步改善了双侧比较的默认展示。

假设项目已经积累了两千条贡献事件，今天只新增三条。过去打开左右两个版本，容易面对两份长长的时间线，自己再去找那三条记录。现在，从源代码管理打开能够明确识别的常用双侧比较时，共同历史默认隐藏，直接展示新增、删除、修改和顺序变化，并告诉你隐藏了多少共同记录。

这个变化看起来很小，但账本用得越久，感受越明显。你检查一次普通提交，不必把从项目初始化开始的历史重新翻一遍；如果旧记录发生了修改、删除或重排，也能更快注意到。来源筛选旁边的数量同步按当前这一侧的变化记录统计，想看这次新增的人类输入或者工具证据，可以继续按人类、AI、工具、系统筛选。

如果这次只是追加三条新事件，旧版本那一侧可能没有变化记录。界面会给出相应提示，完整历史仍然在账本里。需要追溯某条需求的来龙去脉，切回 “贡献时间线”，就能恢复完整阅读。少展示的是重复内容，保留的是完整过程。

原来的“Git 变化”页面、事件 JSON diff 和关联代码 diff 也继续可用。默认差异视图先帮你找到值得看的地方，想追查某条事件具体改了哪些字段，还可以接着打开原生 JSON 差异窗口。

这里也交代一个使用范围：默认双侧差异主要服务于内置 Git 的工作区、暂存区比较。独立打开的历史版本、合并阶段，以及无法明确关联的两个面板，会保留普通阅读器；新增或删除整个文件时，也可能只有存在的那一侧。需要自己指定比较范围，仍然可以使用“Git 变化”。这样遇到不同入口时，看到的内容和版本含义比较容易对得上。

2 验证结果，跟着正在看的那一份走

账本比较越来越方便之后，另一个细节也更值得较真：你点击“验证账本”，验证的到底是哪一份？

这次查看器把验证和具体版本绑定得更清楚了。工作区、暂存区和历史版本分别验证，结果对应各自读取的完整账本快照。 即使差异视图只展示三条新增记录，验证仍会检查那一侧的完整版本，共同历史也包含在内。

因此，看到右侧工作区通过验证，不能顺手把左侧历史版本也当作已经通过；需要核对哪一份，就在对应视图里执行验证。历史版本读取失败，也会保留错误提示，避免你在不知情的情况下换成当前文件继续看。

日常更新时的体验也更细了：工作区或者暂存区账本内容发生变化，对应视图会刷新，旧验证结果随之失效；已经识别的双侧比较会重新计算差异。只是其他文件引起无关的 Git 状态变化时，已有的有效报告可以保留；固定提交的视图则继续指向原来的版本。

我觉得这类细节很能体现一个工具是否开始成熟。你不需要记住内部怎么处理快照，只需要知道：当前看到的版本、当前看的变化，以及当前拿到的验证报告，应该彼此对应。 当然，验证通过说明的是相应检查通过，摘要理解是否准确、贡献是否记录完整，仍需要结合实际材料判断。

3 人类意图，也值得被认真写下来

除了查看器，这轮另一项重要改进来自 v1.3.6：人类输入可以记录明确的意图摘要，并关联当时参考的材料版本。

之前我们已经解决了“人类输入有没有被记下”的问题。可用久了就会发现，只保留一句机械摘录，有时还是不够。比如你说“按报告修改，只做阶段 B，保留旧接口”，几周后再看这句话，可能仍然不知道阶段 B 具体要解决什么、哪些建议没有被采纳。

现在，接入 BAC 的 AI 工具或工作流，可以在理解消息和相关材料后，把目标、范围、约束与验收要求写进显式摘要。摘要支持 1–4000 字符，不会再沿用默认摘录的 96 字符长度去静默截断。目标复杂一点，也有地方把关键条件讲完整。

例如，同样是“按报告修改”，一条更有用的记录可以写成：“人类只采纳计划阶段 B，修复断点恢复后重复入账的问题；保留现有接口，阶段 A 的数据库迁移未获授权。”日后回看时，既能知道要完成什么，也能理解为什么某些建议没有进入实现。真正值得保存的，往往就是这些决定工作方向的限制和选择。

3.1 AI 的理解，保留自己的来源

这一版还把摘要的撰写来源分清楚了：AI 提炼的内容标记为 AI 理解，人类自行提供的摘要保留人类来源；没有经过提炼的默认摘录，则明确表示尚未完成意图理解。

如果工作流需要先捕获输入、之后才能读完报告，也可以先留下原始输入事件，随后追加一条关联的 AI 理解。后面发现理解需要修正，继续追加补充，原来的记录仍然保留。用 bac inspect --human 回看时，人类输入和关联的 AI 理解可以一起查看，同时保留各自来源。

这对协作复盘很有价值。你可以区分“当时人提出了什么”和“AI 当时怎样理解”，发现偏差时，也更容易找到它从哪里开始。这里需要接入的宿主或工作流主动提供摘要；升级 BAC 本身，不会自动替历史对话补写理解，也不会自动调用模型替你总结。

3.2 那句“按这份报告”，终于能对应到具体版本

意图摘要还支持关联项目内参考文件，记录相对路径、内容 hash，以及可选的章节位置。提交宿主实际阅读版本的 hash 后，BAC 会重新读取核对；文件已经变了，就需要重新阅读并确认，避免把对旧材料的理解挂到新版本上。

这解决的是一个特别现实的问题：同一个 report.md，今天和下周可能已经是两份内容。只记文件名，时间久了很难复核；带上版本证据，才更容易知道当时的决定依据是什么。

这里保存的是版本标识和定位，文件正文仍需要通过 Git 或其他原文件保存方式留住。对认真做项目记录的小伙伴，比较理想的习惯是：重要报告留版本，关键选择留摘要，后续实现与测试继续各自入账。过一段时间再回看，故事才接得起来。

4 已经装过查看器，怎么更新？

4.1 商店更新到 0.1.3，再重新加载窗口

打开 VS Code 的 扩展／Extensions 面板，搜索 @id:bensz.bac-viewer，确认扩展名称为 BAC Contribution Ledger、发布者是 bensz。可以从扩展页面点击更新；如果没有出现按钮，先在扩展面板菜单中检查更新。也可以打开官方 Marketplace 页面进入安装。

截至本文核对时，商店已提供 0.1.3。GitHub Release 附带插件包与商店上架原本是两个步骤，这次两边都已经能获取到新版了。

习惯命令行的小伙伴，可以执行：

code --install-extension bensz.bac-viewer --force

更新后，在实际打开项目的那个 VS Code 窗口执行 Developer: Reload Window／开发人员：重新加载窗口。关闭之前打开失败的 .bac 标签，再从源代码管理重新点击。这一步很值得做：扩展文件已经更新，旧窗口仍然可能加载着上一版代码。

随后运行下面的命令，检查安装列表里是否出现 [email protected]：

code --list-extensions --show-versions

如果列表已经是新版，窗口里却继续报旧错误，可以点击“显示日志”，检查报错路径中的 bac-viewer-<版本>/dist/extension.js。仍然指向 0.1.0 或 0.1.1，就继续核对该窗口使用的 VS Code 配置文件，以及实际启用的插件版本。安装列表和窗口实际加载版本，都对上了，才算更新到位。

4.2 商店不方便，就安装 Release 里的 VSIX

到 v1.3.7 Release 的 Assets 下载 bac-viewer-0.1.3.vsix，在 VS Code 扩展面板右上角菜单选择 从 VSIX 安装／Install from VSIX…，选中该文件，再重新加载窗口。插件需要桌面版 VS Code 1.90 或以上。

普通时间线阅读和 Git 比较不需要安装 Python；想在界面中执行完整验证，或者使用新的人类意图记录能力，再单独更新 BAC CLI：

python -m pip install --upgrade bensz-auto-contribution==1.3.7

macOS、Linux 上如果你的 Python 入口叫 python3，替换命令开头即可。使用独立环境时，在设置中将 bacViewer.bacExecutable 指向该环境的 bac 可执行文件；通过 Remote SSH 或开发容器工作时，扩展、Git 和 BAC CLI 也要在对应远程环境中可用。

插件 0.1.3 和 Python 包 1.3.7 是两套独立版本，需要分别更新。 更新后，先从资源管理器打开账本，确认完整时间线正常；再从源代码管理点开一个已有的 .bac 更改，看看变化记录和左右版本；需要验证时，再分别执行验证。中文界面仍可在账本面板右上角选择“简体中文”。

5 这两次发布，还做了哪些收尾？

把本轮提交连起来看，节奏很清楚：10 月 4 日的 72551af 发布 v1.3.6，带来意图摘要和源代码管理兼容；同日的 2facaea 补充多成员账本合并规划与插件旧版本排查；10 月 31 日的 c1fde31 发布 v1.3.7，把新的差异阅读体验和依赖维护一起交付。对应关系如下，方便小伙伴核对：

v1.3.7 也更新了插件构建依赖。按项目发布记录，本次 Python 回归为 122 项测试和 4 项子测试通过，插件 11 项单元测试以及实际 VS Code 的普通查看器、源代码管理和受限工作区集成检查通过，构建依赖审计为零告警。这些检查尤其照顾了来源筛选、没有变化的一侧、恢复完整时间线、明暗主题、窄窗口和版本刷新等真实使用场景。

另外，仓库新增了多成员 BAC 合并的设计计划，开始考虑多人、多机器各有账本时，如何保留原始记录、处理重复与分叉，并形成团队层面的材料。这部分仍然是规划，尚未提供可用的 merge 功能。有团队协作需求的朋友可以关注后续进展，当前版本先把单份账本的记录、阅读与复核用好。

6 小结

这轮 BAC 最打动我的，是它开始照顾那些“真正天天用，才会觉得别扭”的地方：提交前打开账本，先看到这次变化；回看历史，版本和验证结果能对上；几周后重新读到人类输入，也能知道当时究竟采纳了什么、限制了什么。这些改进让记录更容易进入日常复盘和交接。已经装过旧查看器的小伙伴，建议更新到 0.1.3，再翻一翻自己项目最近的几次贡献变化。用下来有什么不顺手，也欢迎把具体场景带到评论区聊聊。(～￣▽￣)～

项目 GitHub 地址：https://github.com/huangwb8/bensz-auto-contribution