CLI for Agent

CLI for Agent

前言：最近在做 CLI 和 CLI 评测，故记录一些自己的思考。在 Agent 出现之前，软件的 CLI，比如 GitHub CLI，都是需要人去自己执行的。在进入 Agent 时代后，软件的 CLI 大部分都是给 Agent 去执行的。给人执行的 CLI 和给 Agent 执行的 CLI 肯定是有不同之处的，本篇就是来探讨在 Agent 时代下，CLI 应该怎么设计才能更好地让 Agent 执行。

1. dry-run 变得必不可少

首先我们要明白什么是 dry-run。dry-run 是一个布尔选项，和 --json、--yes 一样，是挂在子命令后面的参数，比如：

dta deploy --workspace myworkspace --dry-run

​ 起到的作用就是在正式执行前先预览本次执行会产生的影响，比如会作用于哪些资源，要进行哪些操作，当前执行的身份之类的。

​ 为什么对于一些相对危险的 CLI 操作，比如增删改，这么需要 dry-run？为什么之前我们自己用的 CLI 似乎很少看见有这样设计的？本质就是命令的执行者发生了变化。我们之前的 CLI 执行者是人类，人类在执行一条这种影响较大的 CLI 时，肯定是提前明白这个命令到底是干什么的。比如我们以前在使用 git push 时，肯定会想明白我们现在在哪个分支，我们这次改了哪些文件，我们会把代码推到哪个远端。人能理解发生了什么，所以确认即可，不需要 dry-run。

​ 但是当 Agent 来执行时，Agent 的理解和真实 CLI 的执行之前是有 gap 的。如果 CLI 提供的上下文不够清晰或者 Agent 理解出错，直接执行了这些影响较大的命令后意识到自己错了，往往已经晚了。我们引入 dry-run 第一个重要的点就是帮助 Agent 做一个检查：在执行前真正理解当前动作执行的环境、执行后要更改什么东西，如果此时发现错误可以及时纠正。我们 dry-run 生成执行计划时可以带上当前的回滚命令，也方便 Agent 即便真的执行出错也能进行回滚。

​ dry-run 还有另一个用处，就是每次 dry-run 时，可以将所有会影响当前行为与结果的因素做确定性序列化后 Hash 形成 plan ID，然后真正执行的时候重新带上这个 plan ID。CLI 执行的时候会重新计算当前的现场，如果计算出来的 Hash 值和 plan ID 不一致则拒绝执行。这么设计的原因是 Agent 的执行有时候并非连续的，比如我们可能突然让它中断一段时间后恢复执行，此时执行的环境可能就在这段时间发生了变化，如果还执行原来的命令可能会出现别的结果，所以我们要在真正执行时再加一次校验。

2 收不回来的副作用要留痕

我们在执行很多命令时，可能会与其他系统产生交互，其中不少操作会产生不可逆转的副作用。如果允许 Agent 无记录地执行，事后将无法追溯操作来源与上下文。因此，对于会产生副作用或与外部系统交互时可能中断的操作，CLI 应在本地生成一份结构化的 Receipt（执行凭证）。

Receipt 应至少包含以下字段：操作是否成功、执行者身份、执行时的现场环境快照、以及操作完成后的目标状态。这份凭证的价值体现在两个方面：一是供后续审计与排查；二是让跨会话的 Agent 能快速理解当前环境的执行历史，知道此前执行过哪些操作、最新操作是否成功、以及是否可以从当前状态安全重试。

传统 CLI 产出的是给人阅读的日志，而 Agent-Native CLI 产出的应该是给 Agent 解析的 Receipt。前者服务于人的调试，后者服务于 Agent 的状态感知与决策连续性。