# 交互界面

在终端里敲 `aidc`，进入交互界面，和智能体对话。界面管输入和显示，干活的是运行时。对话留在终端自己的滚动历史里，你可以用终端原生的滚动、选择和复制。

<!-- demo:aidc-chat -->

这段录屏演示一轮对话：进入 `aidc`，输入一句话，智能体先列出计划。执行命令前，界面请你确认；确认后，智能体给出结果。

> [!NOTE]
> 前提：已安装 aidc，见 [CLI 概览](cli.md#安装)。没登录时，界面先请你登录。要让智能体在本机干活，需要装 AIDH、Codex 或 Pi 之一。三个都不能用时，界面用 Engine，只聊天，不动本机。

## 进入交互界面

在终端里敲 `aidc` 或 `aidc chat`。stdin 和 stdout 都是终端时，才会进界面。

```bash
aidc                                          # 进入交互界面
aidc chat "看看这个仓库的结构"                  # 进来先发这一句
aidc chat --runtime codex --model <模型>       # 指定运行时和模型
aidc chat --continue                          # 续上这个目录里最近一次的对话
aidc chat --resume [会话 id]                   # 续上指定的对话，不带 id 时打开列表
```

| 参数 | 说明 |
| --- | --- |
| `"开场的一句"` | 进入界面后先发这一句 |
| `--runtime <运行时>` | `aidh`、`codex`、`pi`、`engine`、`agent` 或 `acp`。没写就用上次用的 |
| `--profile <档案>` | AIDH 的档案 |
| `--model <模型>` | 这次启动用的模型。在界面里用 `/model` 换的模型才记进配置，下次沿用 |
| `--continue` | 续上这个目录里、这个运行时最近一次的对话。没有就开新对话 |
| `--resume [会话 id]` | 续上指定的对话。不带 id 时，运行时支持续会话、又有可续的对话，才打开列表；否则只说明原因 |
| `--cwd <目录>` | 工作目录，缺省是当前目录 |

不在终端里时，`aidc` 打印帮助。`aidc chat` 以退出码 2 结束，并提示改用[不进界面：aidc chat -p](#不进界面aidc-chat--p)。

首屏左边是 AIDC 标志，右边是这些信息：

```text
 AIDC CLI 1.77.0

 账号    zhang.san · Demo Company（cell-demo） · developer
 运行时  AIDH
 目录    ~/old-portal

 / 命令 · @ 文件 · ↑ 历史 · esc 中断 · ? 快捷键
```

没登录时，账号一行写「未登录」，界面先显示登录面板。输入账号和密码，或按 `ctrl+b` 在浏览器里批准。登录之后，界面才连运行时。在账号和密码的表单里按 `esc` 退出，退出码是 3。在选组织、等浏览器批准的面板里按 `esc`，回到表单。

首屏下面是输入框。屏幕底部的活动区有这些部分：正在生成的回答、计划、状态行、输入框和状态栏。状态栏左边是运行时、模型、目录和上下文用量，右边是一句提示：

```text
 Engine · deepseek-flash · ~/old-portal                      ? 快捷键
```

对话里的标记：

| 标记 | 意思 |
| --- | --- |
| `› 你的话` | 你发出的话 |
| `● 回答` | 智能体的回答 |
| `✓ 执行 ls -la · 0.2s` | 工具卡片：状态、动作、对象、用时。下面是输出的末尾几行或改动摘要 |
| `✓`、`✗`、`○` | 工具完成、失败、还没开始 |
| `计划 1/3` | 智能体的计划。`✓` 完成，`▸` 进行中，`○` 还没做 |
| `∴ 思考 · 2.1s` | 思考过程。缺省只留一行 |
| `// 生成中 · 3.2s · esc 中断` | 状态行：在做什么、用时、怎么中断。斜杠闪动说明还在进行 |
| `2.4s · 输入 1.2k · 输出 340` | 每轮结束后的一行：用时和 token 数 |

这次说过话时，退出界面会打印续上这次对话的命令：

```text
续上这次对话：aidc chat --runtime aidh --resume <会话 id>
```

Engine 的对话只存在内存里，不能续上，所以 Engine 不打印这一行。ACP 智能体也不打印。

## 选运行时

运行时是真正干活的智能体，界面只管你怎么看、怎么说。`/runtime` 随时换，`aidc runtimes` 看本机能用哪些。

| 运行时 | `--runtime` | 是什么 | 需要 |
| --- | --- | --- | --- |
| AIDH | `aidh` | 本机的 Harness 引擎，经 ACP 对话。能读写文件、跑命令，有风险的操作先问你 | 先用 `aidc aidh install` 装的引擎（或本机 Adis 装的那份），再找 `aidh`、`hermes` 命令。`AIDC_AIDH_COMMAND` 可以整体替换 |
| Codex | `codex` | OpenAI Codex，经 `codex app-server`。在沙箱里干活，越界时先问你 | 本机有 `codex`，并运行过 `codex login` |
| Pi | `pi` | Pi coding agent，经 `pi --mode rpc`。不弹确认 | 本机有 `pi`，并配置了模型 |
| Engine | `engine` | AIDC 模型（`/api/v1/models`）。只聊天，不动本机，用量记在登录的组织 | 登录 |
| 数字员工 | `agent` | 云端的数字员工（Agent API）。工具和会话都在云端 | 环境变量 `AIDC_AGENT_KEY` |

ACP 是 Agent Client Protocol，智能体和客户端之间的协议。

没写 `--runtime` 时，界面用上次用的运行时。上次的不能用，就按 AIDH、Codex、Pi、Engine 的顺序取第一个能用的。

```terminal title="查看运行时"
$ aidc runtimes
○ aidh    AIDH —— 本机 Harness 引擎 · ACP；本机没有 AIDH（aidh 命令）
● codex   Codex（缺省） —— OpenAI · app-server
○ pi      Pi —— Pi · RPC；本机没有 pi
● engine  Engine —— AIDC 模型 · 只聊天，不动本机
○ agent   数字员工 —— 云端智能体 · Agent API；需要 AIDC_AGENT_KEY
```

`aidc runtimes` 要先登录。`●` 表示能用，`○` 表示不能用，行尾写缺什么。「（缺省）」标出现在默认的运行时。`--json` 输出 `{"runtimes": […], "default": "…"}`。

运行时起不来时，界面说明原因和下一步，并打开运行时列表让你换一个。用 `--runtime acp` 时不打开列表。装 Codex：`npm install -g @openai/codex`，然后运行 `codex login`。装 Pi：`npm install -g @earendil-works/pi-coding-agent`，再配置一个模型。

装 AIDH：照 [Harness](/products/harness) 页的一行命令把这台电脑接进组织。macOS 和 Linux 用 `curl -fsSL https://ai-dc.ai/install.sh | bash -s -- --join <公司码> --name <姓名>`，Windows 用 PowerShell 的 `install.ps1`。aidc 在 `PATH` 里找 `aidh` 命令。找不到时，用 `AIDC_AIDH_COMMAND` 指定完整路径。

用环境变量指定运行时的程序和凭证：

| 变量 | 作用 |
| --- | --- |
| `AIDC_AIDH_COMMAND` | 整体替换 AIDH 的启动命令 |
| `AIDC_CODEX_COMMAND` | Codex 程序的路径 |
| `AIDC_PI_COMMAND` | Pi 程序的路径 |
| `AIDC_AGENT_KEY` | Agent Key（`aidc-sk-…`）。在 Console 的智能体页或 Adis 里获取 |
| `AIDC_AGENT_API` | Agent API 地址，缺省 `https://api.ai-dc.ai/v1` |

AIDH 的档案用 `--profile <名字>` 或 `/profile` 选。档案有两种：引擎自己的命名档案，和这台电脑上开出来的数字员工，名字形如 `cell-demo/ops-agent`。`/profile default` 用默认档案。

数字员工运行时里，`/model` 选的是数字员工：一把 Agent Key 可以对应几个。换一个就开新对话。

接入别的智能体：

```bash
aidc chat --runtime acp -- <命令…>
```

这条命令接任何实现了 ACP 的智能体，例如 `gemini --experimental-acp`。`--` 之后是启动智能体的命令。aidc 不把本机文件和终端借给智能体。智能体用自己的工具干活，有风险的操作经 ACP 问你。ACP 智能体不出现在 `/runtime` 列表里。

## 输入

在输入框里写话，按 `⏎` 发送。

- 换行：按 `⌥⏎`、`⇧⏎` 或 `ctrl+j`，或者在行尾写 `\` 再按 `⏎`。
- 命令：输入 `/` 列出命令，边打边筛，最多列 8 条。
- 文件：输入 `@` 列出工作目录里的文件和目录，目录排在前面。发送的是路径文字，由智能体去读文件。
- 粘贴：超过 8 行或 1,500 字的粘贴，折叠成 `[粘贴 #1 · 120 行]`。发送时展开成原文。折叠的占位整块移动、整块删除。
- 排队：回答进行中，或界面还在连接运行时，你也能打字。发出的话排在这一轮之后，输入框上方显示「↳ 排队」。
- 历史：在输入框的第一行按 `↑`，翻出之前发过的话。按 `↓` 翻回来，回到最底下时还原你正在写的话。
- 原样发送：以 `//` 开头的话不当命令，原样发给智能体。

`@` 不列出 `node_modules` 和 `.git`。隐藏文件要先输入 `.`，才会出现。

## 快捷键

输入框为空时，按 `?` 打开快捷键小面板，按任意键关闭。`/help` 把全部快捷键和命令打进对话记录。

| 键 | 作用 |
| --- | --- |
| `⏎` | 发送 |
| `⌥⏎`、`⇧⏎`、`ctrl+j` | 换行。`⇧⏎` 只在支持 kitty 键盘协议的终端里能和 `⏎` 区分 |
| `esc` | 回答进行中：中断。有补全或列表：关掉它。输入框有字：连按两次清空 |
| `ctrl+c` | 有输入时清空。没有输入、回答进行中时中断。空闲时，2 秒内连按两次退出 |
| `ctrl+d` | 输入为空时退出。有输入时删光标后的一个字 |
| `↑`、`↓` | 多行输入里上下移动。到头时翻历史 |
| `tab` | 补全命令和文件 |
| `ctrl+a`、`ctrl+e` | 移到行首、行尾 |
| `ctrl+b`、`ctrl+f` | 左移、右移一个字 |
| `⌥←`、`⌥→`、`⌥b`、`⌥f` | 按词左移、右移 |
| `ctrl+w`、`⌥d` | 删前一个词、删后一个词 |
| `ctrl+u`、`ctrl+k`、`ctrl+y` | 删到行首、删到行尾、粘回刚删的 |
| `ctrl+_` | 撤销 |
| `ctrl+l` | 清屏。对话仍在终端的滚动历史里 |
| `ctrl+z` | 挂起，用 `fg` 回来。Windows 不支持 |

## 斜杠命令

输入 `/` 出补全列表。用 `↑`、`↓` 选择命令。按 `tab` 补全。按 `⏎` 补全并执行。参数可选的命令，按 `⏎` 就执行。参数必填的命令只补全，等你写参数。

| 命令 | 做什么 |
| --- | --- |
| `/help`、`/?` | 命令和快捷键全表。打进对话记录，能滚动回看 |
| `/new` | 开一个新对话 |
| `/clear` | 清屏，并开一个新对话 |
| `/resume` | 续上之前的对话。运行时支持续会话、又有可续的对话时，打开对话列表 |
| `/runtime [运行时]` | 换运行时。不带参数打开列表 |
| `/model [模型]` | 换模型。不带参数打开列表 |
| `/profile [档案]` | 换 AIDH 的档案。`/profile default` 用默认档案 |
| `/status` | 账号、运行时、会话、目录、用量和版本 |
| `/copy` | 复制上一条回答 |
| `/thinking` | 展开或收起思考过程 |
| `/theme [模式]` | 模式是 `auto`、`light` 或 `dark`。不带参数在浅色和深色之间切换 |
| `/login` | 换账号或组织 |
| `/logout` | 退出登录 |
| `/exit`、`/quit`、`/q` | 退出 |

运行时自己的命令接在这些命令后面，`/help` 里标出运行时的名字。AIDH 在回答进行中支持 `/steer`（把话插进这一轮）和 `/queue`（排到下一轮）。

`/runtime`、`/model`、`/profile`、`/resume` 不带参数时，打开一个列表：

- `↑`、`↓` 或 `tab` 移动，`⏎` 确定，`esc` 取消。
- `●` 标出正在用的一项。
- 长列表可以直接打字筛选。
- 不能用的运行时是灰色的。选它时，界面说明缺什么。

回答进行中，不能换运行时和档案，也不能开新对话、续对话、登录或退出登录。界面提示「这一轮还没结束：先 esc 中断」。不认识的命令提示「没有 /xxx 这个命令」。

## 确认操作

智能体要执行命令、改文件、联网等有风险的操作时，输入框的位置换成确认面板，并响一声：

```text
╭─ 需要你确认 ───────────────────────────────╮
│ AIDH 要执行命令                            │
│   npm test                                 │
│                                            │
│ › 1. 允许这一次                            │
│   2. 本会话都允许                          │
│   3. 拒绝                                  │
╰────────────────────────────────────────────╯
  ↑↓ 选择 · ⏎ 确认 · 数字直接选 · esc 拒绝
```

第一行写运行时和它要做的事。事有五种：执行命令、修改文件、删除文件、访问网络和用工具。下面是命令、路径或查询词。

- 选择：按 `1` 到 `9` 直接选，或用 `↑`、`↓`（`tab` 也行）移动，再按 `⏎`。
- 拒绝：按 `esc` 或 `ctrl+c`。
- 选项：由运行时给出。界面把名字换成中文：允许这一次、本会话都允许、总是允许、拒绝、总是拒绝。
- 排队：同时来几个确认，一个一个问，先来的先问。
- 收尾：回答被中断或界面退出时，没回答的确认按拒绝处理。

> [!IMPORTANT]
> 光标默认停在「允许这一次」。按 `⏎` 之前，先读清楚命令或路径。

AIDH 和 Codex 会请你确认。Pi 的设计是不弹确认，aidc 不另加。Engine 只聊天，数字员工的工具在云端跑，所以这两个运行时没有确认面板。

`aidc chat -p` 里没人可问：aidc 缺省拒绝，拒绝的操作记进结果的 `denied`。加 `--yes` 就自动选「允许这一次」。

> [!WARNING]
> `--yes` 允许智能体做它要求的所有事。只在你信任这个目录和这个任务时使用。

## 不进界面：aidc chat -p

`aidc chat -p` 不进界面，跑一轮就退出。脚本和智能体用它。

`-p` 后面写提示。stdout 是终端时，回答边生成边打出来。每个新工具另起一行，以 `· ` 开头，打到 stderr：

```terminal title="跑一轮看答案"
$ aidc chat -p "总结一下 README.md 的安装步骤" --runtime codex
· sed -n 1,80p README.md
README.md 的安装步骤有三步：安装依赖、复制 .env.example、运行 npm run dev。
```

stdout 不是终端，或者加了 `--json` 时，aidc 在结束时输出一个 JSON 对象：

```terminal title="输出 JSON"
$ aidc chat -p "用一句话说明 Action 是什么" --runtime engine --json
{
  "runtime": "engine",
  "model": "deepseek-flash",
  "sessionId": "5b1f0c1e-7d3a-4a52-9c43-1f0e2a8b6d90",
  "text": "Action 是 Semantic 里改数据的唯一方式：每次执行都带参数校验、权限检查和留痕。",
  "stopReason": "end_turn",
  "usage": {
    "inputTokens": 24,
    "outputTokens": 61
  },
  "tools": [],
  "denied": []
}
```

JSON 的字段：

| 字段 | 含义 |
| --- | --- |
| `runtime` | 用的运行时：`aidh`、`codex`、`pi`、`engine`、`agent` 或 `acp` |
| `model` | 运行时报告的模型名。指定了 AIDH 档案时，前面带档案名 |
| `sessionId` | 会话 id。用 `--resume <会话 id>` 续上。Engine 不能续 |
| `text` | 完整的回答 |
| `stopReason` | `end_turn`、`cancelled`、`max_tokens`、`refusal` 或 `error` |
| `error` | 只在 `stopReason` 是 `error` 时出现，写原因 |
| `usage` | 用量。有哪些字段，看运行时报告了什么 |
| `tools` | 这一轮用过的工具，每项有 `title`、`kind`、`status`、`input` |
| `denied` | 被拒绝的操作，每项一行摘要。加了 `--yes` 时是空的 |

`usage` 可能有这些字段：`inputTokens`、`outputTokens`、`reasoningTokens`、`cachedTokens`、`contextUsed`、`contextSize` 和 `costUsd`。`tools` 里的 `kind` 是 `read`、`edit`、`delete`、`move`、`search`、`execute`、`think`、`fetch` 或 `other`。`status` 是 `pending`、`running`、`done` 或 `failed`。

规则：

- `-p` 要先登录。没登录时，退出码是 3。
- 续上对话：`--continue` 续上交互界面在这个目录、这个运行时保存的最近一次对话（`-p` 跑的对话不记进去）。`--resume <会话 id>` 续指定的对话。`-p` 里的 `--resume` 必须带 id。
- 没人确认：缺省拒绝，见[确认操作](#确认操作)。
- 退出码 0 不等于回答完整。检查 `stopReason`：`max_tokens` 表示被截断，`refusal` 表示模型拒绝回答。
- 运行时出错时，`stopReason` 是 `error`，退出码是 8。回答被中断时，退出码是 130。
- 运行时起不来（例如没装）时，退出码是 1，错误里带安装提示。
- 没有提示文字，stdin 又是终端时，退出码是 2。

退出码的完整含义见 [CLI 概览](cli.md#退出码)。

提示也可以从 stdin 传入。不写提示文字时，aidc 把 stdin 当作提示。写了提示文字，aidc 就不读 stdin。要给内容加上要求，先把两者拼在一起，再送进 stdin：

```bash
git diff | aidc chat -p                                                      # stdin 就是提示
(echo "帮我写提交说明："; git diff) | aidc chat -p --json | jq -r .text         # 先写要求，再接内容
```

## 终端与外观

界面在终端里直接画，不切换到备用屏幕，也不抓鼠标。所以滚动、选择和复制都用终端自己的功能。

主题（浅色或深色）按这个顺序决定：

1. `/theme light` 或 `/theme dark`：记进配置，优先级最高。`/theme auto` 取消固定。
2. 环境变量 `AIDC_THEME=light` 或 `AIDC_THEME=dark`。
3. 终端报告的背景色。
4. 环境变量 `COLORFGBG`。
5. 都没有时，macOS 自带终端用浅色，其他终端用深色。

其他设置：

| 设置 | 作用 |
| --- | --- |
| `NO_COLOR` | 设成任何非空值，关闭颜色 |
| `FORCE_COLOR` | `0` 关闭，`1` 16 色，`2` 256 色，`3` 真彩色 |
| `AIDC_REDUCED_MOTION=1` | 关闭加载动效，斜杠不再闪动 |
| `AIDC_HYPERLINKS` | `1` 强制开可点击链接，`0` 强制关 |
| `AIDC_CONFIG_DIR` | 换配置目录，缺省 `~/.aidc` |

没设 `FORCE_COLOR` 时，界面按 `COLORTERM`、`TERM_PROGRAM` 和 `TERM` 判断终端的颜色能力。可点击链接缺省只在已知支持的终端里开。这些终端是 iTerm2、WezTerm、VS Code、Ghostty、Windows Terminal 和 kitty。

中日韩文字和 emoji 占两格，组合符号占零格。输入框里放着真光标，所以中文输入法的候选框跟着输入框里的光标走。窗口大小变了，界面按新宽度重画。更早的内容留在终端的滚动历史里。

选择记在 `~/.aidc/config.json` 的 `tui` 里。里面有运行时、AIDH 档案、每个运行时的模型、配色、思考过程是否展开和最近的对话。退出登录不清它。输入历史在 `~/.aidc/history`，权限是 0600，启动时读最近 500 条。

## 下一步

- [CLI 概览](cli.md)：安装、登录、输出和退出码。
- [常用流程](cli-recipes.md)：按任务写好的完整步骤。
- [智能体接入](agents.md)：让智能体开发、测试、发布应用。
- [参考 · 账号与环境](cli-account.md)：登录、个人工作台、更新。
- [参考 · 模型与感知](cli-ai.md)：`aidc model chat` 等调模型的命令。