2026 年，每一条 CLI 都会被某个 Agent 在某个时刻调用。大多数 CLI 还没准备好。

交互式提示符、彩色输出、终端 UI——这些人类觉得理所当然的设计，遇上自动化 Agent 就会全部崩溃。但如果为了 Agent 去掉这些，又会让人类的使用体验变差。

Google Cloud 的解法是：不需要在两个受众之间做选择。一套 CLI，同时服务两者。

核心理念：解耦数据与呈现

CLI 的内部逻辑应该是一个引擎，输出原始结构化数据。终端 UI 只是这个引擎的其中一个"客户端"。

# 人类得到交互式 TUI a2acli watch --task abc123 # Agent 得到结构化 NDJSON a2acli watch --task abc123 --no-tui

同一个命令，两种输出模式，不需要维护两套代码库。

每个命令都要有 JSON 输出

这是最基本的设计要求：

# 任何产生数据的命令，都要支持 --json 或 --no-tui
a2acli get --task abc123 --json

如果 Agent 解析不了你的输出，你的 CLI 在 Agent 世界里就不存在。

自动检测受众

不要让用户自己选模式。自动检测：

  • NO_COLOR 环境变量已设置 → 跳过交互元素
  • $NO_TUI 环境变量已设置 → 跳过 TUI
  • stdout 被 pipe → 非交互模式

保护 Agent 的上下文窗口

Agent 的 token 限制是硬的。默认行为应该：

  • 主动截断超大数据块
  • 掩码敏感信息（API key 等）
  • 不要把原始 payload 直接吐给 Agent

如果 Agent 真的需要原始数据，用 --full 或 --verbose 显式 opt-in。

出错要给 Hint，不要只报错误

Error: database not initialized
Hint: run 'a2acli init' to create the local database

Agent 会解析 Hint 自我修正。人类也省去了翻文档的麻烦。

确定性退出码

退出码含义
0成功
1通用错误
2参数错误
3连接/认证失败

如果命令本身运行成功但操作失败却返回 0，会打破所有调用它的自动化流程。

配置与命名环境

遵循 XDG 规范：~/.config/app/config.yaml

支持命名环境：

# ~/.config/a2acli/config.yaml
default_env: "local"
envs:
  local:
    service_url: "http://127.0.0.1:9001"
  staging:
    service_url: "https://staging-agent.internal.corp"
    token: "my-staging-auth-token"
  prod:
    service_url: "https://agent.example.com"

# 一个 --env flag 切换全部上下文
a2acli send "Generate report" --env staging

Agent orchestrator 可以直接 --env prod 而不需要知道 URL 或 token。

AGENTS.md：给 Agent 的显式说明书

不要假设 LLM 天生知道怎么用你的工具——显式教它。

在仓库根目录放 AGENTS.md，内容包括：

  • 调用规则
  • 默认工作流
  • 架构标准

复杂命令放 skills/ 目录，包含 Agent 可以直接 ingest 的专用 prompt 文件。

语义色彩系统

颜色要有功能目的，不要为了好看。

语义色标（意义 > 原始颜色名）：

Token用途
Accent标题、分组标签
Command命令名、flag
Pass成功状态
Warn警告、进行中状态
Fail错误状态
Muted元数据、默认值
ID唯一标识符（task ID 等）

原则：颜色用于状态，描述文字保持无色；用留白代替颜色表达层次结构。

命令设计的可预测性

  • 标准化简写：如果 -o 在某个命令里是 --out-dir，就不能在另一个命令里表示 --output。不一致会打断 Agent 的推理。
  • 位置参数 vs Flag：必填核心实体用位置参数（a2acli get <task-id>），可选修饰用 flag。
  • 安全默认值：默认行为永远是最安全、最常见的路径。危险操作要显式 flag 确认。

命令入口设计

帮助信息是 Agent 和人类共同的起点：

Task Management: send Send a message to start or continue a task (start here) watch Subscribe to live updates for a running task get Retrieve the current state of a task Discovery: describe Inspect an agent's identity, skills, and capabilities
  • 按功能分组，不要按字母序
  • 入口点显式标注（(start here)）
  • 每个命令填充三个字段：Short（5-10 词）、Long（完整说明）、Example（3-5 个可直接复制的例子）

例子比描述重要。开发者会先复制粘贴，Agent 会从例子推断 flag 模式。