From 9f5a81b4b0d551836bbee9f8acc6b907cd86e802 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 4 May 2026 23:37:57 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/reference/transcript-hygiene.md | 131 +++++++++++---------- 1 file changed, 66 insertions(+), 65 deletions(-) diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index 4c750f1c0..63809e8bc 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -1,100 +1,100 @@ --- read_when: - - 你正在调试与对话记录结构相关的提供商请求拒绝问题 + - 你正在调试与对话记录结构相关的提供商请求被拒问题 - 你正在更改会话记录清理或工具调用修复逻辑 - - 你正在调查不同提供商之间的工具调用 ID 不匹配问题 -summary: 参考：特定于提供商的会话记录清理和修复规则 + - 你正在调查各提供商之间的 tool-call id 不匹配问题 +summary: 参考：提供商特定的会话记录清理和修复规则 title: 会话记录整理 x-i18n: - generated_at: "2026-05-03T04:08:37Z" + generated_at: "2026-05-04T23:37:24Z" model: gpt-5.5 provider: openai - source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab + source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0 source_path: reference/transcript-hygiene.md workflow: 16 --- -OpenClaw 会在运行前（构建模型上下文时）对对话记录应用**提供商特定的修复**。其中大多数是**内存中**调整，用于满足严格的提供商要求。单独的会话文件修复流程也可能在加载会话前重写已存储的 JSONL，但仅限格式错误的行或无效持久记录的已持久化回合。已交付的助手回复会保留在磁盘上；提供商特定的助手预填充剥离只会在构造出站载荷时发生。发生修复时，原始文件会备份在会话文件旁边。 +OpenClaw 会在运行前（构建模型上下文时）对转录应用**特定提供商的修正**。其中大多数是在**内存中**进行的调整，用于满足严格的提供商要求。单独的会话文件修复流程也可能在加载会话前重写存储的 JSONL，但仅限格式错误的行或作为持久记录无效的已持久化轮次。已交付的助手回复会保留在磁盘上；特定提供商的助手预填内容剥离只会在构造出站 payload 时发生。发生修复时，原始文件会在会话文件旁边备份。 范围包括： -- 仅运行时的提示上下文不进入用户可见的对话记录回合 +- 仅运行时使用的提示上下文不进入用户可见的转录轮次 - 工具调用 ID 清理 - 工具调用输入验证 - 工具结果配对修复 -- 回合验证 / 排序 -- Thought 签名清理 +- 轮次验证 / 排序 +- 思考签名清理 - Thinking 签名清理 -- 图像载荷清理 -- 提供商重放前清理空白文本块 +- 图像 payload 清理 +- 提供商重放前的空白文本块清理 - 用户输入来源标记（用于跨会话路由的提示） -- Bedrock Converse 重放的空助手错误回合修复 +- Bedrock Converse 重放的空助手错误轮次修复 -如果你需要对话记录存储详情，请参阅： +如果你需要转录存储细节，请参见： -- [会话管理深度解析](/zh-CN/reference/session-management-compaction) +- [会话管理深入解析](/zh-CN/reference/session-management-compaction) --- -## 全局规则：运行时上下文不是用户对话记录 +## 全局规则：运行时上下文不是用户转录 -运行时/系统上下文可以添加到某个回合的模型提示中，但它不是终端用户创作的内容。OpenClaw 会为 Gateway 网关回复、排队的后续消息、ACP、CLI 和嵌入式 Pi 运行保留单独面向对话记录的提示正文。已存储的可见用户回合使用该对话记录正文，而不是包含运行时增强内容的提示。 +运行时/系统上下文可以添加到某一轮的模型提示中，但它不是最终用户编写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续消息、ACP、CLI 和嵌入式 Pi 运行保留一个单独面向转录的提示正文。存储的可见用户轮次会使用该转录正文，而不是运行时增强后的提示。 -对于已经持久化运行时包装器的旧版会话，Gateway 网关历史记录界面会在向 WebChat、TUI、REST 或 SSE 客户端返回消息前应用显示投影。 +对于已经持久化运行时包装的旧版会话，Gateway 网关历史记录接口会在向 WebChat、TUI、REST 或 SSE 客户端返回消息前应用显示投影。 --- ## 运行位置 -所有对话记录卫生处理都集中在嵌入式运行器中： +所有转录清理都集中在嵌入式 runner 中： - 策略选择：`src/agents/transcript-policy.ts` - 清理/修复应用：`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`（嵌入式 runner）调用 --- ## 全局规则：图像清理 -图像载荷始终会被清理，以防提供商端因大小限制而拒绝（对过大的 base64 图像进行降采样/重新压缩）。 +图像 payload 始终会被清理，以防因大小限制导致提供商端拒绝（对超大的 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`）。 +- 此流程遍历重放内容时会移除空白文本块。变为空的助手轮次会从重放副本中删除；变为空的用户和工具结果轮次会收到一个非空的已省略内容占位符。 --- ## 全局规则：格式错误的工具调用 -在构建模型上下文之前，会删除同时缺少 `input` 和 `arguments` 的助手工具调用块。这可以防止提供商因部分持久化的工具调用而拒绝请求（例如，在速率限制失败之后）。 +缺少 `input` 和 `arguments` 的助手工具调用块会在构建模型上下文前被丢弃。这可以避免提供商因部分持久化的工具调用而拒绝请求（例如在触发速率限制失败后）。 实现： - `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs` -- 在 `src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` 应用 +- 在 `src/agents/pi-embedded-runner/replay-history.ts` 的 `sanitizeSessionHistory` 中应用 --- ## 全局规则：跨会话输入来源 -当智能体通过 `sessions_send` 向另一个会话发送提示时（包括智能体到智能体的回复/公告步骤），OpenClaw 会持久化创建的用户回合并设置： +当智能体通过 `sessions_send` 向另一个会话发送提示时（包括智能体到智能体的回复/公告步骤），OpenClaw 会将创建的用户轮次持久化，并带有： - `message.provenance.kind = "inter_session"` -OpenClaw 还会在路由后的提示文本前添加同一回合的 `[Inter-session message ... isUser=false]` 标记，使活跃模型调用能够区分外部会话输出和外部终端用户指令。此标记在可用时包含源会话、渠道和工具。为兼容提供商，对话记录仍使用 `role: "user"`，但可见文本和来源元数据都会将该回合标记为跨会话数据。 +OpenClaw 还会在被路由的提示文本前加上同一轮的 `[Inter-session message ... isUser=false]` 标记，以便当前模型调用能够区分外部会话输出和外部最终用户指令。此标记会在可用时包含源会话、渠道和工具。为兼容提供商，转录仍使用 `role: "user"`，但可见文本和来源元数据都会将该轮次标记为跨会话数据。 -在上下文重建期间，OpenClaw 会对仅有来源元数据的较旧持久化跨会话用户回合应用同一标记。 +在上下文重建期间，OpenClaw 会将同样的标记应用到较早持久化、仅包含来源元数据的跨会话用户轮次。 --- @@ -102,79 +102,80 @@ OpenClaw 还会在路由后的提示文本前添加同一回合的 `[Inter-sessi **OpenAI / OpenAI Codex** -- 仅图像清理。 -- 对 OpenAI Responses/Codex 对话记录，删除孤立的 reasoning 签名（后面没有内容块的独立 reasoning 项），并在模型路由切换后删除可重放的 OpenAI reasoning。 -- 保留可重放的 OpenAI Responses reasoning 项载荷，包括加密的空摘要项，以便手动/WebSocket 重放保留与助手输出项配对所需的 `rs_*` 状态。 +- 仅进行图像清理。 +- 对 OpenAI Responses/Codex 转录丢弃孤立的 reasoning 签名（没有后续内容块的独立 reasoning 项），并在模型路由切换后丢弃可重放的 OpenAI reasoning。 +- 保留可重放的 OpenAI Responses reasoning 项 payload，包括加密的空摘要项，以便手动/WebSocket 重放能让所需的 `rs_*` 状态与助手输出项保持配对。 +- 原生 ChatGPT Codex Responses 遵循 Codex wire 对等行为，在不携带先前 item ID 的情况下重放之前的 Responses reasoning/message/function payload，同时保留会话 `prompt_cache_key`。 - 不清理工具调用 ID。 - 工具结果配对修复可能会移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 -- 不进行回合验证或重排。 +- 不进行轮次验证或重排序。 - 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 重放规范化。 -- 不剥离 thought 签名。 +- 不剥离思考签名。 -**OpenAI 兼容的 Gemma 4** +**兼容 OpenAI 的 Gemma 4** -- 历史助手 thinking/reasoning 块会在重放前被剥离，因此本地 OpenAI 兼容 Gemma 4 服务器不会收到前序回合的 reasoning 内容。 -- 当前同一回合的工具调用延续会保留附加到工具调用的助手 reasoning 块，直到工具结果已被重放。 +- 历史助手 thinking/reasoning 块会在重放前被剥离，因此本地兼容 OpenAI 的 Gemma 4 服务器不会收到先前轮次的 reasoning 内容。 +- 当前同一轮工具调用续接会保留附加到工具调用的助手 reasoning 块，直到工具结果完成重放。 **Google（Generative AI / Gemini CLI / Antigravity）** - 工具调用 ID 清理：严格字母数字。 - 工具结果配对修复和合成工具结果。 -- 回合验证（Gemini 风格的回合交替）。 -- Google 回合排序修正（如果历史记录以助手开头，则前置一个微小的用户 bootstrap）。 -- Antigravity Claude：规范化 thinking 签名；删除未签名的 thinking 块。 +- 轮次验证（Gemini 风格轮次交替）。 +- Google 轮次排序修正（如果历史记录以助手开头，则前置一个极小的用户引导）。 +- Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。 -**Anthropic / Minimax（Anthropic 兼容）** +**Anthropic / Minimax（兼容 Anthropic）** - 工具结果配对修复和合成工具结果。 -- 回合验证（合并连续用户回合以满足严格交替）。 -- 当启用 thinking 时，尾部助手预填充回合会从出站 Anthropic Messages 载荷中剥离，包括 Cloudflare AI Gateway 网关路由。 -- 在提供商转换之前，会剥离缺失、为空或空白重放签名的 thinking 块。如果这使助手回合变为空，OpenClaw 会使用非空的已省略 reasoning 文本保留回合形状。 -- 必须剥离的较旧纯 thinking 助手回合会替换为非空的已省略 reasoning 文本，这样提供商适配器不会丢弃重放回合。 +- 轮次验证（合并连续用户轮次以满足严格交替要求）。 +- 启用 thinking 时，会从出站 Anthropic Messages payload 中剥离末尾的助手预填轮次，包括 Cloudflare AI Gateway 网关路由。 +- 缺失、为空或空白重放签名的 thinking 块会在提供商转换前被剥离。如果这会使助手轮次变空，OpenClaw 会使用非空的已省略 reasoning 文本保留轮次形状。 +- 必须剥离的较旧纯 thinking 助手轮次会替换为非空的已省略 reasoning 文本，这样提供商适配器不会丢弃该重放轮次。 **Amazon Bedrock（Converse API）** -- 空助手流错误回合会在重放前修复为非空后备文本块。Bedrock Converse 会拒绝 `content: []` 的助手消息，因此带有 `stopReason: "error"` 且内容为空的持久化助手回合也会在加载前在磁盘上修复。 -- 仅包含空白文本块的助手流错误回合会从内存重放副本中删除，而不是重放无效的空白块。 -- 在 Converse 重放前，会剥离缺失、为空或空白重放签名的 Claude thinking 块。如果这使助手回合变为空，OpenClaw 会使用非空的已省略 reasoning 文本保留回合形状。 -- 必须剥离的较旧纯 thinking 助手回合会替换为非空的已省略 reasoning 文本，以便 Converse 重放保持严格回合形状。 -- 重放会过滤 OpenClaw 交付镜像和 Gateway 网关注入的助手回合。 -- 图像清理通过全局规则应用。 +- 空助手流错误轮次会在重放前修复为非空的回退文本块。Bedrock Converse 会拒绝包含 `content: []` 的助手消息，因此带有 `stopReason: "error"` 且内容为空的已持久化助手轮次也会在加载前在磁盘上修复。 +- 仅包含空白文本块的助手流错误轮次会从内存中的重放副本中删除，而不是重放无效的空白块。 +- 缺失、为空或空白重放签名的 Claude thinking 块会在 Converse 重放前被剥离。如果这会使助手轮次变空，OpenClaw 会使用非空的已省略 reasoning 文本保留轮次形状。 +- 必须剥离的较旧纯 thinking 助手轮次会替换为非空的已省略 reasoning 文本，这样 Converse 重放会保持严格轮次形状。 +- 重放会过滤 OpenClaw delivery-mirror 和 Gateway 网关注入的助手轮次。 +- 图像清理按全局规则应用。 **Mistral（包括基于模型 ID 的检测）** -- 工具调用 ID 清理：strict9（字母数字，长度 9）。 +- 工具调用 ID 清理：strict9（字母数字，长度为 9）。 **OpenRouter Gemini** -- Thought 签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 +- 思考签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 **OpenRouter Anthropic** -- 当启用 reasoning 时，经验证的 OpenRouter OpenAI 兼容 Anthropic 模型载荷会剥离尾部助手预填充回合，与直接 Anthropic 和 Cloudflare Anthropic 重放行为一致。 +- 启用 reasoning 时，会从已验证的 OpenRouter 兼容 OpenAI 的 Anthropic 模型 payload 中剥离末尾的助手预填轮次，以匹配直接 Anthropic 和 Cloudflare Anthropic 的重放行为。 -**其他所有提供商** +**其他所有情况** -- 仅图像清理。 +- 仅进行图像清理。 --- ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 应用了多层对话记录卫生处理： +在 2026.1.22 版本之前，OpenClaw 应用了多层转录清理： -- 每次构建上下文时都会运行一个**对话记录清理插件**，并且可以： +- 一个 **transcript-sanitize 插件**会在每次上下文构建时运行，并且可以： - 修复工具使用/结果配对。 - 清理工具调用 ID（包括保留 `_`/`-` 的非严格模式）。 -- 运行器还会执行提供商特定的清理，造成重复工作。 -- 其他变更发生在提供商策略之外，包括： +- runner 也会执行特定提供商的清理，造成重复工作。 +- 提供商策略之外还发生了其他变更，包括： - 在持久化前从助手文本中剥离 `` 标签。 - - 删除空助手错误回合。 - - 在工具调用后裁剪助手内容。 + - 丢弃空助手错误轮次。 + - 在工具调用后截断助手内容。 -这种复杂性导致了跨提供商回归（尤其是 `openai-responses` 的 `call_id|fc_id` 配对）。2026.1.22 清理移除了该插件，将逻辑集中到运行器中，并让 OpenAI 除图像清理外保持**不触碰**。 +这种复杂性导致了跨提供商回归（尤其是 `openai-responses` 的 `call_id|fc_id` 配对）。2026.1.22 的清理移除了该插件，将逻辑集中到 runner 中，并使 OpenAI 在图像清理之外保持**不改动**。 -## 相关 +## 相关内容 - [会话管理](/zh-CN/concepts/session) -- [会话剪枝](/zh-CN/concepts/session-pruning) +- [会话裁剪](/zh-CN/concepts/session-pruning)