# 参考 · Semantic 本体与数据

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

> [!NOTE]
> 用法里 `<…>` 是要你填的值，`[…]` 是可选项，`|` 表示二选一，`…` 表示可以重复。`<类型>` 是 Object Type 的 API 名（如 `customer`）。`<主键>` 是对象的主键值（如 `cell-demo-a`）。`<链接>` 是链接的 API 名（如 `agents`）。`<Action>` 是 Action 的 API 名（如 `adjust-seats`）。`<分支>` 是分支名。`<提案>` 是提案的 id。
>
> 通用参数（`--json`、`--dry-run`、`--api`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)。输出格式见 [输出](cli.md#输出给人看也给程序读)，退出码见 [退出码](cli.md#退出码)。命名空间缺省是登录的组织，`-n cell-demo` 指定组织。

| 命令 | 做什么 |
| --- | --- |
| [`aidc semantic ontology`](#aidc-semantic-ontology) | 看本体全貌 |
| [`aidc semantic object-types`](#aidc-semantic-object-types) | 列出或查看 Object Type |
| [`aidc semantic action-types`](#aidc-semantic-action-types) | 列出或查看 Action |
| [`aidc semantic interfaces`](#aidc-semantic-interfaces) | 列出或查看接口 |
| [`aidc semantic value-types`](#aidc-semantic-value-types) | 列出值类型 |
| [`aidc semantic shared-properties`](#aidc-semantic-shared-properties) | 列出共享属性 |
| [`aidc semantic describe`](#aidc-semantic-describe) | 看本体说明书 |
| [`aidc semantic types`](#aidc-semantic-types) | 列出全部定义 |
| [`aidc semantic releases`](#aidc-semantic-releases) | 列出语义版本 |
| [`aidc semantic objects`](#aidc-semantic-objects) | 按条件查对象，一页一页取 |
| [`aidc semantic object`](#aidc-semantic-object) | 按主键取一个对象 |
| [`aidc semantic links`](#aidc-semantic-links) | 查对象沿链接连到的对象 |
| [`aidc semantic aggregate`](#aidc-semantic-aggregate) | 计数、求和、平均，或分组统计 |
| [`aidc semantic object-set`](#aidc-semantic-object-set) | 查对象集的一页，或对它做聚合 |
| [`aidc semantic subscribe`](#aidc-semantic-subscribe) | 订阅对象集的变化 |
| [`aidc semantic edits-history`](#aidc-semantic-edits-history) | 看编辑记录 |
| [`aidc semantic apply`](#aidc-semantic-apply) | 执行一个 Action，或只校验它 |
| [`aidc semantic apply-batch`](#aidc-semantic-apply-batch) | 在一个事务里执行多次 Action |
| [`aidc semantic upload-media-content`](#aidc-semantic-upload-media-content) | 上传文件到媒体属性，拿到引用 |
| [`aidc semantic functions list`](#aidc-semantic-functions-list) | 列出已发布的函数 |
| [`aidc semantic functions publish`](#aidc-semantic-functions-publish) | 发布一个函数版本 |
| [`aidc semantic define`](#aidc-semantic-define) | 批量提交定义，写入 main |
| [`aidc semantic archive`](#aidc-semantic-archive) | 归档一个定义 |
| [`aidc semantic publish`](#aidc-semantic-publish) | 发布一个语义版本 |
| [`aidc semantic branch list`](#aidc-semantic-branch-list) | 列出分支 |
| [`aidc semantic branch create`](#aidc-semantic-branch-create) | 新建分支 |
| [`aidc semantic branch show`](#aidc-semantic-branch-show) | 看分支上的改动 |
| [`aidc semantic branch modify`](#aidc-semantic-branch-modify) | 在分支上写入定义，或归档 |
| [`aidc semantic branch validate`](#aidc-semantic-branch-validate) | 校验分支的合并条件 |
| [`aidc semantic branch conflicts`](#aidc-semantic-branch-conflicts) | 看分支与 main 的冲突 |
| [`aidc semantic branch rebase`](#aidc-semantic-branch-rebase) | 把分支跟上 main |
| [`aidc semantic branch discard`](#aidc-semantic-branch-discard) | 放弃分支上的改动 |
| [`aidc semantic branch lock`](#aidc-semantic-branch-lock) | 锁定或解锁分支 |
| [`aidc semantic branch propose`](#aidc-semantic-branch-propose) | 为分支开提案 |
| [`aidc semantic proposals`](#aidc-semantic-proposals) | 列出提案 |
| [`aidc semantic proposal`](#aidc-semantic-proposal) | 看一个提案 |
| [`aidc semantic proposal close`](#aidc-semantic-proposal-close) | 关闭提案 |
| [`aidc semantic proposal approve`](#aidc-semantic-proposal-approve) | 批准提案里的任务 |
| [`aidc semantic proposal reject`](#aidc-semantic-proposal-reject) | 驳回提案里的一个任务 |
| [`aidc semantic proposal merge`](#aidc-semantic-proposal-merge) | 合并提案，进 main |
| [`aidc semantic approval-policy`](#aidc-semantic-approval-policy) | 看或改审批策略 |
| [`aidc semantic security test`](#aidc-semantic-security-test) | 试安全策略：谁看得见哪些对象和属性 |
| [`aidc semantic sql`](#aidc-semantic-sql) | 执行一条只读 SELECT |
| [`aidc semantic database`](#aidc-semantic-database) | 看数据库，或轮换只读直连口令 |
| [`aidc semantic loop-report publish`](#aidc-semantic-loop-report-publish) | 智能体发布或更新一份 Loop 报告 |
| [`aidc semantic loop-report list`](#aidc-semantic-loop-report-list) | 列出本组织的 Loop 报告 |
| [`aidc semantic loop-report history`](#aidc-semantic-loop-report-history) | 看一份报告的变更记录 |
| [`aidc semantic loop-report claim`](#aidc-semantic-loop-report-claim) | 认领一份没有负责智能体的报告 |

## 读定义

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

### aidc semantic ontology

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="看本体全貌"
$ 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)。

### aidc semantic object-types

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名。给了就打印完整定义 | 列出全部 |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="列出类型"
$ aidc semantic object-types
customer                     客户公司
…
$ aidc semantic object-types customer
{
  "apiName": "customer",
  "displayName": "客户公司",
  …
}
```

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

### aidc semantic action-types

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<Action>` | Action 的 API 名。给了就打印完整定义 | 列出全部 |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="列出动作"
$ aidc semantic action-types
adjust-seats                 调整座位数
…
```

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

### aidc semantic interfaces

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<接口>` | 接口的 API 名。给了就打印完整定义 | 列出全部 |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="列出接口"
$ aidc semantic interfaces
Billable                     …
…
```

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

### aidc semantic value-types

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="列出值类型"
$ aidc semantic value-types
customerStage            …  …  enum
…
```

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

### aidc semantic shared-properties

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--branch` | 读这个分支上的定义 | main |

```terminal title="列出共享属性"
$ aidc semantic shared-properties
costUsd                  …  …
…
```

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

### aidc semantic describe

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

```bash
aidc semantic describe [--markdown]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--markdown` | 打印 Markdown 说明书，可以放进智能体的提示词。加了 `--json` 时输出 JSON | 说明摘要 |

```terminal title="看说明书"
$ 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。

```bash
aidc semantic types
```

```terminal title="列出定义"
$ aidc semantic types
object  customer                           客户公司
action  adjust-seats                       调整座位数
```

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

### aidc semantic releases

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

```bash
aidc semantic releases
```

```terminal title="列出版本"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `--where` | 筛选条件。一段 JSON，或一个 `.json` 文件 | 不筛选 |
| `--order-by` | 排序，如 `seats:desc`。多个用逗号分开 | 不指定排序 |
| `--select` | 只取这些属性，用逗号分开 | 不限定 |
| `--page-size` | 一页多少个对象 | 服务端决定 |
| `--page-token` | 接着上一页取。值是上一页给出的令牌 | 第一页 |
| `--branch` | 使用分支上的定义读取 main 的对象数据 | main |

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

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

### aidc semantic object

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `<主键>` | 对象的主键值 | — |
| `--select` | 只取这些属性，用逗号分开 | 不限定 |
| `--branch` | 使用分支上的定义读取 main 的对象数据 | main |

```terminal title="看一个客户"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | 起点对象的 Object Type | — |
| `<主键>` | 起点对象的主键值 | — |
| `<链接>` | 链接的 API 名，如 `agents` | — |
| `--page-size` | 一页多少个对象 | 服务端决定 |
| `--branch` | 使用分支上的定义读取 main 的对象数据 | main |

```terminal title="看链接的对象"
$ aidc semantic links customer cell-demo-a agents
__primaryKey
---
ops-agent
```

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

### aidc semantic aggregate

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名。加 `--interface` 时是接口的 API 名 | — |
| `--select` | 聚合。键是 `$count`，或 `属性:函数`；值是 `unordered`、`asc` 或 `desc` | 必填 |
| `--group-by` | 分组。键是属性名，值见下面的说明 | 不分组 |
| `--where` | 筛选条件，写法同 `objects` | 不筛选 |
| `--interface` | `<类型>` 是接口，统计所有实现它的类型 | 否 |
| `--branch` | 使用分支上的定义读取 main 的对象数据 | main |

```terminal title="付费客户合计"
$ 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` 的每个属性值使用以下格式：

| 格式 | 说明 |
| --- | --- |
| `"exact"` | 按属性值分组 |
| `{"$exactWithLimit": 数量}` | 按属性值分组，限制分组数量 |
| `{"$fixedWidth": 宽度}` | 按固定宽度分组 |
| `{"$ranges": [[起, 止], …]}` | 按指定范围分组 |
| `{"$duration": [数量, "months"]}` | 按指定时长分组 |

时长单位有 `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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<对象集>` | 对象集的定义。一段 JSON，或一个 `.json` 文件 | — |
| `--page-size` | 一页多少个对象 | 服务端决定 |
| `--page-token` | 接着上一页取 | 第一页 |
| `--order-by` | 排序，写法同 `objects` | 不指定排序 |
| `--aggregate` | 对对象集做聚合。JSON 对象，必须有 `$select`，可以有 `$groupBy` | 不聚合 |

```terminal title="对象集计数"
$ aidc semantic object-set '{"type":"base","objectType":"customer"}' --aggregate '{"$select":{"$count":"unordered"}}'
{
  "$count": 6
}
```

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

### aidc semantic subscribe

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `--where` | 筛选条件。只接受 JSON 文字，不接受文件 | 不筛选 |
| `--properties` | 只推送这些属性的值，用逗号分开 | 不限定 |

```terminal title="实时看变化"
$ 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。接入管道时也使用此格式。

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

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

### aidc semantic edits-history

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `--pk` | 只看这个主键的对象 | 全部对象 |
| `--previous` | 每条记录带上改动前的全部属性值。终端只显示摘要，完整内容用 `--json` | 否 |
| `--page-size` | 一页多少条 | 服务端决定 |
| `--branch` | 使用分支上的定义读取 main 的对象数据 | main |

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

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

## 改数据

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

### aidc semantic apply

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<Action>` | Action 的 API 名 | — |
| `--param` | 一个参数，写成 `名=值`。可以重复 | — |
| `--params` | 一个 JSON 对象，装多个参数。`--param` 覆盖同名的值。不接受文件 | — |
| `--validate-only` | 只校验，不执行 | 执行 |
| `--return-edits` | 返回改动的对象数和链接数 | 不返回 |

```terminal title="校验改座位数"
$ aidc semantic apply adjust-seats --param customer=cell-demo-a --param seats=60 --validate-only
✓ 校验通过（没有执行）
```

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

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

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

### aidc semantic apply-batch

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<Action>` | Action 的 API 名 | — |
| `<参数数组>` | 一个 JSON 数组。每项是一次执行的参数对象。最多 20 项。可以是一段 JSON，也可以是 `.json` 文件 | — |
| `--return-edits` | 返回改动的对象和链接 | 不返回 |

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

```terminal title="批量执行"
$ 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` 照样能用。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `<属性>` | 媒体引用属性的 API 名 | — |
| `<文件>` | 要上传的本地文件 | — |
| `--media-item-path` | 文件在媒体集里的路径。同一路径再上传时，旧版本变成历史版本，旧引用仍可读 | 文件名 |
| `--content-type` | 文件的 MIME 类型，如 `text/html` | 不设 |

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

```terminal title="上传文件"
$ 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。

```bash
aidc semantic functions list
```

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

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

### aidc semantic functions publish

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<源码.js>` | 函数的源码，是一个 ES module。默认导出 `(params, ctx) => 结果` | — |
| `--api-name` | 函数名，camelCase | — |
| `--version` | 语义化版本号，如 `1.0.0` | — |
| `--output` | 返回值的类型。一段 JSON，或一个 `.json` 文件，如 `'{"type":"integer"}'` | — |
| `--parameters` | 参数的定义。一段 JSON，或一个 `.json` 文件 | `{}` |
| `--edit-function` | 加上后，这个函数是编辑函数。不加就是查询函数 | 查询函数 |
| `--display-name` | 显示名 | — |
| `--description` | 说明 | — |
| `--timeout-ms` | 运行超时，单位毫秒 | 服务端决定 |
| `--dry-run` | 只校验，不发布 | 发布 |

```terminal title="发布函数"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<文件.json\|目录>` | 一个 `.json` 文件（对象或数组），或一个目录。目录里所有 `.json` 按文件名排序后提交 | — |
| `--dry-run` | 只校验，不写入 | 写入 |

```terminal title="先试跑"
$ 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`。定义的写法见 [定义本体](ontology.md)。
- 定义里写了不认识的字段，定义会被拒。错误信息给出字段的路径。
- 定义有破坏性改动时，输出行末写「⚠ 破坏性」。
- 智能体直接写入 main 会返回 409（`branch_required`），退出码是 6。使用 `--dry-run` 可以校验而不写入。智能体要用分支，见 [建本体：分支与提案](#建本体分支与提案)。
- 定义写入后，用 [`aidc semantic publish`](#aidc-semantic-publish) 发布语义版本。

### aidc semantic archive

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<apiName>` | 要归档的定义的 API 名 | — |
| `--dry-run` | 只预演，不归档 | 归档 |

```terminal title="归档定义"
$ aidc semantic archive customerAgents
已归档 customerAgents
```

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

### aidc semantic publish

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--notes` | 版本说明，写进版本记录 | — |

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

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

## 建本体：分支与提案

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

设 `AIDC_AGENT_ID=<智能体 id>` 后，作者记为这个智能体（见 [在 CI 和智能体里用](cli.md#在-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-approval-policy)，决定由谁批准、谁合并。

### aidc semantic branch list

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

```bash
aidc semantic branch list
```

```terminal title="列出分支"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<分支>` | 分支名 | — |
| `--description` | 分支的说明 | — |

```terminal title="新建分支"
$ 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。

```bash
aidc semantic branch show <分支>
```

```terminal title="看分支改动"
$ aidc semantic branch show add-department
add-department  …  v4  基线 v12  作者 agent:ops-agent
  ± object department
```

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

### aidc semantic branch modify

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<分支>` | 分支名 | — |
| `<文件.json\|目录>` | 要写入的定义，写法同 `define`。这些定义会新增或覆盖 | 不写入 |
| `--archive` | 要归档的定义的 API 名，用逗号分开 | 不归档 |
| `--expected-version` | 分支的版本必须是这个数，才写入 | 不检查 |
| `--dry-run` | 只试跑，给出校验结果，不写入 | 写入 |

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

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

```terminal title="写入分支"
$ 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。

```bash
aidc semantic branch validate <分支>
```

```terminal title="校验分支"
$ aidc semantic branch validate add-department
校验 VALID
  …
  ✓ reference_closure
  …
  ✓ api_names
  …
```

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

### aidc semantic branch conflicts

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

```bash
aidc semantic branch conflicts <分支>
```

```terminal title="看冲突"
$ aidc semantic branch conflicts add-department
没有冲突。
```

- 每个冲突一行。行首的 `✗` 后面是 API 名和原因。
- 有冲突时，用 [`aidc semantic branch rebase`](#aidc-semantic-branch-rebase) 处理。

### aidc semantic branch rebase

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--keep` | 冲突的定义保留分支上的版本 | — |
| `--take-main` | 冲突的定义取 main 上的版本 | — |

```terminal title="跟上 main"
$ aidc semantic branch rebase add-department --take-main customer
已 rebase 到 v13
```

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

### aidc semantic branch discard

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

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

```terminal title="放弃改动"
$ aidc semantic branch discard add-department department
已放弃 department 改动
```

### aidc semantic branch lock

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

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

```terminal title="锁定分支"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<分支>` | 要提案的分支 | — |
| `--title` | 提案的标题 | 必填 |
| `--trigger` | 触发原因：哪个问题答不出，或接了哪个新数据源 | 必填 |
| `--self-test` | 自测结果，如「分支上能答：3 个」 | — |
| `--description` | 提案的说明 | — |

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

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

### aidc semantic proposals

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--status` | 只看这个状态的提案 | 全部 |

```terminal title="列出提案"
$ aidc semantic proposals --status OPEN
● cm2kb7q4e0004qz7d5w1b8x4n  加部门对象类型  分支 add-department  作者 agent:ops-agent
```

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

### aidc semantic proposal

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

```bash
aidc semantic proposal <提案>
```

```terminal title="看提案"
$ 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。

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

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

### aidc semantic proposal approve

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<提案>` | 提案的 id | — |
| `<任务>` | 要批准的任务名（API 名），可以写多个 | 全部待审核的任务 |
| `--note` | 审核说明，写进审核记录 | — |
| `--confirm-breaking` | 批准破坏性改动时必须加。加上后，命令用任务名逐个确认 | — |

```terminal title="批准一个任务"
$ aidc semantic proposal approve cm2kb7q4e0004qz7d5w1b8x4n department --note "字段名没问题"
✓ 批准了 department（1/2 已批准）
```

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

### aidc semantic proposal reject

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

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

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

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

### aidc semantic proposal merge

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

```bash
aidc semantic proposal merge <提案>
```

```terminal title="合并提案"
$ aidc semantic proposal merge cm2kb7q4e0004qz7d5w1b8x4n
✓ 已合并提案 cm2kb7q4e0004qz7d5w1b8x4n：语义版本 v13
```

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

### aidc semantic approval-policy

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

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `get` | 看当前的策略 | 看 |
| `set` | 改成 `review` 或 `yolo` | — |
| `--dry-run` | 只看会变什么，不改 | 改 |

| 策略 | 谁能批准、合并 | 作者自己的批准 | 检查通过后 |
| --- | --- | --- | --- |
| `review`（缺省） | 本组织开发者，在网页上 | 不算数 | 等人点合并 |
| `yolo` | 网页登录，加上能改这个本体的开发者 Key 或 Agent Key | 算数 | 自动合并 |

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

```terminal title="预演改策略"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API 名 | — |
| `--user` | 按这个账号试。值是账号 id | 当前调用者 |
| `--pk` | 真实对象的主键，用逗号分开 | — |
| `--object` | 假设的对象。一段 JSON，或一个 `.json` 文件。可以重复 | — |
| `--policy` | 要试的策略。一段 JSON，或一个 `.json` 文件 | 保存的策略 |

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

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

```terminal title="试安全策略"
$ 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 与数据库 · 选方言](sql.md#选方言)。

```bash
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]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `"<SELECT …>"` | 一条 SELECT 语句。可以用 `WITH`、`VALUES` 或 `TABLE` 开头 | — |
| `--file` | 从文件读语句 | — |
| `--dialect` | `postgres` 或 `spark` | `postgres` |
| `--param` | 位置参数。Postgres 方言替换 `$1`、`$2` …，标准方言替换 `?`。每写一次是一个值 | — |
| `--named` | 标准方言的命名参数，写成 `名=值`，替换 `:名`。不能和 `--param` 一起用 | — |
| `--row-limit` | 最多返回的行数。上限是 10,000 行 | 服务端决定 |
| `--explain` | 不执行。Postgres 方言输出查询计划，标准方言只校验并列出结果的列 | 执行 |
| `--csv` | 输出 CSV，不带行数统计 | 表格 |
| `--arrow` | 标准方言：把 Arrow 结果原样存进这个文件 | — |

```terminal title="查付费客户"
$ 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）
```

```terminal title="导出 CSV"
$ 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`](#aidc-semantic-apply)。
- 结果超过 `--row-limit` 时，最后一行写「截断到」和上限的行数。
- 角色 `reader` 能看见本组织的全部类型。角色 `public` 只能看见授予了所有人的类型。
- `--param` 和 `--named` 的值：整数、小数、`true`、`false`、`null` 按 JSON 解析。写回原样会变的值按字符串传，例如 `007`、`1.50`。值里的逗号保留。
- 表和列的名字，用 [`aidc semantic database`](#aidc-semantic-database) 查看。

```terminal title="标准方言"
$ 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。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--sync` | 按当前的定义重建视图 | 只看 |
| `--rotate` | 轮换只读直连的口令。新口令只显示这一次 | 只看 |

```terminal title="看数据库"
$ aidc semantic database
schema ont_… · 我用 reader 角色 · …
  表  customer                     4 列  客户公司
直连：…@…:…/…（口令用 aidc semantic database --rotate 拿）
```

```terminal title="轮换口令"
$ 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 报告。报告不存在时新建，存在且归你负责时更新。

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

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<文件.html>` | 报告的 HTML 文件 | — |
| `--slug` | 报告的地址名：小写字母、数字、连字符，3–96 个字符 | — |
| `--title` | 标题，最多 120 个字 | — |
| `--description` | 说明，最多 500 个字 | 不改 |
| `--data-date` | 数据日期 | 不改 |
| `--owner-name` | 负责智能体的显示名，最多 40 个字 | Key 对应的智能体 |
| `--dry-run` | 只看要执行哪个 Action，不上传 | — |

```terminal title="发布日报"
$ 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` 只列你负责的。

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

```terminal title="我负责的报告"
$ 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 位。

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

```terminal title="变更记录"
$ 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

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

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

```terminal title="认领报告"
$ aidc semantic loop-report claim daily-output --owner-name "Demo Agent"
已认领 daily-output
```

## 下一步

- [定义本体](ontology.md)：本体的概念，定义文件的写法，审批策略。
- [读写对象](data.md)：读对象，订阅变化，用 Action 改数据。
- [SQL 与数据库](sql.md)：用 SQL 查对象，直连数据库。
- [访问与安全](auth.md)：谁能看见对象，Marking 与安全策略。

命令迁移见 [旧写法与迁移](migration.md)。