@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/tools/exec-approvals.md

@@ -0,0 +1,234 @@
+---
+read_when:
+  - 配置执行审批或允许列表
+  - 在 macOS 应用中实现执行审批用户体验
+  - 审查沙箱逃逸提示及其影响
+summary: 执行审批、允许列表和沙箱逃逸提示
+title: 执行审批
+x-i18n:
+  generated_at: "2026-02-03T08:19:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 97736427752eb905bb5d1f5b54bddbdea38eb5ac5824e2bf99258fcf44ee393c
+  source_path: tools/exec-approvals.md
+  workflow: 15
+---
+
+# 执行审批
+
+执行审批是**配套应用/节点主机的安全护栏**，用于允许沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。可以将其理解为安全联锁：只有当策略 + 允许列表 +（可选的）用户审批都同意时，命令才会被允许执行。
+执行审批是**附加于**工具策略和提权门控之上的（除非 elevated 设置为 `full`，这会跳过审批）。
+生效策略取 `tools.exec.*` 和审批默认值中**更严格**的一方；如果审批字段被省略，则使用 `tools.exec` 的值。
+
+如果配套应用 UI **不可用**，任何需要提示的请求都将由 **ask fallback**（默认：deny）决定。
+
+## 适用范围
+
+执行审批在执行主机上本地强制执行：
+
+- **gateway 主机** → gateway 机器上的 `quantumclaw` 进程
+- **node 主机** → 节点运行器（macOS 配套应用或无头节点主机）
+
+macOS 分工：
+
+- **node 主机服务**通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
+- **macOS 应用**执行审批并在 UI 上下文中执行命令。
+
+## 设置和存储
+
+审批信息存储在执行主机上的本地 JSON 文件中：
+
+`~/.quantumclaw/exec-approvals.json`
+
+示例结构：
+
+```json
+{
+  "version": 1,
+  "socket": {
+    "path": "~/.quantumclaw/exec-approvals.sock",
+    "token": "base64url-token"
+  },
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss",
+    "askFallback": "deny",
+    "autoAllowSkills": false
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "askFallback": "deny",
+      "autoAllowSkills": true,
+      "allowlist": [
+        {
+          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
+          "pattern": "~/Projects/**/bin/rg",
+          "lastUsedAt": 1737150000000,
+          "lastUsedCommand": "rg -n TODO",
+          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
+        }
+      ]
+    }
+  }
+}
+```
+
+## 策略选项
+
+### Security（`exec.security`）
+
+- **deny**：阻止所有主机执行请求。
+- **allowlist**：仅允许在允许列表中的命令。
+- **full**：允许所有命令（等同于提权模式）。
+
+### Ask（`exec.ask`）
+
+- **off**：从不提示。
+- **on-miss**：仅在允许列表未匹配时提示。
+- **always**：每次命令都提示。
+
+### Ask fallback（`askFallback`）
+
+如果需要提示但无法访问 UI，fallback 决定：
+
+- **deny**：阻止。
+- **allowlist**：仅在允许列表匹配时允许。
+- **full**：允许。
+
+## 允许列表（按智能体）
+
+允许列表是**按智能体**配置的。如果存在多个智能体，请在 macOS 应用中切换要编辑的智能体。模式匹配**不区分大小写**。
+模式应解析为**二进制路径**（仅包含基本名称的条目会被忽略）。
+旧版 `agents.default` 条目在加载时会迁移到 `agents.main`。
+
+示例：
+
+- `~/Projects/**/bin/bird`
+- `~/.local/bin/*`
+- `/opt/homebrew/bin/rg`
+
+每个允许列表条目会跟踪：
+
+- **id** 用于 UI 标识的稳定 UUID（可选）
+- **last used** 时间戳
+- **last used command**
+- **last resolved path**
+
+## 自动允许 skill CLI
+
+启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件在节点（macOS 节点或无头节点主机）上被视为已列入允许列表。这通过 Gateway RPC 的 `skills.bins` 获取 skill 二进制列表。如果你想要严格的手动允许列表，请禁用此选项。
+
+## 安全二进制（仅限标准输入）
+
+`tools.exec.safeBins` 定义了一小组**仅限标准输入**的二进制文件（例如 `jq`），这些文件可以在允许列表模式下运行，**无需**显式的允许列表条目。安全二进制会拒绝位置文件参数和类路径标记，因此它们只能操作传入的流。
+在允许列表模式下，shell 链式命令和重定向不会被自动允许。
+
+当每个顶级段都满足允许列表（包括安全二进制或 skill 自动允许）时，允许 shell 链式命令（`&&`、`||`、`;`）。重定向在允许列表模式下仍不受支持。
+命令替换（`$()` / 反引号）在允许列表解析期间会被拒绝，包括在双引号内；如果你需要字面的 `$()` 文本，请使用单引号。
+
+默认安全二进制：`jq`、`grep`、`cut`、`sort`、`uniq`、`head`、`tail`、`tr`、`wc`。
+
+## Control UI 编辑
+
+使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的覆盖设置和允许列表。选择一个作用域（Defaults 或某个智能体），调整策略，添加/删除允许列表模式，然后点击 **Save**。UI 会显示每个模式的 **last used** 元数据，以便你保持列表整洁。
+
+目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点必须通告 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
+如果节点尚未通告执行审批，请直接编辑其本地的 `~/.quantumclaw/exec-approvals.json`。
+
+CLI：`quantumclaw approvals` 支持 gateway 或 node 编辑（参见 [Approvals CLI](/cli/approvals)）。
+
+## 审批流程
+
+当需要提示时，gateway 向操作员客户端广播 `exec.approval.requested`。
+Control UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 gateway 将已批准的请求转发给节点主机。
+
+当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 来关联后续的系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决定，请求将被视为审批超时，并作为拒绝原因显示。
+
+确认对话框包括：
+
+- 命令 + 参数
+- cwd
+- 智能体 id
+- 解析后的可执行文件路径
+- 主机 + 策略元数据
+
+操作：
+
+- **Allow once** → 立即运行
+- **Always allow** → 添加到允许列表 + 运行
+- **Deny** → 阻止
+
+## 审批转发到聊天渠道
+
+你可以将执行审批提示转发到任何聊天渠道（包括插件渠道），并使用 `/approve` 进行批准。这使用正常的出站投递管道。
+
+配置：
+
+```json5
+{
+  approvals: {
+    exec: {
+      enabled: true,
+      mode: "session", // "session" | "targets" | "both"
+      agentFilter: ["main"],
+      sessionFilter: ["discord"], // substring or regex
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" },
+      ],
+    },
+  },
+}
+```
+
+在聊天中回复：
+
+```
+/approve <id> allow-once
+/approve <id> allow-always
+/approve <id> deny
+```
+
+### macOS IPC 流程
+
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + approvals + system.run)
+```
+
+安全注意事项：
+
+- Unix socket 模式 `0600`，token 存储在 `exec-approvals.json` 中。
+- 同 UID 对端检查。
+- 挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
+
+## 系统事件
+
+执行生命周期以系统消息的形式呈现：
+
+- `Exec running`（仅当命令超过运行通知阈值时）
+- `Exec finished`
+- `Exec denied`
+
+这些消息在节点报告事件后发布到智能体的会话中。
+Gateway 主机执行审批在命令完成时（以及可选地在运行时间超过阈值时）发出相同的生命周期事件。
+经过审批门控的执行会复用审批 id 作为这些消息中的 `runId`，以便于关联。
+
+## 影响
+
+- **full** 权限很大；尽可能优先使用允许列表。
+- **ask** 让你保持知情，同时仍允许快速审批。
+- 按智能体的允许列表可防止一个智能体的审批泄漏到其他智能体。
+- 审批仅适用于来自**授权发送者**的主机执行请求。未授权的发送者无法发出 `/exec`。
+- `/exec security=full` 是为授权操作员提供的会话级便利功能，设计上会跳过审批。
+  要完全阻止主机执行，请将审批 security 设置为 `deny`，或通过工具策略拒绝 `exec` 工具。
+
+相关内容：
+
+- [Exec 工具](/tools/exec)
+- [提权模式](/tools/elevated)
+- [Skills](/tools/skills)

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

@@ -0,0 +1,169 @@
+---
+read_when:
+  - 使用或修改 exec 工具
+  - 调试 stdin 或 TTY 行为
+summary: Exec 工具用法、stdin 模式和 TTY 支持
+title: Exec 工具
+x-i18n:
+  generated_at: "2026-02-03T09:26:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3b32238dd8dce93d4f24100eaa521ce9f8485eff6d8498e2680ce9ed6045d25f
+  source_path: tools/exec.md
+  workflow: 15
+---
+
+# Exec 工具
+
+在工作区中运行 shell 命令。通过 `process` 支持前台和后台执行。
+如果 `process` 被禁用，`exec` 将同步运行并忽略 `yieldMs`/`background`。
+后台会话按智能体隔离；`process` 只能看到同一智能体的会话。
+
+## 参数
+
+- `command`（必填）
+- `workdir`（默认为当前工作目录）
+- `env`（键值对覆盖）
+- `yieldMs`（默认 10000）：延迟后自动转入后台
+- `background`（布尔值）：立即转入后台
+- `timeout`（秒，默认 1800）：超时后终止
+- `pty`（布尔值）：在可用时使用伪终端运行（仅限 TTY 的 CLI、编程智能体、终端 UI）
+- `host`（`sandbox | gateway | node`）：执行位置
+- `security`（`deny | allowlist | full`）：`gateway`/`node` 的执行策略
+- `ask`（`off | on-miss | always`）：`gateway`/`node` 的审批提示
+- `node`（字符串）：`host=node` 时的节点 id/名称
+- `elevated`（布尔值）：请求提升模式（gateway 主机）；仅当 elevated 解析为 `full` 时才强制 `security=full`
+
+注意事项：
+
+- `host` 默认为 `sandbox`。
+- 当沙箱隔离关闭时，`elevated` 会被忽略（exec 已在主机上运行）。
+- `gateway`/`node` 审批由 `~/.quantumclaw/exec-approvals.json` 控制。
+- `node` 需要已配对的节点（配套应用或无头节点主机）。
+- 如果有多个可用节点，设置 `exec.node` 或 `tools.exec.node` 来选择一个。
+- 在非 Windows 主机上，exec 会使用已设置的 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免 fish 不兼容的脚本，如果两者都不存在则回退到 `SHELL`。
+- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或代码注入。
+- 重要提示：沙箱隔离**默认关闭**。如果沙箱隔离关闭，`host=sandbox` 将直接在 Gateway 网关主机上运行（无容器）且**不需要审批**。如需审批，请使用 `host=gateway` 运行并配置 exec 审批（或启用沙箱隔离）。
+
+## 配置
+
+- `tools.exec.notifyOnExit`（默认：true）：为 true 时，后台 exec 会话在退出时会入队系统事件并请求心跳。
+- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过此值时发出单次"运行中"通知（0 表示禁用）。
+- `tools.exec.host`（默认：`sandbox`）
+- `tools.exec.security`（默认：sandbox 为 `deny`，gateway + node 未设置时为 `allowlist`）
+- `tools.exec.ask`（默认：`on-miss`）
+- `tools.exec.node`（默认：未设置）
+- `tools.exec.pathPrepend`：exec 运行时添加到 `PATH` 前面的目录列表。
+- `tools.exec.safeBins`：仅限 stdin 的安全二进制文件，无需显式白名单条目即可运行。
+
+示例：
+
+```json5
+{
+  tools: {
+    exec: {
+      pathPrepend: ["~/bin", "/opt/oss/bin"],
+    },
+  },
+}
+```
+
+### PATH 处理
+
+- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。主机执行时会拒绝 `env.PATH` 覆盖。守护进程本身仍使用最小 `PATH` 运行：
+  - macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
+  - Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
+- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。QuantumClaw 在 profile 加载后通过内部环境变量将 `env.PATH` 添加到前面（无 shell 插值）；`tools.exec.pathPrepend` 在此也适用。
+- `host=node`：只有你传递的未被阻止的 env 覆盖会发送到节点。主机执行时会拒绝 `env.PATH` 覆盖。无头节点主机仅在 `PATH` 添加到节点主机 PATH 前面时才接受（不允许替换）。macOS 节点完全丢弃 `PATH` 覆盖。
+
+按智能体绑定节点（在配置中使用智能体列表索引）：
+
+```bash
+quantumclaw config get agents.list
+quantumclaw config set agents.list[0].tools.exec.node "node-id-or-name"
+```
+
+控制 UI：Nodes 标签页包含一个小的"Exec 节点绑定"面板用于相同的设置。
+
+## 会话覆盖（`/exec`）
+
+使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**每会话**默认值。
+不带参数发送 `/exec` 可显示当前值。
+
+示例：
+
+```
+/exec host=gateway security=allowlist ask=on-miss node=mac-1
+```
+
+## 授权模型
+
+`/exec` 仅对**已授权发送者**（渠道白名单/配对加 `commands.useAccessGroups`）生效。
+它仅更新**会话状态**，不写入配置。要彻底禁用 exec，请通过工具策略拒绝它（`tools.deny: ["exec"]` 或按智能体配置）。除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。
+
+## Exec 审批（配套应用/节点主机）
+
+沙箱隔离的智能体可以要求在 `exec` 于 Gateway 网关或节点主机上运行前进行逐请求审批。
+参阅 [Exec 审批](/tools/exec-approvals) 了解策略、白名单和 UI 流程。
+
+当需要审批时，exec 工具会立即返回 `status: "approval-pending"` 和审批 id。一旦被批准（或拒绝/超时），Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 `tools.exec.approvalRunningNoticeMs` 之后仍在运行，会发出单次 `Exec running` 通知。
+
+## 白名单 + 安全二进制文件
+
+白名单执行仅匹配**解析后的二进制路径**（不匹配基本名称）。当 `security=allowlist` 时，仅当每个管道段都在白名单中或是安全二进制文件时，shell 命令才会自动允许。在白名单模式下，链式命令（`;`、`&&`、`||`）和重定向会被拒绝。
+
+## 示例
+
+前台：
+
+```json
+{ "tool": "exec", "command": "ls -la" }
+```
+
+后台 + 轮询：
+
+```json
+{"tool":"exec","command":"npm run build","yieldMs":1000}
+{"tool":"process","action":"poll","sessionId":"<id>"}
+```
+
+发送按键（tmux 风格）：
+
+```json
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
+{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
+```
+
+提交（仅发送 CR）：
+
+```json
+{ "tool": "process", "action": "submit", "sessionId": "<id>" }
+```
+
+粘贴（默认带括号）：
+
+```json
+{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
+```
+
+## apply_patch（实验性）
+
+`apply_patch` 是 `exec` 的子工具，用于结构化多文件编辑。
+需显式启用：
+
+```json5
+{
+  tools: {
+    exec: {
+      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
+    },
+  },
+}
+```
+
+注意事项：
+
+- 仅适用于 OpenAI/OpenAI Codex 模型。
+- 工具策略仍然适用；`allow: ["exec"]` 隐式允许 `apply_patch`。
+- 配置位于 `tools.exec.applyPatch` 下。

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

@@ -0,0 +1,68 @@
+---
+read_when:
+  - 你想要 Firecrawl 支持的网页提取
+  - 你需要 Firecrawl API 密钥
+  - 你想要 web_fetch 的反机器人提取
+summary: 用于 web_fetch 的 Firecrawl 回退（反机器人 + 缓存提取）
+title: Firecrawl
+x-i18n:
+  generated_at: "2026-02-03T10:10:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 08a7ad45b41af41204e44d2b0be0f980b7184d80d2fa3977339e42a47beb2851
+  source_path: tools/firecrawl.md
+  workflow: 15
+---
+
+# Firecrawl
+
+QuantumClaw 可以使用 **Firecrawl** 作为 `web_fetch` 的回退提取器。它是一个托管的
+内容提取服务，支持机器人规避和缓存，有助于处理
+JS 密集型网站或阻止普通 HTTP 请求的页面。
+
+## 获取 API 密钥
+
+1. 创建 Firecrawl 账户并生成 API 密钥。
+2. 将其存储在配置中或在 Gateway 网关环境中设置 `FIRECRAWL_API_KEY`。
+
+## 配置 Firecrawl
+
+```json5
+{
+  tools: {
+    web: {
+      fetch: {
+        firecrawl: {
+          apiKey: "FIRECRAWL_API_KEY_HERE",
+          baseUrl: "https://api.firecrawl.dev",
+          onlyMainContent: true,
+          maxAgeMs: 172800000,
+          timeoutSeconds: 60,
+        },
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- 当存在 API 密钥时，`firecrawl.enabled` 默认为 true。
+- `maxAgeMs` 控制缓存结果可以保留多久（毫秒）。默认为 2 天。
+
+## 隐身 / 机器人规避
+
+Firecrawl 提供了一个用于机器人规避的**代理模式**参数（`basic`、`stealth` 或 `auto`）。
+QuantumClaw 对 Firecrawl 请求始终使用 `proxy: "auto"` 加 `storeInCache: true`。
+如果省略 proxy，Firecrawl 默认使用 `auto`。`auto` 在基本尝试失败时会使用隐身代理重试，这可能比
+仅使用基本抓取消耗更多积分。
+
+## `web_fetch` 如何使用 Firecrawl
+
+`web_fetch` 提取顺序：
+
+1. Readability（本地）
+2. Firecrawl（如果已配置）
+3. 基本 HTML 清理（最后回退）
+
+参见 [Web 工具](/tools/web) 了解完整的 Web 工具设置。