本地 AI Agent 接文件系统，先让它有证据链

周末折腾了一下本地 AI Agent 接文件系统，踩了不少坑。起因是看到 vix-gateway v2.3.1 的 release 摘要，里面说 Agent / TUI 在 API 错误时总会返回 JSON，不再静默 TCP close 导致 RemoteDisconnected，Storage create 会校验 JuiceFS 和目录。我先不碰 MeshDrive 的分布式层，只做本地最小验证。

先解释几个词。AI Agent 是能自己调工具的程序，TUI 是终端文字界面。API 错误是后端接口出错，JSON 是带字段的错误文本，方便脚本判断。RemoteDisconnected 是连接断了但原因不明。JuiceFS 像把云存储伪装成文件夹的软件。Local-first storage 是本地优先写，再同步远端。FS 就是文件系统。

准备阶段只要三样，一台能跑命令行的电脑，一个空测试目录，一个不会乱删东西的隔离文件夹。不要拿工作盘、照片盘、芯片工程目录试。agent 更像会自己跑命令的实习生，得先给小房间。

上手我按最小流程走。先下载 vix-gateway v2.3.1 的 release 包，解压进入目录。打开终端，输入 ./vix-gateway --help，或者按 release 说明里的启动命令执行。看到 agent、storage 这类子命令再继续；没有就先停。然后建一个测试目录，比如 ./fs-test，后面所有写入都限制在这里。再执行 storage create 相关命令，把 JuiceFS 挂载点、目录路径、日志路径都指到 ./fs-test。这一步是存储体检。最后启动 Agent / TUI，界面上看到文字菜单或提示符，就让它写一个文件，把 hello.txt 写到 ./fs-test，内容是 local agent test。预期结果是 ./fs-test/hello.txt 出现，内容一致。失败时终端应该返回 JSON 错误，别只闪一句 RemoteDisconnected。

踩坑环节，我这边遇到两个。

第一个是静默断连。我让 agent 读一个不存在的路径，以前这类程序可能只打印 RemoteDisconnected，像 TCP 连接被拔了。人很难判断是网络、模型、存储还是路径问题。v2.3.1 强调 API 错误返回 JSON，这个方向是对的。新手别只看颜色，要看 error、path 这些字段。没有结构化错误，就没有证据链。

第二个是挂载点假目录。JuiceFS 看着像普通目录，背后有网络和权限。我一开始把挂载点指到只读目录，agent 写文件失败，但报错很绕。后来单独 touch 一下，立刻确认是权限。工程顺序应该是先验证文件系统，再怪模型。就像芯片验证，先跑边界条件，再看逻辑。

可以对比几种现象。文件写成功，说明 agent 有路径、有权限、存储正常，应该记录命令和输出。返回 JSON 错误，能定位字段，适合脚本判断，要保存日志，看 path/error。只有 RemoteDisconnected，说明连接断了，原因不明，要检查网络、挂载点、权限。文件写到别处，说明路径没限制，要停掉，重建隔离目录。

本地 AI Agent 接文件系统，第一步应该是在小目录里写、读、报错、留日志。模型再强，没有存储边界和错误证据，也很难进真实环境。很多瓶颈是功耗墙的问题，存储、网络、权限、日志一起拖后腿。不要一上来就接真业务数据。

接下来半年，本地 agent 的竞争会从模型会不会说话转向谁更容易审计。能返回 JSON、校验挂载点、限定目录，这些听起来朴素，但很像芯片验证里的覆盖率。没有覆盖率，没人敢流片。下一步可以拿一个非敏感文件夹，让 agent 每天写运行日志，再用脚本检查日志里有没有失败字段。等这条路跑通，再考虑接 MCP、工具调用和更复杂的存储。

---

📌 本文编译自 Hacker News，原文 https://github.com/Hardik94/vix-gateway/releases/tag/v2.3.1

版权归原作者所有，本文为基于公开报道的编译与独立分析。