AI Agent CLI 该怎么设计：少猜参数，多给可纠正的错误

如果一条 CLI 命令总让 AI agent 猜参数名、手工转义长 JSON、出了错只回一句“失败”，那它其实并不适合自动化。真正适合 agent 的 CLI，重点不在“功能多”，而在少猜参数、复杂输入能走文件、错误能直接缩短下一次调用路径。

在内容分发、部署、巡检这类无人值守场景里，最消耗成本的往往不是第一次失败，而是失败之后系统没有给出明确修正路径。只要错误仍然是开放题，agent 就得重新探索一遍，流程稳定性会迅速下降。

为什么很多 CLI 对 AI agent 不友好？

很多 CLI 默认假设操作者是能临场补脑的人类：

• 人会猜 --platform 和 --platforms 是否等价；
• 人会记得某个平台发布前还要补分类、标签、摘要；
• 人发现转义炸了，会换个 shell 试试；
• 人看到模糊报错，还会继续翻文档。

但 agent 不该依赖这些隐性经验。自动化里真正需要的是：

• 参数名自描述，避免盲猜；
• 失败后知道缺什么、改什么；
• 长正文、URL、嵌套对象支持文件传参；
• 发布结果可以精确对账到“本次”。

第一原则：不要让 agent 猜

一个面向 agent 的 CLI，至少应该做到四件事。

1. 命令名和参数名尽量语义化

例如 publish --doc article.md --platforms zhihu，就明显比含糊缩写更适合自动化。模型看到名字就能推断用途，失败后也更容易修正。

2. 每个子命令都支持 --help

这不是给人看的文档替代品，而是 agent 的运行时探针。它第一次失败后，应该能立刻自查可用参数，而不是离开当前环境去搜索网页。

3. 未知参数时，要指出正确写法

“invalid argument”几乎没有帮助。更好的错误应该直接告诉调用方：你传了 --platform，这里应为 --platforms。

4. 必填校验做成结构化反馈

如果正式发布失败，系统最好明确返回缺失的 category、tags、summary，而不是只说“发布失败”。

为什么 JSON 文件传参几乎是标配？

一旦命令涉及长正文、封面、目标账号、平台专属参数，shell 转义就会成为高频事故源。PowerShell、cmd、bash 对引号、换行、& 的解释都可能不同。

对人来说，这只是麻烦；对 agent 来说，这会制造一种更危险的假成功：exit code 是 0，但 URL 或正文已经被静默截断。

更稳的设计通常分两层：

1. 简单字段走命令行，例如标题、模式、平台；
2. 复杂结构走文件，例如 --doc article.md、--json payload.json。

这样做的直接收益包括：

• 长文本不依赖 shell 转义；
• agent 可以先写文件，再复用和审计；
• 一旦出问题，可以迅速区分是正文文件错了，还是命令参数错了。

好错误信息，应该让下一次调用更短

AI agent 不是怕失败，而是怕失败后没有方向。一个适合自动化的错误返回，至少应回答三件事：

1. 哪一步失败了？
2. 为什么失败？
3. 下一次最可能正确的改法是什么？

理想情况下，错误里至少包含：

• 稳定的错误 code；
• 缺失字段列表；
• 失败范围（单平台还是整批）；
• 可复用上下文，如草稿 ID、recordId、editorUrl。

以正式发布为例，VALIDATION_FAILED 比“参数不合法”有用得多；如果还能列出 missing: ["category", "tags"]，agent 就可以直接补齐重试。

发布型 CLI 为什么必须能精确对账“本次结果”？

发布工具里最危险的，不是报错，而是把旧结果误认成这次结果。比如发布后列表里确实有一条知乎草稿，但它可能是上一次留下的，不一定是这轮操作创建的。

因此，发布型 CLI 最好具备两项能力：

• 返回本次操作的唯一标识，如 recordId、postId；
• 支持按该标识回查状态，而不是只给一串混合历史记录。

这样 agent 才能准确判断：

• 这次到底是新建草稿还是正式发布成功；
• 命中的文章链接是不是本轮生成；
• 某个平台是否其实已经发布过，应该跳过而不是重发。

默认安全路径，要设计成最短路径

不是每次任务都该直接公开发布。对 agent 友好的 CLI，应该把更安全的路径变成默认值，例如：

• 默认 draft，显式传 publish 才正式发布；
• 正式发布前可先做 preview 或 validation；
• 平台特有要求显式列出，比如掘金要分类、标签、摘要；
• 手动平台明确返回 MANUAL_PUBLISH，不要伪装成已公开。

这样自动化流程就更容易拆成：预览、自检、正式发布、状态回查。

一份可以直接套用的检查清单

如果你在设计一个给 AI agent 调用的 CLI，可以先用这份清单自查：

1. 参数名是否足够语义化？
2. 每个子命令是否支持 --help？
3. 未知参数时，是否提示正确写法？
4. 长文本、URL、嵌套对象是否支持文件传参？
5. 错误是否有稳定的 code？
6. 校验失败时，是否列出缺失字段？
7. 单目标失败会不会拖垮整批任务？
8. 是否返回可回查的唯一 ID？
9. 默认路径是否偏安全？
10. 输出是否结构化到足够让脚本和 agent 对账？

常见问题

参数越少，就越适合 AI agent 吗？

不是。对 agent 来说，清晰比简短更重要。一个参数更明确、错误更可恢复的 CLI，通常比极简但高度隐式的 CLI 更稳定。

为什么文件传参比直接拼 JSON 更重要？

因为 shell 转义是自动化里的高频事故源。把复杂输入写进文件，可以显著降低引号、换行、特殊字符导致的隐蔽失败。

只做 HTTP API，不做 CLI，可以吗？

可以，但很多本地自动化链路仍然优先依赖 CLI。CLI 如果设计得足够好，本身就能成为人、脚本和 agent 共用的一层稳定入口。

发布工具为什么一定要返回唯一记录 ID？

因为没有唯一标识，agent 很容易把旧草稿或旧发布结果误认成这次操作的结果，对外发布时就会直接引发重复动作。

本文首发于 OmniGoAI 官网：https://omnigoai.com/zh/blog/cli-design-for-ai-agents/ ——OmniPost，把内容一键分发到 30+ 平台。