让 Agent 可见、可控、可复核：做 Vizruna 学到的 5 条原则

Vizruna 是我做的一个本地 Agent 工作台。它基于 Pi Agent Runtime，把模型、Skills、工具和会话的运行过程组织成一个在浏览器里就能用的图形界面。你可以和 Agent 对话，看它思考、调用工具，检查它改了哪些文件，还可以让多个 Agent 并行工作。

它在 2026 年 7 月 28 日发布了第一个 Alpha 版本，到 9 月 1 日已经迭代到 alpha.10，目前仍是公开 Alpha。

为什么要做它

我自己平时用 Pi 的命令行写代码（这个专题的第一篇讲过），但想把它用到团队和企业里时，碰到了几个很实际的问题：

Vizruna 就是为了解决这几件事做的。它以开源的 pi-app 为起点，整个开发过程主要靠 Pi 完成，开工前写好的两份说明见上一篇。

这一个多月里，功能加了很多，但真正让它变得“能用”的，是下面 5 条原则。

大多数 Agent 工具给你的，是一个输入框和一段最终回答。中间它读了哪些文件、调了哪些工具、为什么这么做，基本是黑箱。

Vizruna 做的第一件事，就是把过程摊开：按真实的时间顺序，展示用户消息、正在思考、工具调用、流式回答、运行统计和上下文用量。每一轮运行都会单独保存开始和结束时的上下文、Token、工具、压缩、文件和错误，后面的运行不会覆盖前面的记录。

看得见，才谈得上放心交出去。 出了问题，你能定位到是哪一轮、哪一个工具出的错，而不是只能说一句“AI 又抽风了”。

Skill 越装越多之后，会有一个很现实的问题：如果每次都把所有 Skill 的全文塞给模型，上下文很快就满了，模型也更容易被无关内容干扰。

alpha.10 把 Skill 的使用改成了两步：

每一次实际加载了哪个 Skill，都会记录下来。这样既省上下文，也能回头核对：这次任务到底用了哪些能力。

长任务里，一个工具偶尔会返回一大段文本，比如一个很长的日志或者整份文件。直接塞进上下文，后面的对话就没地方了。

所以 Vizruna 加了一个“上下文管家”（Context Governor）：超大的工具结果先保存成本机的私有文件，上下文里只保留头尾摘要、内容指纹和一个可以恢复的引用。需要时再去读全文，不需要就不占地方。

上下文是 Agent 最稀缺的资源，值得像管理内存一样认真对待。

模型很擅长说“已经完成了”。但说完成和真的完成，是两回事。

Vizruna 里有一个“Agent 工厂循环”（Agent Factory Loop）：多个全新的子会话按固定的交接格式，依次负责实现、检查和修复。规则很简单：没有实际验证的证据，模型不能只凭一句“完成”结束循环。

同样的思路也用在了运行诊断上：旧的运行如果没有留下证据，界面会明确标注“无法判断”，而不是用当前环境去反推一个结论。

调一个 Agent，最怕的是“感觉变好了”。改了提示词、换了模型，到底是进步还是退步，很多时候说不清。

Vizruna 的做法是：

两次运行也可以并排比较：版本、模型、思考强度、Token、费用、工具失败和上下文变化，一目了然。比较只标记值得注意的差异，不让模型去猜因果。

你不需要用 Vizruna，也可以用上这 5 条原则。我给客户做 Agent 时，会把它们翻译成更朴素的问题：

如果你想把一段工作交给 Agent，又担心它“做了什么都不知道”，可以看看我的 Skill / Agent 定制服务：我交付的每一个流程，都会按这 5 条原则来做。