iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/configuration/settings.md

@@ -0,0 +1,210 @@
+# 配置 iCode 设置
+
+iCode 设置控制界面外观、默认智能体、会话、工具、通知和部分安全选项。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中完成这些基础配置，并确认修改何时生效。
+
+如需直接编辑 `settings.yaml` 或通过环境变量配置，请参阅[iCode 设置文件参考](../../reference/settings.md)，了解文件位置、设置键和来源优先级。
+
+## 设置窗口
+
+### 打开设置窗口
+
+设置窗口只能在智能体空闲时打开。
+
+使用以下任一方式打开“设置”窗口：
+
+- 按 **F10**。
+- 点击界面底部的 `f10 设置`。
+- 在输入栏中输入 `/settings`，按空格键或 **Enter** 显示标签页列表，然后选择要打开的标签页。
+
+也可以用 `/settings <tab>` 直接打开标签页：
+
+| 标签页 | `<tab>` | 主要设置 |
+| --- | --- | --- |
+| 通用 | `general` | 外观与输入 |
+| 模型与智能体 | `models` | 默认智能体、模型用途与请求重试 |
+| 安全 | `security` | 审批、项目信任、诊断与遥测 |
+| 会话 | `sessions` | 会话标题、存储与回滚 |
+| 工具 | `tools` | 文件搜索、网络工具、智能体提问、工具详情显示与工作区通知 |
+| 通知 | `notifications` | 通知开关、方式与事件 |
+
+例如，输入 `/settings security` 可直接打开“安全”标签页。
+
+### 修改与生效时间
+
+修改会随操作自动保存。输入框中的修改可按回车提交，也会在切换到其他设置或关闭窗口时提交。按 **Esc** 关闭窗口不会撤销已经提交的修改。
+
+设置窗口右下角的状态提示说明修改何时生效；有多类待生效修改时，会同时显示相应提示。
+
+| 状态提示 | 生效时机 |
+| --- | --- |
+| “修改即时保存” | 修改已保存，且没有需要在关闭窗口或重启后才生效的修改 |
+| “修改将在关闭时生效（重载）” | 按 **Esc** 关闭“设置”窗口后生效 |
+| “修改将在当前轮次结束后生效” | 有轮次或工作流正在运行时替代“修改将在关闭时生效（重载）”；关闭“设置”窗口且运行结束后生效 |
+| 提示有多少项修改需重启后生效 | 修改已经保存，但必须退出并重新启动 iCode 后才会生效 |
+
+下文各表的“生效时间”列列出每项设置的通常行为。
+
+## 设置项
+
+### 通用
+
+#### 外观
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 主题 | 切换 TUI 使用的主题。需要调整配色或创建自定义主题时，请参阅[自定义主题](themes.md)。 | 立即 |
+| 界面显示语言 | 只改变 iCode 界面文案，不改变会话内容、模型输出语言或已有记录。也可输入 `/language` 切换界面显示语言。| 立即 |
+
+#### 输入
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 保存提示词历史 | 跨会话保存提交过的输入，供后续复用。主界面未被其他窗口覆盖时，按 **Ctrl+R** 会在输入栏上方打开历史提示词列表；鼠标单击记录，或用上下键选中记录后按回车，会将该提示词复制到输入栏。提示词历史记录文件 `prompt_history.jsonl` 保存在：macOS 和 Linux 的 `~/.chrys/`，或 Windows 的 `%APPDATA%\chrys\`。关闭此设置不会删除该历史记录文件，只是不再读取，按 **Ctrl+R** 将显示“无结果”；重新启用并重启 iCode 后，仍可读取该历史记录文件中的记录。若要清理历史，请删除该历史记录文件；删除后无法恢复。 | 重启后 |
+
+### 模型与智能体
+
+此标签页只选择已有的智能体或模型配置，不编辑其配置。相关操作请参阅[配置智能体](./agents.md)和[配置模型](./models.md)。
+
+#### 智能体
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 默认智能体 | 只决定下次启动 TUI 时默认使用的智能体，不影响当前会话。 | 设置立即保存，下次启动生效 |
+
+#### 模型角色
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 会话标题模型 | 默认“使用当前所选模型”。仅在启用[自动生成会话标题](#会话)时使用。 | 关闭窗口后 |
+| 审批裁判模型 | 默认“使用当前所选模型”。仅在[自动审批模式](./approval.md#了解三种审批模式)下使用。 | 关闭窗口后 |
+| Buddy 模型 | 默认“使用当前所选模型”，用于 Buddy 伙伴功能。 | 关闭窗口后 |
+
+#### LLM
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 瞬时错误最大重试次数 | 控制网络暂时中断、请求超时、模型服务临时不可用或服务端限流等可短暂恢复错误的最大自动重试次数；不会重试模型配置或请求参数等无法等待恢复的问题。次数越高，临时故障恢复的机会越大；若多次重试仍失败，最终失败前的等待时间和模型请求次数也会增加。留空使用 TUI 默认值；设为 `0` 时不自动重试。上下文窗口已满时，iCode 压缩上下文后重新发送的那一次不受此设置影响。 | 关闭窗口后 |
+
+### 安全
+
+#### 审批
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 默认审批模式 | 设置下次启动 iCode 时默认使用的审批模式，不影响当前会话。窗口中只提供 `manual` 和 `auto`；如需在当前会话中绕过审批，请使用 `/approval bypass`。当前会话的模式切换及各模式区别请参阅[配置审批模式](./approval.md)。 | 设置立即保存，下次启动生效 |
+| 仅在自动审查标记后弹出审批对话框 | 默认开启。自动模式下，审批裁判模型评估调用期间不弹出对话框，判定安全的调用直接执行；只有调用被标记或评估失败时才弹出。关闭后，对话框会立即弹出并显示“正在评估”，可以在评估完成前自行决定。已在等待的请求保持其开始时的行为。参阅[在 TUI 中处理审批请求](./approval.md#在-tui-中处理审批请求)。 | 立即 |
+
+#### 项目信任
+
+项目设置、项目钩子和项目 Skills 都随你打开的仓库而来，因此默认都不加载。工作目录中有未加载的项目设置、钩子或 Skills 时，iCode 会弹出提示，说明需要勾选哪一项。
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 加载项目设置 | 读取当前工作目录的 `.chrys/settings.yaml`，应用其中的项目级设置，例如请求重试、自动生成会话标题和工作目录通知。可配置的键及覆盖限制见[项目级设置](../../reference/settings.md#项目级设置)。 | 关闭窗口后 |
+| 加载项目钩子 | 决定是否加载当前工作目录 `.chrys/hooks` 中的 Hooks，不影响用户级 Hooks。创建和验证钩子请参阅[配置和编写 Hooks](../extensions/hooks.md)，完整配置字段见 [Hooks 配置参考](../../reference/hooks.md)。 | 关闭窗口后 |
+| 加载项目 Skills | 决定是否加载当前工作目录 `.agents/skills` 中的 Skills，不影响你自己的 Skill 目录。详见[安装和使用 Skills](../extensions/skills.md)。 | 关闭窗口后 |
+
+#### 诊断
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 捕获原始 HTTP 流量 | 记录模型请求和响应，以便排查问题。**日志可能以明文包含 API 密钥、完整提示词和模型回复**，因此建议仅在排查时开启，并妥善保管日志文件；排查完成后，应及时关闭该设置并重启 iCode。日志文件 `llm_raw_http.jsonl` 保存在当前会话文件夹中；查找该文件夹的方法请参阅[查找会话 ID 和会话保存位置](../daily-use/sessions.md#查找会话-id-和会话保存位置)。 | 重启后 |
+
+#### 遥测
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| OpenTelemetry 导出 | 启用遥测，记录追踪、日志和指标。关闭时，另外两项不会使 iCode 保存或发送遥测数据。 | 重启后 |
+| 遥测端点 | 设置接收遥测数据的收集器地址。未通过设置或环境变量配置任何端点时，仅在本地保存追踪和日志；配置任一端点后停止本地保存，发送失败时也不会回退到本地。 | 重启后 |
+| 遥测中包含敏感数据 | 额外记录提示词、模型回复、工具参数和工具结果，影响本地保存和远端导出；工具耗时指标也可能包含工具参数。启用前请确认数据去向和访问权限。 | 重启后 |
+
+遥测数据的含义、保存位置、端点优先级和收集器连接方法见 [OpenTelemetry 参考](../../reference/opentelemetry.md)。
+
+### 会话
+
+#### 标题
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 自动生成会话标题 | 开启后，iCode 会发起额外的模型请求以根据对话内容智能生成标题。**手动设置会话标题后，iCode 不再自动更新该会话的标题。** 有关设置或清除手动标题，请参阅[修改会话标题](../daily-use/sessions.md#修改会话标题)。 | 关闭窗口后 |
+
+#### 位置
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 会话存储根目录 | 决定 iCode 保存会话的位置，留空时使用默认位置；会话实际保存在该目录的 `sessions` 子目录。“使用中”显示本次启动正在使用的 `sessions` 目录。修改根目录后，需要重启 iCode 才会使用新位置；重启前，会话仍保存在“使用中”所示目录。**重启后，新会话会保存到新目录，但旧会话文件不会自动迁移。** 若要在新位置继续使用已有会话，请参阅[迁移会话存储位置](../daily-use/sessions.md#迁移会话存储位置)。 | 重启后 |
+
+#### 回滚
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 保留的回滚快照数 | 决定每个会话最多保留多少份回滚快照。iCode 每次开始处理一条新提交的提示词前，都会创建一份快照；超过保留数量后，较早的快照会被自动删除。快照保存在对应会话文件夹的 `snapshots` 子目录中。保留的快照越多，使用 `/rollback` 时可返回的较早会话状态越多，但占用的磁盘空间也越多。 | 关闭窗口后 |
+
+### 工具
+
+#### 文件搜索
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 遵循 .gitignore | 在 grep 和 glob 搜索中应用 Git 忽略规则；关闭后仍会跳过隐藏路径，`.ignore` 等其他忽略文件也仍然生效。 | 关闭窗口后 |
+
+#### 网络搜索
+
+以下设置作用于包含网络工具的智能体；网络工具默认关闭，参阅[配置网络工具](./web-tools.md)。智能体配置文件自行设置的模式、结果数或超时，会覆盖该智能体的对应设置。项目设置不能修改这些设置。
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 网络搜索模式 | `auto`（默认）允许包含网络搜索的智能体使用该工具。未配置搜索提供方的智能体会把搜索请求发送到第三方服务 Exa 的公开搜索端点，参阅[网络请求的去向](./web-tools.md#网络请求的去向)。`off` 关闭网络搜索。智能体配置文件指定了模式时，以配置文件为准。 | 关闭窗口后 |
+| 每次网络搜索的结果数 | 智能体未指定数量时，每次搜索返回的结果数，范围 1～20，默认 8。 | 关闭窗口后 |
+| 网页读取模式 | `on`（默认）允许包含网页读取的智能体按 URL 读取页面。`off` 关闭网页读取。智能体配置文件指定了模式时，以配置文件为准。 | 关闭窗口后 |
+| 网络代理地址 | 仅供网络工具使用的 `http://` 或 `https://` 代理，不含凭据和路径。留空表示直接连接。网络工具忽略 `HTTP_PROXY` 等代理环境变量。 | 关闭窗口后 |
+| 网络代理 DNS | 设置代理后由谁解析主机名。`local`（默认）在本机解析，并在连接前检查每个地址。`remote` 把主机名交给代理解析（fake-IP 代理需要这样做），拦截私有地址的工作也随之交给代理；参阅[使用 fake-IP 代理](./web-tools.md#使用-fake-ip-代理)。未设置网络代理地址时不起作用。 | 关闭窗口后 |
+| 自定义搜索端点 | 智能体配置文件中自定义搜索端点的授权项，写成 JSON 数组，每项形如 `{"url": "...", "credential_env_names": ["..."]}`。 | 关闭窗口后 |
+| 网络搜索私有网络来源 | 即使解析到私有地址，网络搜索也可以访问的来源，写成 JSON 数组，例如本机 SearXNG 可写 `["http://127.0.0.1:8080"]`。 | 关闭窗口后 |
+| 网络搜索明文 HTTP 来源 | 网络搜索可以通过明文 `http://` 访问的来源，写成 JSON 数组。 | 关闭窗口后 |
+
+这些值在保存前按网络工具使用的同一套规则检查，被拒绝的值会说明错在哪里。清空列表字段即表示空列表。网络搜索超时、网页读取超时与词元预算，以及网页读取的来源列表不在窗口中显示，需在 `settings.yaml` 中设置（参阅[网络工具](../../reference/settings.md#网络工具)）。
+
+#### 询问用户
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 在对话中显示提问 | 开启后，智能体的提问直接显示在对话中；关闭后，提问显示在弹出窗口中。 | 关闭窗口后 |
+| 询问用户超时（秒） | 决定 iCode 等待回答的时间。留空时使用 TUI 界面显示的默认值。超过设定时间仍未收到回答时，iCode 会把超时结果返回给智能体；设为 `0` 时会一直等待，直到收到回答或任务中断。通过 IDE 插件等 ACP 客户端使用时，`ask_user` 默认不设置服务端等待时限；如需限制等待时间，请在启动 ACP 服务时使用 `--ask-user-timeout`。 | 关闭窗口后 |
+
+#### 外观
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 默认展开工具详情 | 开启后，新出现的工具组默认展开；关闭后默认折叠，只显示摘要和正在执行的操作。可以随时点击工具组展开详情。 | 立即 |
+
+#### 工作区通知
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 工作区变更通知 | 开始处理一条新提交的提示词时，iCode 会向智能体提供自上一次提交提示词以来的工作目录文件变更摘要。其中既包括当前会话中智能体及其子智能体的改动，也包括由人工、其他程序或其他 iCode 会话造成的改动。 | 关闭窗口后 |
+
+### 通知
+
+#### 常规
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 启用通知 | 事件通知的总开关。关闭后不发送桌面弹窗或声音，但会保留发送方式和事件开关的选择；重新启用后，原来的选择仍有效。 | 立即 |
+
+#### 发送方式
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 桌面弹窗、声音 | 可分别启用；两项都关闭时，即使总开关和事件开关已开启，也不会收到通知。                                           | 立即 |
+| iCode 获得焦点时暂停通知 | iCode 位于前台时不发送桌面弹窗或声音。                                                        | 立即 |
+| 测试 | 按当前发送方式发送测试通知，不受总开关、事件开关或是否获得焦点影响；仅用于确认桌面弹窗和声音是否可用，测试前至少开启“桌面弹窗”或“声音”之一。 | 立即 |
+
+#### 事件
+
+| 设置项 | 效果与必要说明 | 生效时间 |
+| --- | --- | --- |
+| 需要审批 | 决定是否在需要审批时触发通知。 | 立即 |
+| 智能体需要输入 | 决定是否在智能体需要输入时触发通知。 | 立即 |
+| 智能体已完成 | 决定是否在智能体完成任务时触发通知。 | 立即 |
+| 智能体错误 | 决定是否在智能体出错时触发通知。 | 立即 |

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/configuration/themes.md

@@ -0,0 +1,61 @@
+# 自定义主题
+
+主题编辑器用于在终端用户界面（Terminal User Interface，TUI）中调整配色，并直接预览效果。本指南介绍如何从已有主题开始修改，保存为自己的主题，以及撤销修改或删除主题。
+
+编辑过程中的配色会实时预览，但不会自动保存。只有点击主题编辑器中的“保存”，修改才会写入主题文件，并在下次启动时继续生效。若希望直接编写 YAML 文件或查询配色字段，请参阅[主题文件参考](../../reference/themes.md)。
+
+## 打开编辑器
+
+1. 按 **F9**，或点击底栏的 `f9 主题`，打开主题列表。
+2. 选择列表底部的“修改主题…”，打开停靠在主界面旁的主题编辑器。
+3. 在编辑器顶部的下拉列表中选择要修改的主题。此操作只切换编辑对象，不会更改当前应用的主题。
+
+编辑器旁保留当前对话，可以观察配色对文字、工具卡片和其他界面元素的影响。
+
+编辑器打开期间，通过 F9、`/theme` 或设置窗口切换应用主题会受到限制。要更换编辑对象，使用编辑器顶部的下拉列表；要切换日常使用的主题，先关闭编辑器。
+
+## 调整并预览颜色
+
+编辑器按 `Colors`、`Buttons`、`Borders` 等分组列出颜色。编辑器使用字段名标识配色项，例如 `primary`（主色）、`background`（整体背景）。
+
+1. 点击要修改的颜色块，打开颜色选择器。
+2. 对于普通主题，在 `RGB / HSV` 中选择或输入颜色，也可以切换到“256 色”选取颜色。ANSI 主题提供 `ANSI` 和“256 色”两种选择方式，ANSI 颜色的实际显示由终端配色决定。
+3. 调整时，主界面会实时预览。确认效果后点击“确认”，把这项修改保留在编辑器中；点击“取消”或按 **Esc**，放弃本次颜色选择器中的修改。
+
+背景色和面板配色（`background`、`surface`、`panel` 和 `boost`）必须保持不透明，因此颜色选择器不提供这些字段的透明度调整。
+
+## 撤销与重置
+
+根据要撤销的范围，选择对应操作：
+
+| 操作 | 结果 |
+| --- | --- |
+| 颜色选择器中的“恢复” | 恢复到打开这次颜色选择器时的值 |
+| 编辑器中的“撤销”／“重做” | 撤销或重做已经确认的编辑操作 |
+| 已修改字段旁的“↺”重置按钮 | 将这一项恢复为本次载入该主题时的值 |
+| “全部重置” | 将所有字段恢复为本次载入该主题时的值 |
+
+## 保存主题
+
+1. 在编辑器中点击“保存”。
+2. 在“保存主题”窗口中填写主题名称。
+3. 点击“保存”。出现保存成功通知后，主题会立即应用，并记住本次选择。
+
+主题名称须满足以下要求：
+
+* 不超过 100 个字符，以英文字母或数字开头，只使用英文字母、数字、点、下划线和连字符，不能以点结尾。
+* 不填写 `.yaml` 或 `.yml` 扩展名。
+* 基于内置主题修改时，须使用新名称另存；基于用户主题修改时，名称与原名称完全一致（含大小写）时会覆盖原文件，使用新名称则另存。重名检查不区分大小写。
+* 不能使用 Windows 设备名，如 `CON`、`NUL`、`COM1`～`COM9` 或 `LPT1`～`LPT9`，也不能使用这些名称后接点和后缀的形式，如 `CON.dark`。
+
+## 关闭或更换编辑对象
+
+切换编辑对象或点击“关闭”时，如有未保存的修改，会询问是否放弃。选择“放弃修改”将丢弃修改并继续操作，选择“取消”则继续编辑。
+
+关闭编辑器后，界面恢复为当前应用的主题。
+
+## 删除用户主题
+
+“删除”会移除该主题文件和当前未保存的修改。内置主题不支持删除。
+
+在编辑器顶部选择用户主题，点击“删除”，核对确认窗口中的主题名称后再次点击“删除”。删除当前已应用的主题后，iCode 会切换到默认主题 `chrys`。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/configuration/tools.md

@@ -0,0 +1,60 @@
+# 配置工具
+
+内置工具为智能体提供访问文件、搜索内容、执行 Shell 命令以及使用其他 iCode 功能的能力。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中为智能体启用或停用内置工具类别。
+
+MCP 服务器提供的工具不属于内置工具，需要在 [MCP 配置](../extensions/mcp.md)中单独管理。
+
+需要查询智能体配置和 Hooks 中使用的工具类别值及具体工具名称时，参阅[工具类别和名称](../../reference/tool-kinds-and-names.md)。
+
+## 打开工具配置
+
+在输入栏中输入 `/agents tools`，打开当前智能体的“工具”标签页。如需修改其他智能体，可在左侧列表中选择。
+
+## 选择内置工具
+
+每个选项对应一类内置工具，根据智能体需要完成的任务启用相应类别：
+
+| 工具类别 | 可完成的操作 | 配置建议 |
+| --- | --- | --- |
+| 读取文件系统 | 读取文件和查看图像（PNG、JPEG 或 WebP） | 需要分析项目文件时启用；只有所选模型支持视觉输入时，智能体才能使用查看图像工具 |
+| 写入文件系统 | 创建、覆写和精确编辑文件 | 仅在智能体需要修改文件时启用 |
+| 文件搜索 | 搜索文件内容，或按名称模式查找文件 | 需要在项目中定位代码和文件时启用 |
+| 网络搜索 | 查找网页链接和摘要；除非智能体配置文件指定了其他提供方，否则使用 Exa（exa.ai） | 需要查询最新文档、发布信息等外部资料时启用。搜索词会发往该外部服务，并可能带有对话中的内容，请注意数据与隐私安全 |
+| 网页读取 | 按 URL 读取页面文本 | 需要阅读搜索到的页面或你指定的页面时启用 |
+| Shell | 在子进程中执行终端命令 | 需要运行构建、测试或其他命令时启用 |
+| 询问用户 | 在任务进行中请求补充信息或让用户作出选择 | 适合 TUI 和 ACP 会话；无界面命令行模式（`icode run`）不会向智能体提供此工具 |
+| 等待 | 暂停任务，最长 3600 秒；TUI 中会显示可提前跳过的倒计时 | 需要等待一段时间后继续任务时启用 |
+| 文档转换器（PDF、Office） | 将 PDF、DOCX、PPTX、XLSX 和 XLS 转换为 Markdown；当前使用的模型支持图片输入、智能体已启用“读取文件系统”工具类别时，还可提取 PDF、DOCX 和 PPTX 中的图片供智能体查看；XLSX 和 XLS 只转换文本与表格 | 需要读取这些文档格式时启用 |
+| 待办事项 | 用实时清单跟踪多步骤任务 | 适合步骤较多、需要显示进度的任务 |
+
+勾选需要启用的类别，取消勾选不需要的类别，然后点击“保存”。
+
+如果修改的是当前会话正在使用的智能体，新工具配置会从后续请求开始生效。
+
+iCode 自带的智能体都没有启用网络搜索；它与只搜索本地文件的“文件搜索”不同。“网页读取”是单独的开关。未配置搜索提供方时，搜索请求会发往 Exa 的公开搜索服务。启用前，请参阅[配置网络工具](./web-tools.md)，了解请求的去向、审批和网络限制。
+
+## 使用“询问用户”工具
+
+“询问用户”工具用于在任务进行中请求补充信息或让用户作出选择。一次提问可以包含 1～5 个问题，支持单选、多选和自由文本。
+
+默认情况下，问题显示在弹出窗口中。如果弹窗遮挡了需要查看的会话内容，可以点击“在对话中回答”，将当前提问切换为在对话中显示；此操作仅对当前提问生效。如果希望后续提问默认在对话中显示，请在[配置 iCode 设置](./settings.md)中开启“在对话中显示提问”。
+
+在 TUI 中，多个问题会显示在同一个提问窗口中。可以切换问题标签，填写各个问题后，在汇总页检查回答并统一提交。
+
+等待回答的时间由[配置 iCode 设置](./settings.md)中的“询问用户超时（秒）”设置控制。
+
+## 按需配置工具
+
+工具配置决定智能体可以使用哪些能力。配置专用智能体时，建议仅启用完成任务所需的工具类别。
+
+例如：
+
+- 只分析代码的智能体可以启用“读取文件系统”和“文件搜索”，不启用“写入文件系统”和 Shell。
+- 修改代码并运行测试的智能体通常需要启用“读取文件系统”“写入文件系统”“文件搜索”和 Shell。
+- 处理不受信任的项目时，应谨慎启用 Shell 和“写入文件系统”。
+
+启用工具只表示智能体可以调用该能力；需要审批的操作仍按当前审批模式处理。有关审批请求和确认方式的详细说明，请参阅[配置审批模式](./approval.md)。
+
+对于文件系统、搜索和 Shell 工具，相对路径会以当前[工作目录](../daily-use/workspaces.md)为基准，Shell 命令也默认在当前工作目录中运行。切换工作目录后，这些相对路径和命令的默认工作目录会随之改变。工作目录是默认操作位置，并不表示工具只能访问工作目录内的路径；操作能否执行还取决于工具参数、需要审批时是否获得批准，以及运行 iCode 的系统用户权限。
+
+命令输出很多时，智能体会看到输出的开头和结尾；条件允许时，iCode 会把输出保存到会话目录。命令输出超过 32 MiB 时，iCode 只保留开头和结尾部分，中间部分不会保存在任何地方，结果中会告诉智能体有多少内容没有保留。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/configuration/web-tools.md

@@ -0,0 +1,286 @@
+# 配置网络工具
+
+网络工具让智能体可以在互联网上查找资料：`web_search` 搜索网页，返回链接和摘要；`web_fetch` 按已知 URL 读取页面文本。本指南介绍如何为智能体启用这两个工具、它们的请求发往何处，以及如何选择搜索提供方和限制网络访问。
+
+**网络工具默认关闭。** iCode 自带的智能体（Code、QA、Explore 和 General）都不包含网络工具；在你为某个智能体启用之前，iCode 不会发送任何搜索请求，也不会读取任何网页。
+
+`web_search` 与“文件搜索”工具（`grep` 和 `glob`）不同，后者只搜索本机文件。
+
+## 启用网络工具
+
+### 为智能体添加工具
+
+在输入栏中输入 `/agents tools`，选择智能体，勾选“网络搜索”“网页读取”或两者，然后点击“保存”。两者都立即可用。除非你选择了其他提供方，网络搜索会把搜索词发送给 Exa（exa.ai），启用前请先阅读[网络请求的去向](#网络请求的去向)。
+
+在智能体配置文件中，也可以把这两个工具类别加入 `tools.builtins`：
+
+```yaml
+tools:
+  builtins: [filesystem.read, search, web_search, web_fetch]
+```
+
+网络工具按智能体分别配置。子智能体（例如 General）只有在自己的配置中包含网络工具时才能使用。如需为内置智能体添加网络工具，在 TUI 中编辑并保存该智能体，iCode 会为其保存一份你自己的配置（参阅[覆盖内置智能体](../../reference/agent-profile.md#覆盖内置智能体)）。
+
+### 关闭网络工具
+
+如需在不从智能体中移除工具的情况下关闭某个工具，按 **F10** 打开“设置”窗口，选择“工具”标签页，在“网络搜索”区域将“网络搜索模式”或“网页读取模式”设为 `off`。“网络搜索模式”默认为 `auto`，“网页读取模式”默认为 `on`，因此包含该工具的智能体可以直接使用。
+
+这两项设置只作用于配置文件未指定模式的智能体。智能体配置文件中的模式优先，因此可以只为某个智能体关闭工具；配置文件设为 `on` 时，即使上述设置为 `off`，该智能体仍保留该工具：
+
+```yaml
+tools:
+  web_fetch:
+    mode: off
+```
+
+“设置”中的修改在关闭窗口后生效；智能体工具配置的修改从后续请求开始生效。
+
+## 网络请求的去向
+
+启用 `web_search` 且未配置搜索提供方时，默认的 `auto` 模式会将搜索请求发送到 **Exa 的公开匿名搜索端点 `https://mcp.exa.ai/mcp`**。Exa 是第三方搜索服务，无需 API 密钥或账号。iCode 只发送智能体要搜索的内容和所需结果数量，不会发送你的文件或对话本身；但搜索词由智能体撰写，可能包含任务中的细节。该服务有免费额度的速率限制，也可能无法访问。如需将搜索请求发往其他服务，参阅[选择搜索提供方](#选择搜索提供方)；如需停止搜索，将模式设为 `off`。
+
+`web_fetch` 直接向托管该 URL 的网站发起请求；如果设置了[网络代理](#控制网络访问)，则经由该代理。请求使用 `Chrys-Web/1.0` 作为 User-Agent，不会发送 Cookie 或已保存的凭据。
+
+搜索结果和读取的页面会作为工具结果返回给智能体，因此也会随对话的其余内容一起发送给模型提供方。只有智能体调用工具时才会发出网络请求，启动时不会发送。
+
+## 审批网络工具调用
+
+`web_search` 和 `web_fetch` 两个类别默认需要审批。这条默认规则在所有显式的 `approval.overrides` 规则之后、配置文件的 `approval.default` 之前生效，因此智能体设置 `default: auto` 并不会取消它。与其他工具一样，当前审批模式决定如何处理请求：
+
+- “手动”模式下，每次网络工具调用都会弹出“工具审批”对话框。
+- “自动”模式下，审批裁判模型可以批准调用。
+- “绕过”模式下（包括无界面命令行 `icode run`），网络工具调用不经询问直接执行。
+
+如果不希望每次搜索都询问，可以在智能体配置文件中设置覆盖项，例如 `approval.overrides: {web_search: auto}`。参阅[配置审批模式](./approval.md)。
+
+## 选择搜索提供方
+
+在智能体配置文件的 `tools.web_search` 下配置搜索提供方，字段说明见[智能体配置文件参考](../../reference/agent-profile.md#toolsweb_search)。在 `providers` 中为每个提供方取一个 ID，模式决定如何使用这些提供方：
+
+| 模式 | 行为 |
+| --- | --- |
+| `auto` | 未配置 `provider`、`fallback_chain` 和 `providers` 时，使用匿名 Exa。配置了 `providers` 时，必须同时用 `fallback_chain` 按顺序列出要尝试的提供方 ID。 |
+| `provider` | 只使用 `provider` 指定的一个提供方，不能设置 `fallback_chain`。 |
+| `off` | 为该智能体关闭网络搜索。 |
+
+也可以写 `true` 或 `false`：`true` 表示 `auto`（对 `web_fetch` 表示 `on`），`false` 表示 `off`。
+
+如果组合无效，例如 `auto` 模式配置了 `providers` 却没有 `fallback_chain`，智能体仍会启动，但不包含网络工具，iCode 会显示一条写明原因的警告（参阅[网络工具没有出现时](#网络工具没有出现时)）。未知的模式或格式错误的提供方条目则会使整个配置文件无效。
+
+### 无需密钥的搜索服务
+
+| 类型 | 服务 |
+| --- | --- |
+| `exa_mcp` | Exa 公开端点，即 `auto` 默认使用的服务 |
+| `bing_html` | Bing 搜索结果页 |
+| `duckduckgo_html` | DuckDuckGo 的 HTML 搜索结果页 |
+
+这些类型只接受 `type` 字段：端点固定，不接受凭据。例如，改用 DuckDuckGo 代替 Exa：
+
+```yaml
+tools:
+  builtins: [filesystem.read, search, web_search, web_fetch]
+  web_search:
+    mode: provider
+    provider: ddg
+    providers:
+      ddg:
+        type: duckduckgo_html
+```
+
+`bing_html` 和 `duckduckgo_html` 读取的是普通搜索结果页，而不是官方 API，可用性和结果质量取决于该服务和本地网络。结果不包含广告和生成式回答。遇到验证码、同意页面或无法识别的页面布局时，会报告错误，而不会当作空结果返回。
+
+### 需要密钥的搜索 API
+
+| 类型 | 服务 | 常用密钥变量 |
+| --- | --- | --- |
+| `tavily` | Tavily Search API | `TAVILY_API_KEY` |
+| `brave` | Brave Search API | `BRAVE_SEARCH_API_KEY` |
+| `exa` | Exa Search API（需认证） | `EXA_API_KEY` |
+
+将 `api_key_env` 设为保存密钥的环境变量名：
+
+```yaml
+tools:
+  web_search:
+    mode: auto
+    fallback_chain: [primary, backup]
+    providers:
+      primary:
+        type: tavily
+        api_key_env: TAVILY_API_KEY
+      backup:
+        type: exa
+        api_key_env: EXA_API_KEY
+```
+
+iCode 从启动 iCode 时的环境变量或用户 `.env` 文件（macOS / Linux：`~/.chrys/.env`；Windows：`%APPDATA%\chrys\.env`）读取密钥。启动环境中已设置的变量优先，即使其值为空。工作目录中的 `.env` 文件不能提供网络工具凭据。用户 `.env` 文件在每次构建智能体时读取，修改后需重新保存智能体或重启 iCode。iCode 只读取智能体实际使用的提供方所需的密钥。
+
+### 回退到其他提供方
+
+`auto` 模式下，iCode 按 `fallback_chain` 的顺序尝试各提供方，并返回第一个得到的结果，空结果也算。出现以下情况时，iCode 会改用下一个提供方：
+
+- 该提供方用完了分给它的时间（参阅[时间限制与重试](#时间限制与重试)）。
+- 连接错误、HTTP 5xx、408 或 429 在重试一次后仍然出现。
+- 无法连接提供方：其域名无法解析、解析到私有地址，或者连接因重试也无法解决的原因被拒绝（例如证书被代理拒绝）。
+- 请求对该提供方来说过大，例如搜索词过长，放进 URL 后超出长度限制。
+- 提供方返回重定向、验证码或同意页面，或者其响应过大、使用不支持的压缩方式或无法读取。
+- `exa_mcp`、`bing_html` 或 `duckduckgo_html` 返回任意 HTTP 4xx 错误，或 `exa_mcp` 报告搜索失败（例如触发了免费版的频率限制）。`exa_mcp` 返回空结果属于正常回答，回退链会就此停止。
+
+对于需要密钥的提供方和自定义提供方，HTTP 4xx 错误通常说明配置有误（例如密钥错误），因此回退链会停止，智能体收到带状态码的错误，例如 `Error: http_4xx (HTTP 403)`。由请求本身引起的错误（例如搜索词为空）也会停止回退链。iCode 不会暗中回退：只尝试你列出的提供方。
+
+### 使用自己的搜索端点
+
+`custom_http` 类型可以连接任何返回 JSON 的 HTTP 搜索服务。在配置文件中映射请求和响应：
+
+```yaml
+tools:
+  builtins: [web_search]
+  web_search:
+    mode: provider
+    provider: corporate
+    providers:
+      corporate:
+        type: custom_http
+        endpoint: https://search.example.com/v1/search
+        method: POST
+        auth:
+          location: header
+          name: Authorization
+          prefix: "Bearer "
+          key_env: CORP_SEARCH_API_KEY
+        request:
+          json:
+            query: {$input: query}
+            limit: {$input: limit}
+        response:
+          results_pointer: /data/items
+          url_pointer: /link
+          title_pointer: /title
+          snippet_pointer: /summary
+```
+
+自定义端点还需要在用户设置中授权。授权项写明确切的端点 URL，以及该提供方可以读取的每个环境变量。可以在“设置”的“自定义搜索端点”中添加，也可以写在用户 `settings.yaml` 中：
+
+```yaml
+tools:
+  web_search:
+    custom_endpoints:
+      - url: https://search.example.com/v1/search
+        credential_env_names: [CORP_SEARCH_API_KEY]
+```
+
+映射规则：
+
+- `{$input: NAME}` 插入搜索参数：`query`、`limit`、`allowed_domains` 或 `blocked_domains`。`{$env: NAME}` 插入环境变量，该变量也必须列在授权项中。每个标记替换一个完整的值，并保留其类型。
+- `method` 为 `GET` 或 `POST`。`GET` 发送 `request.query_params`，列表会展开为重复的参数；`POST` 还可以发送 `request.json` 请求体。
+- `auth.location` 为 `header`、`query` 或 `none`。密钥只能放在 `auth` 或 `$env` 标记中，不能直接写在请求头里。
+- `*_pointer` 字段是 JSON Pointer，例如 `/data/items`。`results_pointer` 和 `url_pointer` 必填。找不到结果容器时，搜索会失败，而不是返回空结果。
+
+以下两个预设可以为常见服务自动填写映射：
+
+- SearXNG：`type: custom_http`、`preset: searxng`，并将 `endpoint` 设为你的实例地址，例如 `https://search.example.com/search`。SearXNG 服务器需要启用 JSON 输出。
+- SerpAPI：`type: custom_http` 和 `preset: serpapi`。授权 `https://serpapi.com/search`，并设置 `credential_env_names: [SERPAPI_API_KEY]`。
+
+## 控制网络访问
+
+网络工具的网络访问只能在用户设置中配置。项目设置和智能体配置文件都不能修改它，因此打开的代码仓库无法扩大工具可访问的范围。常用的搜索选项位于“设置”的“工具”标签页；网页读取相关的列表需在用户 `settings.yaml` 中设置。各设置项的说明参阅[设置文件参考](../../reference/settings.md#网络工具)。
+
+```yaml
+tools:
+  web_egress:
+    proxy_url: ""        # 仅供网络工具使用的 HTTP(S) 代理
+    proxy_dns: local     # remote：由代理解析主机名
+  web_search:
+    private_origins: []
+    http_origins: []
+    custom_endpoints: []
+  web_fetch:
+    denied_origins: []   # 从不读取这些来源，始终优先
+    allowed_origins: []  # 非空时，只读取这些来源
+    private_origins: []  # 即使解析到私有地址也允许
+    http_origins: []     # 允许对这些来源使用明文 http://
+```
+
+列表条目是来源（origin），即协议、主机和可选端口，例如 `https://docs.example.com` 或 `http://127.0.0.1:8080`。条目不能包含路径、查询参数、凭据或通配符。默认端口和主机名大小写会被规范化。在“设置”窗口中，列表以 JSON 数组形式输入，例如 `["https://docs.example.com"]`，保存前会按工具使用的同一套规则检查。
+
+规则如下：
+
+- **仅限 HTTPS**：除非来源列在 `http_origins` 中，否则拒绝明文 `http://`。
+- **仅限公网地址**：连接前，iCode 解析主机名，并拒绝私有、回环、链路本地等非公网地址，除非来源列在 `private_origins` 中。随后 iCode 连接已检查过的地址，同时在请求和 TLS 证书校验中保留原始主机名。“网络代理 DNS”设为 `remote` 时改由代理解析主机名，参阅[使用 fake-IP 代理](#使用-fake-ip-代理)。
+- **网页读取列表**：`denied_origins` 始终优先。`allowed_origins` 非空时，`web_fetch` 只从这些来源读取。
+- **搜索和读取分开授权**：为搜索设置的例外不会让 `web_fetch` 访问该来源，反之亦然。
+- **代理**：网络工具忽略 `HTTP_PROXY`、`HTTPS_PROXY` 等代理变量。如需使用代理，将“网络代理地址”（`tools.web_egress.proxy_url`）设为 `http://` 或 `https://` 代理地址，不含凭据和路径。该代理只用于网络工具。“网络代理 DNS”为默认的 `local` 时，iCode 经代理只连接网站的 IPv4 地址，因此只有 IPv6 地址的网站会返回 `proxy_ipv6_unsupported` 错误。设为 `remote` 时由代理解析主机名，代理可以通过 IPv6 访问这类网站。无论哪种模式，直接写出 IPv6 地址的 URL（例如 `https://[2001:db8::1]/`）都无法通过代理访问。环境中的证书设置（例如 `SSL_CERT_FILE`）仍然有效。
+- 工具 URL、来源列表和代理地址中的主机名都可以包含下划线，例如 `http://search_box:8080`。
+
+例如，要使用位于 `http://127.0.0.1:8080/search` 的 SearXNG 实例，需要在 `custom_endpoints` 中授权该端点，并将 `http://127.0.0.1:8080` 同时加入 `tools.web_search.private_origins` 和 `tools.web_search.http_origins`。
+
+### 使用 fake-IP 代理
+
+部分代理（例如处于 TUN 或 fake-IP 模式的 Clash、Surge）会用 `198.18.0.0/15` 中的占位地址回答 DNS 查询，再由代理自己连接真实网站。这些地址不是公网地址，因此所有网络请求都会返回 `private_address_blocked` 错误，错误中附带指向本设置的提示。要使用这类代理：
+
+1. 将“网络代理地址”（`tools.web_egress.proxy_url`）设为代理的 HTTP 端口，例如 `http://127.0.0.1:7890`。
+2. 将“网络代理 DNS”（`tools.web_egress.proxy_dns`）设为 `remote`。
+
+```yaml
+tools:
+  web_egress:
+    proxy_url: http://127.0.0.1:7890
+    proxy_dns: remote
+```
+
+设为 `remote` 后，iCode 把主机名交给代理，最终连接哪个地址由代理决定。对主机名拦截私有地址和其他非公网目标因此成为代理的职责，而不再由 iCode 负责。其他规则仍然有效：仅限 HTTPS、来源列表、重定向检查，以及按主机名进行的 TLS 证书校验。直接写成非公网地址的 URL（例如 `https://127.0.0.1` 或 `https://localhost`）仍会被拒绝，除非来源列在 `private_origins` 中。URL 中直接写出的 IPv6 地址仍然无法通过代理访问，会返回 `proxy_ipv6_unsupported` 错误。
+
+iCode 不会自行切换到 `remote`。把 fake-IP 地址段加入 `private_origins` 也不能替代这一设置：列表只接受单个来源，而放行整个地址段还会让解析到你自己网络的主机名一并通过。
+
+## 按域名筛选搜索结果
+
+智能体可以用 `allowed_domains` 限定搜索范围，或用 `blocked_domains` 排除域名，但两者不能同时使用。域名同时涵盖其子域名。iCode 始终自行检查结果，提供方能提供多少帮助则因提供方而异：
+
+- Tavily 和 Exa API 自行按域名筛选。
+- Exa 公开端点不支持筛选，因此 iCode 向其请求更多结果，只保留匹配的结果。
+- 其他提供方会在搜索词中收到 `site:` 和 `-site:` 条件。
+
+筛选移除了结果时，搜索输出会报告移除的数量。
+
+## 时间限制与重试
+
+| 设置 | 默认值 | 含义 |
+| --- | --- | --- |
+| 搜索 `timeout_seconds` | 30 秒 | 整个搜索调用的截止时间，包括等待空闲连接名额的时间 |
+| 读取 `timeout_seconds` | 60 秒 | 整个网页读取调用的截止时间 |
+
+在一次搜索中，剩余的每个提供方平分剩下的时间。临时故障（连接错误，或 HTTP 5xx、408、429）会在该份时间内重试一次。用完时间的提供方会把搜索交给 `fallback_chain` 中的下一个提供方。
+
+可以在用户 `settings.yaml` 中设置这些限制（`tools.web_search.timeout_seconds` 和 `tools.web_fetch.timeout_seconds`，1～120 秒），也可以在配置文件的 `tools.web_search` 和 `tools.web_fetch` 下为单个智能体设置。
+
+## 网页读取与搜索结果的限制
+
+- `web_fetch` 用 GET 读取一个 URL，接受文本、HTML、JSON 和 XML。HTML 在移除脚本、样式、表单和隐藏模板后转换为 Markdown。PDF、图片及其他二进制文件会被拒绝，错误响应的正文不会返回。
+- 智能体传给 `web_fetch` 的 `prompt` 会显示给你，并作为关注重点与页面一起提供给智能体。不会有第二个模型读取页面。
+- 同站重定向（协议和端口相同，仅多或少 `www.` 前缀）最多跟随 2 次，每次都按网络规则检查。重定向到其他网站时，iCode 会把新 URL 报告给智能体，由智能体显式读取。
+- 响应大小限制为 2 MiB，传输大小和解压后大小都受此限制。网页读取以及 Bing 和 DuckDuckGo 适配器只接受 gzip 压缩或未压缩的响应。
+- 读取的页面默认最多返回 16,000 个词元（`tools.web_fetch.max_tokens`，最多 64,000）。智能体可以要求更少，但不能更多。搜索输出限制在约 8,000 个词元。
+- 读取过的页面在 15 分钟内会被复用（最多 64 个页面、16 MiB）；仅 `#fragment` 不同的 URL 共用一份。
+- 网络搜索和网页读取在每个智能体中共享 3 个并发连接；一轮对话中，智能体最多搜索 20 次。
+- iCode 不执行 JavaScript，不读取 `robots.txt`，也不对页面做摘要。可以用 `denied_origins` 阻止 `web_fetch` 访问特定来源。每个条目只精确匹配一个来源，不包括子域名或 `www.` 变体，需要的每一个都要单独列出。
+
+搜索结果和页面文本来自外部来源，iCode 会向智能体标明它们是不可信的数据；使用重要信息前，应核对来源链接。
+
+## 由提供方运行的搜索
+
+部分模型服务可以自行运行网络搜索。模型配置在 `chat_options` 中声明此类工具时（例如 `{"tools": [{"type": "web_search"}]}`），提供方的工具会占用该名称。如果智能体也包含对应的 iCode 工具，本地工具会在该次运行中停用，iCode 会显示一次提示。该规则按名称生效：由提供方运行的 `web_search` 不影响本地的 `web_fetch`。
+
+由提供方运行的搜索在模型提供方一侧执行，因此不受 iCode 审批规则和网络设置约束。如需改用 iCode 自己的工具，请从模型的 `chat_options` 中删除该声明。
+
+## 网络工具没有出现时
+
+如果 iCode 无法为某个智能体准备网络工具（例如缺少密钥变量，或自定义端点未授权），该智能体仍会启动，只是不包含网络工具，iCode 会显示一条警告，写明智能体名称和原因。修正配置后，重新保存智能体或重启 iCode。
+
+另外请检查：
+
+- 智能体的 `tools.builtins` 包含 `web_search` 或 `web_fetch`。
+- 工具的模式不是 `off`：即配置文件中的 `tools.web_search.mode` 或 `tools.web_fetch.mode`；配置文件未设置时，为“设置”中的“网络搜索模式”或“网页读取模式”。
+- 模型配置没有声明同名的、由提供方运行的网络工具。
+
+如需查看已加载的工具，在输入栏中输入 `/runtime`；参阅[工具类别和名称](../../reference/tool-kinds-and-names.md)。