# 参考 · 数据接入

本页介绍五组数据接入命令。

- 数据流（`streams`）。
- 数据源（`datasource`）。
- Data Connection（`connectivity`）。
- 加工（`transforms`）。
- 媒体集（`media-sets`）。

数据流、数据源、Data Connection 和加工的命令要本组织的 developer（网页会话或开发者 Key），发布端的 `pipe` 除外。媒体集的权限沿 Ontology 继承，见 [媒体集](#aidc-semantic-media-sets) 组的说明。

> [!NOTE]
> 前提：已登录（`aidc login`）。除 `aidc login`、`aidc logout`、`aidc update` 外，每条命令都要先登录。设置 `AIDC_PUBLISH_KEY` 的 `aidc semantic streams pipe` 无需先登录。通用参数（`--json`、`--dry-run`、`--api`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)。输出格式见 [输出](cli.md#输出给人看也给程序读)，退出码见 [退出码](cli.md#退出码)。`-n` 缺省是登录的组织。
>
> 用法里 `<…>` 是要你填的值，`[…]` 是可选项，`|` 表示二选一，`…` 表示可以重复。占位符：`<流名>` 是数据流的名字，或 `<命名空间>/<流名>`；`<类型>` 是 Object Type 的 API name，如 `production.order_line`；`<cell-…>` 是组织的命名空间，如 `cell-demo`；`<文件>` 是本机的文件路径；`…RID` 是平台对象的 RID，以 `ri.` 开头，如 `<connectionRid>` 和 `<媒体集 RID>`。用对应的 `list` 或 `agents` 类命令查。

| 命令 | 做什么 |
| --- | --- |
| [`aidc semantic streams create`](#aidc-semantic-streams-create) | 声明一条数据流 |
| [`aidc semantic streams list`](#aidc-semantic-streams-list) | 列出数据流和发布端状态 |
| [`aidc semantic streams status`](#aidc-semantic-streams-status) | 看一条数据流的状态和订阅地址 |
| [`aidc semantic streams get`](#aidc-semantic-streams-get) | 打印数据流当前的状态 |
| [`aidc semantic streams tail`](#aidc-semantic-streams-tail) | 订阅变化，每次变化打一行 |
| [`aidc semantic streams delete`](#aidc-semantic-streams-delete) | 删除数据流和它的发布 Key |
| [`aidc semantic streams key`](#aidc-semantic-streams-key) | 签一把发布 Key |
| [`aidc semantic streams keys`](#aidc-semantic-streams-keys) | 列出发布 Key |
| [`aidc semantic streams revoke`](#aidc-semantic-streams-revoke) | 吊销一把发布 Key |
| [`aidc semantic streams publish`](#aidc-semantic-streams-publish) | 发布事件 |
| [`aidc semantic streams pipe`](#aidc-semantic-streams-pipe) | 常驻运行发布端 |
| [`aidc semantic datasource list`](#aidc-semantic-datasource-list) | 列出数据源和同步进度 |
| [`aidc semantic datasource set`](#aidc-semantic-datasource-set) | 把数据流接到 Object Type |
| [`aidc semantic datasource remove`](#aidc-semantic-datasource-remove) | 去掉一条数据源 |
| [`aidc semantic datasource resync`](#aidc-semantic-datasource-resync) | 重新同步一条数据源 |
| [`aidc semantic datasource sync`](#aidc-semantic-datasource-sync) | 立即同步平台上的数据源 |
| [`aidc semantic connectivity agents`](#aidc-semantic-connectivity-agents) | 列出 agent |
| [`aidc semantic connectivity connections`](#aidc-semantic-connectivity-connections) | 列出数据源连接 |
| [`aidc semantic connectivity agent register`](#aidc-semantic-connectivity-agent-register) | 登记 agent，给一次性凭证 |
| [`aidc semantic connectivity agent upgrade`](#aidc-semantic-connectivity-agent-upgrade) | 把旧版 agent 箱子升级为 agent proxy |
| [`aidc semantic connectivity egress list`](#aidc-semantic-connectivity-egress-list) | 列出出口策略 |
| [`aidc semantic connectivity egress create`](#aidc-semantic-connectivity-egress-create) | 建出口策略 |
| [`aidc semantic connectivity egress show`](#aidc-semantic-connectivity-egress-show) | 看一条出口策略 |
| [`aidc semantic connectivity egress revoke`](#aidc-semantic-connectivity-egress-revoke) | 吊销一条出口策略 |
| [`aidc semantic connectivity connection`](#aidc-semantic-connectivity-connection) | 建或更新数据源连接 |
| [`aidc semantic connectivity config`](#aidc-semantic-connectivity-config) | 看连接的配置，秘密只显示名字 |
| [`aidc semantic connectivity secret`](#aidc-semantic-connectivity-secret) | 换一个秘密（口令）的值 |
| [`aidc semantic connectivity migrate`](#aidc-semantic-connectivity-migrate) | 把连接迁到平台的 worker |
| [`aidc semantic connectivity revert-migration`](#aidc-semantic-connectivity-revert-migration) | 退回迁移（30 天内） |
| [`aidc semantic connectivity explore`](#aidc-semantic-connectivity-explore) | 看源数据库的表、结构和样本 |
| [`aidc semantic connectivity imports`](#aidc-semantic-connectivity-imports) | 列出表导入 |
| [`aidc semantic connectivity import`](#aidc-semantic-connectivity-import) | 建或更新一张表的导入 |
| [`aidc semantic connectivity execute`](#aidc-semantic-connectivity-execute) | 执行一次导入 |
| [`aidc semantic connectivity build`](#aidc-semantic-connectivity-build) | 看一次构建的结果 |
| [`aidc semantic connectivity dataset`](#aidc-semantic-connectivity-dataset) | 打印数据集的当前内容（CSV） |
| [`aidc semantic connectivity health create`](#aidc-semantic-connectivity-health-create) | 建一个数据健康检查 |
| [`aidc semantic connectivity health show`](#aidc-semantic-connectivity-health-show) | 看一个检查的定义 |
| [`aidc semantic connectivity health replace`](#aidc-semantic-connectivity-health-replace) | 替换一个检查的定义 |
| [`aidc semantic connectivity health delete`](#aidc-semantic-connectivity-health-delete) | 删除一个检查 |
| [`aidc semantic connectivity health reports`](#aidc-semantic-connectivity-health-reports) | 看检查最近的评估结果 |
| [`aidc semantic connectivity webhooks`](#aidc-semantic-connectivity-webhooks) | 列出 REST 数据源上的 webhook |
| [`aidc semantic connectivity webhook put`](#aidc-semantic-connectivity-webhook-put) | 建或更新一个 webhook |
| [`aidc semantic connectivity webhook get`](#aidc-semantic-connectivity-webhook-get) | 看一个 webhook 的定义 |
| [`aidc semantic connectivity webhook delete`](#aidc-semantic-connectivity-webhook-delete) | 删除一个 webhook |
| [`aidc semantic connectivity webhook test`](#aidc-semantic-connectivity-webhook-test) | 手动执行一个 webhook |
| [`aidc semantic transforms list`](#aidc-semantic-transforms-list) | 列出加工定义 |
| [`aidc semantic transforms put`](#aidc-semantic-transforms-put) | 建或替换一个加工定义 |
| [`aidc semantic transforms show`](#aidc-semantic-transforms-show) | 看加工定义和上次构建 |
| [`aidc semantic transforms build`](#aidc-semantic-transforms-build) | 构建一次加工 |
| [`aidc semantic transforms delete`](#aidc-semantic-transforms-delete) | 删除一个加工定义 |
| [`aidc semantic media-sets list`](#aidc-semantic-media-sets-list) | 列出媒体集 |
| [`aidc semantic media-sets show`](#aidc-semantic-media-sets-show) | 看一个媒体集的详情 |
| [`aidc semantic media-sets create`](#aidc-semantic-media-sets-create) | 建一个媒体集 |
| [`aidc semantic media-sets items`](#aidc-semantic-media-sets-items) | 列出媒体项 |
| [`aidc semantic media-sets upload`](#aidc-semantic-media-sets-upload) | 上传一个文件 |
| [`aidc semantic media-sets sync`](#aidc-semantic-media-sets-sync) | 登记虚拟媒体集里的新文件 |
| [`aidc semantic media-sets metadata`](#aidc-semantic-media-sets-metadata) | 看媒体项的元数据 |
| [`aidc semantic media-sets download`](#aidc-semantic-media-sets-download) | 下载一个媒体项 |
| [`aidc semantic media-sets text`](#aidc-semantic-media-sets-text) | 取 PDF 或 TXT 的全文 |
| [`aidc semantic media-sets clear`](#aidc-semantic-media-sets-clear) | 软删一个路径 |
| [`aidc semantic media-sets retention`](#aidc-semantic-media-sets-retention) | 改保留策略 |
| [`aidc semantic media-sets transaction open`](#aidc-semantic-media-sets-transaction-open) | 开一个事务 |
| [`aidc semantic media-sets transaction commit`](#aidc-semantic-media-sets-transaction-commit) | 提交一个事务 |
| [`aidc semantic media-sets transaction abort`](#aidc-semantic-media-sets-transaction-abort) | 放弃一个事务 |

## aidc semantic streams

数据流接收发布端推来的变化，按序保存，再推给订阅端。这一组管声明、发布 Key、读取和删除。

`create`、`list`、`status`、`get`、`tail`、`delete`、`key`、`keys`、`revoke` 和 `publish` 要 developer。`pipe` 要发布 Key，或 developer 的登录。数据流的协议和订阅方式见 [数据接入](connect.md)。

### aidc semantic streams create

声明一条数据流：名字、显示名、字段白名单和主键。要 developer。

```bash
aidc semantic streams create <流名> [--title <标题>] [--field <名:类型[:显示名]>…] [--key <主键>] [--summary <说明>] [--retention <条数>] [--spec <文件.json>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字。`--spec` 文件里有 `name` 时可以不写 | — |
| `--title` | 显示名 | 同 `<流名>` |
| `--field` | 字段，写成 `名:类型[:显示名]`。可以重复，也可以用逗号分隔。省略类型时是 `string` | — |
| `--key` | 主键字段的名字。有主键的流发布 `rows`，没有主键的流发布 `value` | 没有主键 |
| `--summary` | 说明 | — |
| `--retention` | 保留的事件条数。订阅端断线后，靠它补齐漏掉的事件 | 1000 |
| `--spec` | JSON 文件。键名和参数对应，`fields` 对应 `--field`。命令行参数优先 | — |
| `--dry-run` | 只预演，不创建 | — |

字段的类型可以是 `string`、`number`、`boolean`、`datetime` 或 `json`。至少要有一个字段：用 `--field`，或在 `--spec` 文件里写 `fields`。

```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 "装在哪"
```

同名的数据流再声明一次，会按新的定义更新。定义没有变化时，输出以「无变化：」开头。`--json` 输出 `created`、`changed`、`dryRun` 和 `stream`。

### aidc semantic streams list

列出组织的全部数据流，和每条流的发布端状态。要 developer。

```bash
aidc semantic streams list
```

这条命令没有参数。

```terminal title="列出数据流"
$ aidc semantic streams list
cell-demo/orders  在手订单  seq 128  3 行  ● 在线  正常  最近 2026-10-08T14:03:12
```

每条流一行：名字、显示名、序号、行数，然后是发布端状态。「● 在线」表示 90 秒内收到过心跳，「○ 离线」表示没有。发布端状态有五种：正常、部分异常、连不上数据源、已停止、从未发布。没有数据流时，命令打印「还没有数据流」。

### aidc semantic streams status

看一条数据流的显示名、发布端状态、序号、行数、字段和订阅地址。要 developer。

```bash
aidc semantic streams status <流名>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |

```terminal title="看数据流状态"
$ aidc semantic streams status orders
在手订单（cell-demo/orders）
  发布端  ● 在线  正常  最近 2026-10-08T14:03:12
  序号 128 · 3 行 · 4.2 KB · 保留 1000 条事件
  字段    order_no:string  qty:number  due:datetime（主键 order_no）
  订阅    https://www.ai-dc.ai/api/v1/developer/streams/cell-demo/orders/events
```

「订阅」是订阅地址。这个地址按 `Accept` 请求头返回 SSE 或 JSON 增量。加 `?after=<序号>` 可以从这个序号之后续传。`--json` 输出 `{ stream }`。

### aidc semantic streams get

打印数据流当前的状态。有主键的流打印全部行，没有主键的流打印那个值。要 developer。

```bash
aidc semantic streams get <流名>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |

```terminal title="读当前状态"
$ aidc semantic streams get orders
[
  {
    "order_no": "SO-1001",
    "qty": 12,
    "due": "2026-10-20"
  }
]
```

输出只有状态，没有发布端信息。`--json` 时输出完整的 `{ stream, state }`。

### aidc semantic streams tail

订阅一条数据流。每次变化打印一行，按 Ctrl-C 结束。要 developer。

```bash
aidc semantic streams tail <流名>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |

```terminal title="订阅变化"
$ aidc semantic streams tail orders
连接 connecting
连接 live · 发布端 ● 在线  正常  最近 2026-10-08T14:03:12
14:03:40  seq 128  全量 3 行
14:05:01  seq 129  变化 +1 / -0（共 3 行）  源端 14:04:58
```

- 第一次连上时打印一行「全量」。之后每次变化打印一行「变化」。收到通知时打印 `通知 <JSON>`。
- 时间是 UTC。连接状态和发布端状态写到标准错误输出（stderr）。
- `--json` 时，每行是一个 JSON 对象。`type` 是 `state`（全量）、`patch`（变化）或 `notice`（通知）。
- 订阅出错，且错误是 403 或 404 时，命令打印错误并结束，退出码是 0。

### aidc semantic streams delete

删除一条数据流。它的事件、最新状态和全部发布 Key 都被删掉。要 developer。

```bash
aidc semantic streams delete <流名> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |
| `--dry-run` | 只预演，不删除 | — |

> [!WARNING]
> 删除不能撤回。事件和最新状态都没有了，发布 Key 全部吊销。

```terminal title="先预演"
$ aidc semantic streams delete orders --dry-run
（dry-run）将删除 cell-demo/orders：128 条事件的账与状态，吊销 1 把发布 Key
```

还有 Object Type 的数据源在用这条流时，删除被拒绝，返回 409，退出码是 6。先用 [`aidc semantic datasource remove`](#aidc-semantic-datasource-remove) 去掉数据源，再删除。

### aidc semantic streams key

给数据流签一把发布 Key（`aidc-pk-…`）。这把 Key 只能往这一条流发布。要 developer。

```bash
aidc semantic streams key <流名> --label <装在哪>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |
| `--label` | 发布 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 后，用 [`keys`](#aidc-semantic-streams-keys) 查前缀。用 [`revoke`](#aidc-semantic-streams-revoke) 吊销旧 Key。然后签发新 Key。`--json` 输出 `key` 和 `keyPrefix`。

### aidc semantic streams keys

列出一条数据流的发布 Key。只显示前缀，不显示完整的 Key。要 developer。

```bash
aidc semantic streams keys <流名>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |

```terminal title="列发布 Key"
$ aidc semantic streams keys orders
✓ aidc-pk-7f3a1c2e  工厂服务器 · 订单发布端  签发 2026-10-08T09:12  最近 2026-10-08T14:03
✗ aidc-pk-0b9d4e51  测试机  签发 2026-10-07T16:40  未使用
```

`✓` 表示有效的 Key，`✗` 表示已吊销的 Key。没有 Key 时，命令打印「还没有发布 Key」。

### aidc semantic streams revoke

吊销一把发布 Key。吊销后，这把 Key 不能再往这条流发布。要 developer。

```bash
aidc semantic streams revoke <流名> --prefix <前缀>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |
| `--prefix` | 要吊销的 Key 的前缀，如 `aidc-pk-0b9d4e51`。用 [`keys`](#aidc-semantic-streams-keys) 查看 | 必填 |

```terminal title="吊销 Key"
$ aidc semantic streams revoke orders --prefix aidc-pk-0b9d4e51
已吊销 aidc-pk-0b9d4e51
```

### aidc semantic streams publish

往一条数据流发布事件。要 developer。发布端常驻运行时，用 [`pipe`](#aidc-semantic-streams-pipe)，它读发布 Key。

```bash
aidc semantic streams publish <流名> --event '<JSON>' | --file <事件.json>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 数据流的名字 | — |
| `--event` | 一个事件，或事件的数组，写成 JSON | — |
| `--file` | 从文件读事件。内容和 `--event` 相同 | — |

每个事件有 `type` 和 `data`。`type` 是 `event`、`snapshot`、`patch` 或 `status`。`id` 可以不写，SDK 会自动生成。`--event` 和 `--file` 同时给时，用 `--event`。

```terminal title="发一个事件"
$ aidc semantic streams publish orders --event '{"type":"event","data":{"order_no":"SO-1002","message":"新合同"}}'
已发布：1 条（重复 0，心跳 0）→ seq 130
```

### aidc semantic streams pipe

常驻运行发布端：读适配器输出的 JSON 行，只发变化，并定时心跳。要发布 Key（环境变量 `AIDC_PUBLISH_KEY`），或 developer 的登录。

```bash
AIDC_PUBLISH_KEY=aidc-pk-… aidc semantic streams pipe <流名> [--heartbeat <秒>] [--full-every <分钟>] [--stale-after <分钟>] -- <适配器命令…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<流名>` | 要发布到的数据流。写成 `<命名空间>/<流名>` 最清楚 | — |
| `--heartbeat` | 心跳的间隔，单位是秒。每次心跳会重发发布端的状态，订阅端靠它知道发布端还在 | 30 |
| `--full-every` | 全量快照的间隔，单位是分钟。两次全量之间只发变化 | 360 |
| `--stale-after` | 适配器多久没有输出，就报「部分异常」，单位是分钟 | 15 |
| `-- <适配器命令…>` | 适配器的命令。`--` 后面的内容原样交给适配器。选项要写在 `--` 前面 | — |

发布 Key 只从环境变量 `AIDC_PUBLISH_KEY` 读。不要把 Key 写进命令行参数。

```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）
2026-10-08T14:03:42 忽略适配器输出（不是 JSON）：Traceback (most recent call last):
```

适配器是一个常驻进程，任何语言都可以写。它每行向标准输出打印一个 JSON 对象：

| 一行 | 含义 |
| --- | --- |
| `{"rows":[…]}` | 有主键的流的全表。发布端和上一次比较，只发变化的行 |
| `{"value":{…}}` | 没有主键的流的整体值。变了才发 |
| `{"event":{…}}` | 通知。直接发布 |
| `{"status":"ok"}` | 适配器的健康状态。值是 `ok`、`degraded` 或 `source_unreachable`，可以带 `detail` |

发布端的行为：

- 第一次发布全量快照。之后按主键算差，只发变化。
- 发布失败时，按 1、2、4 秒……的间隔重试，最长 30 秒。同一批事件带同一组 ID，服务端不会收两次。
- 发布端忽略非 JSON 行，并记录一条日志。
- 适配器退出后，按退避时间重启，最长间隔 60 秒。同时报「连不上数据源」，附上标准错误输出的最后三行。
- 服务端拒收一批（字段不在白名单里）时，丢掉这一批，状态报「部分异常」。
- 发布 Key 被吊销，或流被删除（返回 401、403 或 404）时，发布端停止，退出码是 1。
- 按 Ctrl-C 或 SIGTERM 停止时，发布端报「已停止」，最多等 10 秒把积压的事件发完，退出码是 0。

适配器应该每一轮至少打一行 `status`。超过 `--stale-after` 没有任何输出，发布端会报「部分异常」。

```python
# orders_adapter.py：每 30 秒读一次数据源，每行打印一个 JSON
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 semantic datasource

数据源把数据流接到 Object Type 上。数据源是 Object Type 定义的一部分，所以改数据源就是改本体。`set`、`remove`、`resync` 和 `sync` 要 developer。智能体（设了 `AIDC_AGENT_ID`）要在分支上改，见 [定义本体](ontology.md)。

### aidc semantic datasource list

列出数据源和它的同步进度。要 developer。

```bash
aidc semantic datasource list [<类型>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | 只看这个 Object Type 的数据源 | 全部 |

```terminal title="看数据源"
$ aidc semantic datasource list
● production.order_line        ← orders  mirror  同步到 seq 130
```

每条数据源一行。`●` 表示数据源正常，`✗` 表示数据源停用。「（落后 N）」表示同步落后 N。没有数据源时，命令打印「还没有数据源」和 `set` 的用法。

### aidc semantic datasource set

把一条数据流接到 Object Type。命令把数据源写进类型定义，然后用流的当前数据做一次首次同步。要 developer。

```bash
aidc semantic datasource set <类型> --stream <流名> --map <属性=列>… [--mode upsert|mirror] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API name | — |
| `--stream` | 数据流的名字 | — |
| `--map` | 属性对应流里的哪一列，写成 `属性=列`。可以重复，也可以用逗号分隔。主键属性必须映射 | — |
| `--mode` | `upsert`：按主键增改，不删对象。`mirror`：流里没有了的行，对象标记为「源头已消失」 | `upsert` |
| `--dry-run` | 只预演，不写定义 | — |

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

- 同一条数据源已经存在时，输出是「更新数据源」。
- 映射到的列必须在流里。
- 智能体（设了 `AIDC_AGENT_ID`）改数据源要走分支。服务端返回 `branch_required` 时，见 [定义本体](ontology.md)。

### aidc semantic datasource remove

从 Object Type 的定义里去掉一条数据源。对象保留，同步停止。要 developer。

```bash
aidc semantic datasource remove <类型> --stream <流名> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API name | — |
| `--stream` | 要去掉的数据流的名字 | — |
| `--dry-run` | 只预演，不写定义。输出的文字和真正执行时相同 | — |

```terminal title="去掉数据源"
$ aidc semantic datasource remove production.order_line --stream orders
已从 production.order_line 的定义里去掉数据源 orders（对象保留）
```

找不到这条数据源时，退出码是 5。

### aidc semantic datasource resync

用数据流的当前数据，重新同步一条数据源。要 developer。

```bash
aidc semantic datasource resync <类型> --stream <流名>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<类型>` | Object Type 的 API name | — |
| `--stream` | 数据流的名字 | — |

```terminal title="重新同步"
$ aidc semantic datasource resync production.order_line --stream orders
重同步：变化 3 个
```

有行没映射上时，输出多一段「、N 行没映射上」。

### aidc semantic datasource sync

立即同步平台上的数据源。它和 `/semantic` 页面上的「立即同步」按钮做同一件事。要 developer。

```bash
aidc semantic datasource sync
```

这条命令没有参数。

```terminal title="立即同步"
$ aidc semantic datasource sync
已同步平台数据源：production.order_line 3 个（变化 1）（跳过 production.line）
```

AIDC 组织还会同步 AWS 数据源。这时输出多一行，以「AWS：」开头。

## aidc semantic connectivity

Data Connection 让平台直接读数据库。平台的 worker 用只读账号执行 SQL，结果写进数据集，只把变了的行写成对象。客户内网的数据库经 agent proxy 连接。这一组的读和写都要本组织的 developer（网页会话或开发者 Key）。`agent upgrade` 只给平台运维。

接一个数据库的顺序是：

1. `agent register`：客户内网要有 agent 时，先登记。
2. `egress create`：允许平台连的主机和端口。
3. `connection`：建数据源连接（Connection）。
4. `explore`：看源里有哪些表。
5. `import`：建一张表的导入（TableImport）。
6. `execute`：执行导入。

设计见 [数据管道](pipeline.md)。旧版 agent worker 的说明见 [旧写法与迁移](migration.md)。自动化（Automate）的命令见 [参考 · 访问、自动化与用量](cli-govern.md)。

### aidc semantic connectivity agents

列出 agent。agent 是装在客户网络里的 agent proxy，只出站连接平台。要 developer。

```bash
aidc semantic connectivity agents --ontology <cell-…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间，如 `cell-demo` | 必填 |

```terminal title="列出 agent"
$ aidc semantic connectivity agents --ontology cell-demo
site-box                 online   工厂机房
  ri.…
```

每个 agent 两行：API name、状态、显示名，然后是 RID。没有 agent 时，命令打印「没有。」

### aidc semantic connectivity connections

列出数据源连接（Connection）。每个外部数据库或 REST 服务是一个连接。要 developer。

```bash
aidc semantic connectivity connections --ontology <cell-…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间，如 `cell-demo` | 必填 |

```terminal title="列出连接"
$ aidc semantic connectivity connections --ontology cell-demo
erp-sqlserver            active   ERP 数据库（只读）
  ri.…
```

输出格式和 [`agents`](#aidc-semantic-connectivity-agents) 相同。

### aidc semantic connectivity agent register

登记一个 agent proxy，并给出一次性的凭证和三条安装命令。要 developer。

```bash
aidc semantic connectivity agent register --ontology <cell-…> --api-name <名字> --display-name <显示名> [--rotate-token] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--api-name` | agent 的 API name，如 `site-box` | 必填 |
| `--display-name` | 显示名，如 `工厂机房` | 必填 |
| `--rotate-token` | 发一把新凭证 | 已有凭证时不发 |
| `--dry-run` | 只预演，不登记 | — |

```terminal title="登记 agent"
$ aidc semantic connectivity agent register --ontology cell-demo --api-name site-box --display-name 工厂机房
已登记：工厂机房（agentProxy）
  ri.…
凭证（只显示这一次）：…
在客户网络里的机器上：
  …安装命令…
  …配置命令…   # 粘贴上面的凭证（不回显）
  …服务命令…
```

凭证只显示一次。agent 已经有凭证，又没写 `--rotate-token` 时，命令不发新凭证。`--dry-run` 的输出会说明会不会发新凭证。`mode` 为 `agentProxy` 或 `agentWorker`。有 `host` 的 agent 返回 `agentWorker`，否则返回 `agentProxy`。

### aidc semantic connectivity agent upgrade

把旧版 agent 的箱子就地升级为 agent proxy。平台经 AWS SSM 下发一次性的登记码，箱子自己换凭证，凭证不经过人手。只给平台运维，本组织的 developer 不用它。

```bash
aidc semantic connectivity agent upgrade <agent RID 或 API name> --ontology <cell-…> [--wait] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<agent RID 或 API name>` | 要升级的 agent | 必填 |
| `--ontology` | 组织的命名空间 | 必填 |
| `--wait` | 等 agent 连上平台，最多 3 分钟 | 不等 |
| `--dry-run` | 只预演，不下发 | — |

```terminal title="预演升级"
$ aidc semantic connectivity agent upgrade site-box --ontology cell-demo --wait --dry-run
预演：工厂机房 → <实例 ID>（<区域>），以 <用户> 运行，装在 <目录>
```

`--wait` 等不到 agent 连上时，退出码是 1。

### aidc semantic connectivity egress list

列出出口策略。出口策略规定平台可以连接哪些目的地。要 developer。

```bash
aidc semantic connectivity egress list --ontology <cell-…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |

```terminal title="列出出口"
$ aidc semantic connectivity egress list --ontology cell-demo
erp-db-egress            agentProxy active  erp-db.example.com:1433 · 经 1 个 agent
  ri.…
```

每条策略一行：名字、类型、状态、目的地和端口。类型 `direct` 是平台直连。类型 `agentProxy` 是经 agent 连接。目的地可以是域名、IP 或 CIDR。域名只有最左边一段可以用通配符。没有策略时，命令打印「还没有出口策略」和 `create` 的用法。

### aidc semantic connectivity egress create

建一条出口策略。策略允许平台连接一个目的地的一个端口，或一段端口。要 developer。

```bash
aidc semantic connectivity egress create --ontology <cell-…> --file <策略.json> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--file` | 策略的 JSON 文件。字段照 API 的请求体 | 必填 |
| `--dry-run` | 只预演，不建 | — |

```json
{
  "apiName": "erp-db-egress",
  "displayName": "ERP 数据库",
  "type": "agentProxy",
  "address": { "type": "dns", "value": "erp-db.example.com" },
  "ports": { "type": "single", "port": 1433 },
  "agents": ["site-box"]
}
```

```terminal title="建出口策略"
$ aidc semantic connectivity egress create --ontology cell-demo --file erp-via-agent.json
已建：erp-db-egress            agentProxy active  erp-db.example.com:1433 · 经 1 个 agent
  ri.…
```

- 出口策略不能改，只能用 [`revoke`](#aidc-semantic-connectivity-egress-revoke) 吊销。
- 同名、同目的地的策略再建一次，返回已有的那条。输出是「已有（同名同目的地）」。
- 同名但目的地不同，返回 409，退出码是 6。
- 必填字段为 `apiName`、`displayName`、`type`、`address` 和 `ports`。
- `agentProxy` 策略必须用 `agents` 指定 agent 的 API name。`direct` 策略可省略 `agents`，或写空数组。
- 地址类型为 `dns`、`ip` 或 `cidr`。端口类型为 `single` 或 `range`。

### aidc semantic connectivity egress show

看一条出口策略。要 developer。

```bash
aidc semantic connectivity egress show <策略 RID>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<策略 RID>` | 出口策略的 RID，用 [`egress list`](#aidc-semantic-connectivity-egress-list) 查 | — |

```terminal title="看出口策略"
$ aidc semantic connectivity egress show ri.…
erp-db-egress            agentProxy active  erp-db.example.com:1433 · 经 1 个 agent
  ri.…
```

`--json` 输出策略的全部字段。

### aidc semantic connectivity egress revoke

吊销一条出口策略。要 developer。

```bash
aidc semantic connectivity egress revoke <策略 RID> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<策略 RID>` | 出口策略的 RID | — |
| `--dry-run` | 只预演，不吊销 | — |

```terminal title="预演吊销"
$ aidc semantic connectivity egress revoke ri.… --dry-run
预演：erp-db-egress            agentProxy active  erp-db.example.com:1433 · 经 1 个 agent
  ri.…
```

### aidc semantic connectivity connection

建或更新一个数据源连接（Connection）。连接可以是 JDBC 数据库，也可以是 REST 服务。新建连接只收 JDBC 或 REST 形状，并且要有出口策略。要 developer。

```bash
aidc semantic connectivity connection --ontology <cell-…> --file <定义.json> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--file` | 连接的 JSON 文件。字段照 API 的请求体 | 必填 |
| `--dry-run` | 只预演，不建 | — |

口令写成 `"password":{"type":"asPlaintextValue","value":"…"}`。读取已有秘密使用 `asSecretName`。平台加密保存，之后不再回显。

```terminal title="建连接"
$ aidc semantic connectivity connection --ontology cell-demo --file erp-connection.json
已建：{"rid":"ri.…","displayName":"ERP 数据库（只读）",…}
```

输出是连接的 JSON 对象。这里省略了后面的字段。

连接定义的必填字段为 `apiName`、`displayName`、`configuration` 和 `worker`。可选字段为 `description` 和 `exportSettings`。

JDBC 配置使用 `type`、`url` 和 `driverClass`。可选字段 `credentials` 指定账号和口令。REST 配置使用 `type` 和 `domains`。可选字段 `additionalSecrets` 指定额外秘密。

`worker` 写成 `{ "type":"foundryWorker", "networkEgressPolicyRids":[…] }`。

### aidc semantic connectivity config

看一个连接的配置。秘密只显示名字，不显示值。要 developer。

```bash
aidc semantic connectivity config <connectionRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID，用 [`connections`](#aidc-semantic-connectivity-connections) 查 | — |

```terminal title="看配置"
$ aidc semantic connectivity config ri.…
{
  "configuration": {
    …
  }
}
```

### aidc semantic connectivity secret

换一个秘密（口令）的值。值从环境变量或标准输入读。平台加密保存，不回显。要 developer。

```bash
aidc semantic connectivity secret <connectionRid> <秘密名> [--from-env <变量>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |
| `<秘密名>` | 秘密的名字，如 `Password`。用 [`config`](#aidc-semantic-connectivity-config) 查看 | — |
| `--from-env` | 从这个环境变量读值 | 从标准输入读 |
| `--dry-run` | 只检查能不能换，不换 | — |

> [!IMPORTANT]
> 不要把值写在命令行参数里。`--value` 会被拒绝，退出码是 2。命令行参数会留在 shell 历史和进程列表里。

从标准输入读值时，读到的内容去掉末尾的一个换行，就是值。

```bash
printf '%s' "$ERP_DB_PASSWORD" | aidc semantic connectivity secret ri.… Password
```

```terminal title="换口令"
$ aidc semantic connectivity secret ri.… Password --from-env ERP_DB_PASSWORD
已换 Password（平台加密保存，不回显）
```

### aidc semantic connectivity migrate

把旧版 agent worker 的连接迁到平台的 worker。口令从 agent 交给平台，平台加密保存。要 developer。

```bash
aidc semantic connectivity migrate <connectionRid> --policies <策略 RID,…> --yes [--username <名>] [--password-stdin]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 要迁移的连接的 RID | — |
| `--policies` | 出口策略的 RID，多个用逗号分隔 | 必填 |
| `--yes` | 确认迁移。口令会加密保存进平台，所以必须写 | 必填 |
| `--username` | 数据库的账号名 | 不改 |
| `--password-stdin` | 从标准输入读口令 | 从原 agent 获取数据库口令并加密保存 |

```bash
printf '%s' "$ERP_DB_PASSWORD" | aidc semantic connectivity migrate ri.… \
  --policies ri.… --yes --username reader --password-stdin
```

```terminal title="迁移连接"
$ aidc semantic connectivity migrate ri.… --policies ri.… --yes --password-stdin
已迁到 foundryWorker：ERP 数据库（只读）（30 天内可以 aidc semantic connectivity revert-migration ri.…）
```

迁移后 30 天内，可以用 [`revert-migration`](#aidc-semantic-connectivity-revert-migration) 退回。

### aidc semantic connectivity revert-migration

把迁移过的连接退回旧版 agent worker。只在迁移后 30 天内可以用。要 developer。

```bash
aidc semantic connectivity revert-migration <connectionRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |

```terminal title="退回迁移"
$ aidc semantic connectivity revert-migration ri.…
已退回旧版 agent worker：ERP 数据库（只读）
```

### aidc semantic connectivity explore

建数据源之前，先看源数据库里有哪些表、一张表的结构，或几行样本。要 developer。

```bash
aidc semantic connectivity explore <connectionRid> [--search <字>]
aidc semantic connectivity explore <connectionRid> --table <schema.表名> [--schema <schema>]
aidc semantic connectivity explore <connectionRid> --table <schema.表名> --preview [--rows 20]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |
| `--search` | 只列出表名里含这个字的表和视图 | 全部 |
| `--table` | 表名，写成 `schema.表名`，如 `dbo.SalesOrder` | — |
| `--schema` | 和 `--table` 一起用时，单独给 schema | — |
| `--preview` | 取样本行。要和 `--table` 一起用 | — |
| `--rows` | 样本的行数，1–50 | 20 |

三种用法：

- 不给 `--table`：列出表和视图，最多 2,000 张。超过时，用 `--search` 缩小范围。
- 给 `--table`：看表的列、主键、外键，以及被哪些表引用。
- 给 `--table` 和 `--preview`：取样本行。样本只在直连的数据源上取，不写进平台。经 agent proxy 的数据源只能看表和结构。

```terminal title="列出表"
$ aidc semantic connectivity explore ri.… --search Order
dbo.SalesOrder                                   TABLE
dbo.SalesOrderLine                               TABLE
```

```terminal title="看表结构"
$ aidc semantic connectivity explore ri.… --table dbo.SalesOrder
dbo.SalesOrder（TABLE）
  OrderNo                          nvarchar(20)             非空 · PK
  OrderDate                        datetime                 可空
  CustomerCode                     nvarchar(20)             可空
  外键 CustomerCode → dbo.Customer(CustomerCode)
  被引用 dbo.SalesOrderLine(OrderNo) → OrderNo
```

```terminal title="取样本行"
$ aidc semantic connectivity explore ri.… --table dbo.SalesOrder --preview --rows 2
OrderNo	OrderDate	CustomerCode
SO-1001	2026-10-01 00:00:00	C-0001
SO-1002	2026-10-02 00:00:00	C-0007
```

探索成功时，退出码是 0。失败，或者 2 分钟内没有结果，退出码是 8。`--json` 输出探索的完整结果。

### aidc semantic connectivity imports

列出一个连接下的表导入（TableImport）：每张表的导入模式、上次成功的时间、行数和绑定的 Object Type。要 developer。

```bash
aidc semantic connectivity imports <connectionRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |

```terminal title="看导入"
$ aidc semantic connectivity imports ri.…
sales-order-lines            SNAPSHOT 上次成功 2026-10-08T13:00:00.000Z · 1842 行 → production.order_line
  ri.…
```

每个导入两行：名字、模式、上次成功时间、行数和绑定的 Object Type，然后是 RID。「· 过期」表示这次导入的数据已经超过新鲜度的时限。

### aidc semantic connectivity import

建或更新一张表的导入（TableImport）。导入是一条只读的查询，加上导入模式。要 developer。

```bash
aidc semantic connectivity import <connectionRid> --file <TableImport.json> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |
| `--file` | 导入的 JSON 文件。字段照 API 的请求体 | 必填 |
| `--dry-run` | 只预演，不建 | — |

导入模式有两种：

- `SNAPSHOT`：整表，或一段时间窗口。源里没有了的行，对象标记为「源头已消失」。
- `APPEND`：只取上次之后改过的行，只增改。需要可靠的修改时间列。

一个导入最多 150,000 行。同一时间，一个导入只能有一次构建在跑。

```json
{
  "apiName": "sales-order-lines",
  "displayName": "订单明细",
  "importMode": "SNAPSHOT",
  "config": {
    "type": "microsoftSqlServerImportConfig",
    "query": "SELECT OrderNo, LineNo, Qty FROM dbo.SalesOrderLine WHERE OrderDate >= DATEADD(day, -90, GETDATE())"
  }
}
```

```terminal title="预演导入"
$ aidc semantic connectivity import ri.… --file sales-order-lines.json --dry-run
预演：sales-order-lines
  ri.…
```

需要全量重建时，输出会多一段「（下次执行重发全量）」。

必填字段为 `apiName`、`displayName`、`importMode` 和 `config`。可选字段为 `allowSchemaChanges`、`branchName`、`primaryKey`、`freshness`、`rowLimit` 和 `status`。

### aidc semantic connectivity execute

执行一次导入：查询源数据库，写一个数据集事务，只把变了的行写成对象。要 developer。

```bash
aidc semantic connectivity execute <connectionRid> <tableImportRid> [--full] [--wait]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<connectionRid>` | 连接的 RID | — |
| `<tableImportRid>` | 导入的 RID，用 [`imports`](#aidc-semantic-connectivity-imports) 查 | — |
| `--full` | 整表重新读一次，不用增量 | 增量 |
| `--wait` | 等这次执行结束再返回 | 不等 |

```terminal title="执行导入"
$ aidc semantic connectivity execute ri.… ri.… --wait
succeeded  读 1842 · 变 37 · 消失 0 · 对象变化 37 · 2140 ms
  ri.…
```

- 第一次执行是全量。之后只写变化的行。
- 同一个导入同时只跑一次。再执行时，输出以「已有一次在跑：」开头，不会开第二次。
- 构建失败时，退出码是 8。
- 暂停的导入或连接不执行，返回 409，退出码是 6。

### aidc semantic connectivity build

看一次构建（Build）的状态和结果。只查，不执行。要 developer。

```bash
aidc semantic connectivity build <buildRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<buildRid>` | 构建的 RID，由 [`execute`](#aidc-semantic-connectivity-execute) 的输出给出 | — |

```terminal title="看构建"
$ aidc semantic connectivity build ri.…
succeeded  读 1842 · 变 37 · 消失 0 · 对象变化 37 · 2140 ms
  ri.…
```

有详情（如失败原因）时，详情在第二行。

### aidc semantic connectivity dataset

打印数据集当前的内容。格式是 CSV，第一行是表头。要 developer。

```bash
aidc semantic connectivity dataset <datasetRid> [--rows 20]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<datasetRid>` | 数据集的 RID，以 `ri.` 开头 | — |
| `--rows` | 最多返回的行数，写整数 | 20 |

```terminal title="看数据集"
$ aidc semantic connectivity dataset ri.… --rows 3
OrderNo,OrderDate,CustomerCode
SO-1001,2026-10-01 00:00:00,C-0001
SO-1002,2026-10-02 00:00:00,C-0007
```

输出总是 CSV，不论有没有 `--json`。

### aidc semantic connectivity health create

建一个数据健康检查（Data Health）。平台每 5 分钟评估一次。检查失败、升级和恢复时，给建检查的人发邮件。要 developer。

```bash
aidc semantic connectivity health create --file <检查.json> [--intent <用途>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--file` | 检查的 JSON 文件。可以只写 `config`，也可以写 `{ "config": …, "intent": … }` | 必填 |
| `--intent` | 这个检查的用途，写给人看 | — |

`config` 的 `type` 有四种：`buildStatus`（构建状态）、`timeSinceLastUpdated`（距上次更新的时间）、`schemaComparison`（列结构）和 `primaryKey`（主键）。每个检查挂在一个数据集的一个分支上。`subject` 写数据集的 RID 和分支：

```json
{
  "type": "buildStatus",
  "subject": { "datasetRid": "ri.…", "branchId": "master" },
  "statusCheckConfig": { "severity": "MODERATE" }
}
```

`severity` 可取 `MODERATE` 或 `CRITICAL`。

```terminal title="建健康检查"
$ aidc semantic connectivity health create --file check-build.json --intent "订单数据集要按时更新"
已建：buildStatus            ri.… · 订单数据集要按时更新
  ri.…
```

同一个分支上，同一种检查只能有一个。建好的检查，类型不能改。创建、读取、替换、删除及读取报告均要本组织的 developer。

### aidc semantic connectivity health show

看一个检查的定义。要 developer。

```bash
aidc semantic connectivity health show <checkRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<checkRid>` | 检查的 RID，由 `create` 的输出给出 | — |

```terminal title="看检查"
$ aidc semantic connectivity health show ri.…
buildStatus            ri.… · 订单数据集要按时更新
  ri.…
```

### aidc semantic connectivity health replace

整体替换一个检查的定义。检查的类型和挂的数据集不能换。要 developer。

```bash
aidc semantic connectivity health replace <checkRid> --file <检查.json>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<checkRid>` | 检查的 RID | — |
| `--file` | 格式为 `{ "config": …, "intent": … }` 或仅配置。配置不含 `subject` | 必填 |

替换文件 `check-build-replace.json`：

```json
{
  "type": "buildStatus",
  "statusCheckConfig": { "severity": "MODERATE" }
}
```

```terminal title="替换检查"
$ aidc semantic connectivity health replace ri.… --file check-build-replace.json
已替换：buildStatus            ri.…
  ri.…
```

### aidc semantic connectivity health delete

删除一个检查。要 developer。

```bash
aidc semantic connectivity health delete <checkRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<checkRid>` | 检查的 RID | — |

```terminal title="删除检查"
$ aidc semantic connectivity health delete ri.…
已删：ri.…
```

### aidc semantic connectivity health reports

看一个检查最近的评估结果，新的在前。要 developer。

```bash
aidc semantic connectivity health reports <checkRid> [--limit 10]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<checkRid>` | 检查的 RID | — |
| `--limit` | 最多返回几条，取 1–100 | 10 |

```terminal title="看检查报告"
$ aidc semantic connectivity health reports ri.… --limit 2
2026-10-08T14:00:00Z  PASSED         最近一次构建 ri.… 成功
2026-10-08T13:55:00Z  FAILED         最近 1 次构建失败，最近一次 ri.…：源数据库连接超时
```

最新一条是 `FAILED` 时，退出码是 8。没有报告时，命令打印「还没有报告」。

### aidc semantic connectivity webhooks

列出 REST 数据源上的 webhook。要 developer。

```bash
aidc semantic connectivity webhooks --ontology <cell-…> [--connection <数据源 RID 或 apiName>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--connection` | 只看这个数据源上的 webhook | 全部 |

```terminal title="看列表"
$ aidc semantic connectivity webhooks --ontology cell-demo --connection example-rest
example-rest/send-notice                 v1 active   发一条通知 · POST /notices
  ri.…
```

每个 webhook 两行：引用名、版本、状态、显示名和请求的方法与路径，然后是 RID。没有 webhook 时，命令打印「没有 webhook」。

### aidc semantic connectivity webhook put

建或更新一个 webhook。webhook 挂在一个 REST 数据源上，定义请求的方法、路径、输入和输出。webhook 不存秘密，凭证在数据源上。要 developer。

```bash
aidc semantic connectivity webhook put --ontology <cell-…> --file <webhook.json> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--file` | webhook 的 JSON 文件 | 必填 |
| `--dry-run` | 只预演，不写 | — |

请求里的 `{{输入名}}` 会换成输入的值。`{{secrets.名字}}` 会换成数据源上的秘密。

```json
{
  "connection": "example-rest",
  "apiName": "send-notice",
  "displayName": "发一条通知",
  "inputs": { "content": { "type": "string" } },
  "calls": [
    {
      "name": "send",
      "method": "POST",
      "path": "/notices",
      "body": { "type": "json", "value": { "text": "{{content}}" } },
      "extract": { "id": "/id" }
    }
  ],
  "outputs": { "id": { "type": "string" } }
}
```

```terminal title="建一个"
$ aidc semantic connectivity webhook put --ontology cell-demo --file send-notice.json
已建：example-rest/send-notice                 v1 active   发一条通知 · POST /notices
  ri.…
```

### aidc semantic connectivity webhook get

打印一个 webhook 的定义，格式是 JSON。要 developer。

```bash
aidc semantic connectivity webhook get <webhookRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<webhookRid>` | webhook 的 RID，用 [`webhooks`](#aidc-semantic-connectivity-webhooks) 查 | — |

```terminal title="看定义"
$ aidc semantic connectivity webhook get ri.…
{
  "rid": "ri.…",
  "ref": "example-rest/send-notice",
  "version": 1,
  "status": "active",
  …
}
```

### aidc semantic connectivity webhook delete

删除一个 webhook。要 developer。

```bash
aidc semantic connectivity webhook delete <webhookRid> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<webhookRid>` | webhook 的 RID | — |
| `--dry-run` | 只检查能不能删，不删 | — |

```terminal title="预演删除"
$ aidc semantic connectivity webhook delete ri.… --dry-run
预演（可以删）：example-rest/send-notice
```

### aidc semantic connectivity webhook test

手动执行一个 webhook，逐步打印每个请求和响应。`--dry-run` 只渲染请求，不发出去，秘密会打码。要 developer。

```bash
aidc semantic connectivity webhook test <webhookRid> [--inputs '<JSON>' | --inputs-file <文件>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<webhookRid>` | webhook 的 RID | — |
| `--inputs` | 输入，写成 JSON 对象：输入名 → 值 | `{}` |
| `--inputs-file` | 输入的 JSON 文件。写 `-` 表示从标准输入读 | — |
| `--dry-run` | 只渲染请求，不发出去 | — |

`--inputs` 和 `--inputs-file` 只能给一个。

```terminal title="手动执行"
$ aidc semantic connectivity webhook test ri.… --inputs '{"content":"你好"}'
example-rest/send-notice v1：642 ms
send         POST   200  642 ms · 发 27 B · 收 15 B  https://api.example.com/notices
输出：{"id":"n-20261008-0042"}
```

```terminal title="预演请求"
$ aidc semantic connectivity webhook test ri.… --inputs '{"content":"你好"}' --dry-run
预演（不发出去；秘密打码）：example-rest/send-notice v1
send：POST https://api.example.com/notices
  {"text":"你好"}
```

## aidc semantic transforms

加工（Transform）从数据集算出新的数据集。定义包括输入、一条 DuckDB SQL 和增量设置。输入有新数据时，平台自动构建。`put`、`build` 和 `delete` 要 developer。加工的设计见 [数据管道](pipeline.md)。

### aidc semantic transforms list

列出组织的加工定义，和每条定义上次构建成功的时间。要 developer。

```bash
aidc semantic transforms list --ontology <cell-…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |

```terminal title="列出加工"
$ aidc semantic transforms list --ontology cell-demo
active  增量 mergeAndReplace v1        订单日汇总 → order-daily-stats · 上次成功 2026-10-08T13:00:00.000Z
  ri.…
```

每条定义两行：状态、增量设置、显示名、输出的数据集和上次成功的时间，然后是 RID。「非增量」表示每次构建都整份重算。没有定义时，命令打印「没有。」

### aidc semantic transforms put

建或整体替换一个加工定义。按 `apiName` 判断是新建还是替换。同一个 `apiName` 重复提交，结果相同。要 developer。

```bash
aidc semantic transforms put --ontology <cell-…> --file <transform.json> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间 | 必填 |
| `--file` | 加工定义的 JSON 文件 | 必填 |
| `--dry-run` | 只预演，不写 | — |

定义的字段：

| 字段 | 说明 |
| --- | --- |
| `apiName`、`displayName` | 加工的 API name 和显示名 |
| `inputs` | 输入。键是别名。值有 `dataset`（数据集的名字或 RID），还可以有 `key`（表达式的列表，增量时用它算受影响的键） |
| `sql` | 一条 `SELECT`，DuckDB 方言，可以用 `WITH`。只能读 `inputs` 里的别名。产出的列就是数据集的结构 |
| `incremental` | 增量设置。不写，就是非增量：每次整份重算 |

`incremental` 的字段：

| 字段 | 说明 |
| --- | --- |
| `output` | `append`：只算新加的行，追加到产出。`mergeAndReplace`：先算出受影响的键，只重算这些键，再和上一份产出合并 |
| `key` | `mergeAndReplace` 用的键表达式 |
| `snapshotInputs` | 参考表，如价格表。它们整份读。它们的变化不触发构建，也不使之前的结果失效 |
| `semanticVersion` | 口径变了，要回溯历史，就把它加一。加一后，下一次构建整份重算 |
| `requireIncremental` | 设为 `true` 时，不能增量就失败。首次构建和升版本除外 |

```json
{
  "apiName": "order-daily-stats",
  "displayName": "订单日汇总",
  "inputs": {
    "orders": { "dataset": "orders-raw", "key": ["customer_code", "order_date"] },
    "customers": { "dataset": "customers" }
  },
  "sql": "SELECT o.customer_code, o.order_date, count(*) AS order_count, sum(o.amount) AS amount FROM orders o SEMI JOIN customers c ON c.customer_code = o.customer_code GROUP BY ALL",
  "incremental": {
    "semanticVersion": 1,
    "snapshotInputs": ["customers"],
    "output": "mergeAndReplace",
    "key": ["customer_code", "order_date"]
  }
}
```

```terminal title="预演加工"
$ aidc semantic transforms put --ontology cell-demo --file order-daily-stats.json --dry-run
（预演）新建
active  增量 mergeAndReplace v1        订单日汇总 → order-daily-stats · 上次成功 —
  ri.…
```

- 一次构建读的文件不超过 384 MB。产出不超过 500 万行。计算预算为 260 秒。
- 一个数据集只能有一个产出者，一张导入表或一个加工。输入不能绕回自己的产出。
- 数据集里不带时区的时间，在 SQL 里按北京时间算。`current_date` 也是北京时间。

### aidc semantic transforms show

看一个加工定义：输入、增量设置，以及上次构建的结果。要 developer。

```bash
aidc semantic transforms show <transformRid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<transformRid>` | 加工的 RID，用 [`list`](#aidc-semantic-transforms-list) 查 | — |

```terminal title="看加工"
$ aidc semantic transforms show ri.…
active  增量 mergeAndReplace v1        订单日汇总 → order-daily-stats · 上次成功 2026-10-08T13:00:00.000Z
  ri.…
  输入 orders = ri.… · 键 customer_code、order_date
  输入 customers = ri.…
上次构建：
succeeded  incremental · 读 1842 · 写 36 · 受影响的键 4 · 对象变化 0 · 2140 ms
  ri.…
```

`--json` 输出定义，并带上 `lastBuildView`。

### aidc semantic transforms build

构建一次加工。输入和定义都没有变化时，不运行。`--force` 照常运行。要 developer。

```bash
aidc semantic transforms build <transformRid> [--force] [--wait]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<transformRid>` | 加工的 RID | — |
| `--force` | 不管输入有没有变化，都运行。增量与否仍按定义决定 | 不强制 |
| `--wait` | 等构建结束再返回，最多 5 分钟 | 不等 |

`--force` 不强制整份重算。实际构建方式仍由增量条件决定。要整份重算，把 `semanticVersion` 加一。

```terminal title="构建一次"
$ aidc semantic transforms build ri.… --wait
succeeded  incremental · 读 1842 · 写 36 · 受影响的键 4 · 对象变化 0 · 2140 ms
  ri.…
```

构建失败时，退出码是 8。

### aidc semantic transforms delete

删除一个加工定义。产出的数据集留着。如果还有 Object Type 使用它的产出，命令拒绝删除。要 developer。

```bash
aidc semantic transforms delete <transformRid> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<transformRid>` | 加工的 RID | — |
| `--dry-run` | 只预演，不删 | — |

```terminal title="预演删除"
$ aidc semantic transforms delete ri.… --dry-run
（预演）将删除 订单日汇总（产出的 Dataset order-daily-stats 留着）
```

## aidc semantic media-sets

媒体集（Media set）保存图片、文档、音视频等文件。字节放在组织自己的存储里，Semantic 只存元数据。权限沿 Ontology 继承。创建媒体集要 Ontology 的 Editor。上传、登记和删除要媒体集的 Editor。读取要 Viewer。本组织的 developer 是 Owner。修改保留策略、打开事务、提交事务和放弃事务均要媒体集的 Editor。

媒体集的概念、访问和大文件的规则见 [文件：Media sets 与 Space](media.md)。

### aidc semantic media-sets list

列出媒体集。要 Viewer 角色。

```bash
aidc semantic media-sets list
```

这条命令没有参数。

```terminal title="列出媒体集"
$ aidc semantic media-sets list
ri.mio.aidc.media-set.7b2c…  巡检照片  IMAGERY  12 项
```

每个媒体集一行：RID、名字、媒体类型和项数。虚拟媒体集后面有 `· Virtual`，事务型媒体集后面有 `· Transactional`。没有媒体集时，命令打印「还没有媒体集」和 `create` 的用法。

### aidc semantic media-sets show

看一个媒体集的详情：视图、默认分支和保留策略。要 Viewer 角色。

```bash
aidc semantic media-sets show <媒体集 RID>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID，用 [`list`](#aidc-semantic-media-sets-list) 查 | — |

```terminal title="看媒体集"
$ aidc semantic media-sets show ri.mio.aidc.media-set.7b2c…
ri.mio.aidc.media-set.7b2c…  巡检照片  IMAGERY  12 项
  view ri.mio.aidc.view.…  默认分支 master  保留：上传后 365 天 / 覆盖后 30 天
```

保留策略里，没有设置的天数显示为「—」。虚拟媒体集多一段「源文件夹」。`--json` 输出全部字段。

### aidc semantic media-sets create

建一个媒体集。要 Ontology 的 Editor 角色。本组织的 developer 是 Owner，可以直接建。

```bash
aidc semantic media-sets create --name <名字> --schema <类型> [--description <说明>] [--transactional] [--virtual <源文件夹>] [--extra <格式,…>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name` | 媒体集的名字 | 必填 |
| `--schema` | 媒体类型，见下面的列表。大小写不限 | 必填 |
| `--description` | 说明 | — |
| `--transactional` | 写入要放在事务里，提交后才可见 | 不用事务 |
| `--virtual` | 虚拟媒体集。登记组织存储里这个文件夹下的文件，不拷贝 | — |
| `--extra` | 额外能认的格式，逗号分隔，如 `TXT,DOCX`。PDF 文档媒体集可以加 `TXT`、`DOCX` 和 `PPTX` | — |

媒体类型有八种：`IMAGERY`、`DOCUMENT`、`AUDIO`、`VIDEO`、`SPREADSHEET`、`EMAIL`、`DICOM` 和 `MULTIMODAL`。

```terminal title="建媒体集"
$ aidc semantic media-sets create --name 巡检照片 --schema IMAGERY
已建：ri.mio.aidc.media-set.7b2c…  巡检照片  IMAGERY  0 项
下一步：aidc semantic media-sets upload ri.mio.aidc.media-set.7b2c… <文件>
```

虚拟媒体集的「下一步」是 [`sync`](#aidc-semantic-media-sets-sync)。

### aidc semantic media-sets items

列出媒体集里的媒体项。给了 `--path` 时，列出这个路径的版本历史。要 Viewer 角色。

```bash
aidc semantic media-sets items <媒体集 RID> [--path <路径>] [--prefix <前缀>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `--path` | 只列这个路径的版本历史 | 全部 |
| `--prefix` | 只列路径以这个前缀开头的媒体项 | 全部 |

一次请求最多取 1,000 项。

```terminal title="列出媒体项"
$ aidc semantic media-sets items ri.mio.aidc.media-set.7b2c… --prefix line-a/
ri.mio.aidc.media-item.5d1e…  line-a/pump.png  image/png  183204 B  LIVE  2026-10-08 09:30
```

每项一行：RID、路径、类型、大小、状态和创建时间。没有媒体项时，命令打印「没有媒体项。」

### aidc semantic media-sets upload

上传一个本机文件到媒体集。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets upload <媒体集 RID> <文件> [--path <路径>] [--transaction <事务 id>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<文件>` | 本机的文件 | — |
| `--path` | 文件在媒体集里的路径 | 文件名 |
| `--transaction` | 事务的 id。事务型媒体集的写入必须带这个参数 | 不用事务 |

同一路径再上传一次，旧版本变成历史版本。已有的直接引用仍然可以读。

4.4 MB 以下的文件直接上传。更大的文件走直传，命令自动处理。单个媒体项最大 50 GB。

```terminal title="上传照片"
$ aidc semantic media-sets upload ri.mio.aidc.media-set.7b2c… pump.png --path line-a/pump.png
已上传 line-a/pump.png（183204 B）→ ri.mio.aidc.media-item.5d1e…
```

### aidc semantic media-sets sync

登记虚拟媒体集的源文件夹里的新文件。文件不拷贝。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets sync <媒体集 RID>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 虚拟媒体集的 RID | — |

```terminal title="登记新文件"
$ aidc semantic media-sets sync ri.mio.aidc.media-set.7b2c…
扫描 12 个文件：新登记 3，跳过 1（不符合 schema）
```

- 源文件夹里删掉的文件，记录保留，但读不到。输出会多一段「源端已删除 N」。
- 一次扫描有上限。没扫完时，输出提示再运行一次。

### aidc semantic media-sets metadata

打印一个媒体项的元数据，格式是 JSON。元数据的字段取决于文件类型，例如图片的尺寸、文档的页数。要 Viewer 角色。

```bash
aidc semantic media-sets metadata <媒体集 RID> <媒体项 RID>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<媒体项 RID>` | 媒体项的 RID，用 [`items`](#aidc-semantic-media-sets-items) 查 | — |

```terminal title="看元数据"
$ aidc semantic media-sets metadata ri.mio.aidc.media-set.7b2c… ri.mio.aidc.media-item.5d1e…
{
  "type": "imagery",
  "format": "PNG",
  "dimensions": {
    "width": 640,
    "height": 480
  },
  "bands": [],
  "attributes": {},
  "sizeBytes": 183204
}
```

图片元数据的 `type` 为 `imagery`。字段包括 `format`、`bands`、`attributes` 和 `sizeBytes`。解析出尺寸时，包含 `dimensions.width` 和 `dimensions.height`。

### aidc semantic media-sets download

下载一个媒体项到本机文件。要 Viewer 角色。

```bash
aidc semantic media-sets download <媒体集 RID> <媒体项 RID> [--out <文件>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<媒体项 RID>` | 媒体项的 RID | — |
| `--out` | 保存到的文件。同名文件会被覆盖 | 媒体项路径的最后一段 |

```terminal title="下载文件"
$ aidc semantic media-sets download ri.mio.aidc.media-set.7b2c… ri.mio.aidc.media-item.5d1e… --out pump.png
已下载 pump.png（183204 B）
```

### aidc semantic media-sets text

取 PDF 或 TXT 文件的全文。要 Viewer 角色。

```bash
aidc semantic media-sets text <媒体集 RID> <媒体项 RID>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<媒体项 RID>` | 文档的媒体项 RID | — |

```terminal title="取全文"
$ aidc semantic media-sets text ri.mio.aidc.media-set.5a… ri.mio.aidc.media-item.9f0c…
巡检单 2026-10-08
1. 泵体无渗漏
```

输出是纯文本。`--json` 时输出 `{ "text": … }`。

### aidc semantic media-sets clear

删除一个路径（软删）。按这个路径取不到文件了，但已有的直接引用仍可以读。文件之后按保留策略永久删除。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets clear <媒体集 RID> --path <路径> [--transaction <事务 id>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `--path` | 要删除的路径 | 必填 |
| `--transaction` | 事务的 id。事务型媒体集要带这个参数 | 不用事务 |

```terminal title="软删路径"
$ aidc semantic media-sets clear ri.mio.aidc.media-set.7b2c… --path line-a/pump.png
已删除 line-a/pump.png（软删：按路径取不到，已有的直接引用仍可读；按保留策略永久删除）
```

### aidc semantic media-sets retention

改保留策略：上传后多少天删除，被覆盖或删除后多少天删除。`0` 表示不删。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets retention <媒体集 RID> [--older-than <天>] [--overwritten-after <天>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `--older-than` | 上传后多少天删除。`0` 表示不删 | 不改 |
| `--overwritten-after` | 被覆盖或删除后多少天删除。`0` 表示不删 | 不改 |

缩短保留天数，立即生效。到期的媒体项由平台的定时清理删除。

```terminal title="改保留策略"
$ aidc semantic media-sets retention ri.mio.aidc.media-set.7b2c… --older-than 365 --overwritten-after 30
保留策略：上传后 365 天 / 被覆盖或删除后 30 天（缩短立即生效）
```

### aidc semantic media-sets transaction open

开一个事务。事务型媒体集的写入放在事务里，提交后才可见。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets transaction <媒体集 RID> open
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |

```terminal title="开事务"
$ aidc semantic media-sets transaction ri.mio.aidc.media-set.7b2c… open
已开事务 tx-…：aidc semantic media-sets upload ri.mio.aidc.media-set.7b2c… <文件> --transaction tx-…，传完 aidc semantic media-sets transaction ri.mio.aidc.media-set.7b2c… commit tx-…
```

- 一个媒体集的一个分支，同时只能有一个事务。
- 一个事务最多 10,000 项。
- 提交前，谁都读不到事务里的项，上传人也读不到。
- 提交和放弃都要带媒体集的 RID，写成 `transaction <媒体集 RID> commit <事务 id>`。`--json` 输出 `{ "transactionId": … }`。

### aidc semantic media-sets transaction commit

提交一个事务。事务里的媒体项从这时起可以读。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets transaction <媒体集 RID> commit <事务 id>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<事务 id>` | [`open`](#aidc-semantic-media-sets-transaction-open) 输出的事务 id | — |

```terminal title="提交事务"
$ aidc semantic media-sets transaction ri.mio.aidc.media-set.7b2c… commit tx-…
已提交 tx-…：事务里的媒体项现在可读
```

### aidc semantic media-sets transaction abort

放弃一个事务。事务里的媒体项全部删除。要媒体集的 Editor 角色。

```bash
aidc semantic media-sets transaction <媒体集 RID> abort <事务 id>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<媒体集 RID>` | 媒体集的 RID | — |
| `<事务 id>` | 要放弃的事务 id | — |

```terminal title="放弃事务"
$ aidc semantic media-sets transaction ri.mio.aidc.media-set.7b2c… abort tx-…
已放弃 tx-…：事务里的媒体项全部删除
```

## 下一步

- [数据接入](connect.md)：数据流的协议、订阅方式和发布端的设计。
- [数据管道](pipeline.md)：Data Connection 的同步方式、加工和新鲜度。
- [定义本体](ontology.md)：Object Type 和它的数据源怎么写。
- [文件：Media sets 与 Space](media.md)：媒体集的概念、访问和大文件。
- [参考 · Semantic 本体与数据](cli-semantic.md)：本体、对象和 Action 的命令。
- [参考 · 访问、自动化与用量](cli-govern.md)：自动化（`aidc semantic automations`）的命令。
- [CLI 概览](cli.md)：安装、登录、输出和退出码。