mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-28 21:01:43 +03:00
Docs: update zh-CN translations and pipeline
What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
This commit is contained in:
@@ -2,69 +2,69 @@
|
||||
last_updated: "2026-01-05"
|
||||
owner: openclaw
|
||||
status: complete
|
||||
summary: 加固 cron.add 输入处理,对齐 schema,并改进 cron UI/智能体工具
|
||||
summary: 加固 cron.add 输入处理,对齐 schema,改进 cron UI/智能体工具
|
||||
title: Cron Add 加固
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:25:08Z"
|
||||
generated_at: "2026-02-03T07:47:26Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
|
||||
source_path: experiments/plans/cron-add-hardening.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Cron Add 加固与 Schema 对齐
|
||||
# Cron Add 加固 & Schema 对齐
|
||||
|
||||
## 背景
|
||||
|
||||
近期 Gateway网关日志显示 `cron.add` 反复因无效参数(缺少 `sessionTarget`、`wakeMode`、`payload` 以及格式错误的 `schedule`)而失败。这表明至少有一个客户端(可能是智能体工具调用路径)正在发送包装过的或部分指定的任务载荷。此外,TypeScript、Gateway网关 schema、CLI 标志和 UI 表单类型之间的 cron 提供商枚举存在偏差,同时 `cron.status` 的 UI 也存在不匹配问题(期望 `jobCount`,而 Gateway网关返回的是 `jobs`)。
|
||||
最近的 Gateway 网关日志显示重复的 `cron.add` 失败,参数无效(缺少 `sessionTarget`、`wakeMode`、`payload`,以及格式错误的 `schedule`)。这表明至少有一个客户端(可能是智能体工具调用路径)正在发送包装的或部分指定的任务负载。另外,TypeScript 中的 cron 提供商枚举、Gateway 网关 schema、CLI 标志和 UI 表单类型之间存在漂移,加上 `cron.status` 的 UI 不匹配(期望 `jobCount` 而 Gateway 网关返回 `jobs`)。
|
||||
|
||||
## 目标
|
||||
|
||||
- 通过标准化常见的包装载荷并推断缺失的 `kind` 字段,消除 `cron.add` 的 INVALID_REQUEST 错误。
|
||||
- 在 Gateway网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
|
||||
- 明确智能体 cron 工具 schema,使 LLM 生成正确的任务载荷。
|
||||
- 修复 Control UI 中 cron 状态的任务计数显示。
|
||||
- 添加测试以覆盖标准化和工具行为。
|
||||
- 通过规范化常见的包装负载并推断缺失的 `kind` 字段来停止 `cron.add` INVALID_REQUEST 垃圾。
|
||||
- 在 Gateway 网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
|
||||
- 使智能体 cron 工具 schema 明确,以便 LLM 生成正确的任务负载。
|
||||
- 修复 Control UI cron 状态任务计数显示。
|
||||
- 添加测试以覆盖规范化和工具行为。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 更改 cron 调度语义或任务执行行为。
|
||||
- 添加新的调度类型或 cron 表达式解析。
|
||||
- 在必要的字段修复之外全面改造 cron 的 UI/UX。
|
||||
- 除了必要的字段修复外,不大改 cron 的 UI/UX。
|
||||
|
||||
## 发现(当前差距)
|
||||
|
||||
- Gateway网关中的 `CronPayloadSchema` 不包含 `signal` + `imessage`,而 TS 类型中包含它们。
|
||||
- Control UI 的 CronStatus 期望 `jobCount`,但 Gateway网关返回的是 `jobs`。
|
||||
- Gateway 网关中的 `CronPayloadSchema` 排除了 `signal` + `imessage`,而 TS 类型包含它们。
|
||||
- Control UI CronStatus 期望 `jobCount`,但 Gateway 网关返回 `jobs`。
|
||||
- 智能体 cron 工具 schema 允许任意 `job` 对象,导致格式错误的输入。
|
||||
- Gateway网关严格验证 `cron.add` 且不进行标准化,因此包装过的载荷会失败。
|
||||
- Gateway 网关严格验证 `cron.add` 而不进行规范化,因此包装的负载会失败。
|
||||
|
||||
## 变更内容
|
||||
|
||||
- `cron.add` 和 `cron.update` 现在会标准化常见的包装结构并推断缺失的 `kind` 字段。
|
||||
- 智能体 cron 工具 schema 与 Gateway网关 schema 保持一致,减少了无效载荷。
|
||||
- 提供商枚举已在 Gateway网关、CLI、UI 和 macOS 选择器之间对齐。
|
||||
- Control UI 使用 Gateway网关的 `jobs` 计数字段显示状态。
|
||||
- `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 中一致地显示。
|
||||
- **规范化:**包装的 `data`/`job` 负载被解包;`schedule.kind` 和 `payload.kind` 在安全时被推断。
|
||||
- **默认值:**当缺失时,为 `wakeMode` 和 `sessionTarget` 应用安全默认值。
|
||||
- **提供商:**Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致显示。
|
||||
|
||||
请参阅 [Cron 任务](/automation/cron-jobs) 了解标准化后的结构和示例。
|
||||
参见 [Cron 任务](/automation/cron-jobs) 了解规范化的形式和示例。
|
||||
|
||||
## 验证
|
||||
|
||||
- 监控 Gateway网关日志,确认 `cron.add` INVALID_REQUEST 错误已减少。
|
||||
- 确认 Control UI 的 cron 状态在刷新后显示任务计数。
|
||||
- 观察 Gateway 网关日志中 `cron.add` INVALID_REQUEST 错误是否减少。
|
||||
- 确认 Control UI cron 状态在刷新后显示任务计数。
|
||||
|
||||
## 可选后续工作
|
||||
|
||||
- 手动 Control UI 冒烟测试:为每个提供商添加一个 cron 任务,并验证状态任务计数。
|
||||
- 手动 Control UI 冒烟测试:为每个提供商添加一个 cron 任务 + 验证状态任务计数。
|
||||
|
||||
## 待解决问题
|
||||
## 开放问题
|
||||
|
||||
- `cron.add` 是否应接受客户端显式指定的 `state`(目前被 schema 禁止)?
|
||||
- 是否应允许 `webchat` 作为显式的投递提供商(目前在投递解析中被过滤)?
|
||||
- `cron.add` 是否应该接受来自客户端的显式 `state`(当前被 schema 禁止)?
|
||||
- 我们是否应该允许 `webchat` 作为显式投递提供商(当前在投递解析中被过滤)?
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- 审查 Telegram 允许列表的历史变更
|
||||
summary: Telegram 允许列表加固:前缀与空白字符规范化
|
||||
- 查看历史 Telegram 允许列表更改
|
||||
summary: Telegram 允许列表加固:前缀 + 空白规范化
|
||||
title: Telegram 允许列表加固
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:25:02Z"
|
||||
generated_at: "2026-02-03T07:47:16Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
|
||||
source_path: experiments/plans/group-policy-hardening.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Telegram 允许列表加固
|
||||
@@ -18,28 +18,28 @@ x-i18n:
|
||||
**状态**:已完成
|
||||
**PR**:#216
|
||||
|
||||
## 概要
|
||||
## 摘要
|
||||
|
||||
Telegram 允许列表现在以不区分大小写的方式接受 `telegram:` 和 `tg:` 前缀,并容许意外的空白字符。这使得入站允许列表检查与出站发送的规范化保持一致。
|
||||
Telegram 允许列表现在不区分大小写地接受 `telegram:` 和 `tg:` 前缀,并容忍意外的空白。这使入站允许列表检查与出站发送规范化保持一致。
|
||||
|
||||
## 变更内容
|
||||
## 更改内容
|
||||
|
||||
- 前缀 `telegram:` 和 `tg:` 被视为相同(不区分大小写)。
|
||||
- 允许列表条目会被修剪空白;空条目将被忽略。
|
||||
- 前缀 `telegram:` 和 `tg:` 被同等对待(不区分大小写)。
|
||||
- 允许列表条目会被修剪;空条目会被忽略。
|
||||
|
||||
## 示例
|
||||
|
||||
以下所有格式均被接受为同一 ID:
|
||||
以下所有形式都被接受为同一 ID:
|
||||
|
||||
- `telegram:123456`
|
||||
- `TG:123456`
|
||||
- `tg:123456`
|
||||
|
||||
## 重要性
|
||||
## 为什么重要
|
||||
|
||||
从日志或聊天 ID 中复制粘贴时经常会包含前缀和空白字符。规范化处理可以避免在决定是否响应私聊或群组消息时出现误判。
|
||||
从日志或聊天 ID 复制/粘贴通常会包含前缀和空白。规范化可避免在决定是否在私信或群组中响应时出现误判。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [群组聊天](/concepts/groups)
|
||||
- [Telegram 渠道](/channels/telegram)
|
||||
- [群聊](/concepts/groups)
|
||||
- [Telegram 提供商](/channels/telegram)
|
||||
|
||||
@@ -1,105 +1,105 @@
|
||||
---
|
||||
last_updated: "2026-01-19"
|
||||
owner: openclaw
|
||||
status: 草稿
|
||||
summary: 计划:添加 OpenResponses /v1/responses 端点并平稳废弃 Chat Completions
|
||||
title: OpenResponses Gateway网关计划
|
||||
status: draft
|
||||
summary: 计划:添加 OpenResponses /v1/responses 端点并干净地弃用 chat completions
|
||||
title: OpenResponses Gateway 网关计划
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:25:20Z"
|
||||
generated_at: "2026-02-03T07:47:33Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 71a22c48397507d1648b40766a3153e420c54f2a2d5186d07e51eb3d12e4636a
|
||||
source_path: experiments/plans/openresponses-gateway.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenResponses Gateway网关集成计划
|
||||
# OpenResponses Gateway 网关集成计划
|
||||
|
||||
## 背景
|
||||
|
||||
OpenClaw Gateway网关当前在 `/v1/chat/completions` 暴露了一个最小化的 OpenAI 兼容 Chat Completions 端点(参见 [OpenAI Chat Completions](/gateway/openai-http-api))。
|
||||
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`。
|
||||
Open Responses 是基于 OpenAI Responses API 的开放推理标准。它专为智能体工作流设计,使用基于项目的输入加语义流式事件。OpenResponses 规范定义的是 `/v1/responses`,而不是 `/v1/chat/completions`。
|
||||
|
||||
## 目标
|
||||
|
||||
- 添加一个遵循 OpenResponses 语义的 `/v1/responses` 端点。
|
||||
- 将 Chat Completions 保留为兼容层,便于禁用并最终移除。
|
||||
- 保留 Chat Completions 作为兼容层,易于禁用并最终移除。
|
||||
- 使用隔离的、可复用的 schema 标准化验证和解析。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 第一阶段不追求完整的 OpenResponses 功能对等(图片、文件、托管工具)。
|
||||
- 不替换内部智能体执行逻辑或工具编排。
|
||||
- 第一阶段不改变现有 `/v1/chat/completions` 的行为。
|
||||
- 第一阶段完全实现 OpenResponses 功能(图片、文件、托管工具)。
|
||||
- 替换内部智能体执行逻辑或工具编排。
|
||||
- 在第一阶段更改现有的 `/v1/chat/completions` 行为。
|
||||
|
||||
## 研究摘要
|
||||
|
||||
来源:OpenResponses OpenAPI、OpenResponses 规范站点和 Hugging Face 博客文章。
|
||||
来源: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` 项
|
||||
- `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` 项。
|
||||
- 流式传输使用语义化事件,例如:
|
||||
- 成功响应返回带有 `object: "response"`、`status` 和 `output` 项的 `ResponseResource`。
|
||||
- 流式传输使用语义事件,如:
|
||||
- `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` 字段匹配
|
||||
- `event:` 必须匹配 JSON `type` 字段
|
||||
- 终止事件必须是字面量 `[DONE]`
|
||||
- 推理项可以暴露 `content`、`encrypted_content` 和 `summary`。
|
||||
- Reasoning 项可能暴露 `content`、`encrypted_content` 和 `summary`。
|
||||
- HF 示例在请求中包含 `OpenResponses-Version: latest`(可选头部)。
|
||||
|
||||
## 建议架构
|
||||
## 提议的架构
|
||||
|
||||
- 添加 `src/gateway/open-responses.schema.ts`,仅包含 Zod schema(不引入 Gateway网关依赖)。
|
||||
- 添加 `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` 不变,作为旧版兼容适配器。
|
||||
- 保持 `src/gateway/openai-http.ts` 不变,作为遗留兼容适配器。
|
||||
- 添加配置 `gateway.http.endpoints.responses.enabled`(默认 `false`)。
|
||||
- 保持 `gateway.http.endpoints.chatCompletions.enabled` 独立;允许两个端点分别切换。
|
||||
- 当 Chat Completions 启用时,在启动时发出警告以提示其旧版状态。
|
||||
- 当 Chat Completions 启用时发出启动警告,以表明其遗留状态。
|
||||
|
||||
## Chat Completions 废弃路径
|
||||
## Chat Completions 弃用路径
|
||||
|
||||
- 维护严格的模块边界:Responses 和 Chat Completions 之间不共享 schema 类型。
|
||||
- 通过配置使 Chat Completions 变为可选启用,这样无需修改代码即可禁用。
|
||||
- 待 `/v1/responses` 稳定后,更新文档将 Chat Completions 标记为旧版。
|
||||
- 可选的未来步骤:将 Chat Completions 请求映射到 Responses 处理器,以简化移除路径。
|
||||
- 保持严格的模块边界:responses 和 chat completions 之间不共享 schema 类型。
|
||||
- 通过配置使 Chat Completions 成为可选,这样无需代码更改即可禁用。
|
||||
- 一旦 `/v1/responses` 稳定,更新文档将 Chat Completions 标记为遗留。
|
||||
- 可选的未来步骤:将 Chat Completions 请求映射到 Responses 处理器,以便更简单地移除。
|
||||
|
||||
## 第一阶段支持子集
|
||||
|
||||
- 接受 `input` 为字符串或包含消息角色和 `function_call_output` 的 `ItemParam[]`。
|
||||
- 接受 `input` 为字符串或带有消息角色和 `function_call_output` 的 `ItemParam[]`。
|
||||
- 将 system 和 developer 消息提取到 `extraSystemPrompt` 中。
|
||||
- 使用最近的 `user` 或 `function_call_output` 作为智能体运行的当前消息。
|
||||
- 对不支持的内容部分(图片/文件)返回 `invalid_request_error` 拒绝。
|
||||
- 返回包含 `output_text` 内容的单条助手消息。
|
||||
- 返回 `usage`,在接入令牌计量之前使用零值。
|
||||
- 返回带有 `output_text` 内容的单个助手消息。
|
||||
- 返回带有零值的 `usage`,直到 token 计数接入。
|
||||
|
||||
## 验证策略(无 SDK)
|
||||
|
||||
- 为以下支持的子集实现 Zod schema:
|
||||
- 为以下支持子集实现 Zod schema:
|
||||
- `CreateResponseBody`
|
||||
- `ItemParam` + 消息内容部分联合类型
|
||||
- `ItemParam` + 消息内容部分联合
|
||||
- `ResponseResource`
|
||||
- Gateway网关使用的流式事件结构
|
||||
- 将 schema 保存在单个隔离模块中,以避免漂移并支持未来的代码生成。
|
||||
- Gateway 网关使用的流式事件形状
|
||||
- 将 schema 保存在单个隔离模块中,以避免漂移并允许未来代码生成。
|
||||
|
||||
## 流式实现(第一阶段)
|
||||
|
||||
- SSE 行同时包含 `event:` 和 `data:`。
|
||||
- 必需的序列(最小可行方案):
|
||||
- 带有 `event:` 和 `data:` 的 SSE 行。
|
||||
- 所需序列(最小可行):
|
||||
- `response.created`
|
||||
- `response.output_item.added`
|
||||
- `response.content_part.added`
|
||||
- `response.output_text.delta`(按需重复)
|
||||
- `response.output_text.delta`(根据需要重复)
|
||||
- `response.output_text.done`
|
||||
- `response.content_part.done`
|
||||
- `response.completed`
|
||||
@@ -107,15 +107,15 @@ Open Responses 是一个基于 OpenAI Responses API 的开放推理标准。它
|
||||
|
||||
## 测试和验证计划
|
||||
|
||||
- 为 `/v1/responses` 添加端到端测试覆盖:
|
||||
- 为 `/v1/responses` 添加端到端覆盖:
|
||||
- 需要认证
|
||||
- 非流式响应结构
|
||||
- 非流式响应形状
|
||||
- 流式事件顺序和 `[DONE]`
|
||||
- 使用头部和 `user` 的会话路由
|
||||
- 保持 `src/gateway/openai-http.e2e.test.ts` 不变。
|
||||
- 手动测试:使用 curl 请求 `/v1/responses`,设置 `stream: true`,验证事件顺序和终止 `[DONE]`。
|
||||
- 手动:用 `stream: true` curl `/v1/responses` 并验证事件顺序和终止 `[DONE]`。
|
||||
|
||||
## 文档更新(后续)
|
||||
|
||||
- 为 `/v1/responses` 的用法和示例添加新的文档页面。
|
||||
- 在 `/gateway/openai-http-api` 中添加旧版说明并指向 `/v1/responses`。
|
||||
- 为 `/v1/responses` 使用和示例添加新文档页面。
|
||||
- 更新 `/gateway/openai-http-api`,添加遗留说明和指向 `/v1/responses` 的指针。
|
||||
|
||||
Reference in New Issue
Block a user