iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/en/start/getting-started.md

@@ -0,0 +1,170 @@
+# Getting started with iCode
+
+This tutorial shows how to install iCode, configure a model, and use agents to complete a development task in a project.
+
+## 1. Install iCode
+
+Install iCode with [uv](https://docs.astral.sh/uv/getting-started/installation/). If Python 3.14 is not on your system, uv downloads it for you:
+
+```shell
+uv tool install iCode-TUI
+```
+
+To upgrade later, run `uv tool upgrade iCode-TUI`; to remove iCode, run `uv tool uninstall iCode-TUI`.
+
+Windows (x64) and Linux (x86-64 or ARM64, glibc 2.27 or later) need nothing else. On a Mac with Apple silicon, first install the Xcode Command Line Tools with `xcode-select --install`; uv uses them to build one dependency during installation.
+
+If you used an iCode offline package before, remove it first. Delete the folder it unpacked into: `~/Library/Application Support/pyapp/chrys` on macOS, `~/.local/share/pyapp/chrys` on Linux (or `$XDG_DATA_HOME/pyapp/chrys` if you set `XDG_DATA_HOME`), or `%LOCALAPPDATA%\pyapp\data\chrys` on Windows. Then delete `~/.local/bin/chrys` on macOS or Linux, or the `%LOCALAPPDATA%\chrys\bin` folder on Windows.
+
+If uv reports that `icode` already exists, an earlier iCode offline install or another program with the same name is in the way. If it is iCode, run `uv tool install --force iCode-TUI` to replace it.
+
+### Offline packages
+
+On an Intel Mac, Windows on Arm, an older Linux, or a device without internet access, use the prebuilt offline packages from [iCode Releases](https://github.com/openJiuwen-ai/iCode/releases) instead. The packages include Python and every dependency, so you do not need to install Python separately.
+
+In the commands below, `<version>` and `<architecture>` are placeholders. Replace them with the actual values in the downloaded filename.
+
+#### macOS
+
+Choose `icode-macos-aarch64-v<version>-offline.tar.gz` for Apple silicon or `icode-macos-x86_64-v<version>-offline.tar.gz` for Intel, then run the following in your download directory:
+
+```bash
+tar xzf icode-macos-<architecture>-v<version>-offline.tar.gz
+chmod +x ./icode
+./icode install
+```
+
+#### Linux
+
+Choose `icode-linux-x86_64-v<version>-offline.tar.gz` or `icode-linux-aarch64-v<version>-offline.tar.gz` for your processor, then run the following in your download directory:
+
+```bash
+tar xzf icode-linux-<architecture>-v<version>-offline.tar.gz
+chmod +x ./icode
+./icode install
+```
+
+The Linux x86-64 package requires glibc 2.17 or later, and the ARM64 package requires glibc 2.18 or later. Distributions that provide only musl, such as Alpine Linux, are not supported by the prebuilt packages.
+
+#### Windows
+
+Download and extract `icode-windows-x86_64-v<version>-offline.zip`, or `icode-windows-aarch64-v<version>-offline.zip` on Windows on Arm. Open PowerShell, go to the extracted directory, and run:
+
+```powershell
+.\icode.exe install
+```
+
+The installer attempts to add iCode to the current user's `PATH`. Open a new terminal after installation.
+
+### Verify the installation
+
+```shell
+icode --version
+```
+
+The command should print the iCode version number. If you installed with uv and your terminal cannot find `icode`, run `uv tool update-shell` and open a new terminal.
+
+With an offline package, if your system cannot find `icode` on macOS or Linux, add `~/.local/bin` to `PATH` as the installer instructs. If the installer reported that `~/.local/bin/icode` already exists, that command starts another program; use `chrys` instead. On Windows, open a new terminal; if the installer reported that updating the user PATH failed, add `%LOCALAPPDATA%\chrys\bin` to your user `PATH` manually.
+
+## 2. Start iCode in a project
+
+Start this tutorial in a project managed with Git or one that you can safely restore. Before asking an agent to modify files, save any unsaved content and record existing changes with a Git commit. This lets you distinguish the agent's changes and restore the previous state if needed.
+
+In a terminal, go to the project directory and start iCode:
+
+```shell
+cd <project-directory>
+icode
+```
+
+Replace `<project-directory>` with the actual path to your project. To switch directories after startup, see [Working directory](../guides/daily-use/workspaces.md).
+
+## 3. Configure a model
+
+1. Press **F4** or click `f4 Models` at the bottom of the screen to open the **Model Configuration** dialog.
+2. Click **New**.
+3. Enter a **Profile Name** of your choice, such as `My Model`.
+4. In the **Model Options** section, select the **Provider** and **API Style**. Only OpenAI and DeepSeek (OpenAI) provide an API Style option. Before configuring it, check the model service's documentation for supported APIs and follow its recommendation when choosing **Chat Completions** or **Responses**. If the service supports only one API, select its corresponding style; if it supports both, choose according to the service's recommendation or your needs.
+5. Enter the model ID in the **Model** field, and fill in the **Base URL** and **API Key** fields as required by the model service. These field names start with the selected provider, for example **OpenAI Model**.
+6. Set **Max Context Window** and the **Max Output Tokens** field according to the model provider's documentation.
+7. Save the profile and close the dialog. If no model profile was previously available, this profile automatically becomes the active model profile.
+
+> **Tip**
+>
+> An API key entered directly is stored locally in the model profile file. To avoid writing the key to that file, [provide the API key through an environment variable](../guides/configuration/models.md#provide-an-api-key-through-an-environment-variable).
+
+### Verify the model connection
+
+Submit the following in the input field:
+
+```text
+Hello
+```
+
+iCode should reply with a greeting. If the model service returns an error, check the model profile again, including the model ID, base URL, and API key.
+
+## 4. Use agents
+
+### Select an agent
+
+iCode provides two main agents by default: Q&A Agent and Code Agent. Both can read the project, analyze code, and discuss approaches, but they have different roles and tools. Q&A Agent primarily provides read-only capabilities for understanding projects, explaining code, and analyzing problems. Code Agent can modify files and run commands, making it suitable for writing, reviewing, refactoring, debugging, and validating code.
+
+You can switch agents when no agent task is running. Type `#` in the input field to display the agent list above it. Select an agent by clicking it, or use the up and down arrow keys and press Enter. You can also click the agent name in the status bar above the input field to switch agents in the agent selection dialog.
+
+### Use Q&A Agent
+
+Q&A Agent helps you understand a project, analyze code, trace implementations, and discuss approaches **without modifying the project**. It answers based on the project contents and aims to provide evidence you can trace back to its source.
+
+After switching to **Q&A Agent**, type `/new` in the input field and press Enter to start a new session.
+
+The following examples assume the current project is a to-do app and illustrate how to use the agents. Adapt the questions and tasks to your own project.
+
+```text
+Analyze the task list implementation and propose a plan for adding a "Clear completed tasks" feature. Explain which files need to change and the implementation steps.
+```
+
+Q&A Agent may search for files, read their contents, or run read-only commands. Tool calls appear as cards. After completing its analysis, the agent presents an implementation plan.
+
+### Use Code Agent
+
+Code Agent handles tasks that require **modifying files, running commands, and validating results**. It reads the relevant code first, then implements, debugs, or refactors it as requested.
+
+After Q&A Agent provides an implementation plan, you can switch to **Code Agent** in the same session. Switching agents preserves the current session's context, so Code Agent can continue the development task using the existing plan:
+
+```text
+Implement the "Clear completed tasks" feature using the plan we just discussed. Modify the code and run the necessary tests.
+```
+
+If an approval dialog appears, review the tool call before approving it. Pay particular attention to the command, target files, and scope of its effects, and approve only when they match your expectations. For the behavior of each approval mode, see [Configure approval modes](../guides/configuration/approval.md).
+
+When the task is complete, review the agent's final response and use `/diff` to browse the file changes recorded in the current session. Then use Git or another version control tool to inspect the complete working directory changes. Confirm that the feature works correctly, the necessary tests pass, and there are no unrelated changes. Once you have verified the changes, you can commit them.
+
+### Read and copy replies
+
+All agents' replies support Markdown, formulas and Mermaid diagrams. Formulas in your own messages are not rendered as math.
+
+Lists and quotes can contain headings, tables, code and formulas.
+
+Single-line math is written with `$...$` or `\(...\)`. Display formulas in `math` code blocks, `$$...$$` or `\[...\]` can show fractions, matrices and aligned equations. Ordinary text, prices and shell variables keep their Markdown formatting. Formulas that are unsupported or too wide are shown as complete, wrapped source.
+
+For example, `$x^{n+1}$` displays as xⁿ⁺¹ and `$90^\circ$` as 90°.
+
+Mermaid code blocks appear as diagrams; choose **Open full diagram** to view and scroll the full result. Some diagrams are simplified with a notice; unsupported diagrams stay as source.
+
+Mouse selection copies what is displayed, without adding newlines for screen wrapping. Use **copy** beside the message header to copy the original Markdown and LaTeX. Reopening an older conversation uses the current rendering.
+
+## 5. End the session
+
+To finish using iCode, type `/exit` or press `Ctrl+Q` to exit.
+
+## Next steps
+
+You have installed iCode, configured a model, and learned the basics of Q&A Agent and Code Agent, including how to use them together in the same session to complete a development task.
+
+You can continue exploring:
+
+- [Configure agents](../guides/configuration/agents.md) to create or modify agents and set their instructions, models, tools, and sub-agents
+- [Configure models](../guides/configuration/models.md) to connect to and switch between model services
+- [Working directory](../guides/daily-use/workspaces.md)
+- [Configure approval modes](../guides/configuration/approval.md)
+- Extend iCode with [Skills](../guides/extensions/skills.md) and [MCP](../guides/extensions/mcp.md)

chrys/app/tui/screens/guides/_docs/en/start/what-is-icode.md

@@ -0,0 +1,34 @@
+# What is iCode?
+
+**iCode is a platform for running and building agents.**
+
+iCode lets you interact with agents in natural language to read and edit files, run shell commands, search codebases, and perform other tasks. Complex tasks can also be delegated to sub-agents.
+
+The main way to interact with iCode is through its terminal user interface (TUI), which brings conversations, task execution, and tool calls together in one place. Tool calls appear as cards so you can see what the agent is doing. iCode also supports headless execution in scripts, integration with editors through the Agent Client Protocol (ACP), and running the TUI in a browser.
+
+## Key features
+
+* **Flexible combinations of agents and models.** Switch agents and models with a click in the interface or a quick command, and choose different combinations for different tasks within the same session.
+
+* **Configurable agents.** Configure an agent's instructions, model, tools, skills, MCP servers, and sub-agents through the TUI, or edit its YAML profile directly, without changing the iCode source code.
+
+## Model support
+
+The agent determines how to work, while the model provides reasoning and generation capabilities.
+
+Agents and models are independent in iCode, so you can combine them to suit different tasks. iCode includes built-in agents but does not include model profiles or API credentials. Before first use, create a model profile and connect it to a model service.
+
+iCode currently supports model providers including Anthropic, OpenAI, DeepSeek, and GLM. You can also connect to other model services, including locally hosted models, through OpenAI API-compatible endpoints.
+
+## Using iCode
+
+iCode offers several ways to work, depending on your needs:
+
+- **TUI**: The main iCode interface, suited to interactive tasks. View tool calls, handle approval requests, and switch agents and model profiles within a session.
+- **Headless command-line interface (CLI)**: Run non-interactive tasks with `icode run`, suited to one-off tasks, scripts, and automated workflows.
+- **Browser interface**: [Run the TUI in a browser](../guides/running/icode-serve.md) when you need an interactive interface outside the terminal.
+- **ACP server**: Use iCode as an agent backend for [editors or other development tools that support ACP](../guides/running/icode-acp.md).
+
+For first-time use, start with the TUI. An interactive session is a quick way to learn how agents, models, and tools work together.
+
+When you are ready to start, read [Getting started with iCode](getting-started.md) for installation, model configuration, and your first run.

chrys/app/tui/screens/guides/_docs/index.yaml

@@ -0,0 +1,100 @@
+# Default topic ID when opening the user guide.
+default: intro
+# Locale directory names, in language-switching order.
+locales:
+  - zh-Hans
+  - en
+# Topics appear in declaration order. Paths are relative to each locale directory.
+# Use children for groups and labels for localized display names; leaf titles
+# otherwise come from the Markdown H1.
+topics:
+  - id: start
+    labels:
+      zh-Hans: 快速开始
+      en: Quick Start
+    children:
+      - id: intro
+        path: start/what-is-icode.md
+      - id: getting_started
+        path: start/getting-started.md
+  - id: daily_use
+    labels:
+      zh-Hans: 日常使用
+      en: Daily Use
+    children:
+      - id: sessions
+        path: guides/daily-use/sessions.md
+      - id: workspaces
+        path: guides/daily-use/workspaces.md
+  - id: running
+    labels:
+      zh-Hans: 运行 iCode
+      en: Running iCode
+    children:
+      - id: icode_run
+        path: guides/running/icode-run.md
+      - id: icode_acp
+        path: guides/running/icode-acp.md
+      - id: icode_serve
+        path: guides/running/icode-serve.md
+      - id: workflows
+        path: guides/running/workflows.md
+  - id: configuration
+    labels:
+      zh-Hans: 配置 iCode
+      en: Configuration
+    children:
+      - id: models
+        path: guides/configuration/models.md
+      - id: chat_options
+        path: guides/configuration/chat-options.md
+      - id: agents
+        path: guides/configuration/agents.md
+      - id: tools
+        path: guides/configuration/tools.md
+      - id: web_tools
+        path: guides/configuration/web-tools.md
+      - id: approval
+        path: guides/configuration/approval.md
+      - id: memory
+        path: guides/configuration/memory.md
+      - id: compaction
+        path: guides/configuration/compaction.md
+      - id: settings
+        path: guides/configuration/settings.md
+      - id: theme_editor
+        path: guides/configuration/themes.md
+  - id: extensions
+    labels:
+      zh-Hans: 扩展 iCode
+      en: Extensions
+    children:
+      - id: skills
+        path: guides/extensions/skills.md
+      - id: mcp
+        path: guides/extensions/mcp.md
+      - id: hooks
+        path: guides/extensions/hooks.md
+      - id: external_acp_agents
+        path: guides/extensions/external-acp-agents.md
+  - id: reference
+    labels:
+      zh-Hans: 参考
+      en: Reference
+    children:
+      - id: workflow_reference
+        path: reference/workflows.md
+      - id: tui_slash_commands
+        path: reference/tui-slash-commands.md
+      - id: tool_kinds_and_names
+        path: reference/tool-kinds-and-names.md
+      - id: agent_profile_reference
+        path: reference/agent-profile.md
+      - id: settings_reference
+        path: reference/settings.md
+      - id: opentelemetry_reference
+        path: reference/opentelemetry.md
+      - id: hooks_reference
+        path: reference/hooks.md
+      - id: themes_reference
+        path: reference/themes.md

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

@@ -0,0 +1,178 @@
+# 配置智能体
+
+iCode 使用智能体配置定义智能体的名称、提示词、模型、可调用工具和子智能体等。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中创建、克隆、修改、重置、切换和删除智能体配置，以及如何为智能体设置模型和子智能体。
+
+## 打开智能体配置窗口
+
+可通过以下任一方式打开“智能体配置”窗口：
+
+- 按 **F2**。
+- 点击界面底部的 `f2 智能体`。
+- 在输入栏中输入 `/agents`，按空格键或 **Enter** 显示标签页列表，然后选择要打开的标签页。
+
+“智能体配置”窗口左侧显示已有智能体配置列表，右侧通过不同标签页展示当前选中智能体的配置内容。
+
+通过在 `/agents` 后添加标签名，可以直接打开对应标签页：
+
+| 命令 | 打开的标签页 |
+| --- | --- |
+| `/agents basic` | 基本 |
+| `/agents instructions` | 提示词 |
+| `/agents tools` | 工具 |
+| `/agents sub-agents` | 子智能体 |
+| `/agents skills` | Skills |
+| `/agents mcp` | MCP |
+| `/agents memory` | 记忆 |
+| `/agents compaction` | 压缩 |
+
+任务运行期间，“智能体配置”窗口将以只读模式打开，无法修改或保存配置。请等待任务结束后再进行配置调整。
+
+## 管理智能体配置
+
+### 创建智能体配置
+
+以下步骤用于创建“内置”类型的智能体。如需将外部程序接入为子智能体，请参阅[配置外部 ACP 智能体](../extensions/external-acp-agents.md)。
+
+1. 点击“新建”。
+
+2. 在“基本”标签页中配置智能体基本信息：
+    - 填写名称、显示名称和描述，三个字段均不能为空。其中，“名称”用于标识智能体配置，“显示名称”显示在智能体选择列表和主界面中。“名称”必须以字母或数字开头，只能包含英文字母、数字、连字符（`-`）和下划线（`_`），且不能与已有名称重复（不区分大小写）。
+    - 根据使用场景选择是否勾选“仅用作子智能体”。有关主智能体和子智能体的区别，请参阅[主智能体和子智能体](#主智能体和子智能体)。
+    - 根据需要设置智能体使用的模型。默认使用当前活动的模型配置；如需绑定特定模型配置，请参阅[设置智能体使用的模型](#设置智能体使用的模型)。
+
+3. 在“提示词”标签页中填写系统提示词，用于定义智能体的行为准则。系统提示词不能为空。
+
+4. 根据需要在其他标签页中添加智能体配置：
+    - **工具**：选择智能体可以调用的内置工具。参阅[配置工具](./tools.md)。
+    - **子智能体**：添加该智能体可以调用的子智能体。参阅[为智能体配置子智能体](#为智能体配置子智能体)。
+    - **Skills**：配置智能体加载 Skill 的位置。参阅[安装和使用 Skills](../extensions/skills.md)。
+    - **MCP**：连接 MCP 服务器，并配置智能体可以使用的 MCP 工具。参阅[连接 MCP 服务器](../extensions/mcp.md)。
+    - **记忆**：添加需要自动加载到上下文中的文件或文件夹。参阅[配置记忆](./memory.md)。
+    - **压缩**：调整对话内容较多时的上下文压缩方式。新建的智能体配置会使用默认的上下文压缩设置，通常无需修改。如需修改，请参阅[配置上下文压缩](./compaction.md)。
+
+5. 点击“保存”。
+
+### 克隆智能体配置
+
+需要基于现有智能体创建新的配置时，可以使用克隆功能。克隆会生成一个独立副本，不会修改原智能体配置。克隆内置智能体时，iCode 会创建对应的自定义智能体副本，后续可以独立修改。
+
+1. 在左侧列表中选择要克隆的智能体。
+2. 点击“克隆”。
+3. iCode 会复制原智能体的配置，自动生成不重复的智能体名称和显示名称，并选中生成的副本。
+4. 检查并按需修改副本的名称、显示名称和其他配置。
+5. 点击“保存”完成创建。
+
+**说明：**
+
+- 点击“克隆”后，iCode 会创建一个用于当前配置界面编辑的临时副本，只有点击“保存”后，该配置才会正式创建并保留。
+- 修改配置后，需要点击“保存”才能应用修改；关闭智能体配置窗口前未保存的修改内容不会生效。
+
+### 修改智能体配置
+
+1. 在左侧列表中选择需要修改的智能体。
+2. 在对应标签页中调整配置。
+3. 点击“保存”以应用修改。
+
+**说明：**
+
+- iCode 默认提供的内置智能体（如 Code Agent、Q&A Agent）的“名称”和“智能体类型”不可修改，其他配置可以按需调整。
+- 修改配置后，需要点击“保存”才能应用修改；关闭智能体配置窗口前未保存的修改内容不会生效。
+- 如果修改的是当前会话正在使用的智能体，保存后，新配置将在后续请求中生效。
+
+### 删除自定义智能体配置
+
+删除自定义智能体后，保存在本机的相关配置也会被移除，且无法在 iCode 中撤销。内置智能体不能删除。
+
+删除自定义智能体前，需要满足以下条件：
+
+- 至少保留一个可用的主智能体。
+- 如果该智能体仍被其他智能体配置为子智能体，需要先移除相关引用。
+
+按以下步骤删除自定义智能体：
+
+1. 在左侧列表中选择要删除的自定义智能体。
+2. 点击“删除”。
+3. 在确认窗口中核对智能体名称，然后确认删除。
+
+如果删除的是当前正在使用的智能体，关闭配置窗口后，iCode 会自动切换到其他可用的主智能体。
+
+### 重置内置智能体配置
+
+iCode 默认提供的内置智能体不支持删除。
+
+修改内置智能体并保存后，iCode 会在[用户智能体配置目录](../../reference/agent-profile.md#用户智能体配置目录)中生成同名的用户配置文件，例如 `Code.yaml`。该文件会保存修改内容以及当时生效的其他设置。例如，只新增一个 MCP 服务器时，保存后的配置既包含这个 MCP 服务器，也保留其他设置当时的值。
+
+启动时，iCode 会优先使用同名的用户配置文件，而不会将用户配置与内置配置逐项合并。因此，升级 iCode 后，新版本对内置智能体提示词等默认设置的更新不会自动应用到该智能体。
+
+如需采用当前版本的内置默认设置，可以重置内置智能体。重置只保留 Skills、MCP 服务器和记忆设置；提示词、压缩设置及其他设置均恢复为当前版本的内置默认值。
+
+按以下步骤重置：
+
+1. 在左侧列表中选择要重置的内置智能体。
+2. 点击“重置”，然后在确认窗口中再次点击“重置”。
+3. 如果“保存”按钮可用，点击“保存”应用重置结果。如果该按钮不可用，表示当前配置已经符合上述重置结果，无需保存。
+
+重置产生的修改在保存前只会暂存在设置窗口中。关闭窗口会放弃尚未保存的修改。
+
+重置后，如果不再存在同名的用户配置文件，后续升级会直接采用新版内置配置。如果该文件因保留了自定义的 Skills、MCP 服务器或记忆设置而继续存在，以后升级时仍需再次重置，才能同步新版的内置默认设置。
+
+## 配置模型和子智能体
+
+### 设置智能体使用的模型
+
+新创建的智能体默认使用当前活动的模型配置，切换当前使用的模型后，智能体使用的模型也会随之切换。
+
+如果希望智能体始终使用特定模型配置：
+
+1. 在左侧列表中选择智能体，然后打开“基本”标签页。
+2. 取消勾选“使用当前生效的模型配置”（标签中也会显示当前配置）。
+3. 在下拉列表中选择要绑定的模型配置。如需新增或修改模型配置，请参阅[配置模型](./models.md)。
+4. 点击“保存”，然后关闭配置窗口。
+
+如果当前使用的主智能体绑定了特定模型配置，状态栏中的模型配置名称将灰度显示。点击它不会切换模型，而是提示该智能体绑定的是哪个模型。
+
+若要重新通过状态栏切换模型，请在该智能体的“基本”标签页中勾选“使用当前生效的模型配置”，点击“保存”，然后关闭配置窗口。
+
+### 主智能体和子智能体
+
+主智能体直接与用户交互，子智能体则由其他智能体调用，负责完成分派的任务。
+
+一项智能体配置既可以作为主智能体，也可以被其他智能体作为子智能体调用。勾选“仅用作子智能体”后，该智能体不能再被选作主智能体，仅可以被其他智能体调用。
+
+iCode 默认提供的 Code Agent 和 Q&A Agent 可以作为主智能体，Explore 和 General 仅用作子智能体。外部 ACP 智能体也仅用作子智能体，配置方法请参阅[配置外部 ACP 智能体](../extensions/external-acp-agents.md)。
+
+### 为智能体配置子智能体
+
+为智能体添加子智能体后，该智能体可以在执行任务时按需调用子智能体完成部分工作。
+
+在智能体配置页面中，按照以下步骤配置子智能体：
+
+1. 在左侧列表中选择需要配置子智能体的智能体。
+2. 打开“子智能体”标签页。
+3. 点击“+ 添加”，选择要添加的子智能体。
+4. 配置子智能体的“工具名称”、“工具描述”和“最大并发数”。
+5. 根据需要调整页面顶部的“最大总并发数”。
+6. 点击“保存”。
+
+其中：
+
+- “工具名称”和“工具描述”用于帮助智能体识别和使用子智能体。未填写时，分别默认使用子智能体自身的配置名称和描述。
+- “最大并发数”用于限制单个子智能体的同时调用数量；“最大总并发数”用于限制所有子智能体的同时调用总数量。
+
+智能体在执行任务时，会根据子智能体的工具名称和工具描述判断是否向其分派任务。也可以在输入框中指定使用某个子智能体，例如：`调用 <工具名称> 完成 <任务>`。对应的子智能体工具成功返回结果，说明配置已经生效。
+
+子智能体将最终回复返回给调用它的智能体。子智能体在工具调用之间输出的文本显示在其卡片中，但不会返回。最终回复无文本时，将子智能体输出的全部文本按顺序拼接后返回。子智能体失败时，其卡片显示失败原因。外部 ACP 智能体返回的内容由其“结果”设置决定，参阅[设置结果和超时](../extensions/external-acp-agents.md#设置结果和超时)。
+
+**注意**：
+
+- 添加、移除或修改子智能体配置后，必须点击“保存”才能生效。未保存便关闭智能体配置窗口时，本次修改将被丢弃。
+- 智能体不能将自身配置为子智能体，也不能在同一配置中重复添加同一个子智能体。
+
+## 切换当前使用的智能体
+
+可以通过输入栏或状态栏切换当前使用的智能体：
+
+- **通过输入栏切换**：在输入栏中输入 `#`，输入栏上方会显示可用的智能体列表。通过鼠标点击，或使用上下方向键选择智能体后按回车确认。
+- **通过状态栏切换**：点击输入栏上方状态栏中的智能体名称，打开智能体选择窗口，然后选择要使用的智能体。
+
+切换后，iCode 会立即使用所选智能体处理后续请求。当前使用的智能体在列表中以灰色显示，名称前带有空心圆圈。列表仅显示可以作为主智能体使用的配置。

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

@@ -0,0 +1,117 @@
+# 配置审批模式
+
+智能体执行工具调用（例如运行 Shell 命令、写入文件）时，iCode 可能要求先经过审批。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中选择审批模式、处理审批请求，以及不同运行方式下的审批设置。
+
+## 了解三种审批模式
+
+审批模式决定 iCode 如何处理需要审批的工具调用。具体哪些调用需要审批，由智能体配置文件中的 `approval` 审批策略和 iCode 的安全规则共同决定，详见[智能体配置文件参考中的 approval 字段](../../reference/agent-profile.md#approval)。
+
+三种审批模式的行为如下：
+
+| 模式 | 行为 |
+| --- | --- |
+| 手动 | 需要审批的工具调用会弹出对话框，等待人工批准或拒绝。 |
+| 自动 | 由审批裁判模型评估工具调用；判定为安全的调用自动批准，可疑的调用标记出来，等待人工决定。 |
+| 绕过 | 即使智能体配置或安全规则判定需要审批，工具调用也会不经询问直接执行。 |
+
+**审批裁判模型**：“自动”模式会调用审批裁判模型，并将当前时间、工作区目录、本轮全部用户提示及其中最新一条、工具名称、工具类别及参数发送给该模型。审批裁判模型默认使用当前会话的模型。如需修改，按 **F10** 打开“设置”窗口，选择“模型与智能体”标签页，然后在“模型角色”区域修改“审批裁判模型”。
+
+> **提示**
+>
+> **手动模式不代表每次工具调用都会弹窗**。手动模式只表示需要审批的调用由用户决定；不需要审批或符合自动放行条件的调用会直接执行，详见[了解自动放行与安全保护](#了解自动放行与安全保护)。
+
+## 在 TUI 中切换审批模式
+
+在 TUI 中可以使用以下任一方式切换当前使用的审批模式：
+
+- 在输入栏中输入 `/approval`，按空格键或 **Enter** 打开审批模式列表，然后选择模式。也可以直接指定模式，例如 `/approval auto`。
+- 点击界面右上角的审批模式标签，在“审批模式”窗口中选择。
+
+任务运行期间也可以切换模式。已弹出的审批请求不受影响，后续工具调用将使用新模式。
+
+### 设置默认审批模式
+
+未更改默认设置时，首次启动 TUI 默认使用“手动”审批模式。切换当前审批模式时，iCode 也会更新下次启动的默认模式：选择“手动”或“自动”会将所选模式保存为默认值；选择“绕过”只对当前运行生效，为避免重启后继续绕过审批保护，此时下次启动的默认模式会保存为“自动”。
+
+若只需修改下次启动的默认模式，而不改变当前使用的审批模式，请按 **F10** 打开“设置”窗口，在“安全”标签页中修改“默认审批模式”。“设置”窗口不提供“绕过”模式作为可保存的默认值。
+
+## 在 TUI 中处理审批请求
+
+需要审批的工具调用会弹出“工具审批”对话框，显示工具名称和调用参数；编辑文件时还会显示计划差异，便于执行前检查改动。
+
+- 按 **Y** 批准，或按 **N** 拒绝，也可以点击对应按钮。对话框无法用 **Esc** 关闭，必须明确批准或拒绝。
+- 拒绝时可以填写原因，原因会发送给智能体，帮助其调整后续行为。填写原因后，批准按钮不可用。
+- 自动模式下，审批裁判模型评估调用期间不弹出对话框，界面右上角审批模式标签的左侧会显示“审查中”，前面带一个转动的图标。模型判定安全的调用直接执行，不弹对话框；模型判定可疑时，弹出标题为“自动审查已标记”的对话框，展示理由并等待人工决定。为避免误按按键直接批准，光标先停在原因输入框：可以填写原因后拒绝，也可以按 **Tab** 移到按钮上。如果审批裁判模型不可用、评估失败或超时，iCode 不会自动批准工具调用，而是弹出审批对话框，等待人工决定。
+- 如果想在评估期间就看到每个调用，按 **F10** 打开“设置”窗口，在“安全”标签页中关闭“仅在自动审查标记后弹出审批对话框”。之后对话框会立即弹出并显示“正在评估”：模型判定安全后自动关闭，评估完成前也可以直接批准或拒绝。
+
+## 记住审批
+
+你可以让 iCode 记住你批准过的 Shell 命令或文件修改，之后智能体发出相同请求时不再询问。Shell 命令和文件写入、编辑的审批窗口中会出现“记住审批”框：
+
+1. 勾选“相同命令不再询问”（文件为“修改这些文件不再询问”）。
+2. 选择“本会话”或“本项目”。“本会话”在恢复该会话后仍然有效；“本项目”在同一项目的其他会话中也有效。
+3. 选择“批准”。
+
+之后智能体再发出相同请求时会直接运行，不再弹出审批窗口。只会记住这条命令或这些文件，其他操作仍会询问。不勾选直接批准，只批准本次调用。以下情况不会被记住：
+
+- 自动模式下由审批裁判模型批准的调用。被自动审查标记的调用仍会显示“记住审批”框，你批准时可以选择记住。
+- 在审批窗口中编辑过的请求：编辑后的调用只运行一次。
+- 智能体指定了运行文件夹的命令，以及涉及凭据、SSH 密钥等敏感文件的请求。
+- 子智能体、工作流、MCP 工具和其他工具。
+
+如果在你批准之后、实际运行之前，文件夹或文件链接发生变化，使调用会作用到其他位置，该调用会报错停止，而不会在新位置运行。
+
+对于简单命令，“高级选项”中还有“允许在命令末尾添加参数”。勾选后，智能体在该命令末尾添加更多参数时也不再询问。例如这样记住 `git push origin main` 后，`git push origin main --force` 也会直接运行，因此窗口会显示警告。除非你信任所有可能被添加的参数，否则请不要勾选。
+
+如果 iCode 无法保存你的选择，本次调用仍会运行，并提示未能记住该审批。
+
+### 管理已记住的审批
+
+使用 `icode approvals` 命令查看和删除已记住的审批：
+
+```bash
+icode approvals list                         # 列出所有已记住的审批
+icode approvals list --project /work/demo    # 只看某个项目
+icode approvals list --session SESSION_ID --json
+icode approvals revoke GRANT_ID              # 按列表中的 ID 删除一条
+icode approvals clear --project /work/demo   # 删除某个项目的全部审批
+icode approvals clear --session SESSION_ID   # 删除某个会话的全部审批
+icode approvals clear --all                  # 全部删除
+```
+
+会话的审批会随该会话一起删除，用 `/fork` 创建分支时不会被复制到分支。项目的审批会一直保留，直到你删除。
+
+## 了解自动放行与安全保护
+
+以下操作通常会自动放行，不弹出审批对话框：
+
+- 不访问敏感目标的安全只读 Shell 命令，例如 `ls`、`cat`、`grep`。
+- 工作目录 Git 仓库内、且不访问敏感目标的文件写入。
+
+Shell 命令和文件读写访问 `.env`、凭据、私钥等敏感目标时，即使操作只读取文件或写入 Git 工作目录，也仍会进入审批流程。该保护适用于“手动”和“自动”模式；“绕过”模式会跳过这些审批保护。
+
+Skill 脚本以当前用户权限在本机运行，不受沙箱隔离，因此默认会请求审批。会话使用绕过模式时，Skill 脚本会不经询问直接运行。安装或运行第三方 Skill 前，应先检查其 `SKILL.md`、脚本和相关文件，确保可信。
+
+网络工具会向外部服务发送请求，因此 `web_search` 和 `web_fetch` 类别默认也会请求审批，即使智能体的 `approval.default` 为 `auto`。针对这些类别或工具名称的显式 `approval.overrides` 规则仍然优先。“自动”模式下审批裁判模型可以批准这些调用，“绕过”模式下它们会不经询问直接执行。参阅[配置网络工具](./web-tools.md#审批网络工具调用)。
+
+## 在 TUI 中验证审批模式
+
+选择内置的 Code Agent，然后提交以下请求：
+
+```text
+使用 Shell 工具运行 icode --version
+```
+
+该命令只显示版本，不修改文件，但不属于自动放行的只读 Shell 命令。预期结果如下：
+
+- 手动模式下，弹出“工具审批”对话框；批准后显示 iCode 版本。
+- 自动模式下，审批裁判模型评估命令期间，审批模式标签左侧显示“审查中”。模型通常会判定该命令安全，不弹出审批对话框就显示 iCode 版本；若模型将其标记为可疑，则对话框会显示评估理由并等待决定。
+- 绕过模式下，不显示审批对话框，直接运行命令并显示 iCode 版本。
+
+## 其他运行方式的审批模式
+
+其他运行方式使用以下审批模式和切换方式：
+
+- **无界面命令行（`icode run`）**：始终绕过审批，不提供审批相关参数。
+- **iCode ACP 服务**：默认手动，可用 `icode acp --approval manual|auto|bypass` 指定初始模式；支持该能力的 ACP 客户端也可以切换当前会话的模式。
+- **浏览器托管的 TUI（`icode serve`）**：可按照前文介绍的 TUI 操作切换审批模式和处理审批请求。