iCode-TUI 0.29.1__py3-none-any.whl

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

@@ -0,0 +1,276 @@
+# Chat 选项
+
+Chat 选项会给模型配置发出的每个请求加上额外字段。可以用它设置推理强度、开启或关闭思考、开启提示词缓存，或传入网关、自部署服务需要的参数。本指南先介绍填写方法，再列出常见模型服务的设置，并附上各服务的官方文档链接。
+
+提供商文档最后核对日期：**2026-09-30**。下面的示例供按需选用，不应全部一起开启。具体支持情况取决于模型、API 接口和服务端版本；兼容某种协议不代表支持完全相同的选项。
+
+## 添加 Chat 选项
+
+1. 打开“模型配置”窗口（参见[配置模型](./models.md#打开模型配置窗口)），选中一个模型配置。
+2. 在“其他选项”区域找到“Chat 选项（额外请求字段）”，点击“+ 添加”新增一行。
+3. 在左侧输入框填写字段名，在右侧输入框填写值。
+4. 点击“保存”。
+
+保存并关闭窗口后，修改对之后的请求生效。要删除某个选项，点击该行末尾的 ✕，然后保存。
+
+### 值的解析方式
+
+iCode 会尽量把值当作 JSON 解析：
+
+- `0.2` 作为数字发送，`true` 作为布尔值发送。
+- `{"type": "adaptive"}` 作为对象发送，`["a", "b"]` 作为列表发送。
+- 其他内容都作为文本发送：`high` 发送为 `"high"`。如果要发送看起来像数字或 `true` 的文本，请加上引号，例如 `"1"`。
+
+整个值必须写在一行内。请仔细核对括号、引号和逗号。对象中有错误（例如多了一个结尾逗号）时，会被当作普通文本保存，模型服务随后会拒绝请求。必须填写对象的字段（例如 `extra_body`）会先经过检查：iCode 会显示错误，不会保存。
+
+### 服务专有字段的位置
+
+所选提供商和 API 样式对应的客户端库只接受一组固定的顶层字段名，例如 `temperature`、Chat Completions 的 `reasoning_effort`，以及 Anthropic 的 `thinking`。未知字段可能在请求发出前就导致 `unexpected keyword argument` 错误。服务扩展字段，以及 iCode 内置客户端库尚未接受的新 API 字段，请放进 `extra_body`。OpenAI 兼容服务中的例子包括 `top_k`、`enable_thinking` 和 `chat_template_kwargs`：
+
+| 字段名 | 值 |
+| --- | --- |
+| `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}, "top_k": 20}` |
+
+一个模型配置只能有一行 `extra_body`，所以请像上例一样，把所有此类字段写进同一个 JSON 对象。同一个字段既单独成行又出现在 `extra_body` 中时，实际发送的是 `extra_body` 中的值。
+
+`extra_body` 会把字段合并到 HTTP 请求体中，但不能让服务端支持它原本不支持的参数。同样，`top_k` 对 OpenAI 兼容服务是扩展字段，对 Anthropic API 则是原生字段。
+
+### 有专门字段的设置
+
+以下设置不要写在 Chat 选项中：
+
+- **输出长度**：使用“最大输出词元数”字段。保存时会拒绝 `max_tokens` 等行。
+- **流式输出**：使用“流式输出”复选框，默认开启，取消勾选即可关闭。不要添加 `stream` 行。
+- **模型**：使用“模型”字段。
+- **HTTP 请求头**：使用“HTTP 附加请求头”各行，或者添加一行 `extra_headers`，值为 JSON 对象。对于 Anthropic 的 `anthropic-beta` 请求头，“HTTP 附加请求头”会添加到 iCode 的 Beta 标志之后，而 `extra_headers` 行会替换它们，详见 [Anthropic](#anthropic)。
+- **Claude 思考设置**：使用配置文件中的 `thinking_block_binding` 和 `auto_interleaved_thinking` 两行，详见 [Claude 思考设置](./models.md#claude-思考设置)。
+
+消息、工具和系统提示词由 iCode 自行构建，因此保存时会拒绝 `messages` 等字段。
+
+### 不在配置中保存密钥
+
+要从环境变量读取值的一部分，用双大括号写上变量名。例如，把网关令牌作为请求头发送：
+
+| 字段名 | 值 |
+| --- | --- |
+| `extra_headers` | `{"X-Api-Token": "{{MY_GATEWAY_TOKEN}}"}` |
+
+配置文件中保留的是占位符，iCode 在发送请求时才填入实际值。请在启动 iCode 之前设置好该变量；变量未设置时，iCode 会报错并指出变量名。
+
+### 哪些请求使用 Chat 选项
+
+使用同一模型配置的请求会共用 Chat 选项，包括主智能体、子智能体、工作流中的智能体、会话标题生成、自动审批的判断模型以及上下文压缩。具体操作可能根据自身请求覆盖或过滤部分选项。较高的推理强度也可能增加这些辅助请求的耗时和费用。
+
+## 提示词缓存
+
+在 iCode 默认的本地历史模式下，请求会重新发送当前上下文中的对话。提示词缓存让服务复用未变化的前缀，减少重复处理输入的工作量，通常也能降低输入费用。它与服务端保存对话是两回事。写入缓存可能有额外费用，能否节省费用取决于前缀的复用次数。
+
+OpenAI、DeepSeek、GLM、Kimi 的 Chat Completions 接口和通义千问在支持的模型上提供自动缓存。vLLM 和 SGLang 的前缀缓存由服务端管理，是否生效取决于启动配置和模型支持情况。来源和例外见下文各提供商章节。
+
+**Anthropic 的 Claude API 需要显式设置缓存。** 要自动缓存逐渐增长的对话前缀，请添加这一行：
+
+| 字段名 | 值 |
+| --- | --- |
+| `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+
+如果配置中已有 `extra_body` 行，请把 `"cache_control": {"type": "ephemeral"}` 加进它的对象中。Anthropic 标准的 5 分钟缓存写入费用为基础输入价格的 1.25 倍；读取费用为 0.1 倍或更低，因模型而异。如需保留 1 小时，使用 `{"type": "ephemeral", "ttl": "1h"}`，写入费用为 2 倍。有效期从写入或复用缓存的请求开始时计算，因此生成回答也会消耗其中一部分时间。此外，模型还有最短可缓存前缀的要求。当前限制和计费规则见 [Anthropic 提示词缓存文档](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。
+
+### “提示词缓存未开启”提醒
+
+保存模型配置时，如果提供商为“Anthropic”、模型 ID 包含 `claude`，且没有任何 `cache_control` 设置，iCode 会显示“提示词缓存未开启”窗口：
+
+- **添加并保存**：把 `"cache_control": {"type": "ephemeral"}` 加入 `extra_body` 行（没有该行时自动新建），然后保存。
+- **直接保存**：按原样保存配置。
+- 按 **Esc** 或点击窗口外部：返回表单，不保存。
+
+当某次保存让该配置成为完整的 Claude 配置时（新建的配置，或改用“Anthropic”提供商、改成 Claude 模型的配置），iCode 会显示这个提醒。保存本来就是 Claude 配置的配置时，不会再次提醒。
+
+兼容 Anthropic 协议的服务有各自的缓存行为，可能接受、忽略或拒绝 `cache_control`，请查阅对应接口的文档。如果服务拒绝该字段，只从 `extra_body` 中删除 `"cache_control": {...}`，然后保存。此提醒只检查配置内容，无法判断服务端是否实际缓存了请求。
+
+### 检查缓存是否生效
+
+打开侧边栏（按 **Ctrl+G** 显示或隐藏），选择“上下文”标签页。在“词元用量”区域，“缓存命中”一行显示本会话累计报告的缓存读取量。只有请求报告命中时才会增长，不保证每次调用都增长。显示 `-` 不能证明缓存未开启：可能没有命中，也可能服务没有返回缓存用量。
+
+如果“缓存命中”一直显示 `-` 或不再增长：
+
+- 检查模型配置是否包含该服务需要的设置（参见[常见模型服务的设置](#常见模型服务的设置)）。
+- 检查模型的最短可缓存前缀、有效期和缓存写入要求。短提示词可能不满足条件，已过期或被清理的条目也无法复用。
+- 保持可复用内容稳定。更换模型、工具、推理设置或压缩历史都可能减少缓存复用，但发生变化不一定让此前所有匹配的前缀失效。
+- 即使输入相同，请求被路由到不同后端时也可能无法命中。自动缓存不保证每次命中。
+
+## 常见模型服务的设置
+
+以下各节先给出推荐的提供商、API 样式和服务地址，再列出常用设置。字段名和取值范围会随模型变化，请以所用模型的官方文档为准。
+
+### OpenAI
+
+提供商选“OpenAI”，API 样式选“Responses”，服务地址使用默认值。“Chat Completions”也可以使用，但部分较新的模型只在 Responses 下支持工具调用。提示词缓存自动生效。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 推理强度（Responses） | `reasoning` | `{"effort": "high"}` |
+| 推理摘要（Responses） | `reasoning` | `{"effort": "high", "summary": "auto"}` |
+| 推理强度（Chat Completions） | `reasoning_effort` | `high` |
+| 回答更简短 | `verbosity` | `low` |
+| 更便宜、处理更慢 | `service_tier` | `flex` |
+| GPT-5.6 及之后模型的缓存有效期（Responses） | `extra_body` | `{"prompt_cache_options": {"mode": "implicit", "ttl": "30m"}}` |
+
+使用 Responses 时，请用 `reasoning`，不要用 `reasoning_effort`。iCode 会把 `verbosity` 选项转换为 API 的 `text.verbosity`。支持的推理强度、摘要、详细程度和 Flex 服务因模型而异。Flex 还可能返回资源不可用错误，参见 [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing)。
+
+GPT-5.6 及之后的模型使用 `prompt_cache_options`，有效期为 `30m`，自动缓存写入也会计费。较早的模型使用 `prompt_cache_retention`，取值可能为 `in_memory` 或 `24h`，取决于具体模型，两类设置不能混用。请保留 `implicit` 模式：`explicit` 模式需要在内容块上添加缓存断点，Chat 选项表单不会添加这些断点。
+
+使用 Responses 且地址为 OpenAI 官方地址时，iCode 还会把会话 ID 作为 `prompt_cache_key` 发送，同一会话的请求共用一个缓存键；子智能体和工作流中的智能体各用自己的键。要使用自定义的键，请添加 `prompt_cache_key` 行；不想发送，请将其值设为 `null`。
+
+除非需要服务端续接，否则请不要设置 `store`：iCode 默认发送 `false`，这仍然允许提示词缓存。设为 `true` 后，iCode 的上下文压缩会被禁用。
+
+官方文档：[Reasoning](https://developers.openai.com/api/docs/guides/reasoning)、[Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)、[Responses API 参考](https://developers.openai.com/api/reference/resources/responses/methods/create)、[Chat Completions API 参考](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)。
+
+### Anthropic
+
+提供商选“Anthropic”，服务地址为 `https://api.anthropic.com`，不要在末尾加 `/v1`。**请开启提示词缓存**，方法见[提示词缓存](#提示词缓存)。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 提示词缓存 | `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+| 自适应思考 | `thinking` | `{"type": "adaptive"}` |
+| 固定预算的思考（较早的模型） | `thinking` | `{"type": "enabled", "budget_tokens": 8000}` |
+| 投入程度（effort） | `output_config` | `{"effort": "medium"}` |
+| 其他地址上较早模型的交错思考 | `additional_beta_flags` | `["interleaved-thinking-2025-05-14"]` |
+
+- 只有支持自适应思考的模型才能使用 `adaptive`；较新的模型会拒绝旧的 `enabled` / `budget_tokens` 形式。普通固定预算思考要求“最大输出词元数”大于 `budget_tokens`，手动交错思考的预算规则有所不同。
+- 较新的 Claude 模型会拒绝非默认的 `temperature`、`top_p` 和 `top_k` 值，请不要设置。
+- `additional_beta_flags` 和 `betas` 用于给请求增加 Beta 标志，“HTTP 附加请求头”中的 `anthropic-beta` 也一样。iCode 会把它们排在自己的标志之后，合并到同一个 `anthropic-beta` 请求头中发送。`extra_headers` 行中的 `anthropic-beta` 会替换所有这些标志，包括 iCode 自己的标志；此时 iCode 只补上思考设置所需的标志。
+- 在 Anthropic 官方地址上使用固定预算的思考时，iCode 会自动添加交错思考的标志，详见 [Claude 思考设置](./models.md#claude-思考设置)。在其他地址上，请按上表自行添加。自适应思考已自动支持交错思考，无需该标志。交错思考的支持情况因模型而异，服务接受某个 Beta 标志并不代表它实际生效。
+- 在 Anthropic 官方地址上，Claude Opus 5.5、Fable 5.1 或 Sonnet 5.5 使用自适应思考时，iCode 会请服务略去与对话对不上的早先思考内容，详见 [Claude 思考设置](./models.md#claude-思考设置)。你在 `thinking` 中自己写的 `block_binding` 会原样发送，iCode 会补上它所需的 Beta 标志。
+
+官方文档：[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)、[Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)、[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)、[Effort](https://platform.claude.com/docs/en/build-with-claude/effort)、[Beta headers](https://platform.claude.com/docs/en/api/beta-headers)。
+
+### DeepSeek
+
+提供商选“DeepSeek (OpenAI)”，API 样式选“Chat Completions”，服务地址使用默认的 `https://api.deepseek.com`。提示词缓存自动生效。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 关闭思考 | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| 推理强度 | `reasoning_effort` | `high` |
+
+当前 API 默认开启思考，推理强度支持 `low`、`high` 和 `max`。在思考模式下，`temperature`、`presence_penalty` 和 `frequency_penalty` 会被忽略；`top_p` 仅在 0.95 到 1.0 范围内生效。较早模型 ID 的能力可能不同。
+
+官方文档：[思考模式](https://api-docs.deepseek.com/guides/thinking_mode)、[上下文硬盘缓存](https://api-docs.deepseek.com/guides/kv_cache)、[API 参考](https://api-docs.deepseek.com/api/create-chat-completion)。
+
+### GLM（智谱 / Z.ai）
+
+提供商选“GLM (OpenAI)”。默认服务地址为 `https://open.bigmodel.cn/api/paas/v4`；在中国大陆以外请使用 `https://api.z.ai/api/paas/v4`；使用 GLM Coding Plan 时，请使用 `https://open.bigmodel.cn/api/coding/paas/v4` 或 `https://api.z.ai/api/coding/paas/v4`。提示词缓存自动生效。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 关闭思考 | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| 在上下文中保留之前的推理 | `extra_body` | `{"thinking": {"type": "enabled", "clear_thinking": false}}` |
+| 推理强度（GLM-5.2 及之后） | `reasoning_effort` | `high` |
+
+GLM-5.3 始终思考，推理强度支持 `low`、`high` 和 `max`，不要给它传入 `thinking.type: disabled`。GLM-5.2 的强度映射不同，更早的模型不支持该强度字段。`clear_thinking: false` 还要求完整保留历史推理，iCode 的 GLM 提供商会保留这些内容。`temperature` 的取值范围为 0 到 1。
+
+官方文档：[Thinking mode](https://docs.z.ai/guides/capabilities/thinking-mode)、[Context caching](https://docs.z.ai/guides/capabilities/cache)、[API 参考](https://docs.z.ai/api-reference/llm/chat-completion)。
+
+### Kimi（月之暗面）
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址为 `https://api.moonshot.cn/v1`（中国大陆以外为 `https://api.moonshot.ai/v1`）。提示词缓存自动生效。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 推理强度（Kimi K3） | `reasoning_effort` | `high` |
+| 关闭思考（Kimi K2.6） | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| 延长缓存有效期（Chat Completions） | `extra_body` | `{"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}}` |
+
+Kimi K3 始终思考，强度支持 `low`、`high` 和 `max`，不接受 `thinking` 字段。K2.7 Code 始终思考，但不支持 `reasoning_effort`；K2.6 可以关闭思考，也不支持该强度字段。除非具体模型的文档明确支持，否则请不要设置采样选项；部分 Kimi 模型的固定值限制不代表整个系列都采用相同的采样规则。iCode 只接受省略 `n` 或将其设为 `1`。
+
+Chat Completions 默认使用 5 分钟缓存。1 小时选项的写入价格更高；已有缓存条目过期前，修改 TTL 不会改变其有效期。
+
+Kimi 也提供兼容 Anthropic 协议的接口：提供商选“Anthropic”，服务地址为 `https://api.moonshot.ai/anthropic`。在该接口上，只有请求中要求缓存时才会写入缓存，因此请添加[提示词缓存](#提示词缓存)中的 `cache_control` 设置。
+
+官方文档：[Chat API](https://platform.kimi.ai/docs/api/chat)、[使用思考模型](https://platform.kimi.ai/docs/guide/use-thinking-models)、[上下文缓存](https://platform.kimi.ai/docs/guide/context-caching)、[Anthropic 兼容 API](https://platform.kimi.ai/docs/api/messages)。
+
+### 通义千问（阿里云百炼）
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址使用百炼控制台中的 OpenAI 兼容地址。目前推荐工作空间专属接口，例如 `https://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（北京）或 `https://<WorkspaceId>.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`（新加坡），请将 `<WorkspaceId>` 替换为实际工作空间 ID。旧的 `dashscope.aliyuncs.com` 和 `dashscope-intl.aliyuncs.com` 接口仍可使用。API 密钥与接口地域必须匹配，其他地域和 Coding Plan 使用各自的接口。在支持的模型上，隐式缓存自动开启，但不保证命中。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 关闭思考 | `extra_body` | `{"enable_thinking": false}` |
+| 限定思考预算 | `extra_body` | `{"enable_thinking": true, "thinking_budget": 4096}` |
+| 采样 | `extra_body` | `{"top_k": 20}` |
+| 允许模型联网搜索 | `extra_body` | `{"enable_search": true}` |
+
+`enable_thinking: false` 适用于混合思考模型，纯思考模型无法关闭思考。预算范围、`top_k` 和 `enable_search` 的支持情况也因模型而异。部分开源千问模型的思考模式要求开启“流式输出”，商业模型则可能同时支持非流式请求。百炼还提供通过消息内容块标记启用的显式缓存，Chat 选项表单不会添加这些标记。
+
+官方文档：[OpenAI 兼容](https://www.alibabacloud.com/help/en/model-studio/compatibility-of-openai-with-dashscope)、[深度思考](https://www.alibabacloud.com/help/en/model-studio/deep-thinking)、[上下文缓存](https://www.alibabacloud.com/help/en/model-studio/context-cache)。
+
+### vLLM
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址为 `http://<主机>:<端口>/v1`。“API 密钥”填写服务端 `--api-key` 的值；服务端未设置密钥时留空。前缀缓存由服务端配置，请检查 `--enable-prefix-caching` / `--no-enable-prefix-caching` 以及所部署模型的支持情况。
+
+对于需要使用工具的 iCode 智能体，启动服务时请加上 `--enable-auto-tool-choice` 和与模型匹配的 `--tool-call-parser`。推理模型还应配置匹配的 `--reasoning-parser`，以分开显示推理过程和回答。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 关闭思考（Qwen3 等） | `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}}` |
+| 推理强度 | `reasoning_effort` | `low` |
+| 采样 | `extra_body` | `{"top_k": 20, "min_p": 0.0, "repetition_penalty": 1.05}` |
+
+这些参数取决于模型模板，不是通用开关。有些模型始终思考，有些使用不同的开关。`reasoning_effort` 也不是在每个模型上都提供相同的强度等级。请使用与所安装 vLLM 版本对应的文档。
+
+官方文档：[Tool calling](https://docs.vllm.ai/en/latest/features/tool_calling/)、[Reasoning outputs](https://docs.vllm.ai/en/latest/features/reasoning_outputs/)、[OpenAI-compatible server](https://docs.vllm.ai/en/latest/serving/openai_compatible_server/)、[Server arguments](https://docs.vllm.ai/en/latest/cli/serve/)。
+
+### SGLang
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址为 `http://<主机>:<端口>/v1`。使用工具时配置工具解析器，使用推理模型时配置推理解析器。普通服务配置默认开启前缀缓存，但 `--disable-radix-cache` 或模型自身的限制可能将其禁用。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 关闭思考（混合思考的 Qwen3 模型） | `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}}` |
+| 开启思考（DeepSeek-V3.1） | `extra_body` | `{"chat_template_kwargs": {"thinking": true}}` |
+| 推理强度 | `reasoning_effort` | `low` |
+| 采样 | `extra_body` | `{"top_k": 20, "min_p": 0.0, "repetition_penalty": 1.05}` |
+
+模板接受的字段和强度等级取决于模型和 SGLang 版本。推理解析器负责分离输出，本身不会开启思考。保持 `separate_reasoning` 开启，才能分开显示推理过程。`reasoning_effort` 应在请求或服务端模板默认值中择一设置，不要两处同时设置。
+
+官方文档：[OpenAI-compatible API](https://docs.sglang.io/docs/basic_usage/openai_api_completions)、[Server arguments](https://docs.sglang.io/docs/advanced_features/server_arguments)、[Tool parser](https://docs.sglang.io/docs/advanced_features/tool_parser)、[Reasoning parser](https://docs.sglang.io/docs/advanced_features/separate_reasoning)。
+
+### LiteLLM 代理
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址为 `http://<主机>:4000`，API 密钥填写 LiteLLM 虚拟密钥（`sk-...`）。使用 Claude 模型时，也可以选择提供商“Anthropic”并使用相同的服务地址，这样会连接到 LiteLLM 的 Anthropic 格式接口。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 为费用统计打标签 | `extra_body` | `{"metadata": {"tags": ["team-a"]}}` |
+| 按标签路由 | `extra_body` | `{"tags": ["free"]}` |
+
+标签路由要求代理配置中已有匹配的部署标签，并开启标签过滤；只在请求中传入标签不会自动配置路由。费用报表还取决于代理的统计配置和可用功能。
+
+对于不支持的 OpenAI 参数，代理管理员可以配置 `drop_params`，这些设置随后会被静默省略。它不能通用地修复无效的提供商扩展字段或参数值，此类问题应在模型配置中删除或修正对应字段。
+
+官方文档：[Virtual keys](https://docs.litellm.ai/docs/proxy/user_keys)、[Cost tracking](https://docs.litellm.ai/docs/proxy/cost_tracking)、[Tag routing](https://docs.litellm.ai/docs/proxy/tag_routing)、[Drop unsupported params](https://docs.litellm.ai/docs/completion/drop_params)、[Anthropic `/v1/messages` 接口](https://docs.litellm.ai/docs/anthropic_unified)。
+
+### OpenRouter
+
+提供商选“OpenAI”，API 样式选“Chat Completions”，服务地址为 `https://openrouter.ai/api/v1`。
+
+| 用途 | 字段名 | 值 |
+| --- | --- | --- |
+| 指定由哪些提供商提供模型 | `extra_body` | `{"provider": {"order": ["anthropic"], "allow_fallbacks": false}}` |
+| 推理强度 | `extra_body` | `{"reasoning": {"effort": "high"}}` |
+| Claude 模型的提示词缓存 | `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+
+需要同时使用时，请写进同一个对象，例如 `{"provider": {"order": ["anthropic"]}, "cache_control": {"type": "ephemeral"}}`。
+
+`provider.order` 设置优先顺序；如果只允许所列提供商处理请求，请保留 `allow_fallbacks: false`。顶层 `cache_control` 可用于 Claude 的自动缓存，但仍需模型和提供商支持。OpenRouter 文档规定的行为可能与直接调用提供商不同。
+
+官方文档：[Quickstart](https://openrouter.ai/docs/quickstart)、[Provider selection](https://openrouter.ai/docs/guides/routing/provider-selection)、[Reasoning tokens](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens)、[Prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching)。
+
+## 添加选项后请求失败时
+
+- **保存时提示“Chat 选项第 N 行：……”**：按提示修改对应的行，然后重新保存。
+- **报错中包含 `unexpected keyword argument 'x'`**：把字段 `x` 移入 `extra_body`，方法见[服务专有字段的位置](#服务专有字段的位置)。
+- **模型服务提示不支持某个字段**：只删除该字段。如果它位于 `extra_body` 中，只从 JSON 对象里删除这一项，保留其他项，然后保存。
+- **报错中提到某个环境变量**：设置该变量后重启 iCode，或者删除对应的 `{{...}}` 占位符。
+- **找不到明显原因**：逐个删除最近添加的行，直到请求恢复正常，并查阅所用模型的官方文档。

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

@@ -0,0 +1,42 @@
+# 配置上下文压缩
+
+长对话接近模型的上下文窗口时，iCode 会自动压缩较早的内容，为后续请求留出空间。本指南介绍如何配置“内置”类型智能体的 Last Words 补充内容和输出上限。外部 ACP 智能体自行管理上下文。
+
+新建智能体已采用适合大多数任务的默认设置，通常无需调整。
+
+## 了解压缩何时发生
+
+iCode 根据当前模型配置中的最大上下文窗口、最大输出词元数和安全余量自动计算何时开始压缩。请根据模型能力和任务需要，在[模型配置](./models.md)中设置最大上下文窗口和最大输出词元数。“压缩”标签页不能单独设置触发时机。
+
+上下文接近占满时，iCode 还会降低下一次请求的输出上限，使输入和输出都能容纳在上下文窗口内，并为词元数估算误差留出少量余量。
+
+模型服务仍可能报告上下文窗口已满，例如模型实际的上下文窗口小于模型配置中设置的值。如果服务的报错给出的上限小于模型配置中的最大上下文窗口，这次请求会直接失败，报错信息会给出这个上限，请把模型配置中的最大上下文窗口改为该值或更小。否则 iCode 会压缩上下文，并自动重新发送一次请求；如果服务再次报告上下文窗口已满，这次请求就会失败。模型因没有空间回复、一个字都没写就停止时，请求也可能失败。失败之后，下一次请求会先压缩上下文，尽量腾出空间，例如点击“重试”、发送下一条消息或重试工作流节点时。如果仍反复出现，请在模型配置中把最大上下文窗口改为模型的实际值。
+
+压缩时，iCode 会先将较早的工具结果替换为摘要，必要时再移除较早的工具调用及其结果；如果仍需释放空间，则在当前上下文中用压缩摘要代替已经完成的对话轮次。如果这些处理仍然不够，iCode 会为当前任务生成 Last Words，保留继续完成任务所需的信息，再从提供给模型的上下文中移除本轮的工具调用、工具结果和中间内容，只保留用户消息。
+
+三种处理的作用不同：精简较早的工具调用和结果只减少工具使用的占用；压缩摘要代替已完成轮次；Last Words 用于续接当前尚未完成的任务。
+
+在 TUI 中可以观察到以下变化：
+
+- 压缩期间显示“正在压缩对话”。
+- 压缩完成后，侧边栏消息列表中已压缩的对话轮次以灰色显示；对话区在相应位置显示灰色的“已压缩”标记和压缩摘要。
+- 如果生成了 Last Words，可以展开已完成的压缩卡片查看 Last Words 内容。
+
+已压缩的历史轮次仍会保留在会话中。智能体可在需要时查询其中的具体信息，但不会将整段对话重新加入当前上下文。
+
+压缩能降低上下文占用，但摘要无法保证保留每个原始细节。需要长期保留且不能遗漏的项目规则应写入[记忆文件](./memory.md)，重要工作结果应写入工作目录文件，而不应只存在于对话中。
+
+## 调整压缩设置
+
+1. 在输入栏输入 `/agents compaction`，打开当前智能体的“压缩”标签页。如需修改其他智能体，在左侧列表中选择。
+2. 按需调整“Last Words 最大输出词元数”，填写界面允许范围内的整数。实际生成上限不会超过当前模型配置的最大输出词元数。
+3. 如需让 Last Words 重点保留某类信息，填写“Last Words 补充内容（可选强调）”。
+4. 点击“保存”。新设置会在该智能体后续需要压缩时生效。
+
+“Last Words 补充内容（可选强调）”用于指出 Last Words 需要重点保留的信息。例如，如果经常使用该智能体排查问题，可填写：
+
+```text
+优先保留复现步骤、已经排除的原因、关键日志和仍待验证的假设。
+```
+
+填写时聚焦于继续任务所需、但容易在压缩中遗漏的信息，并尽量简短。

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

@@ -0,0 +1,48 @@
+# 配置记忆
+
+本指南介绍如何为主智能体配置记忆。
+
+## 准备记忆内容
+
+**记忆会在主智能体加载时加入系统提示词。** iCode 会读取当前主智能体配置的记忆文件，并将内容作为参考资料提供给智能体。记忆内容会占用模型的上下文窗口，并随请求发送给模型服务。因此，建议避免在记忆中包含密钥、访问令牌等敏感信息。
+
+**子智能体不加载记忆。** 子智能体不会继承主智能体已加载的记忆，也不会加载自身智能体配置中的记忆。[工作流](../running/workflows.md)中的智能体节点则会加载其智能体配置中的记忆。
+
+**记忆适合保存稳定且通用的信息。** iCode 只加载扩展名为 `.md` 或 `.txt` 的记忆文件。适合放入记忆的内容应当能够在多个任务中重复使用，例如项目约定、背景资料和常用信息。内容应简短、明确并保持更新；临时任务要求更适合直接写在当前请求中。
+
+**默认智能体已配置 AGENTS.md 作为记忆。** iCode 默认提供的主智能体（如 Code Agent）会加载工作目录中的 `AGENTS.md`。需要为项目补充通用说明时，可以优先维护该文件；如不需要，可在“记忆”标签页中删除该条目。
+
+## 添加记忆文件
+
+1. 在输入栏中输入 `/agents memory`，打开当前智能体的“记忆”标签页。如需配置其他主智能体，在左侧列表中选择。
+2. 在“文件”区域点击“+ 添加文件”。
+3. 输入路径，或通过“浏览”按钮选择 `.md` 或 `.txt` 文件。勾选“工作区相对路径”时填写相对路径（例如 `AGENTS.md`、`docs/context.md`），否则填写绝对路径。
+   
+    > **注意**：相对路径在加载记忆时按当前工作目录解析，而不是按照创建智能体配置时的目录解析。因此，同一个智能体可以在不同项目中加载各自的 `AGENTS.md`。相对路径不能指向工作目录以外的位置；如需加载工作目录以外的文件，请使用绝对路径。
+4. 点击“保存”，然后关闭智能体配置窗口。
+
+## 添加记忆文件夹
+
+需要加载一组参考文件时，在“文件夹”区域点击“+ 添加文件夹”，勾选“工作区相对路径”时填写相对路径，否则填写绝对路径。添加完成后点击“保存”，然后关闭智能体配置窗口。
+
+iCode 会先加载该目录直属的 `.md` 和 `.txt` 文件，再逐层扫描子目录。对于每个配置的文件夹，最多扫描两层子目录，最多加载 100 个文件。若某个重要文件可能不在扫描范围内，可将其单独添加到“文件”区域。
+
+## 记忆的加载与重新加载
+
+同一实际文件同时被单独添加和从文件夹中发现时，只会加载一次。多个记忆来源的合计内容上限为 35,000 词元。iCode 先加载单独添加的文件，再加载文件夹；一旦某个文件会使内容超过上限，该文件及其后的所有文件都会被跳过，iCode 会显示警告。
+
+切换工作目录或修改当前智能体配置后，iCode 会根据新路径重新加载记忆。
+
+iCode 不会实时监控已经加载的记忆文件。直接在磁盘上修改文件内容后，需要重新加载主智能体才能使修改生效，例如重新启动 iCode、切换工作目录、修改并保存当前智能体配置，或切换到其他主智能体后再切回。
+
+## 验证记忆是否加载
+
+在输入栏中输入 `/runtime`，或点击输入栏上方状态栏右端显示的文件数量，打开“运行时详情”窗口，切换到“文件”标签页。页面会按配置来源列出实际加载的文件。预期文件出现在列表中，即表示记忆已加载。
+
+如果预期文件未显示，请检查：
+
+* 路径是否存在，文件扩展名是否为 `.md` 或 `.txt`。
+* 相对路径指向的文件是否位于当前工作目录内。
+* 添加的条目类型与实际路径是否匹配（文件条目应指向文件，文件夹条目应指向文件夹）。
+* 是否出现内容超过 35,000 词元或部分文件被跳过的警告。
+* 修改配置后是否点击了“保存”。

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

@@ -0,0 +1,158 @@
+# 配置模型
+
+模型配置包含连接模型服务所需的信息。本指南介绍如何在终端用户界面（Terminal User Interface，TUI）中创建、克隆、修改、切换和删除模型配置。配置保存后，可以在不同任务之间切换，不必重复填写连接参数。
+
+## 打开模型配置窗口
+
+使用以下任一方式打开“模型配置”窗口：
+
+- 按 **F4**。
+- 点击界面底部的 `f4 模型`。
+- 在输入栏中输入 `/models`。
+
+左侧列表显示已有模型配置，右侧表单显示当前选中配置的内容。
+
+任务运行期间，“模型配置”窗口将以只读模式打开，无法新建、修改或删除配置。请等待任务结束后再进行配置调整。
+
+## 管理模型配置
+
+### 创建模型配置
+
+1. 点击“新建”。
+2. 填写自定义的配置名称，例如 `我的模型`。
+3. 在模型选项区域，选择模型提供商和 API 样式。仅 OpenAI 和 DeepSeek（OpenAI）提供 API 样式选项。配置前，请根据模型服务商的文档确认其支持的 API，并按文档建议选择 `Chat Completions` 或 `Responses`。如果服务商仅支持其中一种 API，请选择对应的 API 样式；如果两种 API 均支持，则根据服务商的建议或实际使用需求选择。
+4. 填写模型 ID，并根据模型服务的要求填写服务地址和 API 密钥。
+5. 根据模型提供商的说明，填写最大上下文窗口和最大输出词元数。
+6. 根据需要调整流式输出、视觉模型和连接选项。新建的配置默认开启流式输出。
+7. 点击“保存”。
+
+**注意事项：**
+
+- 点击“新建”时，iCode 会立即创建并保存一项空白配置。后续填写或修改的内容需要点击“保存”才会生效；直接关闭窗口不会删除已经创建的空白配置。
+- 配置名称用于在界面中展示和区分模型配置，不会发送给模型服务。配置名称不能为空，且不能与已有配置重复（不区分大小写）。可以使用中文、空格、字母、数字和常见符号。
+- 模型 ID 和词元限制等必填信息不完整时，该配置不会出现在可选模型列表中。
+- 开启流式输出后，回复会随模型生成逐步显示。只要模型服务持续发送内容，较长的回复可以超过“HTTP 读取超时（秒）”设定的时长；只有服务停止发送达到该时长时才会超时。在旧版 iCode 中保存时未勾选“流式输出”的配置，现在也会使用流式输出；如需关闭，请取消勾选“流式输出”后再次保存。如果换回旧版 iCode，旧版会把本版本开启流式输出后保存的配置当作未开启。
+- 开启视觉模型后，图片会以 PNG、JPEG、GIF 或 WebP 格式发送给模型。工具返回的其他格式图片会改为发送一条“图片已略去”的简短说明，对话可以继续。
+- 若此前没有可用的模型配置，新配置在保存并关闭窗口后将自动成为当前使用的模型配置。已有其他模型配置正在使用时，保存新配置不会自动切换模型。
+- 如需设置推理强度、提示词缓存或其他请求字段，请使用“其他选项”区域中的“Chat 选项（额外请求字段）”。参见 [Chat 选项](./chat-options.md)，其中还列出了常见模型服务的设置。某次保存让配置成为通过 Anthropic 协议使用的 Claude 配置时，如果缺少缓存设置，iCode 会提示添加。
+
+### 通过环境变量提供 API 密钥
+
+直接填写的 API 密钥会随模型配置文件保存在本机。
+
+若要从环境变量读取密钥，在 API 密钥字段中填写：
+
+```text
+{{PROVIDER_API_KEY}}
+```
+
+将 `PROVIDER_API_KEY` 替换为存放密钥的环境变量名；启动 iCode 前应确保该环境变量已经设置。环境变量名只能包含字母、数字和下划线，且不能以数字开头。
+
+### 克隆模型配置
+
+需要创建一套大部分参数相同的配置时，可以克隆现有配置。例如，同一提供商下使用不同模型 ID，或为相同模型设置不同的上下文和输出限制。
+
+1. 在左侧列表中选择要复制的模型配置。
+2. 点击“克隆”。
+3. iCode 会创建并选中一个包含原配置全部字段的副本，并为副本生成不重复的名称。
+4. 修改配置名称以及需要变更的字段。
+5. 点击“保存”。
+
+克隆操作会在点击“克隆”时立即保存副本，但不会将副本切换为当前使用的模型。
+
+### 修改模型配置
+
+1. 在左侧列表中选择模型配置。
+2. 修改需要调整的字段。
+3. 点击“保存”。
+
+如果修改了正在使用的模型配置，保存并关闭配置窗口后，新配置将用于后续请求。
+
+### Claude 思考设置
+
+Claude Opus 5.5、Fable 5.1 和 Sonnet 5.5 会把返回的思考内容与它之前的对话绑定。之前的对话发生变化后（例如 iCode 压缩了上下文），模型服务可能拒绝读回这些思考内容。当这些模型在 Anthropic 官方地址上使用自适应思考（在 [“Chat 选项”](./chat-options.md#anthropic)中设置 `"thinking": {"type": "adaptive"}`）时，iCode 会请服务略去对不上的思考内容，而不是拒绝请求。这样模型看到的早先推理会变少，但请求可以正常完成。对于服务原本不做这项检查的账号，这项要求也会让服务开始检查，对不上的思考内容同样会被略去。
+
+如需更改，请在 iCode 配置目录的 `models` 文件夹中（macOS 和 Linux 为 `~/.chrys/models/`，Windows 为 `%APPDATA%\chrys\models\`；文件中的 `name:` 一行即配置名称）打开该配置的文件，添加一行 `thinking_block_binding`，取下列值之一，然后重启 iCode：
+
+| 值 | iCode 向服务提出的要求 |
+| --- | --- |
+| `auto`（默认） | 如上所述。 |
+| `drop_block` | 略去对不上的思考内容。适用于任何地址和模型，只要思考为自适应或固定预算。 |
+| `error` | 遇到对不上的思考内容时拒绝请求。适用于任何地址和模型，只要思考为自适应或固定预算。 |
+| `off` | 不提出要求。你在“Chat 选项”的 `thinking` 中自己写的 `block_binding` 仍会原样发送。 |
+
+如果服务仍因对不上的思考内容拒绝了请求，iCode 会去掉读回的早先思考内容，再发送一次请求，之后也不再发送这些思考内容。这会多发一次请求，模型也不再看到那部分早先的推理。设为 `error` 时，iCode 会直接报告这次拒绝。
+
+在 Anthropic 官方地址上使用固定预算的思考（`"type": "enabled"`）时，iCode 还会开启工具调用之间的思考。Claude Haiku 4.5 和 Claude Opus 4.6 在这种模式下不支持，因此不会开启。如需关闭，请添加一行 `auto_interleaved_thinking: false`。
+
+之后在“模型配置”窗口中保存该配置时，这些行会保留。
+
+### 删除模型配置
+
+删除操作会移除保存在本机的模型配置文件，且**无法在 iCode 中撤销**。确认不再需要该配置后：
+
+1. 打开“模型配置”窗口。
+2. 在左侧列表中选择要删除的配置。
+3. 点击“删除”。
+4. 在确认窗口中再次核对要删除的配置名称，然后点击“删除”。
+
+iCode 至少保留一项模型配置，因此只剩一项时无法点击“删除”。如果删除了正在使用的配置，关闭配置窗口后，iCode 会自动切换到其他可选配置。
+
+## 切换和验证模型配置
+
+### 切换当前模型配置
+
+可以点击模型配置名称标签，或在输入栏中快速切换模型配置。
+
+点击模型配置名称标签：
+
+1. 点击输入栏上方状态栏中的模型配置名称，打开模型选择窗口。
+2. 通过鼠标点击，或使用上下方向键选择模型配置后按回车确认。
+
+在输入栏中快速切换：
+
+1. 在输入栏中输入 `$`，模型配置列表会显示在输入栏上方。
+2. 继续输入配置名称以筛选结果。
+3. 使用上下方向键选择模型配置，然后按回车确认。
+
+切换后，状态栏会显示新的模型配置名称。当前使用的配置在列表中以灰色显示，名称前带有空心圆圈。缺少必填项的模型配置不会显示在列表中。
+
+当前对话会在新的模型配置下继续。有些模型服务返回的推理内容只有它自己能读取，例如 Claude 的思考内容和 OpenAI 的加密推理。如果新配置把请求发往另一个服务地址，iCode 会在请求中略去这些早先的推理内容。你的消息、模型的回复以及 iCode 运行的工具结果仍会照常发送；同一步中由模型服务自己运行的工具，其结果也可能被略去。切换回使用原地址的配置后，这些推理内容会重新发送。早期 iCode 版本保存的推理内容仍按原来的方式发送。
+
+如果状态栏中的模型配置名称灰度显示，表示当前智能体已绑定特定模型配置，点击它只会提示绑定情况。此时输入 `$` 也不会显示模型配置列表，需要先[修改该智能体的模型设置](./agents.md#设置智能体使用的模型)，才能切换模型配置。智能体正在运行时也不能切换。
+
+### 验证模型配置
+
+切换模型后，在输入栏中提交：
+
+```text
+你好
+```
+
+iCode 应正常返回问候回复。若模型服务返回错误，先核对模型 ID、服务地址、API 密钥等模型配置。
+
+仍报错时，对照以下现象排查：
+
+- **报错信息包含 `The Chat Completions client supports only n=1`**：使用 Chat Completions 样式时，iCode 每次请求只处理一条回复，不支持多候选回复，`n` 参数应省略或设为整数 `1`。在模型配置的[“Chat 选项（额外请求字段）”](./chat-options.md)中把该值删除或改为 `1`，包括经 `extra_body` 间接设置的情况。
+- **返回状态为 `HTTP 200` 但响应不是有效的模型回复**：例如 Content-Type 为 `text/html`，正文是错误页、错误 JSON 或空内容。出现这种情况说明网关或代理把后端错误包装成了成功响应；此时核对所选 API 样式与模型服务地址是否匹配，并检查代理路由。
+- **模型服务的内容过滤拦截了回复**：iCode 不会重试该请求，也不会执行被过滤或被拒绝的回复中请求的工具。请换一种方式描述需求。
+- **使用 Responses 样式时，模型服务报告回复失败**：iCode 会显示服务给出的错误。只有再次尝试可能成功的错误（例如服务器错误或限流）才会重试；服务拒绝的请求（例如含有无法读取的图片，或超出账户额度）不会重试。流式回复在完成前中断时，也按同样的规则重试。超出上下文窗口的请求例外，参见[无法连接模型服务时](#无法连接模型服务时)。如果服务在这次失败的回复中已经执行过可能产生改动的工具（例如 MCP 调用），iCode 不会重试，以免工具重复执行。如果服务始终不说明流式回复是否已完成，iCode 会保留已收到的内容，并在日志中记录一条警告。
+- **使用 Anthropic 协议时，流式回复在完成前中断**：iCode 会重试该请求，且不会执行中断的回复中请求的工具。与 Responses 样式一样，如果服务已经执行过可能产生改动的工具（例如 MCP 调用），iCode 不会重试，以免工具重复执行。
+- **流式回复有时中途停止，但没有报错**：部分使用 Chat Completions 样式的服务在结束流式输出时不说明回复是否已完成，iCode 会保留这样的回复。如果希望 iCode 把它当作中断的回复并重试，请在 iCode 配置目录的 `models` 文件夹中（macOS 和 Linux 为 `~/.chrys/models/`，Windows 为 `%APPDATA%\chrys\models\`；文件中的 `name:` 一行即配置名称）打开该配置的文件，添加一行 `stream_requires_finish_reason: true`，然后重启 iCode。之后在“模型配置”窗口中保存该配置时，这一行会保留。
+- **开启流式输出后请求失败，且模型服务或网关不支持流式输出**：在模型配置中取消勾选“流式输出”并保存。如果直接修改配置文件，请添加一行 `stream: false`，然后重启 iCode。关闭流式输出只能解决服务不支持流式输出导致的问题。
+
+### 无法连接模型服务时
+
+iCode 能判断模型请求失败的原因时，会用通俗的话说明原因，并在下方附上原始错误信息；暂停的子智能体卡片上也是如此。iCode 自动重试时，重试提示只显示这句说明。如果运行 iCode 的设备看起来没有网络连接，iCode 也会一并提示，此时请先检查网络。
+
+| 提示内容 | 检查什么 |
+| --- | --- |
+| 无法解析服务地址 | 网络连接和 DNS 设置。如果地址填错了，在模型配置中修改服务地址。 |
+| 拒绝了连接 | 服务地址中的地址和端口，以及模型服务是否正在运行。 |
+| 连接超时或等待响应超时 | 网络、防火墙或 VPN。 |
+| 无法连接到代理 | 代理软件是否正在运行、代理设置是否正确。如需不经代理直接连接，在模型配置中开启“绕过代理”。 |
+| 代理要求身份验证 | 代理的用户名和密码。 |
+| 无法建立安全连接 | 在公司网络中，检查代理的证书设置。 |
+| API 密钥无效或没有访问权限 | 模型配置中的 API 密钥。 |
+| 请求超出模型的上下文窗口 | 模型配置中的上下文窗口是否与模型的实际值一致。开启上下文压缩时，iCode 会压缩上下文并重新发送一次请求，只有这次也失败时才会显示该错误。参见[配置上下文压缩](./compaction.md)。 |
+| 模型配置的最大上下文窗口大于服务端支持的上限 | 在模型配置中把“最大上下文窗口”改为提示中给出的服务端上限或更小，并保存。 |