# 数字分身与你的电脑

数字分身是代表你的那个智能体，下文简称分身。分身能用你名下的每一台电脑，读写文件、跑命令、把文件发给你。每台电脑上的本机策略决定分身能做什么。

> [!NOTE]
> 前提：要能运行 `aidc`（Node.js 18 以上）。你要用自己的账号登录（`aidc login`），并且至少是一家组织的 member。电脑要是 macOS（Apple 芯片）或 Windows x64。

## 快速上手

这一节用两条命令，让分身用上这台 Mac。开始前，先装好 aidc 并登录，见[接上一台 Mac](#接上一台-mac)。

```terminal title="接上这台 Mac"
$ aidc twin bind zhang-san-twin
已绑定：张三的分身（zhang-san-twin）是你的数字分身。你名下每一台登记过的电脑它都能用（每台本机策略再收）；aidc twin 查看。
$ aidc node setup --full --yes --stay-awake
1/4 装 AIDH 运行时（约 120 MB，sha256 校验）…
下载 AIDH 运行时 0.21.3-2：100%
2/4 登记这台电脑…
4/4 起后台 worker…
这台电脑已接上：zhang-san-mbp（demo-zhang-san-mbp-k3f9）
  AIDH 运行时：刚装好 0.21.3-2
  登记：刚登记（demo-zhang-san-mbp-k3f9 → Demo Company）
  worker：0.8.0 已在后台运行（LaunchAgent ai.aidc.cli-node，登录即起）：demo-zhang-san-mbp-k3f9 → https://www.ai-dc.ai
  本机策略：全权（与你本人同权：任何文件、经你的 shell 跑任何命令）· read、write、exec · 先问我：不问（刚改）
  睡眠：插着电时不睡（caffeinate -s；用电池、合上盖子照常睡）· aidc node up --allow-sleep 收回
  数字分身：张三的分身（zhang-san-twin） · 分身 zhang-san-twin 能用：read、write、exec
…
```

`--full --yes` 给分身全权，见[选择权限](#选择权限)。要限定目录时，改用 `--allow` 和 `--scopes`。

## 绑定数字分身

用 `aidc twin bind <智能体>` 把一个智能体绑成你的数字分身。分身是组织共享池里的一个智能体，代表你。

能绑的智能体要同时满足三条：

- 在花名册里是私有的。
- 主人是你。
- 没有共享给任何组、全员、链接或其他人。

部门和公共智能体不能绑。一个人只绑定一个分身，一个智能体只属于一个人。

还没有合适的智能体时，运行 `aidc twin create`。平台在组织的共享池里替你建一个私有的分身，主人是你，并直接绑好。名字缺省是「<你的名字>的分身」，用 `--name` 改。这条命令要组织开通。已经绑了别的智能体当分身时，先运行 `aidc twin unbind`。

已经有分身时再绑一个，新的会换掉原来那个。`aidc twin unbind` 解绑，分身立即不能再用你的电脑。

绑定后，分身能用你名下每一台登记过的电脑，不用一台一台授权。每台电脑上的本机策略再收一道。

分身共享给别人以后，就不能再用你的电脑。平台每次使用时都再判一次。

绑定后，运行 `aidc twin` 查看分身，以及每台电脑它能不能用。● 表示在线，○ 表示不在线。不在线的电脑权限不变，重新在线后分身就能用。

```terminal title="查看分身与电脑"
$ aidc twin
我的数字分身：张三的分身（zhang-san-twin）
我名下的电脑（2 台）：
  ● zhang-san-mbp（demo-zhang-san-mbp-k3f9）：分身 zhang-san-twin 能用：read、write、exec
  ○ zhang-san-pc（demo-zhang-san-pc-7m2q）：分身 zhang-san-twin 能用：read、write、exec
```

## 接上一台 Mac

这一节装好 aidc、登录，并把这台 Mac 接上。

安装脚本不需要 sudo。

```bash
curl -fsSL https://www.ai-dc.ai/developer/cli/install.sh | sh
aidc login
```

只登录 aidc 不会把电脑接上。登录只让这台电脑拿到你账号的 Key。还没接上时，`aidc login` 成功后会提示运行 `aidc node setup`。这样设计是因为登录过的电脑不一定是你的。

`aidc node setup` 的用法：

```bash
aidc node setup [--full --yes | --allow <目录>… --scopes read,write,exec] [--stay-awake] [--name <显示名>]
```

下面这条命令给分身全权，并让插着电的 Mac 不睡：

```bash
aidc node setup --full --yes --stay-awake
```

限定目录时，改用 `--allow <目录>…` 和 `--scopes read,write,exec`，见[选择权限](#选择权限)。各参数的默认值见[参考 · 账号与环境](cli-account.md#aidc-node-setup)。

`aidc node setup` 依次做这几件事：

1. 装 AIDH 运行时。已经装好就跳过。
2. 登记这台电脑。已经登记过就跳过，在用的 Node Key 不变。
3. 设本机策略。只在带了策略参数时才改。
4. 在后台起 worker。
5. 显示分身能不能用这台电脑。

动手之前，它先检查参数和登录。全权没加 `--yes` 时，它只说明风险，不做任何改动。没登录时，它提示先运行 `aidc login`。

同一台电脑重装、重新登记，还是同一条记录。

后台的 worker 只向外连接，电脑不开入站端口。macOS 上它是 LaunchAgent `ai.aidc.cli-node`，你登录这台 Mac 时自动起来。每次运行 `aidc node up`，都先从平台取最新的 worker。

接好以后，运行 `aidc node status` 查看这台电脑的状态。

```terminal title="这台电脑的状态"
$ aidc node status
demo-zhang-san-mbp-k3f9 → https://www.ai-dc.ai（中枢眼里：在线）
worker：在跑
本机策略：全权（与你本人同权：任何文件、经你的 shell 跑任何命令）· read、write、exec · 先问我：不问
睡眠：插着电时不睡（caffeinate -s；用电池、合上盖子照常睡）· aidc node up --allow-sleep 收回
数字分身：张三的分身（zhang-san-twin） · 分身 zhang-san-twin 能用：read、write、exec
```

更新 aidc，运行 `aidc update`。

## 接上一台 Windows 电脑

这一节装好 aidc、登录，并把这台 Windows 电脑接上。

先装 Node.js 18 以上。然后下载单文件 `https://www.ai-dc.ai/developer/cli/aidc.mjs`，用 `node aidc.mjs …` 运行它。

```bash
node aidc.mjs login
node aidc.mjs node setup --full --yes
```

worker 装成计划任务 `ai.aidc.cli-node`，以你自己的身份运行。它不需要管理员权限，也不开窗口。全权时，命令经 PowerShell 运行。

单文件的 aidc 不能用 `aidc update` 更新。要更新，重新下载 `aidc.mjs`。

## 选择权限

这一节决定分身在这台电脑上能做什么。本机策略缺省什么都不许。

### 限定目录（缺省）

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

| 参数 | 做什么 |
| --- | --- |
| `--allow <目录>…` | 分身能使用的目录。不能设成整个家目录或根目录 |
| `--scopes read,write,exec` | 允许的事：读、写、跑命令 |
| `--exec ls,git…\|none` | 允许运行的程序。命令不经 shell，只能跑这里列出的程序 |
| `--ask write,exec\|none` | 先在电脑上弹窗问你的操作，60 秒没点就拒绝。缺省问写文件和跑命令 |

允许的目录之外一律拒绝。软链接指到外面，也拒绝。

「先问我」的弹窗只在 macOS 上有。

### 全权

```bash
aidc node policy --full --yes
```

全权时，分身在这台电脑上与你本人同权：

- 能读写任何文件。
- 命令经你的登录 shell 运行，管道、重定向和任何程序都能用。
- 能做你登录过的 aidc、浏览器、SSH 密钥能做的事。

全权默认不弹窗问你。

> [!IMPORTANT]
> 只在你信任这个分身、它的机器人只对你开放私聊时，才打开全权。

收回全权，运行 `aidc node policy --scoped`。原来允许的目录和程序照旧。

### 两档都适用

节点目录 `~/.aidc/node` 存着 Node Key 和本机策略。任何时候，分身的文件工具都不能碰它。

分身的每一步操作都记在这台电脑上的审计日志里：`~/.aidc/node/logs/device-audit.log`。

## 出门也能用

这一节让插着电的电脑不睡。电脑醒着，分身在你出门时才能用它。

电脑睡着、关机或断网时，分身用不了它。worker 只向外连接，平台没有办法叫醒它。

在 Mac 上，`aidc node setup` 和 `aidc node up` 都能带 `--stay-awake`。它让插着电的 Mac 不睡（`caffeinate -s`）。用电池或合上盖子时，Mac 照常睡。只需设一次，重启后仍然有效。

运行 `aidc node up --allow-sleep` 收回这个设置。运行 `aidc node down` 停 worker 时，这个设置也一起收回。

`aidc node status` 的「睡眠」一行显示这台 Mac 空闲多久睡，以及插电不睡开没开。

在 Windows 上，aidc 不改电源设置。要插电不睡，在 Windows 的电源设置里，把接通电源时的睡眠设成「从不」。

电脑重启以后，你登录一次，worker 才起来。锁屏不影响。

## 分身能做什么

分身用下面 8 个工具操作你的电脑。

| 工具 | 做什么 |
| --- | --- |
| `whoami` | 现查自己是谁的分身、在哪跑、能用哪几台电脑 |
| `list_devices` | 列出你名下的电脑，以及在不在线、能做什么 |
| `list_dir` | 列一个目录，一次最多 500 项 |
| `read_file` | 读文本文件，一次最多 256 KB |
| `write_file` | 写文本文件，最大 1 MB |
| `send_file` | 把电脑上的任何文件发给对方，或拿到分身那边处理。最大 200 MB |
| `put_file` | 把分身那边的文件存到你的电脑上。最大 200 MB |
| `run_command` | 跑命令。缺省 120 秒，最长 200 秒 |

`read_file` 只读文本文件。二进制文件（PDF、图片、Office、压缩包……）用 `send_file`。

在企业微信、钉钉里，20 MB 以内的文件，对方收到的是文件本身。更大的文件，对方收到下载链接。下载链接凭链接就能下载，7 天后打不开。

`put_file` 的上级目录不存在时，会自动建好。

`run_command` 超时，连它起的子进程一起停掉。输出超过 64 KB 时，保留开头和结尾。时间更长的任务，放到后台运行，再看日志。

分身做不到的事：看屏幕、点鼠标、敲键盘。也做不到要人当场输入的交互式命令。例如要输密码的 `sudo`、`vim`，或要按 y 确认的安装程序。能用参数代替交互的命令（比如 `-y`），照常能跑。

## 谁能让分身用电脑

平台每一轮都判断是谁在跟分身说话，再决定能不能用你的电脑。

| 谁在跟分身说话 | 分身能不能用你的电脑 |
| --- | --- |
| 网页工作台、AIDC Desktop、Agent API 的个人 Key、Engine 试运行 | 能用。平台认得出是你 |
| 企业微信、钉钉的私聊 | 缺省能用。平台认不出是谁 |
| 群聊 | 不能用。群里谁都能 @ 它 |
| 平台认得出是别人在跟你的分身说话 | 不能用 |

企业微信、钉钉认不出是谁，所以要让分身的机器人只对你开放私聊。

## 调整与收回

用 `aidc node grant` 和 `aidc node revoke`，一台一台地调整分身能用的电脑。

- `aidc node grant --scopes read`：这台电脑对分身只保留读。
- `aidc node grant --only-me`：只在你本人跟分身说话时，分身才能用这台电脑。
- `aidc node revoke`：这台电脑不给分身用，立即生效。
- `aidc node grant`：不带参数时，恢复缺省的全开。
- `aidc node down`：停 worker。登录这台电脑时，worker 也不会自动起来。

恢复一台被排除的电脑后，在这台电脑上再运行一次 `aidc node up`。

企业微信、钉钉认不出人，所以 `--only-me` 在那里不可用。

## 命令行

下表列出本页涉及的命令。

| 命令 | 做什么 |
| --- | --- |
| [`aidc twin`](cli-account.md#aidc-twin) | 显示你的分身，以及每台电脑它能不能用 |
| [`aidc twin create`](cli-account.md#aidc-twin) | 平台替你建一个数字分身并绑好。要组织开通 |
| [`aidc twin bind <智能体>`](cli-account.md#aidc-twin) | 绑定数字分身。已有分身时，换成新的 |
| [`aidc twin unbind`](cli-account.md#aidc-twin) | 解绑。分身立即不能再用你的电脑 |
| [`aidc node setup`](cli-account.md#aidc-node-setup) | 一条命令接上这台电脑 |
| [`aidc node join`](cli-account.md#aidc-node-join) | 只登记这台电脑，不起 worker |
| [`aidc node policy`](cli-account.md#aidc-node-policy) | 设本机策略 |
| [`aidc node up`](cli-account.md#aidc-node-up) | 起 worker。每次运行都先取最新的 worker |
| [`aidc node down`](cli-account.md#aidc-node-up) | 停 worker |
| [`aidc node status`](cli-account.md#aidc-node-up) | 显示这台电脑的状态 |
| [`aidc node list`](cli-account.md#aidc-node-up) | 列出你名下所有电脑 |
| [`aidc node grant`](cli-account.md#aidc-node-grant) | 调整这台电脑对分身的用法；不带参数则恢复全开 |
| [`aidc node revoke`](cli-account.md#aidc-node-grant) | 这台电脑不给分身用，立即生效 |

每条命令的参数与默认值，见[参考 · 账号与环境](cli-account.md#aidc-node-setup)。

## API

调用下表的端点，可以查看、绑定和设置分身与电脑。

| 方法 | 路径 | 做什么 |
| --- | --- | --- |
| `GET` | `/api/v1/twin` | 查看数字分身，以及名下每台电脑它能不能用 |
| `POST` | `/api/v1/twin` | 建数字分身并绑好（`aidc twin create` 用它） |
| `PUT` | `/api/v1/twin` | 绑定数字分身。一个人一个，换绑即换掉原来那个 |
| `DELETE` | `/api/v1/twin` | 解绑 |
| `GET` | `/api/v1/devices` | 查看名下的电脑：在不在线，分身能不能用 |
| `POST` | `/api/v1/devices` | 登记这台电脑（`aidc node join` 用它） |
| `POST` | `/api/v1/devices/grants` | 调整这台电脑对分身的用法：收窄、只在本人说话时可用，或恢复 |
| `POST` | `/api/v1/devices/grants/revoke` | 这台电脑不给分身用 |
| `POST` | `/api/v1/devices/mcp` | 设备 MCP，智能体那一侧的工具（只认平台发给智能体的设备令牌） |

绑定、登记和单台设置只认账号的开发者 Key（`aidc-dk-…`）。Key 所属的账号要是 developer 或 member。

## 限制

这一节列出分身各项操作的上限。

| 项目 | 上限 |
| --- | --- |
| 列目录 | 500 项 |
| 读文本 | 256 KB |
| 写文本 | 1 MB |
| 收发文件 | 200 MB |
| 企业微信、钉钉里直接收到的文件 | 20 MB |
| 单条命令 | 缺省 120 秒，最长 200 秒 |
| 命令输出 | 64 KB，超过时留开头和结尾 |
| 下载链接 | 7 天 |
| 支持的电脑 | macOS（Apple 芯片）、Windows x64 |

Linux 和 Intel 芯片的 Mac 都不支持。它们没有 AIDH 运行时。

## 常见错误

遇到下表的现象，按「怎么办」处理。

| 现象 | 原因 | 怎么办 |
| --- | --- | --- |
| `aidc twin` 里电脑显示 `○` | 电脑睡着、关机、断网，或 worker 没在跑 | 叫醒或打开电脑；在那台电脑上运行 `aidc node up` |
| `aidc node up` 报 `worker_not_ready`，最近的错误是 401 | 这台电脑在别处重新登记过，这里的 Node Key 失效了 | 运行 `aidc node join`，再运行 `aidc node up` |
| `aidc node setup` 报 `unsupported_platform` | 这台电脑是 Linux 或 Intel 芯片的 Mac | 换一台 macOS（Apple 芯片）或 Windows x64 的电脑 |
| `aidc node join` 报「先装 AIDH」 | 本机还没有 AIDH 运行时 | 运行 `aidc aidh install`，或直接用 `aidc node setup` |
| 分身在群聊里说不能用电脑 | 群聊里分身不动你的电脑 | 改在私聊里跟它说 |
| 设了 `--only-me` 后，企业微信里分身用不了这台电脑 | 企业微信认不出是你 | 运行 `aidc node grant` 恢复缺省，或在网页工作台里跟分身说 |
| 下载链接打开时说「已经失效」 | 链接发出超过 7 天 | 让分身再发一次 |

## 下一步

- [参考 · 账号与环境](cli-account.md#aidc-node-setup)：每条命令的参数与默认值
- [智能体接入](agents.md)：智能体怎么登录、拿凭证、调工具
- [安装 aidc](cli.md#安装)：安装脚本与本机要求