一天写完一个Obsidian插件|顺序比代码值钱

做到第三个插件的时候，我想通了一件事：让 AI 写代码最快的方法，不是让它直接写，而是先让它把真实世界摸清楚。

前两篇文章，我分别把 Hermes Agent 和 WorkBuddy 请进了 Obsidian。第一个下载量过了 9000，第二个两天做完。

这次的主角是 Google 的 Antigravity CLI，命令叫 agy，背后跑的是 Gemini 3.8 Flash。它读长文章的表现好到让我想把它钉在笔记库旁边——总结、翻译、提取要点，一气呵成。

开发只花了一天，几乎没有返工。

我想把这一天的时间分配写下来。因为比起任何一个功能，顺序本身才是最值钱的东西。

01｜这一次，我只让 AI 做一件事

我每天往 Obsidian 里处理很多文章。

真正想做的事其实很固定：总结、翻译、提取要点、拟标题打标签，然后把结果留在这篇笔记里。

前两个插件都是“万能 Agent”，能读写整个笔记库、能跑多步骤工作流。这一次我反过来收窄范围——

五个预设按钮，一个聊天面板，一排"把结果写回去"的动作：替换选区、追加到笔记、新建笔记、写入 frontmatter，外加对整个文件夹的批量处理。

范围缩小之后，反而有余力把“写回去”这一步做细。

哪怕你点完按钮就把光标挪走了，"替换选区"也能凭当初记下的位置和原文找回那段字，再把结果换上去。

方法论一：先决定不做什么。 一个只做一件事的工具，才有资源把最后一公里铺平。

02｜先探针，再 PRD，最后才写代码

这一天的前两个小时，没有写一行插件代码。

手头唯一的参考项目并不可靠：它只在 macOS 上验证过，每轮对话都重新起一个进程，和我打算走的路线完全不同。它的文档能告诉我协议"大概"长什么样——但"大概"不够写解析器。

于是我让 Claude Code 先去跑真实命令：

每条命令的输出原样存成文件，后来直接变成了单元测试的夹具。协议长什么样，不靠猜，不靠参考项目的文档，靠这些文件。

探针跑完，才写 PRD。文档里列出四个需要我拍板的决策：默认模型选哪个、要不要在第一版就做文章预设、传输方式用哪种、Agent 默认有没有文件权限。

我回了一个 approved，它才开始写码。

后面的实现分成五个阶段。光是协议解析器就有 19 个测试，直接对着三份真实输出的夹具跑——一份单轮对话、一份带工具调用、一份两轮中文会话。解析器每改一行，都是在和真的 agy 对话。

这套顺序的价值，在参考项目那里得到了反向印证。

那个项目的文档没提到 system_message 这种步骤类型，也没提到"只思考不输出文字"的步骤会带着用量信息一起结束。这两种情况都躺在我的夹具文件里。

让 AI 写代码最快的方法：先让它把真实世界摸清楚，再让它写文档，最后才让它写代码。

03｜三个坑，全在文档之外

坑一：参数吞字。

敲下 agy -p --output-format json，它回了一行字：“-p 把 --output-format 当成提示词了。”

-p 不是开关，它会吞掉后面紧跟的参数。参考项目每轮都用 -p 传整篇文章，所以从没撞上这个问题。而我要走标准输入，就必须完全绕开它。

坑二：隐形 BOM。

从 PowerShell 灌一行 JSON 进 agy 的标准输入，它回了一句"非法字符"。上一篇 WorkBuddy 文章里，BOM 坏掉的是一个 JSON 文件；这次它藏在管道里，同样看不见。

换成无 BOM 的写法就好了。从 Node 直接拉起子进程时，根本不会有这个字节。

坑三：命令行太长。

参考项目每轮对话都起一个新进程，把整篇文章放在命令行参数里。Windows 有一个硬上限：命令行不能超过 32K 字符。一篇长文章就够撞线了，何况每轮还要付 7 到 10 秒的启动时间。

我改成了每个聊天标签页一个常驻进程，消息按 NDJSON 从标准输入送进去。点 Stop 就杀掉整棵进程树——因为 agy 自己还会拉起一个语言服务器和一个更新器，只杀父进程会留下孤儿。下一轮对话带上 --conversation 续接，上下文一点不丢。

这三个坑有一个共同点：全都是探针阶段就暴露出来的，没有一个是写完代码才发现的。

方法论二：参考实现是地图，不是路线。 它告诉你协议长什么样，但你产品的调用形态一旦不同，每一个"它这样做过"的结论都要在自己的路线上重测。

04｜进程级开关，和第三次说"不"的审查机器人

结构化输出是这个插件最顺手的功能：让模型给文章拟标题、打标签，然后一键写进笔记的 frontmatter。

agy 提供了 --json-schema，一试却发现它是进程级开关——一旦打开，这个进程往后每一轮都强制吐 JSON，聊天就没法正常聊了。

解法是给这类预设单独开一个一次性会话：起进程、跑一轮、拿到解析好的对象、关掉。聊天标签页的常驻进程完全不受影响。

结构化输出做完，我把 0.2.0 提交到官方市场。

审查机器人第三次对我说不。

这个版本里有一行注释关闭了"定时器必须用 window"的规则，因为同一个文件也要在 Node 的测试环境里跑，那里没有 window。

机器人给了三个错误，其中一条：这条规则不允许被关闭。

改成"有 window 用 window，没有就用 globalThis"。又被拒——不允许使用 globalThis。

最后的答案反而最简单：直接从 Node 的 timers 模块导入定时器。仔细想想本该如此，这个定时器是看管子进程的看门狗，本来就不该绑在任何一个 Obsidian 窗口上。

0.2.1，通过。

方法论三：机器审查不接受"关掉规则"，只接受"换一种做法"。 每一次被拒，都是在逼你找到那个本来就更正确的 API。

05｜把 Gemini 请进你的笔记库

插件已经开源，MIT 协议。

装好 agy 并登录，在 Obsidian 里启用插件，点一下 Test CLI，就能在任何一篇笔记上按 Summarize、Translate、Title + tags，然后把结果留在笔记里。

GitHub 中搜索Obsidian-antigravitycli

回头看这一天，快的原因不是 AI 打字快，而是顺序对，而且代码从头到尾都对着真实输出做测试。

前两篇文章的结尾我写过，AI 正在长出文件系统的手脚。

手脚长好以后，最值钱的不是让它什么都能做，而是让它把一件事做到你不用离开当前窗口。