@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/tools/chrome-extension.md

@@ -0,0 +1,183 @@
+---
+read_when:
+  - 你希望智能体驱动现有的 Chrome 标签页（工具栏按钮）
+  - 你需要通过 Tailscale 实现远程 Gateway 网关 + 本地浏览器自动化
+  - 你想了解浏览器接管的安全影响
+summary: Chrome 扩展：让 QuantumClaw 驱动你现有的 Chrome 标签页
+title: Chrome 扩展
+x-i18n:
+  generated_at: "2026-02-03T07:55:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3b77bdad7d3dab6adb76ff25b144412d6b54b915993b1c1f057f36dea149938b
+  source_path: tools/chrome-extension.md
+  workflow: 15
+---
+
+# Chrome 扩展（浏览器中继）
+
+QuantumClaw Chrome 扩展让智能体控制你**现有的 Chrome 标签页**（你的正常 Chrome 窗口），而不是启动一个单独的 quantumclaw 管理的 Chrome 配置文件。
+
+附加/分离通过一个**单独的 Chrome 工具栏按钮**实现。
+
+## 它是什么（概念）
+
+有三个部分：
+
+- **浏览器控制服务**（Gateway 网关或节点）：智能体/工具调用的 API（通过 Gateway 网关）
+- **本地中继服务器**（loopback CDP）：在控制服务器和扩展之间桥接（默认 `http://127.0.0.1:18792`）
+- **Chrome MV3 扩展**：使用 `chrome.debugger` 附加到活动标签页，并将 CDP 消息传送到中继
+
+然后 QuantumClaw 通过正常的 `browser` 工具界面控制附加的标签页（选择正确的配置文件）。
+
+## 安装/加载（未打包）
+
+1. 将扩展安装到稳定的本地路径：
+
+```bash
+quantumclaw browser extension install
+```
+
+2. 打印已安装扩展的目录路径：
+
+```bash
+quantumclaw browser extension path
+```
+
+3. Chrome → `chrome://extensions`
+
+- 启用"开发者模式"
+- "加载已解压的扩展程序" → 选择上面打印的目录
+
+4. 固定扩展。
+
+## 更新（无构建步骤）
+
+扩展作为静态文件包含在 QuantumClaw 发布版（npm 包）中。没有单独的"构建"步骤。
+
+升级 QuantumClaw 后：
+
+- 重新运行 `quantumclaw browser extension install` 以刷新 QuantumClaw 状态目录下的已安装文件。
+- Chrome → `chrome://extensions` → 点击扩展上的"重新加载"。
+
+## 使用它（无需额外配置）
+
+QuantumClaw 附带一个名为 `chrome` 的内置浏览器配置文件，它指向默认端口上的扩展中继。
+
+使用它：
+
+- CLI：`quantumclaw browser --browser-profile chrome tabs`
+- 智能体工具：`browser` 配合 `profile="chrome"`
+
+如果你想要不同的名称或不同的中继端口，创建你自己的配置文件：
+
+```bash
+quantumclaw browser create-profile \
+  --name my-chrome \
+  --driver extension \
+  --cdp-url http://127.0.0.1:18792 \
+  --color "#00AA00"
+```
+
+## 附加/分离（工具栏按钮）
+
+- 打开你希望 QuantumClaw 控制的标签页。
+- 点击扩展图标。
+  - 附加时徽章显示 `ON`。
+- 再次点击以分离。
+
+## 它控制哪个标签页？
+
+- 它**不会**自动控制"你正在查看的任何标签页"。
+- 它**仅**控制你通过点击工具栏按钮**明确附加的标签页**。
+- 要切换：打开另一个标签页并在那里点击扩展图标。
+
+## 徽章 + 常见错误
+
+- `ON`：已附加；QuantumClaw 可以驱动该标签页。
+- `…`：正在连接到本地中继。
+- `!`：中继不可达（最常见：浏览器中继服务器未在此机器上运行）。
+
+如果你看到 `!`：
+
+- 确保 Gateway 网关在本地运行（默认设置），或者如果 Gateway 网关在其他地方运行，在此机器上运行一个节点主机。
+- 打开扩展选项页面；它会显示中继是否可达。
+
+## 远程 Gateway 网关（使用节点主机）
+
+### 本地 Gateway 网关（与 Chrome 在同一台机器上）——通常**无需额外步骤**
+
+如果 Gateway 网关运行在与 Chrome 相同的机器上，它会在 loopback 上启动浏览器控制服务并自动启动中继服务器。扩展与本地中继通信；CLI/工具调用发送到 Gateway 网关。
+
+### 远程 Gateway 网关（Gateway 网关运行在其他地方）——**运行节点主机**
+
+如果你的 Gateway 网关运行在另一台机器上，在运行 Chrome 的机器上启动一个节点主机。Gateway 网关将把浏览器操作代理到该节点；扩展 + 中继保持在浏览器机器本地。
+
+如果连接了多个节点，使用 `gateway.nodes.browser.node` 固定一个或设置 `gateway.nodes.browser.mode`。
+
+## 沙箱隔离（工具容器）
+
+如果你的智能体会话在沙箱中（`agents.defaults.sandbox.mode != "off"`），`browser` 工具可能受到限制：
+
+- 默认情况下，沙箱隔离的会话通常指向**沙箱浏览器**（`target="sandbox"`），而不是你的主机 Chrome。
+- Chrome 扩展中继接管需要控制**主机**浏览器控制服务器。
+
+选项：
+
+- 最简单：从**非沙箱隔离**的会话/智能体使用扩展。
+- 或者为沙箱隔离的会话允许主机浏览器控制：
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+然后确保工具未被工具策略拒绝，并（如果需要）以 `target="host"` 调用 `browser`。
+
+调试：`quantumclaw sandbox explain`
+
+## 远程访问提示
+
+- 将 Gateway 网关和节点主机保持在同一个 tailnet 上；避免将中继端口暴露到 LAN 或公共 Internet。
+- 有意配对节点；如果你不想要远程控制，禁用浏览器代理路由（`gateway.nodes.browser.mode="off"`）。
+
+## "extension path"的工作原理
+
+`quantumclaw browser extension path` 打印包含扩展文件的**已安装**磁盘目录。
+
+CLI 有意**不**打印 `node_modules` 路径。始终先运行 `quantumclaw browser extension install` 将扩展复制到 QuantumClaw 状态目录下的稳定位置。
+
+如果你移动或删除该安装目录，Chrome 将把扩展标记为损坏，直到你从有效路径重新加载它。
+
+## 安全影响（请阅读此内容）
+
+这是强大且有风险的。将其视为给模型"在你的浏览器上动手"。
+
+- 扩展使用 Chrome 的调试器 API（`chrome.debugger`）。附加时，模型可以：
+  - 在该标签页中点击/输入/导航
+  - 读取页面内容
+  - 访问标签页已登录会话可以访问的任何内容
+- **这不像**专用的 quantumclaw 管理配置文件那样隔离。
+  - 如果你附加到你的日常使用配置文件/标签页，你就是在授予对该账户状态的访问权限。
+
+建议：
+
+- 对于扩展中继使用，优先使用专用的 Chrome 配置文件（与你的个人浏览分开）。
+- 将 Gateway 网关和任何节点主机保持在仅限 tailnet；依赖 Gateway 网关身份验证 + 节点配对。
+- 避免通过 LAN（`0.0.0.0`）暴露中继端口，避免使用 Funnel（公开）。
+- 中继阻止非扩展来源，并要求 CDP 客户端提供内部身份验证令牌。
+
+相关：
+
+- 浏览器工具概述：[浏览器](/tools/browser)
+- 安全审计：[安全](/gateway/security)
+- Tailscale 设置：[Tailscale](/gateway/tailscale)

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

@@ -0,0 +1,209 @@
+---
+read_when:
+  - 向新用户介绍 ClawHub
+  - 安装、搜索或发布 Skills
+  - 说明 ClawHub CLI 标志和同步行为
+summary: ClawHub 指南：公共 Skills 注册中心 + CLI 工作流
+title: ClawHub
+x-i18n:
+  generated_at: "2026-02-01T21:42:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8b7f8fab80a34e409f37fa130a49ff5b487966755a7b0d214dfebf5207c7124c
+  source_path: tools/clawhub.md
+  workflow: 15
+---
+
+# ClawHub
+
+ClawHub 是 **QuantumClaw 的公共 Skills 注册中心**。它是一项免费服务：所有 Skills 都是公开的、开放的，所有人都可以查看、共享和复用。Skills 就是一个包含 `SKILL.md` 文件（以及辅助文本文件）的文件夹。你可以在网页应用中浏览 Skills，也可以使用 CLI 来搜索、安装、更新和发布 Skills。
+
+网站：[clawhub.com](https://clawhub.com)
+
+## 适用人群（新手友好）
+
+如果你想为 QuantumClaw 智能体添加新功能，ClawHub 是查找和安装 Skills 的最简单方式。你不需要了解后端的工作原理。你可以：
+
+- 使用自然语言搜索 Skills。
+- 将 Skills 安装到你的工作区。
+- 之后使用一条命令更新 Skills。
+- 通过发布 Skills 来备份你自己的 Skills。
+
+## 快速入门（非技术人员）
+
+1. 安装 CLI（参见下一节）。
+2. 搜索你需要的内容：
+   - `clawhub search "calendar"`
+3. 安装一个 Skills：
+   - `clawhub install <skill-slug>`
+4. 启动一个新的 QuantumClaw 会话，以加载新 Skills。
+
+## 安装 CLI
+
+任选其一：
+
+```bash
+npm i -g clawhub
+```
+
+```bash
+pnpm add -g clawhub
+```
+
+## 在 QuantumClaw 中的定位
+
+默认情况下，CLI 会将 Skills 安装到当前工作目录下的 `./skills`。如果已配置 QuantumClaw 工作区，`clawhub` 会回退到该工作区，除非你通过 `--workdir`（或 `CLAWHUB_WORKDIR`）进行覆盖。QuantumClaw 从 `<workspace>/skills` 加载工作区 Skills，并会在**下一个**会话中生效。如果你已经在使用 `~/.quantumclaw/skills` 或内置 Skills，工作区 Skills 优先级更高。
+
+有关 Skills 加载、共享和权限控制的更多详情，请参阅
+[Skills](/tools/skills)。
+
+## 服务功能
+
+- **公开浏览**Skills 及其 `SKILL.md` 内容。
+- 基于嵌入向量（向量搜索）的**搜索**，而不仅仅是关键词匹配。
+- 支持语义化版本号、变更日志和标签（包括 `latest`）的**版本管理**。
+- 每个版本以 zip 格式**下载**。
+- **星标和评论**，支持社区反馈。
+- **审核**钩子，用于审批和审计。
+- **CLI 友好的 API**，支持自动化和脚本编写。
+
+## CLI 命令和参数
+
+全局选项（适用于所有命令）：
+
+- `--workdir <dir>`：工作目录（默认：当前目录；回退到 QuantumClaw 工作区）。
+- `--dir <dir>`：Skills 目录，相对于工作目录（默认：`skills`）。
+- `--site <url>`：网站基础 URL（浏览器登录）。
+- `--registry <url>`：注册中心 API 基础 URL。
+- `--no-input`：禁用提示（非交互模式）。
+- `-V, --cli-version`：打印 CLI 版本。
+
+认证：
+
+- `clawhub login`（浏览器流程）或 `clawhub login --token <token>`
+- `clawhub logout`
+- `clawhub whoami`
+
+选项：
+
+- `--token <token>`：粘贴 API 令牌。
+- `--label <label>`：为浏览器登录令牌存储的标签（默认：`CLI token`）。
+- `--no-browser`：不打开浏览器（需要 `--token`）。
+
+搜索：
+
+- `clawhub search "query"`
+- `--limit <n>`：最大结果数。
+
+安装：
+
+- `clawhub install <slug>`
+- `--version <version>`：安装指定版本。
+- `--force`：如果文件夹已存在则覆盖。
+
+更新：
+
+- `clawhub update <slug>`
+- `clawhub update --all`
+- `--version <version>`：更新到指定版本（仅限单个 slug）。
+- `--force`：当本地文件与任何已发布版本不匹配时强制覆盖。
+
+列表：
+
+- `clawhub list`（读取 `.clawhub/lock.json`）
+
+发布：
+
+- `clawhub publish <path>`
+- `--slug <slug>`：Skills 标识符。
+- `--name <name>`：显示名称。
+- `--version <version>`：语义化版本号。
+- `--changelog <text>`：变更日志文本（可以为空）。
+- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
+
+删除/恢复（仅所有者/管理员）：
+
+- `clawhub delete <slug> --yes`
+- `clawhub undelete <slug> --yes`
+
+同步（扫描本地 Skills + 发布新增/更新的 Skills）：
+
+- `clawhub sync`
+- `--root <dir...>`：额外的扫描根目录。
+- `--all`：无提示上传所有内容。
+- `--dry-run`：显示将要上传的内容。
+- `--bump <type>`：更新的版本号递增类型 `patch|minor|major`（默认：`patch`）。
+- `--changelog <text>`：非交互更新的变更日志。
+- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
+- `--concurrency <n>`：注册中心检查并发数（默认：4）。
+
+## 智能体常用工作流
+
+### 搜索 Skills
+
+```bash
+clawhub search "postgres backups"
+```
+
+### 下载新 Skills
+
+```bash
+clawhub install my-skill-pack
+```
+
+### 更新已安装的 Skills
+
+```bash
+clawhub update --all
+```
+
+### 备份你的 Skills（发布或同步）
+
+对于单个 Skills 文件夹：
+
+```bash
+clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
+```
+
+一次扫描并备份多个 Skills：
+
+```bash
+clawhub sync --all
+```
+
+## 高级详情（技术性）
+
+### 版本管理和标签
+
+- 每次发布都会创建一个新的**语义化版本** `SkillVersion`。
+- 标签（如 `latest`）指向某个版本；移动标签可以实现回滚。
+- 变更日志附加在每个版本上，在同步或发布更新时可以为空。
+
+### 本地更改与注册中心版本
+
+更新时会使用内容哈希将本地 Skills 内容与注册中心版本进行比较。如果本地文件与任何已发布版本不匹配，CLI 会在覆盖前询问确认（或在非交互模式下需要 `--force`）。
+
+### 同步扫描和回退根目录
+
+`clawhub sync` 首先扫描当前工作目录。如果未找到 Skills，它会回退到已知的旧版位置（例如 `~/quantumclaw/skills` 和 `~/.quantumclaw/skills`）。这样设计是为了在不需要额外标志的情况下找到旧版 Skills 安装。
+
+### 存储和锁文件
+
+- 已安装的 Skills 记录在工作目录下的 `.clawhub/lock.json` 中。
+- 认证令牌存储在 ClawHub CLI 配置文件中（可通过 `CLAWHUB_CONFIG_PATH` 覆盖）。
+
+### 遥测（安装计数）
+
+当你在登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照用于计算安装次数。你可以完全禁用此功能：
+
+```bash
+export CLAWHUB_DISABLE_TELEMETRY=1
+```
+
+## 环境变量
+
+- `CLAWHUB_SITE`：覆盖网站 URL。
+- `CLAWHUB_REGISTRY`：覆盖注册中心 API URL。
+- `CLAWHUB_CONFIG_PATH`：覆盖 CLI 存储令牌/配置的位置。
+- `CLAWHUB_WORKDIR`：覆盖默认工作目录。
+- `CLAWHUB_DISABLE_TELEMETRY=1`：禁用 `sync` 的遥测功能。

package/docs/zh-CN/tools/creating-skills.md

@@ -0,0 +1,61 @@
+---
+title: 创建 Skills
+x-i18n:
+  generated_at: "2026-02-03T10:10:19Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ad801da34fe361ffa584ded47f775d1c104a471a3f7b7f930652255e98945c3a
+  source_path: tools/creating-skills.md
+  workflow: 15
+---
+
+# 创建自定义 Skills 🛠
+
+QuantumClaw 被设计为易于扩展。"Skills"是为你的助手添加新功能的主要方式。
+
+## 什么是 Skill？
+
+Skill 是一个包含 `SKILL.md` 文件（为 LLM 提供指令和工具定义）的目录，可选包含一些脚本或资源。
+
+## 分步指南：你的第一个 Skill
+
+### 1. 创建目录
+
+Skills 位于你的工作区中，通常是 `~/.quantumclaw/workspace/skills/`。为你的 Skill 创建一个新文件夹：
+
+```bash
+mkdir -p ~/.quantumclaw/workspace/skills/hello-world
+```
+
+### 2. 定义 `SKILL.md`
+
+在该目录中创建一个 `SKILL.md` 文件。此文件使用 YAML frontmatter 作为元数据，使用 Markdown 作为指令。
+
+```markdown
+---
+name: hello_world
+description: A simple skill that says hello.
+---
+
+# Hello World Skill
+
+When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
+```
+
+### 3. 添加工具（可选）
+
+你可以在 frontmatter 中定义自定义工具，或指示智能体使用现有的系统工具（如 `bash` 或 `browser`）。
+
+### 4. 刷新 QuantumClaw
+
+让你的智能体"刷新 skills"或重启 Gateway 网关。QuantumClaw 将发现新目录并索引 `SKILL.md`。
+
+## 最佳实践
+
+- **简洁明了**：指示模型*做什么*，而不是如何成为一个 AI。
+- **安全第一**：如果你的 Skill 使用 `bash`，确保提示词不允许来自不受信任用户输入的任意命令注入。
+- **本地测试**：使用 `quantumclaw agent --message "use my new skill"` 进行测试。
+
+## 共享 Skills
+
+你也可以在 [ClawHub](https://clawhub.com) 上浏览和贡献 Skills。

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

@@ -0,0 +1,64 @@
+---
+read_when:
+  - 调整提升模式默认值、允许列表或斜杠命令行为
+summary: 提升的 exec 模式和 /elevated 指令
+title: 提升模式
+x-i18n:
+  generated_at: "2026-02-03T07:55:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 83767a01609304026d145feb0aa0b0533e8cf8b16cd200f724d9e3e8cf2920c3
+  source_path: tools/elevated.md
+  workflow: 15
+---
+
+# 提升模式（/elevated 指令）
+
+## 功能说明
+
+- `/elevated on` 在 Gateway 网关主机上运行并保留 exec 审批（与 `/elevated ask` 相同）。
+- `/elevated full` 在 Gateway 网关主机上运行**并**自动批准 exec（跳过 exec 审批）。
+- `/elevated ask` 在 Gateway 网关主机上运行但保留 exec 审批（与 `/elevated on` 相同）。
+- `on`/`ask` **不会**强制 `exec.security=full`；配置的安全/询问策略仍然适用。
+- 仅在智能体被**沙箱隔离**时改变行为（否则 exec 已经在主机上运行）。
+- 指令形式：`/elevated on|off|ask|full`、`/elev on|off|ask|full`。
+- 仅接受 `on|off|ask|full`；其他任何内容返回提示且不改变状态。
+
+## 它控制什么（以及不控制什么）
+
+- **可用性门控**：`tools.elevated` 是全局基线。`agents.list[].tools.elevated` 可以进一步限制每个智能体的提升（两者都必须允许）。
+- **每会话状态**：`/elevated on|off|ask|full` 为当前会话键设置提升级别。
+- **内联指令**：消息内的 `/elevated on|ask|full` 仅适用于该消息。
+- **群组**：在群聊中，仅当智能体被提及时才遵守提升指令。绕过提及要求的纯命令消息被视为已提及。
+- **主机执行**：elevated 强制 `exec` 到 Gateway 网关主机；`full` 还设置 `security=full`。
+- **审批**：`full` 跳过 exec 审批；`on`/`ask` 在允许列表/询问规则要求时遵守审批。
+- **非沙箱隔离智能体**：对位置无影响；仅影响门控、日志和状态。
+- **工具策略仍然适用**：如果 `exec` 被工具策略拒绝，则无法使用 elevated。
+- **与 `/exec` 分开**：`/exec` 为授权发送者调整每会话默认值，不需要 elevated。
+
+## 解析顺序
+
+1. 消息上的内联指令（仅适用于该消息）。
+2. 会话覆盖（通过发送仅含指令的消息设置）。
+3. 全局默认值（配置中的 `agents.defaults.elevatedDefault`）。
+
+## 设置会话默认值
+
+- 发送一条**仅**包含指令的消息（允许空白），例如 `/elevated full`。
+- 发送确认回复（`Elevated mode set to full...` / `Elevated mode disabled.`）。
+- 如果 elevated 访问被禁用或发送者不在批准的允许列表中，指令会回复一个可操作的错误且不改变会话状态。
+- 发送不带参数的 `/elevated`（或 `/elevated:`）以查看当前的 elevated 级别。
+
+## 可用性 + 允许列表
+
+- 功能门控：`tools.elevated.enabled`（即使代码支持，也可以通过配置将默认值设为关闭）。
+- 发送者允许列表：`tools.elevated.allowFrom`，带有每提供商允许列表（例如 `discord`、`whatsapp`）。
+- 每智能体门控：`agents.list[].tools.elevated.enabled`（可选；只能进一步限制）。
+- 每智能体允许列表：`agents.list[].tools.elevated.allowFrom`（可选；设置时，发送者必须同时匹配全局 + 每智能体允许列表）。
+- Discord 回退：如果省略 `tools.elevated.allowFrom.discord`，则使用 `channels.discord.dm.allowFrom` 列表作为回退。设置 `tools.elevated.allowFrom.discord`（即使是 `[]`）以覆盖。每智能体允许列表**不**使用回退。
+- 所有门控都必须通过；否则 elevated 被视为不可用。
+
+## 日志 + 状态
+
+- Elevated exec 调用以 info 级别记录。
+- 会话状态包括 elevated 模式（例如 `elevated=ask`、`elevated=full`）。