BAC 更新手记：贡献账本走进 VS Code，查看器安装与使用指南
接着上篇报道，BAC 新增 4 个提交并发布 v1.3.3、v1.3.5。重点介绍官方 VS Code 查看器的时间线、Git 比较、代码 diff、中文界面和验证功能，附手动安装教程与百字以内的 AI 安装 prompt。
BenszConan
管理员
文章目录 ⌄
熟悉 BAC 的小伙伴，应该还记得 Bensz Channel 上的《开源新项目 BAC：给 AI 编程一个篡改可发现的贡献记录》：那时我们主要讨论怎样给人类与 AI 的协作留下可复核的过程证据；随后，bensz skills v4.1.0 → v4.1.1 把贡献追踪接进了项目初始化，《BAC 更新手记：让人类贡献不再隐形，账本也更扛造了》补齐了人类输入与写入可靠性，10 月 2 日的《BAC 更新手记：部署更稳妥，也更认真地追问贡献记录的价值》则把进展讲到了部署和实际效用。沿着这条线，今天终于可以介绍一个很直观的新变化：BAC 有了官方 VS Code 查看器，可以直接在编辑器里阅读贡献账本了。 之前积累的记录，现在有了一个更方便我们自己翻阅、也更方便拿给合作者看的入口，哈哈。
这次最值得关注的，是贡献时间线、账本版本比较、关联代码 diff 和完整验证，已经放进了同一个编辑器界面。截至 2026 年 10 月 4 日核对，以上篇文章的发布时间为界，主分支新增了 4 个 commit，10 月 3 日先后发布 v1.3.3、v1.3.5 两个正式 GitHub Release。Python 包当前为 1.3.5，VS Code 插件则是独立版本 0.1.1，已经公开上架 Marketplace。本文重点聊这几项新体验，再带小伙伴们把查看器装起来。
账本可以直接打开看了
如果你的项目已经在用 BAC，大概见过 docs/contribution.bac。它一直在那里，保存着人类提出的需求、AI 的方案与实现，以及工具提供的测试证据。但过去想回看这些内容，通常要先运行命令，再在终端输出里寻找关心的记录。自己知道怎么查当然没问题，换成一个刚接手项目的同事，入口就没那么直观了。
现在安装 BAC Contribution Ledger 扩展后，直接在 VS Code 资源管理器里点击 .bac 文件，就能打开贡献查看器。左侧是事件列表，右侧是选中记录的详情，顶部提供刷新、验证和语言切换。时间线默认把最新事件放在前面；事件多了，还可以继续加载，不需要一次在终端里翻完所有输出。
我觉得这个变化最有价值的地方，是回看过程的动作终于和日常开发待在一起了。你刚看完一个文件的修改，想知道它对应什么需求、有没有留下测试证据，就可以在当前编辑器里继续找。项目交接时，也有了一个能一起点开讨论的界面。
查看器负责阅读已有的 BAC v2 账本。贡献记录仍由 BAC CLI 或接入它的工作流产生；安装插件后，原来的记录方式继续使用。尚未接入 BAC 的项目，需要先初始化并实际记录协作过程，才会有内容可看。
找回那条关键的人类输入
时间线支持按 Human、AI、Tool、System 四类来源筛选，中文界面对应人类、AI、工具、系统。每类旁边都有事件数量，点一下就能把相关记录单独拎出来。搜索框可以搜索摘要、事件类型和关联文件，来源筛选与搜索也可以组合使用。
举个很常见的场景：某次重构结束后，你想回看自己提出的“必须兼容旧数据”这个要求。如果这条输入已经记录进账本，可以先切到人类来源，再搜索“兼容”或相关文件名。找到后点开，看看当时留下了什么摘要和证据，再沿着时间线回看后续的 AI 工作与测试记录。
对经常开着 Codex、Claude Code 做长任务的小伙伴，这比只看最终 diff 更容易把思路接回来。那句只有十几个字、却改变了整个方案的要求，有机会重新回到讨论中心。 当然，搜索能找到多少，取决于当时到底记录了多少；查看器提供的是更方便的阅读入口。
摘要后面的证据，也能顺手展开
点开一条事件，除了摘要，还能查看来源、时间、声明的参与者、信任声明、Git 提交、事件标识和 hash。记录带有关联文件时，会显示文件路径和相应 hash；记录了命令时，可以查看命令文本与退出码；证据内容和原始事件 JSON 也有单独的查看位置。
这对验收很实用。比如账本里写着“测试通过”，你可以继续看它是否记录了执行命令、退出码和证据，而不必停在摘要这一句话上。交接者想核对某次修改，也可以顺着关联文件往下看。一句结论旁边有材料可查，沟通就更容易落到具体问题上。
提交之前，先看账本发生了什么变化
.bac 是一个容器文件，普通 Git diff 不太适合直接阅读它内部的事件变化。这次插件专门加了 Git changes／Git 变化 页面，把比较结果转换成我们能读懂的贡献记录变化。
这里提供三种比较范围。还不熟悉 Git 术语的小伙伴，可以这样理解：HEAD 是当前最近一次提交的版本，暂存区是已经选好、准备放进下一次提交的内容，工作区是磁盘上现在的文件。
| 比较范围 | 适合回答的问题 |
|---|---|
| HEAD → 工作区 | 从上一次提交到现在，账本总共变了什么？ |
| HEAD → 暂存区 | 这次已经准备提交的账本，包含哪些变化？ |
| 暂存区 → 工作区 | 暂存之后又产生了哪些变化，还没有放进提交？ |
操作时切到 Git 变化，选好范围，再点击 比较账本。界面会列出事件新增、修改、删除和重排，也会提示容器元数据或项目绑定是否改变。选中一项变化后，还能点击 Open event JSON diff／打开事件 JSON 差异，用 VS Code 原生双栏界面看具体字段的前后变化。
假设你刚暂存完一轮工作，AI 又继续完成了一次测试、向账本追加了记录。这时“暂存区 → 工作区”就能帮你发现这条新增事件，提醒你检查准备提交的材料是否齐全。反过来，如果旧事件被改动或删掉，也会出现在比较结果中，便于进一步核对。
它还会区分正常的尾部追加与历史内容变化，单纯的 JSON 排版差异不会被算成贡献变化。对用户而言，重点是提交前能看清这份账本具体改变了哪些记录。完整性是否通过，仍要点击验证来检查；版本比较与验证各自回答不同的问题。
喜欢从 Git 面板操作的小伙伴，也可以在资源管理器或源代码管理中的 .bac 条目上右键，选择 BAC: Compare Ledger with HEAD，不用先绕回命令行。
从一条贡献记录，接着看代码
有关联文件的事件，详情里会提供打开文件和代码 diff 的入口。目前可以看 HEAD → 工作区、HEAD → 暂存区，也可以看 记录时提交 → 工作区，比较界面继续使用 VS Code 原生 diff。
于是，回看一次工作可以很自然地连起来：找到人类需求，看 AI 留下的实现记录，打开关联文件，再核对工具证据。对于已经进入 Git 历史的代码，这会减少在账本、文件树和终端之间来回切换的次数。
有一点需要理解清楚：这里的代码比较依赖 Git 版本和当前文件。当时没有提交、后来也没有保留下来的代码内容，不能靠一个文件 hash 重新变出来。 如果记录指向的提交已经丢失，或者关联文件是二进制文件，插件会给出提示。想以后看得明白，日常记录和关键节点的 Git 提交仍然值得认真做。
把查看器装起来
方法一：自己按步骤安装
大多数小伙伴直接用商店版即可。需要桌面版 VS Code 1.90 或以上版本；普通账本浏览不需要 Python，Git 比较需要可用的 Git 和对应项目仓库。只有完整验证才需要另装 BAC CLI。
- 打开 VS Code，进入左侧 扩展／Extensions 面板。Windows、Linux 可按
Ctrl+Shift+X，macOS 可按Cmd+Shift+X。 - 搜索
@id:bensz.bac-viewer，确认扩展名称是 BAC Contribution Ledger、发布者是 bensz，点击安装。也可以打开 官方商店页面，按页面提示进入 VS Code 安装。本文核对到的商店版为 0.1.1。 - 用 文件 → 打开文件夹 打开你的项目根目录，在资源管理器找到
docs/contribution.bac；自定义账本路径的项目则打开自己的.bac文件。点击后应出现贡献时间线。 - 如果该文件原来已经在普通编辑器里打开，右键编辑器标签，选择 重新打开编辑器的方式／Reopen Editor With… → BAC Contribution Ledger。仍未切换时，在命令面板执行 Developer: Reload Window，重载窗口后再打开。
- 面板右上角的语言菜单选择 简体中文。首次界面默认英文，即便 VS Code 本身是中文也一样；也可以在用户设置中把
bacViewer.language改为zh-CN。这个选择会保存，下次打开继续生效。 - 先点人类或 AI 来源筛选，再搜索一个熟悉的需求词或文件名，打开一条记录看看详情。若要使用 Git 比较、文件跳转和验证，请只对自己信任的项目启用 VS Code 工作区信任。
看到时间线和事件详情，就说明基本查看能力已经可以用了。这一步不要求你安装 Node.js，也不用先搭建远程锚定服务。
如果扩展商店访问不顺，可以到 v1.3.5 Release 的 Assets 下载 bac-viewer-0.1.1.vsix，在 VS Code 扩展面板右上角菜单选择 从 VSIX 安装／Install from VSIX…，选中刚下载的文件，再按上面的步骤打开账本。普通用户使用商店或 VSIX 成品即可；源码构建的 Node.js 22.12+ 要求，是给自行打包插件的人准备的。
想一键验证，再加上 BAC CLI
需要完整验证的小伙伴，在准备使用的 Python 3.10+ 环境中安装或升级：
python -m pip install --upgrade bensz-auto-contribution
这里的 python 指你所选环境的 Python；macOS、Linux 上如果入口叫 python3，把命令开头换成 python3 即可。安装后运行：
bac --help
正常应该看到 BAC 的命令帮助。然后回到查看器，点击右上角 Verify ledger／验证账本，就会调用原有 BAC 验证器，并在界面中展示结果和具体报告。
如果终端能运行 bac，插件却提示找不到验证器，通常需要核对环境路径。插件会从 PATH 或 ~/.local/bin/bac 查找；使用虚拟环境时，可在 VS Code 设置里搜索 bacViewer.bacExecutable，填入那个环境中 bac 可执行文件的完整路径，Windows 下则是相应的 bac.exe。这里填文件路径，不是 python -m … 这样的命令字符串。
如果通过 Remote SSH 或开发容器打开项目，插件运行在远程工作区一侧，Git 和 BAC CLI 也要在那里可用；安装扩展时按 VS Code 提示安装到对应远程环境。只在自己电脑上安装 CLI，未必能满足远程项目的验证需要。
方法二：把这段 prompt 交给 AI
如果你平时就在 Codex、Claude Code 或其他 harness 里工作，也可以把下面这段 100 字以内的 prompt 复制进去，让 AI 帮你检查环境和安装：
请为当前 VS Code 安装 bensz.bac-viewer，切换中文并打开项目的 .bac 账本；如需验证，再安装 BAC CLI 并配置路径。
建议在目标项目目录中发这句话，让 AI 知道要打开哪个账本。能够调用 VS Code 命令行的环境，通常可以用下面这条命令安装扩展：
code --install-extension bensz.bac-viewer
如果当前 harness 没有 GUI 操作能力，AI 可以完成安装、检查配置，并把最后需要你点击的位置说明白。最终验收很简单：扩展面板里能找到它，打开 .bac 能看到时间线，需要完整验证时，点击验证能得到报告。
v1.3.5 把几个使用细节也照顾到了
中文界面切换，不打断正在看的记录
v1.3.3 首先带来了查看器；随后 v1.3.5 对应的插件 0.1.1 补上了持久化语言设置和中文说明。切换语言时，搜索词、来源筛选和所选事件会保留；Git 比较可以再执行一次。界面里的读取失败、路径问题等提示，也有了英中文资源。
这里还有个我挺认可的细节：切换中文会翻译界面，账本里的贡献摘要、命令、证据、原始 JSON 和验证器输出则保留原文。 阅读入口可以更亲切，复核材料仍然保持原样。与合作者对照同一条记录时，也更方便确认大家看的确实是同一份内容。扩展名称和命令面板入口继续使用英文，按本文给出的统一名称就能找到。
文件变了，旧的验证结果就会失效
查看器初次打开账本，默认显示 Not verified／未验证。读得出来之后，你仍然需要主动点击验证，才能获得 BAC CLI 的检查结果。报告会展示错误、警告，以及锚定回执等相关状态。
更贴近日常使用的是：账本文件更新后，界面会自动刷新，并清除旧验证结果。比如你在看账本时，AI 又追加了新工作，刚才那份报告就不会继续被当作新文件的验证结论。Git 历史发生变化时，则可以手动重新比较。
这能减少一个很常见的误会：看到先前的“通过”，就以为后来新增的内容也一起检查过了。验证结果对应的是那次检查的工作区账本，Git 比较中的历史版本也不会自动继承这个状态。
查看器本身只读，不修改账本，也不会执行事件里记录的命令。它把过程证据展示给你，验证器检查其完整性；最终如何理解参与者身份、记录覆盖和署名，仍要结合实际材料判断。拿它做项目复盘很合适，但别把一个绿色状态理解成“所有贡献都已被证明”。
稳定版的获取路径更完整了
这次两个正式版本，也把上篇文章介绍的主分支积累纳入了 Release。v1.3.3 包含查看器首版，同时收录此前的部署加固、文档和研究材料；v1.3.5 继续完善语言、打包和发布流程。普通用户现在可以分别从 PyPI 获取 CLI、从 Marketplace 获取插件，或者从 GitHub Release 下载 wheel、源码包和 VSIX。
项目同时更新了 Docker Hub 的 1.3.5 和 latest 等标签；当前发布说明标注的平台为 linux/amd64。已经自托管的小伙伴，需要结合自己的服务器架构和部署文件更新；镜像升级与 Compose 配置同步是两件需要分别检查的事。
这轮也升级了插件打包工具，清除了依赖审计中的 6 项高危告警。按 v1.3.5 发布记录，Python 侧 69 项测试及 4 项子测试通过，插件 9 项测试和 macOS 桌面实际交互测试通过，依赖审计零告警。这些是项目发布记录中的验证结果，说明本次对语言切换、Git 比较和代码 diff 做过检查；其他系统或特殊工作区的表现，仍欢迎小伙伴们反馈具体问题。
至于上一回提到的贡献边界、独立证据和人类干预价值研究，这次也随正式版本收录了相关材料。它们还属于研究计划与论证积累，尚未变成自动贡献评分功能。现阶段最容易感受到的进步，就是打开账本、查找记录和复核变化的步骤更顺手了。
小结
这次 BAC 从 v1.3.2 走到 v1.3.5，最让我在意的变化，是贡献记录终于有了一个适合日常打开的编辑器入口。时间线帮我们找回关键输入，Git 比较让提交前的账本变化更容易读懂，关联代码 diff 与验证报告又让复核可以继续往下走。插件 0.1.1 把中文切换和读取提示也补了起来。对已经在项目里积累 .bac 的小伙伴，现在很值得装上查看器，翻一翻自己留下的工作过程；对刚接触 BAC 的朋友，也可以先从一个小项目开始，看看它能否帮你把交接和复盘讲得更清楚。觉得有用的话，欢迎给项目点个 Star，或者把具体使用场景带到评论区聊聊！
项目 GitHub 地址：https://github.com/huangwb8/bensz-auto-contribution
评论区
0 条评论