# 常用流程 这一页按任务列出完整步骤。每个流程先说做成什么，再列编号步骤。能看到输出的步骤，都给出了输出。示例数据只用 Demo Company（组织，命名空间 `cell-demo`）。 > [!NOTE] > 前提：已登录（`aidc login`）。每个流程开头写了需要的角色。 ## 流程一览 下面是九个流程。每个流程都能单独照做。 - [从零发布一个应用](#从零发布一个应用) - [查对象与聚合](#查对象与聚合) - [用 Action 改数据](#用-action-改数据) - [接一条数据流](#接一条数据流) - [让智能体在分支上改本体](#让智能体在分支上改本体) - [按时自动检查并发邮件](#按时自动检查并发邮件) - [看这个月花了多少](#看这个月花了多少) - [在 CI 和智能体里用](#在-ci-和智能体里用) - [和智能体在终端里一起做](#和智能体在终端里一起做) ## 从零发布一个应用 用工作流模板做一个报表问答应用。应用先进入 test 通道，测过后再发布到 production。 **前提**：第 1 步到第 3 步，member 角色就能做。第 4 步起要 developer。 1. 生成应用目录。 ```terminal title="生成应用目录" $ 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`](cli-apps.md#aidc-app-init)。 2. 在本机预览。 ```terminal title="本机预览" $ 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`](cli-apps.md#aidc-app-dev)。 3. 校验应用。 ```terminal title="校验应用" $ aidc app check ask-report ✓ ask-report：5 个文件，6.0 KB，digest 84d5ed69934c5bc2 ``` 校验规则和服务端相同，上传前就能发现问题。详见 [`aidc app check`](cli-apps.md#aidc-app-check)。 4. 放进 test 通道。 ```terminal title="部署到 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`](cli-apps.md#aidc-app-deploy)。 5. 调一个 API，只预演。 ```bash 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`](cli-apps.md#aidc-app-call)。 6. 发布到 production。 ```terminal title="发布" $ 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`](cli-apps.md#aidc-app-publish) 和 [快速开始](quickstart.md)。 ## 查对象与聚合 用对象查询、聚合和 SQL 读出付费大客户的座位数。三种写法读的是同一份数据。 **前提**：developer 角色。 1. 按条件查对象。 ```terminal title="查对象" $ 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 ``` 结果按座位数从多到少排。第一列是主键。筛选条件的运算符见 [读写对象](data.md)。详见 [`aidc semantic objects`](cli-semantic.md#aidc-semantic-objects)。 2. 合计座位数。 ```terminal title="座位合计" $ aidc semantic aggregate customer --select '{"$count":"unordered","seats:sum":"desc"}' --where '{"stage":"付费","seats":{"$gt":30}}' { "$count": 2, "seats": { "sum": 84 } } ``` 两个客户，座位数合计 84。分组统计的写法见 [`aidc semantic aggregate`](cli-semantic.md#aidc-semantic-aggregate)。 3. 用 SQL 查同样的结果。 ```terminal title="执行 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 与数据库](sql.md) 和 [`aidc semantic sql`](cli-semantic.md#aidc-semantic-sql)。 ## 用 Action 改数据 用 Action 把 Demo Customer A 的座位数改成 60。顺序是：先校验，再执行，最后看编辑记录。 **前提**：developer 角色。 > [!IMPORTANT] > 执行 Action 会改数据，并留下记录。智能体不能直接改数据。直接写入会返回 403（退出码 4）。 1. 只校验，不执行。 ```terminal title="只校验" $ aidc semantic apply adjust-seats --param customer=cell-demo-a --param seats=60 --validate-only ✓ 校验通过（没有执行） ``` 校验不改数据。参数不合格时，命令列出原因，退出码是 2。详见 [`aidc semantic apply`](cli-semantic.md#aidc-semantic-apply)。 2. 执行，并看改动数。 ```terminal title="执行改数据" $ 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 ``` 第二行是这次执行的改动数。 3. 看编辑记录。 ```terminal title="编辑记录" $ 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`](cli-semantic.md#aidc-semantic-edits-history) 和 [读写对象](data.md)。 ## 接一条数据流 把订单数据接进本体（Ontology）。数据流收数据，数据源把数据流接到 Object Type `production.order_line`。 **前提**：developer 角色。发布端只用发布 Key，不用登录。 1. 建数据流。 ```terminal title="建数据流" $ 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`](cli-data.md#aidc-semantic-streams-create) 和 [数据接入](connect.md)。 2. 签一把发布 Key。 ```terminal title="签发布 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`](cli-data.md#aidc-semantic-streams-key)。 3. 运行发布端。适配器是一个常驻程序，每行打印一个 JSON。下面的适配器每 30 秒读一次数据源。 ```python # 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) ``` ```terminal title="运行发布端" $ 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`](cli-data.md#aidc-semantic-streams-pipe)。 4. 把数据流接到 Object Type。 ```terminal title="接数据源" $ 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`](cli-data.md#aidc-semantic-datasource-set)。 5. 看数据源的状态。 ```terminal title="看数据源" $ aidc semantic datasource list ● production.order_line ← orders mirror 同步到 seq 130 ``` `●` 表示数据源正常。`同步到 seq 130` 是同步进度。`mirror` 模式下，数据流里没有了的行，对象标记为「源头已消失」。详见 [`aidc semantic datasource list`](cli-data.md#aidc-semantic-datasource-list)。 ## 让智能体在分支上改本体 智能体发现本体缺一个部门 Object Type。它在分支上加这个类型，校验通过后开提案，交给人审核。 **前提**：developer 角色。智能体用开发者 Key 调 CLI。 > [!IMPORTANT] > 智能体不能直接改 main。直接写入 main 会返回 409（退出码 6）。设了 `AIDC_AGENT_ID` 后，作者记为这个智能体。 1. 开分支。 ```terminal title="开分支" $ AIDC_AGENT_ID=ops-agent aidc semantic branch create add-department --description "加部门对象类型" 已建分支 add-department（基线 v12，作者 agent:ops-agent） ``` 分支基于当前的语义版本。main 不变。详见 [`aidc semantic branch create`](cli-semantic.md#aidc-semantic-branch-create)。 2. 试跑定义。 ```terminal title="试跑" $ aidc semantic branch modify add-department ./ontology --dry-run （dry-run）分支 add-department 试跑：校验 VALID … ✓ reference_closure … ✓ api_names ``` `./ontology` 是定义文件的目录。定义的写法见 [定义本体](ontology.md)。试跑只校验，不写入。 3. 写入分支。 ```terminal title="写入分支" $ aidc semantic branch modify add-department ./ontology ✓ 分支 add-department 已改到 v1：校验 VALID … ✓ reference_closure … ``` 写入后，分支版本加一。`--expected-version` 可以防止覆盖别人的改动。详见 [`aidc semantic branch modify`](cli-semantic.md#aidc-semantic-branch-modify)。 4. 校验合并条件。 ```terminal title="校验分支" $ aidc semantic branch validate add-department 校验 VALID … ✓ reference_closure … ``` 结果是 `VALID` 时，退出码是 0。否则退出码是 2。详见 [`aidc semantic branch validate`](cli-semantic.md#aidc-semantic-branch-validate)。 5. 开提案。 ```terminal title="开提案" $ 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，策略见 [定义本体](ontology.md)。详见 [`aidc semantic branch propose`](cli-semantic.md#aidc-semantic-branch-propose)。 ## 按时自动检查并发邮件 建一个组织级的自动化。它每个工作日 09:30 检查逾期任务，给负责人发邮件。数据变化时触发的工作流，见 [自动化](workflow.md)。 **前提**：建和运行要 developer。查看运行记录，member 也能用。 1. 写定义文件 `任务逾期.json`。 ```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`](cli-govern.md#aidc-semantic-automations-upsert)。 2. 预演，不保存。 ```terminal title="预演自动化" $ aidc semantic automations upsert --ontology cell-demo --file 任务逾期.json --dry-run 预演：任务逾期（看 devTask） ri.aidc.automate.cell-demo.automation.dev-task-overdue ``` 预演检查定义，并看对象集，但不保存。 3. 保存。 ```bash aidc semantic automations upsert --ontology cell-demo --file 任务逾期.json ``` 保存后，系统按时间表查询当前符合条件的对象。 4. 立即运行一次。 ```terminal title="立即运行" $ aidc semantic automations run ri.aidc.automate.cell-demo.automation.dev-task-overdue 已开跑：{…} ``` `{…}` 是这次运行的 JSON，打印在一行里。详见 [`aidc semantic automations run`](cli-govern.md#aidc-semantic-automations-run)。 5. 看运行记录。 ```terminal title="运行记录" $ 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`](cli-govern.md#aidc-semantic-automations-runs)。 ## 看这个月花了多少 看本月花费，导出明细，再估算下个月的费用。 **前提**：`summary` 和 `records` 要 developer。`estimate` 登录即可用。金额是模型厂商的美元标价，不是发票。 1. 看本月汇总。 ```terminal title="看花费" $ 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`](cli-govern.md#aidc-semantic-usage-summary) 和 [用量与账单](billing.md)。 2. 导出本月的明细。 ```terminal title="导出明细" $ 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`](cli-govern.md#aidc-semantic-usage-records)。 3. 估算下个月的费用。 ```terminal title="估算" $ 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`](cli-govern.md#aidc-semantic-usage-estimate)。 ## 在 CI 和智能体里用 用环境变量提供开发者 Key。读取 JSON 输出。按退出码决定下一步。写操作先预演。 **前提**：部署要 developer 角色。Key 从 CI 的密钥库取，不要写进仓库。 1. 用 Key 登录。在 CI 里设环境变量，不运行 `aidc login`。 ```bash export AIDC_API_KEY="$AIDC_DEVELOPER_KEY" # 从 CI 的密钥库取 ``` 在一台机器上，用 `--with-key` 把 Key 存到本机： ```terminal title="保存 Key" $ aidc login --with-key < key.txt 已登录：zhang.san · Demo Company（cell-demo）· developer ``` `AIDC_API_KEY` 优先于保存的 Key。详见 [在 CI 和智能体里用](cli.md#在-ci-和智能体里用)。 2. 确认身份，取出组织编号。 ```terminal title="确认身份" $ aidc whoami --json | jq -r .company.cellId cell-demo ``` `aidc whoami` 的退出码是 3 时，表示未登录或 Key 无效。 3. 校验应用，取 JSON 结果。 ```terminal title="校验应用" $ aidc app check ./ask-report --json { "ok": true, "slug": "ask-report", "namespace": null, "digest": "84d5ed69934c5bc291b3a76a14db9bca9c35c753686cf1262acad2a44429fd1f", "files": 5, "bytes": 6173, "warnings": [] } ``` `warnings` 是空数组时，没有成本告警。 4. 先预演部署。 ```terminal title="预演部署" $ 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。 5. 部署，并按退出码分支。 ```bash 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 概览](cli.md#退出码)。智能体按退出码决定下一步，不解析中文提示。 6. 带幂等键调用 `run`。重试时用同一个键。 ```bash aidc app call ask-report run --channel test --param question="本周有没有异常" --idempotency-key ci-20261008-0001 --json ``` 键长 8 到 128 个字符。第一个字符是字母或数字，其余是字母、数字或 `_ . : -`。详见 [`aidc app call`](cli-apps.md#aidc-app-call)。 7. 标明智能体身份。智能体用开发者 Key 调 CLI 时，设置这一项。 ```bash export AIDC_AGENT_ID=ops-agent ``` 作者记为这个智能体。建本体只能进分支、开提案，由人审核。智能体的完整接入步骤见 [智能体接入](agents.md)。 ## 和智能体在终端里一起做 用 `aidc chat -p` 跑一轮对话。它不进交互界面，回答直接写到标准输出。 **前提**：已登录即可。 > [!IMPORTANT] > 给了提示文字，`aidc chat -p` 就不读管道。要把文件内容交给它，先把要求和内容拼在一起。`-p` 缺省拒绝智能体用工具，加 `--yes` 才自动允许。 1. 问一句。 ```terminal title="跑一轮" $ aidc chat -p "用一句话说明 Action 是什么" --runtime engine Action 是 Semantic 里改数据的唯一方式：每次执行都带参数校验、权限检查和留痕。 ``` 回答边生成边打出。工具调用另起一行，以 `· ` 开头，打到标准错误输出。未指定 `--runtime` 时，优先使用上次保存且仍可用的运行时。否则选择第一个可用的运行时，最后使用 Engine。详见 [不进界面：aidc chat -p](cli-chat.md#不进界面aidc-chat--p)。 2. 取出 `stopReason`。 ```terminal title="取状态" $ aidc chat -p "用一句话说明 Action 是什么" --runtime engine --json | jq -r .stopReason end_turn ``` 退出码 0 不等于回答完整。`max_tokens` 表示回答被截断。`refusal` 表示模型拒绝回答。 3. 把文件内容交给它。 ```bash (echo "写一段提交说明"; git diff) | aidc chat -p --runtime engine ``` 没有写提示文字，aidc 就读标准输入。要求写在前面，内容接在后面。`git diff | aidc chat -p "写一段提交说明"` 不读 `git diff`。 ## 下一步 - [交互界面](cli-chat.md)：进入界面，和智能体对话，确认工具调用。 - [CLI 概览](cli.md)：安装、登录、输出和退出码。 - [参考 · 应用与界面](cli-apps.md)：应用的命令、参数和输出。 - [参考 · Semantic 本体与数据](cli-semantic.md)：读对象、改数据、建本体。 - [参考 · 数据接入](cli-data.md)：数据流和数据源。 - [参考 · 访问、自动化与用量](cli-govern.md)：自动化、看板和用量。