diff --git a/docs/zh-CN/concepts/dreaming.md b/docs/zh-CN/concepts/dreaming.md index 08293a602..f249f7145 100644 --- a/docs/zh-CN/concepts/dreaming.md +++ b/docs/zh-CN/concepts/dreaming.md @@ -2,53 +2,52 @@ read_when: - 你希望记忆提升能够自动运行 - 你希望了解 Dreaming 的三个阶段 - - 你希望在不污染 MEMORY.md 的情况下调整整合行为 -summary: 通过 light、deep 和 REM 三个协同阶段进行后台记忆整合 + - 你希望调整整合过程而不污染 `MEMORY.md` +summary: 具有三个协作阶段的后台记忆整合：浅睡、深睡和 REM title: Dreaming（实验性） x-i18n: - generated_at: "2026-04-05T22:59:53Z" + generated_at: "2026-04-05T23:42:21Z" model: gpt-5.4 provider: openai - source_hash: e6a82edf0b8630b48f458dacc270b0afc4032d5756baf39e28bf142e53cd8080 + source_hash: 9ba56b20013aa53f5f440fd79ea14dc67a61c4fb63ebe91b3fd183d09a842912 source_path: concepts/dreaming.md workflow: 15 --- # Dreaming（实验性） -Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新查看对话中出现的内容，并决定哪些内容值得保留为持久上下文。 +Dreaming 是 `memory-core` 中的后台记忆整合系统。它会重新审视对话期间出现的内容，并判断哪些值得保留为持久上下文。 -Dreaming 使用三个协同工作的**阶段**，而不是彼此竞争的模式。每个阶段都有不同的职责、写入不同的目标，并按照自己的计划运行。 +Dreaming 使用三个相互协作的**阶段**，而不是彼此竞争的模式。每个阶段都有不同的职责、写入不同的目标，并按各自的时间表运行。 ## 三个阶段 -### Light +### 浅睡 -Light Dreaming 会整理最近的杂乱内容。它会扫描最近的记忆轨迹，按 Jaccard 相似度去重，对相关条目进行聚类，并在启用 inline 存储时，将候选记忆暂存到共享的 Dreaming 轨迹文件（`DREAMS.md`）中。 +浅睡 Dreaming 用来整理最近的杂乱信息。它会扫描最近的记忆痕迹，按 Jaccard 相似度去重，对相关条目进行聚类，并在启用内联存储时将候选记忆暂存到共享的 Dreaming 轨迹文件（`DREAMS.md`）中。 -Light **不会**向 `MEMORY.md` 写入任何内容。它只负责组织和暂存。可以理解为：“今天哪些内容以后可能会重要？” +浅睡**不会**向 `MEMORY.md` 写入任何内容。它只负责整理和暂存。可以理解为：“今天的哪些内容以后可能有用？” -### Deep +### 深睡 -Deep Dreaming 会决定哪些内容会成为持久记忆。它运行真正的提升逻辑：基于六种信号的加权评分、阈值门槛、召回次数、唯一查询多样性、近期性衰减以及最大年龄过滤。 +深睡 Dreaming 决定哪些内容会成为持久记忆。它执行真正的提升逻辑：基于六个信号进行加权评分，并应用阈值门槛、召回次数、唯一查询多样性、时效衰减和最大年龄过滤。 -Deep 是**唯一**允许将持久事实写入 `MEMORY.md` 的阶段。 -它还负责在记忆不足时进行恢复（当健康度低于配置阈值时）。可以理解为：“哪些内容足够真实，值得保留？” +深睡是**唯一**允许向 `MEMORY.md` 写入持久事实的阶段。它还负责在记忆稀薄时进行恢复（健康度低于配置阈值）。可以理解为：“哪些内容足够真实，值得保留？” ### REM -REM Dreaming 会寻找模式并进行反思。它检查最近的材料，通过概念标签聚类识别反复出现的主题，并在启用 inline 存储时，将更高层次的笔记和反思写入 `DREAMS.md`。 +REM Dreaming 用于发现模式与反思。它会检查近期内容，通过概念标签聚类识别反复出现的主题，并在启用内联存储时将更高层次的笔记和反思写入 `DREAMS.md`。 -REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。 +REM 在内联模式下写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。 它的输出是解释性的，而不是规范性的。可以理解为：“我注意到了什么模式？” -## 明确边界 +## 硬性边界 | 阶段 | 职责 | 写入位置 | 不会写入 | | ----- | -------- | ------------------------- | -------- | -| Light | 整理 | `DREAMS.md`（inline 模式） | MEMORY.md | -| Deep | 保留 | MEMORY.md | -- | -| REM | 解释 | `DREAMS.md`（inline 模式） | MEMORY.md | +| 浅睡 | 整理 | `DREAMS.md`（内联模式） | MEMORY.md | +| 深睡 | 保留 | MEMORY.md | -- | +| REM | 解释 | `DREAMS.md`（内联模式） | MEMORY.md | ## 快速开始 @@ -70,7 +69,7 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。 } ``` -仅启用 deep 提升： +仅启用深睡提升： ```json { @@ -95,72 +94,71 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。 ## 配置 -所有 Dreaming 设置都位于 `openclaw.json` 中的 `plugins.entries.memory-core.config.dreaming` 下。 -完整键名列表请参见 [记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。 +所有 Dreaming 设置都位于 `openclaw.json` 中的 `plugins.entries.memory-core.config.dreaming` 下。完整键名列表请参见[记忆配置参考](/zh-CN/reference/memory-config#dreaming-experimental)。 ### 全局设置 -| 键名 | 类型 | 默认值 | 说明 | +| 键名 | 类型 | 默认值 | 描述 | | ---------------- | --------- | ---------- | ------------------------------------------------------------ | | `enabled` | `boolean` | `true` | 所有阶段的总开关 | -| `timezone` | `string` | 未设置 | 用于计划评估和 Dreaming 日期分桶的时区 | +| `timezone` | `string` | 未设置 | 用于时间表评估和 Dreaming 日期分桶的时区 | | `verboseLogging` | `boolean` | `false` | 输出每次运行的详细 Dreaming 日志 | -| `storage.mode` | `string` | `"inline"` | 使用 inline `DREAMS.md`、独立报告，或两者同时使用 | +| `storage.mode` | `string` | `"inline"` | 使用内联 `DREAMS.md`、单独报告，或同时使用两者 | -### Light 阶段配置 +### 浅睡阶段配置 -| 键名 | 类型 | 默认值 | 说明 | -| ------------------ | ---------- | ------------------------------- | -------------------------- | -| `enabled` | `boolean` | `true` | 启用 Light 阶段 | -| `cron` | `string` | `0 */6 * * *` | 计划（默认：每 6 小时） | -| `lookbackDays` | `number` | `2` | 扫描多少天内的轨迹 | -| `limit` | `number` | `100` | 每次运行最多暂存的候选数 | -| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 | -| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 | +| 键名 | 类型 | 默认值 | 描述 | +| ------------------ | ---------- | ------------------------------- | ---------------------------- | +| `enabled` | `boolean` | `true` | 启用浅睡阶段 | +| `cron` | `string` | `0 */6 * * *` | 调度计划（默认：每 6 小时） | +| `lookbackDays` | `number` | `2` | 扫描多少天内的痕迹 | +| `limit` | `number` | `100` | 每次运行最多暂存的候选数 | +| `dedupeSimilarity` | `number` | `0.9` | 去重的 Jaccard 阈值 | +| `sources` | `string[]` | `["daily","sessions","recall"]` | 要扫描的数据源 | -### Deep 阶段配置 +### 深睡阶段配置 -| 键名 | 类型 | 默认值 | 说明 | -| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ | -| `enabled` | `boolean` | `true` | 启用 Deep 阶段 | -| `cron` | `string` | `0 3 * * *` | 计划（默认：每天凌晨 3 点） | -| `limit` | `number` | `10` | 每个周期最多提升的候选数 | -| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 | -| `minRecallCount` | `number` | `3` | 最低召回次数阈值 | -| `minUniqueQueries` | `number` | `3` | 最低不同查询数量 | -| `recencyHalfLifeDays` | `number` | `14` | 近期性分数减半所需的天数 | -| `maxAgeDays` | `number` | `30` | 可提升的每日笔记最大年龄 | -| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 | +| 键名 | 类型 | 默认值 | 描述 | +| --------------------- | ---------- | ----------------------------------------------- | -------------------------------- | +| `enabled` | `boolean` | `true` | 启用深睡阶段 | +| `cron` | `string` | `0 3 * * *` | 调度计划（默认：每天凌晨 3 点） | +| `limit` | `number` | `10` | 每个周期最多提升的候选数 | +| `minScore` | `number` | `0.8` | 提升所需的最低加权分数 | +| `minRecallCount` | `number` | `3` | 最低召回次数阈值 | +| `minUniqueQueries` | `number` | `3` | 最低不同查询数量 | +| `recencyHalfLifeDays` | `number` | `14` | 时效分数减半所需天数 | +| `maxAgeDays` | `number` | `30` | 可用于提升的每日笔记最大年龄 | +| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | 数据源 | -### Deep 恢复配置 +### 深睡恢复配置 当长期记忆健康度低于某个阈值时，会触发恢复。 -| 键名 | 类型 | 默认值 | 说明 | -| --------------------------------- | --------- | ------- | -------------------------------- | -| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 | -| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度分数阈值 | -| `recovery.lookbackDays` | `number` | `30` | 向前查找恢复材料的范围 | -| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选数 | -| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选所需的最低置信度 | -| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审查） | +| 键名 | 类型 | 默认值 | 描述 | +| --------------------------------- | --------- | ------- | ---------------------------------- | +| `recovery.enabled` | `boolean` | `true` | 启用自动恢复 | +| `recovery.triggerBelowHealth` | `number` | `0.35` | 触发恢复的健康度阈值 | +| `recovery.lookbackDays` | `number` | `30` | 向前回看多长时间以查找恢复材料 | +| `recovery.maxRecoveredCandidates` | `number` | `20` | 每次运行最多恢复的候选数 | +| `recovery.minRecoveryConfidence` | `number` | `0.9` | 恢复候选所需的最低置信度 | +| `recovery.autoWriteMinConfidence` | `number` | `0.97` | 自动写入阈值（跳过人工审核） | ### REM 阶段配置 -| 键名 | 类型 | 默认值 | 说明 | -| -------------------- | ---------- | --------------------------- | ------------------------------------ | -| `enabled` | `boolean` | `true` | 启用 REM 阶段 | -| `cron` | `string` | `0 5 * * 0` | 计划（默认：每周日凌晨 5 点） | -| `lookbackDays` | `number` | `7` | 反思多少天内的材料 | -| `limit` | `number` | `10` | 最多写入的模式或主题数量 | -| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 | -| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 | +| 键名 | 类型 | 默认值 | 描述 | +| -------------------- | ---------- | --------------------------- | -------------------------------- | +| `enabled` | `boolean` | `true` | 启用 REM 阶段 | +| `cron` | `string` | `0 5 * * 0` | 调度计划（默认：每周日凌晨 5 点） | +| `lookbackDays` | `number` | `7` | 回顾多少天内的材料 | +| `limit` | `number` | `10` | 最多写入的模式或主题数量 | +| `minPatternStrength` | `number` | `0.75` | 最低标签共现强度 | +| `sources` | `string[]` | `["memory","daily","deep"]` | 用于反思的数据源 | -### 执行覆盖 +### 执行覆盖设置 -每个阶段都支持一个 `execution` 块，用于覆盖全局默认值： +每个阶段都接受一个 `execution` 块，用于覆盖全局默认值： -| 键名 | 类型 | 默认值 | 说明 | +| 键名 | 类型 | 默认值 | 描述 | | ----------------- | -------- | ------------ | ------------------------------ | | `speed` | `string` | `"balanced"` | `fast`、`balanced` 或 `slow` | | `thinking` | `string` | `"medium"` | `low`、`medium` 或 `high` | @@ -170,36 +168,36 @@ REM 在 inline 模式下会写入 `DREAMS.md`，**不会**写入 `MEMORY.md`。 | `temperature` | `number` | 未设置 | 采样温度（0-2） | | `timeoutMs` | `number` | 未设置 | 阶段超时时间（毫秒） | -## 提升信号（Deep 阶段） +## 提升信号（深睡阶段） -Deep Dreaming 会组合六种加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。 +深睡 Dreaming 会组合六个加权信号。要完成提升，所有已配置的阈值门槛都必须同时通过。 -| 信号 | 权重 | 说明 | +| 信号 | 权重 | 描述 | | ------------------ | ---- | -------------------------------------------------- | | 频率 | 0.24 | 同一条目被召回的频率 | | 相关性 | 0.30 | 被检索到时的平均召回分数 | | 查询多样性 | 0.15 | 使其浮现出来的不同查询意图数量 | -| 近期性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） | -| 整合度 | 0.10 | 奖励跨多天重复出现的召回 | -| 概念丰富度 | 0.06 | 奖励派生概念标签更丰富的条目 | +| 时效性 | 0.15 | 时间衰减（`recencyHalfLifeDays`，默认 14） | +| 整合度 | 0.10 | 奖励跨多日重复发生的召回 | +| 概念丰富度 | 0.06 | 奖励具有更丰富派生概念标签的条目 | ## 聊天命令 ``` -/dreaming status # 显示阶段配置和执行频率 +/dreaming status # 显示阶段配置和运行节奏 /dreaming on # 启用所有阶段 /dreaming off # 禁用所有阶段 -/dreaming enable light|deep|rem # 启用特定阶段 -/dreaming disable light|deep|rem # 禁用特定阶段 +/dreaming enable light|deep|rem # 启用指定阶段 +/dreaming disable light|deep|rem # 禁用指定阶段 /dreaming help # 显示使用指南 ``` ## CLI 命令 -从命令行预览并应用 deep 提升： +在命令行中预览并应用深睡提升： ```bash -# 预览提升候选 +# 预览提升候选项 openclaw memory promote # 将提升结果应用到 MEMORY.md @@ -208,7 +206,7 @@ openclaw memory promote --apply # 限制预览数量 openclaw memory promote --limit 5 -# 包含已提升条目 +# 包含已经提升的条目 openclaw memory promote --include-promoted # 检查 Dreaming 状态 @@ -217,56 +215,69 @@ openclaw memory status --deep 完整 flag 参考请参见 [memory CLI](/cli/memory)。 +### 预览与解释工具 + +另外两个子命令可帮助你在不写入任何内容的情况下检查提升与 REM 行为： + +```bash +# 解释某个候选为何会或不会被提升 +openclaw memory promote-explain "meeting notes" + +# 预览 REM 反思、候选事实和深睡提升 +openclaw memory rem-harness --json +``` + +完整选项请参见 [memory CLI](/cli/memory)。 + ## 工作原理 -### Light 阶段流程 +### 浅睡阶段流水线 1. 从 `memory/.dreams/short-term-recall.json` 读取短期召回条目。 -2. 过滤出在当前时间 `lookbackDays` 范围内的条目。 +2. 过滤出距当前时间在 `lookbackDays` 范围内的条目。 3. 按 Jaccard 相似度去重（阈值可配置）。 -4. 按平均召回分数排序，最多取 `limit` 条目。 -5. 在启用 inline 存储时，将暂存候选写入 `DREAMS.md` 的 `## Light Sleep` 区块下。 +4. 按平均召回分数排序，最多取 `limit` 个条目。 +5. 在启用内联存储时，将暂存候选写入 `DREAMS.md` 中的 `## Light Sleep` 区块下。 -### Deep 阶段流程 +### 深睡阶段流水线 1. 使用加权信号读取并排序短期召回候选。 2. 应用阈值门槛：`minScore`、`minRecallCount`、`minUniqueQueries`。 -3. 按 `maxAgeDays` 过滤，并应用近期性衰减。 -4. 扩展到所有已配置的记忆工作区。 -5. 写入前重新读取实时每日笔记（跳过过期或已删除的片段）。 -6. 将符合条件的条目连同提升时间戳追加到 `MEMORY.md`。 -7. 标记已提升条目，以便在后续周期中将其排除。 +3. 按 `maxAgeDays` 过滤，并应用时效衰减。 +4. 分发到已配置的各个记忆工作区。 +5. 写入前重新读取实时每日笔记（跳过过时或已删除的片段）。 +6. 将符合条件的条目及其提升时间戳追加到 `MEMORY.md`。 +7. 标记已提升条目，以便将来周期中排除它们。 8. 如果健康度低于 `recovery.triggerBelowHealth`，则运行恢复流程。 -### REM 阶段流程 +### REM 阶段流水线 -1. 读取 `lookbackDays` 范围内的近期记忆轨迹。 -2. 按共现关系对概念标签进行聚类。 +1. 读取 `lookbackDays` 范围内的近期记忆痕迹。 +2. 按共现关系对概念标签聚类。 3. 按 `minPatternStrength` 过滤模式。 -4. 在启用 inline 存储时，将主题和反思写入 `DREAMS.md` 的 `## REM Sleep` 区块下。 +4. 在启用内联存储时，将主题和反思写入 `DREAMS.md` 中的 `## REM Sleep` 区块下。 ## 调度 -每个阶段都会自动管理自己的 cron 任务。启用 Dreaming 后， -`memory-core` 会在 Gateway 网关启动时协调受管的 cron 任务。你无需手动创建 cron 条目。 +每个阶段都会自动管理自己的 cron 作业。启用 Dreaming 后，`memory-core` 会在 Gateway 网关启动时协调受管 cron 作业。你无需手动创建 cron 条目。 -| 阶段 | 默认计划 | 说明 | +| 阶段 | 默认计划 | 描述 | | ----- | ---------------- | ----------------- | -| Light | `0 */6 * * *` | 每 6 小时一次 | -| Deep | `0 3 * * *` | 每天凌晨 3 点 | +| 浅睡 | `0 */6 * * *` | 每 6 小时一次 | +| 深睡 | `0 3 * * *` | 每天凌晨 3 点 | | REM | `0 5 * * 0` | 每周日凌晨 5 点 | -你可以使用阶段的 `cron` 键覆盖任意计划。所有计划都会遵循全局 `timezone` 设置。 +你可以用各阶段的 `cron` 键覆盖任意计划。所有计划都会遵循全局 `timezone` 设置。 ## Dreams UI -启用 Dreaming 后，Gateway 网关侧边栏会显示一个 **Dreams** 标签页，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期时间。每日计数在设置了 `dreaming.timezone` 时会遵循该时区，否则回退到已配置的用户时区。 +启用 Dreaming 后，Gateway 网关侧边栏会显示一个**Dreams**选项卡，其中包含记忆统计信息（短期数量、长期数量、已提升数量）以及下一次计划周期的时间。每日计数会在设置 `dreaming.timezone` 时遵循该时区，否则回退到已配置的用户时区。 -手动运行 `openclaw memory promote` 时，默认会使用与 Deep 阶段相同的阈值，因此除非你传入 CLI 覆盖项，否则计划提升与按需提升会保持一致。 +手动运行 `openclaw memory promote` 默认会使用与深睡阶段相同的阈值，因此除非你传入 CLI 覆盖项，否则计划内提升与按需提升会保持一致。 ## 相关内容 -- [记忆](/zh-CN/concepts/memory) -- [记忆搜索](/zh-CN/concepts/memory-search) +- [Memory](/zh-CN/concepts/memory) +- [Memory Search](/zh-CN/concepts/memory-search) - [记忆配置参考](/zh-CN/reference/memory-config) - [memory CLI](/cli/memory) diff --git a/docs/zh-CN/tools/lobster.md b/docs/zh-CN/tools/lobster.md index 207d0690e..8743efedd 100644 --- a/docs/zh-CN/tools/lobster.md +++ b/docs/zh-CN/tools/lobster.md @@ -1,54 +1,54 @@ --- read_when: - - 你希望使用带显式批准的确定性多步骤工作流 + - 你想要具有显式审批机制的确定性多步骤工作流 - 你需要在不重新运行前面步骤的情况下恢复工作流 -summary: OpenClaw 的类型化工作流运行时，带可恢复的 approval gate。 +summary: OpenClaw 的类型化工作流运行时，支持可恢复的审批关卡。 title: Lobster x-i18n: - generated_at: "2026-04-05T10:12:07Z" + generated_at: "2026-04-05T23:42:20Z" model: gpt-5.4 provider: openai - source_hash: 82718c15d571406ad6f1507de22a528fdab873edfc6aafae10742e500f6a5eda + source_hash: c1014945d104ef8fdca0d30be89e35136def1b274c6403b06de29e8502b8124b source_path: tools/lobster.md workflow: 15 --- # Lobster -Lobster 是一个工作流 shell，让 OpenClaw 能够将多步骤工具序列作为单个、确定性的操作来运行，并带有显式的批准检查点。 +Lobster 是一个工作流 shell，让 OpenClaw 能将多步骤工具序列作为一次单一、确定性的操作来运行，并带有显式审批检查点。 -Lobster 比脱离式后台工作高一个编写层级。关于单个任务之上的 flow 编排，请参见 [Task Flow](/zh-CN/automation/taskflow)（`openclaw tasks flow`）。关于任务活动账本，请参见 [`openclaw tasks`](/zh-CN/automation/tasks)。 +Lobster 位于分离式后台工作的上一层编写层级。有关单个任务之上的流程编排，请参见 [Task Flow](/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 工具调用并得到结构化结果。 -- **内置批准**：副作用操作（发送邮件、发布评论）会暂停工作流，直到明确批准。 -- **可恢复**：被暂停的工作流会返回一个 token；批准后可继续，而无需重新运行所有内容。 +- **一次调用代替多次调用**：OpenClaw 运行一次 Lobster 工具调用，并获得结构化结果。 +- **内置审批**：带有副作用的操作（发送邮件、发布评论）会暂停工作流，直到被显式批准。 +- **可恢复**：已暂停的工作流会返回一个 token；批准后可继续，而无需重新运行所有内容。 ## 为什么使用 DSL，而不是普通程序？ -Lobster 是刻意保持小巧的。目标不是“创造一门新语言”，而是提供一种可预测、对 AI 友好的流水线规范，并带有一等公民级别的批准和恢复 token。 +Lobster 有意保持精简。目标不是“发明一种新语言”，而是提供一种可预测、对 AI 友好的流水线规范，并内建一等支持的审批和恢复 token。 -- **内置 approve/resume**：普通程序可以提示人类，但如果不由你自己发明那套运行时，它就无法使用持久 token 来_暂停并恢复_。 -- **确定性 + 可审计性**：流水线是数据，因此易于记录、Diffs、重放和审查。 -- **为 AI 限制表面**：微小的语法 + JSON 管道减少了“创造性”代码路径，使验证更现实。 -- **内建安全策略**：超时、输出上限、沙箱检查和 allowlists 都由运行时强制执行，而不是由每个脚本各自处理。 -- **仍然可编程**：每个步骤都可以调用任意 CLI 或脚本。如果你想使用 JS/TS，可以从代码生成 `.lobster` 文件。 +- **内置批准/恢复机制**：普通程序可以提示人工确认，但如果没有你自己发明那套运行时，它就无法借助持久 token 实现_暂停并恢复_。 +- **确定性 + 可审计性**：流水线是数据，因此容易记录、Diffs、重放和审查。 +- **面向 AI 的受限表面**：精简语法 + JSON 管道可减少“创造性”代码路径，并让校验变得切实可行。 +- **内建安全策略**：超时、输出上限、沙箱检查和允许列表都由运行时强制执行，而不是由每个脚本分别处理。 +- **依然可编程**：每一步都可以调用任意 CLI 或脚本。如果你想用 JS/TS，可以从代码生成 `.lobster` 文件。 ## 工作原理 -OpenClaw 会以**工具模式**启动本地 `lobster` CLI，并从 stdout 解析一个 JSON 信封。 -如果流水线因等待批准而暂停，该工具会返回一个 `resumeToken`，以便你稍后继续。 +OpenClaw 使用内嵌运行器**在进程内**运行 Lobster 工作流。不会生成外部 CLI 子进程；工作流引擎在 Gateway 网关进程内执行，并直接返回一个 JSON 包装对象。 +如果流水线因等待审批而暂停，工具会返回一个 `resumeToken`，这样你就可以稍后继续。 -## 模式：小型 CLI + JSON 管道 + 批准 +## 模式：小型 CLI + JSON 管道 + 审批 -构建一些使用 JSON 通信的小命令，然后把它们串联成一次 Lobster 调用。（下面的命令名仅为示例 —— 你可以替换成自己的。） +构建能输出 JSON 的小命令，然后将它们串联成一次 Lobster 调用。（下面的命令名仅作示例——可替换为你自己的命令。） ```bash inbox list --json @@ -64,7 +64,7 @@ inbox apply --json } ``` -如果流水线请求批准，请使用该 token 恢复： +如果流水线请求审批，可使用 token 恢复： ```json { @@ -74,7 +74,7 @@ inbox apply --json } ``` -AI 触发工作流；Lobster 执行各个步骤。approval gates 让副作用保持显式且可审计。 +AI 触发工作流；Lobster 执行这些步骤。审批关卡让副作用保持显式且可审计。 示例：将输入项映射为工具调用： @@ -83,11 +83,11 @@ gog.gmail.search --query 'newer_than:1d' \ | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}' ``` -## 仅限 JSON 的 LLM 步骤（llm-task） +## 仅 JSON 的 LLM 步骤（`llm-task`） -对于需要**结构化 LLM 步骤**的工作流，请启用可选的 -`llm-task` 插件工具，并从 Lobster 中调用它。这样既能保持工作流的 -确定性，又能继续使用模型进行分类/摘要/起草。 +对于需要**结构化 LLM 步骤**的工作流，启用可选的 +`llm-task` 插件工具，并从 Lobster 中调用它。这样可以让工作流保持 +确定性，同时仍然可以借助模型进行分类、总结或起草。 启用该工具： @@ -128,11 +128,11 @@ openclaw.invoke --tool llm-task --action json --args-json '{ }' ``` -详细信息和配置选项请参见 [LLM Task](/zh-CN/tools/llm-task)。 +有关详细信息和配置选项，请参见 [LLM Task](/zh-CN/tools/llm-task)。 -## 工作流文件（.lobster） +## 工作流文件（`.lobster`） -Lobster 可以运行 YAML/JSON 工作流文件，支持 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径即可。 +Lobster 可以运行带有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径。 ```yaml name: inbox-triage @@ -158,11 +158,13 @@ steps: 说明： - `stdin: $step.stdout` 和 `stdin: $step.json` 会传递前一步的输出。 -- `condition`（或 `when`）可根据 `$step.approved` 控制步骤是否运行。 +- `condition`（或 `when`）可基于 `$step.approved` 控制步骤是否执行。 ## 安装 Lobster -请在运行 OpenClaw Gateway 网关的**同一台主机**上安装 Lobster CLI（参见 [Lobster 仓库](https://github.com/openclaw/lobster)），并确保 `lobster` 已加入 `PATH`。 +内置的 Lobster 工作流在进程内运行；不需要单独的 `lobster` 二进制文件。内嵌运行器随 Lobster 插件一起提供。 + +如果你在开发或外部流水线中需要独立的 Lobster CLI，请从 [Lobster repo](https://github.com/openclaw/lobster) 安装，并确保 `lobster` 已在 `PATH` 中。 ## 启用该工具 @@ -178,7 +180,7 @@ Lobster 是一个**可选**插件工具（默认未启用）。 } ``` -或按智能体配置： +或者按智能体配置： ```json { @@ -195,28 +197,28 @@ Lobster 是一个**可选**插件工具（默认未启用）。 } ``` -除非你确实打算在严格 allowlist 模式下运行，否则请避免使用 `tools.allow: ["lobster"]`。 +除非你打算在限制性允许列表模式下运行，否则请避免使用 `tools.allow: ["lobster"]`。 -注意：对于可选插件，allowlists 是选择加入的。如果你的 allowlist 只命名了 -插件工具（例如 `lobster`），OpenClaw 仍会保持核心工具启用。若要限制核心 -工具，也请在 allowlist 中加入你希望保留的核心工具或工具组。 +注意：允许列表对于可选插件是选择启用的。如果你的允许列表只列出 +插件工具（如 `lobster`），OpenClaw 会保留核心工具启用状态。若要限制核心 +工具，也请将你希望保留的核心工具或工具组一并加入允许列表。 -## 示例：邮件分类处理 +## 示例：电子邮件分类处理 -不使用 Lobster： +没有 Lobster 时： ``` User: "Check my email and draft replies" → openclaw 调用 gmail.list -→ LLM 做摘要 +→ LLM 进行总结 → User: "draft replies to #2 and #5" → LLM 起草回复 → User: "send #2" → openclaw 调用 gmail.send -（每天重复，且不记得哪些内容已被分类处理） +（每天重复，没有关于已分类内容的记忆） ``` -使用 Lobster： +使用 Lobster 时： ```json { @@ -226,7 +228,7 @@ User: "Check my email and draft replies" } ``` -返回一个 JSON 信封（已截断）： +返回一个 JSON 包装对象（已截断）： ```json { @@ -258,7 +260,7 @@ User: "Check my email and draft replies" ### `run` -以工具模式运行一个流水线。 +以工具模式运行流水线。 ```json { @@ -282,7 +284,7 @@ User: "Check my email and draft replies" ### `resume` -在批准后继续一个被暂停的工作流。 +在审批后继续已暂停的工作流。 ```json { @@ -294,62 +296,62 @@ User: "Check my email and draft replies" ### 可选输入 -- `cwd`：流水线的相对工作目录（必须保持在当前进程工作目录内）。 -- `timeoutMs`：如果子进程超过该时长，则将其终止（默认：20000）。 -- `maxStdoutBytes`：如果 stdout 超过该大小，则将子进程终止（默认：512000）。 +- `cwd`：流水线的相对工作目录（必须保持在 Gateway 网关工作目录内）。 +- `timeoutMs`：如果工作流超过该时长则中止（默认：20000）。 +- `maxStdoutBytes`：如果输出超过该大小则中止（默认：512000）。 - `argsJson`：传递给 `lobster run --args-json` 的 JSON 字符串（仅适用于工作流文件）。 -## 输出信封 +## 输出包装对象 -Lobster 会返回一个 JSON 信封，其状态有以下三种之一： +Lobster 返回一个 JSON 包装对象，其状态有以下三种之一： - `ok` → 成功完成 - `needs_approval` → 已暂停；恢复时需要 `requiresApproval.resumeToken` -- `cancelled` → 已被显式拒绝或取消 +- `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 胶水代码。现在的恢复 token 更紧凑：Lobster 会将工作流恢复状态存储在其状态目录下，并返回一个小型 token 键。 +使用 `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` 来编排多智能体准备工作，然后运行 Lobster 流水线以进行确定性审批。如果某个 Prose 程序需要 Lobster，可通过 `tools.subagents.tools` 为子智能体允许 `lobster` 工具。请参见 [OpenProse](/zh-CN/prose)。 ## 安全 -- **仅限本地子进程** —— 插件本身不发起网络调用。 -- **无密钥管理** —— Lobster 不管理 OAuth；它调用的是管理这些内容的 OpenClaw 工具。 -- **感知沙箱** —— 在沙箱化工具上下文中会被禁用。 -- **已加固** —— 固定可执行文件名（`PATH` 中的 `lobster`）；并强制执行超时和输出上限。 +- **仅限本地进程内**——工作流在 Gateway 网关进程内执行；插件本身不会发起网络调用。 +- **无密钥管理**——Lobster 不管理 OAuth；它调用的是负责管理 OAuth 的 OpenClaw 工具。 +- **感知沙箱**——当工具上下文处于沙箱隔离状态时将被禁用。 +- **已加固**——超时和输出上限由内嵌运行器强制执行。 ## 故障排除 -- **`lobster subprocess timed out`** → 增加 `timeoutMs`，或拆分过长的流水线。 -- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出量。 -- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行，并且只打印 JSON。 -- **`lobster failed (code …)`** → 在终端中运行相同的流水线以检查 stderr。 +- **`lobster timed out`** → 增加 `timeoutMs`，或拆分较长的流水线。 +- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出大小。 +- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行，并且只输出 JSON。 +- **`lobster failed`** → 检查 Gateway 网关日志中的内嵌运行器错误详情。 ## 了解更多 -- [插件](/zh-CN/tools/plugin) -- [插件工具编写](/zh-CN/plugins/building-plugins#registering-agent-tools) +- [Plugins](/zh-CN/tools/plugin) +- [Plugin tool authoring](/zh-CN/plugins/building-plugins#registering-agent-tools) ## 案例研究：社区工作流 -一个公开示例是：“second brain” CLI + Lobster 流水线，用于管理三个 Markdown 仓库（个人、伴侣、共享）。该 CLI 会为统计、收件箱列表和陈旧扫描输出 JSON；Lobster 再把这些命令串联成诸如 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 之类的工作流，并为每个工作流设置 approval gates。AI 在可用时负责判断（分类），不可用时则回退为确定性规则。 +一个公开示例是：一个“第二大脑” CLI + Lobster 流水线，用于管理三个 Markdown 知识库（个人、伴侣、共享）。该 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://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) ## 相关内容 -- [自动化与任务](/zh-CN/automation) —— 调度 Lobster 工作流 -- [自动化概览](/zh-CN/automation) —— 所有自动化机制 -- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具 +- [Automation & Tasks](/zh-CN/automation) — 调度 Lobster 工作流 +- [Automation Overview](/zh-CN/automation) — 所有自动化机制 +- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具