AI 驱动的命令行工具开发与智能 Agent 构建：工具选型别只比较参数

AI 驱动的命令行工具开发与智能 Agent 构建：工具选型别只比较参数

我选 Agent 工具先问它能否限制能力。演示里能连十个工具不代表适合命令行程序；我只需要读取指定目录和输出结构化建议。

agent run --allow-read ./fixtures --deny-shell

拿同一份脱敏 fixture 比较：输出是否能解析、失败时有没有清晰退出码、授权范围是否可见。价格、上下文长度可以记录，但不能替代这三项。任何会上传文件的选项都要默认关闭。

先把命令的边界写成接口

命令行工具最容易被忽略的是默认行为。用户只敲一条命令时，程序会在哪个目录找文件，遇到符号链接是否继续访问，输出是给人看还是给脚本读取，这些都比模型能回答多少问题更早决定工具是否可靠。我倾向于把路径、输出格式和网络能力都做成显式参数，并给出保守的默认值。能离线完成的检查，就不因为接了 Agent 而变成一次远程调用。

输出也要分层。正常结果可以给一段易读的建议，同时提供稳定的 JSON 或明确字段供脚本消费；诊断信息写到标准错误，不要混进机器输出。这样 CI、编辑器插件和终端用户走的是同一套核心逻辑，只是展示方式不同。错误码不必设计得很花，但“输入不合法”“权限不足”“外部服务不可用”最好能区分，调用者才能决定重试、提示还是停止。

把工具调用限制在可复核的范围

Agent 需要调用工具时，我会为每个工具声明输入格式、允许目录和最大返回量。比如搜索命令只接收相对路径和固定后缀，读取命令限制单文件大小，命令执行根本不在默认能力列表里。模型给出的参数先由本地校验器检查，再交给实际函数；不要期待提示词能够替代路径规范化、权限判断或超时控制。

调试记录只保存请求类型、耗时、工具名称和结果状态。对排查来说，这些已经能看出失败发生在解析、授权还是调用阶段；把完整文件、终端历史或模型上下文写进日志，风险远大于收益。需要复现时，使用仓库里的最小 fixture 和固定配置，而不是复制某次用户的真实命令。

用一次失败测试决定是否接入

试用候选方案时，除了正常输入，我还会故意传空文件、不可读路径、格式损坏的配置和超时的模拟服务。关注点是程序能否及时退出、临时文件是否被清理、后续命令是否仍可执行。一个工具在演示里能串起十个动作，并不说明它在失败时会停在正确的位置。

最后把验收命令留在项目里：同一份 fixture 的预期输出、错误码和权限拒绝结果都可重复运行。这样以后换模型、升级依赖或调整提示词时，变化能落到具体 diff 上。命令行 Agent 应该帮人缩短检查路径，而不是扩大它能触碰的范围。

刚开始做这类工具时，功能少一点反而更容易用。先把读取、检查、输出这条链路做稳，等每一步都有明确的输入和失败表现，再考虑增加新的 Agent 动作。命令行的可预测性本身就是体验的一部分。

如果一条能力无法说明它访问什么、失败后留下什么，以及谁能复现结果，我宁可先不把它放进默认命令。

保守默认值更可靠。