面向 Agent 的 CLI / Skill 设计指南

--help 给人，schema 给机器，两者分开做

Agent 选参靠 schema，不靠训练记忆。手写文档一定会和真实 CLI 漂移。

dws 是唯一做到的：dws schema 分四层渐进查询（产品概览 → 产品 → 分组 → leaf），leaf 直接给出每个参数的 type / required / enum / constraints / examples。更关键的是它划定了事实源边界：

# 命令是否存在、当前接受哪些 flag
dws <path> --help
# Agent 选参 / required / 约束 / 风险
dws schema "calendar event create" --compact
# 三者冲突 = 「契约漂移」→ 上报，
# 不许拼接猜测、不许选更宽松的那个

# SKILL.md 开头被迫写：
⚠️ 构造命令前必须查阅完整参数
   不要凭记忆猜测 flag 名

# 这条警告存在本身，就是
# 「没有机器可读契约」的病征

→ 手写文档的代价，看 a1 留下的伤疤就够了：--run 现已必填、run/retry 已废弃、没有 --all（旧版 SKILL.md 拼写错误）。这些都是「文档跟不上代码」的化石。

能被 CLI 拒绝的才是规则，写在 Markdown 里的只是建议

危险操作的拦截必须做进代码；文档拦不住一个「你确定要执行吗」都不问的 Agent。

# SKILL.md「安全红线」：
❌ 禁止 --env prod
❌ 禁止 mw config set ...

# 全靠 Agent 自觉。它完全
# 可以无视，CLI 层不拦。

# schema 里每个工具都标：
"effect": "destructive",
"confirmation": "user_required"

# → 必须先让用户确认，再加 --yes
# CLI 层强制，不是靠提示词

还有第三种更聪明的解法（dms）：不自己造门禁，而是把风险导流到已有的审批链。生产环境的 DML/DDL 一律走平台工单：

order init --order-type change → 编辑 → submit → submit-approval → execute # 审批通过后才执行

→ 设计顺序应该是：先把危险操作的门禁做进 CLI（或导流到审批系统），再谈能力覆盖多少。

隐式上下文对人友好，对 Agent 是坑；要么不做，要么可查可覆盖

「有全局状态，但查不到、也盖不掉」是最差的形态。

这是样本里唯一的真分歧，两种可接受形态：

mw mq topic list \
   --env daily --unit ant-daily

# 且禁止 mw config set 改全局，
# 逼每条命令自带环境，意图零歧义

a1 link status -f json # 执行前先确认绑定
a1 repo mr list          # 用绑定的仓库
a1 repo mr list --repo x # 单次覆盖

→ 核心不是「有没有隐式状态」，而是「Agent 能不能 看见它、并临时推翻它」。a1 的 link status -f json 就是把不可见的状态变可见。

输出必须有机器通道，并且 ID 能被直接取出

让 Agent 从人类表格里抠 ID，等于白送解析错误。

a1 的三档输出是范本：

→ -q 这档最容易被忽略，但对 Agent 最关键：它拼下一条命令通常只需要一个 ID。list 类命令还应统一分页参数（--page-size / --offset），避免每个命令各造一套。

凡「重复到某条件」的逻辑，下沉到 CLI 或脚本，别让 Agent 写循环

Agent 每轮循环 = 一次模型调用。轮询这种事必须由工具承担。

a1 app pipeline status --pipeline-id X \
   --wait-until-settled      # 一条命令等到结束
a1 build job log X --step Y --follow
a1 build job log X --step Y \
   --offset $NEXT --limit 500

# scripts/ 下 40 个脚本，封装
# 翻页/轮询/批量导入/创建轮询
python scripts/aitable_import_via_task.py
# SKILL.md 明令：脚本优先于手写多步

低频变更的元数据落盘 + 带时间戳，把「调 API」降级成「读文件」

表结构这类东西，读本地文件比调接口快一个量级。Agent 只需要一个能自己判断新鲜度的信号。

dms 把数据字典 sync 到本地，每个 JSON 带 synced_at：

~/dms-alibaba/db-groups/<group>/databases/<db>/
├── database.json      # 连接信息 + synced_at
├── _index.json        # 表清单 + synced_at
└── tables/<t>.json     # 字段+索引 + synced_at
# 规则：本地优先；读前看 synced_at，过期再 sync

→ pensieve 是同一思想的极致版：整个知识库就是一个 Git 仓库，「编译一次、持续维护」，查询时读文件而非重新推导原始文档。

故障自愈路径要压成「单命令可判定」，并授权 Agent 自行修复

别让 Agent 面对「先检查安装、再检查登录、再检查配置」的多步判断树——压成一条命令 + 一张处置表。

dms-alibaba auth  # 同时验证安装 + 凭证

a1 faq grep "关键词"   # 内置文档可搜
a1 faq search "..."    # 语义搜索
a1 feedback "标题" ...  # 统一反馈通道

# 承认 Agent 用 CLI 一定会踩坑，
# 就得留一条把坑送回团队的管道

→ dms 还写明：「Agent 有权直接执行安装和修复命令，无需展示给用户手动操作」，并给了无浏览器环境的旁路（直接写 credentials.json）。自愈要连「授权」一起给足。

消歧规则的条数，是你 CLI 领域模型混乱度的体温计

每多一条「⚠️ 不是 XXX」，就说明命令命名多欠一笔债。

a1 里至少 4 处强消歧，dws 有决策树 + 5 条「关键区分」+ 独立的 intent-guide.md：

• a1：交付任务 devix task ≠ 项目工作项 workitem
• a1：pages 站点配置 ≠ 部署 pages 内容（走 ci）
• a1：cr submit --pipeline-id ≠ submit-integration
• a1：pkg deploy-cr ≠ artifact mvn deploy ≠ pkg deploy-intg（三个发布路径）