Docs: add zh-CN translations

2026-04-25 03:58:38 +00:00 · 2026-02-01 22:47:44 +01:00
parent e70984745b
commit 149dc7c4e7
298 changed files with 53861 additions and 0 deletions
--- a/docs/zh-CN/experiments/plans/cron-add-hardening.md
+++ b/docs/zh-CN/experiments/plans/cron-add-hardening.md
@@ -0,0 +1,70 @@
+---
+last_updated: "2026-01-05"
+owner: openclaw
+status: complete
+summary: 加固 cron.add 输入处理，对齐 schema，并改进 cron UI/智能体工具
+title: Cron Add 加固
+x-i18n:
+  generated_at: "2026-02-01T20:25:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
+  source_path: experiments/plans/cron-add-hardening.md
+  workflow: 14
+---
+
+# Cron Add 加固与 Schema 对齐
+
+## 背景
+
+近期 Gateway 日志显示 `cron.add` 反复因无效参数（缺少 `sessionTarget`、`wakeMode`、`payload` 以及格式错误的 `schedule`）而失败。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装过的或部分指定的任务载荷。此外，TypeScript、Gateway schema、CLI 标志和 UI 表单类型之间的 cron 提供商枚举存在偏差，同时 `cron.status` 的 UI 也存在不匹配问题（期望 `jobCount`，而 Gateway 返回的是 `jobs`）。
+
+## 目标
+
+- 通过标准化常见的包装载荷并推断缺失的 `kind` 字段，消除 `cron.add` 的 INVALID_REQUEST 错误。
+- 在 Gateway schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
+- 明确智能体 cron 工具 schema，使 LLM 生成正确的任务载荷。
+- 修复 Control UI 中 cron 状态的任务计数显示。
+- 添加测试以覆盖标准化和工具行为。
+
+## 非目标
+
+- 更改 cron 调度语义或任务执行行为。
+- 添加新的调度类型或 cron 表达式解析。
+- 在必要的字段修复之外全面改造 cron 的 UI/UX。
+
+## 发现（当前差距）
+
+- Gateway 中的 `CronPayloadSchema` 不包含 `signal` + `imessage`，而 TS 类型中包含它们。
+- Control UI 的 CronStatus 期望 `jobCount`，但 Gateway 返回的是 `jobs`。
+- 智能体 cron 工具 schema 允许任意 `job` 对象，导致格式错误的输入。
+- Gateway 严格验证 `cron.add` 且不进行标准化，因此包装过的载荷会失败。
+
+## 变更内容
+
+- `cron.add` 和 `cron.update` 现在会标准化常见的包装结构并推断缺失的 `kind` 字段。
+- 智能体 cron 工具 schema 与 Gateway schema 保持一致，减少了无效载荷。
+- 提供商枚举已在 Gateway、CLI、UI 和 macOS 选择器之间对齐。
+- Control UI 使用 Gateway 的 `jobs` 计数字段显示状态。
+
+## 当前行为
+
+- **标准化：** 包装的 `data`/`job` 载荷会被解包；在安全的情况下推断 `schedule.kind` 和 `payload.kind`。
+- **默认值：** 当 `wakeMode` 和 `sessionTarget` 缺失时，应用安全的默认值。
+- **提供商：** Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致地显示。
+
+请参阅 [Cron 任务](/automation/cron-jobs) 了解标准化后的结构和示例。
+
+## 验证
+
+- 监控 Gateway 日志，确认 `cron.add` INVALID_REQUEST 错误已减少。
+- 确认 Control UI 的 cron 状态在刷新后显示任务计数。
+
+## 可选后续工作
+
+- 手动 Control UI 冒烟测试：为每个提供商添加一个 cron 任务，并验证状态任务计数。
+
+## 待解决问题
+
+- `cron.add` 是否应接受客户端显式指定的 `state`（目前被 schema 禁止）？
+- 是否应允许 `webchat` 作为显式的投递提供商（目前在投递解析中被过滤）？
--- a/docs/zh-CN/experiments/plans/group-policy-hardening.md
+++ b/docs/zh-CN/experiments/plans/group-policy-hardening.md
@@ -0,0 +1,45 @@
+---
+read_when:
+  - 审查 Telegram 允许列表的历史变更
+summary: Telegram 允许列表加固：前缀与空白字符规范化
+title: Telegram 允许列表加固
+x-i18n:
+  generated_at: "2026-02-01T20:25:02Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
+  source_path: experiments/plans/group-policy-hardening.md
+  workflow: 14
+---
+
+# Telegram 允许列表加固
+
+**日期**：2026-01-05  
+**状态**：已完成  
+**PR**：#216
+
+## 概要
+
+Telegram 允许列表现在以不区分大小写的方式接受 `telegram:` 和 `tg:` 前缀，并容许意外的空白字符。这使得入站允许列表检查与出站发送的规范化保持一致。
+
+## 变更内容
+
+- 前缀 `telegram:` 和 `tg:` 被视为相同（不区分大小写）。
+- 允许列表条目会被修剪空白；空条目将被忽略。
+
+## 示例
+
+以下所有格式均被接受为同一 ID：
+
+- `telegram:123456`
+- `TG:123456`
+- `tg:123456`
+
+## 重要性
+
+从日志或聊天 ID 中复制粘贴时经常会包含前缀和空白字符。规范化处理可以避免在决定是否响应私聊或群组消息时出现误判。
+
+## 相关文档
+
+- [群组聊天](/concepts/groups)
+- [Telegram 渠道](/channels/telegram)
--- a/docs/zh-CN/experiments/plans/openresponses-gateway.md
+++ b/docs/zh-CN/experiments/plans/openresponses-gateway.md
@@ -0,0 +1,121 @@
+---
+last_updated: "2026-01-19"
+owner: openclaw
+status: 草稿
+summary: 计划：添加 OpenResponses /v1/responses 端点并平稳废弃 Chat Completions
+title: OpenResponses Gateway 计划
+x-i18n:
+  generated_at: "2026-02-01T20:25:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 71a22c48397507d1648b40766a3153e420c54f2a2d5186d07e51eb3d12e4636a
+  source_path: experiments/plans/openresponses-gateway.md
+  workflow: 14
+---
+
+# OpenResponses Gateway 集成计划
+
+## 背景
+
+OpenClaw Gateway 当前在 `/v1/chat/completions` 暴露了一个最小化的 OpenAI 兼容 Chat Completions 端点（参见 [OpenAI Chat Completions](/gateway/openai-http-api)）。
+
+Open Responses 是一个基于 OpenAI Responses API 的开放推理标准。它专为智能体工作流设计，使用基于项目的输入和语义化流式事件。OpenResponses 规范定义的是 `/v1/responses`，而非 `/v1/chat/completions`。
+
+## 目标
+
+- 添加一个遵循 OpenResponses 语义的 `/v1/responses` 端点。
+- 将 Chat Completions 保留为兼容层，便于禁用并最终移除。
+- 使用隔离的、可复用的 schema 标准化验证和解析。
+
+## 非目标
+
+- 第一阶段不追求完整的 OpenResponses 功能对等（图片、文件、托管工具）。
+- 不替换内部智能体执行逻辑或工具编排。
+- 第一阶段不改变现有 `/v1/chat/completions` 的行为。
+
+## 研究摘要
+
+来源：OpenResponses OpenAPI、OpenResponses 规范站点和 Hugging Face 博客文章。
+
+提取的关键要点：
+
+- `POST /v1/responses` 接受 `CreateResponseBody` 字段，包括 `model`、`input`（字符串或 `ItemParam[]`）、`instructions`、`tools`、`tool_choice`、`stream`、`max_output_tokens` 和 `max_tool_calls`。
+- `ItemParam` 是一个可区分联合类型，包含：
+  - 角色为 `system`、`developer`、`user`、`assistant` 的 `message` 项
+  - `function_call` 和 `function_call_output`
+  - `reasoning`
+  - `item_reference`
+- 成功响应返回一个 `ResponseResource`，包含 `object: "response"`、`status` 和 `output` 项。
+- 流式传输使用语义化事件，例如：
+  - `response.created`、`response.in_progress`、`response.completed`、`response.failed`
+  - `response.output_item.added`、`response.output_item.done`
+  - `response.content_part.added`、`response.content_part.done`
+  - `response.output_text.delta`、`response.output_text.done`
+- 规范要求：
+  - `Content-Type: text/event-stream`
+  - `event:` 必须与 JSON 的 `type` 字段匹配
+  - 终止事件必须是字面量 `[DONE]`
+- 推理项可以暴露 `content`、`encrypted_content` 和 `summary`。
+- HF 示例在请求中包含 `OpenResponses-Version: latest`（可选头部）。
+
+## 建议架构
+
+- 添加 `src/gateway/open-responses.schema.ts`，仅包含 Zod schema（不引入 Gateway 依赖）。
+- 添加 `src/gateway/openresponses-http.ts`（或 `open-responses-http.ts`）用于 `/v1/responses`。
+- 保持 `src/gateway/openai-http.ts` 不变，作为旧版兼容适配器。
+- 添加配置 `gateway.http.endpoints.responses.enabled`（默认 `false`）。
+- 保持 `gateway.http.endpoints.chatCompletions.enabled` 独立；允许两个端点分别切换。
+- 当 Chat Completions 启用时，在启动时发出警告以提示其旧版状态。
+
+## Chat Completions 废弃路径
+
+- 维护严格的模块边界：Responses 和 Chat Completions 之间不共享 schema 类型。
+- 通过配置使 Chat Completions 变为可选启用，这样无需修改代码即可禁用。
+- 待 `/v1/responses` 稳定后，更新文档将 Chat Completions 标记为旧版。
+- 可选的未来步骤：将 Chat Completions 请求映射到 Responses 处理器，以简化移除路径。
+
+## 第一阶段支持子集
+
+- 接受 `input` 为字符串或包含消息角色和 `function_call_output` 的 `ItemParam[]`。
+- 将 system 和 developer 消息提取到 `extraSystemPrompt` 中。
+- 使用最近的 `user` 或 `function_call_output` 作为智能体运行的当前消息。
+- 对不支持的内容部分（图片/文件）返回 `invalid_request_error` 拒绝。
+- 返回包含 `output_text` 内容的单条助手消息。
+- 返回 `usage`，在接入令牌计量之前使用零值。
+
+## 验证策略（无 SDK）
+
+- 为以下支持的子集实现 Zod schema：
+  - `CreateResponseBody`
+  - `ItemParam` + 消息内容部分联合类型
+  - `ResponseResource`
+  - Gateway 使用的流式事件结构
+- 将 schema 保存在单个隔离模块中，以避免漂移并支持未来的代码生成。
+
+## 流式实现（第一阶段）
+
+- SSE 行同时包含 `event:` 和 `data:`。
+- 必需的序列（最小可行方案）：
+  - `response.created`
+  - `response.output_item.added`
+  - `response.content_part.added`
+  - `response.output_text.delta`（按需重复）
+  - `response.output_text.done`
+  - `response.content_part.done`
+  - `response.completed`
+  - `[DONE]`
+
+## 测试和验证计划
+
+- 为 `/v1/responses` 添加端到端测试覆盖：
+  - 需要认证
+  - 非流式响应结构
+  - 流式事件顺序和 `[DONE]`
+  - 使用头部和 `user` 的会话路由
+- 保持 `src/gateway/openai-http.e2e.test.ts` 不变。
+- 手动测试：使用 curl 请求 `/v1/responses`，设置 `stream: true`，验证事件顺序和终止 `[DONE]`。
+
+## 文档更新（后续）
+
+- 为 `/v1/responses` 的用法和示例添加新的文档页面。
+- 在 `/gateway/openai-http-api` 中添加旧版说明并指向 `/v1/responses`。