我让 AI 全自动开发了 5 个文档插件，然后把这些坑喂回了给它

一句话：5 个插件、80% 以上代码出自 AI 之手、20 多个官方文档没写的坑——这篇文章讲清楚"在宿主产品里接 AI 能力"的设计思路，以及一个更重要的发现：AI 全自动开发的上限，取决于你喂给它多少运行时真相。

如果你正打算用 AI 做点东西，这篇文章想给你三个可以直接带走的东西：

1. 一张 AI 能力选型地图——你的功能该用本地模型、云端 API 还是干脆不用模型？四条路径，一条判断标准（第二节）；
2. 一份设计启发清单——做"嵌在别人产品里的 AI 功能"，哪些设计决策决定了成败（第三节）；
3. 一套和 AI 协作的方法——什么交给 AI、什么必须人做、踩到的坑怎么变成 AI 的能力（第四节）。

写这篇文章时刻意避开了代码细节。不是说代码不重要，而是读者要的是"为什么这么设计"，不是"怎么实现"——后者在你的仓库里，前者只在这篇文章里。

背景很简单：我长期使用的一款协作文档产品开放了插件体系，我想验证一件事——把"从零写一个插件"整个交给 AI 编程智能体，人一行代码不写，只提需求、验收、报告现象，到底能走多远。

于是过去几个月，我让 AI 陆续交付了 5 个插件：

5 个插件把插件 SDK 的 4 个运行面全压测了一遍，也恰好覆盖了"在别人产品里接 AI"的全部典型场景。结论先放在这：可行，但 AI 第一次交付的东西，十个坑能踩中十个。它写不出能跑的第一版，不是因为笨，而是因为插件运行时有一堆"文档没写、只有踩过才知道"的隐藏语义。

这件事做久了，我慢慢看清一个规律：坑是学费，文档是资产。每次 AI 踩坑、我排查、把结论写进项目里的 SKILL.md，AI 的下一版就少错一批。到第四个插件的时候，它的第一版代码已经能直接跑。这篇文章就把整个循环摊开讲。

一、先懂一件事：能力与权限天然错位

任何"把 AI 塞进宿主产品"的场景，第一件事都不是选模型，而是搞清楚一个矛盾：

AI 需要的资源（网络、计算、音频、Canvas）和宿主给你的权限，几乎总是错位的。

文档插件把这一点做到了极致。插件的运行环境被劈成两半：

┌─────────────────────── Docs Host ─────────────────────────┐
│                                                            │
│   Service（文档主线程沙箱）        UI Iframes                │
│  ┌──────────────────────┐         ┌───────────────────┐   │
│  │  有全部文档权限        │ expose() │  有完整 Web 能力   │   │
│  │  读内容/改文档/插图片  │◄─────────┤  网络/推理/音频     │   │
│  │                      │─────────►│  Canvas/WebGPU    │   │
│  │  ✘ 但不能联网          │  emit()  │                   │   │
│  │  ✘ 没有第三方包       │          │  ✘ 但摸不到文档    │   │
│  └──────────────────────┘          └───────────────────┘   │
└────────────────────────────────────────────────────────────┘

左边是个有钥匙的哑巴，右边是个没钥匙的正常人。两边通信全靠异步消息，且只传得动纯数据——图片、音频、模型张量，都不能直接过桥。

这不是插件体系独有的刁难。小程序、Web Worker、浏览器扩展、任何沙箱环境，全是同一个结构。所以所有"宿主内 AI 功能"的核心设计问题都一样：

AI 能力跑在"有资源没权限"的一侧，处理结果要落到"有权限没资源"的一侧——中间那条搬运通道怎么设计，决定了整个功能形态。

有了这个视角，再看四条接入路径，就清晰了。

二、AI 能力接入的 4 条路径：怎么选

2.1 本地推理：模型跑在浏览器里

场景：Oh My Image 的一键抠图。用户在文档里选一张图，点按钮，背景没了，图片不出浏览器。

技术上：选一个支持浏览器端推理的库（我用了 onnxruntime-web 系的方案），模型约 80MB，第一次用时下载，之后浏览器缓存，推理全程在本地跑。

这三点决定了它值不值得选：

• 数据零外发——用户图片从头到尾没离开浏览器。隐私敏感、合规场景，这是唯一可选路径
• 无服务端成本——不需要 GPU 服务器，不需要按量付费，一千个用户和一百个用户对成本的影响都是零
• 代价是"重"——模型文件打进产品里没法裁剪，低端机第一次要等下载，依赖较新的浏览器能力

什么时候选它：输入是隐私数据（图片、文档、用户内容），或者你要做"离线也能用"的功能。什么时候别选：输入是纯文本、对延迟不敏感、模型太大——浏览器扛不动百亿参数。

2.2 云端 API + 代理层：绕不开的中间人

场景：夸夸机的语音合成。文本发出去，音频拿回来。

设计上的第一课：直连外部 AI 服务，在宿主环境里几乎必死。 我最初直连第三方 TTS 接口，两条死路：宿主的 iframe 域名和外部 API 不同源，被浏览器 CORS 策略直接拦截；免费接口连发几次就被限流拉黑。

解法是常识但常被跳过：在中间加一层自己的代理服务（我在一台服务器上用现成的开源库部署了一套）。CORS、限流、密钥管理三个问题，一层全解决。

一条值得记住的经验：如果功能依赖外部 AI 服务，"自己的代理层"应该出现在方案的第一页，而不是等联调被 CORS 拦了才补。它还顺手带来了换供应商的自由——上游从 A 家切到 B 家，前端一行不用动。

2.3 双模式降级：AI 能力永远不要假设它可用

场景：夸夸机同时有在线 TTS（覆盖全部关键词、多音色）和预置的离线语音包（覆盖核心关键词）。开启时先做一次健康检查，服务可用走在线，不可用自动切离线；在线模式单次失败，也能降级到该词条的离线语音。

这个设计的判断标准很朴素：

降级方案的成本（一份离线语音包 + 一段健康检查逻辑），几乎永远低于"功能不可用"的信任损失。

放到 LLM 产品上同理：云端模型超时之后，fallback 是缓存结果、小模型还是明确的错误提示？这三个选项必须在方案阶段选定，不能等线上炸了再补。用户对"AI 功能"的容错率本来就低——第一次用就失败，他会默认它永远不可用。

还有一个容易漏的设计：降级路径本身也需要被测试。我在预置语音时故意少放了一条，专门用来验证"在线失败自动切离线"真的能触发。测试降级，得先有办法触发降级。

2.4 零模型：有时候最好的 AI 方案是不用 AI

场景：夸夸机的关键词检测、Typo Checker 的错字检测，全都没用模型，靠事件 + 规则。

为什么：文档是"用户逐字输入"的场景。规则匹配毫秒级、每次敲键实时响应；云端 LLM 往返半秒起，每次敲键卡一下。在实时场景里，规则的体验碾压模型。

这条路径最容易被忽视，因为它听起来"不够 AI"。但换个角度算账很清楚：模型带来的是覆盖率和泛化，规则带来的是确定性和速度。输入模式越受控（关键词、固定格式、拼写纠错），规则的优势越大。最优解往往是混合结构：规则做第一道检测（快、便宜），命中后再交给 AI 深度处理（准、贵）。

2.5 一张表收尾

选型标准一句话：输入是隐私数据 → 本地；输入纯文本能忍延迟 → 云端加代理；要求实时 → 规则；对可用性敏感 → 双模式。

三、设计启发：做"宿主内 AI 功能"的几个关键决策

坑的细节不逐个罗列了（每篇插件复盘文章里有完整记录）。这里只讲真正决定功能形态的设计决策——每一个都是我在某个插件里用真实代价换来的。

启发 1：动作半径——改用户的，还是加新的

用户选了文档里的一张图来编辑，点"应用"之后应该发生什么？

AI 的第一版实现是"在光标处插入新图"——用户每编辑一次，文档里多一张图，原图纹丝不动。正确语义是替换优先、插入兜底：能定位到原图就改原图，实在不行才新增。

这个决策的名字叫动作半径：你的功能对用户环境的改动，最小化到什么程度？

• 改用户正在看的东西 → 用户感知是"它听懂了我"
• 默默增加新内容 → 用户感知是"它弄乱了我的文档"

对所有"往用户领地里写东西"的 AI 功能，这条都是信任的第一道关。 AI 生成内容越泛滥，"克制"越稀缺。评审任何这类功能时都值得专门问一句：撤销成本是多少？能不能一步撤销？能不能只改不增？

启发 2：感知方式——轮询、快照、还是事件

想让功能"对文档内容变化做出反应"，第一反应通常是轮询——定时读一次内容，比对新旧。

这条路在插件体系里是死的：读接口返回的是静态快照，不随编辑更新，轮询永远拿到一样的结果。正确姿势是订阅编辑事件，事件到达时再取内容，才是实时的。

抽象一层，这是个通用设计题："读"接口和"订阅"接口的边界，调用方是猜不出来的。你的功能需要感知宿主状态时，第一件事是搞清楚宿主到底提供哪种语义——提供的是快照（你该订阅事件）、是流（你该增量处理）、还是实时引用（你可以直接观察）。搞错这个，后面全是白费。

顺带一个反直觉的细节：拿到实时全文之后，"用户刚输入了什么"也不能用尾部对比来算——用户可能打在文档中间。我最终的方案是对每个关键词做计数对比：这个词出现的次数变多了，就是刚输入的。检测"增量"这件事，比想象中难，值得在方案阶段就想清楚。

启发 3：时序——加载时机不确定时，推拉结合

插件的两个模块启动顺序不确定：A 给 B 发消息时，B 可能还没准备好，消息静默丢失——不报错，不重试，就是丢了。这是所有跨模块通信里最阴险的一类问题。

标准解法叫推拉双保险：发送方把状态存下来并提供查询接口，接收方启动时先主动查一次（覆盖"我比消息晚"），同时订阅后续推送（覆盖"我比消息早"）。两头都顾到，事件丢失率归零。

这个模式适用于一切"两端启动时机不确定"的场景：iframe、Web Worker、Electron 窗口、微前端、甚至跨团队的 webhook。单靠"发"永远会丢，推拉结合是标配。

启发 4：资源命名——工程规范是最后一块多米诺

一个教科书级的案例。插件打包了 582 个音频文件部署上线，部分文件访问一律返回 400。

排障用对比法：另一个插件的几十张英文图片，走完全相同的打包路径，一切正常。最后定位到根因：文件名含中文。服务器对 URL 编码后的非 ASCII 路径返回 400。改纯数字命名，问题消失。

但故事没完，后面还倒了两块多米诺：macOS 的 zip 命令会损坏中文文件名；如果文件名里编码了关键词（012_牛.mp3），以后调整关键词顺序，播放出来的文案就和实际对不上——用户听到"靠谱"，屏幕显示"牛"。

三个 bug 一个根因：资源命名没定规范。 这条启示对谁都成立：当项目要批量产生资源文件（素材、生成物、缓存）时，"命名规范"应该在方案阶段就定好，不是出事后的补丁。

顺带说排障方法本身：这次能快速破案，靠的是手里有一个"已知正常的对照组"。排障时最贵的不是知识，是对比对象——平时就该留意留一个。

启发 5：降级体验——AI 的"不可用状态"是需求的一部分

第 2.3 节讲的是技术降级，这里讲体验侧：AI 功能的失败状态，用户看到什么？

多数 AI 功能的失败状态是"转圈 → 报错 → 空白"，用户视角等于功能不存在。夸夸机的做法是分级兜底：在线合成失败 → 播该词条的离线语音 → 连离线也没有 → 弹窗正常显示文案，静音 3 秒自动关。任何一层失败，用户都还能拿到"被夸到"这个核心体验，只是声音降级了。

设计需求时值得为 AI 功能专门画一个状态机：可用、降级、不可用三态各自的用户体验是什么？第三态不设计，前两态等于没设计。

四、AI 全自动开发：一次诚实的能力复盘

前两节讲的是"插件怎么做"，这一节讲"AI 全自动写插件，行不行"。如果你打算用 AI 做东西，这可能是最实用的一节。

先说数据。5 个插件，80% 以上的代码出自 AI，人类写的行数是零——我做的是提需求、跑验收、把异常现象描述回给它。200 多条文案库、700 多个音频的批量生成管线、四工具路由架构、九面板编辑器，全是它交付的。

4.1 它强在哪

样板和模式复用是绝对主场。 5 个插件共享同一套骨架，第一个插件趟出来之后，后面四个几乎不再犯结构性错误。"人写着烦"的重复性代码，它秒出且零错误。

排障推理出乎意料地好。 上面那个中文文件名 400 的案子，把四步排障流程和对照组给它，它自己推出了根因——这个根因任何文档里都没有，是从证据里推出来的。

不知疲倦的体力活没有对手。 枯燥至极的文案库、素材批量管线，它半小时交卷且质量在线，还会主动设计断点续传和降级测试这类细节。

4.2 它弱在哪

对看不见的运行时语义，它完全靠猜。 20 个坑里的大多数——快照语义、字段为 undefined、接口脑补——都是 AI 第一版就踩中的。不是模型不行，是这些信息不存在于它的训练语料里：alpha 阶段的内部 SDK，全网没有一篇文章。它只能按通用模式"脑补"，而脑补错误的方向，恰恰是文档缺失的方向。

最能说明问题的一个案例：宿主的 UI 接口只有"订阅事件"，没有"取消订阅"。AI 按通用事件接口的惯例脑补出了一个不存在的"取消订阅"方法，写进了清理逻辑，运行时才炸。人很难犯这种错——人会查类型定义；AI 不会，它只是"觉得应该有"。

架构决策它不会替你做。 本地推理还是云端 API、要不要降级、资源怎么命名——这些决策影响整个产品形态，AI 会给你一个默认解，但不会主动权衡你的业务约束。必须在它动工之前说清楚，事后改的代价是重写。

调试对它是黑盒。 AI 看不到任何控制台输出（宿主的日志还分裂在两个不同环境里），一轮"加日志 → 人肉看 → 描述现象"的循环要好几分钟。这是整个流程里最慢的环节，也是"全自动"里最名不副实的一环。

4.3 人和 AI 的分工表

5 个插件做下来，我把"什么交给 AI、什么必须人做"收敛成一张表，做任何 AI 项目前可以先过一遍：

注意第一行和最后一行的对称性：AI 包揽"写"，人包揽"验"，中间的"架构"和"真相"是交接面。在 AI 看不到运行时的前提下，这是唯一能跑通的协作结构。

4.4 最有用的发现：坑是学费，文档是资产

把上面这些拼起来，就得到这个实验真正的产出——一套让 AI 越用越强的循环：

AI 写代码 → 人跑一遍 → 发现坑 → 坑写进 SKILL.md → AI 下一轮不再踩
     ▲                                            │
     └──────────── 循环，坑单调递减 ────────────────┘

那份给 AI 读的文档（SKILL.md），被验证最值钱的段落按踩坑频率排序：

1. 运行环境的能与不能（铁律区）——一条"沙箱内不能发网络请求"，杜绝了后面四个插件的全部同类错误
2. 通信约束——什么数据能过桥、什么不能
3. 常见错误对照表——现象 → 原因 → 解法三列
4. 实战经验——竞态、快照、跨域、命名，按真实项目回写

再加一条纪律：每完成一个需求，把新踩的坑回写进去。效果立竿见影：同一个错误，AI 在第一个插件里犯过一次、写进文档之后，后面四个插件一次没再犯。到第四个插件，AI 的第一版代码已经能直接跑。

落到你的项目里，这套东西不神秘：SKILL.md 换成你项目里的 AGENTS.md / CLAUDE.md，循环一模一样。关键动作就三个——发现异常别只修代码，把"为什么错"写成 AI 能读的规则；规则按"能与不能 → 通信约束 → 错误对照表 → 实战经验"分层组织；强制自己每次踩坑都回写。一个月后你会发现，AI 在你这个项目里的产出质量，和它在别人项目里的，完全是两个水平。

所以我的结论是这句话：

AI 全自动开发的上限，不取决于模型，取决于你喂给它多少运行时真相。

模型三个月一换代，但"这个接口返回快照"、"两端启动顺序不确定"这些运行时真相不会过期。它们才是喂给 AI 最有营养的东西。这也是我理解这类文章存在意义的方式——文章是给人读的运行时真相，SKILL.md 是给 AI 读的，两者本质上是同一种资产。

五、怎么做一个给业务赋能的 AI 功能

最后一节回答更功利的问题：这类事情值不值得做。我的判断框架：

好的赋能功能 = 把用户的四步折叠成一步

传统流程:  切出文档 → 开外部工具 → 处理 → 贴回文档
            └────── 切换成本 ×2 ──────┘
插件流程:  宿主内一步完成 ✔

具体六条：

1. 选题：高频 × 宿主原生 × 现有功能空白。抠图（配图高频、宿主无原生能力）和错字检测（写文档高频、无原生检查）都命中。判断方法：观察用户有没有"切出去处理再贴回来"的动作，有就是空白。
2. 写回：替换优先于新增，动作半径最小化（见启发 1）。
3. 降级：AI 能力必须有 fallback（见启发 5）。
4. 协作：宿主如果有共享数据机制，主动问一句——我的数据放进去，协作者是不是自动就能看到？是的话，实时协作白拿。Draw 就是这么得到多人协作能力的：一个人画，所有人的画布自动同步，我没写一行同步代码。
5. 分发：这是宿主生态被低估的优势。普通工具要部署、域名、运维、推广；插件提审一次，组织内所有用户打开任意文档就能用。分发成本趋近于零，意味着 100 行代码的小工具从"不值得做"变成了"值得做"，ROI 的计算方式彻底变了。
6. 量化：选题时预埋指标（抠图 = 每人每次省 30 秒 × 宿主用户量），上线后拿数据说话。

六、局限性

照例诚实交代边界：结论基于 alpha 阶段的插件 SDK，接口语义可能变化；本地推理在低端设备未充分验证；关键词检测在"删了重输"场景有误判（在夸夸机里算 feature，严肃场景要另设计）；代理服务是个人部署方案，生产化要补鉴权和容量；"AI 全自动开发"的结论出自单人 + 5 个插件的样本，团队规模化需要更多数据。

另外，本文刻意略去了 15+ 个 API 级坑位的完整清单（快照语义的具体表现、跨域图片的多策略加载、iframe 日志分裂等）。下方列出目前已公开的相关专题，按需深入即可。

结语

这次实验最大的收获不是 5 个插件本身，而是验证了一个判断：AI 编程智能体在受限运行时里的表现，会随着你沉淀的"运行时真相"单调上升。文档里每一条踩坑记录，都是 AI 能力边界的一次外扩。

坑是学费，文档是资产。趟完这一轮，我把学费单都留在这了。

想动手的朋友，路径是现成的：第二节选路径，第三节抓设计决策，第四节的循环让 AI 写，第五节的公式选题。剩下的，交给时间。

相关复盘

• 图片编辑插件架构复盘：Oh My Image
• 关键词触发、语音合成与浏览器音频：夸夸插件
• 多绘图库插件工作台：工具适配、路由状态与草稿保存
• 小游戏合集架构复盘：Game-All-In-One
• 错别字检测复盘：Typo Checker
• 把本地插件变成博客在线实验室：公开运行与隔离边界