# 参考 · 应用与界面

本页覆盖四组命令。`aidc app` 做、测、发布和查看应用。`aidc ui` 管界面 SDK。`aidc evolve` 管自进化。`aidc share` 分享应用。member 能用本机命令和 `aidc app call / card / about / apis`。应用卡片的花费一行只有 developer 看得到。其余命令要你所在组织（命名空间 `cell-demo`）的 developer 角色。

> [!NOTE]
> 本机命令是 `aidc app init / export / check / dev`、`aidc ui …` 和 `aidc evolve slots`。除 `aidc login`、`aidc logout`、`aidc update` 外，每条命令都要先登录。通用参数（`--json`、`--dry-run`、`--api`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)。输出格式见 [输出](cli.md#输出给人看也给程序读)，退出码见 [退出码](cli.md#退出码)。用法里 `<…>` 是要你填的值，`[…]` 是可选项，`|` 表示二选一。`<应用>` 是应用的 slug、`<命名空间>/<slug>`，或应用目录。

| 命令 | 做什么 |
| --- | --- |
| [`aidc app init`](#aidc-app-init) | 生成一个新应用的目录 |
| [`aidc app export`](#aidc-app-export) | 导出标准 Plugin 包 |
| [`aidc app check`](#aidc-app-check) | 本地校验清单、版本包和 Skills |
| [`aidc app dev`](#aidc-app-dev) | 在本机预览应用 |
| [`aidc app deploy`](#aidc-app-deploy) | 上传版本，放进 test 通道 |
| [`aidc app publish`](#aidc-app-publish) | 把测过的版本发布到 production 通道 |
| [`aidc app rollback`](#aidc-app-rollback) | 让 production 回到更早的版本 |
| [`aidc app status`](#aidc-app-status) | 看通道和各版本的状态 |
| [`aidc app history`](#aidc-app-history) | 看发布记录 |
| [`aidc app list`](#aidc-app-list) | 列出组织的应用 |
| [`aidc app registry`](#aidc-app-registry) | 看每个应用用了哪些 SDK 和资源 |
| [`aidc app card`](#aidc-app-card) | 看应用卡片 |
| [`aidc app usage`](#aidc-app-usage) | 看资源用量 |
| [`aidc app about`](#aidc-app-about) | 读应用说明，给智能体用 |
| [`aidc app apis`](#aidc-app-apis) | 列出应用的 APIs 和 Skills |
| [`aidc app call`](#aidc-app-call) | 调应用的一个 API |
| [`aidc ui components`](#aidc-ui-components) | 列出界面组件和示例标记 |
| [`aidc ui tokens`](#aidc-ui-tokens) | 看设计令牌 |
| [`aidc ui add`](#aidc-ui-add) | 给已有应用接上界面 SDK |
| [`aidc evolve`](#aidc-evolve) | 自进化命令的总说明 |
| [`aidc evolve slots`](#aidc-evolve-slots) | 列出页面上的槽位和可调参数 |
| [`aidc evolve list`](#aidc-evolve-list) | 列出应用里的改进 |
| [`aidc evolve show`](#aidc-evolve-show) | 看一条改进的对话和指令 |
| [`aidc evolve compile`](#aidc-evolve-compile) | 看一句话会变成什么指令 |
| [`aidc evolve save`](#aidc-evolve-save) | 直接提交一条改进 |
| [`aidc evolve adopt`](#aidc-evolve-adopt) | 采纳一条待采纳的改进 |
| [`aidc evolve reject`](#aidc-evolve-reject) | 不采纳改进，或拒绝提案 |
| [`aidc evolve revert`](#aidc-evolve-revert) | 撤销一条改进 |
| [`aidc evolve propose`](#aidc-evolve-propose) | 把个人改进提交给所有人，或新建提案 |
| [`aidc evolve overlay`](#aidc-evolve-overlay) | 看叠在应用上的改进 |
| [`aidc evolve bake`](#aidc-evolve-bake) | 把全员改进写进源码 |
| [`aidc evolve evidence`](#aidc-evolve-evidence) | 收集改进的证据 |
| [`aidc evolve suggest`](#aidc-evolve-suggest) | 让模型起草提案 |
| [`aidc evolve proposals`](#aidc-evolve-proposals) | 列出提案 |
| [`aidc evolve accept`](#aidc-evolve-accept) | 采纳一条提案 |
| [`aidc evolve apply`](#aidc-evolve-apply) | 应用一条提案 |
| [`aidc share`](#aidc-share) | 分享应用 |
| [`aidc share list`](#aidc-share-list) | 列出分享 |
| [`aidc share revoke`](#aidc-share-revoke) | 撤销分享 |

## aidc app init

生成一个新应用的目录，里面有一份清单、一条 Skill 和一个能跑的界面。`skills` 模板没有界面。member 可用，只在本机写文件。

```bash
aidc app init <slug> [--template <模板>] [--title <标题>] [--format plugin|aidc] [--device-type desktop|mobile] [--object-type <Object Type>] [--action-type <Action>] [-n <命名空间>] [--dir <目录>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的地址名。小写字母开头，可含数字和连字符，2–48 个字符 | — |
| `--template` | 起点模板，取值见下面的模板表 | `blank` |
| `--title` | 应用的显示名 | 同 `<slug>` |
| `--format` | 清单格式。`plugin` 生成 `plugin.json`，`aidc` 生成 `aidc.app.json` | `plugin` |
| `--device-type` | 界面按哪种设备设计：`desktop` 或 `mobile`。`mobile` 的应用出现在 Nexus 手机入口 | `desktop` |
| `--object-type` | 只对 `semantic` 模板有效：界面读哪个 Object Type | `production.order_line` |
| `--action-type` | 只对 `semantic` 模板有效：按钮执行哪个 Action | `production.flag_issue`；给了 `--object-type` 时为空 |
| `-n`、`--namespace` | 写进清单的命名空间 | 不写，部署时取登录的组织 |
| `--dir` | 生成到哪个目录 | `./<slug>` |

```terminal title="生成拍照检查应用"
$ aidc app init inspector --template camera --title "布面质检"
已生成 /home/demo/inspector（Skill 在 skills/inspector/SKILL.md，先把 description 改成这个应用真正解决的事）
下一步：aidc app dev /home/demo/inspector
$ find inspector -type f | sort
inspector/app.js
inspector/index.html
inspector/plugin.json
inspector/skills/inspector/SKILL.md
inspector/style.css
```

`--json` 输出 `dir` 和 `files`。`files` 按写入顺序列出生成的文件。`skills` 模板只有两个文件：

```terminal title="Skill 应用"
$ aidc app init site-check --template skills --json
{
  "dir": "/home/demo/site-check",
  "files": [
    "skills/site-check/SKILL.md",
    "plugin.json"
  ]
}
```

生成的文件：

| 文件 | 说明 |
| --- | --- |
| `plugin.json` | 应用清单，标准 Plugin 格式。`--format aidc` 时是 `aidc.app.json` |
| `skills/<slug>/SKILL.md` | 一条 Skill。每个模板都有，先把 `description` 改成这个应用真正解决的事 |
| `index.html`、`app.js`、`style.css` | 界面，已经接好界面 SDK。`skills` 模板没有 |

模板：

| 模板 | 界面 | 清单 `sdk` | 做什么 |
| --- | --- | --- | --- |
| `skills` | 无 | 空 | 只有一条 Skill，教智能体用现成的 AIDC 命令 |
| `blank` | 有 | `ui` | 一张欢迎卡片和一个按钮 |
| `camera` | 有 | `vision`、`model`、`ui` | 拍照并检查，声明摄像头权限和模型 `gpt-6-luna` |
| `voice` | 有 | `voice`、`model`、`ui` | 实时转写，声明麦克风权限和模型 `gpt-live-transcribe`、`deepseek-flash` |
| `data` | 有 | `semantic`、`model`、`ui` | 读演示用的 ERP 数据集报告 |
| `semantic` | 有 | `semantic`、`ui` | 读一个 Object Type，按钮执行一个 Action |
| `workflow` | 有 | `semantic`、`ui` | 带一个两步工作流：计算加模型分析，可以预演 |
| `modeling` | 有 | `modeling`、`ui` | 3D 世界查看器，带锚点和估价按钮 |

给了 `--object-type` 却没给 `--action-type`，应用只读，没有按钮。

`skills` 模板的下一步是 `aidc app check` 和 `aidc app deploy`。其余模板的下一步是 `aidc app dev`。

退出码是 2 的情况：

- `<slug>` 不合规。
- `--template`、`--format` 或 `--device-type` 的值不对。
- 目录里已经有应用清单。

## aidc app export

把应用导出成标准 Plugin 包，一个 zip 文件。member 可用，只在本机读写文件。

```bash
aidc app export [<目录>] [--out <文件.zip>] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |
| `--out` | zip 文件的地址。文件已存在就报错 | `<slug>-<version>.zip` |
| `-n`、`--namespace` | 命名空间，用来生成应用的 MCP 服务器地址 | 清单里的 `namespace` |

```terminal title="导出包"
$ aidc app export inspector --namespace cell-demo
已导出 OpenAI Compatible Plugin：/home/demo/inspector-0.1.0.zip
```

zip 里每个文件的路径都以 `<slug>/` 开头。里面有应用的全部文件和 `plugin.json`。给了命名空间时，还有 `mcp.json`，写着应用的 MCP 服务器地址。没有命名空间时，命令提示「未指定 namespace，不生成 MCP 连接」。`--json` 输出 `{ path, files, mcpUrl }`。

版本包没有通过校验时，命令报错，退出码 2。

## aidc app check

在本机校验应用的清单、版本包和 Skills。校验规则和服务端是同一份，上传前就能发现问题。member 可用。

```bash
aidc app check [<目录>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |

```terminal title="校验通过"
$ aidc app check inspector
✓ inspector：5 个文件，4.0 KB，digest da8fde78a8ad88f5
```

`digest` 是版本包内容的指纹，只显示前 16 位。同样的内容永远是同一个 digest。

校验的内容：

- 文件数不超过 200，总大小不超过 3 MB。
- 路径是包内相对路径，文件类型是网页常用类型。
- 清单写了入口页，入口页就在包里。
- 每条 Skill 的 `name` 和目录同名。
- 每条 Skill 的 `description` 不超过 1024 个字符。
- 每条 Skill 的正文不为空。
- 代码用到的 SDK，清单 `sdk` 里都登记了。
- 包里没有 SDK 副本。

出问题时，所有问题一次列全，退出码 2：

```terminal title="漏登记 SDK"
$ aidc app check inspector
错误：版本包没有通过校验。
  · 代码用到了 vision SDK，但 aidc.app.json 的 sdk 没有登记——加进 "sdk" 再部署
```

工作流定时间隔不到 5 分钟时，命令拒收。发现以下成本问题时，命令在 stderr 打印以 `⚠️` 开头的告警。告警不拦截。`--json` 时告警在 `warnings` 字段。

- 工作流定时间隔为 5 分钟至 1 小时时，告警以 `⚠️ 高频定时` 开头。
- 工作流定时间隔超过 1 小时且不到 1 天时，告警不写「高频」。
- `limits` 中的 `computeMinutesPerMonth`、`notificationsPerDay`、`dailyTokens` 或 `realtimeSessionsPerDay` 高于缺省值。
- 代码里 `setInterval` 和拉数据写在同一个文件。

告警的含义见[发布 SDK](publish.md#资源上限与成本告警)。

`--json` 输出 `{ ok, slug, namespace, digest, files, bytes, warnings }`。

## aidc app dev

在本机起一个预览服务器，用浏览器看应用。member 可用。

```bash
aidc app dev [<目录>] [--port <端口>] [-n <命名空间>] [--sdk-dir <目录>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |
| `--port` | 预览服务器的端口 | `5173` |
| `-n`、`--namespace` | 命名空间，语义层和日志按它找组织 | 优先取清单的 `namespace`；清单没写时取 `-n`，再没有取登录的组织 |
| `--sdk-dir` | 用本地构建的 SDK 目录代替线上的 SDK。只在改 SDK 本身时用 | — |

```terminal title="本机预览"
$ aidc app dev inspector
本地预览：http://localhost:5173（Ctrl-C 结束）
→ GET /developer/sdk/v1/ui.css
→ GET /developer/sdk/v1/aidc.js
→ POST /api/v1/models/chat/completions
```

预览服务器的行为：

- 把应用目录当作站点根，入口页带上和线上一样的运行时信息。
- 把 `/api/`、`/v1/` 和 `/developer/sdk/` 转发到 API 根，缺省 `https://www.ai-dc.ai`。
- 开发者 Key 只在本机进程里补到 API 请求上，不下发到浏览器。
- 本地预览产生的模型用量，记在这把 Key 所属的组织名下。
- 只监听 `127.0.0.1`，只有同一台电脑能打开。
- 每个转发的请求在终端打印一行 `→ 方法 路径`。

命令一直运行，按 Ctrl-C 结束。清单 `entry` 为 `null` 的应用没有界面。打开它的首页，会得到一段说明：用 `aidc app check` 校验，部署后在应用页看 Skills 和 APIs。

> [!IMPORTANT]
> 不要把 SDK 副本放进应用目录。路径含 `developer/sdk/` 的文件，部署时整个版本被拒收。给别人看预览，用 `aidc app deploy` 返回的 Developer 预览地址。

## aidc app deploy

上传一个版本，放进 test 通道，得到 Developer 预览地址。要 developer。

```bash
aidc app deploy [<目录>] [--notes <说明>] [-n <命名空间>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |
| `--notes` | 这个版本的说明，写进发布记录，最多 500 个字符 | — |
| `-n`、`--namespace` | 部署到哪个组织 | 清单里的 `namespace`，没有就取登录的组织 |
| `--dry-run` | 只校验和计算，不创建版本，不进 test 通道 | — |

```terminal title="先预演，再部署"
$ aidc app deploy inspector --dry-run
（dry-run）将新建版本 digest da8fde78a8ad88f5，5 个文件；test 地址 https://www.ai-dc.ai/developer/cell-demo/apps/inspector
$ aidc app deploy inspector --notes "首版"
新版本 v0.1.0（构建 #1）已进入 test 通道
  Developer 预览：https://www.ai-dc.ai/developer/cell-demo/apps/inspector
测好后发布：aidc app publish inspector
```

版本号取清单的 `version`。每个版本还有一个构建序号，如 `#1`，是第几次上传。

- 同样的内容重复部署，返回已有的版本，不产生新版本，重试永远安全。
- 这时命令打印「内容未变，复用版本」。
- 每个版本号只能对应一份内容。内容改变后要升 `version`，否则服务端拒绝部署，退出码 6。
- 版本包没有通过校验时，退出码 2。
- 不是 developer 时，退出码 4。
- `--json` 输出 `{ namespace, slug, semver, version, created, digest, test, production, warnings }`。

```terminal title="没升版本号"
$ aidc app deploy inspector
错误：版本号 0.1.0 已经用于另一份内容（构建 #1）。改了内容就要升版本号：改 aidc.app.json 的 version 再部署。
```

## aidc app publish

把测过的版本发布到 production 通道，也就是 Nexus。要 developer。

```bash
aidc app publish [<应用>] [--version <版本>] [--notes <说明>] [-n <命名空间>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录。在应用目录里运行时可以省略 | 当前目录 |
| `--version` | 发布哪个版本。写版本号如 `1.2.0`，或构建序号如 `3` | test 通道当前的版本 |
| `--notes` | 说明，写进发布记录 | — |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |
| `--dry-run` | 只打印计划，不切换 | — |

```terminal title="发布版本"
$ aidc app publish inspector --dry-run
（dry-run）将发布：production 从 v— 切到 v0.1.0
  Nexus：https://www.ai-dc.ai/nexus/cell-demo/apps/inspector
$ aidc app publish inspector --notes "首版"
发布：production 从 v— 切到 v0.1.0
  Nexus：https://www.ai-dc.ai/nexus/cell-demo/apps/inspector
```

- 发布的就是测过的那个版本，不重新打包。
- production 只接受进过 test 的版本，否则命令报错，退出码 6。
- production 已经是这个版本时，命令打印「production 已经是 v0.1.0，无变化」，退出码 0。
- 应用不存在时，退出码 5，先运行 `aidc app deploy`。

## aidc app rollback

让 production 回到更早的已测版本。要 developer。

```bash
aidc app rollback <应用> --version <版本> [--notes <说明>] [-n <命名空间>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `--version` | 回到哪个版本，版本号或构建序号。必填 | — |
| `--notes` | 说明，写进发布记录 | — |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |
| `--dry-run` | 只打印计划，不切换 | — |

```terminal title="回到上一个版本"
$ aidc app rollback inspector --version 0.1.0 --notes "回退：提示太啰嗦"
回滚：production 从 v0.1.1 切到 v0.1.0
  Nexus：https://www.ai-dc.ai/nexus/cell-demo/apps/inspector
```

不给 `--version`，命令报错，退出码 2。用 `aidc app status` 查哪些版本测过。

## aidc app status

看一个应用的通道、各版本的版本号、构建序号和更新状态。要 developer。

```bash
aidc app status [<应用>] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录。在应用目录里运行时可以省略 | 当前目录 |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="看应用的状态"
$ aidc app status inspector
布面质检（cell-demo/inspector）
  test        v0.1.1  https://www.ai-dc.ai/developer/cell-demo/apps/inspector
  production  v0.1.0  https://www.ai-dc.ai/nexus/cell-demo/apps/inspector
  版本：
    v0.1.1      #2   测试中    2026-10-08T14:03  提示更明确
    v0.1.0      #1   已上线    2026-10-08T10:12  首版
```

版本按构建序号从新到旧排列。更新状态有六种：

| 状态 | 含义 |
| --- | --- |
| 已上线 | production 当前的版本 |
| 测试中 | test 当前的版本，还没上线 |
| 已测未发 | 进过 test，比线上新，但被更新的测试版替换，没发布过 |
| 已被替换 | 比线上版本旧 |
| 已回滚 | 上过线，后来被回滚到更早的版本 |
| 未测试 | 上传了，还没进过 test |

## aidc app history

看一个应用的发布记录：谁、什么时候、哪个通道、从哪个版本到哪个版本。要 developer。

```bash
aidc app history [<应用>] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="看发布记录"
$ aidc app history inspector
2026-10-08T15:30  production 回滚   v0.1.1 → v0.1.0  account:cm2k9f3a70001qz7d5w1b8x4n  回退：提示太啰嗦
2026-10-08T14:40  production 发布   v0.1.0 → v0.1.1  account:cm2k9f3a70001qz7d5w1b8x4n  提示更明确
2026-10-08T14:03  test       进测试  v0.1.0 → v0.1.1  account:cm2k9f3a70001qz7d5w1b8x4n  提示更明确
2026-10-08T10:20  production 发布   v0.1.0  account:cm2k9f3a70001qz7d5w1b8x4n  首版
2026-10-08T10:12  test       进测试  v0.1.0  account:cm2k9f3a70001qz7d5w1b8x4n  首版
```

记录从新到旧，最多 30 条。每条的动作是「进测试」「发布」或「回滚」，最后一列是 `--notes` 的内容。还没有记录时，命令打印「还没有发布记录。」

## aidc app list

列出你所在组织的所有应用，以及每个应用 test 和 production 的版本。要 developer。

```bash
aidc app list
```

这条命令没有参数。

```terminal title="列出应用"
$ aidc app list
cell-demo/inspector  布面质检  test v0.1.1  production v0.1.0
cell-demo/order-desk  订单台  test v1.0.0  production v1.0.0
```

组织里还没有应用时，命令打印「还没有应用（aidc app init <slug>）。」

## aidc app registry

看应用登记表：每个应用登记了哪些 SDK，实际用到哪些，读写哪些资源，近 7 天用得怎么样。要 developer。

```bash
aidc app registry [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `-n`、`--namespace` | 看哪个组织的登记表 | 登录的组织 |

```terminal title="看应用登记表"
$ aidc app registry
cell-demo · 2 个应用
● inspector（布面质检）  正式 0.1.0 / 测试 0.1.1  本公司成员
    SDK：vision、model、ui（实际用到：vision、ui）
    资源：语义 —；Action —；数据流 —；模型 gpt-6-luna
    近 7 天：打开 18、操作 0、反馈 1（未处理 1）、错误 0
● order-desk（订单台）  正式 1.0.0 / 测试 1.0.0  本公司成员
    SDK：semantic、ui（实际用到：semantic、ui）
    资源：语义 order；Action flag_order；数据流 —；模型 —
    近 7 天：打开 42、操作 6、反馈 0（未处理 0）、错误 0
按 SDK：
  视觉（vision）：inspector
  模型（model）：inspector
  语义（semantic）：order-desk
  界面（ui）：inspector、order-desk
```

「实际用到」是部署时对包做静态分析的结果。用了没登记的 SDK，部署会被拒收，所以这里只会出现「登记了没用到」。视觉、语音、视频走模型通道，用了它们，登记的 `model` 不算多余。

## aidc app card

看应用卡片：负责部门、版本、SDK、连了哪些数据、对外能力与依赖、谁能用、近 7 天使用。member 也能用。花费一行只有 developer 看得到。

```bash
aidc app card [<应用>] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="看应用卡片"
$ aidc app card inspector
# 布面质检（cell-demo/inspector）
拍一张布面照片，判断有没有污渍、破洞。

| 项 | 内容 |
| --- | --- |
| 负责 | 质检部 · 视觉组 |
| 版本 | 正式 0.1.0 · 测试 0.1.1 · 最新 0.1.1（发布记录 5 条） |
| SDK | 视觉、模型、界面（部署分析实际用到：视觉、界面） |
| 连数据库 | 否（不读写语义层） |
| 模型 | gpt-6-luna |
| 谁能用 | 本公司成员；分享：全公司 0 · 指定账号 1 · 公开链接 1 |
| 近 7 天 | 打开 18 · 操作 0 · 反馈 1（未处理 1）· 错误 0 |
| 花费（USD，标价） | 本月 1.842310（468 次、612000 tokens） · 今天 0.210000 · 累计 1.842310 · 月底预测 7.103000 |
| 地址 | /nexus/cell-demo/apps/inspector |
```

输出是一段 Markdown，可以贴进文档或交给智能体。完整的卡片还有「读」「写（Action）」「数据流」「对外能力」「依赖能力」「工作流」几行，这里省略。花费一行只有 developer 看得到，金额是模型厂商的美元标价。`--json` 输出 `{ card }`。卡片字段的含义见[应用卡片](app-card.md)。

## aidc app usage

看一个应用的资源用量：本月计算分钟、全部上限、定时、今天的通知。要 developer。

```bash
aidc app usage [<应用>] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="看资源用量"
$ aidc app usage cell-demo/inspector
cell-demo/inspector v0.1.0 · 2026-10
  计算分钟  312 / 2000（16%）
    实时连接          0 分钟  0 次
    工作流运行         0 分钟  0 次
    模型调用        312 分钟  468 次
    摄像头画面         0 分钟  0 次
  上限      dailyTokens=1000000  requestsPerMinute=30  realtimeSessionsPerDay=100  computeMinutesPerMonth=2000  notificationsPerDay=20
  定时      —
  通知      今天 发出 0 · 拦下 0 · 未配置 0 · 失败 0（上限 20/天）· 邮件通道 已配置
```

计算分钟按类型分行：实时连接、工作流运行、模型调用、摄像头画面。用到 80% 时，行尾提示「快用完了」。用完时提示「已用完」：这个应用的票据请求返回 429，下月 1 日恢复。上限的含义见[发布 SDK](publish.md#资源上限与成本告警)。

## aidc app about

读一个应用的说明。member 也能用。这份说明写给智能体，和应用地址下的 `about.md` 是同一份。

```bash
aidc app about <应用> [--channel test] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `--channel` | 写 `test`，读 test 通道的版本。只对 developer 生效 | `production` |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="读应用说明"
$ aidc app about cell-demo/inspector
# 布面质检（AIDC 应用）

> 拍一张布面照片，判断有没有污渍、破洞。

这是写给你（智能体）的说明。人把这份文档交给你，意思是请你用这个应用帮他做事。读一遍，然后照做：先弄清人要什么，按下面的 Skill 调 API，结论只用 API 返回的内容。

## 人通常会这样说

- 帮我检查这张布面照片有没有污渍
…
```

说明里有：做什么、人通常怎么说、怎么登录。还有 APIs 的调用写法、MCP 地址、用到的 AIDC 命令，以及每条 Skill 的全文和规矩。`--json` 输出 `{ app, prompt, markdown }`，`prompt` 是人交给智能体的那一句话。

## aidc app apis

列出一个应用的 APIs、Skills，以及它用到的 AIDC 命令。member 也能用。

```bash
aidc app apis <应用> [--channel test] [-n <命名空间>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | 当前目录 |
| `--channel` | 写 `test`，读 test 通道的版本。只对 developer 生效 | `production` |
| `-n`、`--namespace` | 应用所在组织的命名空间 | 应用目录里清单的 `namespace`，没有就取登录的组织。写 `<命名空间>/<slug>` 时用其中的命名空间 |

```terminal title="列出 APIs"
$ aidc app apis cell-demo/order-desk
订单台（cell-demo/order-desk v1.0.0 · production）
APIs 2
  ● open_orders                  query     待处理订单
      参数：status:string limit:integer
      aidc app call cell-demo/order-desk open_orders --json
  ● flag_order                   action    标记异常订单  [写入，先 --preview]
      参数：order*:string reason*:string preview:boolean
      aidc app call cell-demo/order-desk flag_order --param order=<order> --param reason=<reason> --json
Skills 1
  triage-orders：排查异常订单：先列待处理订单，找出缺料、延期的，再标记并说明原因。用户问「哪些订单有问题」时使用。
说明：https://www.ai-dc.ai/nexus/cell-demo/apps/order-desk/about.md
```

每个 API 占一行。实心圆点 `●` 是清单显式导出的。空心圆点 `○` 是平台从登记的类型和 Action 自动提取的。`kind` 有 `query`、`get`、`aggregate`、`action`，工作流应用还有 `run`、`get_run`、`list_runs`。参数名后的 `*` 表示必填。会写入的 API 带「写入，先 --preview」。

应用没有自己的 API 时，命令提示「这个应用没有自己的 API」，并列出 Skills 和用到的 AIDC 命令。

## aidc app call

调应用的一个 API。member 和 developer 都能用。

```bash
aidc app call <应用> <API> [--param <名=值>]… [--params <JSON>] [--input <JSON>] [--preview] [--channel test|production] [--idempotency-key <键>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<应用>` | 应用的 slug、`<命名空间>/<slug>` 或应用目录 | — |
| `<API>` | API 的名字，用 `aidc app apis` 查 | — |
| `--param` | 一个参数，写成 `名=值`，可以重复。值是数字、`true`、`false`、`null` 时按 JSON 解析，其余当文本 | — |
| `--params` | 一个 JSON 对象，装多个参数 | — |
| `--input` | 一个 JSON 对象，作为 API 的输入。同名的键，`--param` 和 `--params` 优先 | — |
| `--preview` | 预演：读、算、AI 分析照跑，写入只返回计划 | — |
| `--channel` | 调哪个通道的版本。`test` 只对 developer 生效 | `production` |
| `--idempotency-key` | 幂等键，8–128 位字母、数字和 `_ . : -`。`run` 重复提交同一个键，返回同一次运行 | — |
| `--dry-run` | 只校验输入，不执行。`get_run`、`list_runs` 照样读取运行记录 | — |

```terminal title="查待处理订单"
$ aidc app call cell-demo/order-desk open_orders --param status=待处理 --param limit=1
{
  "api": "open_orders",
  "kind": "query",
  "channel": "production",
  "version": "1.0.0",
  "output": {
    "kind": "query",
    "rows": [
      {
        "_pk": "SO-1001",
        "customer": "Demo Customer A",
        "status": "待处理"
      }
    ],
    "count": 1,
    "total": 7
  }
}
```

输出总是 JSON。`output` 里有什么，和 API 的 `kind` 有关：

| `kind` | `output` 里有什么 |
| --- | --- |
| `query` | `rows`、`count`、`total` |
| `get` | `row` |
| `aggregate` | `groups` |
| `action` | `object`、`rev`、`event`。预演时多一个 `plan` |

会写入的 API 先预演，把计划给人看，确认后再正式调用：

```bash
aidc app call cell-demo/order-desk flag_order --param order=SO-1002 --param reason=缺料 --preview
aidc app call cell-demo/order-desk flag_order --param order=SO-1002 --param reason=缺料
```

- 身份是「应用 × 调用人的角色」。
- 调用人拿不到应用本来拿不到的东西，留痕记的是调用人。
- member 只能调 production 通道上、对自己开放的应用。
- 看不到的应用和不存在的应用一样，返回 404，退出码 5。
- developer 能调本组织的任何应用。
- 只允许 developer 的 Action，经应用调用会返回 403，退出码 4。
- API 不存在时，退出码 5，错误信息列出这个应用有哪些 API。
- 输入不合格时，退出码 2。

## aidc ui components

列出界面 SDK 的组件、它们引入的 CSS 类和示例标记。member 可用，在本机完成，不联网。

```bash
aidc ui components [<组件>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<组件>` | 组件的 id，如 `button`。给了就打印这个组件的说明和示例标记 | 列出全部组件 |

```terminal title="列出组件"
$ aidc ui components
页面
  appbar     顶栏　　　　 aidc-appbar aidc-appbar__title aidc-appbar__actions
  layout     版面　　　　 aidc-page aidc-page--narrow aidc-stack aidc-row aidc-muted

操作
  button     按钮　　　　 aidc-btn aidc-btn--secondary aidc-btn--outline aidc-btn--ghost aidc-btn--destructive aidc-btn--link aidc-btn--sm aidc-btn--lg aidc-btn--icon aidc-btn--block
  tabs       标签页　　　 aidc-tabs aidc-tabs__list aidc-tabs__trigger aidc-tabs__panel
  dialog     对话框　　　 aidc-dialog aidc-dialog__header aidc-dialog__title aidc-dialog__description aidc-dialog__footer
…
```

组件按五组排列：页面、操作、表单、展示、反馈。

```terminal title="看一个组件的标记"
$ aidc ui components button
按钮（button）· 操作
主按钮是实心黑（signal 主题下是信号橙）；次要、描边、幽灵、危险、链接五种变体，三种尺寸与图标按钮。

<div class="aidc-row">
  <button type="button" class="aidc-btn">发布</button>
  <button type="button" class="aidc-btn aidc-btn--secondary">保存草稿</button>
  <button type="button" class="aidc-btn aidc-btn--outline">预览</button>
  <button type="button" class="aidc-btn aidc-btn--ghost">取消</button>
  <button type="button" class="aidc-btn aidc-btn--destructive">删除</button>
  <a class="aidc-btn aidc-btn--link" href="#">查看说明</a>
</div>
…
```

组件 id 不存在时，命令列出所有可选的 id，退出码 2。`--json` 输出 `{ stylesheet, components }`。带组件 id 时，输出这个组件的 `id`、`title`、`group`、`summary`、`classes`、`html`，有脚本的组件还有 `js`。数据和 `/developer/sdk/v1/ui.json` 同源。

## aidc ui tokens

看界面 SDK 的设计令牌，也就是一组 CSS 变量。member 可用，在本机完成，不联网。

```bash
aidc ui tokens [--mode light|dark] [--theme aidc|signal] [--css]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--mode` | 明暗：`light` 或 `dark` | `light` |
| `--theme` | 主题：`aidc` 的主按钮是实心黑，`signal` 的主按钮和焦点环是信号橙 | `aidc` |
| `--css` | 输出完整的 CSS 变量块，含 `:root`、`.dark` 和主题覆盖。这时忽略 `--mode` 和 `--theme` | — |

```terminal title="深色令牌"
$ aidc ui tokens --theme signal --mode dark
--radius: 0.375rem;
--background: #0a0a0a;
--foreground: #ededed;
--card: #111111;
--card-foreground: #ededed;
--popover: #111111;
--popover-foreground: #ededed;
--primary: #ff4d00;
…
--chart-5: #e34400;
```

```terminal title="输出 CSS"
$ aidc ui tokens --css
:root {
  color-scheme: light;
  --radius: 0.375rem;
…
```

`--mode` 或 `--theme` 的值不对时，退出码 2。`--json` 输出 `{ theme, mode, tokens }`。

## aidc ui add

给已有应用接上界面 SDK：入口页加上 `ui.css`，清单的 `sdk` 加上 `ui`。重复运行不会重复改。member 可用，只改本机文件。

```bash
aidc ui add [<目录>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |
| `--dry-run` | 只打印会改哪些文件，不写 | — |

```terminal title="接上界面 SDK"
$ aidc ui add old-portal --dry-run
将要修改：index.html、aidc.app.json
部署前把 version 从 1.0.0 升一级（内容变了版本号要变），再 aidc app deploy。
$ aidc ui add old-portal
已修改：index.html、aidc.app.json
部署前把 version 从 1.0.0 升一级（内容变了版本号要变），再 aidc app deploy。
$ aidc ui add old-portal
已经接好，没有要改的。
```

- `ui.css` 的 `<link>` 插在入口页第一个样式表之前，应用自己的样式在后，优先。
- 入口页没有样式表时，`<link>` 插在 `</head>` 之前。
- 应用没有界面（清单 `entry` 为 `null`）时，命令报错，退出码 2。
- 入口页里找不到 `</head>` 时，命令报错并给出要手动加的 `<link>`，退出码 2。
- 改了清单或入口页，部署前把 `version` 升一级。

## aidc evolve

管理应用的自进化。你可以看用户在应用里提的改进，采纳或撤销它们，把改进写进源码，或者按证据提改进提案。除 `slots` 外，这组命令要 developer，管本组织的应用。

子命令分两类：

| 你要做什么 | 子命令 |
| --- | --- |
| 看本机页面上的槽位 | `slots` |
| 管应用里的改进。命令带 `<slug>` | `list`、`show`、`compile`、`save`、`adopt`、`reject`、`revert`、`propose`、`overlay` |
| 把全员改进写进源码 | `bake` |
| 按证据提提案。命令不带 `<slug>` | `evidence`、`suggest`、`proposals`、`propose`、`accept`、`reject`、`apply` |

`propose` 和 `reject` 两类都有。带 `<slug> <id>` 两个参数的，管应用里的改进。其余的管提案。

管理应用里改进的命令（`list`、`show`、`compile`、`save`、`adopt`、`reject`、`revert`、`propose`、`overlay`、`bake`）要求应用先登记自进化。`slots`、`evidence`、`suggest` 不要求。登记的方法：清单 `sdk` 里有 `evolve`，页面上用 `data-evolve` 标出能改的区域。没登记时，命令报错 `evolve_not_enabled`，退出码 6。

用 `-n` 指定组织，用 `--channel test` 或 `--channel production` 指定通道。概念和接入步骤见[自进化 SDK](evolve.md)。

### aidc evolve slots

在本机列出页面上的槽位，和清单里声明的槽位、可调参数，看谁有谁没有。member 可用，不联网。

```bash
aidc evolve slots [<目录>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<目录>` | 应用目录 | `.` |

```terminal title="列出槽位"
$ aidc evolve slots helpdesk
helpdesk · 自进化已登记 · 4 个槽位 · 2 个可调参数（另有内置槽位 page = 整个页面）
  ● chat               对话框  别名 聊天框、对话窗口
  ● composer           （没起名字：清单 evolve.slots 加 title，用户才能用名字说它）
  ● send               发送按钮
  ○ title              标题  ← 页面里没找到 data-evolve
  ◆ --chat-width       对话框宽度 · length · 360px–1100px · 挂在 chat
  ◆ --accent           强调色 · color
```

`●` 是页面里找到的槽位，`○` 是清单声明了但页面里没有的槽位，`◆` 是可调参数。没起名字的槽位，用户只能在页面上点选。

### aidc evolve list

列出一个应用里的改进，看谁提了什么、处于什么状态。

```bash
aidc evolve list <slug> [--status <状态>] [--scope app|personal] [--kind overlay|request] [--channel test|production]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `--status` | 只看一个状态：`live`、`proposed`、`rejected` 或 `reverted` | 全部 |
| `--scope` | `app` 是全员改进，`personal` 是个人改进 | 全部 |
| `--kind` | `overlay` 是界面改进，`request` 是交给开发者的代码改动 | 全部 |
| `--channel` | 看哪个通道的版本 | 有 production 版本时用 production，否则用 test |

```terminal title="看待采纳的改进"
$ aidc evolve list helpdesk --status proposed
helpdesk 1.0.0（production）· 1 个改进工程
cm2k9f3a70001qz7d5w1b8x4n  待采纳      所有人   发送按钮变深蓝
    李四 · 2026-10-08 13:20 · 基于 1.0.0
    发送按钮 · 背景色 #1e3a8a
```

每条改进三行：id、状态、范围和标题；作者、时间和基于哪个版本；指令的人话摘要。状态有四种：

| `--status` | 显示 | 含义 |
| --- | --- | --- |
| `live` | 生效中 | 个人改进只对提出的人生效，全员改进对所有人生效 |
| `proposed` | 待采纳 | 全员改进，对提出的人已生效，等 developer 采纳 |
| `rejected` | 未采纳 | developer 没有采纳 |
| `reverted` | 已撤销 | 已经撤销 |

要改代码的请求（`--kind request`）状态显示不同：`live` 显示「已采纳，待开发」，`proposed` 显示「待开发者处理」，`reverted` 显示「已撤回」。

范围显示为「所有人」「只对自己」或「要改代码」。改进指向的槽位在当前版本里没有时，标题后有「（当前版本已失效）」。

### aidc evolve show

看一条改进的原话、对话和指令。

```bash
aidc evolve show <slug> <id> [--channel test|production]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `<id>` | 改进的 id，取自 `aidc evolve list` 的第一列 | — |
| `--channel` | 看哪个通道的版本 | 有 production 版本时用 production，否则用 test |

```terminal title="看一条改进"
$ aidc evolve show helpdesk cm2k9f3a70001qz7d5w1b8x4n
cm2k9f3a70001qz7d5w1b8x4n  待采纳      所有人   发送按钮变深蓝
    李四 · 2026-10-08 13:20 · 基于 1.0.0
    发送按钮 · 背景色 #1e3a8a

对话：
  用户：发送按钮改成深蓝色
  助手：好的，已把发送按钮改成深蓝色。

指令：
[
  {
    "op": "style",
    "slot": "send",
    "set": {
      "background-color": "#1e3a8a"
    }
  }
]
```

找不到这个 id 时，命令报错，退出码 2。

### aidc evolve compile

看一句话会变成什么改进指令，不保存。

```bash
aidc evolve compile <slug> "<一句话>" [--slot <槽位>] [--model deepseek-flash|gpt-5.4-mini] [--channel test|production]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `"<一句话>"` | 用户会说的话，最多 500 个字符 | — |
| `--slot` | 先选中的槽位 | 从话里找槽位名 |
| `--model` | 编译用的模型：`deepseek-flash` 或 `gpt-5.4-mini` | 清单 `evolve.model`，缺省 `deepseek-flash` |
| `--channel` | 用哪个通道的版本 | 有 production 版本时用 production，否则用 test |

```terminal title="编译一句话"
$ aidc evolve compile helpdesk "发送按钮改成深蓝色"
好的，把发送按钮改成深蓝色。
  · 发送按钮 · 背景色 #1e3a8a
deepseek-flash · 1840 ms

[
  {
    "op": "style",
    "slot": "send",
    "set": {
      "background-color": "#1e3a8a"
    }
  }
]
```

常见说法（变大、变小、隐藏、恢复）不调模型，最后一行显示「快速意图」。要调模型时，用量按应用计费，计入计算分钟。界面指令做不到的改动，命令提示「界面指令做不到，需要改代码」。

### aidc evolve save

直接提交一条改进，不经过应用里的对话。适合智能体用。

```bash
aidc evolve save <slug> --ops <指令.json> --title "<标题>" [--scope app|personal] [--say "<原话>"] [--channel test|production] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `--ops` | 指令文件：一个指令数组，或 `{ "ops": [...] }`。必填 | — |
| `--title` | 改进的标题，最多 40 个字符。必填 | — |
| `--scope` | `app` 对所有人，`personal` 只对自己 | `app` |
| `--say` | 用户的原话，写进对话 | 同 `--title` |
| `--channel` | 保存到哪个通道的版本 | 有 production 版本时用 production，否则用 test |
| `--dry-run` | 只校验，不保存 | — |

```terminal title="提交一条改进"
$ cat ops.json
[{ "op": "style", "slot": "send", "set": { "background-color": "#1e3a8a" } }]
$ aidc evolve save helpdesk --ops ops.json --title "发送按钮变深蓝" --scope app
已保存：cm2k9f3a70001qz7d5w1b8x4n  生效中      所有人   发送按钮变深蓝
    张三 · 2026-10-08 13:41 · 基于 1.0.0
    发送按钮 · 背景色 #1e3a8a
```

指令有五种：

| 指令 | 做什么 |
| --- | --- |
| `token` | 改应用声明的可调参数，按范围夹紧 |
| `style` | 改一个槽位的样式 |
| `text` | 改只出现一次的槽位的文字 |
| `attr` | 改提示文字：`placeholder`、`title` 或 `aria-label` |
| `reset` | 恢复原样，可以只恢复几个属性 |

每种指令的写法：

```json
[
  { "op": "token", "name": "--chat-width", "value": "768px" },
  { "op": "style", "slot": "send", "set": { "background-color": "#1e3a8a" } },
  { "op": "text", "slot": "title", "text": "客服工作台" },
  { "op": "attr", "slot": "composer", "name": "placeholder", "value": "问点什么…" },
  { "op": "reset", "slot": "sidebar", "props": ["display"] }
]
```

- 一条改进最多 12 条指令。
- 每个应用同时生效的全员改进最多 40 条，到了先用 `aidc evolve bake` 写进源码。
- 每人同时生效的个人改进最多 20 条。
- 同样的文件和标题再提交一次，返回「已存在（幂等）」，不会重复保存。
- developer 提交的全员改进立即生效。

### aidc evolve adopt

采纳一条待采纳的全员改进，让它对所有人生效。

```bash
aidc evolve adopt <slug> <id> [--note <说明>] [--channel test|production] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `<id>` | 改进的 id | — |
| `--note` | 说明 | — |
| `--channel` | 改哪个通道的版本 | 有 production 版本时用 production，否则用 test |
| `--dry-run` | 只预演，不改状态 | — |

```terminal title="采纳一条改进"
$ aidc evolve adopt helpdesk cm2k9f3a70001qz7d5w1b8x4n
cm2k9f3a70001qz7d5w1b8x4n  生效中      所有人   发送按钮变深蓝
    李四 · 2026-10-08 13:20 · 基于 1.0.0
    发送按钮 · 背景色 #1e3a8a
```

对已经处于目标状态的改进再执行一次，命令报错，不会重复生效。

### aidc evolve reject

不采纳一条待采纳的改进，或拒绝一条提案。

```bash
aidc evolve reject <slug> <id> [--note <说明>] [--channel test|production] [--dry-run]
aidc evolve reject <提案 id>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug> <id>` | 应用的 slug 和改进的 id。给两个参数，管应用里的改进 | — |
| `<提案 id>` | 只给一个参数，管提案 | — |
| `--note` | 说明，只对改进有效 | — |
| `--channel` | 改哪个通道的版本，只对改进有效 | 有 production 版本时用 production，否则用 test |
| `--dry-run` | 只预演，不改状态，只对改进有效 | — |

```bash
aidc evolve reject helpdesk cm2k9f3a70001qz7d5w1b8x4n --note "先固化现有的改进"
aidc evolve reject cm2kb7q4e0005qz7d5w1b8x4n
```

不采纳界面改进时，它退回成提出人的个人改进，提出人的页面不会突然变回去。不采纳代码改动时，对应的提案变成 rejected。拒绝提案的输出是 `<提案 id> → rejected`。

### aidc evolve revert

撤销一条改进：自己的个人改进或待采纳改进，或 developer 撤销一条全员改进。

```bash
aidc evolve revert <slug> <id> [--note <说明>] [--channel test|production] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `<id>` | 改进的 id | — |
| `--note` | 说明 | — |
| `--channel` | 改哪个通道的版本 | 有 production 版本时用 production，否则用 test |
| `--dry-run` | 只预演，不改状态 | — |

```bash
aidc evolve revert helpdesk cm2k9f3a70001qz7d5w1b8x4n --note "按钮颜色和品牌色冲突"
```

输出和 `aidc evolve adopt` 一样，是这条改进的三行摘要，状态变成「已撤销」。

### aidc evolve propose

把自己的个人改进提交给所有人，或新建一条提案。

```bash
aidc evolve propose <slug> <id> [--note <说明>] [--channel test|production] [--dry-run]
aidc evolve propose --spec <提案.json>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug> <id>` | 应用的 slug 和改进的 id。给两个参数，把这条个人改进提交给所有人。developer 提交，立即对所有人生效 | — |
| `--spec` | 提案文件。不给 `<slug> <id>` 时必填 | — |
| `--note`、`--channel`、`--dry-run` | 同 `aidc evolve adopt`，只对改进有效 | — |

提案文件的字段：

| 字段 | 说明 |
| --- | --- |
| `target` | `semantic`、`app`、`action` 或 `data` |
| `title` | 标题，最多 120 个字符 |
| `rationale` | 理由，最多 2000 个字符 |
| `patch` | `semantic` 提案是一组语义补丁，只做加法。其他提案是 `{ "request": "要改什么" }` |
| `evidence` | 证据，最多 20 条，每条有 `kind`、`ref`、`excerpt` |
| `feedback` | 采纳哪些反馈的 id，最多 20 个。应用后这些反馈自动标记为已处理 |

```terminal title="新建一条提案"
$ aidc evolve propose --spec 提案.json
已提交提案 cm2kb7q4e0004qz7d5w1b8x4n：把发送按钮的深蓝色写进代码
```

提案 `target` 为 `app` 时，`patch` 写成 `{ "request": "…" }`，交给开发者或智能体改代码。

### aidc evolve overlay

看当前叠在应用上的改进：全员改进，加上你自己的个人改进。

```bash
aidc evolve overlay <slug> [--scope app] [--css] [--channel test|production]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `--scope` | 写 `app` 只看全员改进 | 全员加你自己的 |
| `--css` | 只输出覆盖层的 CSS | — |
| `--channel` | 看哪个通道的版本 | 有 production 版本时用 production，否则用 test |

```terminal title="看覆盖层"
$ aidc evolve overlay helpdesk
helpdesk 1.0.0 · 覆盖层 3f9a1c07 · 全员 1 条 · 你自己 0 条
  发送按钮 · 背景色 #1e3a8a

[data-evolve="send"]{background-color:#1e3a8a !important}
$ aidc evolve overlay helpdesk --css
[data-evolve="send"]{background-color:#1e3a8a !important}
```

没有任何改进时，命令打印「（没有改动）」。指向当前版本里不存在的槽位的改进，不会出现在这里，第一行的末尾有失效的条数。

### aidc evolve bake

把对所有人生效的改进写进应用的源码（只改本机文件）。部署并发布新版本后，已写进源码的改进不再叠加；没写进的照常生效。

```bash
aidc evolve bake <slug> [--dir <应用目录>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug，要和 `--dir` 里应用的 slug 一致 | — |
| `--dir` | 应用的源码目录 | `.` |
| `--dry-run` | 只打印会改什么，不写文件 | — |

```terminal title="先预演，再固化"
$ aidc evolve bake helpdesk --dir helpdesk --dry-run
（dry-run）将固化 1 条全员改进进 helpdesk 的源码，版本 1.0.0 → 1.0.1：
  ✓ 发送按钮变深蓝（发送按钮 · 背景色 #1e3a8a）
改动文件：evolve.css、index.html、plugin.json
$ aidc evolve bake helpdesk --dir helpdesk
已固化 1 条全员改进进 helpdesk 的源码，版本 1.0.0 → 1.0.1：
  ✓ 发送按钮变深蓝（发送按钮 · 背景色 #1e3a8a）
改动文件：evolve.css、index.html、plugin.json
下一步：aidc app deploy /home/demo/helpdesk → 在 Developer 里看一眼 → aidc app publish helpdesk。新版本上线后这些改进不再叠加（改进工程里显示「已固化进 1.0.1」）。
```

- 命令读 production 通道上生效中的全员界面改进。
- 样式和可调参数写进 `evolve.css`，入口页自动链上它。
- 文字写进静态 HTML，只改唯一出现的槽位。
- 文字改在脚本画出来的元素上的改进不固化，继续由覆盖层生效，命令用 `○` 列出它们。
- 清单的 `evolve.baked` 记下固化了哪些改进，版本号的 patch 加 1。
- 之后照常 `aidc app deploy`，在 Developer 里看一眼，再 `aidc app publish`。
- 没有可固化的改进时，命令打印「没有可固化的全员改进」，退出码 0。

### aidc evolve evidence

收集改进的证据：使用、反馈、操作、错误、语义定义与数据画像，以及用户在应用里做过的改进。智能体拿它判断该改什么。

```bash
aidc evolve evidence [<slug>] [--types <类型,…>] [--days <天数>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 围绕哪个应用，写应用的 slug | 整个组织 |
| `--types` | 额外关注的 Object Type，用逗号分隔，最多 12 个 | — |
| `--days` | 看最近几天，1–90 | 30 |

```terminal title="看证据有哪些部分"
$ aidc evolve evidence helpdesk --days 7 | jq keys
[
  "actions",
  "actionsDefined",
  "app",
  "days",
  "errors",
  "evolved",
  "feedback",
  "namespace",
  "openProposals",
  "semanticVersion",
  "types",
  "usage"
]
```

输出总是 JSON：

| 字段 | 内容 |
| --- | --- |
| `usage` | 打开、操作、反馈、错误的次数，访客数，常用项，按天的用量 |
| `feedback` | 未处理的反馈，带评分、原话和关联的对象 |
| `actions` | 最近 20 次操作 |
| `errors` | 最近的错误 |
| `types`、`actionsDefined` | 应用声明的 Object Type 的数据画像，以及相关的 Action |
| `openProposals` | 还没决定的提案 |
| `evolved` | 用户在应用里做过的改进：改了什么、给谁、留没留下 |

### aidc evolve suggest

让模型根据证据，加上你带来的材料，起草改进提案。提案存为 open，等你决定。

```bash
aidc evolve suggest [<slug>] [--types <类型,…>] [--file <文件>]… [--skill <SKILL.md>]… [--conversation <文件>]… [--model <模型>] [--max <条数>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 围绕哪个应用，写应用的 slug | 整个组织 |
| `--types` | 额外关注的 Object Type，最多 12 个 | — |
| `--file` | 口径、规范这类文件。可以重复，也可以用逗号分隔，最多 8 个 | — |
| `--skill` | 技能文件，如 `SKILL.md`。最多 8 个 | — |
| `--conversation` | 对话摘录。最多 8 个 | — |
| `--model` | 起草用的模型 | `gpt-5.4-mini` |
| `--max` | 最多提几条，1–10 | 5 |

命令按 UTF-8 文本读取文件。服务端按类别截取材料正文。口径文件共约 12,000 个字符。技能共约 8,000 个字符。对话共约 12,000 个字符。同类材料有多份时，服务端平分该类字符额度。用量按组织计费。

```terminal title="让模型起草提案"
$ aidc evolve suggest helpdesk --conversation 群聊.txt --max 2
gpt-5.4-mini 起草了 2 条提案：
  cm2kb7q4e0004qz7d5w1b8x4n  [app] 把发送按钮的深蓝色写进代码
      一条全员改进已经生效，三位同事在反馈里说发送按钮不够醒目。建议在下一个版本固化这条改进。
  cm2kb7q4e0005qz7d5w1b8x4n  [semantic] 说清楚「状态」的口径
      两条反馈都在问「状态」指当班还是当天。建议在对象类型里补一段说明。
```

模型只提 `semantic`（语义定义，只做加法）和 `app`（应用）两类提案。格式不对的提案被丢弃，输出里写「丢弃 N 条格式不对的」。

### aidc evolve proposals

列出提案。

```bash
aidc evolve proposals [--status open|accepted|rejected|applied]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--status` | 只看一个状态 | 全部 |

```terminal title="列出待决定的提案"
$ aidc evolve proposals --status open
cm2kb7q4e0004qz7d5w1b8x4n  open     [app] 把发送按钮的深蓝色写进代码
cm2kb7q4e0005qz7d5w1b8x4n  open     [semantic] 说清楚「状态」的口径
```

已应用的提案行尾有 `→ <落地的版本>`。没有提案时，命令打印「没有提案。」

### aidc evolve accept

采纳一条提案。采纳后还要 `aidc evolve apply` 才会落地。

```bash
aidc evolve accept <提案 id>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<提案 id>` | 提案的 id，取自 `aidc evolve proposals` | — |

```terminal title="采纳提案"
$ aidc evolve accept cm2kb7q4e0005qz7d5w1b8x4n
cm2kb7q4e0005qz7d5w1b8x4n → accepted
```

提案已经应用过时，命令报错，退出码 6。

### aidc evolve apply

应用一条提案。语义类提案会改定义并自动发一个新语义版本。智能体作者不能直接应用语义类提案：返回 `branch_required`（退出码 6），要走本体的分支与提案。应用类提案要带上落地它的应用版本号。

```bash
aidc evolve apply <提案 id> [--version <版本>] [--notes <说明>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<提案 id>` | 提案的 id | — |
| `--version` | 应用类提案必填：落地它的应用版本号，如 `1.2.0` | — |
| `--notes` | 说明，最多 500 个字符 | 语义类提案自动写「采纳改进提案：<标题>」 |

```terminal title="应用语义类提案"
$ aidc evolve apply cm2kb7q4e0005qz7d5w1b8x4n
已应用 cm2kb7q4e0005qz7d5w1b8x4n → v5
```

应用类提案的流程：

1. 开发者或智能体改代码。
2. `aidc app deploy` 把新版本放进 test 通道。
3. 人确认后，`aidc app publish` 发布。
4. `aidc evolve apply <提案 id> --version 1.2.0`，输出里的落地版本就是 `1.2.0`。

应用类提案不带 `--version`，命令报错，退出码 2。被采纳的反馈在应用后自动标记为已处理。

## aidc share

把一个应用分享给本组织全员、指定的账号，或持链接的人。要 developer。

```bash
aidc share <slug> (--company | --user <用户名或邮箱> | --public) [--role viewer|editor] [--days <天数>] [--note <备注>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 应用的 slug | — |
| `--company` | 分享给本组织全员 | — |
| `--user` | 分享给指定账号，写用户名或邮箱。账号可以属于别的组织 | — |
| `--public` | 生成一条公开链接。拿到链接的人要先登录 AIDC，只能读 | — |
| `--role` | `viewer` 只读，`editor` 可编辑。`--public` 只能是 `viewer` | `viewer` |
| `--days` | 有效天数，1–365 | 不过期 |
| `--note` | 备注，最多 200 个字符 | — |
| `--dry-run` | 只预演，不创建 | — |

三种分享方式选一种。同时给了几种，按 `--public`、`--user`、`--company` 的顺序取第一种。

```terminal title="分享应用"
$ aidc share inspector --user li.si@example.com --role viewer --days 30
已分享：inspector → users li.si@example.com（viewer）
$ aidc share inspector --public --days 7
已分享：inspector → public（viewer）
链接（只显示这一次）：https://www.ai-dc.ai/nexus/s/<32 位令牌>
```

- `--company` 和 `--user` 对同一个对象再分享一次，是改角色和有效期，命令打印「已更新分享」。
- `--public` 每次生成一条新链接，完整地址只在这一次输出里，之后只显示前缀。
- 每次创建和撤销都进审计和应用日志。
- 没有选择任何分享方式时，命令报错，退出码 2。
- 找不到账号时，退出码 5。

## aidc share list

列出分享，看谁能打开应用。要 developer。

```bash
aidc share list [<slug>]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<slug>` | 只看一个应用的分享 | 全部应用 |

```terminal title="列出分享"
$ aidc share list inspector
● cm2p4d8e10002qz7d5w1b8x4n  inspector  users:li.si  viewer  至 2026-11-07
● cm2p4d8e10003qz7d5w1b8x4n  inspector  public  viewer  /nexus/s/kY3d9a…  至 2026-10-15
○ cm2p4d8e10001qz7d5w1b8x4n  inspector  company  viewer  已撤销
```

实心圆点是有效的分享，空心圆点是已撤销或已过期的。最多列出最近的 200 条，新的在前。还没有分享时，命令打印「还没有分享。」

## aidc share revoke

撤销一条分享，链接立即失效。要 developer。

```bash
aidc share revoke <分享 id> [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<分享 id>` | 分享的 id，取自 `aidc share list` 的第二列 | — |
| `--dry-run` | 只预演，不撤销 | — |

```terminal title="撤销分享"
$ aidc share revoke cm2p4d8e10003qz7d5w1b8x4n
已撤销 cm2p4d8e10003qz7d5w1b8x4n
```

撤销是软删除，记录保留。找不到这条分享时，退出码 5。

## 下一步

- [应用（Apps）](apps.md)：应用的组成、清单、Skills 与 APIs。
- [发布 SDK](publish.md)：清单字段、通道和资源上限。
- [界面 SDK](ui.md)：组件、设计令牌和 `ui` 模块。
- [自进化 SDK](evolve.md)：槽位、改进指令、证据与提案。
- [快速开始](quickstart.md)：十分钟做出第一个应用。
- [CLI 概览](cli.md)：安装、登录、输出和退出码。
- [参考 · 模型与感知](cli-ai.md)：`aidc model`、`aidc vision`、`aidc voice` 等命令。