为什么 CLI 对 Agent 重要

Agent 访问外部能力有三种方式：API、MCP、终端命令。CLI 的独特优势在于——几乎所有通用 Agent（Codex、Claude Code、OpenClaw 等）都自带 Bash 工具，无需服务方搭建 MCP server。它把鉴权、参数组装、分页、错误处理封装进命令，Agent 只需读一份精简的命令说明就能按需决策。

但使用者形态变了：过去是终端前的开发者，现在是「读取输出 → 做决策 → 执行下一条命令」的 Agent。如何同时满足两类用户，是 IT中华 认为设计上最值得思考的课题。

一、编程语言：单二进制是底线

Agent 运行环境不可预测，可能是本地、Docker、远程 Linux。三个硬指标：

• 单文件无运行时依赖：下载即跑，不假设装了 Node/Python
• 可交叉编译：覆盖 macOS/Linux/Windows × amd64/arm64
• 启动快：Agent 高频调用，静态语言首选

IT中华 推荐选 Go + Cobra，CGO_ENABLED=0 后零依赖，分发用 GoReleaser 一套配置同时产出 npm/Homebrew/GitHub Release。

二、登录授权：设备码流程 + 分阶段轮询

API Key 方式风险太大（长期有效、全量权限、明文存储）。采用 OAuth 2.0 Device Authorization Grant，拿到的是短期、可刷新、可精细授权、可吊销的 access token。

关键设计：分阶段轮询。Agent 是「执行 → 拿结果 → 决策」循环，不能在同一次调用里既输出链接又轮询。拆成两步：

# 第一阶段：立即返回 URL + next_action
linkai auth login --no-wait --json

# 第二阶段：带超时的轮询
linkai auth login --device-code <code> --wait 60 --json

--wait 参数区分两类用户：不传走人类交互式登录；传了切到 Agent 有界轮询路径。

三、命令与参数：结构化优先

• --json 全局参数：约定 Agent 总是加 --json，拿到稳定可解析的结构化数据
• 流式自动切换：终端默认流式，管道/重定向（Agent 场景）默认非流式，--json 时强制非流式
• --dry-run 试运行：破坏性命令支持预演，只打印将发送的请求
• 输出分流：结果走 stdout，过程信息走 stderr，Agent 只需处理 stdout
• 退出码语义：0成功 / 1一般错误 / 2参数错误 / 3认证权限 / 4网络异常。权限不足时给出授权命令提示，Agent 据此重新拉起授权而非盲目重试

四、Skill 配套：写给 Agent 的说明书

反复 --help 试错成本太高，需要一份 Skill 文件：

skills/linkai-cli/
├── SKILL.md          # 主入口：全局说明 + 决策流程
└── references/       # 按模块拆分：auth / install / admin

原则：单目录扁平结构，不让每个子模块都装成独立 Skill（会增加上下文消耗）。通过 go:embed 打包进二进制，版本严格锁定。

五、分发与更新：一句话装好

理想状态是给 Agent 一句话就能自己装好。多渠道分发：

版本更新两层：被动通知（启动时拉版本号，结束时 stderr 提示）+ 主动更新（update 命令自动检测安装方式并升级）。

六、安全防护：四道防线

1. 权限最小化：scope 用 资源:动作 格式（如 app:read），高危操作须显式授权
2. Token 存储：macOS 存钥匙串，其他平台文件权限 0600，用可撤销的 opaque token
3. 设备绑定：每请求携带设备 ID，降低盗用风险
4. 危险字符过滤：输入侧拒绝 Bidi 覆盖、零宽字符、ANSI 转义等

IT中华 · www.itzh.vip · 技术日记