aidc CLI

为什么智能体首选 CLI

aidc 是同一套 API 外面的命令行，业务逻辑都在服务端，CLI 只管参数、文件和输出。它有四个习惯，让人和智能体都用得放心：

• 每条命令都能输出 JSON：标准输出不是终端时自动开启，也可以手动加 --json。
• 脚本命令不等输入：终端里的裸命令 aidc 会进入交互界面，aidc login 也会提示输入。脚本要写出子命令。
• 退出码固定：脚本靠它决定下一步，不用去解析文字。
• 支持预演的命令先演一遍：--dry-run、--validate-only、--preview。

多数远程命令要凭证。免登录命令包括 login、logout、update、help 和 --version。本地命令也有例外。streams pipe 可用 AIDC_PUBLISH_KEY，connect send 可用 AIDC_AGENT_KEY。开发者凭证先读 AIDC_API_KEY，再读 ~/.aidc/config.json。命名空间缺省是当前组织，-n cell-… 可指定。用 aidc whoami 核对身份与组织。

在示例工厂上跑一遍

先从读开始。ontology 给全貌，objects 按条件取一页，aggregate 聚合，sql 直接写 SELECT。条件与聚合的写法和 SDK 一致，只是变成了 JSON 参数。

aidc semantic ontology --json                      # 全貌：对象类型（主键、链接）、Action Type、Interface
aidc semantic object-types workOrder --json        # 一个对象类型的属性与链接

aidc semantic objects workOrder --where '{"status":"running","lineCode":"L01"}' --order-by dueAt:asc --select workOrderNo,dueAt,goodQty --page-size 20 --json
aidc semantic object workOrder WO-1001 --json
aidc semantic links workOrder WO-1001 order --json         # 沿关系：这张工单属于哪张销售订单
aidc semantic edits-history workOrder --pk WO-1001 --json  # 谁改过什么

aidc semantic aggregate workOrder --where '{"status":"done"}' --select '{"$count":"unordered","goodQty:sum":"desc"}' --group-by '{"lineCode":"exact"}' --json
aidc semantic sql 'SELECT status, count(*) FROM "workOrder" GROUP BY 1' --csv

翻页也很简单：输出里有 nextPageToken 时，把它交给 --page-token，直到不再出现。

另外两条值得记住。复杂的对象集（并、交、差、沿关系）可以写成一个 JSON 文件，交给 aidc semantic object-set，加 --aggregate 就直接对它聚合。sql 走只读的 Semantic 数据库：一条 SELECT，最多 10,000 行、20 秒，表名是对象类型的 API name，名字里有大写字母要加双引号。

改的命令一律先校验。--validate-only 不写任何东西；校验不通过时退出码是 2，脚本里加了 set -e 就会停在这一步。通过了，再去掉它，想看改了什么就加 --return-edits。批量用 apply-batch，参数写成一个数组文件，普通批量一次最多 20 个，放在一个事务里。配置 writeback webhook 的 Action 一次只能提交一个请求。

aidc semantic apply hold-work-order --param workOrder=WO-1001 --param reason="来料不良" --validate-only
aidc semantic apply hold-work-order --param workOrder=WO-1001 --param reason="来料不良" --return-edits

把它们串起来，就是一个可以放心重试的改数据脚本：

1. 读现状

   object 取出对象，确认它还是你以为的样子。

2. 只校验

   apply --validate-only，退出码不是 0 就停。

3. 执行

   去掉校验开关，加 --return-edits，把返回存下来。

4. 复查

   edits-history 看这次改动是否记在账上。

输出与退出码

JSON 模式下，成功输出这条命令的数据对象，失败输出 { ok: false, error: { code, message, status, details, requestId } }。进度提示一律写在 stderr，所以 stdout 永远是干净的 JSON，可以直接交给别的程序。

这些退出码和第 1 课讲的 HTTP 状态一一对应：400 与 422 是 2，401 是 3，403 是 4，404 是 5，409 是 6，429 是 7，5xx 和网络错误是 8。所以在 REST 里学到的错误规则，在命令行里原样适用。

这张表放进脚本，就是一个 case：

aidc semantic apply hold-work-order --param workOrder=WO-1001 --validate-only --json > check.json
case $? in
  0)   aidc semantic apply hold-work-order --param workOrder=WO-1001 --return-edits --json ;;
  2)   echo "校验没通过，先改参数" >&2; exit 2 ;;        # 不重试
  7|8) echo "稍后再试" >&2; exit 1 ;;                   # 退避后重试
  *)   exit 1 ;;
esac

有一个坑很常见：把所有非零退出码都当成「再试一次」。2、3、4、5 重试一万次结果也一样，只有 7 和 8 才值得退避重试。