# 参考 · 访问、自动化与用量

本页覆盖九组命令：资源的访问、账号与组织、Markings、自动化、工作流、看板、Space、应用日志，以及用量与账单。每条命令的第一句末尾写它要什么角色：「member 也能用」或「要 developer」。

> [!NOTE]
> 用法里 `<…>` 是要你填的值，`[…]` 是可选项，`|` 表示二选一。占位符：`<rid>` 是资源的 RID，`<cell-…>` 是组织的命名空间（如 `cell-demo`），`<账号 id>` 和 `<组 id>` 是账号与组的 id，`<id>` 是 Space 条目的 id，`<automationRid>` 是自动化的 RID，`<moduleRid>` 是看板的 RID，`<slug>` 是应用的地址名。
> 命令示例里的 id、地址和数字都是演示值。`member` 是组织里的成员，`developer` 是组织里的开发者。
> `-n` 对 `aidc semantic admin`、`aidc semantic observability`、`aidc semantic usage` 和 `aidc semantic automate` 有效。自动化的 `list`、`upsert`、`runs` 和看板的 `list`、`save` 用 `--ontology <cell-…>`，不用 `-n`。通用参数（`--json`、`--dry-run`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)，退出码见 [退出码](cli.md#退出码)。

| 命令 | 做什么 |
| --- | --- |
| [`aidc semantic filesystem list`](#aidc-semantic-filesystem-list) | 列出你看得见的资源 |
| [`aidc semantic filesystem show`](#aidc-semantic-filesystem-show) | 看一个资源 |
| [`aidc semantic filesystem roles`](#aidc-semantic-filesystem-roles) | 看资源上的每一条角色授予 |
| [`aidc semantic filesystem access`](#aidc-semantic-filesystem-access) | 设置资源的开放程度 |
| [`aidc semantic filesystem share`](#aidc-semantic-filesystem-share) | 分享给人、组、所有人或互联网 |
| [`aidc semantic filesystem unshare`](#aidc-semantic-filesystem-unshare) | 撤销一个分享 |
| [`aidc semantic filesystem link`](#aidc-semantic-filesystem-link) | 生成邀请链接 |
| [`aidc semantic filesystem markings`](#aidc-semantic-filesystem-markings) | 看资源上挂的 Marking |
| [`aidc semantic filesystem mark`](#aidc-semantic-filesystem-mark) | 给资源挂上 Marking |
| [`aidc semantic filesystem unmark`](#aidc-semantic-filesystem-unmark) | 去掉资源上的 Marking |
| [`aidc semantic admin whoami`](#aidc-semantic-admin-whoami) | 看当前登录的身份 |
| [`aidc semantic admin members list`](#aidc-semantic-admin-members-list) | 列出本组织的人 |
| [`aidc semantic admin members import`](#aidc-semantic-admin-members-import) | 导入名单，让人成为本组织的 member |
| [`aidc semantic admin groups list`](#aidc-semantic-admin-groups-list) | 列出组 |
| [`aidc semantic admin groups show`](#aidc-semantic-admin-groups-show) | 看一个组 |
| [`aidc semantic admin groups search`](#aidc-semantic-admin-groups-search) | 按名字前缀找组 |
| [`aidc semantic admin groups mine`](#aidc-semantic-admin-groups-mine) | 看自己在哪些组里 |
| [`aidc semantic admin groups create`](#aidc-semantic-admin-groups-create) | 建一个组 |
| [`aidc semantic admin groups rename`](#aidc-semantic-admin-groups-rename) | 改组名或说明 |
| [`aidc semantic admin groups delete`](#aidc-semantic-admin-groups-delete) | 删除一个组 |
| [`aidc semantic admin groups members`](#aidc-semantic-admin-groups-members) | 列出组的成员 |
| [`aidc semantic admin groups add-members`](#aidc-semantic-admin-groups-add-members) | 给组加成员 |
| [`aidc semantic admin groups remove-members`](#aidc-semantic-admin-groups-remove-members) | 从组里移出成员 |
| [`aidc semantic admin groups expiration`](#aidc-semantic-admin-groups-expiration) | 设置或查看成员到期规则 |
| [`aidc semantic admin users list`](#aidc-semantic-admin-users-list) | 列出本组织的用户 |
| [`aidc semantic admin users show`](#aidc-semantic-admin-users-show) | 看一个用户的属性 |
| [`aidc semantic admin users search`](#aidc-semantic-admin-users-search) | 按前缀找用户 |
| [`aidc semantic admin users groups`](#aidc-semantic-admin-users-groups) | 看一个用户在哪些组里 |
| [`aidc semantic admin users set-attributes`](#aidc-semantic-admin-users-set-attributes) | 设置用户的部门和岗位 |
| [`aidc semantic admin organization`](#aidc-semantic-admin-organization) | 看组织的编号和名字 |
| [`aidc semantic admin marking-categories list`](#aidc-semantic-admin-marking-categories-list) | 列出 Marking 类别 |
| [`aidc semantic admin marking-categories show`](#aidc-semantic-admin-marking-categories-show) | 看一个类别和它里面的 Marking |
| [`aidc semantic admin marking-categories create`](#aidc-semantic-admin-marking-categories-create) | 建一个 Marking 类别 |
| [`aidc semantic admin marking-categories rename`](#aidc-semantic-admin-marking-categories-rename) | 改类别的名字或说明 |
| [`aidc semantic admin markings list`](#aidc-semantic-admin-markings-list) | 列出 Marking |
| [`aidc semantic admin markings show`](#aidc-semantic-admin-markings-show) | 看一个 Marking |
| [`aidc semantic admin markings create`](#aidc-semantic-admin-markings-create) | 建一个 Marking |
| [`aidc semantic admin markings rename`](#aidc-semantic-admin-markings-rename) | 改 Marking 的名字或说明 |
| [`aidc semantic admin markings members`](#aidc-semantic-admin-markings-members) | 列出 Marking 的成员 |
| [`aidc semantic admin markings add-members`](#aidc-semantic-admin-markings-add-members) | 给 Marking 加成员 |
| [`aidc semantic admin markings remove-members`](#aidc-semantic-admin-markings-remove-members) | 从 Marking 移出成员 |
| [`aidc semantic admin markings roles`](#aidc-semantic-admin-markings-roles) | 看 Marking 的角色分配 |
| [`aidc semantic admin markings grant`](#aidc-semantic-admin-markings-grant) | 授予 Marking 的角色 |
| [`aidc semantic admin markings revoke`](#aidc-semantic-admin-markings-revoke) | 收回 Marking 的角色 |
| [`aidc semantic admin markings mine`](#aidc-semantic-admin-markings-mine) | 看某人是哪些 Marking 的成员 |
| [`aidc semantic automations list`](#aidc-semantic-automations-list) | 列出组织级的自动化 |
| [`aidc semantic automations upsert`](#aidc-semantic-automations-upsert) | 建或更新一个自动化 |
| [`aidc semantic automations show`](#aidc-semantic-automations-show) | 看一个自动化和它最近的运行 |
| [`aidc semantic automations run`](#aidc-semantic-automations-run) | 立即开一次运行 |
| [`aidc semantic automations pause`](#aidc-semantic-automations-pause) | 暂停一个自动化 |
| [`aidc semantic automations resume`](#aidc-semantic-automations-resume) | 恢复一个自动化 |
| [`aidc semantic automations delete`](#aidc-semantic-automations-delete) | 删除一个自动化 |
| [`aidc semantic automations runs`](#aidc-semantic-automations-runs) | 列出自动化的运行记录 |
| [`aidc semantic automate capabilities`](#aidc-semantic-automate-capabilities) | 列出工作流可用的能力 |
| [`aidc semantic automate list`](#aidc-semantic-automate-list) | 列出工作流应用 |
| [`aidc semantic automate get`](#aidc-semantic-automate-get) | 看一个工作流的定义 |
| [`aidc semantic automate run`](#aidc-semantic-automate-run) | 开一次工作流运行 |
| [`aidc semantic automate runs`](#aidc-semantic-automate-runs) | 列出工作流的运行记录 |
| [`aidc semantic automate status`](#aidc-semantic-automate-status) | 看一次运行的每一步 |
| [`aidc semantic automate watch`](#aidc-semantic-automate-watch) | 等一次运行结束 |
| [`aidc semantic applications list`](#aidc-semantic-applications-list) | 列出本组织的看板 |
| [`aidc semantic applications save`](#aidc-semantic-applications-save) | 保存一个看板版本 |
| [`aidc semantic applications show`](#aidc-semantic-applications-show) | 看看板的定义和版本 |
| [`aidc semantic applications versions`](#aidc-semantic-applications-versions) | 看看板的版本历史 |
| [`aidc semantic applications publish`](#aidc-semantic-applications-publish) | 把一个版本发布给用户 |
| [`aidc semantic applications evaluate`](#aidc-semantic-applications-evaluate) | 按页面算出看板的数据 |
| [`aidc space ls`](#aidc-space-ls) | 列出你看得见的条目 |
| [`aidc space show`](#aidc-space-show) | 看一个条目 |
| [`aidc space get`](#aidc-space-get) | 下载一个条目的内容 |
| [`aidc space recent`](#aidc-space-recent) | 列出最近看过的条目 |
| [`aidc space page`](#aidc-space-page) | 建一个页 |
| [`aidc space edit`](#aidc-space-edit) | 改一个页的内容 |
| [`aidc space deploy`](#aidc-space-deploy) | 部署一个 HTML 文件、目录或 zip 成站点 |
| [`aidc space versions`](#aidc-space-versions) | 列出站点的版本 |
| [`aidc space version`](#aidc-space-version) | 看一个版本的文件清单 |
| [`aidc space deploy-version`](#aidc-space-deploy-version) | 部署一个版本，或回滚 |
| [`aidc space undeploy`](#aidc-space-undeploy) | 撤下站点 |
| [`aidc space rm-version`](#aidc-space-rm-version) | 删一个没在部署的版本 |
| [`aidc space upload`](#aidc-space-upload) | 上传文件 |
| [`aidc space project`](#aidc-space-project) | 建一个 Project |
| [`aidc space mv`](#aidc-space-mv) | 把条目移到 Project，或移回 Your files |
| [`aidc space rename`](#aidc-space-rename) | 改条目的名字 |
| [`aidc space share`](#aidc-space-share) | 分享给人、智能体或组 |
| [`aidc space access`](#aidc-space-access) | 看谁能打开这个条目 |
| [`aidc space people`](#aidc-space-people) | 列出可以分享给的人、智能体和组 |
| [`aidc space fav`](#aidc-space-fav) | 收藏一个条目 |
| [`aidc space unfav`](#aidc-space-unfav) | 取消收藏 |
| [`aidc space trash`](#aidc-space-trash) | 放进回收站 |
| [`aidc space restore`](#aidc-space-restore) | 从回收站恢复 |
| [`aidc space rm`](#aidc-space-rm) | 永久删除回收站里的条目 |
| [`aidc space empty-trash`](#aidc-space-empty-trash) | 清空回收站 |
| [`aidc semantic observability summary`](#aidc-semantic-observability-summary) | 看使用、反馈和错误的汇总 |
| [`aidc semantic observability events`](#aidc-semantic-observability-events) | 列出应用的记录 |
| [`aidc semantic observability feedback`](#aidc-semantic-observability-feedback) | 改一条反馈的状态 |
| [`aidc semantic usage summary`](#aidc-semantic-usage-summary) | 看今日、本月和累计的花费 |
| [`aidc semantic usage records`](#aidc-semantic-usage-records) | 看每一次调用的明细 |
| [`aidc semantic usage check`](#aidc-semantic-usage-check) | 核对账单 |
| [`aidc semantic usage prices`](#aidc-semantic-usage-prices) | 看每个模型的单价 |
| [`aidc semantic usage estimate`](#aidc-semantic-usage-estimate) | 估算一个月要花多少 |

## 访问：aidc semantic filesystem

这一组管资源的开放程度、角色、邀请链接和 Markings。资源是 Ontology、Object Type、智能体、文件和文件夹。只有资源的 Owner 能改分享和开放程度。本组织的开发者也算资源的 Owner（管理员兜底规则）。概念见 [访问与账号](auth.md)。应用的分享（`aidc share`）见 [参考 · 应用与界面](cli-apps.md#aidc-share)。

### aidc semantic filesystem list

列出你看得见的资源。member 也能用，只列出你有权看的资源。

```bash
aidc semantic filesystem list [--scope public|organization|shared|mine] [--type ontology|objectType|agent|file|folder]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--scope` | 资源的范围，取值见下面的列表 | `public` |
| `--type` | 只列一种资源 | 全部 |

`--scope` 的取值：

- `public`：所有登录的 AIDC 账号都能看见的资源。
- `shared`：别的组织分享给你的资源。
- `organization`：你所属组织的 Ontology，以及这些组织中已设置访问权限的资源。
- `mine`：资源访问记录中 Owner 是你的资源。

两种范围都只返回你有权打开的资源。

```terminal title="列出资源"
$ aidc semantic filesystem list --scope organization --type objectType
group        viewer     objectType 订单行  …
             ri.ontology.aidc.object-type.order-line
```

### aidc semantic filesystem show

看一个资源的类型、开放程度、你的角色和打开地址。member 也能用。

```bash
aidc semantic filesystem show <rid>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<rid>` | 资源的 RID，如 `ri.ontology.aidc.object-type.order-line` | — |

```terminal title="看一个资源"
$ aidc semantic filesystem show ri.ontology.aidc.object-type.order-line
group        viewer     objectType 订单行  …
             ri.ontology.aidc.object-type.order-line
打开：…
```

### aidc semantic filesystem roles

列出资源上的每一条角色授予，并标出来源。member 也能用。输出的第一行是资源名、你的角色和开放程度。

```bash
aidc semantic filesystem roles <rid>
```

```terminal title="看角色"
$ aidc semantic filesystem roles ri.ontology.aidc.object-type.order-line
订单行（我的角色 viewer，开放程度 group）
owner      GROUP cell-demo:developers  · 资源自带的规则
viewer     USER cm2n5y1d00006qz7p8r2t3k9v
```

### aidc semantic filesystem access

设置资源的开放程度。要资源的 Owner。

```bash
aidc semantic filesystem access <rid> --tier private|group|public|internet
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<rid>` | 资源的 RID | — |
| `--tier` | 开放程度，必填，取值见下面的列表 | — |

`--tier` 的取值：

- `private`：只有 Owner 能看。
- `group`：只有被分享的人和组能看。
- `public`：所有登录的 AIDC 账号能看。
- `internet`：不登录也能读，只读。不能执行 Action，也不能查 SQL。

```terminal title="设为组可见"
$ aidc semantic filesystem access ri.ontology.aidc.object-type.order-line --tier group
订单行：开放程度 group
owner      GROUP cell-demo:developers  · 资源自带的规则
```

### aidc semantic filesystem share

分享资源。要资源的 Owner。`--everyone` 和 `--internet` 只能给 `viewer` 角色。

```bash
aidc semantic filesystem share <rid> (--user <账号 id> | --group <组 id> | --everyone | --internet) [--role viewer|editor|owner]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<rid>` | 资源的 RID | — |
| `--user` | 分享给一个账号 | — |
| `--group` | 分享给一个组。`cell-…` 是本组织全员，`cell-…:developers` 是本组织的开发者 | — |
| `--everyone` | 分享给所有登录的 AIDC 账号（Public） | — |
| `--internet` | 分享给所有人，不登录也能读（Open to Internet） | — |
| `--role` | `viewer`、`editor` 或 `owner` | `viewer` |

```terminal title="分享给一个人"
$ aidc semantic filesystem share ri.ontology.aidc.object-type.order-line --user cm2n5y1d00006qz7p8r2t3k9v --role editor
已分享：订单行（开放程度 group）
owner      GROUP cell-demo:developers  · 资源自带的规则
editor     USER cm2n5y1d00006qz7p8r2t3k9v
```

### aidc semantic filesystem unshare

撤销一个分享。要资源的 Owner。`--role` 必填，要写出撤销哪个角色。

```bash
aidc semantic filesystem unshare <rid> (--user <账号 id> | --group <组 id> | --everyone | --internet) --role viewer|editor|owner
```

```bash
aidc semantic filesystem unshare ri.ontology.aidc.object-type.order-line --user cm2n5y1d00006qz7p8r2t3k9v --role editor
```

### aidc semantic filesystem link

生成邀请链接。要资源的 Owner。链接属于一个组。持链接的人登录后得到链接里的角色。链接只显示一次。

```bash
aidc semantic filesystem link <rid> [--days 30]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<rid>` | 资源的 RID | — |
| `--days` | 链接有效的天数 | `30` |

```terminal title="生成邀请链接"
$ aidc semantic filesystem link ri.ontology.aidc.object-type.order-line --days 7
邀请链接（属于 Group；只显示这一次；持链接的人登录后得到 viewer，到期 2026-10-15）：
  https://www.ai-dc.ai/…
```

### aidc semantic filesystem markings

看资源上挂的 Marking：直接挂的，和从上层继承来的。登录即可用，结果以你的权限为准。

```bash
aidc semantic filesystem markings <rid>
```

```terminal title="看挂的"
$ aidc semantic filesystem markings ri.ontology.aidc.object-type.order-line
订单行（objectType）
  直接挂的  薪资  cm2m4t8v00004qz7k3p9w1d2e
```

Marking 的意思和规则见 [Semantic](semantic.md)。

### aidc semantic filesystem mark

给资源挂上 Marking。要这个 Marking 的 USE 角色，并且是资源的 Owner。能挂的资源是 Ontology、Object Type、数据流、TableImport，以及数据基座里的文件与文件夹。

```bash
aidc semantic filesystem mark <rid> <Marking id…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<rid>` | 资源的 RID | — |
| `<Marking id…>` | 一个或多个 Marking 的 id。用 `aidc semantic admin markings list` 查 | — |

```terminal title="挂上"
$ aidc semantic filesystem mark ri.ontology.aidc.object-type.order-line cm2m4t8v00004qz7k3p9w1d2e
订单行（objectType）
  直接挂的  薪资  cm2m4t8v00004qz7k3p9w1d2e
```

### aidc semantic filesystem unmark

去掉资源上的 Marking。要这个 Marking 的 DECLASSIFY 和 USE 角色，并且是资源的 Owner。

```bash
aidc semantic filesystem unmark <rid> <Marking id…>
```

```bash
aidc semantic filesystem unmark ri.ontology.aidc.object-type.order-line cm2m4t8v00004qz7k3p9w1d2e
```

## 账号与组织：aidc semantic admin

这一组管当前身份、成员、组、用户属性和组织。写操作要本组织的 developer。`aidc groups`、`aidc users`、`aidc organization` 与 `aidc semantic admin` 下的同名命令相同。部门就是组，组可以嵌套。概念见 [Semantic](semantic.md)。

### aidc semantic admin whoami

看当前登录的账号、组织、角色、Key 前缀，以及能发布到哪些组织。member 也能用。这条命令与 `aidc whoami` 相同，见 [参考 · 账号与环境](cli-account.md)。

```bash
aidc semantic admin whoami
```

```terminal title="看身份"
$ aidc semantic admin whoami
张三（zhang.san）· Demo Company（cell-demo）· developer · Key aidc-dk-xxxxxxxx… · 可发布到 cell-demo
```

member 登录时，最后一段显示「不能部署 / 发布（member）」。

### aidc semantic admin members list

列出本组织的人：角色、状态和邮箱。要 developer。

```bash
aidc semantic admin members list
```

```terminal title="列出成员"
$ aidc semantic admin members list
Demo Company（cell-demo）· 3 人
  developer  已激活  张三  <zhang.san@example.com>
  member     已激活  李四  <li.si@example.com>
  member     待激活  王五  <wang.wu@example.com>
```

### aidc semantic admin members import

把已有的用户名单导入为本组织的 member。要 developer。先加 `--dry-run` 看每个人会怎么处理。

```bash
aidc semantic admin members import <名单.json|.csv> --source <来源名> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<名单.json\|.csv>` | 名单文件：JSON 数组，或 `{ "members": [...] }`；CSV 表头要有 `email` | — |
| `--source` | 来源名，如 `old-portal`，必填 | — |
| `--dry-run` | 只预演，不写入 | — |

一次最多导入 1000 人。每个人的处理方式：

- `新建待激活账号 + member`：AIDC 里没有这个邮箱。建一个待激活账号和本组织的 member。
- `补 member`：已有账号，但还不是本组织的人。
- `已是 member，不动`。
- `已是 developer，不动`：不降级。
- `账号已停用，不动`。
- `冲突，未处理`。

```terminal title="预演导入"
$ aidc semantic admin members import members.csv --source old-portal --dry-run
预演（没有写入）：Demo Company（cell-demo）· 来源 old-portal · 3 人
  新建待激活账号 + member：2
  已是 member，不动：1
  席位：12 → 14 / 50
确认无误后去掉 --dry-run 再跑一次；重复导入不会重复建号。
```

不加 `--dry-run` 时，命令打印「已导入」。新账号的本人用这个邮箱在 https://www.ai-dc.ai/login 收验证码登录，即可激活。

### aidc semantic admin groups list

列出本组织的组，每行是编号、名字和说明。member 也能用，组名和说明对组织成员都可见。

```bash
aidc semantic admin groups list
```

```terminal title="列出组"
$ aidc semantic admin groups list
cm2k9f3a70001qz7d5w1b8x4n  财务  财务部的人
cm2n6q2e00007qz7x1c4v8m5r  应付  应付账款组
```

### aidc semantic admin groups show

看一个组：名字、说明、realm 和属性。member 也能用。

```bash
aidc semantic admin groups show <组 id>
```

```bash
aidc semantic admin groups show cm2k9f3a70001qz7d5w1b8x4n
```

### aidc semantic admin groups search

按名字前缀找组。member 也能用。

```bash
aidc semantic admin groups search <名字前缀>
```

```terminal title="找组"
$ aidc semantic admin groups search 财
cm2k9f3a70001qz7d5w1b8x4n  财务  财务部的人
```

### aidc semantic admin groups mine

看自己在哪些组里。member 也能用。

```bash
aidc semantic admin groups mine
```

```terminal title="我的组"
$ aidc semantic admin groups mine
cm2k9f3a70001qz7d5w1b8x4n  财务  财务部的人
```

### aidc semantic admin groups create

建一个组。要 developer。组名在本组织内唯一。

```bash
aidc semantic admin groups create --name <组名> [--description <说明>] [--attr <键=值>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name` | 组名，必填 | — |
| `--description` | 说明 | — |
| `--attr` | 组的属性，写成 `键=值`。可以重复写 | — |

```terminal title="建一个组"
$ aidc semantic admin groups create --name 财务 --description 财务部的人
已建组：cm2k9f3a70001qz7d5w1b8x4n  财务  财务部的人
加成员：aidc semantic admin groups add-members cm2k9f3a70001qz7d5w1b8x4n <账号或组 id>
```

### aidc semantic admin groups rename

改组名或说明。要 developer。

```bash
aidc semantic admin groups rename <组 id> --name <新组名> [--description <说明>]
```

```terminal title="改组名"
$ aidc semantic admin groups rename cm2k9f3a70001qz7d5w1b8x4n --name 财务部
已改：cm2k9f3a70001qz7d5w1b8x4n  财务部  财务部的人
```

### aidc semantic admin groups delete

删除一个组。要 developer。成员资格、授给这个组的资源角色和 Marking 成员资格都会收回。

```bash
aidc semantic admin groups delete <组 id>
```

```terminal title="删除一个组"
$ aidc semantic admin groups delete cm2n6q2e00007qz7x1c4v8m5r
已删组 cm2n6q2e00007qz7x1c4v8m5r（成员资格、授给它的资源角色、Marking 成员资格一起收回）
```

> [!WARNING]
> 删组会收回它授下去的资源角色和 Marking 成员资格。删之前先看 `aidc semantic admin groups members`。

### aidc semantic admin groups members

列出组的成员：账号或组，有到期时间的会标出。要 developer。组的成员本人也能看。

```bash
aidc semantic admin groups members <组 id> [--transitive]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<组 id>` | 组的 id | — |
| `--transitive` | 连嵌套组里的人一起列出 | — |

```terminal title="看组成员"
$ aidc semantic admin groups members cm2k9f3a70001qz7d5w1b8x4n
账号 cm2n5y1d00006qz7p8r2t3k9v  到期 2026-12-31
账号 cm2o7w3f00008qz7b6t5k1n4q
组   cm2n6q2e00007qz7x1c4v8m5r
```

### aidc semantic admin groups add-members

给组加成员。要 developer。成员可以是账号或组。组之间不能成环。

```bash
aidc semantic admin groups add-members <组 id> <账号或组 id…> [--expires 2026-12-31]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<组 id>` | 组的 id | — |
| `<账号或组 id…>` | 一个或多个账号 id 或组 id | — |
| `--expires` | 到期日。到这一天结束为止 | 不到期 |

```terminal title="加成员"
$ aidc semantic admin groups add-members cm2k9f3a70001qz7d5w1b8x4n cm2n5y1d00006qz7p8r2t3k9v --expires 2026-12-31
已加 1 个成员
```

### aidc semantic admin groups remove-members

从组里移出成员。要 developer。

```bash
aidc semantic admin groups remove-members <组 id> <id…>
```

```terminal title="移出成员"
$ aidc semantic admin groups remove-members cm2k9f3a70001qz7d5w1b8x4n cm2o7w3f00008qz7b6t5k1n4q
已移出 1 个成员
```

### aidc semantic admin groups expiration

设置或查看组的成员到期规则：新成员最多在多少天内到期，或必须早于某一天。设置要 developer。

```bash
aidc semantic admin groups expiration <组 id> [--days <天数>] [--until 2026-12-31] [--clear]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<组 id>` | 组的 id | — |
| `--days` | 从现在起最多多少天 | — |
| `--until` | 到期必须早于这一天 | — |
| `--clear` | 取消到期规则 | — |

`--days` 和 `--until` 都设时，取更严的那个。不带参数时只查看当前规则。

```terminal title="设置到期规则"
$ aidc semantic admin groups expiration cm2n6q2e00007qz7x1c4v8m5r --days 90
90 天内
$ aidc semantic admin groups expiration cm2n6q2e00007qz7x1c4v8m5r --clear
不限制
```

### aidc semantic admin users list

列出本组织的用户：编号、用户名、名字、组织、状态和属性。要 developer。

```bash
aidc semantic admin users list
```

```terminal title="列出用户"
$ aidc semantic admin users list
cm2k9f3a70001qz7d5w1b8x4n  zhang.san  张三  cell-demo  ACTIVE  department=财务  jobTitle=会计
cm2o7w3f00008qz7b6t5k1n4q  li.si  李四  cell-demo  ACTIVE
```

### aidc semantic admin users show

看一个用户的账号、组织、状态和属性。不写账号 id 时看自己（`me`）。看自己谁都能用。看别人要 developer。

```bash
aidc semantic admin users show [<账号 id>|me]
```

```terminal title="看自己"
$ aidc semantic admin users show me
cm2k9f3a70001qz7d5w1b8x4n  zhang.san  张三  cell-demo  ACTIVE  department=财务  jobTitle=会计
  department=财务
  jobTitle=会计
```

### aidc semantic admin users search

按前缀找用户。要 developer。

```bash
aidc semantic admin users search <前缀>
```

```terminal title="找用户"
$ aidc semantic admin users search li
cm2o7w3f00008qz7b6t5k1n4q  li.si  李四  cell-demo  ACTIVE
```

### aidc semantic admin users groups

看一个用户在哪些组里。看自己谁都能用。看别人要 developer。`--transitive` 连嵌套组一起列出。

```bash
aidc semantic admin users groups [<账号 id>|me] [--transitive]
```

```terminal title="看自己的组"
$ aidc semantic admin users groups me
cm2k9f3a70001qz7d5w1b8x4n
```

### aidc semantic admin users set-attributes

设置用户的属性，例如部门（`department`）和岗位（`jobTitle`）。要主组织的 developer。一个属性的多个值用逗号分开。`multipass:` 开头的属性名保留给平台。

```bash
aidc semantic admin users set-attributes <账号 id> <键=值1,值2> …
```

```terminal title="设置属性"
$ aidc semantic admin users set-attributes cm2o7w3f00008qz7b6t5k1n4q department=财务 jobTitle=会计
已改：cm2o7w3f00008qz7b6t5k1n4q  li.si  李四  cell-demo  ACTIVE  department=财务  jobTitle=会计
```

### aidc semantic admin organization

看组织的编号（`cell-…`）和名字。不写编号时看登录的组织。登录即可用。

```bash
aidc semantic admin organization [<cell-…>]
```

```terminal title="看组织"
$ aidc semantic admin organization
cell-demo  Demo Company
```

## Markings：aidc semantic admin

Marking 是强制控制。访问资源时，既要有资源角色，也要满足 Marking 条件。Owner 和 developer 也不能绕过 Marking。Marking 分类别。类别有两种：`CONJUNCTIVE`（全都要满足）和 `DISJUNCTIVE`（满足任一）。类别由本组织的开发者建。Marking 的成员和角色由它的 ADMINISTER 管。`aidc markings` 和 `aidc marking-categories` 与 `aidc semantic admin` 下的同名命令相同。规则见 [Semantic](semantic.md)。

### aidc semantic admin marking-categories list

列出本组织的 Marking 类别。登录即可用，结果以你的权限为准。

```bash
aidc semantic admin marking-categories list
```

```terminal title="列出类别"
$ aidc semantic admin marking-categories list
cm2m4t8v00005qz7k1r9p2q7w  数据分级  全都要满足（CONJUNCTIVE）  Visible  2 个 Marking
```

### aidc semantic admin marking-categories show

看一个类别，以及它里面的 Marking。登录即可用，结果以你的权限为准。

```bash
aidc semantic admin marking-categories show <类别 id>
```

```terminal title="看类别"
$ aidc semantic admin marking-categories show cm2m4t8v00005qz7k1r9p2q7w
cm2m4t8v00005qz7k1r9p2q7w  数据分级  全都要满足（CONJUNCTIVE）  Visible  2 个 Marking
  Marking：cm2m4t8v00004qz7k3p9w1d2e、cm2m4t8v00006qz7n5x8c3f1d
```

### aidc semantic admin marking-categories create

建一个 Marking 类别。要 developer。创建的人成为这个类别的 ADMINISTER。

```bash
aidc semantic admin marking-categories create --name <类别名> [--description <说明>] [--disjunctive] [--hidden]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name` | 类别名，必填 | — |
| `--description` | 说明 | — |
| `--disjunctive` | 类别是 `DISJUNCTIVE`，满足任一即可 | `CONJUNCTIVE` |
| `--hidden` | 类别设为 Hidden | Visible |

```terminal title="建类别"
$ aidc semantic admin marking-categories create --name 数据分级
已建类别：cm2m4t8v00005qz7k1r9p2q7w  数据分级  全都要满足（CONJUNCTIVE）  Visible  0 个 Marking
下一步：aidc semantic admin markings create --name … --category cm2m4t8v00005qz7k1r9p2q7w
```

### aidc semantic admin marking-categories rename

改类别的名字或说明。以服务端的权限为准。

```bash
aidc semantic admin marking-categories rename <类别 id> --name <新名字> [--description <说明>]
```

```terminal title="改类别名"
$ aidc semantic admin marking-categories rename cm2m4t8v00005qz7k1r9p2q7w --name 数据密级
已改：cm2m4t8v00005qz7k1r9p2q7w  数据密级  全都要满足（CONJUNCTIVE）  Visible  2 个 Marking
```

> [!WARNING]
> 类别和 Marking 建了就不能删。Marking 也不能换到别的类别。

### aidc semantic admin markings list

列出本组织的 Marking。登录即可用，结果以你的权限为准。

```bash
aidc semantic admin markings list
```

```terminal title="列表"
$ aidc semantic admin markings list
cm2m4t8v00004qz7k3p9w1d2e  薪资  类别 cm2m4t8v00005qz7k1r9p2q7w  人事用的薪资数据
```

### aidc semantic admin markings show

看一个 Marking。登录即可用，结果以你的权限为准。

```bash
aidc semantic admin markings show <Marking id>
```

```bash
aidc semantic admin markings show cm2m4t8v00004qz7k3p9w1d2e
```

### aidc semantic admin markings create

建一个 Marking。要类别的 ADMINISTER。创建的人是这个 Marking 的 ADMINISTER，但不是成员。

```bash
aidc semantic admin markings create --name <名字> --category <类别 id> [--description <说明>] [--member <主体>,…]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name` | Marking 的名字，必填 | — |
| `--category` | 所属类别的 id，必填 | — |
| `--description` | 说明 | — |
| `--member` | 建的时候加成员。可以重复，也可以用逗号分开 | — |

`<主体>` 是账号 id、组 id，或 `cell-…`（本组织全员），或 `cell-…:developers`（本组织的开发者）。

```terminal title="新建"
$ aidc semantic admin markings create --name 薪资 --category cm2m4t8v00005qz7k1r9p2q7w --member cm2n6q2e00007qz7x1c4v8m5r
已建 Marking：cm2m4t8v00004qz7k3p9w1d2e  薪资  类别 cm2m4t8v00005qz7k1r9p2q7w
你是它的 ADMINISTER（不是成员）。挂到资源上：aidc semantic filesystem mark <rid> cm2m4t8v00004qz7k3p9w1d2e
```

### aidc semantic admin markings rename

改 Marking 的名字或说明。要 ADMINISTER。

```bash
aidc semantic admin markings rename <Marking id> --name <新名字> [--description <说明>]
```

```terminal title="改名"
$ aidc semantic admin markings rename cm2m4t8v00004qz7k3p9w1d2e --name 薪酬
已改：cm2m4t8v00004qz7k3p9w1d2e  薪酬  类别 cm2m4t8v00005qz7k1r9p2q7w
```

### aidc semantic admin markings members

列出 Marking 的成员：账号和组。要 ADMINISTER。

```bash
aidc semantic admin markings members <Marking id>
```

```terminal title="看成员"
$ aidc semantic admin markings members cm2m4t8v00004qz7k3p9w1d2e
组   cm2n6q2e00007qz7x1c4v8m5r
账号 cm2n5y1d00006qz7p8r2t3k9v
```

### aidc semantic admin markings add-members

给 Marking 加成员。要 ADMINISTER。打印返回的成员列表。

```bash
aidc semantic admin markings add-members <Marking id> <主体…>
```

```bash
aidc semantic admin markings add-members cm2m4t8v00004qz7k3p9w1d2e cm2o7w3f00008qz7b6t5k1n4q
```

### aidc semantic admin markings remove-members

从 Marking 移出成员。要 ADMINISTER。

```bash
aidc semantic admin markings remove-members <Marking id> <主体…>
```

```bash
aidc semantic admin markings remove-members cm2m4t8v00004qz7k3p9w1d2e cm2o7w3f00008qz7b6t5k1n4q
```

### aidc semantic admin markings roles

列出 Marking 的角色分配：谁是 ADMINISTER、DECLASSIFY 或 USE。持有这个 Marking 的任一角色，或是本组织的 developer，都能查看。

```bash
aidc semantic admin markings roles <Marking id>
```

```terminal title="看角色"
$ aidc semantic admin markings roles cm2m4t8v00004qz7k3p9w1d2e
ADMINISTER  账号 cm2n5y1d00006qz7p8r2t3k9v
USE         组   cm2n6q2e00007qz7x1c4v8m5r
```

### aidc semantic admin markings grant

授予 Marking 的角色。要 ADMINISTER。角色是 `ADMINISTER`、`DECLASSIFY` 或 `USE`。USE 让人可以把这个 Marking 挂到资源上。DECLASSIFY 让人可以去掉挂上的 Marking。

```bash
aidc semantic admin markings grant <Marking id> ADMINISTER|DECLASSIFY|USE <主体…>
```

```bash
aidc semantic admin markings grant cm2m4t8v00004qz7k3p9w1d2e USE cm2n6q2e00007qz7x1c4v8m5r
```

### aidc semantic admin markings revoke

收回 Marking 的角色。要 ADMINISTER。

```bash
aidc semantic admin markings revoke <Marking id> ADMINISTER|DECLASSIFY|USE <主体…>
```

```bash
aidc semantic admin markings revoke cm2m4t8v00004qz7k3p9w1d2e USE cm2n6q2e00007qz7x1c4v8m5r
```

### aidc semantic admin markings mine

看我是哪些 Marking 的成员。`--user` 看本组织某人的。登录即可用，结果以你的权限为准。

```bash
aidc semantic admin markings mine [--user <账号 id>]
```

```terminal title="我的"
$ aidc semantic admin markings mine
cm2m4t8v00004qz7k3p9w1d2e  薪资
```

## 自动化：aidc semantic automations

这一组管组织级的自动化（Automation）。数据变化或到了时间，自动化执行 Action、函数或邮件通知。它替代 cron。查看定义和运行记录，member 也能用。创建、修改、暂停、恢复、删除和立即运行，要 developer。概念见 [自动化](workflow.md)。工作流应用的运行在下一组。

`list`、`upsert` 和 `runs` 用 `--ontology <cell-…>` 指定组织，不用 `-n`。

### aidc semantic automations list

列出组织级的自动化：状态、条件类型、名字、替代的 cron 数和上次触发时间。member 也能用。

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

```terminal title="列出自动化"
$ aidc semantic automations list --ontology cell-demo
active  runOnAllObjects  任务逾期（替代 1 个 cron）· 上次触发 2026-10-08T01:30:00.000Z
  ri.aidc.automate.cell-demo.automation.dev-task-overdue
```

### aidc semantic automations upsert

建一个自动化；已有的自动化会被更新。要 developer。加 `--dry-run` 只校验，并看对象集，不保存。保存时从现在开始记录对象，不回放历史。

```bash
aidc semantic automations upsert --ontology <cell-…> --file <automation.json> [--dry-run]
```

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

定义文件的写法。下面的例子每个工作日 09:30 检查状态为「待接受」「进行中」或「阻塞」、截止日期到今天为止的任务，给负责人发邮件：

```json
{
  "apiName": "dev-task-overdue", "displayName": "任务逾期", "status": "active",
  "condition": { "type": "runOnAllObjects", "every": "1d", "at": "09:30", "weekdays": [1, 2, 3, 4, 5],
    "objectSet": { "type": "filter", "objectSet": { "type": "base", "objectType": "devTask" }, "where": { "type": "and", "value": [
      { "type": "in", "field": "status", "value": ["待接受", "进行中", "阻塞"] },
      { "type": "relativeDateRange", "field": "dueDate", "relativeEndTime": { "value": 0, "timeUnit": "DAYS" }, "timeZoneId": "Asia/Shanghai" } ] } } },
  "effects": [{ "type": "notification", "channel": "email", "executionMode": { "type": "perObject" },
    "recipients": [{ "type": "propertyBacked", "property": "assigneeAccountId" }],
    "title": "任务逾期：{{title}}", "template": "{{#objects}}任务「{{title}}」截止 {{dueDate}}，现在是「{{status}}」。{{/objects}}" }]
}
```

```terminal title="预演自动化"
$ aidc semantic automations upsert --ontology cell-demo --file 任务逾期.json --dry-run
预演：任务逾期（看 devTask）
  ri.aidc.automate.cell-demo.automation.dev-task-overdue
```

> [!IMPORTANT]
> 效果类型只接受 `action`、`function` 和邮件 `notification`。

### aidc semantic automations show

看一个自动化：名字、状态、下次评估时间，以及最近 20 次运行。member 也能用。

```bash
aidc semantic automations show <automationRid>
```

```terminal title="看一个自动化"
$ aidc semantic automations show ri.aidc.automate.cell-demo.automation.dev-task-overdue
任务逾期（active，下次评估 2026-10-09T01:30:00.000Z）
2026-10-08T01:30:00.000Z succeeded  3 个对象 · notification:succeeded
```

### aidc semantic automations run

立即开一次运行，不等条件。要 developer。

```bash
aidc semantic automations run <automationRid>
```

```terminal title="立即运行"
$ aidc semantic automations run ri.aidc.automate.cell-demo.automation.dev-task-overdue
已开跑：{…}
```

`{…}` 是这次运行的对象，打印在一行里，是 JSON。

### aidc semantic automations pause

暂停一个自动化。要 developer。暂停期间，条件不触发，到期也不执行。恢复后，从恢复的时间起重新记录对象。暂停期间的变化不补发。

```bash
aidc semantic automations pause <automationRid>
```

```terminal title="暂停"
$ aidc semantic automations pause ri.aidc.automate.cell-demo.automation.dev-task-overdue
任务逾期：paused
```

### aidc semantic automations resume

恢复一个暂停的自动化。要 developer。

```bash
aidc semantic automations resume <automationRid>
```

```terminal title="恢复"
$ aidc semantic automations resume ri.aidc.automate.cell-demo.automation.dev-task-overdue
任务逾期：active
```

### aidc semantic automations delete

删除一个自动化。要 developer。

```bash
aidc semantic automations delete <automationRid>
```

```terminal title="删除"
$ aidc semantic automations delete ri.aidc.automate.cell-demo.automation.dev-task-overdue
已删：任务逾期
```

### aidc semantic automations runs

列出自动化的运行记录，最新的在前。每次运行一行：时间、状态、对象数，和每个效果的结果。member 也能用。

```bash
aidc semantic automations runs --ontology <cell-…> [--automation <rid 或 apiName>] [--status <状态>] [--since <ISO 时间>] [--page-size 50] [--page-token <游标>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间，必填 | — |
| `--automation` | 只看一个自动化，写 RID 或 `apiName` | 全部 |
| `--status` | 只看一种状态，如 `failed` | 全部 |
| `--since` | 只看这个时间以后的运行，写 ISO 时间 | — |
| `--page-size` | 每页行数 | `50` |
| `--page-token` | 翻页用的游标，接在上一页末尾的提示后面 | — |

```bash
aidc semantic automations runs --ontology cell-demo --automation dev-task-overdue --status failed --since 2026-10-01T00:00:00Z
```

有下一页时，输出的最后一行是 `下一页：--page-token <游标>`。第三列是触发类型：`change`、`manual`、`time` 或 `schedule`。它们分别表示数据变化、手动运行、时间条件和对象集定时运行。

## Automate 工作流：aidc semantic automate

这一组管工作流应用（Automate）的能力、运行和结果。工作流把已发布应用的能力连成一张图，可以手动运行，也可以在数据变化时自动运行。工作流的写法见 [自动化](workflow.md)。

运行权限：开发者 Key 可以正式运行，也可以预演。工作流清单 `trigger.manual.roles` 里的角色可以正式运行。本组织的其他成员只能预演（`--preview`）。`--channel test` 只对开发者有效，它运行测试通道的版本。

### aidc semantic automate capabilities

列出能力目录：已发布应用对外提供的能力。`●` 是清单显式导出的能力，`○` 是平台自动提取的。`--app` 只看一个应用的能力。登录即可用。

```bash
aidc semantic automate capabilities [--app <slug>]
```

```bash
aidc semantic automate capabilities --app order-desk
```

### aidc semantic automate list

列出工作流应用：标题、负责部门、正式版本和测试版本、步数、触发方式和最近一次运行。登录即可用。

```bash
aidc semantic automate list
```

### aidc semantic automate get

看一个工作流的定义：触发方式、泳道，以及每一层的步骤。登录即可用。`--channel test` 看测试通道的版本，只对开发者有效。

```bash
aidc semantic automate get <slug> [--channel test]
```

```bash
aidc semantic automate get order-check
```

### aidc semantic automate run

开一次工作流运行。正式运行要开发者 Key，或清单 `trigger.manual.roles` 里的角色。其他本组织成员只能加 `--preview`。默认等运行结束。每完成一步，打印一行进度。

```bash
aidc semantic automate run <slug> [--input '{…}'] [--param <名=值>] [--preview] [--channel test] [--no-wait]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 工作流应用的 slug | — |
| `--input` | 输入，一个 JSON 对象 | — |
| `--param` | 一个输入，写成 `名=值`，可以重复。同名的键，`--param` 优先 | — |
| `--preview` | 预演。读、算和模型分析照跑；写入只返回计划 | 正式运行 |
| `--channel` | `test` 运行测试通道的版本，只对开发者有效 | `production` |
| `--no-wait` | 开跑后立即返回，只打印运行 id | — |
| `--idempotency-key` | 幂等键。同一个键返回同一次运行 | — |
| `--dry-run` | 只校验输入，打印将执行的步骤 | — |

```terminal title="预演输入"
$ aidc semantic automate run order-check --param order=SO-1002 --dry-run
（dry-run）输入合格，将按 3 步执行：
  第 1 层 [订单] 读取订单
  第 2 层 [计算] 算缺料
  第 3 层 [模型] 写分析
```

```terminal title="预演运行"
$ aidc semantic automate run order-check --param order=SO-1002 --preview
✓ [订单] 读取订单  ← order-desk/open_orders@1.0.0（120 ms，1 行）
✓ [计算] 算缺料（85 ms）
✓ [模型] 写分析（2100 ms，1020 tokens）
运行 cm2k9f3a70001qz7d5w1b8x4n  预演 · succeeded  v1.0.0（production）  手动  3.4 s  1020 tokens
✓ [订单] 读取订单  ← order-desk/open_orders@1.0.0（120 ms，1 行）
✓ [计算] 算缺料（85 ms）
✓ [模型] 写分析（2100 ms，1020 tokens）
结果：{"summary":"缺料 2 项，建议延期交货"}
```

每一步前面的 `✓` 是成功，`✗` 是失败，`–` 是跳过，`…` 是运行中，`·` 是等待。运行失败时，命令的退出码是 1。

```terminal title="只开跑"
$ aidc semantic automate run order-check --param order=SO-1002 --no-wait
已开跑：cm2k9f3a70001qz7d5w1b8x4n（aidc semantic automate status order-check cm2k9f3a70001qz7d5w1b8x4n）
```

### aidc semantic automate runs

列出一个工作流最近的运行，最新的在前。每次运行一行：状态、运行 id、时间、预演或正式、触发来源、每一步的状态和耗时。登录即可用。

```bash
aidc semantic automate runs <slug> [--limit <条数>]
```

```terminal title="看运行记录"
$ aidc semantic automate runs order-check --limit 2
✓ cm2k9f3a70001qz7d5w1b8x4n  2026-10-08 14:03  预演  手动 张三  ✓✓✓  3.4 s
✗ cm2k9f3a70001qz7d5w1b8x3m  2026-10-08 13:10  正式  数据变化 SO-1005  ✓✓✗  1.2 s  模型超时
```

没有运行时，命令打印「还没有运行。」。

### aidc semantic automate status

看一次运行：每一步的状态、耗时和输出，最后是运行的结果。登录即可用。

```bash
aidc semantic automate status <slug> <运行 id>
```

```terminal title="看一次运行"
$ aidc semantic automate status order-check cm2k9f3a70001qz7d5w1b8x4n
运行 cm2k9f3a70001qz7d5w1b8x4n  预演 · succeeded  v1.0.0（production）  手动  3.4 s  1020 tokens
✓ [订单] 读取订单  ← order-desk/open_orders@1.0.0（120 ms，1 行）
✓ [计算] 算缺料（85 ms）
✓ [模型] 写分析（2100 ms，1020 tokens）
结果：{"summary":"缺料 2 项，建议延期交货"}
```

### aidc semantic automate watch

等一次运行结束。运行中每次有步骤变化，打印一行进度。结束后打印这次运行的结果。成功时退出码是 0，失败时是 1。

```bash
aidc semantic automate watch <slug> <运行 id>
```

```terminal title="等运行结束"
$ aidc semantic automate watch order-check cm2k9f3a70001qz7d5w1b8x4n
✓…·  running
✓✓✓  succeeded
运行 cm2k9f3a70001qz7d5w1b8x4n  预演 · succeeded  v1.0.0（production）  手动  3.4 s  1020 tokens
✓ [订单] 读取订单  ← order-desk/open_orders@1.0.0（120 ms，1 行）
✓ [计算] 算缺料（85 ms）
✓ [模型] 写分析（2100 ms，1020 tokens）
结果：{"summary":"缺料 2 项，建议延期交货"}
```

## 看板：aidc semantic applications

这一组管 Semantic 里的看板（Workshop 模块）。看板只存页面、组件和变量的定义。打开时，平台按看的人的权限从本体现算数据。概念见 [看板与工作台](workshop.md)。

谁能做什么：保存和发布要 developer。组织成员打开看板时，只看到已发布的版本。谁能发布由组织的审批策略决定，见 [Semantic](semantic.md)。

### aidc semantic applications list

列出本组织的看板：已发布的版本号、最新版本号，以及最后保存的人。member 也能用。

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

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

```terminal title="列出看板"
$ aidc semantic applications list --ontology cell-demo
v3     云费用看板（最新 v4，人保存；替代 0 个旧页面）
  ri.aidc.workshop.cell-demo.module.cloud-costs
```

### aidc semantic applications save

保存一个新版本。没有这个看板就新建。要 developer。用网页会话、开发者 Key，或智能体的 Agent Key 都可以。加 `--dry-run` 只校验：类型、属性和变量引用都按你的权限检查。`--as-agent` 声明这是智能体在用你的 Key。

```bash
aidc semantic applications save --ontology <cell-…> --file <应用.json> [--dry-run] [--publish] [--as-agent <智能体 id>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ontology` | 组织的命名空间，必填 | — |
| `--file` | 看板的定义，JSON。字段与 API 请求体一致，写法见 [看板与工作台](workshop.md) | — |
| `--dry-run` | 只校验，不保存 | — |
| `--publish` | 保存后直接发布 | 不发布 |
| `--as-agent` | 智能体的 id。把这个版本记为智能体保存的 | — |

```terminal title="校验"
$ aidc semantic applications save --ontology cell-demo --file 云费用看板.json --dry-run
校验通过：将保存为 v1（新应用）
```

```bash
aidc semantic applications save --ontology cell-demo --file 云费用看板.json --publish
```

### aidc semantic applications show

看看板的定义：版本号、发布的版本号和页面。成员只能看已发布的版本。开发者可以用 `--version` 看任一版本。

```bash
aidc semantic applications show <moduleRid> [--version <版本号>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<moduleRid>` | 看板的 RID | — |
| `--version` | 看哪个版本。只对开发者有效 | 已发布的版本 |

```terminal title="看看板"
$ aidc semantic applications show ri.aidc.workshop.cell-demo.module.cloud-costs
云费用看板：v3（发布 v3）· 页面 总览(overview)、明细(detail)
  …
```

### aidc semantic applications versions

看看板的版本历史：版本号、保存时间、谁保存的，以及是否发布过。要 developer。

```bash
aidc semantic applications versions <moduleRid>
```

```terminal title="看版本"
$ aidc semantic applications versions ri.aidc.workshop.cell-demo.module.cloud-costs
v4    2026-10-08T14:03:00.000Z 智能体 ops-agent
v3    2026-10-07T10:20:00.000Z 人 account:cm2k9f3a70001qz7d5w1b8x4n · 发布过 · 加了逾期列
```

### aidc semantic applications publish

把一个版本发布给用户。用户看到的版本就是这一个。要 developer。审批策略是 `review` 时，智能体保存的版本要人在 Semantic 网页上点「发布」。`--dry-run` 只预演。

```bash
aidc semantic applications publish <moduleRid> <版本号> [--dry-run]
```

```terminal title="发布版本"
$ aidc semantic applications publish ri.aidc.workshop.cell-demo.module.cloud-costs 4
云费用看板：用户现在看到 v4
```

### aidc semantic applications evaluate

按看板的页面算出一页数据：每个组件的结果。成员看已发布的版本。开发者可以用 `--version` 指定版本。智能体也用它取数。

```bash
aidc semantic applications evaluate <moduleRid> [--page <页面 id>] [--filters '<JSON>'] [--version <版本号>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<moduleRid>` | 看板的 RID | — |
| `--page` | 页面的 id | 第一页 |
| `--filters` | 筛选条件，JSON：`{ "<筛选变量>": { "<属性>": "值" } }` | — |
| `--version` | 版本号。只对开发者有效 | 已发布的版本 |

```terminal title="取一页数据"
$ aidc semantic applications evaluate ri.aidc.workshop.cell-demo.module.cloud-costs --page overview --filters '{"vendorFilter":{"vendor":"Vercel"}}'
v4 · 总览
  kpi [metricCard] 合计（美元）=1234.56
  byVendor [chartXY] 3 个类目
```

## Space：aidc space

这一组管 Space：每个人和每个智能体自己的空间。Space 里有页（Markdown）、文件、站点（自包含的 HTML，自动部署成网页），以及 Project（共享的容器）。人和智能体用同一套命令。`aidc semantic space` 与 `aidc space` 相同。概念见 [Media sets 与 Space](media.md)。

登录的人都能用，只能操作自己有权限的条目。只有 Owner 能分享、放进回收站、恢复和永久删除。Editor 能改内容和名字。智能体能读的，不超过它的 owner。

打开地址是 `<API 根地址>/semantic/<cell>/space/items/<id>`。默认根地址为 `https://www.ai-dc.ai`。站点地址是 `<API 根地址>/p/<cell>/<slug>`。

### aidc space ls

列出你看得见的条目。member 也能用。

```bash
aidc space ls [--view all|pages|sites|images|files|projects|trash] [--tab suggested|favorites|yours|shared] [--project <id>] [--q <词>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--view` | 只看一类：页、站点、图片、文件、Project 或回收站 | 服务端决定 |
| `--tab` | 看一组：推荐、收藏、我的，或分享给我的 | 服务端决定 |
| `--project` | 只看一个 Project 里的条目 | — |
| `--q` | 按名字搜索 | — |

```terminal title="列出条目"
$ aidc space ls
Demo Company（cell-demo）
cm2k9f3a70001qz7d5w1b8x4n  页    周会纪要
                          张三 · owner · private · 2026-10-08 14:03
```

### aidc space show

看一个条目：类型、所有者、角色、开放程度和打开地址。member 也能用。

```bash
aidc space show <id>
```

```terminal title="看一个条目"
$ aidc space show cm2k9f3a70001qz7d5w1b8x4o
cm2k9f3a70001qz7d5w1b8x4o  站点 周报
                          运营助手 [AI] · owner · group · 2026-10-07 18:20
打开：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4o
站点：https://www.ai-dc.ai/p/cell-demo/7a2c9e4b1f80
```

### aidc space get

下载条目的内容。页是 Markdown，文件是原来的字节。不加 `--out` 时，内容打印到标准输出。member 也能用。

站点加 `--out <目录>` 时，命令把部署版本的全部文件写进这个目录。加 `--version` 下载指定的版本。只有一个 HTML 的旧站点，`--out` 写一个文件。

```bash
aidc space get <id> [--out <文件|目录>] [--version <版本>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<id>` | 条目的 id | — |
| `--out` | 写到这个文件。站点写到这个目录。短写 `-o` | 打印到标准输出 |
| `--version` | 站点：下载这个版本 | 部署中的版本 |

```terminal title="下载站点的一个版本"
$ aidc space get cm2kb7d2e0004qz7d9v3c6y1p --out ./source --version release-2
已写入 ./source（12 个文件，版本 release-2）
```

站点还没有部署、又没写 `--version` 时，命令以退出码 2 结束，提示用 `--version` 下载已上传的版本。

### aidc space recent

列出你最近看过的条目。member 也能用。

```bash
aidc space recent
```

### aidc space page

建一个页。内容用 `--file` 或 `--text` 给出。member 也能用。你是这个页的 Owner。

```bash
aidc space page "<标题>" [--file <页.md> | --text "…"] [--project <id>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<标题>` | 页的标题，必填 | — |
| `--file` | 页的内容，Markdown 文件 | — |
| `--text` | 页的内容，直接写在命令里 | — |
| `--project` | 建在这个 Project 里 | Your files |

```terminal title="建页"
$ aidc space page "周会纪要" --file 周会.md
已建页：
cm2k9f3a70001qz7d5w1b8x4n  页    周会纪要
                          张三 · owner · private · 2026-10-08 14:03
打开：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4n
```

### aidc space edit

改页的内容。命令先读出页的当前版本，再带着这个版本保存。读取后若有人修改了页面，服务端会拒绝保存。member 也能用，但要是这个页的 Owner 或 Editor。

```bash
aidc space edit <id> --file <页.md>
aidc space edit <id> --text "…"
```

```terminal title="改页"
$ aidc space edit cm2k9f3a70001qz7d5w1b8x4n --file 周会.md
已保存（第 3 版）：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4n
```

### aidc space deploy

把一个 HTML 文件、一个目录或一个 zip 部署成站点，返回托管地址。每次上传是站点的一个版本。member 也能用。

```bash
aidc space deploy <目录|zip|html> [--name <名字>] [--site <站点 id>] [--version <版本>] [--upload-only] [--project <id>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录\|zip\|html>` | 要部署的内容。目录与 zip 的根上要有 `index.html` | — |
| `--name` | 站点的名字。也可以写 `--title` | 文件名或目录名 |
| `--site` | 给这个站点上传新版本。也可以写 `--update` | 新建站点 |
| `--version` | 版本名：字母、数字、`.`、`_`、`-`，最长 64 个字符 | 平台编号 |
| `--upload-only` | 只上传，不部署 | 上传即部署 |
| `--project` | 新站点建在这个 Project 里 | Your files |
| `--dry-run` | 只校验，不上传。写了 `--site` 时服务端也校验 | — |

```terminal title="部署站点"
$ aidc space deploy weekly-report.html --name "周报"
已部署：https://www.ai-dc.ai/p/cell-demo/7a2c9e4b1f80
查看：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4o
版本 1 · 1 个文件 · 18432 字节

开放程度 private：aidc space share cm2k9f3a70001qz7d5w1b8x4o --tier …（private / group / public / internet）
```

```terminal title="预演一个目录"
$ aidc space deploy ./dist --name "报告" --dry-run
本地校验通过：将建站点「报告」，版本 1，12 个文件，482133 字节。没有创建或上传。
新站点建在 Your files，缺省 Private。
```

- 站点包最多 1,000 个文件，解压后最多 20 MB。资源用相对路径。不能含隐藏路径和符号链接。
- 命令把目录打成 zip，在本机校验。zip 不超过 4 MB 时经 API 上传，更大的自动分片直传。
- 新站点是 Private。给已有站点上传新版本，受众不变。
- 建新站点时上传失败，命令把空站点放进回收站。
- 包不合规时，命令以退出码 2 结束，并列出每个问题。

### aidc space versions

列出站点的全部版本。要 Editor。

```bash
aidc space versions <站点 id>
```

```terminal title="站点的版本"
$ aidc space versions cm2kb7d2e0004qz7d9v3c6y1p
release-2 · ready · 12 个文件 · 482133 字节 · Deployed
release-1 · ready · 11 个文件 · 470021 字节
```

### aidc space version

看一个版本的文件清单。要 Editor。

```bash
aidc space version <站点 id> <版本>
```

```terminal title="一个版本的文件"
$ aidc space version cm2kb7d2e0004qz7d9v3c6y1p release-2
版本 release-2 · 12 个文件 · 482133 字节
index.html · 2311 · text/html
assets/index-4f1c2a.js · 401230 · text/javascript
…
```

### aidc space deploy-version

部署站点的一个版本。部署旧版本就是回滚。要 Editor。

```bash
aidc space deploy-version <站点 id> <版本> [--dry-run]
```

```terminal title="回滚到上一个版本"
$ aidc space deploy-version cm2kb7d2e0004qz7d9v3c6y1p release-1 --dry-run
计划：deploy · release-2 → release-1（不改数据）
$ aidc space deploy-version cm2kb7d2e0004qz7d9v3c6y1p release-1
部署版本 release-1：https://www.ai-dc.ai/p/cell-demo/3b8d1e5a9c27
```

### aidc space undeploy

撤下站点。网页立即停止服务。版本都保留，之后可以再部署。要 Editor。

```bash
aidc space undeploy <站点 id> [--dry-run]
```

```terminal title="撤下站点"
$ aidc space undeploy cm2kb7d2e0004qz7d9v3c6y1p --dry-run
计划：undeploy · release-1 → —（不改数据）
```

### aidc space rm-version

删一个版本。正在部署的版本不能删。要 Owner。

```bash
aidc space rm-version <站点 id> <版本> [--dry-run]
```

```terminal title="删一个旧版本"
$ aidc space rm-version cm2kb7d2e0004qz7d9v3c6y1p release-2
已删版本 release-2
```

### aidc space upload

上传文件。文件直接传到组织自己的 S3。`.html` 文件自动部署成站点。单个文件最大 5 GB。智能体上传的文件最大 64 MB。member 也能用。

```bash
aidc space upload <文件…> [--project <id>]
```

```terminal title="上传文件"
$ aidc space upload contract.pdf photo.png
contract.pdf → 文件 cm2k9f3a70001qz7d5w1b8x4p
photo.png → 文件 cm2k9f3a70001qz7d5w1b8x4q
cm2k9f3a70001qz7d5w1b8x4p  文件   contract.pdf
                          张三 · owner · private · 2026-10-08 14:15
打开：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4p
cm2k9f3a70001qz7d5w1b8x4q  文件   photo.png
                          张三 · owner · private · 2026-10-08 14:15
打开：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4q
```

命令先在标准错误输出打印每个文件的进度（`→` 之前是文件名），再打印每个条目的详情。

### aidc space project

建一个 Project。Project 是共享的容器。分享 Project 时，里面的东西一起给到，只加不减。member 也能用。

```bash
aidc space project "<名字>" [--description <说明>]
```

```terminal title="新建"
$ aidc space project "2026 采购" --description "采购部的材料"
已建 Project：
cm2k9f3a70001qz7d5w1b8x4r  Project 2026 采购
                          张三 · owner · private · 2026-10-08 14:20
打开：https://www.ai-dc.ai/semantic/cell-demo/space/items/cm2k9f3a70001qz7d5w1b8x4r
分享 Project = 里面的东西一起给到：aidc space share cm2k9f3a70001qz7d5w1b8x4r --user …
```

### aidc space mv

把条目移到一个 Project，或者用 `--root` 移回 Your files。权限以服务端为准。

```bash
aidc space mv <id> (--project <id> | --root)
```

```terminal title="移动条目"
$ aidc space mv cm2k9f3a70001qz7d5w1b8x4n --project cm2k9f3a70001qz7d5w1b8x4r
已移到 2026 采购
```

### aidc space rename

改条目的名字。要 Editor 或 Owner。

```bash
aidc space rename <id> "<新名字>"
```

```terminal title="改名"
$ aidc space rename cm2k9f3a70001qz7d5w1b8x4n "周会纪要（10 月）"
已改名：周会纪要（10 月）
```

### aidc space share

分享给人、智能体或组，或者只改开放程度。要 Owner。`--also-owner` 同时分享给智能体的 owner。智能体读的内容，不超过它的 owner。

```bash
aidc space share <id> [--user <账号 id、用户名或邮箱>…] [--agent <智能体 id>…] [--group <组 id 或 cell-…>…] [--role viewer|editor|owner] [--tier private|group|public|internet] [--also-owner]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--user` | 分享给人。可以重复，也可以用逗号分开 | — |
| `--agent` | 分享给智能体 | — |
| `--group` | 分享给组。`cell-…` 是本组织全员 | — |
| `--role` | `viewer`、`editor` 或 `owner` | `viewer` |
| `--tier` | 开放程度：`private`、`group`、`public` 或 `internet` | 不改 |
| `--also-owner` | 分享给智能体时，同时分享给它的 owner | — |

`--user`、`--agent`、`--group` 要写一个，或者写 `--tier`。

```terminal title="开放给互联网"
$ aidc space share cm2k9f3a70001qz7d5w1b8x4o --tier internet
已分享，开放程度 internet
```

```bash
aidc space share cm2k9f3a70001qz7d5w1b8x4o --user li.si@example.com --agent ops-agent --also-owner --role viewer
```

### aidc space access

看谁能打开这个条目。每一行是一个主体和它的角色。member 也能用。

```bash
aidc space access <id>
```

```terminal title="看访问权限"
$ aidc space access cm2k9f3a70001qz7d5w1b8x4n
开放程度 group，我的角色 owner
owner    张三
editor   李四
viewer   运营助手 [AI]
```

### aidc space people

列出可以分享给的人、智能体和组，并给出分享时要写的参数。`--q` 按名字搜索。member 也能用。

```bash
aidc space people [--q <词>]
```

```terminal title="分享的候选"
$ aidc space people
人   张三  --user cm2k9f3a70001qz7d5w1b8x4n
AI   运营助手  --agent ops-agent（owner 张三）
组   财务  --group cm2k9f3a70001qz7d5w1b8x4n
```

### aidc space fav

收藏一个条目。member 也能用。

```bash
aidc space fav <id>
```

```terminal title="收藏"
$ aidc space fav cm2k9f3a70001qz7d5w1b8x4n
已收藏：周会纪要
```

### aidc space unfav

取消收藏。member 也能用。

```bash
aidc space unfav <id>
```

```terminal title="取消收藏"
$ aidc space unfav cm2k9f3a70001qz7d5w1b8x4n
已取消收藏：周会纪要
```

### aidc space trash

把条目放进回收站。要 Owner。站点会停止服务。回收站里的条目可以恢复。

```bash
aidc space trash <id>
```

```terminal title="放进回收站"
$ aidc space trash cm2k9f3a70001qz7d5w1b8x4n
已放进回收站：周会纪要（aidc space restore cm2k9f3a70001qz7d5w1b8x4n 恢复）
```

### aidc space restore

从回收站恢复条目，回到原来的位置。要 Owner。

```bash
aidc space restore <id>
```

```terminal title="恢复"
$ aidc space restore cm2k9f3a70001qz7d5w1b8x4n
已恢复：周会纪要
```

### aidc space rm

永久删除回收站里的条目。字节、站点和分享一起删除。只能删回收站里的条目。要 Owner。

```bash
aidc space rm <id>
```

永久删除后不能撤回。

```terminal title="永久删除"
$ aidc space rm cm2k9f3a70001qz7d5w1b8x4n
已永久删除（1 项）
```

### aidc space empty-trash

清空回收站：永久删除回收站里的每一项，释放存储。要 Owner。加 `--dry-run` 只看有多少项、多少字节，不删除。

```bash
aidc space empty-trash [--dry-run]
```

```terminal title="看回收站"
$ aidc space empty-trash --dry-run
回收站里有 3 项（1.2 MB）：去掉 --dry-run 就永久删除。
```

```terminal title="清空回收站"
$ aidc space empty-trash
已永久删除 3 项
```

## 日志：aidc semantic observability

这一组看应用的使用情况、反馈和错误。要 developer。概念见 [应用日志](log.md)。

### aidc semantic observability summary

查看应用或组织最近几天的使用汇总。输出还包括未处理反馈和版本状态。要 developer。

```bash
aidc semantic observability summary [<应用>] [--days 7]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug。不写就看整个组织 | 整个组织 |
| `--days` | 看最近几天 | `7` |

```terminal title="看汇总"
$ aidc semantic observability summary inspector --days 7
inspector · 最近 7 天：打开 / 使用 18、操作 0、反馈 1、错误 0，访客 4 人
…
未处理反馈：
  cm2k9f3a70001qz7d5w1b8x4n  李四：拍照时总是提示光线不足
版本：
  0.1.1      测试中
  0.1.0      已上线
```

### aidc semantic observability events

列出应用的记录，最新的在前。可以按应用、类型、状态和时间筛选。要 developer。

```bash
aidc semantic observability events [--app <应用>] [--kind feedback] [--status open] [--type <类型>] [--object <对象>] [--since <时间>] [--limit <条数>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--app` | 只看一个应用 | 全部 |
| `--kind` | 只看一类记录，如 `feedback` | 全部 |
| `--status` | 只看一种状态，如 `open` | 全部 |
| `--type` | 只看一种 Object Type | 全部 |
| `--object` | 只看一个对象 | 全部 |
| `--since` | 只看这个时间以后的记录 | — |
| `--limit` | 最多列出几条 | — |

```terminal title="看反馈"
$ aidc semantic observability events --app inspector --kind feedback --status open
2026-10-08 13:20:00  feedback general                      李四  inspector@0.1.1  [open]
```

没有记录时，命令打印「没有记录。」。

### aidc semantic observability feedback

改一条反馈的状态。要 developer。

```bash
aidc semantic observability feedback <记录 id> --status planned|done|dismissed|open
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<记录 id>` | 运行 `aidc semantic observability events --json`，取 `events[].id` | — |
| `--status` | `planned`（已计划）、`done`（已完成）、`dismissed`（已忽略）或 `open`（未处理），必填 | — |

```terminal title="改状态"
$ aidc semantic observability feedback cm2k9f3a70001qz7d5w1b8x4n --status done
反馈 cm2k9f3a70001qz7d5w1b8x4n → done
```

## 用量与账单：aidc semantic usage

这一组看用量和账单。金额是模型厂商的美元标价，不是发票。`summary`、`records` 和 `check` 要 developer。`prices` 和 `estimate` 登录即可用。加 `--fx 7.1` 同时显示人民币，只影响显示。概念见 [用量与账单](billing.md)。

### aidc semantic usage summary

看今日、本月和累计的花费。按应用、开发者 Key、模型和天拆开，并给出月底预测和预算。要 developer。

```bash
aidc semantic usage summary [--app <slug>] [--month 2026-09] [--budget <美元>] [--fx <汇率>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--app` | 只看一个应用 | 整个组织 |
| `--month` | 看哪个月，UTC 自然月 | 本月 |
| `--budget` | 按这个预算做规划。只用来算，不拦截调用 | — |
| `--fx` | 汇率（1 美元 = 多少人民币），同时显示人民币 | — |

```terminal title="看花费"
$ aidc semantic usage summary --month 2026-10
cell-demo · 2026-10（UTC）· 美元标价 · 截至 2026-10-08 14:00 UTC
今日 $0.2100 · 本月 $1.84（预测月底 $3.28，日均 $0.0614） · 累计 $5.12（自 2026-08-01）
本月 468 次 · 612K tokens
按应用（本月）
  cell-demo/inspector                  $1.61   87.5%  312 次 · 540K tokens
  cell-demo/order-desk               $0.2300   12.5%  156 次 · 72K tokens
按模型（本月）
  gpt-6-luna                     $1.61  312 次 · 540K tokens
…
```

### aidc semantic usage records

看每一次调用的明细：时间、通道、应用或开发者 Key、模型、token 数和费用。默认按页读。`--all` 读全部。`--csv` 输出 CSV。要 developer。

```bash
aidc semantic usage records [--app <slug>] [--month <月>] [--from <时间>] [--to <时间>] [--model <模型>] [--lane app|developer] [--limit <条数>] [--cursor <游标>] [--all] [--max <行数>] [--csv]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--app` | 只看一个应用 | 整个组织 |
| `--month` | 看哪个月 | 本月 |
| `--from`、`--to` | UTC 日期，格式 `YYYY-MM-DD`，包含两端日期。不能与 `--month` 同用 | — |
| `--model` | 只看一个模型 | 全部 |
| `--lane` | `app` 是应用的调用，`developer` 是开发者 Key 的调用 | 全部 |
| `--limit` | 这一页的条数 | 服务端决定 |
| `--cursor` | 翻页用的游标，接在上一页末尾的提示后面 | — |
| `--all` | 读全部记录 | 按页读 |
| `--max` | 用 `--all` 时最多读多少行 | `100000` |
| `--csv` | 输出 CSV | 人读格式 |

```terminal title="看明细"
$ aidc semantic usage records --app inspector --limit 2
2026-10-08 13:58:12  app       cell-demo/inspector          gpt-6-luna                1234 tokens  $0.002100
2026-10-08 13:41:05  app       cell-demo/inspector          deepseek-flash             512 tokens  $0.000210
还有：加 --cursor MjAyNi0xMC0wOFQxMzo0MTowNS4wMDBafGNtMms5ZjNhNzAwMDFxejdkNXcxYjh4NG4（或 --all 读全）
$ aidc semantic usage records --app inspector --limit 2 --cursor MjAyNi0xMC0wOFQxMzo0MTowNS4wMDBafGNtMms5ZjNhNzAwMDFxejdkNXcxYjh4NG4
…
```

```bash
aidc semantic usage records --app inspector --month 2026-09 --all --csv > 9月明细.csv
```

CSV 的第一行是表头：`at,lane,app,key,model,promptTokens,completionTokens,totalTokens,audioSeconds,costUsd`。没有价格的行，费用那一列留空。

### aidc semantic usage check

核对账单。对不上时，退出码是 1。要 developer。

```bash
aidc semantic usage check [--month <月>] [--app <slug>]
```

本月记录超过 50,000 行时，命令跳过逐行核对和复算，只核对分组汇总。

命令核对的内容：

- 应用用量与开发者 Key 用量合计等于本月总数。
- 模型维度和按天维度各自合计等于本月总数。
- 另一条路逐行读取台账，重算次数、token 数和金额，结果相同。
- 逐行的费用相加等于本月金额。未计价的行不计入金额，但会单独列出。
- 累计不小于本月。
- 逐行按现行价目复算。结果高于或低于现行价的行，只作提示，不算对账失败。

```bash
aidc semantic usage check --month 2026-09
```

首行是 `对账 <组织> <月份>[ · <应用>]：通过 ✓` 或 `对账 <组织> <月份>[ · <应用>]：不一致 ✗`。

检查项是 `apps+keys=month`、`models=month`、`daily=month`、`cumulative=month`、`ledger`、`ledger.raw`、`total>=month`。跳过逐行核对时不输出 `ledger.raw`。

### aidc semantic usage prices

看每个模型的单价和来源。价目是公开的，登录即可用。

```bash
aidc semantic usage prices
```

每个模型一行，列是：模型名、计量方式、单价、来源。

| 计量方式 | 显示 |
| --- | --- |
| `tokens` | 按 token |
| `audio` | 按分钟 |
| `session` | 按场次 |
| `world` | 按次 |

| 来源 | 显示 |
| --- | --- |
| `vendor` | 厂商价 |
| `catalog` | 目录同步 |
| `override` | 运营方覆盖 |
| `none` | 未知 |

### aidc semantic usage estimate

估算一个月要花多少。按现行价目算出每次、每天和每月的费用。登录即可用。估算只是计算，不改变账单。

```bash
aidc semantic usage estimate -m <模型> --calls <次数> [--per day|month] [--days <天数>] [--input <N>] [--cached <N>] [--output <N>] [--seconds <N>] [--kind text|image|pano|multi-image|video] [--label <名字>] [--off-peak <0–1>] [--budget <美元>] [--fx <汇率>]
aidc semantic usage estimate --file <估算.json>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `-m` | 模型，必填 | — |
| `--calls` | 调用次数，必填 | — |
| `--per` | `--calls` 的单位：按天（`day`）还是按月（`month`） | `day` |
| `--days` | 一个月按几天算 | 服务端决定 |
| `--input` | 每次调用的输入 token 数 | — |
| `--cached` | 每次调用里命中缓存的输入 token 数 | — |
| `--output` | 每次调用的输出 token 数 | — |
| `--seconds` | 每次调用的音频秒数 | — |
| `--kind` | 生成世界的输入类型 | — |
| `--label` | 这一行的名字 | 模型名 |
| `--off-peak` | 非峰时调用的占比，0 到 1。DeepSeek 按调用时刻分峰时和非峰时 | `0`（全按峰时） |
| `--budget` | 对比月预算 | — |
| `--file` | 多行估算的定义文件，格式 `{ "items": [ … ] }` | — |

```bash
aidc semantic usage estimate -m deepseek-flash --calls 200 --input 1500 --cached 1000 --output 300 --budget 20
```

输出每一行：每次、每天、每月的费用。最后是合计，以及和预算比较的结果。没有价格的行标为「未计价」，不算进合计。

```bash
aidc semantic usage estimate --file 估算.json
```

旧写法的命令与新写法的对照，见 [旧写法与迁移](migration.md)。