参考 · Semantic 本体与数据

本页覆盖 aidc semantic 下读写本体（Ontology）的命令。命令分八组：读定义、读对象、改数据、函数、建本体、安全、SQL 与 Loop 报告。这些命令要你所在组织的 developer 角色。数据接入见 参考 · 数据接入，访问、自动化与用量见 参考 · 访问、自动化与用量。

读定义

这一组命令读本体的定义。前六个命令收 --branch <分支>，读的是分支上的定义，不是 main。

aidc semantic ontology

看本体全貌：Object Type、链接、Action 和接口。要 developer。

aidc semantic ontology [--branch <分支>]

$ aidc semantic ontology
…（cell-demo）
  customer                 客户公司  主键 customerId  链接 agents
  ⚡ adjust-seats           调整座位数
…
$ 

• 每个 Object Type 一行。这一行依次是 API 名、显示名、主键和链接。
• ⚡ 开头的行是 Action。◇ 开头的行是接口，行末是实现它的 Object Type。
• 要看一个 Object Type 的完整定义，用 aidc semantic object-types。

aidc semantic object-types

列出 Object Type。给了 API 名，打印它的完整定义。要 developer。

aidc semantic object-types [<类型>] [--branch <分支>]

$ aidc semantic object-types
customer                     客户公司
…
$ aidc semantic object-types customer
{
  "apiName": "customer",
  "displayName": "客户公司",
  …
}
$ 

• 列表的每行是 API 名和显示名。
• 给了名字时，输出是这个类型的 JSON。

aidc semantic action-types

列出 Action。给了 API 名，打印它的完整定义。要 developer。

aidc semantic action-types [<Action>] [--branch <分支>]

$ aidc semantic action-types
adjust-seats                 调整座位数
…
$ 

• 名字不存在时，命令报「没有 名字」，退出码是 2。

aidc semantic interfaces

列出接口（Interface）。给了 API 名，打印它的完整定义。要 developer。

aidc semantic interfaces [<接口>] [--branch <分支>]

$ aidc semantic interfaces
Billable                     …
…
$ 

• 名字不存在时，命令报「没有 名字」，退出码是 2。
• 要看哪些 Object Type 实现了接口，用 aidc semantic ontology 看 ◇ 开头的行。

aidc semantic value-types

列出值类型。每个值类型带字段类型和约束。要 developer。

aidc semantic value-types [--branch <分支>]

$ aidc semantic value-types
customerStage            …  …  enum
…
$ 

• 每行依次是 API 名、显示名、字段类型（JSON）和约束种类，如 enum、regex。

aidc semantic shared-properties

列出共享属性。共享属性是能被多个 Object Type 复用的属性定义。要 developer。

aidc semantic shared-properties [--branch <分支>]

$ aidc semantic shared-properties
costUsd                  …  …
…
$ 

• 每行依次是 API 名、显示名和数据类型（JSON）。

aidc semantic describe

看本体说明书，包括对象数、属性数和 Action。要 developer。

aidc semantic describe [--markdown]

$ aidc semantic describe
Demo Company（cell-demo） · 语义版本 v12
  customer                         客户公司（6 个对象，5 个属性）
  ⚡ adjust-seats                   调整座位数（modify customer）
$ 

• 第一行是组织名、命名空间和当前的语义版本。还没发过版本时，写「还没发过语义版本」。
• Action 行末的括号里是操作（create、modify、delete）和它作用的 Object Type。
• Action 当前用户无权执行时，行末写「无权执行」。

aidc semantic types

列出全部定义。每行依次是种类、API 名和显示名。要 developer。

aidc semantic types

$ aidc semantic types
object  customer                           客户公司
action  adjust-seats                       调整座位数
$ 

• 状态不是 active 的定义，行末写出状态。
• 种类有 object、link、enum、action、interface、sharedProperty 和 valueType。

aidc semantic releases

列出语义版本。每行依次是版本号、改动种类、发布时间、发布人和迁移说明。要 developer。

aidc semantic releases

$ aidc semantic releases
v12  只增  2026-10-07 18:02  account:cm2k9f3a70001qz7d5w1b8x4n  …
v11  破坏性  2026-10-05 10:44  account:cm2k9f3a70001qz7d5w1b8x4n  …
$ 

• 只增：没有检测到破坏性改动。给已有类型新增非必填属性也属于只增。
• 破坏性：按差异规则判定，例如删属性、改类型或改主键。
• 没有版本时，命令打印「还没有语义版本。」

读对象

这一组命令读对象（Object）。收 --branch <分支> 的命令使用分支上的定义读取 main 的对象数据。数据只有 main 一份。这样可以在分支上验证问题能不能答出。

aidc semantic objects

按条件查对象，一页一页取。要 developer。

aidc semantic objects <类型> [--where '<JSON>'] [--order-by <属性:asc|desc>,…] [--select <属性,…>] [--page-size <数量>] [--page-token <令牌>] [--branch <分支>]

$ 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
$ 

• 第一行是「本页个数 / 总数」。有下一页时，第一行后面写出 --page-token 的值。
• --order-by 的属性不写方向时按升序（asc）。
• 表格的第一列是主键，其余列是 --select 或对象的属性。
• --where 的运算符见 读写对象。
• 输出是 JSON 时，对象列表在 data 里，总数在 totalCount 里，下一页的令牌在 nextPageToken 里。

aidc semantic object

按主键取一个对象。要 developer。

aidc semantic object <类型> <主键> [--select <属性,…>] [--branch <分支>]

$ aidc semantic object customer cell-demo-a --select name,seats
{
  "__rid": "ri.phonograph2-objects.aidc.object.…",
  "__primaryKey": "cell-demo-a",
  "__apiName": "customer",
  "__title": "Demo Customer A",
  "name": "Demo Customer A",
  "seats": 48
}
$ 

• 输出是对象的 JSON。以 __ 开头的字段是对象的元数据：资源 id、主键、类型名和标题。
• 主键不存在，或你看不见这个对象时，命令报错。

aidc semantic links

查一个对象沿一条链接连到的对象。要 developer。

aidc semantic links <类型> <主键> <链接> [--page-size <数量>] [--branch <分支>]

$ aidc semantic links customer cell-demo-a agents
__primaryKey
---
ops-agent
$ 

• 链接的 API 名在 aidc semantic ontology 的链接列里。
• 输出是表格。第一列是主键，其余列是对象的属性，最多 7 列。
• 这个命令没有 --page-token，只打印一页。

aidc semantic aggregate

对一类对象做计数、求和、平均、最大、最小或去重计数。也可以按组统计。要 developer。

aidc semantic aggregate <类型> --select '<JSON>' [--group-by '<JSON>'] [--where '<JSON>'] [--interface] [--branch <分支>]

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

• 函数有 sum、avg、min、max、exactDistinct 和 approximateDistinct。

--group-by 的每个属性值使用以下格式：

时长单位有 seconds、minutes、hours、days、weeks、months、quarters 和 years。

• 分组时，结果是数组。每项有 $group（分组的值）和统计值。
• 没有匹配的对象且不分组时，仅选择 $count 会返回 {"$count":0}。同时选择 seats:sum 时，结果还包含 "seats":{"sum":null}。

aidc semantic object-set

查对象集的一页，或对对象集做聚合。对象集用 JSON 定义，可以是一段 JSON，也可以是 .json 文件。要 developer。

aidc semantic object-set <对象集.json | '<JSON>'> [--page-size <数量>] [--page-token <令牌>] [--order-by <属性:asc|desc>,…] [--aggregate '<JSON>']

$ aidc semantic object-set '{"type":"base","objectType":"customer"}' --aggregate '{"$select":{"$count":"unordered"}}'
{
  "$count": 6
}
$ 

• 对象集的写法见 读写对象。
• 给了 --aggregate 时，输出是聚合结果。没有给时，输出本页个数、总数和对象表格。需要下一页令牌时，使用 --json 读取 nextPageToken。

aidc semantic subscribe

订阅对象集的变化，每次变化打一行。按 Ctrl-C 结束。要 developer。

aidc semantic subscribe <类型> [--where '<JSON>'] [--properties <属性,…>]

$ aidc semantic subscribe customer --where '{"stage":"付费"}'
订阅中：customer where {"stage":"付费"}（Ctrl-C 结束）
对象集要整个重读（刚订阅 / 落后太多 / 依赖的类型变了）
06:12:45  ● customer cell-demo-a
06:13:02  ✗ customer cell-demo-b（离开对象集）
$ 

• ● 表示对象进入对象集，或对象变了。行末是主键。
• ✗ 表示对象离开对象集。原因是被筛掉、被删除，或源头消失。
• 行首的时间按 UTC 显示。
• 断线后自动重连并尝试续传。无法续传时，命令提示整体重读。
• 对象集需要整体重读时，终端提示「对象集要整个重读」。刚订阅、落后太多，或依赖的类型变了，都会出现这个提示。
• 加 --json 后，每行输出一个 JSON。接入管道时也使用此格式。

{"type":"change","state":"ADDED_OR_UPDATED","object":{}}

object 包含变化的对象，此处省略属性。state 的值是 ADDED_OR_UPDATED 或 REMOVED。需要整体重读时，输出 {"type":"outOfDate"}。

aidc semantic edits-history

看一个 Object Type 的编辑记录。可以只看一个对象。要 developer。

aidc semantic edits-history <类型> [--pk <主键>] [--previous] [--page-size <数量>] [--branch <分支>]

$ 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.…
$ 

• 每行依次是时间、编辑种类、主键、操作人和操作号。
• 没有记录时，命令打印「（没有编辑）」。

改数据

改数据用 Action。Action 的参数校验、权限和留痕都由平台做。智能体不能直接新建、修改、删除或导入数据，这些请求会得到 403（退出码 4）。

aidc semantic apply

执行一个 Action，或只校验它。要 developer。

aidc semantic apply <Action> [--param <名=值>]… [--params '<JSON>'] [--validate-only] [--return-edits]

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

$ aidc semantic apply adjust-seats --param customer=cell-demo-a --param seats=3 --validate-only
✗ 校验不通过
  提交条件：座位数不能少于成员数
$ 

$ 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
$ 

• 对象参数传对象的主键，如 customer=cell-demo-a。
• --param 将 true、false 和 null 按 JSON 解析。只有解析后能原样写回的数字才转成数字。其余的值当作文字。
• 1.50、007 保留为字符串。对象值如媒体引用，用 --params 传入。
• 校验不通过时，命令列出不合格的参数和没通过的提交条件，退出码是 2。
• --validate-only 只校验，不写入任何数据。

aidc semantic apply-batch

在一个事务里执行同一个 Action 多次。要 developer。

aidc semantic apply-batch <Action> <参数数组.json | '<JSON>'> [--return-edits]

[
  { "customer": "cell-demo-a", "seats": 60 },
  { "customer": "cell-demo-b", "seats": 40 }
]

$ aidc semantic apply-batch adjust-seats batch.json
✓ 已执行 2 次 adjust-seats（一个事务）
$ 

• 一个事务：全部生效，或全部不生效。
• 这个命令没有 --validate-only。要先校验，用 aidc semantic apply --validate-only 逐项试。

aidc semantic upload-media-content

把一个本地文件上传到媒体引用属性，拿到引用。要 developer。旧的命令名 aidc semantic upload-media 照样能用。

aidc semantic upload-media-content <类型> <属性> <文件> [--media-item-path <路径>] [--content-type <类型>]

下面的例子假设本体里有 Object Type report，它有媒体引用属性 html。

$ aidc semantic upload-media-content report html ./daily.html --content-type text/html
{"mimeType":"text/html","reference":{"type":"mediaSetViewItem","mediaSetViewItem":{"mediaSetRid":"ri.…","mediaSetViewRid":"ri.…","mediaItemRid":"ri.…"}}}
$ 

• 文件直接上传到组织自己的存储。0 字节的文件不收。
• 输出是一行 MediaReference 的 JSON。把引用放进 apply 的 --params，作为媒体引用参数的值，例如 {"html":引用}。引用一小时内要用上。

函数

函数（Function）是用代码写的逻辑。它在隔离的运行时里执行。

aidc semantic functions list

列出已发布的函数。每个函数显示最新版本、种类和版本数。要 developer。

aidc semantic functions list

$ aidc semantic functions list
countPaidCustomers           1.0.0            查询函数  共 1 个版本 · 最近 2026-10-08T09:12:44.000Z
  ri.…
$ 

• 每个函数占两行。第二行是函数的资源 id。
• 还没有函数时，命令打印「还没有函数。」

aidc semantic functions publish

发布一个函数版本。要 developer。

aidc semantic functions publish <源码.js> --api-name <名字> --version <版本> --output '<JSON>' [--parameters '<JSON>'] [--edit-function] [--display-name <名字>] [--description <说明>] [--timeout-ms <毫秒>] [--dry-run]

$ aidc semantic functions publish count.js --api-name countPaidCustomers --version 1.0.0 --output '{"type":"integer"}'
已发布：countPaidCustomers@1.0.0（查询函数）
  ri.…
$ 

• 发布后，同一版本不能改内容。要改，发新版本号。
• 同一版本、同一内容和配置再发布，输出「没有变化」，不新建版本。源码和签名不变时，可修改 --timeout-ms。命令输出「已更新配置」，不新建版本。
• 同一版本、内容不同，命令报冲突。
• 智能体只能发预发布版本，如 1.1.0-rc.1。
• --dry-run 的输出是「预演通过（没有发布）」。

建本体：定义与发布

这一组命令直接写 main，只给开发者用。智能体改本体要走分支，见下一组。

aidc semantic define

批量提交定义，直接写入 main。一批里互相引用的定义一起校验。要 developer。

aidc semantic define <文件.json|目录> [--dry-run]

$ aidc semantic define ontology/ --dry-run
（dry-run）更新 object customer
（dry-run）新建 link customerAgents
（dry-run）会定义 2 个词条，引用闭合。
$ 

• 定义是 JSON。kind 有 objectType、linkType、actionType、interfaceType、sharedPropertyType 和 valueType。定义的写法见 定义本体。
• 定义里写了不认识的字段，定义会被拒。错误信息给出字段的路径。
• 定义有破坏性改动时，输出行末写「⚠ 破坏性」。
• 智能体直接写入 main 会返回 409（branch_required），退出码是 6。使用 --dry-run 可以校验而不写入。智能体要用分支，见 建本体：分支与提案。
• 定义写入后，用 aidc semantic publish 发布语义版本。

aidc semantic archive

归档一个定义。归档后，它的数据源同步停止。已有的对象保留。要 developer。

aidc semantic archive <apiName> [--dry-run]

$ aidc semantic archive customerAgents
已归档 customerAgents
$ 

• 不再用的定义，归档即可。归档不删除已有的对象。

aidc semantic publish

把当前定义发布成一个语义版本。定义没有变化时，版本号不变。要 developer。

aidc semantic publish [--notes <说明>]

$ aidc semantic publish --notes "新增部门对象类型"
已发布语义版本 v13（只增，12 个词条）
$ 

• 版本种类有两种。只增表示没有检测到破坏性改动。给已有类型新增非必填属性也属于只增。破坏性按差异规则判定。
• 定义没有变化时，输出「定义没有变化，仍是 v12」这样的文字。
• 查看已发布的版本，用 aidc semantic releases。

建本体：分支与提案

智能体不能直接改 main。智能体在分支上修改定义，再开提案。审核与合并按组织的审批策略执行。开发者可以直接定义，见上一组。

设 AIDC_AGENT_ID=<智能体 id> 后，作者记为这个智能体（见 在 CI 和智能体里用）。智能体改本体的顺序是：

1. 开分支：aidc semantic branch create <分支>。
2. 写入定义：aidc semantic branch modify <分支> <目录>。先加 --dry-run 试跑。
3. 验证：aidc semantic objects <类型> --branch <分支>。再看 branch validate 和 branch conflicts。
4. 开提案：aidc semantic branch propose <分支> --title … --trigger …。
5. 审核与合并：看 approval-policy，决定由谁批准、谁合并。

aidc semantic branch list

列出分支。每行依次是名字、状态、分支版本、作者和改动数。要 developer。

aidc semantic branch list

$ aidc semantic branch list
add-department               ACTIVE  v4  作者 agent:ops-agent  2 处改动
$ 

• 分支 35 天没有活动，状态转为 INACTIVE。再过 7 天，分支的数据被删除。
• 分支状态有 ACTIVE、INACTIVE、MERGED、CLOSED、DELETED。新建分支为 ACTIVE。

aidc semantic branch create

新建一个分支。基线是创建时的语义版本。要 developer。

aidc semantic branch create <分支> [--description <说明>]

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

• 作者是当前的身份。设了 AIDC_AGENT_ID 时，作者是这个智能体。

aidc semantic branch show

看一个分支：状态、版本、基线和全部改动。要 developer。

aidc semantic branch show <分支>

$ aidc semantic branch show add-department
add-department  …  v4  基线 v12  作者 agent:ops-agent
  ± object department
$ 

• ± 开头的行是新增或修改。− 开头的行是归档。
• 锁定的分支在 branch show 首行末尾显示 🔒。

aidc semantic branch modify

在分支上写入一份定义，或归档分支上的定义。要 developer。

aidc semantic branch modify <分支> [<文件.json|目录>] [--archive <apiName,…>] [--expected-version <版本>] [--dry-run]

文件与 --archive 至少提供一个。

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

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

• 校验结果是 VALID 或 INVALID。加了 --dry-run 且结果是 INVALID 时，退出码是 2。
• 写入后，分支版本加一。
• --expected-version 用来防止覆盖别人的改动。分支版本不一致时，命令拒绝写入。

aidc semantic branch validate

校验分支。检查合并条件（merge checks）。要 developer。

aidc semantic branch validate <分支>

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

• 命令检查定义合法性、引用闭合、数据源、webhook 和安全。命令还检查主键、API 名、分支与 main 的冲突和设计。
• 结果是 VALID 时，退出码是 0。否则退出码是 2。
• 每个检查项一行。✓ 是通过，⚠ 是警告，✗ 是不通过。

aidc semantic branch conflicts

列出分支与 main 的冲突。要 developer。

aidc semantic branch conflicts <分支>

$ aidc semantic branch conflicts add-department
没有冲突。
$ 

• 每个冲突一行。行首的 ✗ 后面是 API 名和原因。
• 有冲突时，用 aidc semantic branch rebase 处理。

aidc semantic branch rebase

把分支跟上 main。冲突的定义取哪一边，由参数决定。要 developer。

aidc semantic branch rebase <分支> [--keep <apiName,…>] [--take-main <apiName,…>]

$ aidc semantic branch rebase add-department --take-main customer
已 rebase 到 v13
$ 

• 输出的版本号是分支的新基线。

aidc semantic branch discard

放弃分支上的改动。不给定义名时，放弃全部改动。要 developer。

aidc semantic branch discard <分支> [<apiName> …]

$ aidc semantic branch discard add-department department
已放弃 department 改动
$ 

aidc semantic branch lock

锁定或解锁一个分支。要 developer。

aidc semantic branch lock <分支> [--unlock]

$ aidc semantic branch lock add-department
已锁定 add-department
$ aidc semantic branch lock add-department --unlock
已解锁 add-department
$ 

• 锁定的分支在 branch show 首行末尾显示 🔒。
• 锁定后不能修改或归档分支定义、放弃改动、rebase 或新开提案。这些操作返回 409。先解锁再执行。

aidc semantic branch propose

为分支开一个提案，写明为什么要改。要 developer。

aidc semantic branch propose <分支> --title <标题> --trigger <触发原因> [--self-test <自测结果>] [--description <说明>]

$ 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。
$ 

• 缺 --title 或 --trigger 时，退出码是 2。
• 平台自动附上改动、校验结果和影响面。影响面包括 30 天的写入次数、活跃用户和依赖的应用。
• 审批策略是 review 时，提案要本组织的开发者在网页上批准。
• 审批策略是 yolo 时，作者的批准算数。检查通过就直接合并。输出变成「已开提案 … 并合并」。
• 同一个分支同时开两个提案，只有一个成功。
• 提案尚未合并时，JSON 输出包含 reviewUrl。可以把这个审核地址交给人。

aidc semantic proposals

列出提案。可以按状态筛选。要 developer。

aidc semantic proposals [--status OPEN|MERGED|CLOSED]

$ aidc semantic proposals --status OPEN
● cm2kb7q4e0004qz7d5w1b8x4n  加部门对象类型  分支 add-department  作者 agent:ops-agent
$ 

• 行首符号：● 是打开的提案，✓ 是已合并的提案，○ 是其他状态的提案。
• 没有提案时，命令打印「（没有提案）」。

aidc semantic proposal

看一个提案：标题、状态、任务、合并检查和审核网页。要 developer。

aidc semantic proposal <提案>

$ aidc semantic proposal cm2kb7q4e0004qz7d5w1b8x4n
加部门对象类型（OPEN，分支 add-department，作者 agent:ops-agent）
  … department  created
merge checks：
  …
  ✓ reference_closure
  …
审核与合并：aidc semantic proposal approve|merge cm2kb7q4e0004qz7d5w1b8x4n（组织的审批策略是 yolo 时），或在网页上：https://www.ai-dc.ai/developer/cell-demo/ontology/proposals/cm2kb7q4e0004qz7d5w1b8x4n
$ 

• 任务行首的符号：✓ 是已批准，✗ 是已驳回，… 是待审核。
• 任务行末的「⚠ 破坏性」表示这是破坏性改动。批准它要加 --confirm-breaking。
• 批准绑在分支的版本上。分支改过后，旧的批准不算数，要重新批准。

aidc semantic proposal close

关闭一个提案，不合并。正在合并的提案不能关闭。要 developer。

aidc semantic proposal close <提案> [--note <说明>]

$ aidc semantic proposal close cm2kb7q4e0004qz7d5w1b8x4n --note "改用别的方案"
已关闭提案 cm2kb7q4e0004qz7d5w1b8x4n
$ 

aidc semantic proposal approve

批准提案里的任务。不写任务名，就批准全部待审核的任务。要 developer。

aidc semantic proposal approve <提案> [<任务> …] [--note <说明>] [--confirm-breaking]

$ aidc semantic proposal approve cm2kb7q4e0004qz7d5w1b8x4n department --note "字段名没问题"
✓ 批准了 department（1/2 已批准）
$ 

• 命令先检查任务名和破坏性确认，再逐项批准。后续请求失败时，此前的批准保留。
• 任务名不存在时，退出码是 5。
• 批准破坏性改动却没加 --confirm-breaking 时，退出码是 2。一个都不批准。
• 全部任务都批准后，输出最后一行，提示合并命令。
• 命令读取提案后、提交批准前，分支又发生修改时，返回 409。退出码是 6。重新看 proposal，再批准。

aidc semantic proposal reject

驳回提案里的一个任务。一次只能驳回一个任务。要 developer。

aidc semantic proposal reject <提案> <任务> [--note <说明>]

$ aidc semantic proposal reject cm2kb7q4e0004qz7d5w1b8x4n agent --note "字段名要改"
✓ 驳回了 agent（1/2 已批准）
$ 

• 有任何一个任务被驳回，提案就不能合并。

aidc semantic proposal merge

合并一个提案，进 main，并发布一个语义版本。全部任务都批准、合并检查都通过，才能合并。要 developer。

aidc semantic proposal merge <提案>

$ aidc semantic proposal merge cm2kb7q4e0004qz7d5w1b8x4n
✓ 已合并提案 cm2kb7q4e0004qz7d5w1b8x4n：语义版本 v13
$ 

• 一个组织同时只能合并一个提案。另一个合并正在进行时，命令返回 409，退出码是 6。

aidc semantic approval-policy

看或改组织的审批策略。要 developer；改策略只给本组织的开发者本人，智能体不能改。

aidc semantic approval-policy [get]
aidc semantic approval-policy set review|yolo [--dry-run]

$ aidc semantic approval-policy
cell-demo 审批策略 review：审核人 = 网页会话；需要 1 个批准；作者自己批准不算数；合并要审核人来点
$ 

$ aidc semantic approval-policy set yolo --dry-run
（dry-run）review → yolo，没有改
cell-demo 审批策略 yolo：审核人 = 网页会话、开发者 Key、Agent Key；需要 1 个批准；作者自己批准算数；检查通过自动合并
  ● cm2kb7q4e0004qz7d5w1b8x4n  加部门对象类型
$ 

• 改回 review 时，智能体给的批准作废，回到待审核。
• 把策略设成当前的值，不写入任何东西。
• 任何策略下，安全策略的改动都要满足相关 Marking 的人批准。
• 策略名写错时，退出码是 2。

安全

aidc semantic security test

试安全策略：按某个人，看一组对象和属性能不能看见。只给开发者用。结果不显示属性值。要 developer。

aidc semantic security test <类型> [--user <账号 id>] [--pk <主键,…>] [--object '<JSON>']… [--policy <JSON 或文件>]

不传 --user 时，命令使用当前调用者的安全身份。

--pk 和 --object 至少要给一个。两个都不给时，退出码是 2。

$ aidc semantic security test employeeCompensation --user cm2k9f3a70001qz7d5w1b8x4n --pk e1,e2
employeeCompensation：按 cm2k9f3a70001qz7d5w1b8x4n 试保存的策略
  ✓ 看得见  e1  看不见的属性：baseSalary
  ✗ 看不见  e2
$ 

• 给了 --policy 时，输出写「没保存的策略」。这种试算不会保存策略。
• 整个类型的 Marking 不满足时，输出「整个类型看不见」。
• 有主键没有结果时，输出「有的主键没有结果：对象不存在，或你自己看不见」。

SQL

aidc semantic sql

执行一条只读的 SELECT 语句。表名是 Object Type 的 API 名。列名是属性的 API 名。要 developer。

缺省用 Postgres 方言。加 --dialect spark 用标准方言。两种方言的区别见 SQL 与数据库 · 选方言。

aidc semantic sql "<SELECT …>" [--param <值>]… [--row-limit <行数>] [--explain] [--csv]
aidc semantic sql "<SELECT …>" --dialect spark [--param <值>… | --named <名=值>…] [--csv | --json | --arrow <文件>]
aidc semantic sql --file <q.sql> [--csv]

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

$ aidc semantic sql 'SELECT name, seats FROM customer WHERE stage = $1 ORDER BY seats DESC' --param 付费 --csv
name,seats
Demo Customer A,48
Demo Customer B,36
$ 

• 上限是 10,000 行，20 秒。
• 只能读。写入只能用 aidc semantic apply。
• 结果超过 --row-limit 时，最后一行写「截断到」和上限的行数。
• 角色 reader 能看见本组织的全部类型。角色 public 只能看见授予了所有人的类型。
• --param 和 --named 的值：整数、小数、true、false、null 按 JSON 解析。写回原样会变的值按字符串传，例如 007、1.50。值里的逗号保留。
• 表和列的名字，用 aidc semantic database 查看。

$ aidc semantic sql 'SELECT name, seats FROM customer WHERE seats > ? ORDER BY seats DESC' --dialect spark --param 30
name	seats
Demo Customer A	48
Demo Customer B	36
（2 行 · 16 ms · Spark 方言）
$ aidc semantic sql 'SELECT * FROM customer' --dialect spark --arrow customers.arrow
✓ 写入 customers.arrow（Arrow IPC stream，2984 字节，6 行）
$ 

aidc semantic database

看 Semantic 数据库的 schema、我能查的表和列。开发者可以重建视图，或轮换只读直连的口令。要 developer。

aidc semantic database [--sync]
aidc semantic database --rotate

$ aidc semantic database
schema ont_… · 我用 reader 角色 · …
  表  customer                     4 列  客户公司
直连：…@…:…/…（口令用 aidc semantic database --rotate 拿）
$ 

$ aidc semantic database --rotate
只读直连（口令只显示这一次，再轮换即失效）：
  psql "…"
  schema ont_… · user …
$ 

• 输出里每个视图占一行。种类是「表」（Object Type）、「链接」（Link Type）或「接口」。
• 直连只给本组织的开发者。
• 轮换口令后，旧口令立即失效。口令只显示一次，请立即保存到安全的地方。
• 直连是只读事务，有 20 秒超时，最多 10 个连接。只能看到本组织的视图。

Loop 报告

智能体用自己的 Agent Key 发布 Loop 报告。Key 决定组织：只能写自己的组织，只能发自己负责的报告。没写 -n 时，命令从 Key 取组织。开发者 Key 也能用，可以直接更新任何报告。

aidc semantic loop-report publish

发布一份 HTML 报告。报告不存在时新建，存在且归你负责时更新。

aidc semantic loop-report publish <文件.html> --slug <slug> --title <标题> [--description <说明>] [--data-date YYYY-MM-DD] [--owner-name <显示名>] [--dry-run] [--json]

$ aidc semantic loop-report publish daily.html --slug daily-output --title "日产量日报" --data-date 2026-10-08 --owner-name "Demo Agent" --dry-run
将执行 create-loop-report
https://www.ai-dc.ai/semantic/cell-demo/objects/loopReport/daily-output
$ aidc semantic loop-report publish daily.html --slug daily-output --title "日产量日报" --data-date 2026-10-08 --owner-name "Demo Agent"
已发布 daily-output
https://www.ai-dc.ai/semantic/cell-demo/objects/loopReport/daily-output
$ 

• 新报告执行 create-loop-report。已有、归你负责的报告执行 update-loop-report。
• 没有负责智能体的报告，先执行 claim-loop-report 认领，再更新。
• 内容、标题、说明、数据日期都没变时，命令输出「没变，跳过」，不上传。
• 报告归别的智能体时，命令不上传，以退出码 3 结束。请人在 AIDC 里执行 assign-loop-owner 改负责智能体。

aidc semantic loop-report list

列出本组织的 Loop 报告。加 --mine 只列你负责的。

aidc semantic loop-report list [--mine] [--json]

$ aidc semantic loop-report list --mine
daily-output  日产量日报  Demo Agent  2026-10-08  2026-10-08T09:30:12.000Z  aidc
$ 

每行依次是 slug、标题、负责智能体、数据日期、发布时间和发布通道。

aidc semantic loop-report history

看一份报告的变更记录：时间、谁、做了什么，以及内容摘要的前 8 位。

aidc semantic loop-report history <slug> [--json]

$ aidc semantic loop-report history daily-output
2026-10-08T09:30:12.000Z  Demo Agent  发布 daily-output  3f9a1c07
2026-10-07T09:30:05.000Z  Demo Agent  发布 daily-output  b12e7d44
$ 

「做了什么」一列是 Action 定义里的 summary。

aidc semantic loop-report claim

认领一份没有负责智能体的报告。

aidc semantic loop-report claim <slug> --owner-name <显示名> [--dry-run] [--json]

$ aidc semantic loop-report claim daily-output --owner-name "Demo Agent"
已认领 daily-output
$ 

下一步

• 定义本体：本体的概念，定义文件的写法，审批策略。
• 读写对象：读对象，订阅变化，用 Action 改数据。
• SQL 与数据库：用 SQL 查对象，直连数据库。
• 访问与安全：谁能看见对象，Marking 与安全策略。

命令迁移见 旧写法与迁移。