# 参考 · 账号与环境

本页讲账号和本机环境的命令：登录、退出、查身份、管理 Key、个人工作台、电子名片、更新、邮件通道、版本和帮助。登录有四种方式，都在 `aidc login` 一节说明。交互界面（直接敲 `aidc`）见 [交互界面](cli-chat.md)。

> [!NOTE]
> 用法里的 `<账号>` 是用户名或邮箱。`<cellId>` 是组织的命名空间，例如 `cell-demo`。`<图>` 是本机的图片文件。`[…]` 是可选项，`a | b` 是二选一。
> 除 `aidc login`、`aidc logout`、`aidc update`、`aidc help` 和 `aidc --version` 外，每条命令都要先登录。没有登录时，命令以退出码 3 结束。
> 通用参数（`--json`、`--api`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)。退出码见 [退出码](cli.md#退出码)。

| 命令 | 做什么 |
| --- | --- |
| [`aidc login`](#aidc-login) | 在终端里登录，换一把开发者 Key |
| [`aidc login --with-key`](#aidc-login---with-key) | 用一把现成的 Key 登录，给 CI 用 |
| [`aidc login --browser`](#aidc-login---browser) | 打印授权链接，人在浏览器里批准 |
| [`aidc login --continue`](#aidc-login---continue) | 浏览器批准后完成登录 |
| [`aidc logout`](#aidc-logout) | 删除本机的 Key |
| [`aidc whoami`](#aidc-whoami) | 看当前的账号、组织和角色 |
| [`aidc keys`](#aidc-keys) | 列出开发者 Key |
| [`aidc me`](#aidc-me) | 我的工作台：身份、席位、用量、存储 |
| [`aidc me org`](#aidc-me-org) | 组织用量（要 developer） |
| [`aidc me card`](#aidc-me-card) | 看我的电子名片 |
| [`aidc me card set`](#aidc-me-card-set) | 改电子名片 |
| [`aidc me card publish`](#aidc-me-card-publish) | 公开电子名片 |
| [`aidc me card unpublish`](#aidc-me-card-unpublish) | 不公开电子名片 |
| [`aidc me card delete`](#aidc-me-card-delete) | 删除电子名片 |
| [`aidc update`](#aidc-update) | 把 aidc 更新到最新版 |
| [`aidc aidh install`](#aidc-aidh-install) | 装或更新本机的 AIDH 引擎 |
| [`aidc aidh status`](#aidc-aidh-status) | 看本机 AIDH 的版本与目录 |
| [`aidc twin`](#aidc-twin) | 绑定、查看、解绑你的数字分身 |
| [`aidc node join`](#aidc-node-join) | 登记这台电脑，给数字分身用 |
| [`aidc node policy`](#aidc-node-policy) | 设这台电脑允许分身做什么 |
| [`aidc node up`](#aidc-node-up) | 起、停这台电脑上的 worker，看状态，列出名下电脑 |
| [`aidc node grant`](#aidc-node-grant) | 这台电脑对分身收窄、只在本人说话时用，或不给用 |
| [`aidc notify test`](#aidc-notify-test) | 发一封测试邮件，检查邮件通道 |
| [`aidc issue report`](#aidc-issue-report) | 报告 AIDC 本身的问题，交给自动修复 |
| [`aidc --version`](#aidc---version) | 打印版本号 |
| [`aidc help`](#aidc-help) | 打印全部命令 |

## aidc login

在终端里输入账号和密码，换一把开发者 Key，存进 `~/.aidc/config.json`。账号须已验证邮箱、已设置正式密码，并属于至少一个组织。登录后的角色（member 或 developer）由组织决定。

```bash
aidc login [--user <账号>] [-n <cellId>]
aidc login --with-key
aidc login --browser [--no-wait]
aidc login --continue [--no-wait]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--user <账号>` | 账号。给了，就不再问账号 | 上次登录的账号 |
| `-n`、`--namespace <cellId>` | 要代表的组织。能代表多个组织的账号，用它选择一个 | 在终端里选 |
| `--with-key` | 从标准输入读一把开发者 Key。见 [`aidc login --with-key`](#aidc-login---with-key) | — |
| `--browser` | 打印授权链接和授权码。见 [`aidc login --browser`](#aidc-login---browser) | — |
| `--continue` | 接着上一次 `--browser` 完成登录。见 [`aidc login --continue`](#aidc-login---continue) | — |
| `--no-wait` | 不等待。`--browser` 打印后马上返回；`--continue` 只查一次 | 一直等到批准或超时 |
| `--json` | 输出 JSON | 标准输出不是终端时自动开启 |

```terminal title="终端登录"
$ aidc login --user zhang.san
登录 AIDC Developer（https://www.ai-dc.ai）
还没有账号？在 https://www.ai-dc.ai/login 点「注册」创建（建议用公司邮箱）；使用 AIDC Developer 至少要是一家公司的 member（公司发给你的授权码），部署与发布还要 developer。

密码：
已登录：张三（zhang.san）· Demo Company（cell-demo）· developer
```

- 账号提示会带上上次的账号，例如 `账号（用户名或邮箱）[zhang.san]：`。直接按回车，就用它。
- 密码输入时不显示字符。输错时，aidc 显示「账号或密码不对，再输一次。」终端里最多输三次。
- 账号能代表多个组织时，aidc 列出这些组织。输入序号或 `cellId` 选择一个。
- 按 Ctrl-C 取消。退出码是 130。
- 密码只在提示处输入。`aidc login` 不读命令行参数、环境变量或标准输入里的密码。传入 `--password` 时，aidc 报错并以退出码 2 结束。
- 不在交互终端里运行时（智能体、CI 或管道），aidc 立即以退出码 2 结束，并告诉你改用 `--with-key` 或 `--browser`。
- 登录成功后，Key 写进配置文件。每次登录都签一把新 Key，旧的仍然有效。
- 以 member 身份登录时，aidc 会说明：member 能调用应用、在本机开发；部署与发布要 developer。

退出码：

| 退出码 | 情形 |
| --- | --- |
| 0 | 登录成功 |
| 2 | 不在交互终端里运行；没输入账号或密码；用了 `--password` |
| 2 | `--with-key` 的输入不是 `aidc-dk-` 开头 |
| 2 | 没有待完成的浏览器登录；浏览器批准超过 10 分钟 |
| 3 | 三次都输错了账号或密码；Key 无效；浏览器还没批准（`--continue --no-wait`） |
| 4 | 账号还不属于任何组织；邮箱未验证；临时密码要先改；`-n` 指定的组织不是这个账号能代表的 |
| 7 | 登录尝试太频繁 |
| 8 | 连不上服务器 |
| 130 | 按 Ctrl-C 取消 |

### aidc login --with-key

把一把现成的开发者 Key（`aidc-dk-…`）存到本机。CI 和无人值守的机器用它。不需要先登录。

```bash
aidc login --with-key < key.txt
```

```terminal title="用 Key 登录"
$ aidc login --with-key < key.txt
已登录：zhang.san · Demo Company（cell-demo）· developer
```

- Key 只从标准输入读。命令行参数和环境变量里的 Key 不会被读取。
- 标准输入不是 `aidc-dk-` 开头的 Key 时，退出码 2。
- aidc 先在服务端核验这把 Key。Key 无效时，退出码 3。
- CI 里更常见的做法是设置环境变量 `AIDC_API_KEY`，不运行这条命令。见 [在 CI 和智能体里用](cli.md#在-ci-和智能体里用)。

### aidc login --browser

打印一个授权链接和授权码。人在浏览器里批准后，接着运行 `aidc login --continue`。身边没有终端的智能体用它。不需要先登录。

```bash
aidc login --browser [--no-wait] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--no-wait` | 打印链接后马上返回，不等待批准 | 一直等到批准或超时 |
| `--json` | 输出 JSON。链接在 `url`，授权码在 `userCode` | 标准输出不是终端时自动开启 |

```terminal title="打印授权链接"
$ aidc login --browser --no-wait --json
{"event":"authorize","url":"https://www.ai-dc.ai/developer/cli/authorize?code=BDKF-QRTZ","userCode":"BDKF-QRTZ","expiresIn":600}
```

- 授权码 10 分钟内有效。`expiresIn` 的单位是秒。
- 不加 `--no-wait` 时，aidc 每隔几秒查一次，直到批准或超时。在终端里，它还会打印链接和授权码。
- 等待期间，授权信息保存在配置文件的 `pending` 字段里。设备码只存在这台机器上。
- 身边没有终端时，先用 `--no-wait --json` 拿到链接，把链接交给人。之后用 `aidc login --continue --no-wait --json` 查批准状态。

### aidc login --continue

接着上一次 `aidc login --browser` 完成登录。加 `--no-wait` 时只查一次，适合智能体轮询。不需要先登录。

```bash
aidc login --continue [--no-wait] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--no-wait` | 只查一次。没批准时退出码 3；批准了就完成登录 | 一直等到批准或超时 |
| `--json` | 输出 JSON | 标准输出不是终端时自动开启 |

```terminal title="查一次批准状态"
$ aidc login --continue --no-wait --json
{"event":"authorization_pending","url":"https://www.ai-dc.ai/developer/cli/authorize?code=BDKF-QRTZ","userCode":"BDKF-QRTZ","expiresAt":"2026-10-08T12:10:00.000Z"}
$ echo $?
3
$ aidc login --continue --no-wait --json
{"event":"logged_in","username":"zhang.san","cellId":"cell-demo","companyName":"Demo Company","role":"developer","keyPrefix":"aidc-dk-…"}
$ echo $?
0
```

- 没有待完成的登录，或者登录已经过期，退出码 2。先运行 `aidc login --browser --no-wait`。
- 批准以后，aidc 保存 Key，并清除 `pending`。
- 不加 `--no-wait` 时，一直等到批准。超时后退出码 2，要重新运行 `aidc login --browser`。

## aidc logout

删除本机的开发者 Key。服务端的 Key 仍然有效，除非加 `--revoke`。不需要先登录。

```bash
aidc logout [--revoke] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--revoke` | 同时在服务端吊销配置文件里的这把 Key。吊销后，这把 Key 在任何机器上都不能用 | 不吊销 |

```terminal title="退出登录"
$ aidc logout
已退出（Key 仍有效，要吊销请加 --revoke）。
```

```terminal title="退出并吊销"
$ aidc logout --revoke
已退出并吊销这把开发者 Key。
```

- 退出只清除登录信息：Key、组织、角色和账号名。`apiBase` 和交互界面的设置留在配置文件里。
- 环境变量 `AIDC_API_KEY` 不受影响。`aidc logout` 只改配置文件。
- 退出后，运行需要登录的命令，退出码是 3。

## aidc whoami

显示当前登录的账号、组织、角色和 Key 前缀。member 和 developer 都能用。

```bash
aidc whoami [--json]
```

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

- member 的那一行以「不能部署 / 发布（member）」结尾。
- `--json` 输出 `account`、`company`、`role`、`key` 和 `namespaces` 五个字段。
- 取一个字段，例如 `aidc whoami --json | jq -r .company.cellId`，输出 `cell-demo`。

用 Agent Key（`aidc-sk-…`）时，`aidc whoami` 显示这个智能体的身份：智能体名、组织、本体上的角色。受限的 Key 另外列出能做的操作、能读的对象类型和能执行的 Action。

```terminal title="智能体看身份"
$ aidc whoami
智能体 demo-agent · 公司 cell-demo · viewer（按公司授予的权限）
```

## aidc keys

列出你的开发者 Key，有效的和已吊销的都列出。member 和 developer 都能用。

```bash
aidc keys [--json]
```

```terminal title="列出 Key"
$ aidc keys
✓ aidc-dk-…  cell-demo  aidc CLI 1.77.0  2026-10-08T09:30:12.000Z
✗ aidc-dk-…  cell-demo  aidc CLI 1.76.0  2026-10-06T14:02:51.000Z
```

- 每行依次是：状态、Key 前缀、组织、创建它的客户端、最近使用的时间。
- `✓` 表示 Key 有效。`✗` 表示已吊销。没用过的 Key 写「未使用」。
- 命令行只能吊销本机的 Key，用 `aidc logout --revoke`。
- `--json` 输出 `keys` 列表。每项有 `id`、`prefix`、`cellId`、`client`、`role`、`createdAt`、`lastUsedAt` 和 `revoked`。

## aidc me

显示我的工作台：身份、席位与配额、本月用量、分身和存储。member 和 developer 都能用。

```bash
aidc me [--period month|30d|YYYY-MM] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--period` | 用量的时间段：`month` 是本月（按 UTC），`30d` 是最近 30 天，`YYYY-MM` 是某一个月 | `month` |
| `-n`、`--namespace <cellId>` | 看哪个组织 | 当前开发者 Key 所属组织。使用 `AIDC_API_KEY` 时，以该 Key 所属组织为准 |

```terminal title="看我的工作台"
$ aidc me
张三（zhang.san）· Demo Company（cell-demo）· 已核验 · developer
席位：人 · 1 个席位（含分身）· 每月配额 …
…
```

- 第一行显示姓名、账号、组织和核验状态。具备 developer 角色时，追加 `developer`。
- 之后是席位和配额、本月用量（按来源分行）、分身、存储。
- 存储分三项：我的文件、Space 和回收站。
- 你负责的智能体列在最后，每个智能体有自己的用量和回合数。
- 文件太多时，存储只数前 5,000 个，行里写「至少」。
- `--json` 输出完整的工作台数据。

## aidc me org

显示组织里每个人和每个数字员工的用量与存储。要该组织的 developer。

```bash
aidc me org [--period month|30d|YYYY-MM] [--sort storage] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--period` | 同 [`aidc me`](#aidc-me) | `month` |
| `--sort storage` | 按存储排序。不给时，按计算秒排序 | 按计算秒 |
| `-n`、`--namespace <cellId>` | 看哪个组织 | 当前开发者 Key 所属组织。使用 `AIDC_API_KEY` 时，以该 Key 所属组织为准 |

```terminal title="看组织用量"
$ aidc me org --sort storage
Demo Company（cell-demo）· 2026-10
席位：2 / 20（只按人数）· 数字员工 3 个，不占席位
…
  人  张三               2,100 tokens · 42 计算秒 · 3 个回合 · 存储 0.5 GB
```

- 最多列出 30 行。要看全部，加 `--json`。
- 席位只按人数算。数字员工不占席位。
- 没有该组织 developer 角色时，退出码为 4。

## aidc me card

看我的电子名片：名字、职位、联系方式、链接、外观、是否公开，以及打开次数。member 和 developer 都能用。

```bash
aidc me card [-n <cellId>] [--json]
```

```terminal title="看名片"
$ aidc me card
张三（Zhang San）· 产品经理 · Demo Company
公开 · https://www.ai-dc.ai/card/zhang-san · 打开过 12 次（最近 2026-10-07）
邮箱 zhang.san@example.com
外观 背景 signal · 二维码 signal / dots / 中间 aidc · 头像没有 · 微信二维码没有
```

- 还没有名片时，命令提示用 `aidc me card set --title …` 建一张。
- 名片没有公开时，链接和二维码都打不开。

### aidc me card set

改我的电子名片，只改你写了的项。member 和 developer 都能用。第一次运行会建一张名片，姓名缺省用账号的显示名。

```bash
aidc me card set [--name <姓名>] [--name-en <英文名>] [--title <职位>] [--rank <职级>] [--department <部门>] \
  [--phone <手机>] [--office-phone <座机>] [--email <邮箱>] [--wechat <微信号>] [--dingtalk <钉钉号>] \
  [--address <地址>] [--website <网址>] [--bio <简介>] [--tag <标签>]… [--link <标题=网址>]… \
  [--avatar <图|none>] [--wechat-qr <图|none>] [--theme signal|ink|clay|dawn] \
  [--qr-color signal|ink|ocean|forest] [--qr-style dots|rounded|square] [--qr-center aidc|avatar|none] \
  [--clear-tags] [--clear-links] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name`、`--name-en`、`--title`、`--rank`、`--department` | 姓名、英文名、职位、职级、部门 | 姓名缺省用账号的显示名 |
| `--phone`、`--office-phone`、`--email`、`--wechat`、`--dingtalk` | 手机、座机、邮箱、微信号、钉钉号 | — |
| `--address`、`--website`、`--bio` | 地址、网址、简介 | — |
| `--tag <标签>` | 标签。可以重复，也可以用逗号分隔。`--clear-tags` 清空全部标签 | — |
| `--link <标题=网址>` | 链接，例如 `--link 官网=https://example.com`。可以重复。`--clear-links` 清空全部链接 | — |
| `--avatar <图>` | 头像。图片只收 `.png`、`.jpg`、`.jpeg`、`.webp`，不超过 290,000 字节。写 `none` 删除头像 | 不改 |
| `--wechat-qr <图>` | 微信二维码图片，规则同头像。写 `none` 删除 | 不改 |
| `--theme`、`--qr-color`、`--qr-style`、`--qr-center` | 背景、二维码颜色、二维码样式、二维码中间的图案。取值见用法 | 不改 |
| `--dry-run` | 只显示改后的结果，不保存 | — |

```terminal title="先预演"
$ aidc me card set --title 产品经理 --dry-run
（dry-run，没保存）
张三（Zhang San）· 产品经理 · Demo Company
公开 · https://www.ai-dc.ai/card/zhang-san · 打开过 12 次（最近 2026-10-07）
…
```

- 至少写一项。什么都不写时，退出码 2。
- 头像和微信二维码的图片在本机读取，再上传。格式不对或太大时，退出码 2。图片先裁成正方形，网页上传会自动裁成 512×512。
- 没有写的项保持原样。

### aidc me card publish

公开我的电子名片。公开后，链接和二维码可以打开。member 和 developer 都能用。

```bash
aidc me card publish [-n <cellId>] [--json]
```

```terminal title="公开名片"
$ aidc me card publish
张三（Zhang San）· 产品经理 · Demo Company
公开 · https://www.ai-dc.ai/card/zhang-san · 打开过 12 次（最近 2026-10-07）
…
```

### aidc me card unpublish

不公开我的电子名片。不公开后，链接和二维码都打不开。名片的内容保留。member 和 developer 都能用。

```bash
aidc me card unpublish [-n <cellId>] [--json]
```

```terminal title="不公开名片"
$ aidc me card unpublish
张三（Zhang San）· 产品经理 · Demo Company
没公开（链接与二维码打不开） · https://www.ai-dc.ai/card/zhang-san · 打开过 12 次（最近 2026-10-07）
…
```

### aidc me card delete

删除我的电子名片。链接和二维码立刻失效。实际删除须加 `--yes`。使用 `--dry-run` 时不需要。member 和 developer 都能用。

```bash
aidc me card delete [--yes] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--yes` | 确认实际删除。实际删除时不加，命令报错，退出码 2。使用 `--dry-run` 时不需要 | — |
| `--dry-run` | 只看会不会删，不删 | — |

```terminal title="删除名片"
$ aidc me card delete --yes
名片已删除，链接与二维码已失效。
网页上可以重新做一张：Semantic › 我的 › 名片。
```

- 没有名片时，命令显示「没有名片可删。」
- `--dry-run` 时，命令显示「（dry-run）会删掉这张名片。」或「（dry-run）没有名片可删。」

## aidc update

把本机的 aidc 换成线上最新版。不需要登录，任何人都能用。

```bash
aidc update [--check] [--force] [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--check` | 只看线上版本，不改文件 | — |
| `--dry-run` | 说明会从哪个版本换成哪个版本，不改文件 | — |
| `--force` | 线上版本与本机相同或更旧时也换。用来降级，或修复损坏的安装 | 只换到更新的版本 |
| `--json` | 输出 JSON | 标准输出不是终端时自动开启 |

```terminal title="检查并更新"
$ aidc update --check
有新版：1.76.0 → 1.77.0。运行 aidc update 更新。
$ aidc update
已更新：1.76.0 → 1.77.0（/home/demo/.aidc/bin/aidc.mjs）
更新内容：https://www.ai-dc.ai/developer/docs/changelog
要退回上一版：mv /home/demo/.aidc/bin/aidc.mjs.prev /home/demo/.aidc/bin/aidc.mjs
```

更新的做法：

- 从安装脚本用的同一个地址下载新版。
- 先写到同目录的临时文件，运行一次 `--version` 核对，再替换原来的文件。中途失败，原来的 aidc 照常能用。
- 旧版本留在 `aidc.mjs.prev`。要退回，运行输出里的 `mv` 命令。
- 登录、Key 和配置文件不受影响。
- 只从 https 地址下载。本机开发用的 `http://localhost` 除外。
- 同一时间只能有一个 `aidc update` 在换。它用锁文件 `aidc.update.lock` 挡住别的更新。
- 仅更新真实文件名为 `aidc.mjs`、且同目录有指向它的 `aidc` 符号链接的安装。直接通过 Node 运行符合条件的文件也能更新。

检查版本时，JSON 包含 `current` 和 `latest`。`updateAvailable` 表示是否有新版，`path` 表示安装路径。更新后还有 `updated`、`from`、`to` 和 `previous`。`path` 是符合上述条件的 `aidc.mjs`。这份 aidc 不符合上述条件时，`path` 是 `null`。

退出码：

| 退出码 | 情形 | 怎么办 |
| --- | --- | --- |
| 0 | 成功，或已是最新版 | — |
| 2 | 这份 aidc 不是安装脚本装的；API 根不是 https 地址 | 重新运行安装脚本 |
| 4 | 安装目录写不进去 | 检查目录的权限 |
| 6 | 另一个 `aidc update` 正在运行 | 等待更新结束 |
| 6 | 上次更新被打断，留下了锁 | 遗留锁超过 10 分钟且确认没有更新运行时，加 `--force` |
| 6 | 本机版本已变化 | 重新运行 `aidc update` |
| 8 | 下载失败；下到的不是 aidc；新版跑不起来 | 本机文件不动，稍后重试 |

## aidc aidh install

装本机的 AIDH 运行时：引擎、独立的 Python 和锁定版本的依赖。AIDH 是本机的智能体引擎，和 AIDC Desktop（Adis）用同一份运行时。大小和 sha256 都对上才装；对不上就失败，本机不动。

```bash
aidc aidh install [--force] [--dry-run]
aidc aidh update [--force] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--force` | 已经是这一版也重新下载 | — |
| `--dry-run` | 只看会装哪一版、要不要下载，不下载 | — |

```bash
aidc aidh install
aidc aidh update --dry-run
```

- 运行时装在 `~/.aidc/aidh-runtime/<版本>/`，约 120 MB。`current` 指向在用的一版。
- `update` 有新版才换。上一版留着回退，更早的删掉。
- 本机已经有 Adis 装的运行时，就直接用它，不重复下载。`AIDC_AIDH_RUNTIME_DIR` 可以指到一棵已解包的运行时。
- 交互界面的 AIDH 运行时和 `aidc node` 都用这一份。
- 支持 macOS（Apple 芯片）和 Windows x64。

## aidc aidh status

看本机在用的 AIDH 运行时、引擎版本和线上最新版。`aidc aidh path` 打印运行时目录和启动器。

```bash
aidc aidh status [--offline] [--json]
aidc aidh path [--json]
aidc aidh <引擎命令…>
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--offline` | 不查线上最新版 | 查 |
| `--json` | 输出 JSON，给脚本和桌面版读 | 文字 |

- 其余参数原样交给引擎，例如 `aidc aidh chat`、`aidc aidh acp`、`aidc aidh --version`。
- 本机还没有运行时：命令报 `not_found`，提示先运行 `aidc aidh install`。

## aidc twin

绑定你的数字分身。数字分身代表你：你名下每一台登记过的电脑，它都能用，不用一台一台借。

数字分身要满足三条：在花名册里是私有的、主人是你、没有共享给别人（组、全员、链接或别的人）。一个人只有一个分身，一个智能体只属于一个人。部门和公共智能体不能绑。

```bash
aidc twin [--json]
aidc twin bind <智能体> [--dry-run]
aidc twin unbind [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `bind <智能体>` | 把这个智能体绑成你的分身。已经有分身时，换成新的 | — |
| `unbind` | 解绑。分身立即不能再用你的电脑 | — |
| `--dry-run` | 只预演，不改 | — |

```bash
aidc twin bind zhang-san-twin
aidc twin
```

- `aidc twin` 显示你的分身，以及你名下每台电脑它能不能用。
- 分身共享给别人之后，就不能再用你的电脑。
- 平台每次使用时都再判一次。认得出是别人在跟你的分身说话时，它不能动你的电脑。

## aidc node join

登记这台电脑。电脑的主人是登录的账号。登记以后，你的数字分身就能用它。要先运行 `aidc aidh install`。

智能体在云端的共享池里运行。分身用你的电脑读文件、写文件、跑命令。电脑不开入站端口，worker 只出站去领活。有三道闸：

1. 电脑登记在你名下。
2. 分身是你的：一个人一个，一个智能体只属于一个人。
3. 每台电脑本机的策略说了算。没设策略，什么都不许。

```bash
aidc node join [--name <显示名>] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--name` | 这台电脑的显示名 | — |
| `--dry-run` | 只预演，不登记 | — |

```bash
aidc node join --name "张三的笔记本"
```

## aidc node policy

设这台电脑的本机策略：允许的目录、能做什么、能跑哪些程序、哪些操作先问你。策略只存在这台电脑上。

```bash
aidc node policy [--allow <目录>…] [--remove <目录>…] [--scopes read,write,exec] [--exec ls,git…|none] [--ask write,exec|none] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--allow`、`--remove` | 允许、去掉的目录，可以写多个。不允许整个家目录或根目录 | 没有目录 |
| `--scopes` | 这台电脑允许的事：读（列目录、读文件）、写文件、跑命令。和平台那一道取交集 | 什么都不许 |
| `--exec` | 允许跑的程序，按程序名。`none` 表示都不许 | 都不许 |
| `--ask` | 哪些操作先在电脑上弹窗问你。60 秒没点就拒绝。`none` 表示都不问 | `write,exec` |
| `--dry-run` | 只看改后的策略，不保存 | — |

```bash
aidc node policy --allow ~/Documents/工作 --scopes read,write --ask write
```

- 允许的目录之外的路径一律拒绝，软链接指到外面也拒绝。
- 命令不经 shell。参数里写出来的路径，也必须在允许的目录里。
- 每一步都记在这台电脑上的审计日志里：`~/.aidc/node/logs/device-audit.log`。

## aidc node up

起这台电脑上的 worker。worker 在后台常驻，macOS 上开机自启。

```bash
aidc node up [--foreground]
aidc node down
aidc node status
aidc node list
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--foreground` | 在前台跑，不装成后台服务 | 后台 |

- `aidc node down` 停 worker。
- `aidc node status` 显示这台电脑：在线状态、本机策略、分身能不能用。
- `aidc node list` 列出你名下的所有电脑：在不在线、worker 版本、分身能不能用。

## aidc node grant

调整这台电脑给分身用的方式。分身缺省就能用你名下的每一台电脑：读、写、跑命令全开，本机策略再收一道。

```bash
aidc node grant [--scopes read,write,exec] [--only-me] [--dry-run]
aidc node revoke [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--scopes` | 这台电脑对分身收窄到这些事 | 全开 |
| `--only-me` | 只在你本人跟分身说话时，它才能用这台电脑 | 认不出是别人时都能用 |
| `--dry-run` | 只预演，不改 | — |

```bash
aidc node grant --scopes read
aidc node grant --only-me
aidc node revoke
```

- `aidc node grant` 不带参数，恢复缺省的全开。
- `aidc node revoke` 让这台电脑不给分身用，立即生效。
- 命令里可以写智能体名，写的要是你的分身，否则返回 409 `twin_mismatch`。还没有分身时，`aidc node grant <智能体>` 会把它绑成你的分身。
- `--only-me` 要认得出是谁在说话。网页工作台、AIDC Desktop、Agent API 的个人 Key 和 Engine 试运行认得出是你。企业微信、钉钉还认不出人，`--only-me` 在那里不可用。
- 智能体那一侧用 MCP 工具：`list_devices`、`list_dir`、`read_file`、`write_file`、`run_command`。

## aidc notify test

给自己发一封测试邮件，检查工作流的邮件通道能不能送达。要 developer。

```bash
aidc notify test [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--dry-run` | 只显示发件人、收件人、通道，以及邮件、企业微信、钉钉渲染后的样子。不发信，不记账 | — |

收件人是这把 Key 的持有人的已验证邮箱。每个账号每 10 分钟最多发 3 次。超过时，退出码 7。

```terminal title="发测试邮件"
$ aidc notify test
zhang.san@example.com：已发出，去收件箱看看
```

| 输出 | 意思 | 退出码 |
| --- | --- | --- |
| 已发出，去收件箱看看 | 邮件已发出 | 0 |
| 没发出：邮件通道未配置（生产环境变量 RESEND_API_KEY） | 平台还没配置邮件通道 | 8 |
| 被拦下（冷却 / 日上限） | 发信太频繁，被拦下 | 8 |
| 发送失败 | 邮件发送出错 | 8 |

## aidc issue report

报告 AIDC 本身的问题：报错、打不开、太慢、费用不对。命令开一张问题单，按策略排进 AIDC 的自动修复。member 和 developer 都能用。

```bash
aidc issue report "<一句话>" --description "<经过>" [--conversation <对话 id>] [--page <页面或应用>] [-n <cell-…>|public] [--dry-run]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `"<一句话>"` | 问题的标题 | — |
| `--description` | 经过：做了什么，看到了什么 | — |
| `--conversation` | 出问题的对话 id | — |
| `--page` | 出问题的页面或应用 | — |
| `-n` | 组织；`public` = AIDC 平台本身的问题，不挂在哪家组织下 | 登录的组织（只在一家组织时） |
| `--dry-run` | 只看要开的单，不提交 | — |

```terminal title="报告一个问题"
$ aidc issue report "看板打不开" --description "打开 /semantic/cell-demo/applications/daily 一直转圈，刷新也一样" --page daily
已记下：问题单 afi_3c9e1b7d2a4f6085（open），已排进自动修复
```

- 每人每小时最多 10 条。
- 智能体手里只有只读 Key 时，用 Ontology MCP 的 `report_issue` 工具报，额度相同。见[智能体接入](agents.md)。

## aidc --version

打印 aidc 的版本号。不需要登录，任何人都能用。`aidc -v` 相同。

```bash
aidc --version [--json]
```

```terminal title="看版本"
$ aidc --version
1.77.0
$ aidc --version --json
{"version":"1.77.0"}
```

- 只在不带子命令时有效。`aidc app publish --version 1.2.0` 这类子命令里的 `--version` 是参数，见 [参考 · 应用与界面](cli-apps.md)。

## aidc help

打印全部命令和用法。不需要登录，任何人都能用。

```bash
aidc help
aidc --help
aidc -h
```

- `aidc help`、`aidc --help`、`aidc -h`，以及在命令后面加 `--help`，都打印同一份清单。清单不分组。
- 直接运行 `aidc`，在终端里进入交互界面。不在终端里运行时，打印这份清单。
- 用 `grep` 找一条命令：

```terminal title="查一条命令"
$ aidc help | grep "aidc logout"
  aidc logout [--revoke]                   删除本机 Key（--revoke 同时在服务端吊销）
```

## 配置文件与环境变量

aidc 把登录的结果写进配置文件。环境变量可以覆盖其中的 Key 和 API 根地址。

配置文件是 `~/.aidc/config.json`。`AIDC_CONFIG_DIR` 可以换一个目录。目录的权限是 0700，文件的权限是 0600。

> [!IMPORTANT]
> 配置文件里有开发者 Key。不要提交进代码仓库，也不要发给别人。CI 用密钥库里的 `AIDC_API_KEY`。

| 字段 | 内容 |
| --- | --- |
| `apiKey` | 开发者 Key，`aidc-dk-…` 开头 |
| `keyPrefix` | Key 的前缀，用来显示 |
| `cellId` | 组织的命名空间，例如 `cell-demo` |
| `companyName` | 组织的名字 |
| `role` | `developer` 或 `member` |
| `username` | 账号。下次 `aidc login` 时作为默认账号 |
| `apiBase` | API 的根地址 |
| `savedAt` | 保存配置的时间 |
| `pending` | 浏览器批准还没完成时的授权信息 |
| `tui` | 交互界面记住的选择 |

| 环境变量 | 作用 |
| --- | --- |
| `AIDC_API_KEY` | 开发者 Key。设了它，就不用登录。它优先于配置文件里的 Key |
| `AIDC_API_BASE` | API 的根地址 |
| `AIDC_CONFIG_DIR` | 配置目录。缺省是 `~/.aidc` |

aidc 按这个顺序找凭证和地址：

- Key：环境变量 `AIDC_API_KEY`，然后是配置文件里的 `apiKey`。
- API 根地址：`--api`，然后是 `AIDC_API_BASE`，然后是配置文件里的 `apiBase`，最后是 `https://www.ai-dc.ai`。

## 下一步

- [交互界面](cli-chat.md)：直接敲 `aidc`，在终端里和智能体对话。
- [参考 · 模型与感知](cli-ai.md)：模型、视觉、语音、视频和建模命令。
- [参考 · 应用与界面](cli-apps.md)：应用的校验、部署和发布。
- [CLI 概览](cli.md)：安装、输出格式和退出码。