From a6f7495a9cfe65cf8e7b2cdc274b826e587dd36f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 3 May 2026 22:56:40 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/memory-wiki.md | 193 +++++++++++++++--------------- docs/zh-CN/tools/llm-task.md | 53 ++++---- docs/zh-CN/tools/lobster.md | 166 ++++++++++++------------- 3 files changed, 206 insertions(+), 206 deletions(-) diff --git a/docs/zh-CN/plugins/memory-wiki.md b/docs/zh-CN/plugins/memory-wiki.md index 628c90f9e..3db691265 100644 --- a/docs/zh-CN/plugins/memory-wiki.md +++ b/docs/zh-CN/plugins/memory-wiki.md @@ -3,68 +3,68 @@ read_when: - 你想要超出普通 MEMORY.md 笔记的持久知识 - 你正在配置内置的 memory-wiki 插件 - 你想了解 wiki_search、wiki_get 或桥接模式 -summary: memory-wiki：带有来源、声明、仪表板和桥接模式的已编译知识库 -title: Memory Wiki +summary: 'memory-wiki: 带有来源信息、声明、仪表板和桥接模式的编译知识库' +title: 记忆 wiki x-i18n: - generated_at: "2026-04-29T19:21:18Z" + generated_at: "2026-05-03T22:55:52Z" model: gpt-5.5 provider: openai - source_hash: 744d569f8b0c9b668ea54dc057f808544359eaae87d5557de2e6acd1b31acd89 + source_hash: b070177b7c1217e9102bc57680b4009265e3584ede7ad6dc3ba7b6393260fefe source_path: plugins/memory-wiki.md workflow: 16 --- -`memory-wiki` 是一个内置插件，可将持久化记忆转换为编译后的知识库。 +`memory-wiki` 是一个内置插件，会将持久记忆转换为编译后的知识库。 -它**不会**取代活跃记忆插件。活跃记忆插件仍然负责召回、提升、索引和 Dreaming。`memory-wiki` 与它并行工作，并将持久化知识编译成可导航的 wiki，其中包含确定性页面、结构化声明、来源、仪表盘和机器可读摘要。 +它**不会**取代主动记忆插件。主动记忆插件仍然负责召回、提升、索引和 Dreaming。`memory-wiki` 与它并列工作，并将持久知识编译成可导航的 wiki，其中包含确定性页面、结构化声明、来源依据、仪表板和机器可读摘要。 -当你希望记忆更像一个维护良好的知识层，而不是一堆 Markdown 文件时，可以使用它。 +当你希望记忆更像一个维护良好的知识层，而不是一堆 Markdown 文件时，请使用它。 -## 它增加了什么 +## 它添加了什么 - 一个带有确定性页面布局的专用 wiki 库 -- 结构化的声明和证据元数据，而不仅仅是散文 -- 页面级来源、置信度、矛盾和开放问题 +- 结构化声明和证据元数据，而不仅是 prose +- 页面级来源依据、置信度、矛盾和开放问题 - 面向智能体/运行时消费者的编译摘要 -- wiki 原生搜索/获取/应用/lint 工具 -- 可选桥接模式，用于从活跃记忆插件导入公共工件 -- 可选 Obsidian 友好的渲染模式和 CLI 集成 +- wiki 原生的 search/get/apply/lint 工具 +- 可选桥接模式，用于从主动记忆插件导入公共产物 +- 可选的 Obsidian 友好渲染模式和 CLI 集成 -## 它如何与记忆配合 +## 它如何配合记忆 可以这样理解这种分层： -| 层 | 拥有 | +| 层 | 负责 | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| 活跃记忆插件（`memory-core`、QMD、Honcho 等） | 召回、语义搜索、提升、Dreaming、记忆运行时 | -| `memory-wiki` | 编译后的 wiki 页面、来源丰富的综合内容、仪表盘、wiki 专用搜索/获取/应用 | +| 主动记忆插件（`memory-core`、QMD、Honcho 等） | 召回、语义搜索、提升、Dreaming、记忆运行时 | +| `memory-wiki` | 编译后的 wiki 页面、富含来源依据的综合内容、仪表板、wiki 专用 search/get/apply | -如果活跃记忆插件公开共享召回工件，OpenClaw 可以用 `memory_search corpus=all` 一次性搜索这两层。 +如果主动记忆插件暴露共享召回产物，OpenClaw 可以用 `memory_search corpus=all` 在一次处理中搜索两个层。 -当你需要 wiki 专用排序、来源或直接页面访问时，请改用 wiki 原生工具。 +当你需要 wiki 专用排序、来源依据或直接页面访问时，请改用 wiki 原生工具。 ## 推荐的混合模式 -对于本地优先设置，一个可靠的默认选择是： +对于本地优先设置，一个强默认方案是： -- 使用 QMD 作为活跃记忆后端，用于召回和广泛语义搜索 -- 使用处于 `bridge` 模式的 `memory-wiki`，用于持久化综合知识页面 +- 使用 QMD 作为主动记忆后端，用于召回和广泛语义搜索 +- 使用 `bridge` 模式的 `memory-wiki`，用于持久的综合知识页面 这种分层效果很好，因为每一层都保持专注： -- QMD 让原始笔记、会话导出和额外集合保持可搜索 -- `memory-wiki` 编译稳定实体、声明、仪表盘和来源页面 +- QMD 让原始笔记、会话导出和额外集合可搜索 +- `memory-wiki` 编译稳定实体、声明、仪表板和来源页面 实用规则： - 当你想对记忆进行一次广泛召回时，使用 `memory_search` -- 当你想要具有来源感知能力的 wiki 结果时，使用 `wiki_search` 和 `wiki_get` -- 当你希望共享搜索跨越两层时，使用 `memory_search corpus=all` +- 当你想要具有来源依据感知能力的 wiki 结果时，使用 `wiki_search` 和 `wiki_get` +- 当你想让共享搜索跨越两层时，使用 `memory_search corpus=all` -如果桥接模式报告导出工件为零，说明活跃记忆插件当前尚未公开公共桥接输入。先运行 `openclaw wiki doctor`，然后确认活跃记忆插件支持公共工件。 +如果桥接模式报告导出的产物为零，说明主动记忆插件当前尚未暴露公共桥接输入。先运行 `openclaw wiki doctor`，然后确认主动记忆插件支持公共产物。 当桥接模式处于活动状态且启用了 `bridge.readMemoryArtifacts` 时，`openclaw wiki status`、`openclaw wiki doctor` 和 `openclaw wiki bridge -import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检查与运行时记忆插件上下文保持一致。如果桥接被禁用或工件读取被关闭，这些命令会保留本地/离线行为。 +import` 会通过正在运行的 Gateway 网关读取。这样可让 CLI 桥接检查与运行时记忆插件上下文保持一致。如果桥接被禁用或产物读取被关闭，这些命令会保持本地/离线行为。 ## 库模式 @@ -72,19 +72,19 @@ import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检 ### `isolated` -自己的库、自己的来源，不依赖 `memory-core`。 +拥有自己的库、自己的来源，不依赖 `memory-core`。 -当你希望 wiki 成为自己的精选知识存储时使用此模式。 +当你希望 wiki 成为独立策划的知识存储时使用此模式。 ### `bridge` -通过公共插件 SDK 边界，从活跃记忆插件读取公共记忆工件和记忆事件。 +通过公共插件 SDK 接缝，从主动记忆插件读取公共记忆产物和记忆事件。 -当你希望 wiki 编译和组织记忆插件导出的工件，而不访问私有插件内部实现时使用此模式。 +当你希望 wiki 编译和整理记忆插件导出的产物，而不进入私有插件内部机制时使用此模式。 桥接模式可以索引： -- 导出的记忆工件 +- 导出的记忆产物 - Dream 报告 - 每日笔记 - 记忆根文件 @@ -92,9 +92,9 @@ import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检 ### `unsafe-local` -显式的同机逃生口，用于本地私有路径。 +针对本机私有路径的显式同机逃生口。 -此模式有意设计为实验性且不可移植。仅当你理解信任边界，并且确实需要桥接模式无法提供的本地文件系统访问时才使用它。 +此模式有意保持实验性且不可移植。仅当你理解信任边界，并且明确需要桥接模式无法提供的本地文件系统访问时，才使用它。 ## 库布局 @@ -118,19 +118,19 @@ import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检 托管内容保留在生成块内。人工笔记块会被保留。 -主要页面分组包括： +主要页面组包括： - `sources/` 用于导入的原始材料和桥接支持的页面 -- `entities/` 用于持久化事物、人物、系统、项目和对象 +- `entities/` 用于持久事物、人物、系统、项目和对象 - `concepts/` 用于想法、抽象、模式和策略 -- `syntheses/` 用于编译后的摘要和维护型汇总 -- `reports/` 用于生成的仪表盘 +- `syntheses/` 用于编译摘要和维护型汇总 +- `reports/` 用于生成的仪表板 ## 结构化声明和证据 -页面可以携带结构化的 `claims` frontmatter，而不仅仅是自由形式文本。 +页面可以携带结构化的 `claims` frontmatter，而不仅是自由格式文本。 -每个声明可以包括： +每条声明可以包括： - `id` - `text` @@ -151,7 +151,7 @@ import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检 - `note` - `updatedAt` -这让 wiki 更像一个信念层，而不是被动的笔记堆。声明可以被跟踪、评分、质疑，并回溯到来源来解决。 +这使 wiki 更像一个信念层，而不是被动的笔记转储。声明可以被跟踪、评分、争议化，并追溯回来源。 ## 面向智能体的实体元数据 @@ -165,10 +165,10 @@ import` 会通过正在运行的 Gateway 网关读取。这会让 CLI 桥接检 - `privacyTier`：`public`、`local-private`、`sensitive` 或 `confirm-before-use` - `bestUsedFor` / `notEnoughFor`：紧凑的路由提示 - `lastRefreshedAt`：独立于页面编辑时间的来源刷新时间戳 -- `personCard`：可选的人物专用路由卡片，包含用户名、社交账号、邮箱、时区、路线、适合询问、不适合询问、置信度和隐私 -- `relationships`：指向相关页面的类型化边，包含目标、类型、权重、置信度、证据类型、隐私层级和备注 +- `personCard`：可选的人物专用路由卡，包含用户名、社交账号、邮箱、时区、通道、适合询问事项、避免询问事项、置信度和隐私 +- `relationships`：指向相关页面的类型化边，包含目标、类型、权重、置信度、证据类型、隐私级别和备注 -对于人物 wiki，智能体通常应从 `reports/person-agent-directory.md` 开始，然后在使用联系方式或推断事实之前，用 `wiki_get` 打开人物页面。 +对于人物 wiki，智能体通常应先从 `reports/person-agent-directory.md` 开始，然后在使用联系方式或推断事实前，用 `wiki_get` 打开人物页面。 示例： @@ -220,23 +220,23 @@ claims: ## 编译流水线 -编译步骤会读取 wiki 页面、规范化摘要，并在以下位置输出稳定的面向机器的工件： +编译步骤会读取 wiki 页面、规范化摘要，并在以下位置输出稳定的机器面向产物： - `.openclaw-wiki/cache/agent-digest.json` - `.openclaw-wiki/cache/claims.jsonl` -这些摘要存在的目的，是让智能体和运行时代码不必抓取 Markdown 页面。 +这些摘要的存在，是为了让智能体和运行时代码不必抓取 Markdown 页面。 编译输出还支持： -- 搜索/获取流程的首轮 wiki 索引 +- search/get 流程的首轮 wiki 索引 - 声明 ID 回查到所属页面 - 紧凑的提示词补充 -- 报告/仪表盘生成 +- 报告/仪表板生成 -## 仪表盘和健康报告 +## 仪表板和健康报告 -启用 `render.createDashboards` 后，编译会维护 `reports/` 下的仪表盘。 +启用 `render.createDashboards` 后，编译会在 `reports/` 下维护仪表板。 内置报告包括： @@ -252,16 +252,16 @@ claims: 这些报告会跟踪如下内容： -- 矛盾备注集群 -- 竞争声明集群 +- 矛盾备注簇 +- 竞争声明簇 - 缺少结构化证据的声明 - 低置信度页面和声明 - 过期或未知新鲜度 - 带有未解决问题的页面 -- 人物/实体路由卡片 +- 人物/实体路由卡 - 结构化关系边 - 证据类别覆盖率 -- 使用前需要审查的非公开隐私层级 +- 使用前需要审查的非公共隐私级别 ## 搜索和检索 @@ -278,26 +278,26 @@ claims: 重要行为： -- `wiki_search` 和 `wiki_get` 会在可能时使用编译摘要作为首轮结果 +- `wiki_search` 和 `wiki_get` 会在可能时使用编译摘要作为第一轮处理 - 声明 ID 可以解析回所属页面 - 有争议/过期/新鲜的声明会影响排序 -- 来源标签可以保留到结果中 -- 搜索模式可以为人物查找、问题路由、来源证据或原始声明偏置排序 +- 来源依据标签可以保留到结果中 +- 搜索模式可以让排序偏向人物查找、问题路由、来源证据或原始声明 实用规则： - 使用 `memory_search corpus=all` 进行一次广泛召回 -- 当你关心 wiki 专用排序、来源或页面级信念结构时，使用 `wiki_search` + `wiki_get` +- 当你关心 wiki 专用排序、来源依据或页面级信念结构时，使用 `wiki_search` + `wiki_get` 搜索模式： -- `auto`：平衡的默认模式 +- `auto`：平衡默认值 - `find-person`：提升类似人物的实体、别名、用户名、社交账号和规范 ID -- `route-question`：提升智能体卡片、适合询问提示、最适用提示和关系上下文 +- `route-question`：提升智能体卡片、适合询问提示、最适合用途提示和关系上下文 - `source-evidence`：提升来源页面和结构化证据元数据 - `raw-claim`：提升匹配的结构化声明，并在结果中返回声明/证据元数据 -当结果匹配结构化声明时，`wiki_search` 可以在其详情载荷中返回 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 和 `evidenceSourceIds`。可用时，文本输出还会包含紧凑的 `Claim:` 和 `Evidence:` 行。 +当结果匹配结构化声明时，`wiki_search` 可以在其 details payload 中返回 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 和 `evidenceSourceIds`。可用时，文本输出也会包含紧凑的 `Claim:` 和 `Evidence:` 行。 ## 智能体工具 @@ -312,26 +312,26 @@ claims: 它们的作用： - `wiki_status`：当前库模式、健康状态、Obsidian CLI 可用性 -- `wiki_search`：搜索 wiki 页面，以及在配置后搜索共享记忆语料库；接受 `mode`，用于人物查找、问题路由、来源证据或原始声明深挖 +- `wiki_search`：搜索 wiki 页面，并在配置后搜索共享记忆语料库；接受用于人物查找、问题路由、来源证据或原始声明钻取的 `mode` - `wiki_get`：按 ID/路径读取 wiki 页面，或回退到共享记忆语料库 -- `wiki_apply`：进行窄范围综合/元数据变更，而不是自由形式页面手术 -- `wiki_lint`：结构检查、来源缺口、矛盾、开放问题 +- `wiki_apply`：进行窄范围综合/元数据变更，而不是自由格式页面手术 +- `wiki_lint`：结构检查、来源依据缺口、矛盾、开放问题 -该插件还会注册非独占的记忆语料库补充，因此当活跃记忆插件支持语料库选择时，共享的 `memory_search` 和 `memory_get` 可以访问 wiki。 +该插件还会注册一个非独占的记忆语料库补充，因此当主动记忆插件支持语料库选择时，共享的 `memory_search` 和 `memory_get` 可以触达 wiki。 ## 提示词和上下文行为 -启用 `context.includeCompiledDigestPrompt` 后，记忆提示词部分会附加来自 `agent-digest.json` 的紧凑编译快照。 +启用 `context.includeCompiledDigestPrompt` 后，记忆提示词区段会附加来自 `agent-digest.json` 的紧凑编译快照。 该快照有意保持小而高信号： -- 仅包含顶级页面 -- 仅包含顶级声明 +- 仅包含顶层页面 +- 仅包含顶层声明 - 矛盾数量 - 问题数量 -- 置信度/新鲜度限定信息 +- 置信度/新鲜度限定词 -这是可选功能，因为它会改变提示词形态，并且主要适用于显式消费记忆补充的上下文引擎或旧版提示词组装。 +这是可选项，因为它会改变提示词形状，并且主要适用于明确消费记忆补充的上下文引擎或旧版提示词组装。 ## 配置 @@ -389,24 +389,27 @@ claims: 关键开关： -- `vaultMode`: `isolated`、`bridge`、`unsafe-local` -- `vault.renderMode`: `native` 或 `obsidian` -- `bridge.readMemoryArtifacts`: 导入活跃 memory 插件的公共工件 -- `bridge.followMemoryEvents`: 在 bridge 模式中包含事件日志 -- `search.backend`: `shared` 或 `local` -- `search.corpus`: `wiki`、`memory` 或 `all` -- `context.includeCompiledDigestPrompt`: 将紧凑摘要快照追加到 memory 提示词分区 -- `render.createBacklinks`: 生成确定性的相关区块 -- `render.createDashboards`: 生成仪表板页面 +- `vaultMode`：`isolated`、`bridge`、`unsafe-local` +- `vault.renderMode`：`native` 或 `obsidian` +- `bridge.readMemoryArtifacts`：导入主动记忆插件的公开产物 +- `bridge.followMemoryEvents`：在桥接模式中包含事件日志 +- `search.backend`：`shared` 或 `local` +- `search.corpus`：`wiki`、`memory` 或 `all` +- `context.includeCompiledDigestPrompt`：将紧凑摘要快照追加到记忆提示词部分 +- `render.createBacklinks`：生成确定性的相关块 +- `render.createDashboards`：生成仪表盘页面 -### 示例：QMD + bridge 模式 +### 示例：QMD + 桥接模式 -当你想用 QMD 进行召回，并用 `memory-wiki` 维护知识层时，请使用此配置： +当你想将 QMD 用于回忆，并将 `memory-wiki` 用作维护型知识层时使用此配置： ```json5 { memory: { backend: "qmd", + }, + plugins: { + entries: { "memory-wiki": { enabled: true, config: { @@ -435,13 +438,13 @@ claims: 这会保持： -- QMD 负责活跃 memory 召回 -- `memory-wiki` 专注于编译页面和仪表板 -- 在你有意启用编译摘要提示词之前，提示词形态保持不变 +- QMD 负责主动记忆回忆 +- `memory-wiki` 专注于编译后的页面和仪表盘 +- 提示词形态保持不变，直到你有意启用编译摘要提示词 ## CLI -`memory-wiki` 还暴露一个顶层 CLI 界面： +`memory-wiki` 还公开了一个顶层 CLI 界面： ```bash openclaw wiki status @@ -465,27 +468,27 @@ openclaw wiki obsidian status 支持的工作流包括： -- Status 探测 +- 状态探测 - vault 搜索 - 打开页面 - 调用 Obsidian 命令 -- 跳转到日记 +- 跳转到每日笔记 这是可选的。即使没有 Obsidian，wiki 仍可在原生模式下工作。 ## 推荐工作流 -1. 保留你的活跃 memory 插件，用于召回、提升和 Dreaming。 +1. 保留你的主动记忆插件，用于回忆、提升和 Dreaming。 2. 启用 `memory-wiki`。 -3. 除非你明确需要 bridge 模式，否则从 `isolated` 模式开始。 -4. 当来源出处很重要时，使用 `wiki_search` / `wiki_get`。 -5. 使用 `wiki_apply` 进行范围较窄的综合整理或元数据更新。 -6. 在有意义的更改后运行 `wiki_lint`。 -7. 如果你想查看陈旧内容或矛盾内容，请开启仪表板。 +3. 除非你明确想要桥接模式，否则从 `isolated` 模式开始。 +4. 当来源依据很重要时，使用 `wiki_search` / `wiki_get`。 +5. 使用 `wiki_apply` 进行小范围综合或元数据更新。 +6. 在有意义的变更后运行 `wiki_lint`。 +7. 如果你想查看过期内容或矛盾内容，请开启仪表盘。 ## 相关文档 -- [Memory 概览](/zh-CN/concepts/memory) +- [记忆概览](/zh-CN/concepts/memory) - [CLI：memory](/zh-CN/cli/memory) - [CLI：wiki](/zh-CN/cli/wiki) - [插件 SDK 概览](/zh-CN/plugins/sdk-overview) diff --git a/docs/zh-CN/tools/llm-task.md b/docs/zh-CN/tools/llm-task.md index 7850f2c2c..2e89238fd 100644 --- a/docs/zh-CN/tools/llm-task.md +++ b/docs/zh-CN/tools/llm-task.md @@ -1,21 +1,21 @@ --- read_when: - - 你想在工作流中加入一个纯 JSON 的 LLM 步骤 - - 你需要经过 schema 验证的 LLM 输出用于自动化 -summary: 用于工作流的纯 JSON LLM 任务（可选插件工具） + - 你想要在工作流中使用仅 JSON 的 LLM 步骤 + - 你需要用于自动化的、经过模式验证的大语言模型输出 +summary: 仅 JSON 的 LLM 任务，用于工作流（可选插件工具） title: LLM 任务 x-i18n: - generated_at: "2026-04-23T23:04:53Z" - model: gpt-5.4 + generated_at: "2026-05-03T22:55:44Z" + model: gpt-5.5 provider: openai - source_hash: 613aefd1bac5b9675821a118c11130c8bfaefb1673d0266f14ff4e91b47fed8b + source_hash: 9cdc5d4feef17fb6d6d90d819d4c92d26a4ec43e4f5364c6acbaad1934a89269 source_path: tools/llm-task.md - workflow: 15 + workflow: 16 --- -`llm-task` 是一个**可选插件工具**，用于运行纯 JSON 的 LLM 任务，并返回结构化输出（可选地根据 JSON Schema 进行验证）。 +`llm-task` 是一个**可选插件工具**，用于运行仅 JSON 的 LLM 任务，并返回结构化输出（可选根据 JSON Schema 验证）。 -这非常适合 Lobster 之类的工作流引擎：你可以添加一个单独的 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。 +这非常适合 Lobster 这样的工作流引擎：你可以添加单个 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。 ## 启用插件 @@ -31,21 +31,18 @@ x-i18n: } ``` -2. 将该工具加入 allowlist（它以 `optional: true` 注册）： +2. 允许可选工具： ```json { - "agents": { - "list": [ - { - "id": "main", - "tools": { "allow": ["llm-task"] } - } - ] + "tools": { + "alsoAllow": ["llm-task"] } } ``` +只有在你想使用限制性允许列表模式时，才使用 `tools.allow`。 + ## 配置（可选） ```json @@ -68,11 +65,11 @@ x-i18n: } ``` -`allowedModels` 是一个由 `provider/model` 字符串组成的 allowlist。如果设置了它，则任何不在列表中的请求都会被拒绝。 +`allowedModels` 是 `provider/model` 字符串的允许列表。如果已设置，列表之外的任何请求都会被拒绝。 ## 工具参数 -- `prompt`（字符串，必填） +- `prompt`（字符串，必需） - `input`（任意类型，可选） - `schema`（对象，可选 JSON Schema） - `provider`（字符串，可选） @@ -83,11 +80,11 @@ x-i18n: - `maxTokens`（数字，可选） - `timeoutMs`（数字，可选） -`thinking` 接受标准的 OpenClaw 推理预设，例如 `low` 或 `medium`。 +`thinking` 接受标准 OpenClaw 推理预设，例如 `low` 或 `medium`。 ## 输出 -返回包含解析后 JSON 的 `details.json`（提供 `schema` 时会据此验证）。 +返回包含已解析 JSON 的 `details.json`（并在提供 `schema` 时根据它进行验证）。 ## 示例：Lobster 工作流步骤 @@ -111,15 +108,15 @@ openclaw.invoke --tool llm-task --action json --args-json '{ }' ``` -## 安全说明 +## 安全注意事项 -- 该工具是**纯 JSON** 的，并会指示模型仅输出 JSON（无代码围栏、无评论）。 -- 本次运行不会向模型暴露任何工具。 -- 除非你使用 `schema` 进行验证，否则应将输出视为不受信任。 -- 在任何有副作用的步骤（发送、发布、exec）之前放置审批。 +- 该工具**仅输出 JSON**，并指示模型只输出 JSON（不输出代码围栏，不输出评论）。 +- 此次运行不会向模型暴露任何工具。 +- 除非你使用 `schema` 进行验证，否则应将输出视为不可信。 +- 在任何有副作用的步骤（发送、发布、执行）之前加入审批。 -## 相关 +## 相关内容 -- [Thinking 级别](/zh-CN/tools/thinking) +- [思考级别](/zh-CN/tools/thinking) - [子智能体](/zh-CN/tools/subagents) - [斜杠命令](/zh-CN/tools/slash-commands) diff --git a/docs/zh-CN/tools/lobster.md b/docs/zh-CN/tools/lobster.md index 8d98a0c70..5d3028238 100644 --- a/docs/zh-CN/tools/lobster.md +++ b/docs/zh-CN/tools/lobster.md @@ -1,52 +1,52 @@ --- read_when: - - 你希望使用具有显式批准机制的确定性多步骤工作流 - - 你需要在不重新运行前面步骤的情况下恢复工作流 -summary: 带可恢复批准关卡的 OpenClaw 类型化工作流运行时。 -title: Lobster + - 你需要带有明确审批的确定性多步骤工作流 + - 你需要在不重新运行先前步骤的情况下恢复工作流 +summary: OpenClaw 的类型化工作流运行时，带可恢复的审批门禁。 +title: 龙虾 x-i18n: - generated_at: "2026-04-27T06:07:17Z" - model: gpt-5.4 + generated_at: "2026-05-03T22:55:42Z" + model: gpt-5.5 provider: openai - source_hash: 1700bcfdbcf4558cb908935834e9059221d0d26ad78ed6f9e2158f7e0b83edbd + source_hash: e1a81fddd11fa36f4ce3b3f0bce35f5a7e90300e225027331965bdfdc8919532 source_path: tools/lobster.md - workflow: 15 + workflow: 16 --- -Lobster 是一个工作流 shell，让 OpenClaw 能够把多步骤工具序列作为一次单一、确定性的操作来运行，并带有显式批准检查点。 +Lobster 是一个工作流 shell，可让 OpenClaw 将多步工具序列作为单个确定性操作运行，并带有明确的批准检查点。 -Lobster 位于分离式后台工作之上的一个编写层。若要了解单个任务之上的流程编排，请参见 [Task Flow](/zh-CN/automation/taskflow)（`openclaw tasks flow`）。若要查看任务活动账本，请参见 [`openclaw tasks`](/zh-CN/automation/tasks)。 +Lobster 是位于分离式后台工作之上的一个创作层。若要了解高于单个任务的流程编排，请参阅[任务流](/zh-CN/automation/taskflow)（`openclaw tasks flow`）。若要了解任务活动账本，请参阅 [`openclaw tasks`](/zh-CN/automation/tasks)。 -## 引子 +## 钩子 -你的助手可以构建管理它自己的工具。只要提出一个工作流请求，30 分钟后你就能得到一个 CLI 和一组可通过一次调用运行的流水线。Lobster 就是缺失的那一块：确定性流水线、显式批准，以及可恢复状态。 +你的助手可以构建用于管理自身的工具。提出一个工作流需求，30 分钟后你就会得到一个 CLI 加上能作为一次调用运行的管道。Lobster 就是缺失的那一环：确定性管道、明确批准，以及可恢复状态。 -## 为什么要用它 +## 为什么 -如今，复杂工作流需要来回进行许多工具调用。每次调用都会消耗 token，而且 LLM 必须编排每一个步骤。Lobster 把这种编排移入一个类型化运行时： +如今，复杂工作流需要大量来回工具调用。每次调用都会消耗 token，并且 LLM 必须编排每一步。Lobster 将这种编排移入一个类型化运行时： -- **一次调用代替多次调用**：OpenClaw 运行一次 Lobster 工具调用，并获得结构化结果。 -- **内置批准**：带副作用的操作（发送邮件、发布评论）会暂停工作流，直到被显式批准。 -- **可恢复**：暂停的工作流会返回一个令牌；批准后可恢复，而无需重新运行所有内容。 +- **一次调用替代多次调用**：OpenClaw 运行一次 Lobster 工具调用并获得结构化结果。 +- **内置批准**：副作用（发送电子邮件、发表评论）会暂停工作流，直到获得明确批准。 +- **可恢复**：暂停的工作流会返回一个 token；批准后即可恢复，无需重新运行所有内容。 -## 为什么使用 DSL，而不是普通程序？ +## 为什么使用 DSL 而不是普通程序？ -Lobster 是有意保持精简的。目标不是“发明一种新语言”，而是提供一个可预测、对 AI 友好的流水线规范，并拥有一等的批准与恢复令牌能力。 +Lobster 有意保持小巧。目标不是“一个新语言”，而是一个可预测、AI 友好的管道规格，并以批准和恢复 token 作为一等能力。 -- **内置批准/恢复**：普通程序可以提示人类，但如果没有你自己实现那套运行时，它无法使用持久令牌来_暂停并恢复_。 -- **确定性 + 可审计性**：流水线是数据，因此易于记录、Diffs、重放和审查。 -- **面向 AI 的受限表面**：微小语法 + JSON 管道可以减少“创造性”代码路径，并使验证更现实。 -- **内建安全策略**：超时、输出上限、沙箱检查和允许列表由运行时统一强制执行，而不是由每个脚本自行处理。 +- **批准/恢复是内置的**：普通程序可以提示人工确认，但除非你自己发明这套运行时，否则它无法使用持久 token 来_暂停和恢复_。 +- **确定性 + 可审计性**：管道是数据，因此很容易记录、比较差异、重放和审查。 +- **面向 AI 的受限表面**：小型语法 + JSON 管道减少了“创意型”代码路径，并让验证变得现实。 +- **内置安全策略**：超时、输出上限、沙箱检查和允许列表由运行时强制执行，而不是由每个脚本各自处理。 - **仍然可编程**：每一步都可以调用任意 CLI 或脚本。如果你想使用 JS/TS，可以从代码生成 `.lobster` 文件。 ## 工作原理 -OpenClaw **在进程内**运行 Lobster 工作流，使用的是嵌入式运行器。不会启动外部 CLI 子进程；工作流引擎在 Gateway 网关进程内部执行，并直接返回一个 JSON 信封。 -如果流水线因等待批准而暂停，该工具会返回 `resumeToken`，以便你稍后继续。 +OpenClaw 使用嵌入式 runner **进程内**运行 Lobster 工作流。不会生成外部 CLI 子进程；工作流引擎在 Gateway 网关进程内执行，并直接返回 JSON 信封。 +如果管道因批准而暂停，该工具会返回 `resumeToken`，方便你之后继续。 ## 模式：小型 CLI + JSON 管道 + 批准 -构建一些会说 JSON 的小命令，然后把它们串联成一次 Lobster 调用。（下面的命令名只是示例——请替换成你自己的。） +构建会输出 JSON 的小命令，然后将它们串联成一次 Lobster 调用。（下面的示例命令名可替换为你自己的。） ```bash inbox list --json @@ -62,7 +62,7 @@ inbox apply --json } ``` -如果流水线请求批准，请使用该令牌恢复： +如果管道请求批准，请使用 token 恢复： ```json { @@ -72,7 +72,7 @@ inbox apply --json } ``` -AI 触发工作流；Lobster 执行步骤。批准关卡让副作用保持显式且可审计。 +AI 触发工作流；Lobster 执行步骤。批准门禁让副作用保持明确且可审计。 示例：将输入项映射为工具调用： @@ -84,10 +84,10 @@ gog.gmail.search --query 'newer_than:1d' \ ## 仅 JSON 的 LLM 步骤（llm-task） 对于需要**结构化 LLM 步骤**的工作流，请启用可选的 -`llm-task` 插件工具，并从 Lobster 中调用它。这样既能保持工作流 -的确定性，又能让你借助模型完成分类/总结/起草。 +`llm-task` 插件工具，并从 Lobster 调用它。这样既能保持工作流确定性， +又仍然可以用模型进行分类、总结或起草。 -启用该工具： +启用工具： ```json { @@ -107,7 +107,7 @@ gog.gmail.search --query 'newer_than:1d' \ } ``` -在流水线中使用它： +在管道中使用： ```lobster openclaw.invoke --tool llm-task --action json --args-json '{ @@ -126,11 +126,11 @@ openclaw.invoke --tool llm-task --action json --args-json '{ }' ``` -详情和配置选项请参见 [LLM Task](/zh-CN/tools/llm-task)。 +详情和配置选项请参阅 [LLM 任务](/zh-CN/tools/llm-task)。 ## 工作流文件（.lobster） -Lobster 可以运行带有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径即可。 +Lobster 可以运行带有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径。 ```yaml name: inbox-triage @@ -155,18 +155,18 @@ steps: 说明： -- `stdin: $step.stdout` 和 `stdin: $step.json` 用于传递前一步的输出。 -- `condition`（或 `when`）可根据 `$step.approved` 对步骤进行门控。 +- `stdin: $step.stdout` 和 `stdin: $step.json` 会传递先前步骤的输出。 +- `condition`（或 `when`）可以根据 `$step.approved` 为步骤设置门禁。 ## 安装 Lobster -内置的 Lobster 工作流在进程内运行；不需要单独的 `lobster` 二进制文件。嵌入式运行器会随 Lobster 插件一起提供。 +内置 Lobster 工作流以进程内方式运行；不需要单独的 `lobster` 二进制文件。嵌入式 runner 随 Lobster 插件一起提供。 -如果你在开发或外部流水线中需要独立的 Lobster CLI，请从 [Lobster 仓库](https://github.com/openclaw/lobster) 安装，并确保 `lobster` 位于 `PATH` 中。 +如果你需要用于开发或外部管道的独立 Lobster CLI，请从 [Lobster repo](https://github.com/openclaw/lobster) 安装，并确保 `lobster` 位于 `PATH` 中。 -## 启用该工具 +## 启用工具 -Lobster 是一个**可选**插件工具（默认不启用）。 +Lobster 是一个**可选**插件工具（默认未启用）。 推荐方式（增量、安全）： @@ -178,7 +178,7 @@ Lobster 是一个**可选**插件工具（默认不启用）。 } ``` -或者按智能体启用： +或按 agent 配置： ```json { @@ -195,25 +195,25 @@ Lobster 是一个**可选**插件工具（默认不启用）。 } ``` -除非你明确打算在严格允许列表模式下运行，否则不要使用 `tools.allow: ["lobster"]`。 +除非你打算以限制性允许列表模式运行，否则请避免使用 `tools.allow: ["lobster"]`。 -可选插件的允许列表采用选择启用机制。如果你的允许列表只列出插件工具（如 `lobster`），OpenClaw 仍会保留核心工具为启用状态。若要限制核心工具，也请将你需要的核心工具或工具组一并加入允许列表。 +允许列表对于可选插件是选择启用的。`alsoAllow` 只启用指定的可选插件工具，同时保留正常核心工具集。若要限制核心工具，请将 `tools.allow` 与你需要的核心工具或工具组一起使用。 -## 示例：电子邮件分流 +## 示例：电子邮件分诊 -不使用 Lobster： +没有 Lobster： ``` -用户：“检查我的邮件并起草回复” -→ openclaw 调用 gmail.list -→ LLM 总结 -→ 用户：“为 #2 和 #5 起草回复” -→ LLM 起草 -→ 用户：“发送 #2” -→ openclaw 调用 gmail.send -（每天重复，不记得哪些已经处理过） +User: "Check my email and draft replies" +→ openclaw calls gmail.list +→ LLM summarizes +→ User: "draft replies to #2 and #5" +→ LLM drafts +→ User: "send #2" +→ openclaw calls gmail.send +(repeat daily, no memory of what was triaged) ``` 使用 Lobster： @@ -252,13 +252,13 @@ Lobster 是一个**可选**插件工具（默认不启用）。 } ``` -一个工作流。确定。安全。 +一个工作流。确定性。安全。 ## 工具参数 ### `run` -以工具模式运行一个流水线。 +以工具模式运行管道。 ```json { @@ -270,7 +270,7 @@ Lobster 是一个**可选**插件工具（默认不启用）。 } ``` -带参数运行工作流文件： +使用参数运行工作流文件： ```json { @@ -282,7 +282,7 @@ Lobster 是一个**可选**插件工具（默认不启用）。 ### `resume` -在批准后继续已暂停的工作流。 +批准后继续暂停的工作流。 ```json { @@ -294,62 +294,62 @@ Lobster 是一个**可选**插件工具（默认不启用）。 ### 可选输入 -- `cwd`：流水线的相对工作目录（必须保持在 Gateway 网关工作目录内）。 -- `timeoutMs`：如果工作流超过该时长则中止（默认：20000）。 -- `maxStdoutBytes`：如果输出超过该大小则中止工作流（默认：512000）。 -- `argsJson`：传递给 `lobster run --args-json` 的 JSON 字符串（仅适用于工作流文件）。 +- `cwd`：管道的相对工作目录（必须保持在 Gateway 网关工作目录内）。 +- `timeoutMs`：如果工作流超过此时长则中止（默认：20000）。 +- `maxStdoutBytes`：如果输出超过此大小则中止（默认：512000）。 +- `argsJson`：传递给 `lobster run --args-json` 的 JSON 字符串（仅限工作流文件）。 ## 输出信封 -Lobster 会返回一个 JSON 信封，其状态为以下三种之一： +Lobster 返回带有三种状态之一的 JSON 信封： - `ok` → 成功完成 -- `needs_approval` → 已暂停；恢复时需要 `requiresApproval.resumeToken` -- `cancelled` → 被显式拒绝或取消 +- `needs_approval` → 已暂停；需要 `requiresApproval.resumeToken` 才能恢复 +- `cancelled` → 已明确拒绝或取消 -该工具会同时在 `content`（美化后的 JSON）和 `details`（原始对象）中暴露该信封。 +该工具会同时在 `content`（格式化 JSON）和 `details`（原始对象）中公开信封。 ## 批准 -如果存在 `requiresApproval`，请检查提示并决定： +如果存在 `requiresApproval`，请检查提示并作出决定： -- `approve: true` → 恢复并继续执行带副作用的操作 -- `approve: false` → 取消并结束该工作流 +- `approve: true` → 恢复并继续副作用 +- `approve: false` → 取消并最终完成工作流 -使用 `approve --preview-from-stdin --limit N` 可以把 JSON 预览附加到批准请求中，而无需自定义 `jq`/heredoc 粘合代码。现在的恢复令牌更紧凑：Lobster 会将工作流恢复状态保存在其状态目录下，并返回一个小型令牌键。 +使用 `approve --preview-from-stdin --limit N` 将 JSON 预览附加到批准请求，无需自定义 jq/heredoc 粘合代码。恢复 token 现在很紧凑：Lobster 会在其状态目录下存储工作流恢复状态，并返回一个小型 token 键。 ## OpenProse -OpenProse 与 Lobster 配合良好：先使用 `/prose` 编排多智能体准备工作，再运行一个 Lobster 流水线来执行带确定性批准的流程。如果某个 Prose 程序需要 Lobster，请通过 `tools.subagents.tools` 为子智能体允许 `lobster` 工具。参见 [OpenProse](/zh-CN/prose)。 +OpenProse 与 Lobster 配合良好：使用 `/prose` 编排多 agent 准备工作，然后运行 Lobster 管道以获得确定性批准。如果 Prose 程序需要 Lobster，请通过 `tools.subagents.tools` 为子 agent 允许 `lobster` 工具。请参阅 [OpenProse](/zh-CN/prose)。 ## 安全 -- **仅本地进程内**——工作流在 Gateway 网关进程内部执行；插件自身不会发起网络调用。 -- **无密钥管理**——Lobster 不管理 OAuth；它调用的是负责此事的 OpenClaw 工具。 -- **感知沙箱**——当工具上下文处于沙箱隔离中时，该功能会被禁用。 -- **已加固**——超时和输出上限由嵌入式运行器强制执行。 +- **仅本地进程内**——工作流在 Gateway 网关进程内执行；插件本身不会发起网络调用。 +- **无机密管理**——Lobster 不管理 OAuth；它调用负责这些操作的 OpenClaw 工具。 +- **感知沙箱**——当工具上下文处于沙箱隔离状态时会禁用。 +- **加固**——嵌入式 runner 会强制执行超时和输出上限。 ## 故障排除 -- **`lobster timed out`** → 增加 `timeoutMs`，或拆分较长流水线。 -- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes`，或减少输出大小。 -- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行，并且只输出 JSON。 -- **`lobster failed`** → 检查 Gateway 网关日志中的嵌入式运行器错误详情。 +- **`lobster timed out`** → 增加 `timeoutMs`，或拆分过长的管道。 +- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出大小。 +- **`lobster returned invalid JSON`** → 确保管道以工具模式运行，并且只打印 JSON。 +- **`lobster failed`** → 查看 Gateway 网关日志，获取嵌入式 runner 错误详情。 ## 了解更多 - [插件](/zh-CN/tools/plugin) -- [插件工具编写](/zh-CN/plugins/building-plugins#registering-agent-tools) +- [插件工具创作](/zh-CN/plugins/building-plugins#registering-agent-tools) ## 案例研究：社区工作流 -一个公开示例是：“第二大脑” CLI + Lobster 流水线，用于管理三个 Markdown 仓库（个人、伴侣、共享）。该 CLI 会为统计、收件箱列表和陈旧扫描输出 JSON；Lobster 会把这些命令串联成诸如 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 之类的工作流，每个都带有批准关卡。AI 在可用时负责判断（分类），在不可用时则回退到确定性规则。 +一个公开示例：“第二大脑”CLI + Lobster 管道，用于管理三个 Markdown vault（个人、伴侣、共享）。CLI 会为统计信息、收件箱列表和陈旧扫描输出 JSON；Lobster 将这些命令串联成 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 等工作流，每个工作流都带有批准门禁。当 AI 可用时，它负责判断（分类）；不可用时，则回退到确定性规则。 -- 讨论串：[https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) +- 线程：[https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) - 仓库：[https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) -## 相关内容 +## 相关 - [自动化与任务](/zh-CN/automation) — 调度 Lobster 工作流 - [自动化概览](/zh-CN/automation) — 所有自动化机制 -- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 +- [工具概览](/zh-CN/tools) — 所有可用 agent 工具