API 友好不等于开发者友好，也不等于模型友好

Mon, 06 Jul 2026 00:00:00 +0000

上周我让一个 Coding Agent 帮我用飞书发一条群消息。

它读完了 lark-cli im --help，看到了 messages 子命令，继续往下翻——发现 messages 下面只有 delete、forward、urgent_app 这些操作。 没有 send。

Agent 懵了。发消息这么基础的操作，怎么可能没有？

它又去翻了 raw API 路径 lark-cli api POST /open-apis/im/v1/messages，拼了一大坨 JSON body，调通了。但这条路绕过了 CLI 的所有设计——参数校验、身份管理、错误处理——全部自己来。

后来我告诉它：你应该用 lark-cli im +send。这个 +send 是一个 shortcut——飞书 CLI 为高频操作预置的语义快捷方式，比 raw API 路径短得多，也比它好用得多。

Agent 不知道有这回事，因为 --help 的输出里没有明显标记 shortcut 的存在。

同样的事情也发生在钉钉上。我让另一个 Agent 用 DWS 给同事发一条消息，它调了 dws chat message send，参数都对了，返回结果是：

{"success": true, "result": {"openTaskId": "..."}}

Agent 认为发送成功了，继续下一步。但十分钟后我打开钉钉——消息根本没到。

Agent 不知道发生了什么。success: true 告诉它「成功了」，但现实是消息石沉大海。后来排查发现是 PAT 权限不够——API 返回了「成功」，但实际投递被权限系统拦截了。

对人类来说，打开手机看一眼就知道没收到。但对 Agent 来说，success: true 就是真理——它没有能力验证现实，只能信任返回值。

这就是「API 友好」和「模型友好」之间的鸿沟。

Lark on All about Raspberry Pi