AI时代：重写你的CLI

人类DX和代理DX并不对立——它们是正交的。彩色的输出、贴心的交互式提示符、简写的便利flag——这些人类友好的设计，请保留。但在这些之下，你需要构建起原始载荷路径、运行时Schema自省、输入硬化、以及安全护栏——这些代理需要的、能让它们在无人监督的情况下安全运行的基础设施。在AI代理越来越多地充当"人与系统之间的中间层"的今天，CLI不再仅仅是开发者手中的瑞士军刀——它正在成为AI代理伸向外部

飞函安全

431人浏览 · 2026-03-05 20:13:25

飞函安全 · 2026-03-05 20:13:25 发布

你的CLI，还在为人类设计吗？

过去三十年，命令行界面（CLI）的设计哲学围绕着一个假设：使用者是人类。所以我们有了--help，有了彩色输出，有了交互式提示，有了Stack Overflow上无数手把手的教程。

但现在，CLI的"用户画像"正在发生颠覆性的变化——AI代理（Agent）正在成为CLI最活跃的消费者。

它们不需要彩色输出，不需要交互式引导，不需要"对人类友好"的参数缩写。它们需要的是：确定性的输入、机器可读的输出、以及防止自己犯错的安全护栏。

Justin Poehnelt——Google Workspace CLI的构建者——在最近一篇文章中一针见血地指出了这个趋势。他的核心论断是：

人类DX（开发者体验）优化的是"可发现性"；代理DX优化的是"可预测性"。这两者之间的差异，大到你不能指望在一个为人类设计的CLI上打几个补丁了事。

本文将基于他的实践经验，深入探讨：在AI代理为主要消费者的时代，一个CLI到底应该长什么样？

一、原始JSON载荷 > 精心设计的Flag

人类讨厌在终端里手写嵌套JSON。但AI代理恰恰相反——它更喜欢JSON。

传统"人类优先"的CLI设计，会为每个参数创建一个独立的flag：

my-cli spreadsheet create \
  --title "Q1 Budget" \
  --locale "en_US" \
  --timezone "America/Denver" \
  --sheet-title "January" \
  --sheet-type GRID \
  --frozen-rows 1 \
  --frozen-cols 2 \
  --row-count 100 \
  --col-count 10 \
  --hidden false

10个flag，扁平命名空间，无法表达嵌套结构。对人类来说尚可接受，但对AI代理来说，这种设计充满了陷阱：记错flag名、遗漏必填项、无法表达复杂的嵌套对象。

"代理优先"的方式，只需要一个flag——直接传入完整的API载荷：

gws sheets spreadsheets create --json '{
  "properties": {
    "title": "Q1 Budget",
    "locale": "en_US",
    "timeZone": "America/Denver"
  },
  "sheets": [{
    "properties": {
      "title": "January",
      "sheetType": "GRID",
      "gridProperties": {
        "frozenRowCount": 1,
        "frozenColumnCount": 2,
        "rowCount": 100,
        "columnCount": 10
      },
      "hidden": false
    }
  }]
}'

这段JSON直接映射到底层API的Schema，对LLM来说生成起来毫不费力。零翻译损耗。

当然，这并不意味着要抛弃人类友好的flag。正确的做法是：让原始载荷路径成为一等公民，与便利flag并存。比如通过--output json、环境变量OUTPUT_FORMAT=json、或者在stdout非TTY时默认输出NDJSON——让同一个二进制文件同时服务人类和代理。

二、Schema自省取代静态文档

人类通过--help、文档网站和Stack Overflow学习CLI。

AI代理呢？它们通过对话开始时注入的上下文来学习。

这意味着一个根本性的变化：把静态的API文档塞进System Prompt的做法既烧token又容易过时。更好的方式是——让CLI自身成为文档，可在运行时被查询。

Google Workspace CLI的做法是提供一个schema子命令：

gws schema drive.files.list
gws schema sheets.spreadsheets.create

每次调用会返回该API方法的完整签名——参数、请求体、响应类型、所需的OAuth范围——全部以机器可读的JSON格式输出。代理可以在运行时自助获取最新的API定义，而不需要预先塞入（可能已经过时的）文档。

底层原理是利用了Google的Discovery Document，CLI在运行时动态解析$ref引用。CLI本身成为了API接受什么输入的"唯一真相源"——不是六个月前文档网站上的描述，而是此时此刻API真正接受的格式。

这个模式的本质洞察是：代理不需要"学习"你的CLI，它需要在运行时"询问"你的CLI。

三、上下文窗口纪律

API返回的数据量可以非常庞大。一封Gmail邮件的完整JSON可能就会吃掉代理上下文窗口的相当一部分。人类不在乎——大不了翻翻页。但代理的每一个token都是要付费的，而且过多的无关字段会直接稀释它的推理能力。

两个关键机制：

字段掩码（Field Masks）

限制API返回的字段范围：

gws drive files list --params '{"fields": "files(id,name,mimeType)"}'

原本可能返回20个字段的巨大JSON对象，现在只返回三个必要字段。对代理来说，这不是锦上添花，而是生死攸关——上下文窗口有限，每个无用字段都在消耗推理资源。

NDJSON分页（流式处理）

--page-all以NDJSON格式逐页输出，代理可以流式处理每一页，而不需要将整个响应缓冲进内存（和上下文）。

Google Workspace CLI的CONTEXT.md中写道：

“Workspace APIs返回巨大的JSON块。在列出或获取资源时，必须始终使用字段掩码，添加--params '{"fields": "id,name"}'以避免压垮你的上下文窗口。”

这段指导直接写在CLI自带的代理上下文文件里——因为上下文窗口纪律不是代理能自行领悟的，必须被显式声明。

四、输入硬化：防止幻觉造成的灾难

这是整篇文章中最被低估的维度。

人类会打错字。代理会产生幻觉。两者的失败模式完全不同。

人类几乎不可能意外输入../../.ssh——但代理可能因为混淆路径片段而生成这个路径；
代理可能在资源ID中嵌入查询参数（fileId?fields=name）——这种事已经发生过了；
代理可能传入一个预编码的URL字符串，导致双重编码（%2e%2e变成..）——这很常见。

“代理会产生幻觉。请以此为前提来构建。”

CLI必须成为最后一道防线。具体措施包括：

威胁类型	人类的典型错误	代理的典型幻觉	防御方式
文件路径	拼错目录名	生成`../../.ssh`等路径穿越	规范化并沙箱化所有输出路径
控制字符	复制粘贴乱码	生成不可见字符	拒绝ASCII 0x20以下的字符
资源ID	拼错ID	在ID中嵌入查询参数`?fields=`	拒绝包含`?`和`#`的输入
URL编码	几乎不会预编码	经常预编码导致双重编码	拒绝包含`%`的资源名称

核心原则：代理不是可信的操作者。 你不会构建一个信任用户输入的Web API而不做校验，那也不应该构建一个信任代理输入的CLI。

五、发布"代理技能"，而不只是命令

这是一个思维模式的根本转变。

人类通过--help、文档站和搜索引擎学习CLI。代理则通过对话开始时注入的上下文来学习。 这意味着知识的打包方式必须根本性地改变。

Google Workspace CLI随附了100多个SKILL.md文件——带有YAML frontmatter的结构化Markdown，每个API surface一个，外加更高层级的工作流：

---
name: gws-drive-upload
version: 1.0.0
metadata:
  openclaw:
    requires:
      bins: ["gws"]
---

技能文件可以编码那些从--help中并不显而易见的、代理专属的指导规则：

“对所有变更操作始终使用--dry-run”
“在执行写入/删除命令之前，始终先向用户确认”
“对每个list调用都添加--fields”

这些规则之所以必要，是因为代理没有直觉——它们需要不变量（invariants）被显式声明出来。一个技能文件的成本，远低于一次幻觉造成的损失。

六、多接口适配：MCP、扩展、环境变量

人类的接口是交互式终端。代理的接口因框架而异。一个设计良好的CLI应该能从同一个二进制文件服务多种代理接口：

         ┌─────────────────┐
         │  Discovery Doc  │
         │  (唯一真相源)     │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │   Core Binary   │
         │     (gws)       │
         └─┬────┬────┬───┬─┘
           │    │    │   │
     ┌─────┘    │    │   └─────┐
     ▼          ▼    ▼         ▼
  ┌──────┐ ┌──────┐ ┌───────┐ ┌──────┐
  │ CLI  │ │ MCP  │ │Gemini │ │ Env  │
  │(人类)│ │stdio │ │扩展   │ │ Vars │
  └──────┘ └──────┘ └───────┘ └──────┘

MCP（Model Context Protocol）：通过gws mcp --services drive,gmail将所有命令暴露为基于stdio的JSON-RPC工具。代理获得类型化的、结构化的调用方式，无需处理shell转义；
Gemini CLI Extension：直接将CLI安装为代理的原生能力。CLI不再是代理"调用"的东西，而是代理"自身拥有"的能力；
环境变量注入：代理做OAuth不方便也不应该做。通过GOOGLE_WORKSPACE_CLI_TOKEN和GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE环境变量注入凭证——这是无人值守场景下唯一可行的认证路径。