iCode-TUI 0.29.1__py3-none-any.whl

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

@@ -0,0 +1,175 @@
+# 安装和使用 Skills
+
+Skill 是一组可复用的操作说明，可以附带参考资料和脚本，用于扩展智能体处理特定任务的能力。本指南介绍如何为“内置”类型的智能体安装 Skill、确认 Skill 已加载，以及使用 Skill。外部 ACP 智能体是否支持 Skill 以及如何配置，由外部智能体决定。
+
+## Skill 安装位置
+
+根据 Skill 的使用范围和共享需求，选择合适的安装位置：
+
+| 位置 | 适合情况                                 | iCode 中的加载方式 |
+| --- |--------------------------------------| --- |
+| iCode 用户 Skill 目录 | 希望 iCode 中所有“内置”类型的智能体都能使用           | 始终自动加载 |
+| Agent Skills 共享目录 | 希望在 iCode 与其他支持 Agent Skills 的工具之间共享 | 默认自动加载，可针对智能体关闭 |
+| `<working-directory>/.agents/skills` | 只希望在当前工作目录中使用                         | 勾选“加载项目 Skills”后才加载，也可针对智能体关闭 |
+| 自定义目录 | 希望从指定位置加载                            | 需要在相应智能体配置中手动添加 |
+
+其中，`<working-directory>` 表示当前工作目录。工作目录中的 Skill 随仓库而来，因此需要先在“设置 → 安全 → 项目信任”中勾选“加载项目 Skills”（`project.skills_enabled`），iCode 才会加载。工作目录中有未加载的 Skill 时，iCode 会弹出提示。切换工作目录后，iCode 会重新加载新工作目录中的 Skill。
+
+两个用户级 Skill 目录在不同平台上的路径如下：
+
+| 目录 | macOS 和 Linux | Windows |
+| --- | --- | --- |
+| iCode 用户 Skill 目录 | `~/.chrys/skills` | `%APPDATA%\chrys\skills` |
+| Agent Skills 共享目录 | `~/.agents/skills` | `%USERPROFILE%\.agents\skills` |
+
+对于前三种安装位置，将 Skill 目录复制或移动到对应位置即可。使用自定义目录时，无需移动 Skill，只需在相应智能体的配置中添加 Skill 所在目录。
+
+iCode 会在已配置的 Skill 目录及其最多两层子目录中查找 `SKILL.md` 文件。找到 `SKILL.md` 后，将所在目录识别为一个 Skill 目录，不再继续查找其中嵌套的 Skill。
+
+## 安装并启用 Skill
+
+iCode 用户 Skill 目录始终自动加载。Agent Skills 共享目录默认也会自动加载；当前工作目录中的 Skill 目录在勾选“加载项目 Skills”后加载。若曾在智能体配置中关闭对应来源，需要重新启用。使用自定义目录时，需要将目录添加到相应智能体的配置中。
+
+如需直接在智能体 YAML 中定义不带文件的内嵌 Skill，请参阅[智能体配置文件](../../reference/agent-profile.md#skillsinline)。
+
+如需检查或调整智能体的 Skill 配置，请按以下步骤操作：
+
+1. 在输入栏中输入 `/agents skills`，打开当前智能体的“Skills”标签页。如需配置其他智能体，在左侧列表中选择。
+2. 根据 Skill 所在位置，确认对应的 Skill 来源已启用：
+
+   * “从用户文件夹加载 Skills（如果存在）”对应 Agent Skills 共享目录；
+   * “从工作文件夹加载 Skills（如果存在）”对应 `<working-directory>/.agents/skills`，仅在“设置 → 安全 → 项目信任”中勾选了“加载项目 Skills”时生效。
+
+3. 如果 Skill 位于其他目录，点击“+ 添加”，填写 Skill 所在目录：
+
+   * 使用相对于工作目录的路径时，勾选“工作区相对路径”。
+   * 使用绝对路径时，取消勾选“工作区相对路径”。
+
+4. 如果 Skill 包含脚本，确认脚本扩展名已列入“允许的脚本扩展名”。默认启用 `.py`、`.sh` 和 `.ps1`；其他可选扩展名包括 `.ts`、`.js` 和 `.rb`。运行脚本所需的解释器必须已经安装。
+5. 如需调整 Skill 脚本的最长运行时间，在“脚本执行超时（秒）”中填写正整数。
+6. 点击“保存”。
+
+> **注意**：Skill 脚本会作为本地进程运行，不受安全沙箱隔离。安装第三方 Skill 前，请检查 `SKILL.md`、脚本及其他相关文件，仅安装来自可信来源的 Skill。iCode 通过 `run_skill_script` 工具运行 Skill 脚本；该工具是否需要确认，取决于智能体审批规则和[当前审批模式](../configuration/approval.md)。
+
+Skill 脚本向标准输出或标准错误输出超过 32 MiB 时，iCode 只保留这部分输出的开头和结尾，中间部分不会保存，结果中会告诉智能体有多少内容没有保留。
+
+## 确认 Skill 已加载
+
+保存智能体配置并返回会话后，iCode 会重新加载 Skill。如果直接在磁盘上添加 Skill 目录或修改其中的文件，iCode 不会实时监控这些变化。下一次发送消息时，iCode 会先重新扫描当前智能体已启用的 Skill 目录，再处理该消息。
+
+可通过以下任一方式确认 Skill 已加载：
+
+* 在输入栏中输入 `/` 后，继续输入 Skill 名称（例如 `/release-`）。自动补全列表会随输入内容筛选匹配项；Skill 名称出现在“已加载 Skills”分组中，即表示已加载。
+* 输入 `/runtime`，或点击输入栏上方状态栏右端显示的 Skill 数量，打开“运行时详情”窗口，然后在“Skills”标签页中查看 Skill 名称和来源。
+
+如果 Skill 未出现，请依次检查：
+
+* 使用 Agent Skills 共享目录或工作目录 Skill 目录时，是否已启用对应选项（工作目录 Skill 目录还需勾选“加载项目 Skills”）；使用自定义目录时，是否已将其添加到当前智能体。
+* Skill 目录是否位于所选位置或其最多两层子目录中。
+* Skill 是否符合[创建 Skill 的基本规范](#创建-skill-的基本规范)。
+
+## 使用 Skill
+
+Skill 通常无需手动调用。当任务与某个 Skill 的描述匹配时，智能体会自动加载该 Skill 的完整说明，并按照其中的指引执行任务。例如：
+
+```text
+根据当前仓库从上一个版本以来的变更起草发布说明。
+```
+
+也可以在消息开头使用 `/skill-name` 显式调用已加载的 Skill。例如：
+
+```text
+/release-notes 根据当前仓库从上一个版本以来的变更起草发布说明。
+```
+
+如果 Skill 名称与 iCode 的内置斜杠命令相同，则无法使用 `/skill-name` 显式调用该 Skill。此时，可以在消息中直接指定 Skill 名称，例如：
+
+```text
+使用 release-notes Skill，根据当前仓库从上一个版本以来的变更起草发布说明。
+```
+
+当前会话首次加载该 Skill 时，会显示 `load_skill` 工具调用卡片，其中包含 `release-notes` Skill 名称；随后智能体会按照 Skill 说明完成任务。
+
+## 同名 Skill 的优先级
+
+从前文列出的[Skill 安装位置](#skill-安装位置)加载的 Skill 都属于目录 Skill，每个 Skill 都包含 `SKILL.md`。iCode 还支持直接在智能体配置文件中定义内嵌 Skill，这类 Skill 不需要 Skill 目录或 `SKILL.md`。
+
+如果发现多个同名 Skill，iCode 只会加载优先级最高的一个。优先级从高到低依次为：
+
+1. 智能体“Skills”标签页中手动添加的目录，越靠上优先级越高（新添加的目录位于列表顶部）；
+2. iCode 用户 Skill 目录；
+3. Agent Skills 共享目录；
+4. 当前工作目录中的 Skill；
+5. 智能体配置文件中的内嵌 Skill，按其定义顺序。
+
+如果同一个安装位置或自定义目录中存在多个同名 Skill，其发现顺序不确定。为确保加载指定版本，请仅保留其中一个。
+
+## 附录
+
+### 创建 Skill 的基本规范
+
+每个 Skill 使用独立目录，并在目录根层提供一个 `SKILL.md`。以下示例是一个可加载的最小 Skill：
+
+```markdown
+---
+name: release-notes
+description: 根据提交记录起草面向用户的发布说明
+---
+
+# 起草发布说明
+
+1. 读取上一个版本以来的提交记录。
+2. 按新增、修复和兼容性变化分类。
+3. 只写用户可观察到的变化。
+```
+
+#### 编写 `SKILL.md`
+
+`SKILL.md` 需要使用 UTF-8 编码。文件开头是由 `---` 包围的 YAML 配置区，也称为 frontmatter；之后是提供给智能体的操作说明。frontmatter 应写成有效的 YAML 键值对象；若不是有效的 YAML，iCode 会尝试逐行读取并记录警告。iCode 按以下规则校验文件内容：
+
+| 内容 | 加载要求 |
+| --- | --- |
+| frontmatter | 必须存在，且顶层内容应为 YAML 键值对象，不能使用锚点（`&`）或别名（`*`）；长度不超过 16384 个字符，嵌套不超过 64 层 |
+| `name` | 必填；必须与 Skill 目录名完全一致；长度为 1～64 个字符；只能包含小写字母、数字和连字符（`-`）。不能包含大写字母、下划线（`_`）等其他字符，也不能以连字符开头或结尾，不能包含连续连字符 |
+| `description` | 必填；须为文本，长度不超过 1024 个字符。建议同时说明 Skill 用途和适用场景，帮助智能体判断何时加载 |
+| `compatibility` | 可选；须为文本，长度不超过 500 个字符 |
+| `license`、`allowed-tools` | 可选；iCode 读取其文本，但不额外校验其内容 |
+| `metadata` | 可选；必须是值为纯文本或数字的 YAML 对象，否则 iCode 不会保留该字段 |
+| 正文 | iCode 不额外限制长度或结构 |
+
+为了确保 Skill 能够稳定加载，请使用有效的 YAML 编写 frontmatter。缺少 frontmatter、`name` 或 `description`，或者字段值未通过上述校验时，iCode 不会加载该 Skill。可选字段写成列表或对象时会被忽略。
+
+几个可选字段分别用于：
+
+* `compatibility`：说明 Skill 依赖的运行环境，例如适用的产品、所需的系统软件包或网络访问条件。
+* `license`：声明 Skill 采用的许可证，可以填写许可证名称或 Skill 目录中许可证文件的名称。
+* `allowed-tools`：按照 Agent Skills 规范声明可预先批准运行的工具。该字段仍处于实验阶段；iCode 当前只读取并保留字段值，不会据此自动授予工具权限。
+
+iCode 的 Skill 目录和 `SKILL.md` 格式遵循 Agent Skills 通用规范。上述字段的详细写法和 Skill 的完整规范参阅 [Agent Skills 官方规范](https://agentskills.io/specification)。
+
+#### 添加脚本和资源
+
+Skill 可以按需附带脚本、参考资料和其他文本资源。
+
+例如：
+
+```text
+release-notes/
+├── SKILL.md
+├── scripts/
+│   └── collect.py
+├── references/
+│   └── style-guide.md
+└── assets/
+    └── template.html
+```
+
+iCode 只会将以下扩展名的文本文件识别为 Skill 资源：`.md`、`.txt`、`.rst`、`.html`、`.htm`、`.xml`、`.svg`、`.json`、`.jsonl`、`.yaml`、`.yml`、`.toml`、`.csv`、`.tsv`、`.ini`、`.cfg`、`.css`。
+
+资源文件需要使用 UTF-8 编码。此外：
+
+* 脚本扩展名必须列入智能体配置的“允许的脚本扩展名”。
+* iCode 只读取 Skill 目录根层和直接子目录中的文件。例如，`guide.md` 和 `references/guide.md` 会被发现，`references/api/guide.md` 则会被忽略。
+* iCode 会跳过 Skill 目录内部通过符号链接或 Windows 目录联接访问的文件和目录。这两类链接都指向磁盘中的其他位置；如需使用其中的内容，请将实际文件放入 Skill 目录。
+
+不符合扩展名、目录层级或链接规则的文件不会出现在 Skill 的资源或脚本清单中；资源不是有效的 UTF-8 文本时，会在读取时失败。这些情况不影响符合要求的 `SKILL.md` 加载。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/running/icode-acp.md

@@ -0,0 +1,61 @@
+# 使用 iCode ACP 服务
+
+支持智能体客户端协议（Agent Client Protocol，ACP）的编辑器或开发工具，可以连接 iCode，在客户端中使用 iCode 智能体。ACP 客户端提供交互界面，iCode 通过标准输入输出（stdio）与客户端通信，负责运行智能体、执行工具并保存会话。
+
+开始前，请先安装 iCode，并至少配置一个模型。有关准备步骤，参阅[开始使用 iCode](../../start/getting-started.md)和[配置模型](../configuration/models.md)。
+
+## 连接 iCode
+
+在 ACP 客户端的“添加智能体”或类似设置中，填写以下信息：
+
+| 项目 | 值 |
+| --- | --- |
+| 可执行文件 | `icode` |
+| 参数 | `acp` |
+
+这相当于客户端启动：
+
+```shell
+icode acp
+```
+
+如果客户端只提供一个启动命令字段，则填写完整命令 `icode acp`。
+
+保存配置后，按以下步骤验证连接：
+
+1. 在客户端启动或连接 iCode。
+2. 新建会话并发送一条消息。
+3. 确认客户端显示 iCode 的回复。出现回复即表示连接配置成功。
+
+## 配置启动选项
+
+`icode acp` 支持以下启动选项。若客户端分别设置可执行文件和参数，将这些选项追加到 `acp` 后。
+
+| 选项 | 默认值 | 用途 |
+| --- | --- | --- |
+| `-a`、`--agent <agent>` | `Code` | 指定新会话使用的内置或自定义智能体；可使用名称、显示名称或 ID。恢复的会话沿用保存时的智能体。如需创建自定义智能体，参阅[配置智能体](../configuration/agents.md)。 |
+| `--approval <mode>` | `manual` | 指定该 ACP 服务新建或恢复的每个会话的初始审批模式；可选 `manual`、`auto` 或 `bypass`。`bypass` 审批模式会跳过审批并直接执行工具调用，请谨慎使用。各审批模式的规则参阅[配置审批模式](../configuration/approval.md)。 |
+| `-C`、`--workdir <directory>` | 无 | 为客户端未发送工作目录的会话提供默认工作目录。 |
+| `--ask-user-timeout <seconds>` | 不限时 | 限制等待客户端回答智能体提问的时间；省略或设为 `0` 及负数时，不设置等待时限。 |
+
+## 工作目录和会话
+
+客户端在创建或恢复会话时，可以将项目的工作目录交给 iCode。客户端提供的工作目录必须是已存在的绝对路径。客户端未提供工作目录时，iCode 使用 `--workdir <project-directory>` 指定的目录；两者同时存在时，以客户端提供的工作目录为准。
+
+iCode 会在启动时检查 `--workdir`。即使客户端随后会提供工作目录，该选项指定的目录也必须存在，否则 iCode 无法启动。
+
+会话数据不会写入工作目录，而是保存在 iCode 的会话存储目录中；有关实际保存位置，参阅[查找会话 ID 和会话保存位置](../daily-use/sessions.md#查找会话-id-和会话保存位置)。iCode 会记录会话创建时的工作目录。通过 ACP 客户端列出会话时，只会显示与当前工作目录匹配的会话；恢复会话时，如果工作目录不匹配，iCode 会拒绝恢复。
+
+通过 ACP 客户端使用的会话也会出现在 TUI 的“聊天会话”窗口中，勾选其中的“ACP”即可看到。参阅[恢复已有会话](../daily-use/sessions.md#恢复已有会话)。
+
+## 在客户端中完成交互
+
+iCode 会将智能体回复和工具调用状态发送给客户端。客户端取消任务时，iCode 会中断当前任务。
+
+当前模型支持视觉输入时，提示中可以包含 PNG、JPEG、GIF 或 WebP 格式的图像。提示中的图像为其他格式时，iCode 会拒绝该提示，客户端会收到错误。
+
+如果客户端支持管理会话，关闭会话后仍可以在同一工作目录中恢复；删除会话会移除 iCode 保存的会话记录，之后无法在 iCode 中恢复。
+
+如果要在 ACP 客户端中使用提问功能，客户端需要支持 iCode 的 `_chrys/request_input` 扩展请求（在会自动添加下划线前缀的 ACP SDK 中显示为 `chrys/request_input`）。iCode 通过此请求向客户端发送智能体的问题，并接收用户回答；不支持该请求的客户端无法完成需要用户回答的任务。等待回答的时间可以通过 `--ask-user-timeout` 限制。
+
+客户端支持审批模式或模型切换时，可以更改当前会话的相应设置。这些切换与通过 `--approval` 设置的初始模式一样，都不会写入 iCode 的本地配置；但如果客户端使用 iCode 的扩展请求修改设置、智能体配置或模型配置，这些更改会写入 iCode 的本地配置。下次启动 ACP 服务时，初始审批模式仍只由 `--approval` 决定，其他初始设置按本地配置和当次启动参数确定。模型配置和可用智能体仍由 iCode 的本地配置管理。

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/running/icode-run.md

@@ -0,0 +1,190 @@
+# 使用 icode run 执行无界面任务
+
+`icode run` 在终端中执行任务，完成后返回智能体的最终回复。它不打开终端用户界面（Terminal User Interface，TUI）；任务运行期间，会逐行显示智能体正在做什么，适合一次性任务、脚本和自动化流程。
+
+本指南介绍 `icode run` 如何指定任务、智能体、模型、工作目录和会话，如何查看或隐藏运行进度，以及如何取得适合程序处理的 JSON 输出。
+
+## 开始前
+
+运行前需要完成以下准备：
+
+- 已安装 iCode，并至少配置一个可用模型。请参阅[开始使用 iCode](../../start/getting-started.md)和[配置模型](../configuration/models.md)。
+- 已确定要使用的智能体。内置的 `QA` 智能体在 TUI 中显示为“Q&A Agent”，其指令要求它不修改任何内容，但它可以执行 Shell 命令，且 `icode run` 执行这些命令前不会请求审批；`Code` 智能体可以修改文件和运行命令。自定义智能体的能力取决于其配置。请参阅[配置智能体](../configuration/agents.md)。
+- 如任务可能修改文件，先保存未写入磁盘的工作，并在可恢复的工作目录中运行，例如已提交当前变更的 Git 仓库。
+
+> **注意**
+>
+> `icode run` 始终绕过工具审批。智能体调用 Shell、写入文件或运行 Skill 时不会等待确认。只应在可信的工作目录中运行可信的智能体和任务。
+
+`icode run` 在运行期间不能与人交互；应在启动前将任务要求和所需上下文写入提示词。
+
+## 执行任务
+
+在项目目录中运行命令，并通过 `-a` 或 `--agent` 指定智能体。任务文本含空格时使用引号：
+
+```shell
+icode run "概述这个项目的目录结构和主要模块" --agent QA
+```
+
+任务运行期间，iCode 会显示运行进度；任务完成后，先显示一行汇总，再显示智能体的最终回复。例如：
+
+```text
+• Q&A Agent ready · Example Model · session 8de5057d58ff · ~/projects/demo
+I'll start with the top-level layout.
+→ shell  ls
+  ✓ 0.1s
+→ read   README.md
+  ✓ 0.0s
+
+✓ Done · 8.2s · 2 tool calls · session 8de5057d58ff
+The project has three main parts: ...
+```
+
+各行的含义请参阅[查看运行进度](#查看运行进度)。回复中可能改动终端显示的控制字符会显示为 `�`；将输出重定向到文件或其他程序，或添加 `--json` 时，回复保持原样。若任务失败，错误信息写入标准错误（`stderr`），命令以非零状态退出。iCode 能判断模型请求失败的原因时，错误信息会说明原因，下方的 `detail:` 行显示原始错误信息。
+
+需要让智能体修改或验证代码时，可使用 `Code`：
+
+```shell
+icode run "修复登录表单的验证错误，并运行相关测试" --agent Code
+```
+
+这类任务可能修改工作目录中的文件并执行命令；运行前应确认提示词、智能体和当前目录都符合预期。
+
+运行 `icode run -h` 或 `icode run --help` 可以查看当前版本支持的参数。
+
+## 查看运行进度
+
+进度行写入标准错误（`stderr`），最终回复写入标准输出（`stdout`）。在终端中两者都会显示；使用 `>` 保存回复或将回复交给其他程序时，只有回复会写入：
+
+```shell
+icode run "为最近的改动撰写发布说明" --agent QA > notes.md
+```
+
+每一行表示一个步骤：
+
+| 行 | 含义 |
+| --- | --- |
+| `• Q&A Agent ready · …` | 智能体已启动，并显示其模型、会话和工作目录。 |
+| 普通文本 | 智能体在步骤之间说明的内容。 |
+| `→ read   README.md` | 智能体调用工具，此处为读取文件。 |
+| `✓ 0.1s` 或 `✗ exit 1 · 2.5s` | 工具已完成，或已失败并附原因，以及耗时。 |
+| `↳ Explore → grep   TODO` | 子智能体的步骤，以子智能体名称开头。 |
+| `↻ … Retrying in 7s (attempt 2/18)` | 模型请求因临时原因失败，将重试。 |
+| `Todo 1/3 · → Running tests` | 智能体的待办列表已更新。 |
+| `Warning: …` | 值得注意但不会中止任务的情况。 |
+| `✓ Done · 8.2s · 2 tool calls · session …` | 任务已完成，显示耗时、智能体调用工具的次数和会话。 |
+
+如只需查看警告、错误和最终回复，可添加 `-q` 或 `--quiet`：
+
+```shell
+icode run "概述这个项目" --agent QA --quiet
+```
+
+## 指定工作目录
+
+`-C` 或 `--workdir` 指定智能体处理文件和执行命令时使用的工作目录，无需先在终端中切换目录：
+
+```shell
+icode run "检查未提交的变更并说明风险" --agent QA --workdir <project-directory>
+```
+
+将 `<project-directory>` 替换为实际项目路径。可以使用绝对路径，或相对于运行命令时所在目录的路径；路径必须指向一个已有目录。
+
+## 从文件读取任务
+
+较长、需要版本管理或由脚本生成的任务可以放在文本文件中，再通过 `-t` 或 `--task` 读取：
+
+```shell
+icode run --task prompts/review.md --agent Code --workdir <project-directory>
+```
+
+`--task` 不要求特定文件后缀。iCode 会读取该文件内容，并将其作为本次任务的提示词。任务文件路径可以是绝对路径，也可以是相对路径；使用相对路径时，iCode 会在 `--workdir` 指定的目录中查找该文件，未指定 `--workdir` 时，则在运行命令时所在的目录中查找。
+
+一次运行只能使用一种提示词来源：直接传入提示词或使用 `--task`。两者不能同时使用。
+
+## 选择智能体和模型
+
+`icode run` 必须通过 `--agent` 指定智能体。运行 `icode agents` 可以查看可用的智能体配置：
+
+```text
+Default  Name  Display Name  ID            Model
+   *     Code  Code Agent    b011c0de0001  active
+         QA    Q&A Agent     b0119a000005  Example Model
+```
+
+上述示例省略了部分行和列，`Example Model` 为虚构的模型配置。
+
+`Name`、`Display Name` 和 `ID` 均可作为 `--agent` 的值。`Model` 为 `active` 表示使用当前生效的模型配置；显示具体名称表示使用已绑定的模型配置。
+
+对于使用 `active` 模型的智能体，可以通过 `-m` 或 `--model` 为本次运行指定模型配置；对于已绑定模型的智能体，`--model` 不生效。
+
+运行 `icode models` 可以查看可用的模型配置：
+
+```text
+Active  ID            Name           Provider  API   Model          Context  Flags
+   *    0123456789ab  Example Model  openai    chat  example-model  200k     stream
+```
+
+`Active` 列中的 `*` 表示默认生效的模型配置。`ID` 和 `Name` 均可作为 `--model` 的值。
+
+## 取得 JSON 输出
+
+添加 `--json` 后，成功结果以 JSON 对象写入标准输出（`stdout`），错误和警告以 JSON 对象写入标准错误（`stderr`），不显示运行进度。例如：
+
+```shell
+icode run "hello" -a QA --json
+```
+
+以下是一次运行的实际输出：
+
+```json
+{"session_id": "8de5057d-58ff-477e-9158-2f1b8d8e9fc0", "result": "Hello! I'm iCode, a read-only Q&A assistant for this codebase. I can help you with questions about the code, architecture, APIs, conventions, and how things work — with file and line references so you can jump straight to the source.\n\nWhat would you like to know?", "duration": 9.018}
+```
+
+其中，`session_id` 是本次任务所属的会话 ID，`result` 是智能体的最终回复，`duration` 是本次任务的耗时秒数。
+
+读取不存在的任务文件时：
+
+```shell
+icode run --task missing.md -a QA --json
+```
+
+标准错误输出：
+
+```json
+{"error": "Task file does not exist: missing.md", "code": "task_file_not_found"}
+```
+
+`error` 是错误说明，`code` 是可供程序判断的错误类别。上述错误发生在会话创建前，因此没有 `session_id`；任务开始后发生错误（例如模型请求失败）时，输出还会包含 `session_id`。
+
+## 继续已有会话
+
+需要连续对话时，可使用 `-s` 或 `--session` 恢复已有会话，并基于已有对话继续提交任务。未指定 `-C` 或 `--workdir` 时，恢复后使用该会话保存时的工作目录，而不是执行命令所在的目录；指定 `-C` 或 `--workdir` 会改用指定目录。自动化任务需要确定文件操作位置时，应显式指定 `-C` 或 `--workdir`。如果该会话保存的工作目录已不存在，iCode 会提示错误并停止，此时可使用 `-C` 或 `--workdir` 在另一个目录中继续该会话。
+
+在无界面模式下，可从第一轮 JSON 输出的 `session_id` 字段获取会话 ID：
+
+```shell
+icode run "检查当前改动并列出需要补充的测试" --agent Code --json
+```
+
+将返回的会话 ID 传给第二轮：
+
+```shell
+icode run "根据上一轮的结果，补充缺少的测试" --agent Code -s <session-id> --json
+```
+
+其中 `<session-id>` 填写第一轮返回的会话 ID。
+
+通过 `icode run` 创建或继续的会话也会出现在 TUI 的“聊天会话”窗口中，勾选其中的“CLI”即可看到。参阅[恢复已有会话](../daily-use/sessions.md#恢复已有会话)。
+
+## 退出状态
+
+自动化脚本可以根据退出状态判断结果：
+
+| 状态 | 含义 |
+| --- | --- |
+| `0` | 智能体已正常完成并返回最终回复。 |
+| `1` | 配置、任务文件、智能体、模型、会话或任务执行出现错误。具体原因写入标准错误。 |
+| `2` | 命令行参数无效，例如缺少 `--agent`，或同时提供或均未提供提示词和 `--task`。用法说明以纯文本写入标准错误，即使指定了 `--json` 也是如此。 |
+| `124` | 内部操作超时。`icode run` 不限制任务的总运行时间。 |
+| `130` | 运行被中断。 |

chrys/app/tui/screens/guides/_docs/zh-Hans/guides/running/icode-serve.md

@@ -0,0 +1,239 @@
+# 在浏览器中运行 iCode
+
+`icode serve` 在浏览器中显示 iCode 的终端用户界面（Terminal User Interface，TUI），支持对话、审批工具调用和修改配置。
+
+启动选项可通过 `icode serve --help` 查看。
+
+本文将运行浏览器的设备称为“本机”，将运行 iCode 服务的机器称为“服务端”。服务端可以是本机，也可以是通过网络访问的远程服务器。
+
+开始前，服务端应已[安装 iCode](../../start/getting-started.md#1-安装-icode)。浏览器提供操作界面，iCode 则使用服务端的配置，以启动服务的系统用户权限读取、修改文件和执行命令。这些操作均发生在服务端，所有访问者共享服务端的配置、文件和会话，不会获得独立账户。
+
+首次登录后，如果尚未配置模型，需要先在浏览器界面中[配置模型](../../start/getting-started.md#3-配置模型)，然后才能开始对话。任务运行期间应保持页面连接；关闭、刷新页面或断线都会中断该页面中正在执行的任务。
+
+根据服务端的位置和访问方式，参阅对应章节：
+
+| 使用场景 | 操作章节 |
+| --- | --- |
+| 本机运行和访问 | [在本机启动 iCode](#在本机启动-icode) |
+| 通过 SSH 访问远程服务器上的 iCode | [从本机访问远程 iCode](#从本机访问远程-icode) |
+| 通过固定的 HTTPS 域名访问 | [通过固定的 HTTPS 域名访问](#通过固定的-https-域名访问) |
+
+## 在本机启动 iCode
+
+### 1. 启动服务
+
+在本机终端中进入工作目录，然后启动服务：
+
+```shell
+icode serve --auth-required
+```
+
+按终端提示输入并确认浏览器登录密码，密码不能为空。`--auth-required` 启用密码登录；未指定认证选项时，无需登录即可访问。
+
+终端显示 `Serving iCode TUI on ...` 和访问地址后，表示服务已启动。
+
+### 2. 在浏览器中登录
+
+在本机浏览器中打开 `http://localhost:7777`，输入启动时设置的密码。`localhost` 表示本机，`7777` 是服务端口。
+
+登录后应显示 iCode 界面，服务端已有的模型配置会继续使用。确认模型已配置后，发送“你好”，检查是否能收到回复。
+
+启动时所在目录即为初始工作目录。点击对话区底部边框右侧的目录路径可[切换工作目录](../daily-use/workspaces.md#在会话中切换工作目录)。`icode serve` 不接受 TUI 的 `--workdir`、`--agent`、`--model` 或 `--session` 参数；更换智能体、模型和恢复会话均在页面中操作。
+
+### 3. 结束使用
+
+使用期间应保持服务终端运行。任务结束后，在该终端按 `Ctrl+C` 停止服务。
+
+每次打开页面并建立连接，服务端都会启动一个独立的 iCode 实例。对话记录保存在服务端，重新打开页面后，可[恢复已保存的会话](../daily-use/sessions.md#恢复已有会话)。
+
+浏览器登录状态有效期为 12 小时，服务重启后需重新登录。同一客户端地址连续 5 次输入错误密码后会被锁定，只能通过重启服务解除。重启会断开所有已连接的页面。
+
+## 从本机访问远程 iCode
+
+如果已能通过 SSH 登录远程服务器，可以建立 SSH 隧道，将本机浏览器的连接通过加密通道转发到远程 iCode，无需配置域名。以下步骤需要在本机打开两个终端窗口。
+
+### 1. 在第一个终端中登录远程服务器并启动 iCode
+
+```shell
+ssh <user>@<server>
+```
+
+将 `<user>` 替换为服务器的 SSH 用户名，`<server>` 替换为其 IP 地址或主机名，使用 SSH 密钥或密码登录。
+
+登录后，在该终端中执行的命令会运行在远程服务器上。进入远程工作目录，然后启动 iCode：
+
+```shell
+icode serve --auth-required
+```
+
+设置浏览器登录密码，确认终端显示服务地址，并保持终端运行。
+
+### 2. 在第二个终端中建立隧道
+
+在本机打开第二个终端，执行以下命令建立隧道：
+
+```shell
+ssh -N -o ExitOnForwardFailure=yes -L 7777:localhost:7777 <user>@<server>
+```
+
+用户名和服务器地址与上一步相同。SSH 身份验证完成后，终端通常不再输出内容，也不返回命令提示符；保持终端运行。
+
+若 SSH 登录需指定其他端口或密钥，两条命令均需添加相同的连接选项。
+
+### 3. 在本机浏览器中访问
+
+访问 `http://localhost:7777`，输入第一步设置的 iCode 浏览器登录密码。
+
+浏览器访问本机的 `localhost:7777` 后，SSH 隧道会将连接转发到远程 iCode。因此，本例中的浏览器地址应保持为 `localhost`，不能改为远程 IP。
+
+任务结束后，在第一个终端按 `Ctrl+C` 停止 iCode，在第二个终端按 `Ctrl+C` 关闭 SSH 隧道。
+
+## 通过固定的 HTTPS 域名访问
+
+通过 `https://icode.example.com` 等固定地址访问时，需部署反向代理：浏览器与代理建立加密连接，代理再将请求转发至 iCode。
+
+本节适用于已有 HTTPS 代理的环境。域名和证书需要在代理侧配置，iCode 本身不提供 HTTPS 服务。
+
+### 1. 启动 iCode
+
+以下示例要求代理与 iCode 运行在同一台服务器上。在服务器终端中进入工作目录，将 `icode.example.com` 替换为实际域名，然后运行：
+
+```shell
+icode serve --host 127.0.0.1 --port 7777 --public-url https://icode.example.com --auth-required
+```
+
+设置浏览器登录密码，并保持终端运行。此命令让 iCode 只接受同一台服务器上的连接，浏览器则通过代理访问 `--public-url` 指定的地址。
+
+### 2. 配置代理连接
+
+代理需满足以下要求：
+
+- 将该域名的请求转发至 `http://127.0.0.1:7777`。
+- 保留浏览器请求中的原始 `Host` 头，使 iCode 能核对访问域名。
+- 支持 WebSocket 连接，供页面持续传输输入和回复。
+
+默认情况下，iCode 按代理地址累计密码错误次数，多个访问者可能共享失败计数。若代理可信且会正确重写 `X-Forwarded-For`（客户端地址请求头），可在 iCode 启动命令中添加 `--auth-trust-forwarded-for`，改为按代理提供的访问者地址计数。
+
+### 3. 验证访问
+
+将 `icode.example.com` 替换为实际域名，在本机浏览器中打开对应的 HTTPS 地址，例如 `https://icode.example.com`，无需添加 iCode 的端口 `:7777`。浏览器应显示 iCode 登录页面，且没有证书警告。登录后发送一条消息，确认能收到回复。
+
+浏览器到代理的连接已加密；代理到 iCode 仍使用服务器内部的 HTTP 连接。
+
+### 其他部署方式
+
+代理位于其他服务器或独立容器中时，`127.0.0.1` 可能无法连接 iCode。调整监听地址后，应通过防火墙或容器网络规则限制后端端口仅供可信代理访问，避免绕过 HTTPS 代理直接连接。设置 HTTPS `--public-url` 不会加密代理到 iCode 的 HTTP 连接。
+
+## 从文件或环境变量读取密码
+
+无法在终端交互输入密码时，可通过文件或环境变量提供。两种方式均自动启用认证，无需添加 `--auth-required`，且不能同时使用。
+
+### 使用密码文件
+
+在服务端准备一个 UTF-8 纯文本文件，将登录密码写入文件。密码不能为空，文件末尾的换行会被忽略。
+
+进入工作目录，指定密码文件启动：
+
+```shell
+icode serve --auth-password-file "<password-file>"
+```
+
+将 `<password-file>` 替换为服务端的密码文件路径。启动时不再提示输入密码，浏览器使用文件中的密码登录。
+
+### 使用环境变量
+
+在服务端为 iCode 启动进程设置环境变量，例如 `CHRYS_SERVE_PASSWORD`，并将变量值设为非空的登录密码。然后运行：
+
+```shell
+icode serve --auth-password-env CHRYS_SERVE_PASSWORD
+```
+
+`--auth-password-env` 的参数为环境变量名称。启动时不再提示输入密码，浏览器使用该变量的值登录。
+
+## 直接通过局域网 IP 访问
+
+直接通过局域网 IP 访问会以明文传输登录密码和对话内容，仅适用于明确接受此风险的网络环境。
+
+在服务端进入工作目录，将 `192.168.1.20` 替换为服务端实际的局域网 IP，然后运行：
+
+```shell
+icode serve --host 0.0.0.0 --public-url http://192.168.1.20:7777 --auth-required --allow-insecure-auth
+```
+
+`--host 0.0.0.0` 允许其他设备连接 iCode。`--allow-insecure-auth` 显式允许通过网络进行明文密码登录；本例未指定该选项时，iCode 会拒绝启动。
+
+在本机浏览器中使用服务端的实际局域网 IP 访问，例如 `http://192.168.1.20:7777`，然后登录。若无法连接，检查本机与服务端是否互通，以及服务端防火墙是否允许客户端访问 TCP 端口 `7777`。
+
+## 故障排查
+
+### 提示找不到 `icode` 命令
+
+确认服务端已安装 iCode，且安装目录已加入 `PATH`。若刚完成安装，重新打开终端后运行以下命令验证：
+
+```shell
+icode --version
+```
+
+### 本机启动提示端口被占用
+
+通过 `--port` 指定一个空闲端口，并在浏览器地址中使用相同端口。例如，若 `8888` 空闲：
+
+```shell
+icode serve --port 8888 --auth-required
+```
+
+然后访问 `http://localhost:8888`。
+
+### SSH 隧道提示本地端口被占用
+
+将 `-L` 后的第一个端口改为本机空闲端口，最后一个端口保持为远程 iCode 的监听端口。例如，远程 iCode 使用 `7777`，且本机的 `8888` 端口空闲时，可在本机运行：
+
+```shell
+ssh -N -o ExitOnForwardFailure=yes -L 8888:localhost:7777 <user>@<server>
+```
+
+将 `<user>` 和 `<server>` 替换为 SSH 用户名和服务器地址。同时在远程服务器上重新启动 iCode，指定新的浏览器访问地址：
+
+```shell
+icode serve --public-url http://localhost:8888 --auth-required
+```
+
+然后在本机访问 `http://localhost:8888`。
+
+### 浏览器提示无法访问
+
+先确认 iCode 服务仍在运行，再核对浏览器地址是否与所用方式一致：按本机或 SSH 示例访问时使用 `localhost`，通过 HTTPS 访问时使用配置的域名，通过局域网直连时使用服务端 IP。
+
+如果地址正确但仍无法访问，SSH 方式还需检查隧道是否运行，HTTPS 方式则需检查域名解析和代理服务。
+
+### HTTPS 页面出现证书警告
+
+确认浏览器使用了配置的域名，并检查代理证书是否过期、是否与域名匹配，以及浏览器是否信任其签发机构。
+
+### HTTPS 页面返回 `502`
+
+检查 iCode 是否仍在运行、代理转发的地址和端口是否与 iCode 的监听配置一致，以及代理是否能连接该地址；具体原因可查看代理日志。
+
+### 页面返回 `421`
+
+使用 iCode 启动时显示的域名或 IP 及端口访问。经代理访问时，检查代理是否保留了原始 `Host` 头。
+
+### WebSocket 连接返回 `403`
+
+核对浏览器地址是否与 `--public-url` 指定的地址一致，包括协议（`http` 或 `https`）、域名和端口。iCode 会拒绝来源地址不匹配的连接。
+
+### 登录时返回 `403`
+
+若提示 `Invalid login token`，重新打开登录页面后输入密码；若提示 `Invalid login origin`，核对浏览器地址是否与 iCode 配置的访问地址一致。
+
+### 提示密码尝试次数过多
+
+该客户端地址已锁定。先确认其他页面没有正在执行的任务，再在 iCode 终端按 `Ctrl+C` 并重新启动。多个代理访问者同时被锁定时，按 HTTPS 章节中的条件检查是否适合启用 `--auth-trust-forwarded-for`。
+
+### 页面刷新或断线后未显示原对话
+
+页面重新连接后，服务端会启动新的 iCode 实例。可按“恢复已保存的会话”中的步骤恢复对话记录，但中断的任务不会自动继续。
+
+### 复制失败
+
+若出现复制对话框，点击 **Copy**。仍失败时，选中对话框中的文字，使用浏览器的复制快捷键手动复制。