iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/daily-use/sessions.md

@@ -0,0 +1,77 @@
+# 管理与恢复会话
+
+会话包含对话历史及相关数据，例如回滚快照、诊断日志等。iCode 会自动保存会话，以便稍后恢复对话或查询历史任务。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中切换、命名、查找、恢复和删除会话，以及更换存储位置时如何迁移已有会话。
+
+## 切换到新会话
+
+智能体空闲时，根据是否需要保留当前会话的记录，在输入栏中使用对应命令：
+
+| 目的 | 命令 | 对当前会话的影响 |
+| --- | --- | --- |
+| 开始新会话，稍后仍可恢复当前会话 | `/new` | 保留，可从会话列表恢复 |
+| 开始新会话，不再保留当前会话 | `/clear` | 显示确认对话框，确认后永久删除，无法恢复 |
+
+## 修改会话标题
+
+可以通过以下任一方式修改当前会话的标题：
+
+- 点击主界面左上角的“会话：…”区域，打开“会话标题”窗口，输入标题并点击“保存”。
+- 在输入栏中输入 `/rename`，打开“会话标题”窗口，输入标题并点击“保存”。
+- 在 `/rename` 后直接输入标题，例如 `/rename 修复登录问题`。
+
+手动设置标题后，新标题会显示在会话列表和主界面中，iCode 将不再自动更新该会话的标题。若已开启[自动生成会话标题](../configuration/settings.md#会话)，清空“会话标题”窗口中的内容并保存后，iCode 会恢复已有的自动标题，并在后续任务中继续自动更新。
+
+## 恢复已有会话
+
+智能体空闲时，在输入栏中输入 `/resume`，可恢复最近的聊天会话。
+
+需要查找和恢复其他会话时，按 **F1**、点击 `f1 会话` 或在输入栏中输入 `/sessions`，打开“聊天会话”窗口。窗口会列出会话 ID、标题、目录、最近活跃时间、对话轮次数和会话数据大小。每页最多显示 100 个会话，最近活跃的排在前面。
+
+- **按最后使用位置筛选**：搜索框上方的“TUI”“CLI”“ACP”复选框分别对应最后在 TUI 中、通过 [`icode run`](../running/icode-run.md)，或在通过 [`icode acp`](../running/icode-acp.md) 连接的编辑器等客户端中使用的会话。默认只勾选“TUI”。旧版本 iCode 保存的会话按 TUI 处理。所做选择在退出 iCode 前一直保留。将鼠标悬停在会话上，可查看它最后在哪里使用。
+- **翻页**：点击复选框右侧的“上一页”或“下一页”。
+- **会话排序**：会话默认按最近活跃时间从新到旧排列。点击列标题可按该列对当前页排序：“最近活跃”“轮次”和“大小”首次点击时降序排列，其他列首次点击时升序排列。再次点击同一列标题可反转顺序。
+- **搜索会话**：要查找会话，可在底部搜索框中输入会话 ID、标题、目录或曾经输入的提示词。搜索只在当前页中进行。
+- **恢复会话**：选择目标会话后点击“恢复”；也可以双击目标会话，或使用上下方向键选择后按回车。iCode 会关闭当前对话视图，加载所选会话，并将工作目录切换到该会话保存时的主工作目录；当前会话仍会保存在列表中。恢复前可通过列表中的“目录”列核对将要恢复的工作目录。如果该目录已不存在，iCode 会请你选择另一个文件夹，详见[工作目录被删除或移动时](workspaces.md#工作目录被删除或移动时)。
+
+恢复较长的对话时，iCode 会先显示最近的内容，可立即继续操作；更早的消息会在随后几秒内陆续加载到上方。
+
+如果恢复的对话改用了与之前不同的模型服务，部分早先的推理内容可能会被略去，详见[切换当前模型配置](../configuration/models.md#切换当前模型配置)。
+
+## 删除旧会话
+
+打开“聊天会话”窗口，先核对会话 ID、目录和最近活跃时间。不确定时，可以先恢复会话确认内容，再返回“聊天会话”窗口。选择不再需要的会话，点击“删除”。
+
+确认删除后，该会话的对话历史、回滚快照和会话内诊断数据等内容会被永久删除，无法恢复。删除会话不会撤销智能体已对工作目录文件做出的修改。
+
+删除当前会话时，iCode 会同时开始新会话，与 `/clear` 类似。其他 iCode 实例正在使用的会话无法删除，请先关闭该实例。
+
+## 查找会话 ID 和会话保存位置
+
+当前会话 ID 显示在主界面左上角的“会话：…”区域；历史会话 ID 显示在“聊天会话”窗口的列表中。
+
+输入 `/settings sessions`，或按 **F10** 后选择“会话”标签页，“会话存储根目录”下方的“使用中”会显示当前实际使用的 `sessions` 目录。每个会话保存在该目录下以会话 ID 命名的子目录中。
+
+未自定义会话存储根目录时，macOS 和 Linux 的 `sessions` 目录默认为 `~/.chrys/sessions`，Windows 默认为 `%APPDATA%\chrys\sessions`。
+
+## 迁移会话存储位置
+
+更换会话存储位置时，需要设置新的会话存储根目录，并将已有会话迁移到新位置。新位置在重启后生效；仅修改存储位置不会自动迁移已有会话。
+
+开始前，结束当前任务并关闭其他 iCode 实例，然后执行以下操作：
+
+1. 输入 `/settings sessions`，或按 **F10** 后选择“会话”标签页，然后在“会话存储根目录”中选择新的根目录。
+2. 点击“迁移会话”。确认“从”是当前使用的 `sessions` 目录，“到”是新根目录下的 `sessions` 目录，然后点击“迁移”。
+3. 等待迁移完成，并根据结果处理未复制的会话：
+
+   | 结果 | 说明 | 后续操作 |
+   | --- | --- | --- |
+   | 已复制 | 会话已复制到目标目录。 | 无需处理。 |
+   | 已存在 | 目标中已有同一会话 ID，因此跳过。iCode 不会比较或更新目标内容。 | 无法确认目标版本时，建议更换空的目标目录重新迁移，或保留源数据。 |
+   | 使用中 | 会话正在某个 iCode 实例中打开，因此跳过。 | 关闭其他实例后重试。若是当前会话，关闭设置窗口并执行 `/new`；不要在新会话中发送消息，然后再次迁移。 |
+   | 忙碌 | 会话正在保存或被其他操作占用，因此跳过。 | 等待相关操作结束后重试。 |
+   | 失败 | 会话复制失败。 | 根据窗口列出的路径和原因处理权限或路径问题后重试。 |
+
+4. 处理“使用中”“忙碌”或“失败”的会话后，点击“关闭”，再点击“迁移会话”重新迁移（每次迁移完成后“迁移”按钮会被禁用），直到需要保留的会话均已复制。
+5. 关闭所有 iCode 实例并重新启动，再按 **F1** 打开“聊天会话”窗口，确认重要会话已经出现并可以恢复。
+
+迁移完成后，源目录会保留原数据，不会自动删除。确认迁移完整后，如需释放空间，关闭 iCode，再归档或删除迁移窗口中“从”所显示的旧 `sessions` 目录。手工删除无法撤销。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/daily-use/workspaces.md

@@ -0,0 +1,51 @@
+# 工作目录
+
+工作目录是 iCode 执行文件操作和命令时使用的默认目录。在让智能体修改文件前，建议先保存尚未写入磁盘的内容，并使用 Git commit 记录已有变更，以便区分智能体所做的修改，并在需要时恢复到修改前的状态。
+
+## 启动时选择工作目录
+
+在终端中进入项目目录并启动 iCode：
+
+```shell
+cd <project-directory>
+icode
+```
+
+iCode 会将启动时所在的目录作为工作目录。
+
+也可以通过 `-C` 或 `--workdir` 选项指定工作目录，无需先进入项目目录：
+
+```shell
+icode -C <project-directory>
+```
+
+## 在会话中切换工作目录
+
+智能体空闲时，可以点击对话区底部边框右侧显示的当前工作目录路径，或在输入栏中输入 `/chdir`，打开“更改目录”窗口。在窗口中浏览并选择目标目录。如需新建文件夹，先点击要放置它的文件夹，再点击“新建文件夹”，输入名称后按 Enter，新文件夹会被自动选中。若目标工作目录最近使用过，可在“收藏”标签页的“最近”分组中选择。
+
+已知目标路径时，在输入栏中输入以下命令可直接切换：
+
+```text
+/chdir <project-directory>
+```
+
+`<project-directory>` 可以是绝对路径，也可以是相对于当前工作目录的路径。如果目标不存在或不是目录，iCode 会提示错误并保留当前工作目录。
+
+切换完成后，对话区底部边框右侧会显示新的工作目录路径。智能体后续的文件读取、命令和其他操作会以新工作目录作为默认位置。
+
+切换工作目录时，iCode 会重新加载当前智能体，并加载新工作目录中的记忆和 Skills（其中的 Skills 仅在勾选“加载项目 Skills”时加载）。具体配置方式参阅[配置记忆](../configuration/memory.md)和[安装和使用 Skills](../extensions/skills.md)。
+
+切换工作目录不会创建新会话，当前对话历史仍会保留。处理无关项目时，建议先输入 `/new` 创建新会话，再在新会话中切换工作目录，避免在原会话中留下工作目录变更记录或混用不同项目的上下文。
+
+## 工作目录被删除或移动时
+
+如果在 iCode 之外（例如在文件管理器或另一个终端中）删除或移动了工作目录，iCode 将无法继续使用它：
+
+- 正在执行的任务会继续运行。需要使用工作目录的命令和文件操作会失败，智能体会告诉你该目录已不存在。
+- 任务结束时，或你发送消息时，iCode 会弹出“工作文件夹不存在”窗口。点击“选择文件夹…”并选择一个文件夹，“更改目录”窗口会定位到仍然存在的最近一级文件夹。iCode 会切换到所选文件夹，并保留当前对话。
+- 你发送的消息会保留在输入栏中，切换后再次发送即可。
+- 如果关闭窗口而未选择文件夹，下次发送消息时窗口会再次弹出。也可以使用 `/chdir` 切换，或将文件夹移回原来的位置。
+
+恢复的会话所保存的工作目录已不存在时，iCode 会请你选择一个文件夹来打开该会话。取消后不会恢复该会话；如果是通过 `-s` 启动 iCode，则会改为创建新会话。
+
+如果在已不存在的目录中启动 iCode，iCode 会提示错误并退出。请进入一个存在的目录，或使用 `-C` 指定项目目录的完整路径，例如 `icode -C ~/projects/my-app`。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/extensions/external-acp-agents.md

@@ -0,0 +1,126 @@
+# 配置外部 ACP 智能体
+
+本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中接入支持智能体客户端协议（Agent Client Protocol，ACP）的外部智能体，并将其添加为主智能体的子智能体。
+
+**外部 ACP 智能体可以作为子智能体或工作流节点使用，不能作为聊天主智能体**。每次调用外部 ACP 智能体时，iCode 都会为本次调用启动外部智能体进程，并通过 ACP 与其通信。任务处理和工具调用由外部智能体负责，审批请求、执行状态、进度更新和最终结果通过 ACP 连接传递。调用结束后，iCode 会关闭连接并终止该进程。
+
+## 准备外部智能体
+
+配置外部智能体前，请确认其满足以下条件：
+
+- 已安装在运行 iCode 的设备上；
+- 支持通过标准输入输出（stdio）运行 ACP 服务；
+- 已完成必要的登录或认证，或已准备好认证所需的环境变量；
+- 可以通过可执行文件及参数启动 ACP 模式。
+
+无需提前启动 ACP 服务。测试连接或调用子智能体时，iCode 会根据配置自动启动外部智能体进程，并通过 stdio 建立 ACP 连接。
+
+首次配置前，建议参考外部智能体的文档，准备以下信息：
+
+- 启动 ACP 模式所需的可执行文件和参数；
+- 所需的认证信息；
+- 可选的会话模式、模型和其他配置项。
+
+其中，会话模式、模型和其他配置项可以在首次配置时填写，也可以在连接成功后根据测试结果补充。
+
+## 创建配置并测试连接
+
+### 创建外部 ACP 智能体配置
+
+1. 打开“智能体配置”窗口。
+2. 点击“新建”，填写名称、显示名称和描述。
+3. 将“智能体类型”改为“外部 ACP”。iCode 会自动将其设置为“仅用作子智能体”。
+4. 打开“ACP 设置”标签页，在“可执行文件”中填写程序名称或路径，并逐项添加启动参数。
+5. 按需添加认证所需的环境变量。外部智能体不会继承 iCode 的环境变量，需要在此添加，详见[使用环境变量](#使用环境变量)。
+6. “会话模式”“模型 ID”和“配置选项”可以暂时留空，完成基础配置后点击“测试”。
+
+“可执行文件”和“参数”需要分开填写。例如，若启动命令为：
+
+```text
+example-agent acp --model example-model
+```
+
+应将 `example-agent` 填入“可执行文件”，并分别将 `acp`、`--model` 和 `example-model` 添加为启动参数。不要将整条命令填写到“可执行文件”中。
+
+> **注意**
+>
+> 将自定义智能体的“智能体类型”从“内置”改为“外部 ACP”时，除名称、显示名称和描述等基本信息外，原有配置会被清除。若需要保留原配置，请新建外部 ACP 智能体。
+
+### 测试连接
+
+测试连接时，iCode 会启动一个临时外部智能体进程，检查能否建立 ACP 会话，但不会发送任务。连接成功后，报告会显示身份、能力、模式、模型、配置选项和认证方式等栏目，并列出外部智能体提供的信息；未提供的信息可能显示“未声明。”“智能体未报告其身份信息。”或留空，这不表示连接失败。
+
+测试结束后，iCode 会关闭该临时进程。
+
+如果连接失败，请依次检查：
+
+- 错误信息和标准错误输出末尾是否说明缺少依赖、参数错误或认证失败；
+- 可执行文件和启动参数是否正确；
+- 认证信息或环境变量是否有效；
+- 配置的工作目录是否存在且允许访问。
+
+### 示例：将 iCode 配置为外部 ACP 智能体
+
+iCode 自身也可以通过 stdio 提供 ACP 服务。可以使用以下配置：
+
+- “可执行文件”：`icode`
+- “参数”：添加 `acp`
+
+以上配置对应启动命令：
+
+```bash
+icode acp
+```
+
+该命令会启动 iCode ACP 服务，默认提供 `Code` 智能体，并使用 `manual` 审批模式。有关 iCode ACP 服务的更多配置和使用说明，请参阅[使用 iCode ACP 服务](../running/icode-acp.md)。
+
+## 使用环境变量
+
+外部智能体不会继承 iCode 运行环境中的环境变量。它启动时只带有一组基本变量（macOS 和 Linux 上为 `HOME`、`LOGNAME`、`PATH`、`SHELL`、`TERM` 和 `USER`；Windows 上为 `APPDATA`、`HOMEDRIVE`、`HOMEPATH`、`LOCALAPPDATA`、`PATH`、`PATHEXT`、`PROCESSOR_ARCHITECTURE`、`SYSTEMDRIVE`、`SYSTEMROOT`、`TEMP`、`USERNAME` 和 `USERPROFILE`），以及智能体配置中设置的环境变量。智能体所需的其他变量，例如 API 密钥或 `HTTPS_PROXY` 等代理设置，请在配置中作为环境变量添加。
+
+在可执行文件、参数、环境变量值和工作目录中，可以使用 `{{ENV_VAR}}` 引用 iCode 运行环境中的环境变量，从而复用已有配置值，避免在智能体配置中直接填写固定值或敏感信息。环境变量名只能包含字母、数字和下划线，且不能以数字开头。
+
+例如，若 API 密钥保存在 `EXTERNAL_AGENT_API_KEY` 环境变量中，可以将外部智能体所需环境变量的值设置为：
+
+```text
+{{EXTERNAL_AGENT_API_KEY}}
+```
+
+保存配置、测试连接以及每次启动外部智能体时，iCode 都会解析引用的环境变量。若对应环境变量不存在或值为空，配置将无法保存，测试连接或调用也会失败。
+
+## 设置工作目录
+
+“工作目录”留空时，外部智能体使用 iCode 当前会话的工作目录。
+
+“工作目录”可以填写相对路径或绝对路径；相对路径以当前会话的工作目录为基准。
+
+默认情况下，外部智能体的工作目录必须位于当前会话的主工作目录或任一附加工作目录内。若要使用上述目录范围之外的目录，请勾选“允许 cwd 位于工作区外”。此选项只放宽目录校验，不会改变外部智能体的文件权限。启用前，请确认外部智能体程序可信，并检查目标目录是否包含敏感文件。
+
+## 调整外部智能体配置
+
+首次测试连接成功后，可以根据测试报告进一步完善外部智能体配置：
+
+- **会话模式**：设置外部智能体的会话模式。填写测试报告中列出的模式 ID。
+- **模型 ID**：指定外部智能体使用的模型。填写测试报告中列出的模型 ID。此设置不影响主智能体使用的模型。
+- **配置选项**：设置外部智能体提供的其他配置项。填写测试报告中对应的配置项 ID 和值。
+
+以上配置项均可留空。留空时，iCode 将使用外部智能体的默认配置。修改配置后，请重新测试连接。
+
+默认情况下，如果外部智能体不支持指定的会话模式或配置选项，连接测试会失败。若希望忽略不支持的设置并继续连接，请启用“尽力应用模式和配置选项”。
+
+“模型 ID”按尽力方式应用。如果外部智能体未列出指定模型，或以“不支持的方法”或“参数无效”错误拒绝切换，iCode 会继续使用外部智能体的默认模型；切换模型时出现其他错误则连接失败。
+
+## 设置结果和超时
+
+“结果”决定主智能体收到的内容：
+
+- **最后一个消息片段**：只返回外部智能体最后一段回复，适合大多数任务。
+- **完整记录**：返回外部智能体在本次调用中发送的所有消息片段，适合需要查看完整回复过程的任务。
+
+“握手超时（秒）”限制启动进程、完成 ACP 初始化和打开会话所等待的时间。“空闲超时（秒；0 表示禁用）”限制调用期间未收到任何活动时的等待时间；设为 `0` 时不限制空闲等待时间。“测试”按钮不使用“握手超时（秒）”，始终最多等待 15 秒；启动较慢的智能体可能测试失败，但实际调用时仍可正常工作。
+
+## 将外部 ACP 智能体添加到主智能体
+
+保存外部智能体配置后，按照[为智能体配置子智能体](../configuration/agents.md#为智能体配置子智能体)中的步骤，将其添加到主智能体。
+
+在“配置”下拉列表中，外部 ACP 智能体的名称带有 `(ACP)` 标记。选择对应的配置并保存即可。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/extensions/hooks.md

@@ -0,0 +1,167 @@
+# 配置和编写 Hooks
+
+钩子（Hooks）用于在指定事件发生时自动运行本地脚本或命令。例如，可以在一轮任务结束后记录结果、在工具运行前检查参数，或在用户提交消息时为模型补充要求。
+
+本指南通过一个简单的示例，介绍如何编写和配置钩子，并提供几个可以按需修改的常用示例。完整的事件列表、配置字段、默认值以及脚本的输入输出格式，请参阅 [Hooks 配置参考](../../reference/hooks.md)。
+
+> **安全提示**
+>
+> 钩子直接使用当前用户的权限运行，不经过工具审批，也不受安全沙箱限制。启用项目自带的钩子前，请检查其配置文件以及运行的脚本和命令。
+>
+> 钩子可能接收对话内容、工具参数和工具运行结果。若钩子会将这些数据发送到外部服务，请注意检查其中是否包含敏感信息。
+
+## 创建第一个钩子
+
+下面将在 iCode 当前会话的工作目录中创建一个项目钩子。它只对当前工作目录生效，并会在每一轮结束后将轮次状态追加到该目录下的 `hook-events.log`。
+
+### 1. 创建配置
+
+创建 `.chrys/hooks/hooks.yaml`：
+
+```yaml
+hooks:
+  - id: record-turn
+    event: after_turn
+    run:
+      type: script
+      path: scripts/record_turn.py
+```
+
+`id` 是钩子的稳定标识，在同一个配置文件中不能重复；这里将它命名为 `record-turn`。
+
+这项配置在 `after_turn` 事件发生时运行 `scripts/record_turn.py`。相对脚本路径以钩子配置文件所在目录为基准，因此这里指向下一步创建的 `.chrys/hooks/scripts/record_turn.py`。
+
+### 2. 创建脚本
+
+创建 `.chrys/hooks/scripts/record_turn.py`：
+
+```python
+import json
+import os
+from pathlib import Path
+
+with open(os.environ["CHRYS_HOOK_PAYLOAD_FILE"], encoding="utf-8") as payload_file:
+    payload = json.load(payload_file)
+
+with Path("hook-events.log").open("a", encoding="utf-8") as log_file:
+    log_file.write(f"turn={payload['turn']} status={payload['status']}\n")
+```
+
+iCode 通过 `CHRYS_HOOK_PAYLOAD_FILE` 环境变量提供本次事件的 JSON 输入文件。`after_turn` 事件的输入包含 `turn` 和 `status`，分别表示轮次编号和结束状态。脚本默认在 iCode 当前会话的工作目录中运行，所以 `hook-events.log` 也会写到工作目录。
+
+### 3. 加载并验证
+
+项目钩子默认不加载。在终端用户界面（Terminal User Interface，TUI）中按 **F10** 打开“设置”，在“安全”-“项目信任”区域勾选“加载项目钩子”。如果已经勾选，切换会话或重启 iCode，使磁盘上的配置生效。
+
+在 TUI 中输入 `/runtime`，打开“钩子”标签页，应能看到 `record-turn`。提交一条消息并等待当前轮结束后，检查工作目录中的 `hook-events.log`。文件应出现类似内容：
+
+```text
+turn=1 status=ok
+```
+
+## 示例：按工具参数阻止操作
+
+需要在工具运行前检查或拒绝操作时，使用 `before_tool_call` 事件和阻塞式执行。下面的示例阻止文件写入工具修改名为 `.env` 的文件。
+
+先把以下条目加入 `.chrys/hooks/hooks.yaml` 的 `hooks` 列表：
+
+```yaml
+  - id: protect-env
+    event: before_tool_call
+    match:
+      tool_kind: filesystem.write
+      args:
+        path:
+          regex: "(^|[\\\\/])\\.env$"
+    run:
+      type: script
+      path: scripts/protect_env.py
+    execution:
+      mode: blocking
+      timeout_seconds: 5
+      on_error: block
+```
+
+这段配置只匹配具有 `path` 参数，并且路径以 `.env` 结尾的 `filesystem.write` 工具调用。阻塞式钩子会在 iCode 继续处理调用前完成。
+
+然后创建 `.chrys/hooks/scripts/protect_env.py`：
+
+```python
+import json
+import os
+
+with open(os.environ["CHRYS_HOOK_RESULT"], "w", encoding="utf-8") as result_file:
+    json.dump(
+        {"action": "block", "reason": "不允许通过文件写入工具修改 .env"},
+        result_file,
+        ensure_ascii=False,
+    )
+```
+
+脚本通过 `CHRYS_HOOK_RESULT` 指定的结果文件返回 `action: block` 和拒绝原因。脚本打印到标准输出或标准错误的内容不作为操作决定读取，iCode 对两者各最多保留 256 KiB（开头和结尾）。
+
+`on_error: block` 表示脚本无法启动、超时或返回非零退出码时也拒绝工具调用，适合需要失败时保持限制的检查。这个钩子只会阻止匹配的 `filesystem.write` 调用；Shell 命令不受影响。
+
+切换会话或重启 iCode 后，先创建一个专门用于验证的 `hook-demo/.env`，写入已知内容，例如 `HOOK_TEST=unchanged`。然后要求智能体仅使用 `write_file` 或 `edit_file` 尝试修改一次，被拒绝后停止，不使用 Shell 或其他方式。检查该工具调用是否在执行前被拒绝，并显示脚本提供的原因；再确认文件内容保持不变。验证后可以删除 `hook-demo/.env`。
+
+## 示例：为模型添加系统提醒
+
+`user_prompt_submit` 钩子可以在用户提交消息时，为模型补充要求或提示。下面的示例只对 Code 智能体生效，并提醒它在修改 Python 文件后运行项目测试。
+
+先把以下条目加入 `.chrys/hooks/hooks.yaml` 的 `hooks` 列表：
+
+```yaml
+  - id: remind-python-tests
+    event: user_prompt_submit
+    match:
+      profile: Code
+    run:
+      type: script
+      path: scripts/remind_python_tests.py
+    execution:
+      mode: blocking
+      timeout_seconds: 5
+```
+
+然后创建 `.chrys/hooks/scripts/remind_python_tests.py`：
+
+```python
+import json
+import os
+
+with open(os.environ["CHRYS_HOOK_RESULT"], "w", encoding="utf-8") as result_file:
+    json.dump(
+        {"system_reminder": "修改 Python 文件后，运行与改动相关的测试。"},
+        result_file,
+        ensure_ascii=False,
+    )
+```
+
+切换会话或重启 iCode，使配置生效。系统提醒只有在阻塞式钩子成功结束后才会生效。iCode 会用 `<system-reminder>` 标签包住提醒内容，随用户提交的消息一起发送给模型。这段提醒不会显示在 TUI 对话中，也不会写入会话数据。
+
+如需确认 `user_prompt_submit` 钩子是否生效，或查看系统提醒发送给模型时的实际内容，可以检查模型请求的原始 HTTP 日志。该日志包含未脱敏的 API 密钥和完整对话内容，应仅在排查问题时临时启用。在 TUI 中按 **F10**，进入“安全”-“诊断”，开启“捕获原始 HTTP 流量”，然后重启 iCode。使用 Code 智能体提交一条消息后，在当前会话目录的 `llm_raw_http.jsonl` 中搜索提醒正文“修改 Python 文件后”。当前会话目录的位置参阅[查找会话 ID 和会话保存位置](../daily-use/sessions.md#查找会话-id-和会话保存位置)。验证完成后，应关闭原始 HTTP 流量捕获并再次重启 iCode。
+
+如果只想在部分任务中添加提醒，可以让脚本读取 `CHRYS_HOOK_PAYLOAD_FILE` 中的 `text`（用户刚提交的消息），并只在消息符合条件时向 `CHRYS_HOOK_RESULT` 写入 `system_reminder`。
+
+## 选择运行方式
+
+多数钩子只需根据“当前操作是否必须等待结果”选择执行方式：
+
+| 需求 | 建议模式 | 行为 |
+| --- | --- | --- |
+| 在操作继续前检查、拒绝或修改操作 | `blocking` | iCode 等待钩子结束；部分事件会采用结果文件中的操作决定 |
+| 不阻塞当前操作，但希望 iCode 在当前轮或会话结束时等待一段时间 | `async` | iCode 立即继续，之后在适用的事件和等待上限内等待钩子完成 |
+| 普通通知或允许被退出打断的记录任务 | `fire_and_forget` | iCode 立即继续，结束当前轮或会话时也不等待；这是默认模式 |
+
+异步钩子（`async`）不会延迟触发它的事件或当前操作。当前轮或会话结束时，如果相应的异步钩子仍在运行，iCode 会等待它完成后再结束当前轮或会话。`user_interrupt` 触发的异步钩子不会被等待。会话结束时的等待上限可在[全局设置](../../reference/hooks.md#全局设置)中配置。需要在 iCode 退出后重试未完成的任务时，还应配置 `delivery: durable`。
+
+## 使用全局钩子
+
+前面的示例都放在当前工作目录的 `.chrys/hooks` 中，只对该工作目录生效。需要在所有工作目录使用同一个钩子时，可以改用全局配置：
+
+| 平台 | 全局配置文件 |
+| --- | --- |
+| macOS 和 Linux | `~/.chrys/hooks/hooks.yaml` |
+| Windows | `%APPDATA%\chrys\hooks\hooks.yaml` |
+
+项目配置和全局配置可以同时加载。两处钩子的执行顺序、同名 ID 和 `settings` 合并规则见[多个钩子的执行顺序与配置合并](../../reference/hooks.md#多个钩子的执行顺序与配置合并)。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/extensions/mcp.md

@@ -0,0 +1,95 @@
+# 连接 MCP 服务器
+
+模型上下文协议（Model Context Protocol，MCP）服务器可以为 iCode 智能体提供外部工具、提示词模板和使用说明。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中连接 HTTP 或 STDIO MCP 服务器、配置可调用的工具，以及控制是否加载提示词模板、是否将服务器使用说明加入模型上下文。
+
+连接 MCP 服务器前，请确认服务器来源可信。服务器可能接收工具调用参数，并访问本机文件、网络服务或账号数据；其提供的提示词模板和使用说明也可能影响智能体的行为。
+
+## 添加 MCP 服务器配置
+
+在输入栏中输入 `/agents mcp`，打开当前智能体的“MCP”标签页。添加的服务器配置只对当前智能体生效，不会自动应用到其他智能体。
+
+每个服务器对应一张卡片。已保存的服务器默认折叠，只显示名称；点击名称可展开或折叠。保存时如果发现问题，有问题的卡片会自动展开。要删除服务器，点击卡片上的“✕”并确认。
+
+点击“+ 添加”，然后在列表顶部新增的卡片中填写以下字段：
+
+1. 填写“服务器名称”。名称用于在当前智能体的 MCP 配置中标识该服务器。同一个智能体的 MCP 配置中，服务器名称不能重复，且不区分大小写。
+2. 可选填写“描述”，用于备注服务器的用途。该描述不会作为服务器使用说明提供给智能体。
+
+HTTP 请求头值和 STDIO 环境变量值都可以使用 `{{ENV_VAR}}` 引用启动 iCode 前已经设置的环境变量。环境变量名只能包含字母、数字和下划线，且不能以数字开头。
+
+接下来，根据服务器的连接方式完成 HTTP 或 STDIO 设置。
+
+### 使用 HTTP 连接
+
+1. 将“传输方式”设为 `HTTP`。
+2. 填写服务器 URL。URL 必须以 `http://` 或 `https://` 开头。
+3. 如果服务器需要认证，在“请求头”中添加名称和值。可以用 `{{ENV_VAR}}` 引用启动 iCode 前已经设置的环境变量，例如：
+
+   ```text
+   名称：Authorization
+   值：Bearer {{MCP_API_TOKEN}}
+   ```
+
+4. 如果当前网络要求该服务器不经过系统代理，启用“绕过代理”。
+5. 建议保持 TLS 证书验证开启。如果需要连接已确认可信的自签名服务器，可以启用“跳过 TLS 验证”。启用后，iCode 不会验证 HTTPS 服务器证书，无法确认连接的是预期服务器。
+
+### 使用 STDIO 连接
+
+1. 将“传输方式”设为 `STDIO`。
+2. 在“命令”中填写用于启动服务器的程序名称或路径以及所需参数。TUI 会将这行内容拆分并分别保存到智能体 YAML 的 `command` 和 `args` 字段；手工编辑 YAML 时，应将可执行文件写入 `command`，将参数逐项写入 `args`。
+3. 按需添加该进程需要的环境变量。变量值可以直接填写，也可以用 `{{ENV_VAR}}` 引用启动 iCode 前已经设置的环境变量。
+
+STDIO 连接会在本机启动指定程序。如果启动命令会下载或运行第三方软件包或脚本，应先确认其来源可信并检查相关内容。
+
+## 配置说明、工具和请求选项
+
+以下设置同时适用于 HTTP 和 STDIO 服务器。
+
+### 服务器说明与提示词模板
+
+- **将服务器使用说明加入模型上下文（如有）**：新建配置默认启用。启用后，服务器说明会加入模型上下文，并可能影响智能体的行为。
+- **将服务器提示词模板加载为工具（如有）**：新建配置默认启用。启用后，服务器提供的提示词模板会作为可调用工具加入模型工具列表。
+
+### 工具访问
+
+- **可用工具范围**：控制允许智能体使用的服务器工具。可以选择“全部服务器工具”、“仅选定工具”或“无工具”。
+
+选择“仅选定工具”时，填写以 `,` 分隔的工具名称列表。如果还不清楚服务器提供的工具名称，可以先选择“全部服务器工具”，再按照[测试并保存](#测试并保存)中的步骤从连接报告查看工具名称。
+
+### 工具加载
+
+- **加载策略**：控制工具何时提供给智能体。选择“全部加载 — 一开始就加载全部可用工具”时，“可用工具范围”内的所有工具在任务开始时即可使用。选择“按需加载 — 需要时再加载工具”时，任务开始时仅提供“初始可见工具（可选）”中的工具，智能体可在需要时加载“可用工具范围”内的其他工具。服务器提供的工具较多、常用工具较少时，按需加载可以减少任务开始时发送给模型的工具信息。
+- **初始可见工具（可选）**：使用“按需加载 — 需要时再加载工具”时，可以填写以 `,` 分隔的工具名称列表。填写的工具必须包含在“可用工具范围”中。
+
+例如：
+
+- 服务器只提供 `search` 和 `read_file`，并且两者经常使用，可以选择“全部加载 — 一开始就加载全部可用工具”。
+- 服务器提供几十个工具，但通常只使用 `search` 和 `read_file`，可以选择“按需加载 — 需要时再加载工具”，并将这两个工具填入“初始可见工具（可选）”。
+
+使用 Claude Opus 5.5、Fable 5.1 或 Sonnet 5.5 时，按需加载有额外代价。这些模型会把返回的思考内容与它之前的对话绑定，包括智能体当时可用的工具。智能体加载或卸载工具，或下一个任务重新只从初始可见工具开始时，这部分对话就会变化，模型服务可能略去早先的思考内容，或拒绝读回这些内容。如果服务拒绝，iCode 会去掉早先的思考内容，再发送一次请求，这会多发一次请求。无论是服务略去，还是 iCode 去掉后重发，模型都不再看到那部分早先的推理。设为 `thinking_block_binding: error` 时，iCode 会直接报告这次拒绝，不会重发。相关设置详见 [Claude 思考设置](../configuration/models.md#claude-思考设置)。
+
+### 命名与限制
+
+- **工具名称前缀**：为该服务器的工具名称添加前缀，并使用 `_` 连接前缀与原名称。例如，前缀 `github` 会将工具 `search` 显示为 `github_search`。不同服务器或内置工具存在同名工具时，可以用前缀避免冲突。
+- **MCP 请求超时（秒）**：限制单次 MCP 请求等待时间；留空时使用界面显示的默认值。
+
+## 测试并保存
+
+1. **启用/停用服务器**：如需启用 MCP 服务器，保持勾选配置卡片左下角的“启用”选项。如需保留配置但暂时停用服务器，取消勾选该选项。停用后，服务器不会向智能体提供工具、提示词模板或使用说明。
+2. **测试服务器连接**：点击服务器配置卡片右下角的“测试”。iCode 会尝试连接服务器，并在连接报告中显示服务器身份、声明的能力和使用说明，以及当前配置下可用的工具和提示词模板。
+3. **保存配置**：点击“保存”。如果修改的是当前会话正在使用的智能体，保存后的 MCP 配置会用于后续请求。
+
+如果测试失败：
+
+- HTTP 服务器应检查 URL、认证请求头、环境变量以及代理和 TLS 设置。
+- STDIO 服务器应先查看连接错误中显示的可执行文件、工作目录、进程退出码和标准错误输出末尾，再核对命令、参数和环境变量，并确认命令能在所示工作目录中启动。iCode 只显示有限长度的标准错误输出；需要完整日志时，请按照服务器文档启用日志记录。分享诊断信息前，请移除令牌、凭据等敏感信息。
+
+## 验证 MCP 工具调用
+
+关闭智能体配置窗口，提交一项需要使用该服务器工具的低风险任务。例如，如果服务器提供只读搜索工具，可以要求智能体搜索一条明确的数据。
+
+对话中应显示对应的 MCP 工具调用卡片，并返回服务器提供的数据。若弹出“工具审批”对话框，请先核对工具名称和调用参数，再决定是否批准。有关审批方式，请参阅[配置审批模式](../configuration/approval.md)。
+
+如果工具返回的图像、音频或文件无法解码，智能体会收到一条简短说明代替该项，结果的其余内容照常送达。工具返回的链接会以文字（名称、地址和描述）交给智能体。
+
+如果连接测试成功，但对话中工具不可用，请检查服务器是否已启用、工具是否出现在连接报告中，以及是否包含在“可用工具范围”中。