为什么坚持 CLI 优先
在接入智能体之前，这些数据操作首先是命令行工具。原因很实际：CLI 是最容易被脚本组合、被自动化、被验证的形态。我自己排查问题时用它，定时任务用它，后来智能体也用它。一套工具多种消费者，维护成本只有一份。
命令设计
命令遵循「动词加对象」的结构：
metabox collect --source datasource
metabox normalize --date 2026-08-01
metabox export --format json
几条设计约定：
- 每个命令只做一件事，组合交给调用方。
- 参数有默认值，但关键操作要求显式传参，避免误触。
- 退出码严格区分：零表示成功，非零表示失败，脚本可以放心用它做流程控制。
JSON 输出契约
给智能体用的工具，输出必须是机器可读的。我给每个命令都加了 --json 开关：
- 正常输出走标准输出，整体是一个结构清晰的 JSON 文档。
- 诊断信息走标准错误，永远不混进数据流。
- 失败时输出统一结构的错误对象，包含错误码和可读信息，模型读到后能自行决定重试还是上报。
这套契约定下来之后，智能体侧的解析代码几乎没有再改过。
服务化接入
最近的一步是把这批命令包装成 MCP 服务。每个命令对应一个工具，参数定义直接复用 CLI 的参数，描述文本告诉模型这个工具适合什么场景、有哪些限制。智能体不感知底层是子进程调用还是别的什么，它只看到一组语义明确的工具。
实际效果比我预期的好：模型对「有一个工具能查数据」这类明确描述的利用率，明显高于让它在自由文本里猜命令。
小结
工具链的价值在于边界清晰：人、脚本、智能体各自通过最适合自己的入口，使用同一套能力。以上内容仅供技术交流参考。