diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index d5856fcea..613a665b2 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -1,73 +1,79 @@ --- read_when: - 你正在调试与转录结构相关的提供商请求拒绝问题 - - 你正在更改转录净化或工具调用修复逻辑 - - 你正在调查跨提供商的工具调用 id 不匹配问题 -summary: 参考：特定于提供商的转录净化和修复规则 + - 你正在更改转录清理或工具调用修复逻辑 + - 你正在调查跨提供商的工具调用 ID 不匹配问题 +summary: 参考：提供商特定的转录清理和修复规则 title: 转录清理规范 x-i18n: - generated_at: "2026-04-24T18:11:02Z" + generated_at: "2026-04-24T21:20:34Z" model: gpt-5.4 provider: openai - source_hash: 6970504736b6a6bf09c6066ecb76e98900d8d0c4181573557ca2d2b8eb526493 + source_hash: eb9b8ea55b34810609d65433fa3be1558dd7c59bf4b33e66dfab3fdbd5a211ef source_path: reference/transcript-hygiene.md workflow: 15 --- -本文档描述了在一次运行前（构建模型上下文时）应用到转录内容的**特定于提供商的修复**。这些是用于满足严格提供商要求的**内存中**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；但是，单独的会话文件修复流程可能会在加载会话之前，通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会在会话文件旁边备份。 +本文档描述了在一次运行前（构建模型上下文时）应用于转录的**提供商特定修复**。这些是用于满足严格提供商要求的**内存中**调整。这些清理步骤**不会**重写磁盘上存储的 JSONL 转录；不过，单独的会话文件修复流程可能会在加载会话前通过丢弃无效行来重写格式错误的 JSONL 文件。发生修复时，原始文件会与会话文件一起备份。 范围包括： -- 工具调用 id 净化 +- 仅运行时的提示词上下文，不进入用户可见的转录轮次 +- 工具调用 ID 清理 - 工具调用输入验证 - 工具结果配对修复 -- 回合验证 / 排序 -- thought signature 清理 -- 图像负载净化 +- 轮次验证 / 排序 +- 思考签名清理 +- 图像载荷清理 - 用户输入来源标记（用于跨会话路由的提示词） -如果你需要了解转录存储细节，请参见： +如果你需要了解转录存储细节，请参阅： - [/reference/session-management-compaction](/zh-CN/reference/session-management-compaction) --- +## 全局规则：运行时上下文不是用户转录 + +运行时 / 系统上下文可以被添加到某一轮的模型提示词中，但它不是终端用户撰写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续操作、ACP、CLI 以及嵌入式 Pi 运行保留一个独立的面向转录的提示词正文。存储的可见用户轮次使用该转录正文，而不是经过运行时增强的提示词。 + +对于已经持久化了运行时包装内容的旧版会话，Gateway 网关历史记录界面会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。 + +--- + ## 运行位置 所有转录清理都集中在嵌入式运行器中： - 策略选择：`src/agents/transcript-policy.ts` -- 净化 / 修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` +- 清理 / 修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` 该策略使用 `provider`、`modelApi` 和 `modelId` 来决定应用哪些规则。 -与转录清理分开，会话文件会在加载前按需修复： +与转录清理分开的是，会话文件会在加载前按需修复： - `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded` -- 由嵌入式运行器中的 `run/attempt.ts` 和 `compact.ts` 调用 +- 从 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用 --- -## 全局规则：图像净化 +## 全局规则：图像清理 -图像负载始终会被净化，以防止因大小限制而被提供商拒绝 -（对过大的 base64 图像进行缩放 / 重新压缩）。 +图像载荷始终会被清理，以防止因大小限制导致提供商侧拒绝请求（对过大的 base64 图像进行缩放 / 重新压缩）。 -这也有助于控制支持视觉模型的图像驱动 token 压力。 -较低的最大尺寸通常会减少 token 使用量；较高的尺寸则能保留更多细节。 +这也有助于控制支持视觉能力的模型因图像导致的 token 压力。较低的最大尺寸通常会减少 token 使用量；较高的尺寸则会保留更多细节。 实现： - `src/agents/pi-embedded-helpers/images.ts` 中的 `sanitizeSessionMessagesImages` - `src/agents/tool-images.ts` 中的 `sanitizeContentBlocksImages` -- 图像最大边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认值：`1200`）。 +- 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认值：`1200`）。 --- ## 全局规则：格式错误的工具调用 -如果 assistant 工具调用块同时缺少 `input` 和 `arguments`，则会在构建模型上下文前被丢弃。 -这样可以防止提供商因部分持久化的工具调用而拒绝请求（例如在速率限制失败之后）。 +缺少 `input` 和 `arguments` 的助手工具调用块会在构建模型上下文之前被丢弃。这样可以防止提供商因部分已持久化的工具调用而拒绝请求（例如，在速率限制失败之后）。 实现： @@ -78,16 +84,14 @@ x-i18n: ## 全局规则：跨会话输入来源 -当一个智能体通过 `sessions_send` 向另一个会话发送提示词时（包括 -智能体对智能体的 reply/announce 步骤），OpenClaw 会将创建出的用户回合持久化，并附带： +当一个智能体通过 `sessions_send` 将提示词发送到另一个会话时（包括智能体到智能体的回复 / 通知步骤），OpenClaw 会在创建的用户轮次中持久化以下字段： - `message.provenance.kind = "inter_session"` -该元数据会在转录追加时写入，不会改变角色 -（为保证提供商兼容性，`role: "user"` 保持不变）。转录读取器可以利用它来避免将路由的内部提示词视为终端用户编写的指令。 +此元数据会在追加到转录时写入，不会更改角色 +（为保证提供商兼容性，仍保持 `role: "user"`）。转录读取器可以利用这一点，避免将路由的内部提示词视为终端用户撰写的指令。 -在上下文重建期间，OpenClaw 还会在内存中为这些用户回合加上一个简短的 `[Inter-session message]` -标记，以便模型将它们与外部终端用户指令区分开来。 +在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次添加一个简短的 `[Inter-session message]` 标记作为前缀，以便模型能够将它们与外部终端用户指令区分开来。 --- @@ -95,59 +99,58 @@ x-i18n: **OpenAI / OpenAI Codex** -- 仅图像净化。 -- 对于 OpenAI Responses/Codex 转录，丢弃孤立的 reasoning signature（即后面没有内容块的独立 reasoning 项）。 -- 不执行工具调用 id 净化。 -- 不执行工具结果配对修复。 -- 不执行回合验证或重排。 +- 仅进行图像清理。 +- 对于 OpenAI Responses / Codex 转录，丢弃孤立的推理签名（后面没有内容块的独立推理项）。 +- 不进行工具调用 ID 清理。 +- 不进行工具结果配对修复。 +- 不进行轮次验证或重排序。 - 不生成合成工具结果。 -- 不移除 thought signature。 +- 不剥离思考签名。 **Google（Generative AI / Gemini CLI / Antigravity）** -- 工具调用 id 净化：严格字母数字。 +- 工具调用 ID 清理：严格字母数字。 - 工具结果配对修复和合成工具结果。 -- 回合验证（Gemini 风格的回合交替）。 -- Google 回合顺序修复（如果历史记录以 assistant 开头，则前置一个很小的用户 bootstrap）。 -- Antigravity Claude：规范化 thinking signature；丢弃未签名的 thinking 块。 +- 轮次验证（Gemini 风格的轮次交替）。 +- Google 轮次顺序修复（如果历史记录以助手开头，则预置一个极小的用户引导消息）。 +- Antigravity Claude：规范化思考签名；丢弃未签名的思考块。 -**Anthropic / Minimax（兼容 Anthropic）** +**Anthropic / Minimax（Anthropic 兼容）** - 工具结果配对修复和合成工具结果。 -- 回合验证（合并连续的用户回合，以满足严格交替要求）。 +- 轮次验证（合并连续的用户轮次以满足严格交替要求）。 -**Mistral（包括基于 model-id 的检测）** +**Mistral（包括基于模型 ID 的检测）** -- 工具调用 id 净化：strict9（长度为 9 的字母数字）。 +- 工具调用 ID 清理：strict9（长度为 9 的字母数字）。 **OpenRouter Gemini** -- thought signature 清理：移除非 base64 的 `thought_signature` 值（保留 base64）。 +- 思考签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 **其他所有情况** -- 仅图像净化。 +- 仅进行图像清理。 --- ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 会应用多层转录清理： +在 2026.1.22 版本之前，OpenClaw 应用了多层转录清理： -- 一个 **transcript-sanitize 扩展** 会在每次构建上下文时运行，并且可以： +- 一个 **transcript-sanitize extension** 会在每次构建上下文时运行，并且可以： - 修复工具使用 / 结果配对。 - - 净化工具调用 id（包括保留 `_`/`-` 的非严格模式）。 -- 运行器还会执行特定于提供商的净化，这造成了重复工作。 -- 在提供商策略之外还会发生其他变更，包括： - - 在持久化前从 assistant 文本中移除 `` 标签。 - - 丢弃空的 assistant 错误回合。 - - 在工具调用之后裁剪 assistant 内容。 + - 清理工具调用 ID（包括保留 `_` / `-` 的非严格模式）。 +- 运行器也会执行提供商特定清理，这造成了重复工作。 +- 提供商策略之外还会发生其他变更，包括： + - 在持久化之前从助手文本中剥离 `` 标签。 + - 丢弃空的助手错误轮次。 + - 在工具调用之后裁剪助手内容。 -这种复杂性导致了跨提供商回归问题（尤其是 `openai-responses` -`call_id|fc_id` 配对）。2026.1.22 的清理移除了该扩展，将 -逻辑集中到运行器中，并使 OpenAI 在图像净化之外保持**不触碰**。 +这种复杂性导致了跨提供商回归问题（特别是 `openai-responses` +`call_id|fc_id` 配对）。2026.1.22 的清理工作移除了该扩展，将逻辑集中到运行器中，并让 OpenAI 除图像清理之外保持**不触碰**。 ## 相关内容 - [会话管理](/zh-CN/concepts/session) -- [会话裁剪](/zh-CN/concepts/session-pruning) +- [会话修剪](/zh-CN/concepts/session-pruning) diff --git a/docs/zh-CN/web/webchat.md b/docs/zh-CN/web/webchat.md index 0e6021331..dae1d6cf9 100644 --- a/docs/zh-CN/web/webchat.md +++ b/docs/zh-CN/web/webchat.md @@ -1,60 +1,49 @@ --- read_when: - 调试或配置 WebChat 访问 -summary: 用于聊天 UI 的 loopback WebChat 静态主机和 Gateway WS 用法 +summary: 用于聊天 UI 的 Loopback WebChat 静态主机和 Gateway 网关 WS 用法 title: WebChat x-i18n: - generated_at: "2026-04-24T04:08:21Z" + generated_at: "2026-04-24T21:20:35Z" model: gpt-5.4 provider: openai - source_hash: 466e1e92ea5b8bb979a34985b9cd9618c94a0a4a424444024edda26c46540f1e + source_hash: c112aca6c6fb29c5752fe931dcd47749acf0b8d8d505522f75b82533fc3ffb5a source_path: web/webchat.md workflow: 15 --- -状态：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway WebSocket 通信。 +状态：macOS/iOS SwiftUI 聊天 UI 直接与 Gateway 网关 WebSocket 通信。 ## 它是什么 -- 一个面向 gateway 的原生聊天 UI（没有嵌入式浏览器，也没有本地静态服务器）。 +- 一个面向 gateway 的原生聊天 UI（不嵌入浏览器，也不使用本地静态服务器）。 - 使用与其他渠道相同的会话和路由规则。 -- 确定性路由：回复总是返回到 WebChat。 +- 确定性路由：回复始终会返回到 WebChat。 ## 快速开始 1. 启动 gateway。 2. 打开 WebChat UI（macOS/iOS 应用）或 Control UI 聊天标签页。 -3. 确保已配置有效的 gateway 认证路径（默认是共享密钥， - 即使在 loopback 上也是如此）。 +3. 确保已配置有效的 gateway 身份验证路径（默认使用 shared-secret，即使在 loopback 上也是如此）。 -## 工作原理（行为） +## 它的工作方式（行为） -- UI 连接到 Gateway WebSocket，并使用 `chat.history`、`chat.send` 和 `chat.inject`。 -- `chat.history` 为了稳定性设置了边界：Gateway 网关可能会截断长文本字段、省略较重的元数据，并将过大的条目替换为 `[chat.history omitted: message too large]`。 -- `chat.history` 也会进行显示规范化：内联投递指令标签 - 例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、纯文本工具调用 XML - 有效负载（包括 `...`、 - `...`、`...`、 - `...` 以及被截断的工具调用块），还有 - 泄露的 ASCII/全角模型控制令牌，都会从可见文本中移除；而那些整个可见文本仅为精确静默 - 令牌 `NO_REPLY` / `no_reply` 的助手条目会被省略。 -- `chat.inject` 会将一条助手备注直接附加到记录中，并广播到 UI（不会运行智能体）。 -- 已中止的运行可能会在 UI 中保留部分助手输出可见。 -- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到记录历史中，并为这些条目标记中止元数据。 -- 历史始终从 gateway 获取（不监视本地文件）。 +- UI 连接到 Gateway 网关 WebSocket，并使用 `chat.history`、`chat.send` 和 `chat.inject`。 +- `chat.history` 为了稳定性进行了边界限制：Gateway 网关可能会截断长文本字段、省略较重的元数据，并将超大条目替换为 `[chat.history omitted: message too large]`。 +- `chat.history` 还会进行显示规范化：仅运行时存在的 OpenClaw 上下文、入站信封包装器、内联投递指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块），以及泄漏的 ASCII/全角模型控制令牌，都会从可见文本中移除；而且当 assistant 条目的全部可见文本仅为精确的静默令牌 `NO_REPLY` / `no_reply` 时，该条目会被省略。 +- `chat.inject` 会将一条 assistant 注释直接追加到转录中，并广播给 UI（不会运行智能体）。 +- 已中止的运行可能会让部分 assistant 输出继续在 UI 中可见。 +- 当存在已缓冲输出时，Gateway 网关会将已中止的部分 assistant 文本持久化到转录历史中，并为这些条目标记中止元数据。 +- 历史记录始终从 gateway 获取（不会监视本地文件）。 - 如果 gateway 不可达，WebChat 为只读。 ## Control UI 智能体工具面板 -- Control UI 的 `/agents` 工具面板有两个独立视图： - - **Available Right Now** 使用 `tools.effective(sessionKey=...)`，显示当前 - 会话在运行时实际可用的内容，包括核心、插件和渠道自有工具。 - - **Tool Configuration** 使用 `tools.catalog`，并聚焦于 profiles、overrides 以及 - catalog 语义。 -- 运行时可用性是会话范围的。在同一个智能体上切换会话，可能会改变 - **Available Right Now** 列表。 -- 配置编辑器并不意味着运行时可用性；实际访问仍遵循策略 - 优先级（`allow`/`deny`、按智能体以及提供商/渠道的 overrides）。 +- Control UI 的 `/agents` Tools 面板有两个独立视图： + - **当前可用** 使用 `tools.effective(sessionKey=...)`，显示当前会话在运行时实际可以使用的内容，包括核心、插件和渠道拥有的工具。 + - **工具配置** 使用 `tools.catalog`，并继续聚焦于配置文件、覆盖项和目录语义。 +- 运行时可用性是会话范围的。在同一智能体上切换会话可能会改变 **当前可用** 列表。 +- 配置编辑器并不意味着运行时可用；实际访问仍遵循策略优先级（`allow`/`deny`、每个智能体以及提供商/渠道覆盖）。 ## 远程使用 @@ -63,20 +52,18 @@ x-i18n: ## 配置参考（WebChat） -完整配置： [配置](/zh-CN/gateway/configuration) +完整配置：[配置](/zh-CN/gateway/configuration) WebChat 选项： -- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当某个记录条目超过此限制时，Gateway 网关会截断长文本字段，并可能用占位符替换过大的消息。客户端也可以在每次请求中发送 `maxChars`，以覆盖单次 `chat.history` 调用的默认值。 +- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 响应中文本字段的最大字符数。当某个转录条目超过此限制时，Gateway 网关会截断长文本字段，并可能用占位符替换超大消息。客户端还可以发送每次请求的 `maxChars`，以便仅对单次 `chat.history` 调用覆盖此默认值。 -相关的全局选项： +相关全局选项： - `gateway.port`、`gateway.bind`：WebSocket 主机/端口。 -- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`： - 共享密钥 WebSocket 认证。 -- `gateway.auth.allowTailscale`：启用后，浏览器 Control UI 聊天标签页可使用 Tailscale - Serve 身份头。 -- `gateway.auth.mode: "trusted-proxy"`：用于位于身份感知**非 loopback**代理源之后的浏览器客户端的反向代理认证（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 +- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：shared-secret WebSocket 身份验证。 +- `gateway.auth.allowTailscale`：启用后，浏览器中的 Control UI 聊天标签页可以使用 Tailscale Serve 身份标头。 +- `gateway.auth.mode: "trusted-proxy"`：为位于身份感知型 **非 loopback** 代理源之后的浏览器客户端提供反向代理身份验证（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。 - `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：远程 gateway 目标。 - `session.*`：会话存储和主键默认值。