vivac

用途

vivac 是一个为编码智能体设计的溯源树（provenance tree）工具。当使用智能体进行开发时，工作会不断衍生出新的工作，几层之后很容易丢失最初的目标线索。vivac 的核心思路是：每个节点都记录自己是从哪个节点“出生”的，从而在数月后仍能回答“我们为什么在这里”。

它面向同时运行多个项目、需要频繁切换上下文的开发者。作者本人并行运行八个项目，其中五个规模较大，vivac 正是为了解决“每次回到一个项目都要重新拼凑已定决策”以及“智能体改变已经确定的事情”这两个问题而构建的。

主要能力

• 溯源树：每个节点记录其父节点，形成可回溯的决策与工作结构。
• 会话简报：会话打开时自动运行 vivac session start，将当前位置、已定决策和不可触碰事项注入智能体上下文。
• 开放/关闭状态：vivac done 会拒绝在仍有未关闭发现时标记完成，并说明缺少什么；open 按顺序列出等待处理的事项，最多显示十条。
• 决策记录：--alternative 保存被拒绝的选项，--supersedes 链接推翻关系，--against 记录判定所依据的规则或支柱。
• 假设废弃：abandon 标记被驳斥的前提，其下所有内容随之废弃，但可救援的内容仍保留在出生位置。
• Web 界面：vivac web 在浏览器中打开本机所有项目，查看哪个项目有进展、哪个停滞、节点完整谱系和整棵树；Agents 页面可比较不同 harness 的原生版本并应用同步计划；Artifacts 页面连接保留的交付物与其生产者及引用精确修订的决策。
• 数据可移植：.vivac/ 是项目内的纯 JSON 行文件，可用一条命令导出，无需本二进制即可读取。
• 安全约束：写入时进行脱敏防护，不存储密钥、个人数据、文件内容，不发送遥测。

使用方式

安装：每个发布版本提供预编译二进制（Linux 和 macOS 的 x86_64 与 aarch64，Windows 的 x86_64），列于 SHA256SUMS 并带有签名构建溯源。解压后将 vivac 放入 PATH。也可使用 Rust 工具链 1.89 或更新版本通过 cargo install 从 crates.io 源码构建。升级运行 vivac update。

初始设置：在打开智能体的文件夹中运行 vivac setup，然后运行 vivac setup codex（针对 Codex）。设置会安装钩子、开场模块、服务器和技能，并显示将触碰的每个文件及每个钩子将运行的确切命令。

基本循环：开始第一条线索时说明正在做什么，这会免费创建边；然后询问当前位置和原因。

迁移已有项目：vivac setup 不会自动读取其他记忆系统或 CLAUDE.md、AGENTS.md、MEMORY.md 等文件。需使用 vivac-migrate 技能，由智能体列出所有来源、询问要引入哪些、在写入前展示计划、检查写入内容，然后逐个提议退役其他映射。

适用场景

• 同时运行多个项目，需要快速恢复上下文。
• 使用智能体开发，工作会衍生多层子任务。
• 需要记录决策及其替代方案、推翻关系和依据。
• 希望在不同 harness 或模型之间切换时保持同一份记录。
• 需要在不询问智能体的情况下自行查看项目状态。

限制

• 它节省令牌，但不是全部；智能体仍需读取文件、推理和解释。
• 它不能保证没有任何遗忘，因为所有记忆系统仍依赖模型判断。
• 它不自动捕获文件，Artifacts 需显式操作。
• 它不读取其他记忆系统或项目文档，迁移需由智能体在用户决定下完成。
• 不建议与另一个记忆系统同时使用，因为两个映射会冲突。
• 性能预算：读取 50 ms，写入 5 ms，未达标会被指出。
• 不存储密钥、个人数据、文件内容，不发送遥测。
• 拉取请求暂未开放，原因见 CONTRIBUTING.md。