# 助手 (/zh/docs/ai/assistant)

助手是内置在 Echolot 中的 AI 智能体。你用平常的话提问（“Create order 为什么失败？”“为这个请求编写检查”），它通过外部智能体所用的同一套工具处理你的工作区：
列出和读取请求、发送请求、读取响应、编写检查、编辑规范、启动模拟服务器并运行流程。它的每次调用都会实时显示在面板中，
任何可能更改数据的操作都会先询问你。

<Shot id="ai-assistant-panel" alt="停靠在请求页面右侧的助手面板，其中有一个问题、助手进行的工具调用以及它的回答" />

## 打开助手 [#open-the-assistant]

助手是停靠在每个页面右侧的面板。可以用以下任一方式打开或关闭：

- <kbd>⌘</kbd><kbd>J</kbd>
- **视图 › 显示助手**（或**隐藏助手**）
- 魔棒按钮，即页面标题栏中的最后一个按钮

每个窗口都有自己的助手，处理该窗口的工作区。

要加宽面板，请将其左边缘向左拖移；它会占用页面的空间，直到页面的最小宽度。向右拖移可以变窄，双击边缘则恢复为通常的宽度。

## 选取模型提供商 [#choose-a-model-provider]

第一次打开面板时，它会显示**选取模型**。选取**打开助手设置…**，或打开**设置 › 助手**，然后在**添加提供商**下添加提供商：

| 提供商 | 需要输入 | 备注 |
| --- | --- | --- |
| **Anthropic** | **API 密钥** | Claude 模型。每个账户都有一个**推理强度**设置：**模型默认值**、`low`、`medium`、`high`、`xhigh` 或 `max`。 |
| **OpenAI** | **API 密钥** | |
| **Google Gemini** | **API 密钥** | |
| **OpenAI 兼容** | **地址**，以及**API 密钥（可选）** | 任何支持 OpenAI Chat Completions API 的服务器：Ollama、LM Studio、OpenRouter 等。除非你输入其他地址，否则地址为 `http://127.0.0.1:11434/v1`（这台 Mac 上的 Ollama）。 |
| **CLI 智能体（ACP）** | **智能体**和**命令** | 你 Mac 上支持 Agent Client Protocol 的编码智能体。仅限直接下载版，见下文。 |

选取**添加**。Echolot 会载入该提供商的模型并选取第一个；可在账户的**模型**菜单中选取其他模型，或选取**载入模型**重新获取列表。
如果提供商没有列出模型，请在**模型**栏中输入模型的名称。

要免费且离线地试用助手，可以在 [Ollama](https://ollama.com) 中运行一个模型，并将它作为**OpenAI 兼容**提供商，使用默认地址添加。

### 密钥保存在钥匙串中 [#keys-stay-in-the-keychain]

API 密钥存储在这台 Mac 的登录钥匙串中，绝不会进入工作区，并且只会发送到提供商自己的地址。账户旁的**移除…** 会从钥匙串中删除它的密钥。

### 在提供商之间切换 [#switch-between-providers]

有多个提供商时，**设置 › 助手 › 提供商**中打勾的那个就是助手使用的提供商。也可以在面板中切换：面板标题栏中的模型菜单会以*提供商 · 模型*的形式列出每个账户，
其底部的**助手设置…** 会打开设置。

### 本地编码智能体（CLI 智能体） [#local-coding-agents-cli-agent]

<Edition only="direct">
  本地 CLI 智能体仅限直接下载版：App Store 版无法启动安装在你 Mac 上的程序。在那里请使用 API 密钥、Ollama 或其他 OpenAI 兼容服务器。
</Edition>

CLI 智能体自带模型和登录。Echolot 在工作区文件夹中启动它，并通过 Echolot 的 MCP 服务器将工作区提供给它，所以请先开启**设置 › 智能体 › 允许智能体使用打开的工作区**
（参见[外部智能体](/docs/ai/agents)）。将**CLI 智能体（ACP）** 选为提供商，然后选取一个**智能体**：

| 智能体 | 命令 | 需要 |
| --- | --- | --- |
| **Claude Code** | `npx -y @zed-industries/claude-code-acp` | Node.js；使用你的 Claude 订阅或 `ANTHROPIC_API_KEY` |
| **Codex** | `npx -y @zed-industries/codex-acp` | Node.js；使用你的 ChatGPT 登录或 `OPENAI_API_KEY` |
| **Gemini CLI** | `gemini --experimental-acp` | 已安装 Gemini CLI |
| **其他** | 你输入的命令 | 任何通过标准输入输出支持 ACP 的智能体 |

之后可以在账户的**命令**栏中更改命令。每个对话都有自己的智能体进程，关闭窗口时它会结束。智能体自己的权限请求也会询问你。

## 一次性许可 [#the-one-time-permission]

在向某个提供商发送第一条消息之前，Echolot 会询问：**要发送到 *提供商* 吗？** 问题会说明将发送什么（你的消息、助手读取的工作区数据及其工具结果）、发送到哪里，
以及机密值绝不会被发送。**取消**是默认按钮，所以按 <kbd>↩</kbd> 绝不会意外发送；选取**允许**才会继续。

Echolot 对每个提供商只询问一次：Anthropic 一次、OpenAI 一次、Gemini 一次、每个 OpenAI 兼容服务器（按主机）一次，每个 CLI 智能体一次。
这台 Mac 上的服务器（`localhost`、`127.0.0.1`、`::1`）从不询问，因为没有任何内容离开这台 Mac。而你网络上其他位置的服务器会询问。

**设置 › 助手 › 允许接收你的数据**列出你允许过的每个提供商。**撤销许可**会收回许可；下一条消息会再次询问。

## 提问 [#ask]

在面板底部的**询问助手…** 中输入。<kbd>↩</kbd> 发送，<kbd>⇧</kbd><kbd>↩</kbd> 换行，助手工作时按 <kbd>⌘</kbd><kbd>.</kbd> 可以让它停止。

新对话会针对你所在的页面给出建议。点按其中一条，即可将它放入文本栏：

| 页面 | 建议 |
| --- | --- |
| 请求 | **发送此工作区中的每个请求，并告诉我哪些失败。** · **打开的请求为什么失败？看看它的上一个响应。** · **根据打开的请求的最新响应为它编写检查。** · **获取此列表的所有页面，并将条目存储为 CSV。** |
| MCP 服务器 | **检查此 MCP 服务器并总结它提供的内容。** · **调用此服务器的每个只读工具一次，并报告返回的内容。** |
| 规范 | **修复此规范中 Lint 报告的问题。** · **将此工作区中的请求编写为 OpenAPI 规范文档。** |
| 模拟服务器 | **启动此规范的模拟服务器，并将一个新环境指向它。** · **将最新的真实响应作为示例存储到规范中。** |
| 流程 | **构建一个登录并导出列表每一页的流程。** · **此流程上次运行为什么失败？** |

### 你打开的内容会一并发送 [#what-you-have-open-goes-along]

文本栏上方的标签显示你打开了什么：打开的请求、测试页面及其失败的检查、运行器的上一次运行、打开的规范、模拟服务器、流程或 MCP 服务器。
每个标签都会随你的消息一起发送，所以你可以说“这个请求”或“上一次运行”。点按某个标签，下一条消息就不再带上它；再次点按则恢复。
将鼠标悬停在标签上，可以看到模型收到的那句话。

### 助手能做什么 [#what-the-assistant-can-do]

助手拥有[外部智能体](/docs/ai/agents#toolsets)可以获得的每一组工具，无论设置 › 智能体中开启了什么：请求和响应、运行带检查的文件夹、历史记录、环境、
工作区的文件夹和变量、规范、模拟服务器、MCP 服务器和流程。批准仍然适用于其中每一项。

它从不获得更改智能体策略、代理、证书、工作区认证或脚本的工具。

每次工具调用都会在对话中显示为一张卡片，包含其输入和结果，以及它正在运行、已完成还是失败。文本栏下方的一行显示目前已用的令牌数，
在模型的价格已知时，还会显示大约的费用。

## 批准更改 [#approve-what-changes]

当助手想要执行策略要求询问的操作时，窗口中会出现一个表单：***智能体*想要发送可能更改数据的请求**，并显示调用以及请求发出时的样子，机密值已被遮盖。

<Shot id="ai-assistant-approval" alt="批准表单：智能体想要发送可能更改数据的请求，其中有它将发送的 POST 请求，以及“拒绝”“在本次会话中允许”和“允许一次”按钮" />

- **允许一次**运行这次调用。
- **在本次会话中允许**运行这次调用以及与它类似的调用，在窗口关闭之前无需询问：对工作区的每一项更改（无论由哪个工具进行：先创建请求，再存储文件夹的认证，再创建环境），
  以及对同一主机使用相同方法的发送（对 `demo.echolot.dev` 的每个 GET）。删除仍会询问，受保护的环境、新主机以及比普通更改范围更窄的内容（例如流程的某个版本）也一样；
  对于这些，它只涵盖同样的那次调用。表单会说明它涵盖什么。
- **在更改和发送前不再询问**是表单上的一个复选框，适用于更改，以及更改数据的发送。勾选它再允许，会开启下文的**设置 › 助手 › 询问时机**。
  删除、新主机或受保护的环境不提供它。
- **拒绝**会拒绝该操作，并告知助手。

对于发送到新主机、发送到受保护的环境以及删除，**允许一次**不是默认按钮，所以 <kbd>↩</kbd> 无法批准它们。五分钟内无人回答的问题会被拒绝。有多个调用在等待时，
表单会说明还有多少个。

询问什么取决于工作区的智能体规则。没有任何规则时，情况如下：

| 助手的操作 | 没有工作区规则时 |
| --- | --- |
| 读取请求和环境 | 运行 |
| 安全的发送（GET、GraphQL 查询、MCP 读取） | 运行 |
| 其他发送（POST、PUT、PATCH、DELETE、文件正文） | 询问 |
| 发送到受保护的环境 | 始终询问 |
| 发送到新主机（工作区中没有请求或环境使用它们） | 始终询问 |
| 对工作区的更改 | 询问 |
| 删除（项目会移到废纸篓） | 询问 |

### 减少询问 [#ask-less]

**设置 › 助手 › 询问时机 › 仅在删除、新主机和受保护的环境之前询问**会停止关于发送和更改的询问：助手创建请求、环境、规范、模拟服务器和流程，
并发送 POST、PUT 和 DELETE 请求，而无需询问。每次调用仍会显示在对话中。移到废纸篓、助手启动时工作区未使用过的主机和受保护的环境仍会询问，
运行未提供给智能体的流程也一样。它在你开启之前是关闭的，并且只涵盖助手；外部智能体遵循工作区的规则。

要放宽或收紧这些规则，或者限制主机和发送，请使用**工作区设置 › 智能体**：参见[智能体的工作区规则](/docs/ai/agents#workspace-rules)。
同样的规则也适用于外部智能体。如果那里的**智能体可以使用此工作区**已关闭，助手也会拒绝在该工作区中工作。

### 受保护的环境 [#protected-environments]

[受保护的环境](/docs/workspaces/protected-environments)处于活动状态时，助手的每次发送都会先询问，无论方法是什么，也无论规则怎么说。
选取**在本次会话中允许**只涵盖同样的那次调用。

## 模型永远看不到的内容 [#what-the-model-never-sees]

- **机密值。** Echolot 在任何内容发送给模型之前，都会替换每个机密变量的值，包括消息、工具结果和错误。模型只能按名称看到机密。
- **你自己的模式。** **设置 › 助手 › 对模型隐藏**每行接受一个正则表达式。工具返回的内容中，所有匹配的部分在模型看到之前都会被替换为 `[hidden]`。
  可用于不属于机密变量的数据，例如客户 ID 或电子邮件地址。不是有效正则表达式的行会以红色显示，并被忽略。
- **完整的响应正文。** 响应以摘要的形式送达模型（状态、标头、耗时、大纲、正文的前几个字节、检查结果），并附带一个句柄；
  它通过该句柄、JSONPath 或搜索，一次读取正文的更多内容。

要确切看到随你的下一条消息发送的内容，请点按面板标题栏中的眼睛按钮，即**模型看到的内容**。它会显示指令、工具、对话和上下文，并附有令牌数的估计值。

## 保留对话 [#keep-a-conversation]

对话保存在这台 Mac 上，按工作区区分。在面板的标题栏中：

- **新建对话**（铅笔）开始一个新对话。
- **之前的对话**（时钟）列出**在这台 Mac 上**的对话和**已在此工作区中共享**的对话。点按其中一个即可打开。
- 保留菜单（带箭头的托盘）可以将对话变成持久的内容：

| 命令 | 作用 |
| --- | --- |
| **存储为测试** | 创建一个名为*助手 · 对话标题*的文件夹，助手的每次发送对应一个请求，按顺序编号，每个请求都带有对它得到的状态的检查。 |
| **存储为流程** | 同样的文件夹，外加一个依次发送这些请求的流程。 |
| **在工作区中共享** | 将对话以 Markdown 记录和一份记录文件的形式存储在工作区的 `assistant/` 文件夹中，机密已被替换，队友通过 Git 拉取后即可阅读，并从**已在此工作区中共享**中打开。 |
| **重放调用** | 不使用模型，按顺序再次运行对话中的工具调用，并将结果显示为新的对话。批准与任何调用一样适用。 |

对话发送过请求之后，**存储为测试**和**存储为流程**才可用。

## 这台 Mac 上的 Apple 智能 [#apple-intelligence-on-this-mac]

在已开启 Apple 智能的 macOS 26 上，Echolot 还会使用 Apple 的设备端模型处理小任务，这些任务从不离开这台 Mac，也不需要提供商或许可：

- 响应窗格中的 Apple 智能菜单：**总结响应**、**解释错误**（用于错误响应）、**建议检查**（带一个按钮，用来添加 Echolot 可以运行的检查）和**建议名称**（带一个按钮，用来重新命名请求）。
- 失败的流程运行上的**解释失败原因**，以及正在运行的模拟服务器日志上的**总结日志**。
- [Echo 的评论](/docs/ai/echo#ai-comments)，在你开启之后。

每个回答都会注明**已在此 Mac 上作答；没有发送任何内容。** 模型不可用时，这些按钮不会显示。助手面板本身始终使用设置 › 助手中的提供商。

## 用模型试用服务器的工具 [#try-a-servers-tools-with-a-model]

在 [MCP 服务器](/docs/mcp-servers/tools-and-quality)页面上，**用模型试试**卡片会显示模型会选择服务器的哪些工具。在**有人会让智能体用此服务器做什么？** 中输入某人可能让智能体做的事，然后选取**试用**。
设置 › 助手中选取的模型会看到该服务器的工具，并说明它会调用哪个以及使用什么参数；不会真的调用任何内容。不符合工具输入 Schema 的调用会显示问题所在，
不清楚的工具名称和描述就是这样暴露出来的。

对某个提供商的第一次试用会询问与助手相同的一次性许可。此处不使用 CLI 智能体。

## 疑难解答 [#troubleshooting]

- **“请先在“设置 › 助手”中选取模型提供商。”** 没有打勾的提供商。请添加一个，或在**设置 › 助手 › 提供商**中勾选一个。
- **“此工作区的智能体已关闭”**：**工作区设置 › 智能体 › 智能体可以使用此工作区**已关闭（`workspace.toml` 中的 `[agents] enabled = false`）。开启它才能在那里使用助手。
- **提供商在“添加”或“载入模型”之后显示错误。** 请检查密钥，对于 OpenAI 兼容服务器，还要检查它是否在该地址上运行。消息会指出提供商以及出了什么问题。
- **CLI 智能体无法启动。** 请检查它的命令能否在“终端”中运行，并确认**设置 › 智能体 › 允许智能体使用打开的工作区**已开启。