参考 · 数据接入

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

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

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

aidc semantic streams

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

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

aidc semantic streams create

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

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

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

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

aidc semantic streams list

这条命令没有参数。

$ aidc semantic streams list
cell-demo/orders  在手订单  seq 128  3 行  ● 在线  正常  最近 2026-10-08T14:03:12
$ 

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

aidc semantic streams status

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

aidc semantic streams status <流名>

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

aidc semantic streams get <流名>

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

aidc semantic streams tail <流名>

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

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

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

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

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

$ 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 查前缀。用 revoke 吊销旧 Key。然后签发新 Key。--json 输出 key 和 keyPrefix。

aidc semantic streams keys

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

aidc semantic streams keys <流名>

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

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

$ aidc semantic streams revoke orders --prefix aidc-pk-0b9d4e51
已吊销 aidc-pk-0b9d4e51
$ 

aidc semantic streams publish

往一条数据流发布事件。要 developer。发布端常驻运行时，用 pipe，它读发布 Key。

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

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

$ 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 的登录。

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

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

$ 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 对象：

发布端的行为：

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

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

# 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）要在分支上改，见 定义本体。

aidc semantic datasource list

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

aidc semantic datasource list [<类型>]

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

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

aidc semantic datasource set

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

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

$ 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 时，见 定义本体。

aidc semantic datasource remove

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

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

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

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

aidc semantic datasource resync

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

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

$ aidc semantic datasource resync production.order_line --stream orders
重同步：变化 3 个
$ 

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

aidc semantic datasource sync

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

aidc semantic datasource sync

这条命令没有参数。

$ 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：执行导入。

设计见 数据管道。旧版 agent worker 的说明见 旧写法与迁移。自动化（Automate）的命令见 参考 · 访问、自动化与用量。

aidc semantic connectivity agents

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

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

$ aidc semantic connectivity agents --ontology cell-demo
site-box                 online   工厂机房
  ri.…
$ 

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

aidc semantic connectivity connections

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

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

$ aidc semantic connectivity connections --ontology cell-demo
erp-sqlserver            active   ERP 数据库（只读）
  ri.…
$ 

输出格式和 agents 相同。

aidc semantic connectivity agent register

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

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

$ 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 不用它。

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

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

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

aidc semantic connectivity egress list

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

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

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

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

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

$ 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 吊销。
• 同名、同目的地的策略再建一次，返回已有的那条。输出是「已有（同名同目的地）」。
• 同名但目的地不同，返回 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。

aidc semantic connectivity egress show <策略 RID>

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

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

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

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

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

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

aidc semantic connectivity config <connectionRid>

$ aidc semantic connectivity config ri.…
{
  "configuration": {
    …
  }
}
$ 

aidc semantic connectivity secret

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

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

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

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

$ aidc semantic connectivity secret ri.… Password --from-env ERP_DB_PASSWORD
已换 Password（平台加密保存，不回显）
$ 

aidc semantic connectivity migrate

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

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

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

$ 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

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

aidc semantic connectivity revert-migration <connectionRid>

$ aidc semantic connectivity revert-migration ri.…
已退回旧版 agent worker：ERP 数据库（只读）
$ 

aidc semantic connectivity explore

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

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]

三种用法：

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

$ aidc semantic connectivity explore ri.… --search Order
dbo.SalesOrder                                   TABLE
dbo.SalesOrderLine                               TABLE
$ 

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

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

aidc semantic connectivity imports <connectionRid>

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

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

导入模式有两种：

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

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

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

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

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

$ aidc semantic connectivity execute ri.… ri.… --wait
succeeded  读 1842 · 变 37 · 消失 0 · 对象变化 37 · 2140 ms
  ri.…
$ 

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

aidc semantic connectivity build

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

aidc semantic connectivity build <buildRid>

$ aidc semantic connectivity build ri.…
succeeded  读 1842 · 变 37 · 消失 0 · 对象变化 37 · 2140 ms
  ri.…
$ 

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

aidc semantic connectivity dataset

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

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

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

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

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

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

severity 可取 MODERATE 或 CRITICAL。

$ aidc semantic connectivity health create --file check-build.json --intent "订单数据集要按时更新"
已建：buildStatus            ri.… · 订单数据集要按时更新
  ri.…
$ 

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

aidc semantic connectivity health show

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

aidc semantic connectivity health show <checkRid>

$ aidc semantic connectivity health show ri.…
buildStatus            ri.… · 订单数据集要按时更新
  ri.…
$ 

aidc semantic connectivity health replace

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

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

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

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

$ aidc semantic connectivity health replace ri.… --file check-build-replace.json
已替换：buildStatus            ri.…
  ri.…
$ 

aidc semantic connectivity health delete

删除一个检查。要 developer。

aidc semantic connectivity health delete <checkRid>

$ aidc semantic connectivity health delete ri.…
已删：ri.…
$ 

aidc semantic connectivity health reports

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

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

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

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

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

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

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

{
  "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" } }
}

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

aidc semantic connectivity webhook get <webhookRid>

$ aidc semantic connectivity webhook get ri.…
{
  "rid": "ri.…",
  "ref": "example-rest/send-notice",
  "version": 1,
  "status": "active",
  …
}
$ 

aidc semantic connectivity webhook delete

删除一个 webhook。要 developer。

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

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

aidc semantic connectivity webhook test

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

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

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

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

$ 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。加工的设计见 数据管道。

aidc semantic transforms list

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

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

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

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

定义的字段：

incremental 的字段：

{
  "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"]
  }
}

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

aidc semantic transforms show <transformRid>

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

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

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

$ aidc semantic transforms build ri.… --wait
succeeded  incremental · 读 1842 · 写 36 · 受影响的键 4 · 对象变化 0 · 2140 ms
  ri.…
$ 

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

aidc semantic transforms delete

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

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

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

aidc semantic media-sets list

列出媒体集。要 Viewer 角色。

aidc semantic media-sets list

这条命令没有参数。

$ aidc semantic media-sets list
ri.mio.aidc.media-set.7b2c…  巡检照片  IMAGERY  12 项
$ 

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

aidc semantic media-sets show

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

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

$ 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，可以直接建。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

aidc semantic media-sets metadata

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

aidc semantic media-sets transaction abort

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

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

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

下一步

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