@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/tools/subagents.md

@@ -0,0 +1,167 @@
+---
+read_when:
+  - 你想通过智能体执行后台/并行工作
+  - 你正在更改 sessions_spawn 或子智能体工具策略
+summary: 子智能体：生成隔离的智能体运行，并将结果通告回请求者聊天
+title: 子智能体
+x-i18n:
+  generated_at: "2026-02-03T10:12:07Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3c83eeed69a65dbbb6b21a386f3ac363d3ef8f077f0e03b834c3f0a9911dca7c
+  source_path: tools/subagents.md
+  workflow: 15
+---
+
+# 子智能体
+
+子智能体是从现有智能体运行中生成的后台智能体运行。它们在自己的会话中运行（`agent:<agentId>:subagent:<uuid>`），完成后将结果**通告**回请求者的聊天渠道。
+
+## 斜杠命令
+
+使用 `/subagents` 检查或控制**当前会话**的子智能体运行：
+
+- `/subagents list`
+- `/subagents kill <id|#|all>`
+- `/subagents log <id|#> [limit] [tools]`
+- `/subagents info <id|#>`
+- `/subagents send <id|#> <message>`
+- `/subagents steer <id|#> <message>`
+- `/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]`
+
+`/subagents info` 显示运行元数据（状态、时间戳、会话 id、转录路径、清理）。
+
+### 启动行为
+
+`/subagents spawn` 以用户命令方式启动后台子智能体，任务完成后会向请求者聊天频道回发一条最终完成消息。
+
+- 该命令非阻塞，先返回 `runId`。
+- 完成后，子智能体会将汇总/结果消息发布到请求者聊天渠道。
+- `--model` 与 `--thinking` 可仅对本次运行做覆盖设置。
+- 可在完成后通过 `info`/`log` 查看详细信息和输出。
+
+主要目标：
+
+- 并行化"研究 / 长任务 / 慢工具"工作，而不阻塞主运行。
+- 默认保持子智能体隔离（会话分离 + 可选沙箱隔离）。
+- 保持工具接口难以滥用：子智能体默认**不**获得会话工具。
+- 避免嵌套扇出：子智能体不能生成子智能体。
+
+成本说明：每个子智能体都有**自己的**上下文和 token 使用量。对于繁重或重复的任务，为子智能体设置更便宜的模型，而让主智能体使用更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或每智能体覆盖来配置。
+
+## 工具
+
+使用 `sessions_spawn`：
+
+- 启动子智能体运行（`deliver: false`，全局队列：`subagent`）
+- 然后运行通告步骤，并将通告回复发布到请求者的聊天渠道
+- 默认模型：继承调用者，除非你设置了 `agents.defaults.subagents.model`（或每智能体的 `agents.list[].subagents.model`）；显式的 `sessions_spawn.model` 仍然优先。
+- 默认思考：继承调用者，除非你设置了 `agents.defaults.subagents.thinking`（或每智能体的 `agents.list[].subagents.thinking`）；显式的 `sessions_spawn.thinking` 仍然优先。
+
+工具参数：
+
+- `task`（必需）
+- `label?`（可选）
+- `agentId?`（可选；如果允许，在另一个智能体 id 下生成）
+- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行并在工具结果中显示警告）
+- `thinking?`（可选；覆盖子智能体运行的思考级别）
+- `runTimeoutSeconds?`（默认 `0`；设置后，子智能体运行在 N 秒后中止）
+- `cleanup?`（`delete|keep`，默认 `keep`）
+
+允许列表：
+
+- `agents.list[].subagents.allowAgents`：可以通过 `agentId` 指定的智能体 id 列表（`["*"]` 允许任意）。默认：仅限请求者智能体。
+
+发现：
+
+- 使用 `agents_list` 查看当前允许用于 `sessions_spawn` 的智能体 id。
+
+自动归档：
+
+- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes` 后自动归档（默认：60）。
+- 归档使用 `sessions.delete` 并将转录重命名为 `*.deleted.<timestamp>`（同一文件夹）。
+- `cleanup: "delete"` 在通告后立即归档（仍通过重命名保留转录）。
+- 自动归档是尽力而为的；如果 Gateway 网关重启，待处理的定时器会丢失。
+- `runTimeoutSeconds` **不会**自动归档；它只停止运行。会话会保留直到自动归档。
+
+## 认证
+
+子智能体认证按**智能体 id** 解析，而不是按会话类型：
+
+- 子智能体会话键是 `agent:<agentId>:subagent:<uuid>`。
+- 认证存储从该智能体的 `agentDir` 加载。
+- 主智能体的认证配置文件作为**回退**合并；智能体配置文件在冲突时覆盖主配置文件。
+
+注意：合并是累加的，所以主配置文件始终可用作回退。目前尚不支持每智能体完全隔离的认证。
+
+## 通告
+
+子智能体通过通告步骤报告：
+
+- 通告步骤在子智能体会话中运行（不是请求者会话）。
+- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不发布任何内容。
+- 否则，通告回复通过后续的 `agent` 调用（`deliver=true`）发布到请求者的聊天渠道。
+- 通告回复在可用时保留线程/话题路由（Slack 线程、Telegram 话题、Matrix 线程）。
+- 通告消息被规范化为稳定模板：
+  - `Status:` 从运行结果派生（`success`、`error`、`timeout` 或 `unknown`）。
+  - `Result:` 通告步骤的摘要内容（如果缺失则为 `(not available)`）。
+  - `Notes:` 错误详情和其他有用的上下文。
+- `Status` 不是从模型输出推断的；它来自运行时结果信号。
+
+通告负载在末尾包含统计行（即使被包装）：
+
+- 运行时间（例如 `runtime 5m12s`）
+- Token 使用量（输入/输出/总计）
+- 配置模型定价时的估计成本（`models.providers.*.models[].cost`）
+- `sessionKey`、`sessionId` 和转录路径（以便主智能体可以通过 `sessions_history` 获取历史记录或检查磁盘上的文件）
+
+## 工具策略（子智能体工具）
+
+默认情况下，子智能体获得**除会话工具外的所有工具**：
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+通过配置覆盖：
+
+```json5
+{
+  agents: {
+    defaults: {
+      subagents: {
+        maxConcurrent: 1,
+      },
+    },
+  },
+  tools: {
+    subagents: {
+      tools: {
+        // deny 优先
+        deny: ["gateway", "cron"],
+        // 如果设置了 allow，则变为仅允许模式（deny 仍然优先）
+        // allow: ["read", "exec", "process"]
+      },
+    },
+  },
+}
+```
+
+## 并发
+
+子智能体使用专用的进程内队列通道：
+
+- 通道名称：`subagent`
+- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`）
+
+## 停止
+
+- 在请求者聊天中发送 `/stop` 会中止请求者会话并停止从中生成的任何活动子智能体运行。
+
+## 限制
+
+- 子智能体通告是**尽力而为**的。如果 Gateway 网关重启，待处理的"通告回复"工作会丢失。
+- 子智能体仍然共享相同的 Gateway 网关进程资源；将 `maxConcurrent` 视为安全阀。
+- `sessions_spawn` 始终是非阻塞的：它立即返回 `{ status: "accepted", runId, childSessionKey }`。
+- 子智能体上下文仅注入 `AGENTS.md` + `TOOLS.md`（无 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。

package/docs/zh-CN/tools/thinking.md

@@ -0,0 +1,80 @@
+---
+read_when:
+  - 调整思考或详细模式指令解析或默认值时
+summary: "`/think` + `/verbose` 的指令语法及其对模型推理的影响"
+title: 思考级别
+x-i18n:
+  generated_at: "2026-02-01T21:43:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1a611474c2781c9a8e9dac0e084e7ee4ef58aebece181fdc877392fc27442746
+  source_path: tools/thinking.md
+  workflow: 15
+---
+
+# 思考级别（/think 指令）
+
+## 功能说明
+
+- 在任何入站消息正文中使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
+- 级别（别名）：`off | minimal | low | medium | high | xhigh`（仅 GPT-5.2 + Codex 模型）
+  - minimal → "think"
+  - low → "think hard"
+  - medium → "think harder"
+  - high → "ultrathink"（最大预算）
+  - xhigh → "ultrathink+"（仅 GPT-5.2 + Codex 模型）
+  - `highest`、`max` 映射为 `high`。
+- 提供商说明：
+  - Z.AI（`zai/*`）仅支持二元思考（`on`/`off`）。任何非 `off` 级别均视为 `on`（映射为 `low`）。
+
+## 解析优先顺序
+
+1. 消息上的内联指令（仅适用于该条消息）。
+2. 会话覆盖（通过发送仅包含指令的消息设置）。
+3. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
+4. 回退：具备推理能力的模型为 low；否则为 off。
+
+## 设置会话默认值
+
+- 发送一条**仅包含**指令的消息（允许空白），例如 `/think:medium` 或 `/t high`。
+- 该设置在当前会话中持续生效（默认按发送者）；通过 `/think:off` 或会话空闲重置来清除。
+- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令将被拒绝并给出提示，会话状态保持不变。
+- 不带参数发送 `/think`（或 `/think:`）可查看当前思考级别。
+
+## 按智能体应用
+
+- **内嵌 Pi**：解析后的级别传递给进程内的 Pi 智能体运行时。
+
+## 详细模式指令（/verbose 或 /v）
+
+- 级别：`on`（最小）| `full` | `off`（默认）。
+- 仅包含指令的消息切换会话详细模式并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别返回提示且不改变状态。
+- `/verbose off` 存储一个显式的会话覆盖；通过会话 UI 选择 `inherit` 来清除。
+- 内联指令仅影响该条消息；否则应用会话/全局默认值。
+- 不带参数发送 `/verbose`（或 `/verbose:`）可查看当前详细模式级别。
+- 启用详细模式后，发出结构化工具结果的智能体（Pi 及其他 JSON 智能体）会将每个工具调用作为独立的元数据消息发回，可用时以 `<emoji> <tool-name>: <arg>` 为前缀（路径/命令）。这些工具摘要在每个工具启动时立即发送（独立气泡），而非作为流式增量。
+- 当详细模式为 `full` 时，工具输出也会在完成后转发（独立气泡，截断至安全长度）。如果在运行过程中切换 `/verbose on|full|off`，后续的工具气泡会遵循新设置。
+
+## 推理可见性（/reasoning）
+
+- 级别：`on|off|stream`。
+- 仅包含指令的消息切换回复中是否显示思考块。
+- 启用时，推理内容作为**独立消息**发送，以 `Reasoning:` 为前缀。
+- `stream`（仅 Telegram）：在回复生成期间将推理内容流式输出到 Telegram 草稿气泡中，然后发送不包含推理的最终回答。
+- 别名：`/reason`。
+- 不带参数发送 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
+
+## 相关内容
+
+- 提权模式文档位于[提权模式](/tools/elevated)。
+
+## 心跳
+
+- 心跳探测正文为配置的心跳提示词（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令照常生效（但避免从心跳中更改会话默认值）。
+- 心跳投递默认仅包含最终负载。要同时发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或按智能体 `agents.list[].heartbeat.includeReasoning: true`。
+
+## Web 聊天 UI
+
+- Web 聊天的思考选择器在页面加载时从入站会话存储/配置中读取并反映会话的已存储级别。
+- 选择另一个级别仅应用于下一条消息（`thinkingOnce`）；发送后，选择器会回到已存储的会话级别。
+- 要更改会话默认值，请发送 `/think:<level>` 指令（和之前一样）；选择器将在下次刷新后反映该设置。

package/docs/zh-CN/tools/web.md

@@ -0,0 +1,289 @@
+---
+read_when:
+  - 你想启用 web_search 或 web_fetch
+  - 你需要设置 Brave Search API 密钥
+  - 你想使用 Perplexity Sonar 进行网络搜索
+summary: Web 搜索 + 获取工具（Brave Search API、Perplexity 直连/OpenRouter）
+title: Web 工具
+x-i18n:
+  generated_at: "2026-02-03T10:12:43Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 760b706cc966cb421e370f10f8e76047f8ca9fe0a106d90c05d979976789465a
+  source_path: tools/web.md
+  workflow: 15
+---
+
+# Web 工具
+
+QuantumClaw 提供两个轻量级 Web 工具：
+
+- `web_search` — 通过 Brave Search API、Firecrawl Search、Gemini with Google Search grounding、Grok、Kimi 或 Perplexity Search API 搜索网络。
+- `web_fetch` — HTTP 获取 + 可读性提取（HTML → markdown/文本）。
+
+这些**不是**浏览器自动化。对于 JS 密集型网站或需要登录的情况，请使用[浏览器工具](/tools/browser)。
+
+## 工作原理
+
+- `web_search` 调用你配置的提供商并返回结果。
+- 结果按查询缓存 15 分钟（可配置）。
+- `web_fetch` 执行普通 HTTP GET 并提取可读内容（HTML → markdown/文本）。它**不**执行 JavaScript。
+- `web_fetch` 默认启用（除非显式禁用）。
+- 启用捆绑的 Firecrawl 插件后，还会提供 `firecrawl_search` 和 `firecrawl_scrape`。
+
+## 选择搜索提供商
+
+| 提供商                | 结果形式           | 说明                                            | API 密钥                                    |
+| --------------------- | ------------------ | ----------------------------------------------- | ------------------------------------------- |
+| **Brave Search API**  | 结构化结果 + 摘要  | 支持 Brave `llm-context` 模式                   | `BRAVE_API_KEY`                             |
+| **Firecrawl Search**  | 结构化结果 + 摘要  | Firecrawl 专用搜索控制请使用 `firecrawl_search` | `FIRECRAWL_API_KEY`                         |
+| **Gemini**            | AI 综合答案 + 引用 | 使用 Google Search grounding                    | `GEMINI_API_KEY`                            |
+| **Grok**              | AI 综合答案 + 引用 | 使用 xAI 实时网络搜索                           | `XAI_API_KEY`                               |
+| **Kimi**              | AI 综合答案 + 引用 | 使用 Moonshot web search                        | `KIMI_API_KEY` / `MOONSHOT_API_KEY`         |
+| **Perplexity Search** | 结构化结果 + 摘要  | 兼容 OpenRouter Sonar 路径                      | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
+
+参见 [Brave Search 设置](/brave-search) 和 [Perplexity Sonar](/perplexity) 了解提供商特定详情。
+
+在配置中设置提供商：
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "brave", // 或 "firecrawl" | "gemini" | "grok" | "kimi" | "perplexity"
+      },
+    },
+  },
+}
+```
+
+示例：切换到 Perplexity Search / Sonar 兼容路径：
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+## 获取 Brave API 密钥
+
+1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户
+2. 在控制面板中，选择 **Data for Search** 计划（不是"Data for AI"）并生成 API 密钥。
+3. 运行 `quantumclaw configure --section web` 将密钥存储在配置中（推荐），或在环境中设置 `BRAVE_API_KEY`。
+
+Brave 提供免费层和付费计划；查看 Brave API 门户了解当前限制和定价。
+
+### 在哪里设置密钥（推荐）
+
+**推荐：** 运行 `quantumclaw configure --section web`。它会把密钥存储到 `~/.quantumclaw/quantumclaw.json` 的 `plugins.entries.brave.config.webSearch.apiKey`。
+
+**环境变量替代方案：** 在 Gateway 网关进程环境中设置 `BRAVE_API_KEY`。对于 Gateway 网关安装，将其放在 `~/.quantumclaw/.env`（或你的服务环境）中。参见[环境变量](/help/faq#how-does-quantumclaw-load-environment-variables)。
+
+## 使用 Perplexity（直连或通过 OpenRouter）
+
+Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用的 AI 综合答案。你可以通过 OpenRouter 使用它们（无需信用卡 - 支持加密货币/预付费）。
+
+### 获取 OpenRouter API 密钥
+
+1. 在 https://openrouter.ai/ 创建账户
+2. 添加额度（支持加密货币、预付费或信用卡）
+3. 在账户设置中生成 API 密钥
+
+### 设置 Perplexity 搜索
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        provider: "perplexity",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            // API 密钥（如果设置了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
+            apiKey: "sk-or-v1-...",
+            // 基础 URL（如果省略则根据密钥感知默认值）
+            baseUrl: "https://openrouter.ai/api/v1",
+            // 模型（默认为 perplexity/sonar-pro）
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+**环境变量替代方案：** 在 Gateway 网关环境中设置 `OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY`。对于 Gateway 网关安装，将其放在 `~/.quantumclaw/.env` 中。
+
+如果未设置基础 URL，QuantumClaw 会根据 API 密钥来源选择默认值：
+
+- `PERPLEXITY_API_KEY` 或 `pplx-...` → `https://api.perplexity.ai`
+- `OPENROUTER_API_KEY` 或 `sk-or-...` → `https://openrouter.ai/api/v1`
+- 未知密钥格式 → OpenRouter（安全回退）
+
+### 可用的 Perplexity 模型
+
+| 模型                             | 描述                 | 最适合   |
+| -------------------------------- | -------------------- | -------- |
+| `perplexity/sonar`               | 带网络搜索的快速问答 | 快速查询 |
+| `perplexity/sonar-pro`（默认）   | 带网络搜索的多步推理 | 复杂问题 |
+| `perplexity/sonar-reasoning-pro` | 思维链分析           | 深度研究 |
+
+## web_search
+
+使用配置的提供商搜索网络。
+
+### 要求
+
+- `tools.web.search.enabled` 不能为 `false`（默认：启用）
+- 所选提供商的 API 密钥：
+  - **Brave**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
+  - **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
+
+### 配置
+
+```json5
+{
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        maxResults: 5,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+      },
+    },
+  },
+}
+```
+
+提供商专属的 web_search 配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。
+旧的 `tools.web.search.*` 提供商路径仅作为兼容层暂时保留，不应再用于新配置。
+
+### 工具参数
+
+- `query`（必需）
+- `count`（1–10；默认来自配置）
+- `country`（可选）：用于特定地区结果的 2 字母国家代码（例如"DE"、"US"、"ALL"）。如果省略，Brave 选择其默认地区。
+- `search_lang`（可选）：搜索结果的 ISO 语言代码（例如"de"、"en"、"fr"）
+- `ui_lang`（可选）：UI 元素的 ISO 语言代码
+- `freshness`（可选，仅限 Brave）：按发现时间过滤（`pd`、`pw`、`pm`、`py` 或 `YYYY-MM-DDtoYYYY-MM-DD`）
+
+**示例：**
+
+```javascript
+// 德国特定搜索
+await web_search({
+  query: "TV online schauen",
+  count: 10,
+  country: "DE",
+  search_lang: "de",
+});
+
+// 带法语 UI 的法语搜索
+await web_search({
+  query: "actualités",
+  country: "FR",
+  search_lang: "fr",
+  ui_lang: "fr",
+});
+
+// 最近结果（过去一周）
+await web_search({
+  query: "TMBG interview",
+  freshness: "pw",
+});
+```
+
+## web_fetch
+
+获取 URL 并提取可读内容。
+
+### 要求
+
+- `tools.web.fetch.enabled` 不能为 `false`（默认：启用）
+- 可选的 Firecrawl 回退：设置 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY`。
+
+### 配置
+
+```json5
+{
+  tools: {
+    web: {
+      fetch: {
+        enabled: true,
+        maxChars: 50000,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+        maxRedirects: 3,
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+        readability: true,
+        firecrawl: {
+          enabled: true,
+          apiKey: "FIRECRAWL_API_KEY_HERE", // 如果设置了 FIRECRAWL_API_KEY 则可选
+          baseUrl: "https://api.firecrawl.dev",
+          onlyMainContent: true,
+          maxAgeMs: 86400000, // 毫秒（1 天）
+          timeoutSeconds: 60,
+        },
+      },
+    },
+  },
+}
+```
+
+### 工具参数
+
+- `url`（必需，仅限 http/https）
+- `extractMode`（`markdown` | `text`）
+- `maxChars`（截断长页面）
+
+注意：
+
+- `web_fetch` 首先使用 Readability（主要内容提取），然后使用 Firecrawl（如果已配置）。如果两者都失败，工具返回错误。
+- Firecrawl 请求使用机器人规避模式并默认缓存结果。
+- `web_fetch` 默认发送类 Chrome 的 User-Agent 和 `Accept-Language`；如需要可覆盖 `userAgent`。
+- `web_fetch` 阻止私有/内部主机名并重新检查重定向（用 `maxRedirects` 限制）。
+- `web_fetch` 是尽力提取；某些网站需要浏览器工具。
+- 参见 [Firecrawl](/tools/firecrawl) 了解密钥设置和服务详情。
+- 响应会被缓存（默认 15 分钟）以减少重复获取。
+- 如果你使用工具配置文件/允许列表，添加 `web_search`/`web_fetch` 或 `group:web`。
+- 如果缺少 Brave 密钥，`web_search` 返回一个简短的设置提示和文档链接。