Developer命令行 aidc

常用流程

这一页按任务列出完整步骤。每个流程先说做成什么，再列编号步骤。能看到输出的步骤，都给出了输出。示例数据只用 Demo Company（组织，命名空间 cell-demo）。

说明

前提：已登录（aidc login）。每个流程开头写了需要的角色。

流程一览

下面是九个流程。每个流程都能单独照做。

从零发布一个应用
查对象与聚合
用 Action 改数据
接一条数据流
让智能体在分支上改本体
按时自动检查并发邮件
看这个月花了多少
在 CI 和智能体里用
和智能体在终端里一起做

从零发布一个应用

用工作流模板做一个报表问答应用。应用先进入 test 通道，测过后再发布到 production。

前提：第 1 步到第 3 步，member 角色就能做。第 4 步起要 developer。

生成应用目录

$ aidc app init ask-report --template workflow --title "报表问答"
已生成 /home/demo/ask-report（Skill 在 skills/ask-report/SKILL.md，先把 description 改成这个应用真正解决的事）
下一步：aidc app dev /home/demo/ask-report
$

目录里有清单、一条 Skill 和一个界面。改 skills/ask-report/SKILL.md 里的 description，写上应用解决的问题。参数见 aidc app init。

在本机预览。

本机预览

$ aidc app dev ask-report
本地预览：http://localhost:5173（Ctrl-C 结束）
→ GET /developer/sdk/v1/ui.css
→ GET /developer/sdk/v1/aidc.js
$

预览只在这台电脑上可以打开。终端为代理到服务端的请求打印一行。测完按 Ctrl-C 结束。详见 aidc app dev。

校验应用。

校验应用

$ aidc app check ask-report
✓ ask-report：5 个文件，6.0 KB，digest 84d5ed69934c5bc2
$

校验规则和服务端相同，上传前就能发现问题。详见 aidc app check。

放进 test 通道。

部署到 test

$ aidc app deploy ask-report --notes "首版"
新版本 v0.1.0（构建 #1）已进入 test 通道
  Developer 预览：https://www.ai-dc.ai/developer/cell-demo/apps/ask-report
测好后发布：aidc app publish ask-report
$

改了内容要先升 version。内容不变时，重复部署不产生新版本。详见 aidc app deploy。

调一个 API，只预演。
```
aidc app call ask-report run --channel test --param question="本周有没有异常" --preview --json
```
--preview 时，读、计算和 AI 分析照常运行，写入只返回计划。返回结构是 {"api":"run","kind":"run","preview":true,"run":{…},"created":true}。run 包含 id、app、version、channel、mode、trigger、status、input、steps、output 等字段。重复幂等调用时，created 为 false。去掉 --preview 就是正式运行。用 get_run 看每一步的结果。详见 aidc app call。
发布到 production。

发布

$ aidc app publish ask-report --notes "首版"
发布：production 从 v— 切到 v0.1.0
  Nexus：https://www.ai-dc.ai/nexus/cell-demo/apps/ask-report
$

只能发布进过 test 通道的版本。发布的是第 4 步测过的同一个版本，不重新打包。详见 aidc app publish 和快速开始。

查对象与聚合

用对象查询、聚合和 SQL 读出付费大客户的座位数。三种写法读的是同一份数据。

前提：developer 角色。

按条件查对象。

查对象

$ aidc semantic objects customer --where '{"stage":"付费","seats":{"$gt":30}}' --order-by seats:desc --select name,seats
2 / 2 个
__primaryKey | name | seats
--- | --- | ---
cell-demo-a | Demo Customer A | 48
cell-demo-b | Demo Customer B | 36
$

结果按座位数从多到少排。第一列是主键。筛选条件的运算符见读写对象。详见 aidc semantic objects。

合计座位数。

座位合计

$ aidc semantic aggregate customer --select '{"$count":"unordered","seats:sum":"desc"}' --where '{"stage":"付费","seats":{"$gt":30}}'
{
  "$count": 2,
  "seats": {
    "sum": 84
  }
}
$

两个客户，座位数合计 84。分组统计的写法见 aidc semantic aggregate。

用 SQL 查同样的结果。

执行 SQL

$ aidc semantic sql 'SELECT name, seats FROM customer WHERE stage = $1 AND seats > 30 ORDER BY seats DESC' --param 付费
name	seats
Demo Customer A	48
Demo Customer B	36
（2 行 · 14 ms · 角色 reader）
$

SQL 只能读。表名是 Object Type 的 API 名，列名是属性的 API 名。详见 SQL 与数据库和 aidc semantic sql。

用 Action 改数据

用 Action 把 Demo Customer A 的座位数改成 60。顺序是：先校验，再执行，最后看编辑记录。

前提：developer 角色。

重要

执行 Action 会改数据，并留下记录。智能体不能直接改数据。直接写入会返回 403（退出码 4）。

只校验，不执行。

只校验

$ aidc semantic apply adjust-seats --param customer=cell-demo-a --param seats=60 --validate-only
✓ 校验通过（没有执行）
$

校验不改数据。参数不合格时，命令列出原因，退出码是 2。详见 aidc semantic apply。

执行，并看改动数。

执行改数据

$ aidc semantic apply adjust-seats --param customer=cell-demo-a --param seats=60 --return-edits
✓ 已执行 adjust-seats（ri.actions.aidc.action.…）
  改动：新建 0、修改 1、删除 0、建链接 0、删链接 0
$

第二行是这次执行的改动数。

看编辑记录。

编辑记录

$ aidc semantic edits-history customer --pk cell-demo-a
2026-10-08 14:22:05  modifyEdit  {"customerId":"cell-demo-a"}  account:cm2k9f3a70001qz7d5w1b8x4n  ri.actions.aidc.action.…
$

每行依次是时间、编辑种类、主键、操作人和操作号。详见 aidc semantic edits-history 和读写对象。

接一条数据流

把订单数据接进本体（Ontology）。数据流收数据，数据源把数据流接到 Object Type production.order_line。

前提：developer 角色。发布端只用发布 Key，不用登录。

建数据流。

建数据流

$ aidc semantic streams create orders --title 在手订单 --key order_no --field order_no:string:合同号 --field qty:number:数量 --field due:datetime:交期
新建数据流 cell-demo/orders（3 个字段，主键 order_no）
下一步：aidc semantic streams key cell-demo/orders --label "装在哪"
$

数据流只收声明过的字段。详见 aidc semantic streams create 和数据接入。

签一把发布 Key。

签发布 Key

$ aidc semantic streams key orders --label "工厂服务器 · 订单发布端"
发布 Key（只显示这一次，只能发布 cell-demo/orders）：
  aidc-pk-…
装到发布端：AIDC_PUBLISH_KEY=<上面这把> aidc semantic streams pipe cell-demo/orders -- <适配器命令>
$

发布 Key 只显示这一次。丢了就吊销旧 Key，再签一把新的。详见 aidc semantic streams key。

运行发布端。适配器是一个常驻程序，每行打印一个 JSON。下面的适配器每 30 秒读一次数据源。

# orders_adapter.py
import json, time

while True:
    rows = read_orders()  # 换成读数据源的代码
    print(json.dumps({"rows": rows}), flush=True)
    print(json.dumps({"status": "ok"}), flush=True)
    time.sleep(30)

运行发布端

$ AIDC_PUBLISH_KEY=aidc-pk-… aidc semantic streams pipe cell-demo/orders -- python3 orders_adapter.py
发布端启动：cell-demo/orders（主键 order_no）← python3 orders_adapter.py
2026-10-08T14:03:12 发布 → seq 129（2 条，3 行，182ms）
$

发布端只发变化的行，并定时发心跳。这个命令不会自己结束，按 Ctrl-C 停止。详见 aidc semantic streams pipe。

把数据流接到 Object Type。

接数据源

$ aidc semantic datasource set production.order_line --stream orders --map orderLineKey=order_no --map qty=qty
接上数据源 production.order_line ← orders（写进了类型定义），首次同步：变化 3 个
$

--map 写成「属性=列」。主键属性必须映射。详见 aidc semantic datasource set。

看数据源的状态。

看数据源

$ aidc semantic datasource list
● production.order_line        ← orders  mirror  同步到 seq 130
$

● 表示数据源正常。同步到 seq 130 是同步进度。mirror 模式下，数据流里没有了的行，对象标记为「源头已消失」。详见 aidc semantic datasource list。

让智能体在分支上改本体

智能体发现本体缺一个部门 Object Type。它在分支上加这个类型，校验通过后开提案，交给人审核。

前提：developer 角色。智能体用开发者 Key 调 CLI。

重要

智能体不能直接改 main。直接写入 main 会返回 409（退出码 6）。设了 AIDC_AGENT_ID 后，作者记为这个智能体。

开分支。

开分支

$ AIDC_AGENT_ID=ops-agent aidc semantic branch create add-department --description "加部门对象类型"
已建分支 add-department（基线 v12，作者 agent:ops-agent）
$

分支基于当前的语义版本。main 不变。详见 aidc semantic branch create。

试跑定义。

试跑

$ aidc semantic branch modify add-department ./ontology --dry-run
（dry-run）分支 add-department 试跑：校验 VALID
  …
  ✓ reference_closure
  …
  ✓ api_names
$

./ontology 是定义文件的目录。定义的写法见定义本体。试跑只校验，不写入。

写入分支。

写入分支

$ aidc semantic branch modify add-department ./ontology
✓ 分支 add-department 已改到 v1：校验 VALID
  …
  ✓ reference_closure
  …
$

写入后，分支版本加一。--expected-version 可以防止覆盖别人的改动。详见 aidc semantic branch modify。

校验合并条件。

校验分支

$ aidc semantic branch validate add-department
校验 VALID
  …
  ✓ reference_closure
  …
$

结果是 VALID 时，退出码是 0。否则退出码是 2。详见 aidc semantic branch validate。

开提案。

开提案

$ AIDC_AGENT_ID=ops-agent aidc semantic branch propose add-department --title "加部门对象类型" --trigger "问「各部门本月成本」答不出"
✓ 已开提案 cm2kb7q4e0004qz7d5w1b8x4n：加部门对象类型
  … department  created
审核：https://www.ai-dc.ai/developer/cell-demo/ontology/proposals/cm2kb7q4e0004qz7d5w1b8x4n
组织的审批策略是 review：提案要本组织开发者在网页上逐项批准（破坏性改动要输入实体名确认），合并后才进 main。
$

每项前的 … 表示这一项还没批准。把审核地址交给人。改动按组织的审批策略进入 main，策略见定义本体。详见 aidc semantic branch propose。

按时自动检查并发邮件

建一个组织级的自动化。它每个工作日 09:30 检查逾期任务，给负责人发邮件。数据变化时触发的工作流，见自动化。

前提：建和运行要 developer。查看运行记录，member 也能用。

写定义文件 任务逾期.json。

{
  "apiName": "dev-task-overdue",
  "displayName": "任务逾期",
  "status": "active",
  "condition": {
    "type": "runOnAllObjects",
    "every": "1d",
    "at": "09:30",
    "weekdays": [1, 2, 3, 4, 5],
    "objectSet": {
      "type": "filter",
      "objectSet": { "type": "base", "objectType": "devTask" },
      "where": {
        "type": "and",
        "value": [
          { "type": "in", "field": "status", "value": ["待接受", "进行中", "阻塞"] },
          { "type": "relativeDateRange", "field": "dueDate", "relativeEndTime": { "value": 0, "timeUnit": "DAYS" }, "timeZoneId": "Asia/Shanghai" }
        ]
      }
    }
  },
  "effects": [
    {
      "type": "notification",
      "channel": "email",
      "executionMode": { "type": "perObject" },
      "recipients": [{ "type": "propertyBacked", "property": "assigneeAccountId" }],
      "title": "任务逾期：{{title}}",
      "template": "{{#objects}}任务「{{title}}」截止 {{dueDate}}，现在是「{{status}}」。{{/objects}}"
    }
  ]
}

效果只接受 action、function 和邮件通知。详见 aidc semantic automations upsert。

预演，不保存。

预演自动化

$ aidc semantic automations upsert --ontology cell-demo --file 任务逾期.json --dry-run
预演：任务逾期（看 devTask）
  ri.aidc.automate.cell-demo.automation.dev-task-overdue
$

预演检查定义，并看对象集，但不保存。

保存。

aidc semantic automations upsert --ontology cell-demo --file 任务逾期.json

保存后，系统按时间表查询当前符合条件的对象。

立即运行一次。

立即运行

$ aidc semantic automations run ri.aidc.automate.cell-demo.automation.dev-task-overdue
已开跑：{…}
$

{…} 是这次运行的 JSON，打印在一行里。详见 aidc semantic automations run。

看运行记录。

运行记录

$ aidc semantic automations runs --ontology cell-demo --automation dev-task-overdue
2026-10-08T06:20:41.000Z succeeded  manual 任务逾期 · 3 个对象 · notification:succeeded
2026-10-08T01:30:00.000Z succeeded  schedule 任务逾期 · 3 个对象 · notification:succeeded
$

最新的在前。第三列是触发类型。manual 表示手动运行。schedule 表示按时间表查询当前对象集。详见 aidc semantic automations runs。

看这个月花了多少

看本月花费，导出明细，再估算下个月的费用。

前提：summary 和 records 要 developer。estimate 登录即可用。金额是模型厂商的美元标价，不是发票。

看本月汇总。

看花费

$ aidc semantic usage summary --month 2026-10
cell-demo · 2026-10（UTC）· 美元标价 · 截至 2026-10-08 14:00 UTC
今日 $0.2100 · 本月 $1.84（预测月底 $7.10，日均 $0.0614） · 累计 $5.12（自 2026-08-01）
本月 468 次 · 612K tokens
按应用（本月）
  cell-demo/ask-report                 $1.61   87.5%  312 次 · 540K tokens
  cell-demo/order-desk               $0.2300   12.5%  156 次 · 72K tokens
按模型（本月）
  gpt-6-luna                     $1.61  312 次 · 540K tokens
…
$

汇总按应用、开发者 Key、模型和天拆开，并给出月底预测。用 --budget 给一个预算，就能看到用了多少。详见 aidc semantic usage summary 和用量与账单。

导出本月的明细。

导出明细

$ aidc semantic usage records --app ask-report --month 2026-10 --all --csv > 10月明细.csv
$ head -1 10月明细.csv
at,lane,app,key,model,promptTokens,completionTokens,totalTokens,audioSeconds,costUsd
$

CSV 的每一行是一次调用。没有价格的行，费用列留空。详见 aidc semantic usage records。

估算下个月的费用。

估算

$ aidc semantic usage estimate -m deepseek-flash --calls 200 --input 1500 --cached 1000 --output 300 --budget 20
deepseek-flash           每次 $… · 每天 $… · 每月 $…
合计：每天 $… · 每月 $…（一个月按 … 天）
预算 $20.00 / 月：放得下（…%）
$

… 代替的是按现行价目算出的数字。估算只计算，不改变账单。超出预算时，第三行显示「超了」。详见 aidc semantic usage estimate。

在 CI 和智能体里用

用环境变量提供开发者 Key。读取 JSON 输出。按退出码决定下一步。写操作先预演。

前提：部署要 developer 角色。Key 从 CI 的密钥库取，不要写进仓库。

用 Key 登录。在 CI 里设环境变量，不运行 aidc login。
```
export AIDC_API_KEY="$AIDC_DEVELOPER_KEY"   # 从 CI 的密钥库取
```
在一台机器上，用 --with-key 把 Key 存到本机：

保存 Key

$ aidc login --with-key < key.txt
已登录：zhang.san · Demo Company（cell-demo）· developer
$

AIDC_API_KEY 优先于保存的 Key。详见在 CI 和智能体里用。

确认身份，取出组织编号。

确认身份

$ aidc whoami --json | jq -r .company.cellId
cell-demo
$

aidc whoami 的退出码是 3 时，表示未登录或 Key 无效。

校验应用，取 JSON 结果。

校验应用

$ aidc app check ./ask-report --json
{
  "ok": true,
  "slug": "ask-report",
  "namespace": null,
  "digest": "84d5ed69934c5bc291b3a76a14db9bca9c35c753686cf1262acad2a44429fd1f",
  "files": 5,
  "bytes": 6173,
  "warnings": []
}
$

warnings 是空数组时，没有成本告警。

先预演部署。

预演部署

$ aidc app deploy ./ask-report --dry-run
（dry-run）将新建版本 digest 84d5ed69934c5bc2，5 个文件；test 地址 https://www.ai-dc.ai/developer/cell-demo/apps/ask-report
$

--dry-run 只校验和计算，不创建版本。加 --json 时输出 JSON。

部署，并按退出码分支。

aidc app deploy ./ask-report --notes "CI 构建" --json
case $? in
  0) echo "已进入 test 通道" ;;
  3) echo "未登录：请人运行 aidc login" ;;
  6) echo "版本号已用于别的内容：升 version 再部署" ;;
  7) echo "额度用完或请求太频繁：停下来告诉人" ;;
  8) echo "上游或网络故障：稍后重试" ;;
  *) echo "读 error.message 再决定" ;;
esac

退出码的完整含义见 CLI 概览。智能体按退出码决定下一步，不解析中文提示。

带幂等键调用 run。重试时用同一个键。
```
aidc app call ask-report run --channel test --param question="本周有没有异常" --idempotency-key ci-20261008-0001 --json
```
键长 8 到 128 个字符。第一个字符是字母或数字，其余是字母、数字或 _ . : -。详见 aidc app call。
标明智能体身份。智能体用开发者 Key 调 CLI 时，设置这一项。
```
export AIDC_AGENT_ID=ops-agent
```
作者记为这个智能体。建本体只能进分支、开提案，由人审核。智能体的完整接入步骤见智能体接入。

和智能体在终端里一起做

用 aidc chat -p 跑一轮对话。它不进交互界面，回答直接写到标准输出。

前提：已登录即可。

重要

给了提示文字，aidc chat -p 就不读管道。要把文件内容交给它，先把要求和内容拼在一起。-p 缺省拒绝智能体用工具，加 --yes 才自动允许。

问一句。

跑一轮

$ aidc chat -p "用一句话说明 Action 是什么" --runtime engine
Action 是 Semantic 里改数据的唯一方式：每次执行都带参数校验、权限检查和留痕。
$

回答边生成边打出。工具调用另起一行，以 · 开头，打到标准错误输出。未指定 --runtime 时，优先使用上次保存且仍可用的运行时。否则选择第一个可用的运行时，最后使用 Engine。详见不进界面：aidc chat -p。

取出 stopReason。

取状态

$ aidc chat -p "用一句话说明 Action 是什么" --runtime engine --json | jq -r .stopReason
end_turn
$

退出码 0 不等于回答完整。max_tokens 表示回答被截断。refusal 表示模型拒绝回答。

把文件内容交给它。
```
(echo "写一段提交说明"; git diff) | aidc chat -p --runtime engine
```
没有写提示文字，aidc 就读标准输入。要求写在前面，内容接在后面。git diff | aidc chat -p "写一段提交说明" 不读 git diff。

下一步

交互界面：进入界面，和智能体对话，确认工具调用。
CLI 概览：安装、登录、输出和退出码。
参考 · 应用与界面：应用的命令、参数和输出。
参考 · Semantic 本体与数据：读对象、改数据、建本体。
参考 · 数据接入：数据流和数据源。
参考 · 访问、自动化与用量：自动化、看板和用量。

本页由 developer/docs/cli-recipes.md 生成 · Markdown 原文 · llms.txt