iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/zh-Hans/reference/opentelemetry.md

@@ -0,0 +1,177 @@
+# OpenTelemetry 参考
+
+iCode 可通过 OpenTelemetry 记录智能体运行过程中产生的以下遥测数据：
+
+- **追踪**：记录智能体运行、模型请求和工具调用等操作的起止时间、父子调用关系及错误信息，用于查看调用过程和定位耗时环节。
+- **日志**：按事件记录时间、级别和具体内容，例如工具调用成功、运行警告或错误信息；有调用上下文时，可与对应追踪关联。
+- **指标**：记录模型请求耗时、输入与输出 Token 数量、工具调用耗时等数值，用于汇总用量、耗时分布和变化趋势。
+
+收集器是接收遥测数据的服务。iCode 使用 OpenTelemetry Protocol（OTLP）向收集器发送数据。下文中的“端点”指收集器接收遥测数据的地址。
+
+本页介绍 iCode 的 OpenTelemetry 配置、遥测数据的保存与导出方式，以及连接 OTLP 收集器的方法。
+
+## 启用与数据去向
+
+### 启用配置
+
+OpenTelemetry 默认关闭。可在终端用户界面（Terminal User Interface，TUI）的[设置 → 安全 → 遥测](../guides/configuration/settings.md#遥测)中启用，也可使用以下环境变量。**本页配置均在重启 iCode 后生效。**
+
+| 环境变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `CHRYS_OTEL` | `false` | 启用 OpenTelemetry 导出 |
+| `CHRYS_OTEL_ENDPOINT` | 空 | 设置收集器端点，对应 TUI 的“遥测端点” |
+| `CHRYS_OTEL_SENSITIVE_DATA` | `false` | 在遥测中包含提示词、模型回复和工具参数等敏感内容 |
+
+布尔值接受 `1`、`true`、`yes`、`on`（开启）和 `0`、`false`、`no`、`off`（关闭），不区分大小写。
+
+在 TUI 中修改的设置会保存在用户设置文件 `settings.yaml` 中。上述环境变量设置为有效值后：
+
+- 环境变量优先于文件中的对应配置生效，但不会修改该文件。
+- TUI 会显示环境变量指定的值，并禁用对应设置项的编辑。
+
+关闭 `CHRYS_OTEL` 或 TUI 中的“OpenTelemetry 导出”后，即使已配置端点或敏感数据选项，iCode 也不会保存或发送遥测数据。
+
+### 数据去向
+
+启用 OpenTelemetry 后，如果未配置任何收集器端点，追踪和日志保存在本地；配置收集器端点后，则改为远端导出。
+
+追踪、日志和指标可以共用一个接收地址，也可以分别配置。每类数据使用哪个地址，由[端点优先级](#端点优先级)决定；数据去向如下：
+
+| 数据类型 | 本地保存 | 远端导出（已为该类数据配置接收地址） |
+| --- | --- | --- |
+| 追踪 | 当前会话文件夹中的 `otel/traces.jsonl` | 发送到收集器 |
+| 日志 | 当前会话文件夹中的 `otel/logs.jsonl` | 发送到收集器 |
+| 指标 | 不保存 | 发送到收集器 |
+
+本地文件会在产生相应记录后创建。会话文件夹的位置见[查找会话 ID 和会话保存位置](../guides/daily-use/sessions.md#查找会话-id-和会话保存位置)。
+
+配置任一收集器端点并重启 iCode 后，iCode 将停止在本地保存遥测数据。远端导出失败时不会回退到本地保存，因此相关数据可能丢失。
+
+发送到接收端的数据是否保存以及保留多久，由接收端的配置决定。
+
+## 敏感数据
+
+开启“遥测中包含敏感数据”或设置 `CHRYS_OTEL_SENSITIVE_DATA=true` 后，追踪和日志中可能包含提示词、模型回复、工具参数和工具结果。这些内容可能包含文件内容、凭据或其他私密信息。该设置同时影响本地保存和远端导出。
+
+**开启敏感数据后，工具调用耗时指标也会附带工具参数。** 因此，即使仅导出指标，也可能向收集器发送这些参数。
+
+启用此选项前，请确认数据保存位置、访问权限和保留策略。关闭此选项不会删除此前已经保存或发送的记录。
+
+## 连接收集器
+
+远端导出需要已运行且接收 OTLP/gRPC 的 OTLP 收集器。配置时，请使用收集器提供的端点和认证信息。
+
+下文的标准 `OTEL_*` 变量也可以写在工作目录的 `.env` 文件或用户 `.env` 文件（macOS / Linux：`~/.chrys/.env`；Windows：`%APPDATA%\chrys\.env`）中。启动时，这些文件中的值会覆盖 shell 中导出的同名变量。
+
+### 端点优先级
+
+三类数据共用的地址称为**基础端点**，可通过 TUI 中的“遥测端点”、`CHRYS_OTEL_ENDPOINT` 或标准环境变量 `OTEL_EXPORTER_OTLP_ENDPOINT` 配置。
+
+如需分别指定接收地址，可设置以下**类型专用端点**。类型专用端点仅覆盖对应数据类型的基础端点：
+
+| 数据类型 | 专用端点环境变量 |
+| --- | --- |
+| 追踪 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` |
+| 日志 | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` |
+| 指标 | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` |
+
+存在多项配置时，每类数据按照以下优先级选择第一个非空端点：
+
+1. 对应数据类型的专用端点环境变量。
+2. 通用环境变量 `OTEL_EXPORTER_OTLP_ENDPOINT`。
+3. `CHRYS_OTEL_ENDPOINT`。
+4. TUI 中保存的“遥测端点”。
+
+如果未配置基础端点，仅设置某一类数据的专用端点，则只导出该类数据。例如，仅设置 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 时，只发送追踪数据；日志和指标既不会发送，也不会保存到本地。
+
+标准 `OTEL_EXPORTER_OTLP_*` 环境变量不会显示在 TUI 的“遥测端点”中。如果修改 TUI 中的端点后，数据仍发送到原地址，请检查是否设置了优先级更高的标准环境变量。
+
+### 协议与地址格式
+
+iCode 通过 OTLP/gRPC 发送数据，直接使用配置的端点地址。`OTEL_EXPORTER_OTLP_PROTOCOL` 应保持未设置或设为 `grpc`。iCode 安装包不包含 OTLP HTTP 导出器：设为 `http/protobuf`（或 `http`）时，OpenTelemetry 初始化失败，iCode 不会记录任何遥测数据，也不会保存到本地；设为其他值时不会导出任何数据。
+
+端点地址须包含协议前缀：`http://` 使用未加密连接，适用于本机收集器；`https://` 使用 TLS。连接远端收集器时，请使用 `https://`，并按服务要求配置认证信息。
+
+### 认证请求头
+
+如果收集器需要通过请求头进行认证，可使用以下环境变量：
+
+| 环境变量 | 作用范围 |
+| --- | --- |
+| `OTEL_EXPORTER_OTLP_HEADERS` | 所有数据类型 |
+| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | 追踪 |
+| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | 日志 |
+| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | 指标 |
+
+请求头使用逗号分隔的 `名称=值` 格式。请求头名称须使用小写字母，因为 gRPC 会拒绝包含大写字母的名称；值按原样发送，不做 URL 解码。例如：
+
+```bash
+export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <token>"
+```
+
+将 `<token>` 替换为收集器提供的令牌，并在启动 iCode 前设置。
+
+类型专用请求头会与通用请求头合并；存在同名请求头时，类型专用值优先。
+
+### 本机连接示例
+
+假设本机收集器通过 `http://localhost:4317` 接收 OTLP gRPC 请求，不需要认证，且未设置其他标准端点环境变量，可在 Bash 或 Zsh 中运行：
+
+```bash
+export CHRYS_OTEL=true
+export CHRYS_OTEL_ENDPOINT=http://localhost:4317
+icode
+```
+
+此配置会通过未加密的 gRPC 连接将追踪、日志和指标发送到 `http://localhost:4317`。
+
+## 在接收端查看数据
+
+### 服务标识
+
+默认服务名（`service.name`）为 `chrys`，服务版本为当前安装的 iCode 版本。可在收集器或其连接的观测平台中按服务名查找数据。
+
+如果多处运行的 iCode 向同一个收集器发送数据，可以用服务名和资源属性区分数据来源。资源属性是附在遥测数据上的标签，例如运行环境和实例名称。
+
+例如，在测试环境中运行一个 iCode 实例，可在 Bash 或 Zsh 中设置：
+
+```bash
+export OTEL_SERVICE_NAME=icode-test
+export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=staging,service.instance.id=test-01"
+```
+
+在同一终端启动 iCode 后，导出的数据会带上以下标识，可在观测平台中据此筛选：
+
+| 属性 | 示例值 | 含义 |
+| --- | --- | --- |
+| `service.name` | `icode-test` | 服务名称 |
+| `deployment.environment.name` | `staging` | 运行环境，此处表示测试环境 |
+| `service.instance.id` | `test-01` | 实例名称，用于区分同一环境中的多个 iCode 实例 |
+
+`OTEL_RESOURCE_ATTRIBUTES` 使用逗号分隔多个 `名称=值`。其中的属性会覆盖同名默认属性；如果设置了 `service.name`，也会覆盖 `OTEL_SERVICE_NAME`。
+
+例如，设置 `OTEL_SERVICE_NAME=icode-test`，同时设置 `OTEL_RESOURCE_ATTRIBUTES="service.name=icode-qa"`，最终服务名为 `icode-qa`。
+
+### 指标与验证
+
+配置指标端点后（也可继承基础端点），iCode 每 5 秒尝试导出以下指标：
+
+| 指标 | 单位 | 统计内容 |
+| --- | --- | --- |
+| `gen_ai.client.operation.duration` | 秒 | 模型请求耗时 |
+| `gen_ai.client.token.usage` | Token | 模型请求的输入与输出 Token 数量，分别记录 |
+| `chrys.function.invocation.duration` | 秒 | 工具调用耗时 |
+
+iCode 会为 Token 用量自动添加 `gen_ai.token.type` 标签。在观测平台查询 `gen_ai.client.token.usage` 时：
+
+- 筛选 `gen_ai.token.type=input`，查看输入 Token 用量。
+- 筛选 `gen_ai.token.type=output`，查看输出 Token 用量。
+- 按 `gen_ai.token.type` 分组，同时展示两类用量。
+
+已启用 OpenTelemetry 且为指标配置了接收地址时，可提交一次请求并触发模型请求或工具调用，然后在接收端查询上述指标，以确认数据是否成功导出。Token 用量仅在模型响应提供相应统计时记录。
+
+如果未收到数据，可依次检查：
+
+1. 是否已启用 OpenTelemetry，并在修改配置后重启 iCode。
+2. 收集器是否在该端点接收 OTLP/gRPC，`OTEL_EXPORTER_OTLP_PROTOCOL` 是否未设置或设为 `grpc`，以及是否存在优先级更高的端点配置。
+3. 收集器是否需要认证，以及认证请求头是否配置正确。

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

@@ -0,0 +1,245 @@
+# iCode 设置文件参考
+
+`settings.yaml` 保存 iCode 的界面偏好、默认智能体、会话和工具设置。本文按用途列出常用设置键，并说明文件位置与格式、值的写法、多个来源并存时的优先级，以及项目文件可以覆盖的范围。
+
+在终端用户界面（Terminal User Interface，TUI）中修改设置的步骤和生效时间，见[配置 iCode 设置](../guides/configuration/settings.md)。
+
+## 文件位置与格式
+
+| 配置来源 | macOS / Linux | Windows | 用途 |
+| --- | --- | --- | --- |
+| 用户设置 | `~/.chrys/settings.yaml` | `%APPDATA%\chrys\settings.yaml` | 保存个人设置；TUI 设置窗口写入此文件 |
+| 项目设置 | 工作目录下的 `.chrys/settings.yaml` | 同左 | 覆盖该工作目录的部分设置，默认不加载 |
+
+iCode 仅在当前会话的工作目录下查找 `.chrys/settings.yaml`，不向父目录或子目录查找。
+
+文件使用 YAML 格式。键名以点分隔表示嵌套层级，例如 `llm.retry.max_transient` 在文件中写为：
+
+```yaml
+llm:
+  retry:
+    max_transient: 3
+```
+
+手动编辑设置文件后，保存并重新启动 iCode 使修改生效。
+
+## 设置键
+
+表中“无”表示没有对应环境变量，“未指定”表示该键没有保存值（未填写或留空）。通用的取值写法与无效值处理见[值的写法与无效值](#值的写法与无效值)。
+
+### 界面与输入
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `ui.theme` | `CHRYS_THEME` | `chrys` | 字符串；使用 TUI 主题列表（按 **F9** 打开）中已有的主题名称。已停用的名称 `chrys-dark` 按 `chrys` 读取，其他未知名称回到默认主题 |
+| `ui.locale` | `CHRYS_LOCALE` | `system` | 字符串；`system` 跟随系统，也可设为 `en` 或 `zh-Hans`。不支持的语言使用英语；不改变模型回复语言 |
+| `ui.editor.keymap` | `CHRYS_EDITOR_KEYMAP` | `standard` | 字符串；`standard`、`emacs`、`vim`，选择输入编辑器的按键模式 |
+| `ui.chat.tool_groups_expanded` | 无 | `false` | 布尔值；新出现的工具组是否默认展开详情 |
+| `ui.chat.file_snapshot_inline_chars` | `CHRYS_TUI_FILE_SNAPSHOT_INLINE_CHARS` | `131072` | 整数；控制文件编辑卡片直接载入的改动前后内容上限，按两者字节数合计判断。不超过上限时随卡片载入，标题显示具体的增删行数；超过上限且有可用快照引用时，展开差异才读取，标题不显示具体行数。`0` 或负数将上限设为零；没有可用快照引用时仍可能保留内联内容。此设置只控制卡片的内容载入方式；是否备份文件内容由 `mutations.snapshot.max_file_mb` 和 `mutations.snapshot.skip_binary` 决定 |
+| `history.prompt.enabled` | `CHRYS_HISTORY_DISABLE` | `true` | 布尔值；跨会话保存和读取输入历史，关闭不会删除已有记录。环境变量含义相反：只有精确的 `1` 禁用历史，其他值不禁用 |
+| `workspace.mru_max_entries` | `CHRYS_WORKSPACE_MRU_MAX_ENTRIES` | `20` | 整数；最多保留多少个最近使用的工作目录，上限 `100`，`0` 或负数禁用记录 |
+
+### 智能体、模型与请求
+
+模型用途键填写已有模型配置的 ID 或唯一名称；Buddy 伙伴不选择模型配置，其键填写模型服务端的模型名称（`model_id`）。
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `agent.default_profile` | `CHRYS_DEFAULT_AGENT` | `Code` | 字符串；下次启动 TUI 时的默认智能体，不切换当前会话；显式 `--agent` 优先 |
+| `model.profile.active` | `CHRYS_MODEL_PROFILE` | 未指定 | 字符串；选择已有模型配置，作为智能体未指定有效 `model.profile_id` 时的后备模型。显式 `--model` 优先于此键，但仍作为后备模型；ACP 会话中显式切换模型则优先于智能体指定的模型 |
+| `model.role.approval_judge` | `CHRYS_MODEL_PROFILE_APPROVAL_JUDGE` | 未指定 | 字符串；自动审批使用的模型配置，未指定时使用当前模型 |
+| `model.role.session_title` | `CHRYS_MODEL_PROFILE_SESSION_TITLE` | 未指定 | 字符串；自动生成会话标题使用的模型配置，未指定时使用当前模型 |
+| `model.role.buddy_model_id` | `CHRYS_PET_MODEL` | 未指定 | 字符串；Buddy 伙伴使用的模型，沿用当前模型配置的连接；未指定时使用当前模型 |
+| `llm.retry.max_transient` | `CHRYS_MAX_TRANSIENT_RETRIES` | `null` | 整数或 `null`；`null` 使用当前启动入口的默认次数：TUI（含 `icode serve`）和 `icode acp` 为 `10` 次，`icode run` 和 `icode workflow run` 为 `18` 次。每次重试前的等待逐次变长，最长 10 分钟。`0` 禁用瞬时错误自动重试，负数无效，上限 `50` |
+
+瞬时错误重试用于临时网络故障、请求超时、限流等可恢复错误。提高次数也会增加最终失败前的等待时间和请求次数；该数字不等于整个任务的模型请求总数。
+
+### 审批与项目信任
+
+`approval` 相关键控制智能体请求执行操作时的审批行为；三种模式的差别与配置步骤见[配置审批模式](../guides/configuration/approval.md)。
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `approval.default_mode` | `CHRYS_DEFAULT_APPROVAL_MODE` | `manual` | 字符串；`manual` 手动审批、`auto` 自动审批、`bypass` 跳过审批。设置默认模式不会切换当前会话 |
+| `ui.approval.defer_while_judging` | 无 | `true` | 布尔值；自动模式下，TUI 是否只在审批裁判模型标记调用或评估失败时才弹出审批对话框。`false` 表示评估期间立即弹出。ACP 服务器和 `icode run` 不受影响 |
+| `project.config_enabled` | 无 | `false` | 布尔值；是否加载各工作目录的项目设置，必须在用户设置中启用 |
+| `project.hooks_enabled` | 无 | `false` | 布尔值；是否加载工作目录 `.chrys/hooks` 中的项目 Hooks，必须在用户设置中启用，不影响用户级 Hooks |
+| `project.skills_enabled` | 无 | `false` | 布尔值；是否加载工作目录 `.agents/skills` 中的项目 Skills，必须在用户设置中启用；智能体自身的“从工作文件夹加载 Skills”选项也需保持开启 |
+
+手动在 YAML 或环境变量中将默认审批模式设为 `bypass`，下次按此默认值启动时就会跳过审批。在 TUI 中通过 `/approval` 切换到 `bypass` 时，iCode 会将默认模式保存为 `auto`；TUI 设置窗口不提供 `bypass`。
+
+项目设置、项目 Hooks 和项目 Skills 都随你打开的仓库而来，因此默认都不加载，并且分别开启：开启其中一项不会开启其他项。工作目录中有未开启的项时，iCode 会弹出提示，说明需要开启哪个设置。Hooks 是 iCode 在特定事件时运行的外部命令，编写与配置见[配置和编写 Hooks](../guides/extensions/hooks.md)；Skills 见[安装和使用 Skills](../guides/extensions/skills.md)。
+
+### 会话与文件恢复
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `session.title.auto` | `CHRYS_SESSION_TITLE_AUTO` | `true` | 布尔值；通过额外模型请求自动生成会话标题。手动设置标题后，不再自动更新该会话标题 |
+| `storage.session_root_dir` | `CHRYS_SESSION_ROOT_DIR` | 未指定 | 路径字符串；默认使用用户配置目录，实际会话位于根目录下的 `sessions` 子目录；支持 `~`，建议使用绝对路径 |
+| `rollback.snapshots_keep` | `CHRYS_ROLLBACK_SNAPSHOTS_KEEP` | `20` | 整数；每个会话保留的回滚快照数，最小 `1`；超出后删除较早快照 |
+| `mutations.snapshot.max_file_mb` | `CHRYS_MUTATION_SNAPSHOT_MAX_FILE_MB` | `50` | 整数；单个文件备份的大小上限，单位 MiB。`0` 或负数取消大小限制；超限文件仍记录为有改动，但不备份内容，无法据此显示差异或恢复文件 |
+| `mutations.snapshot.skip_binary` | `CHRYS_MUTATION_SNAPSHOT_SKIP_BINARY` | `true` | 布尔值；是否跳过二进制文件内容备份。设为 `false` 时仍受单文件大小上限约束 |
+
+改变会话存储根目录不会自动迁移旧会话；指定目录不可用时会提示并回退到默认位置。迁移步骤见[迁移会话存储位置](../guides/daily-use/sessions.md#迁移会话存储位置)。
+
+### 工具与工作目录变更
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `tools.search.respect_gitignore` | 无 | `true` | 布尔值；grep 和 glob 搜索时应用 `.gitignore` 规则。设为 `false` 时仍会跳过隐藏路径，`.ignore` 等其他忽略文件也仍然生效 |
+| `tools.ask_user.inline` | `CHRYS_ASK_USER_INLINE` | `false` | 布尔值；TUI 中将智能体提问显示在对话中，而不是弹出窗口 |
+| `tools.ask_user.timeout_seconds` | `CHRYS_ASK_USER_TIMEOUT_SECONDS` | `900` | 整数或 `null`；等待回答的秒数，超时后向智能体返回超时结果；`0`、负数或用户 YAML 的 `null` 表示无限等待 |
+| `tools.result.ceiling_tokens` | `CHRYS_TOOL_RESULT_CEILING_TOKENS` | `64000` | 整数；单条工具结果交给模型前的最终长度上限，单位 token。`0` 关闭此限制；正数最小 `2000`，负数无效 |
+| `workspace.change_notice.enabled` | `CHRYS_WORKSPACE_CHANGE_NOTICE` | `true` | 布尔值；开始处理新提示词时，向智能体提供自上次提交提示词以来的工作目录文件变更摘要，包含智能体造成的改动和外部改动 |
+| `workspace.change_notice.max_entries` | `CHRYS_WORKSPACE_CHANGE_NOTICE_MAX_ENTRIES` | `50` | 整数；变更摘要的最大条目数，范围 `1`–`100` |
+| `mutations.parallel_implicit_tools` | `CHRYS_PARALLEL_IMPLICIT_TOOLS` | `true` | 布尔值；允许同一会话中的 Shell、Skill 脚本等可能改动文件的工具并行运行。设为 `false` 更容易判断文件改动来自哪次工具调用 |
+| `mutations.coordination.enabled` | `CHRYS_MUTATION_COORDINATION` | `true` | 布尔值；协助区分共享工作目录的不同 iCode 会话造成的文件改动 |
+
+工具自身还可能有独立的输出限制，例如 MCP 返回结果和 Skill 资源的限制。将 `tools.result.ceiling_tokens` 设为 `0` 不会关闭这些限制，也不能恢复已被工具截断的内容。此外，Shell 命令和 Skill 脚本的每一路输出最多保留 32 MiB，与这些 token 限制无关。
+
+### 网络工具
+
+以下键用于配置 `web_search` 和 `web_fetch` 工具。这两个工具默认关闭，还需要加入智能体才能使用。这些键没有对应环境变量，只能在用户设置中配置，项目设置不能配置。TUI 的“设置”窗口在“工具”标签页中提供常用的键，其余的键需在用户 `settings.yaml` 中设置。工具如何使用这些值，参阅[配置网络工具](../guides/configuration/web-tools.md)。
+
+来源列表的每一项都是确切的来源（协议、主机和可选端口，例如 `https://docs.example.com`），不能包含路径、查询参数、凭据或通配符。列表可以写成 YAML 列表，也可以写成 JSON 数组字符串；TUI 保存时使用 JSON 字符串。空字符串表示空列表。两个模式键中，`true` 或不加引号的 `on` 对网络搜索表示 `auto`、对网页读取表示 `on`；`false` 或不加引号的 `off` 表示 `off`。这些值按工具使用的同一套规则检查，无效值会被报告（并说明错在哪里）然后忽略。
+
+| YAML 键 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- |
+| `tools.web_search.mode` | `auto` | 字符串；`auto` 或 `off`。`auto` 时，包含 `web_search` 且未配置搜索提供方的智能体会将搜索请求发送到 Exa 公开端点 `https://mcp.exa.ai/mcp`；`off` 关闭网络搜索。智能体配置文件中的 `tools.web_search.mode` 优先 |
+| `tools.web_search.num_results` | `8` | 整数，范围 `1`–`20`；智能体未指定数量时每次搜索返回的结果数。智能体配置文件中的值优先 |
+| `tools.web_search.timeout_seconds` | `30` | 整数，范围 `1`–`120`；整个搜索调用的截止时间（秒），包括等待空闲连接的时间。智能体配置文件中的值优先 |
+| `tools.web_search.custom_endpoints` | `[]` | 对象列表，每项形如 `{"url": "...", "credential_env_names": ["..."]}`；授权一个 `custom_http` 搜索端点及其可以读取的环境变量。同一 URL 只能出现一次 |
+| `tools.web_search.private_origins` | `[]` | 来源列表；即使解析到私有或其他非公网地址也允许访问的搜索端点 |
+| `tools.web_search.http_origins` | `[]` | 来源列表；允许通过明文 `http://` 访问的搜索端点 |
+| `tools.web_fetch.mode` | `on` | 字符串；`on` 或 `off`。`on` 模式下，包含 `web_fetch` 的智能体可以使用该工具；`off` 模式下不提供。智能体配置文件中的 `tools.web_fetch.mode` 优先 |
+| `tools.web_fetch.max_tokens` | `16000` | 整数，范围 `1`–`64000`；读取的页面最多返回的词元数。智能体可以要求更少，但不能更多。智能体配置文件中的值优先 |
+| `tools.web_fetch.timeout_seconds` | `60` | 整数，范围 `1`–`120`；整个网页读取调用的截止时间（秒）。智能体配置文件中的值优先 |
+| `tools.web_fetch.private_origins` | `[]` | 来源列表；即使解析到私有或其他非公网地址，`web_fetch` 也可以读取的来源 |
+| `tools.web_fetch.http_origins` | `[]` | 来源列表；`web_fetch` 可以通过明文 `http://` 读取的来源 |
+| `tools.web_fetch.allowed_origins` | `[]` | 来源列表；非空时，`web_fetch` 只从这些来源读取 |
+| `tools.web_fetch.denied_origins` | `[]` | 来源列表；`web_fetch` 从不读取的来源，优先于其他所有列表 |
+| `tools.web_egress.proxy_url` | 未设置 | 字符串；仅供网络工具使用的 `http://` 或 `https://` 代理，写成不含凭据和路径的来源，例如 `http://proxy.example.com:8080`。网络工具忽略 `HTTP_PROXY`、`HTTPS_PROXY` 等变量 |
+| `tools.web_egress.proxy_dns` | `local` | 字符串；`local` 或 `remote`。设置代理后，`local` 在本机解析主机名，只连接检查过的公网地址；`remote` 把主机名交给代理，由代理决定最终地址。未设置 `proxy_url` 时不起作用。参阅[使用 fake-IP 代理](../guides/configuration/web-tools.md#使用-fake-ip-代理) |
+
+这些值中的主机名可以包含下划线。
+
+### 上下文与轨迹分析
+
+以下设置没有对应环境变量。
+
+| YAML 键 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- |
+| `context.warn_threshold_pct` | `0.5` | 数值；范围 `0`–`1`，表示上下文窗口的占用比例。用量达到阈值时向智能体提示一次上下文用量较高，回落到阈值以下后再次达到才会再提示；默认阈值为 50%；不改变自动压缩的触发条件 |
+| `trajectory.verify_commands` | 内置常见测试、检查命令列表 | 字符串；轨迹分析用来识别验证操作的命令词，以逗号分隔，例如 `"pytest,ruff,npm test"`。自定义值替换整份列表；只影响分析归类，不执行这些命令 |
+
+### 通知
+
+以下键均为布尔值，默认均为 `true`，没有对应环境变量，用于 TUI 的事件通知。
+
+| YAML 键 | 效果 |
+| --- | --- |
+| `notifications.enabled` | 事件通知总开关 |
+| `notifications.delivery.desktop` | 发送桌面弹窗 |
+| `notifications.delivery.sound` | 播放声音 |
+| `notifications.suppress_when_focused` | iCode 获得焦点时暂停通知 |
+| `notifications.events.approval_required` | 需要审批时通知 |
+| `notifications.events.ask_user` | 智能体需要输入时通知 |
+| `notifications.events.turn_complete` | 智能体完成任务时通知 |
+| `notifications.events.turn_error` | 智能体出错时通知 |
+
+发送通知需要总开关、对应事件开关和至少一种发送方式开启，且未因获得焦点而暂停。关闭总开关不会清除其他选择。
+
+### 诊断与遥测
+
+**原始 HTTP 日志可能包含明文 API 密钥、完整提示词和模型回复。** 仅在明确数据去向和访问权限后启用，排查结束后关闭不再需要的诊断选项并重启 iCode。
+
+| YAML 键 | 环境变量 | 默认值 | 类型、取值与效果 |
+| --- | --- | --- | --- |
+| `log.raw_http_capture` | `CHRYS_DEBUG_LLM_RAW_HTTP_LOG` | `false` | 布尔值；将模型原始 HTTP 请求和响应写入当前会话目录的 `llm_raw_http.jsonl` |
+| `otel.enabled` | `CHRYS_OTEL` | `false` | 布尔值；启用 OpenTelemetry 导出 |
+| `otel.endpoint` | `CHRYS_OTEL_ENDPOINT` | 未指定 | 字符串；遥测收集器端点。未配置任何端点时仅在本地保存追踪和日志；标准 OTLP 端点环境变量优先于此设置。配置端点后停止本地保存，发送失败时不回退 |
+| `otel.sensitive_data` | `CHRYS_OTEL_SENSITIVE_DATA` | `false` | 布尔值；额外记录提示词、模型回复、工具参数和工具结果，可能包含私密信息；仅在明确数据去向和访问权限后启用 |
+
+数据保存位置、收集器连接、认证和指标查询见 [OpenTelemetry 参考](./opentelemetry.md)。
+
+## 来源优先级
+
+每个键独立按以下优先级取值，使用靠前的有效值。项目设置还必须符合[项目级设置](#项目级设置)的限制。
+
+| 优先级 | 来源 |
+| --- | --- |
+| 1 | 当前会话中的明确选择、命令行参数或入口固定行为 |
+| 2 | 启动进程时已有的环境变量 |
+| 3 | 旧版用户 `.env` 中尚未迁移的设置（macOS / Linux：`~/.chrys/.env`；Windows：`%APPDATA%\chrys\.env`） |
+| 4 | 已启用且允许应用的项目设置 |
+| 5 | 用户设置 |
+| 6 | 内置默认值 |
+
+启动时，iCode 会尝试将旧版用户 `.env` 中的 iCode 设置迁入用户 `settings.yaml`，并清理已迁移的设置行。合并时 `settings.yaml` 中已有的同名键优先保留，不会被覆盖；尚未完成迁移的设置行仍按上表第 3 级来源生效。迁移失败时会提示，并在下次启动时重试。模型服务的 API 密钥等环境变量保留在 `.env` 中。
+
+工作目录 `.env` 中的 iCode 设置不生效。项目设置应写入 `.chrys/settings.yaml`。
+
+## 值的写法与无效值
+
+下面说明向设置文件与环境变量填值的通用规则；单个键的上下限、`null` 的含义等约束，见[设置键](#设置键)各键行的“类型、取值与效果”列。
+
+- 布尔值在 YAML 中写 `true` 或 `false`。对应的环境变量接受 `1`、`true`、`yes`、`on` 和 `0`、`false`、`no`、`off`，不区分大小写。个别环境变量的含义与名称相反或只接受特定拼写，已在对应键行注明。
+- 整数直接写数字。标明上下限的键，超界值会被调整到边界；明确禁止负数的键会拒绝负值。`0` 或负数的特殊含义（禁用、取消限制等）以各键行说明为准。
+- 未填写的键和空字符串通常不提供覆盖。要撤销某个文件中的设置，删除该键；删除后仍可能使用其他来源的值（见[来源优先级](#来源优先级)）。
+- 类型列为“整数或 `null`”的键可写 `null`，其含义已在对应键行说明；用户设置与项目文件对 `null` 的处理不同，见[项目级设置](#项目级设置)。
+- 未知键会被报告且不生效。多数无效值会被忽略并报告，取值继续向较低优先级查找——例如，环境变量中的值无效而用户设置中已有有效值时，使用用户设置的值。`approval.default_mode`、`tools.result.ceiling_tokens`、`log.raw_http_capture`、`otel.sensitive_data`、`mutations.trace.fsatrace_path` 五个键不同：一旦在查找中遇到无效值，就直接采用内置默认值并停止查找，不回退到较低优先级。例如，无法识别的审批模式会采用默认值 `manual`。
+
+## 项目级设置
+
+项目设置默认不加载。先在用户 `settings.yaml` 中启用，或在 TUI 的“设置 → 安全”中打开“加载项目设置”：
+
+```yaml
+project:
+  config_enabled: true
+```
+
+启用后适用于所打开的工作目录。项目文件只能配置下表中的键。
+
+有覆盖方向限制的键只接受表中“允许的覆盖方向”内的项目值，比较时以用户 YAML 中的值为基准；用户未设置时以内置默认值为基准。`llm.retry.max_transient` 在用户未设置或设为 `null` 时，按当前启动入口的默认值比较。没有方向限制的键直接采用项目值。环境变量不参与比较，但仍优先于项目设置。项目文件写入 `null` 不提供覆盖。
+
+| 项目可配置的键 | 允许的覆盖方向 |
+| --- | --- |
+| `llm.retry.max_transient` | 只能减少或保持重试次数 |
+| `tools.result.ceiling_tokens` | 只能降低或保持结果长度上限；`0` 表示无限制，是最宽松的值，仅当用户设置本身就是 `0` 时项目才能写 `0` |
+| `session.title.auto` | 可以关闭；不能重新开启用户已关闭的自动标题 |
+| `mutations.parallel_implicit_tools` | 可以关闭；不能重新开启用户已关闭的并行执行 |
+| `mutations.coordination.enabled` | 可以开启；不能关闭用户已开启的跨会话改动区分 |
+| `workspace.change_notice.enabled` | 可以开启；不能关闭用户已开启的变更通知 |
+| `workspace.change_notice.max_entries` | 可在 `1`–`100` 范围内覆盖 |
+| `context.warn_threshold_pct` | 可在 `0`–`1` 范围内覆盖 |
+| `trajectory.verify_commands` | 可替换验证命令列表 |
+
+网络工具相关的键（`tools.web_search.*`、`tools.web_fetch.*` 和 `tools.web_egress.*`）不在此表中，因此项目无法开启网络搜索，也无法扩大网络工具可连接的范围。
+
+例如，在工作目录的 `.chrys/settings.yaml` 中写入：
+
+```yaml
+llm:
+  retry:
+    max_transient: 3
+```
+
+启用项目设置并重新启动后，若用户未设置重试次数，则使用项目的 `3` 次；若用户 YAML 已设为 `1`，项目中的 `3` 会被拒绝，仍使用 `1`。启动环境中的有效值始终优先。
+
+iCode 会提示并忽略项目中不允许的键、超出覆盖限制的值和未知键，继续应用其他有效设置。
+
+## 启动入口的差异
+
+| 入口 | 与设置文件有关的行为 |
+| --- | --- |
+| `icode`（TUI） | 使用界面、输入、通知设置；默认智能体取自 `agent.default_profile` |
+| `icode run` | 固定跳过审批，不等待用户回答；默认审批模式和提问超时设置不改变这些行为 |
+| `icode acp` | 智能体客户端协议（Agent Client Protocol，ACP）服务；初始智能体和审批模式由 `--agent`、`--approval` 决定，默认分别为 `Code`、`manual`；提问默认无限等待，由 `--ask-user-timeout` 指定超时 |
+| `icode serve` | 在浏览器中承载 TUI；配置文件和环境变量来自运行 iCode 服务的机器 |
+
+## 设置未生效时
+
+1. 确认设置文件的位置正确，保存后已重新启动 iCode。
+2. 检查是否存在更高优先级的来源；删除 YAML 中的键不会清除其他来源的值。
+3. 对项目设置，确认用户已启用加载，且键名和覆盖方向符合限制。
+4. 查看 iCode 启动时报告的消息：无效值或未知键的处理规则见[值的写法与无效值](#值的写法与无效值)；目录相关提示对照[文件位置与格式](#文件位置与格式)检查。

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

@@ -0,0 +1,149 @@
+# 主题文件参考
+
+iCode 支持通过主题文件自定义终端用户界面（Terminal User Interface，TUI）的外观。本页介绍主题文件的格式、常用配色字段和加载规则。通过界面修改并保存主题，请参阅[自定义主题](../guides/configuration/themes.md)。
+
+## 文件位置与命名
+
+主题文件保存在以下目录中；目录不存在时先创建。
+
+| 平台 | 目录 |
+| --- | --- |
+| macOS / Linux | `~/.chrys/themes/` |
+| Windows | `%APPDATA%\chrys\themes\` |
+
+主题文件使用 UTF-8 编码，扩展名必须为 `.yaml` 或 `.yml`，直接存放在上述目录中。iCode 不读取子目录中的主题文件。
+
+主题名称为文件名去除 `.yaml` 或 `.yml` 扩展名后的部分。主题名称须满足以下要求：
+
+* 以英文字母或数字开头，只使用英文字母、数字、点、下划线和连字符。
+* 不能与内置主题重名，比较时不区分大小写。内置主题名称包括 `chrys`、`chrys-legacy`、`chrys-ansi`、主题列表中的 Textual 主题（如 `nord`、`textual-dark`），以及已停用的名称 `chrys-dark`。
+* 不能以 `.yaml` 或 `.yml` 结尾，比较时不区分大小写，例如不能使用 `my-theme.yaml.yaml`。
+
+`.yaml` 和 `.yml` 文件名称相同时，优先使用 `.yaml`；如果 `.yaml` 文件无效，仍会尝试使用 `.yml`。同名主题只保留一个。
+
+新增或修改主题文件后，重启 iCode 加载，再按 **F9** 在主题列表中选择对应主题即可应用。
+
+## 文件格式
+
+以下是自定义深色主题 `icode-ocean.yaml` 的示例：
+
+```yaml
+# 整体配色
+primary: "#5c9ded"
+secondary: "#7aa2c7"
+accent: "#70c1b3"
+warning: "#e5b567"
+error: "#e57373"
+success: "#81c784"
+dark: true
+background: "#18212b"
+foreground: "#e6edf3"
+surface: "#202c38"
+panel: "#263442"
+
+# 指定区域的配色
+variables:
+  footer-background: "#18212b"
+  footer-foreground: "#e6edf3"
+  input-selection-background: "#5c9ded 35%"
+  markdown-block-background: "#202c38"
+```
+
+`primary` 是唯一必填字段，其余字段均可按需设置。未指定的颜色由 iCode 自动补齐，具体规则见[默认配色规则](#默认配色规则)。
+
+## 配置字段
+
+主题文件由两部分组成：
+
+* **顶层字段**：设置主题的整体配色。
+* **`variables`**：设置特定界面区域的颜色和样式。
+
+`variables` 必须是字符串到字符串的映射。顶层未知字段会导致该主题被跳过。
+
+### 整体配色
+
+以下字段设置主题的基础颜色。
+
+| 配置目标 | 字段 | 说明 |
+| --- | --- | --- |
+| 主色 | `primary` | 主题的主要标识色，用于标题和强调背景 |
+| 次要强调色 | `secondary` | 用于与主色区分的元素 |
+| 点缀色 | `accent` | 用于少量需引起注意的元素，通常与 `primary`、`secondary` 形成对比 |
+| 状态色 | `warning`、`error`、`success` | 分别用于警告、错误和成功状态的背景、边框及文字 |
+| 整体背景 | `background` | 未被控件覆盖区域的默认背景色 |
+| 默认文字颜色 | `foreground` | 应在 `background`、`surface` 和 `panel` 三种背景上均清晰可读 |
+| 控件背景 | `surface` | 控件的默认背景色，通常用于位于整体背景之上的控件 |
+| 区域区分色 | `panel` | 用于在视觉上区分界面中的某个区域与主要内容 |
+| 深色或浅色模式 | `dark` | `true` 为深色，`false` 为浅色；影响未填写的背景色和自动配色 |
+| ANSI 配色模式 | `ansi` | 默认为 `false`。设为 `true` 时启用终端 ANSI 配色模式，支持使用 `ansi_red`、`ansi_default` 等颜色值；实际 ANSI 颜色由终端配色决定。此模式忽略顶层 `surface` 和 `panel` 的设置，两者均使用透明色 |
+
+颜色字段必须是字符串。十六进制值需要加引号，例如 `"#5c9ded"`；也可以使用 `"rgb(92, 157, 237)"` 或 `"red"` 等颜色表示方式。
+
+顶层颜色字段可用 `"rgba(92, 157, 237, 0.35)"` 表示 35% 不透明度，不支持 `"#5c9ded 35%"` 这种百分比后缀写法。
+
+字段不能留空或设置为 `null`。不需要配置时直接省略。
+
+### 按钮、底栏、选区和光标
+
+以下字段配置在 `variables` 下，仅影响对应的界面元素。`variables` 下的颜色值支持百分比后缀，例如 `input-selection-background: "#5c9ded 35%"` 表示以 35% 不透明度混合该颜色。百分比混色适用于 RGB 颜色；`ansi_*` 颜色忽略不透明度。
+
+| 配置目标 | 字段 |
+| ---------- | --------------------------------------------------- |
+| 按钮文字       | `button-flat-foreground`                            |
+| 按钮悬停文字、背景 | `button-hover-foreground`、`button-hover-background` |
+| 按钮禁用文字、背景 | `button-disabled-foreground`、`button-disabled-background` |
+| 底栏背景、文字    | `footer-background`、`footer-foreground`             |
+| 底栏快捷键背景、文字 | `footer-key-background`、`footer-key-foreground`     |
+| 输入选区背景     | `input-selection-background`                        |
+| 块状光标背景、文字  | `block-cursor-background`、`block-cursor-foreground` |
+| 块状光标文字样式   | `block-cursor-text-style`                           |
+
+未设置的按钮颜色使用主题默认配色。
+
+`block-cursor-text-style` 接受 Textual 文字样式，例如 `"bold"`（默认，粗体）、`"italic"`、`"underline"`、`"reverse"` 或 `"none"`（不附加文字样式）。
+
+### 边框、控件和内容区域
+
+以下字段同样配置在 `variables` 下。未设置的字段使用下表中的默认配色。
+
+| 字段 | 未填写时的颜色 | 影响的界面元素 |
+| --- | --- | --- |
+| `border-color` | 各区域原有的配色 | 统一普通界面边框；消息、警告和错误状态边框仍保留各自颜色，按钮边框仍跟随按钮背景 |
+| `tool-group-title-color` | `warning` | 工具调用组标题 |
+| `control-background`、`control-background-muted` | `surface` | 控件的背景及弱化背景 |
+| `control-disabled-background` | `background` | 禁用控件背景 |
+| `control-foreground-muted` | `text-disabled` | 控件的弱化文字 |
+| `overlay-background` | `panel` | 鼠标悬停提示和界面通知的背景 |
+| `markdown-block-background` | `surface` | Markdown 引用块和围栏代码块的背景 |
+| `hatch-color` | `foreground` 的 15% 不透明度混合色 | 空状态区域的斜线纹理 |
+
+滚动条可通过 `scrollbar`、`scrollbar-hover`、`scrollbar-active` 配置普通、悬停和拖动状态的颜色。`scrollbar-background` 同时决定这三种状态的轨道背景；已有的 `scrollbar-background-hover` 和 `scrollbar-background-active` 可分别覆盖对应状态。
+
+## 默认配色规则
+
+非 ANSI 主题中，未指定的字段使用以下默认值，或根据其他颜色自动计算。ANSI 模式使用终端配色，不应按下表推断最终显示颜色。
+
+| 未填写的字段 | 使用的值 |
+| --- | --- |
+| `dark` | `true`，即深色模式 |
+| `secondary`、`accent`、`warning` | 与 `primary` 相同 |
+| `error`、`success` | 与 `secondary` 相同 |
+| `background` | 深色模式为 `#121212`；浅色模式为 `#efefef` |
+| `foreground` | 背景色的反色 |
+| `surface` | 深色模式为 `#1e1e1e`；浅色模式为 `#f5f5f5` |
+| `panel` | 根据 `surface`、`primary` 和深浅色模式混合生成 |
+
+以下可选字段位于文件顶层，用于调整自动生成的配色。
+
+| 字段 | 默认行为 | 可调整的内容 |
+| --- | --- | --- |
+| `luminosity_spread` | 默认 `0.15` | 控制从基础颜色生成明暗色阶时的变化幅度；填写有限数值，不接受 `.nan` 或 `.inf` |
+| `boost` | 深色模式且未填写 `panel` 时，在自动生成的面板颜色上叠加与背景对比的黑色或白色，不透明度为 4% | 填写颜色字符串。深色模式且未填写 `panel` 时替代该叠加色，调整自动生成的面板亮度，并作为 `block-hover-background` 的默认值（该颜色的 10% 不透明度）；浅色模式或已填写 `panel` 时不生效 |
+
+顶层还接受 `text_alpha` 字段，须填写有限数值，但目前不会改变显示颜色。
+
+## 加载失败
+
+加载时发现 YAML 格式错误、缺少 `primary`、未知顶层字段或无效字段值时，iCode 会显示警告并跳过该文件。根据警告检查对应文件，修正后重启加载；其他有效主题仍可使用。
+
+主题通过加载后，如果应用时发现 `variables` 值无法用于对应的界面样式，iCode 会显示警告并回退到默认主题 `chrys`。回退不会覆盖已保存的主题选择，修正文件后可重启重试。

chrys/app/tui/screens/guides/_docs/zh-Hans/reference/tool-kinds-and-names.md

@@ -0,0 +1,58 @@
+# 工具类别和名称
+
+iCode 使用工具类别（`tool_kind`）对用途或来源相近的工具进行分组，使用工具名称（`tool_name`）标识具体工具。同一类别可以包含多个工具，例如 `filesystem.write` 类别包含 `write_file` 和 `edit_file`。
+
+在终端用户界面（Terminal User Interface，TUI）的输入栏中输入 `/runtime`，或点击输入栏上方状态栏右端显示的工具数量，打开“运行时详情”窗口。“工具”标签页列出按类别分组的内置工具和子智能体工具，“MCP”标签页列出按服务器分组的 MCP 工具名称。Skill 工具和上下文工具不会在该窗口中列出。智能体只能调用当前已加载的工具。
+
+## 类别和名称概览
+
+“内置”表示该类别可以通过智能体配置的 `tools.builtins` 字段启用。
+
+| 工具类别 | 内置 | 用途或来源 | 工具名称 |
+| --- | --- | --- | --- |
+| `shell` | 是 | 执行 Shell 命令 | 当前 Shell 的名称；Windows 上检测到 Git Bash 时还包括 `git_bash`，ACP 会话中还包括 `list_workspace_dirs` |
+| `filesystem.read` | 是 | 读取文件和查看图像 | `read_file`、`view_image` |
+| `filesystem.write` | 是 | 创建、覆写和编辑文件 | `write_file`、`edit_file` |
+| `search` | 是 | 搜索文件内容和文件名 | `grep`、`glob` |
+| `web_search` | 是 | 在网络上搜索链接和摘要 | `web_search` |
+| `web_fetch` | 是 | 按 URL 读取网页内容 | `web_fetch` |
+| `ask_user` | 是 | 在任务中询问用户 | `ask_user` |
+| `sleep` | 是 | 等待 | `sleep` |
+| `doc_converter` | 是 | 转换 PDF 和 Office 文档 | `convert_document` |
+| `todo` | 是 | 维护待办事项 | `todo_write` |
+| `sub_agent` | 否 | 调用子智能体 | 由智能体配置决定 |
+| `mcp` | 否 | MCP 服务器工具和按需加载控制工具 | 由 MCP 服务器及其配置决定 |
+| `skill` | 否 | 加载 Skill、读取资源和运行脚本 | `load_skill`、`read_skill_resource`、`run_skill_script` |
+| `context` | 否 | 压缩和查询对话上下文 | `compress_context`、`recall_context`、`list_compressed_contexts` |
+
+具体工具是否可用还取决于当前智能体、模型能力和运行方式。例如，`view_image` 只会提供给支持图片输入的模型，无界面命令行模式 `icode run` 不提供 `ask_user`。
+
+iCode 自带的智能体都没有启用 `web_search` 和 `web_fetch`。智能体包含这两个工具时，如果某个工具的模式为 `off`，或模型提供方运行同名的网络工具，对应的本地工具不会提供。参阅[配置网络工具](../guides/configuration/web-tools.md)。
+
+## Shell 工具名称
+
+`shell` 类别中的主要工具使用当前 Shell 的名称，例如 `zsh`、`bash`、`pwsh`、`powershell` 或 `cmd`。在 Windows 上检测到 Git Bash 时，iCode 还会在主要 Shell 工具之外提供 `git_bash` 工具。实际名称取决于操作系统和 iCode 检测到的 Shell。
+
+ACP 会话还会提供 `list_workspace_dirs`，用于列出主工作目录和 ACP 客户端提供的其他工作目录。
+
+## 子智能体工具名称
+
+`sub_agent` 类别中，每个工具对应一个可调用的子智能体。工具名称由智能体配置中的 [`sub_agents.agents[].tool_name`](./agent-profile.md#sub_agents) 决定；省略该字段时，默认使用子智能体的配置名称。
+
+显式设置的 `tool_name` 必须以字母或下划线开头，之后只能包含字母、数字或下划线。省略 `tool_name` 时直接使用配置名称，因此工具名称可能包含连字符或以数字开头。同一父智能体内的工具名称不能重复。
+
+## MCP 工具名称
+
+`mcp` 类别包含 MCP 服务器提供的工具。iCode 会先将工具名称中除英文字母、数字、下划线和连字符以外的字符替换为连字符。未设置 `tool_name_prefix` 时，直接使用处理后的名称。
+
+设置 `tool_name_prefix` 后，iCode 还会移除处理后名称开头的下划线和连字符，再按 `<前缀>_<工具名称>` 拼接；名称被移除为空时，只使用前缀。例如，服务器提供 `search` 或 `_search`，前缀为 `github` 时，最终名称均为 `github_search`。
+
+配置 `approval.overrides` 或 Hooks 的 `match.tool_name` 时，应**以“运行时详情”窗口的“MCP”标签页中显示的实际工具名称为准**。
+
+启用按需加载时，iCode 还会提供三个控制工具：
+
+- `<前缀>_list_mcp_tools`
+- `<前缀>_load_tool`
+- `<前缀>_unload_tool`
+
+未配置 `tool_name_prefix` 时，控制工具以 `mcp_` 加 MCP 服务器名称作为前缀，其中英文字母和数字以外的每个字符都会编码为 `-<十六进制码>-`，例如服务器 `my-server` 对应 `mcp_my-2d-server_list_mcp_tools`；服务器名称过长时会被截短并以哈希值结尾。控制工具不会显示在“运行时详情”窗口的“MCP”标签页中。