@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/plugins/agent-tools.md

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 你想在插件中添加新的智能体工具
+  - 你需要通过允许列表使工具可选启用
+summary: 在插件中编写智能体工具（模式、可选工具、允许列表）
+title: 插件智能体工具
+x-i18n:
+  generated_at: "2026-02-03T07:53:22Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4479462e9d8b17b664bf6b5f424f2efc8e7bedeaabfdb6a93126e051e635c659
+  source_path: plugins/agent-tools.md
+  workflow: 15
+---
+
+# 插件智能体工具
+
+QuantumClaw 插件可以注册**智能体工具**（JSON 模式函数），这些工具在智能体运行期间暴露给 LLM。工具可以是**必需的**（始终可用）或**可选的**（选择启用）。
+
+智能体工具在主配置的 `tools` 下配置，或在每个智能体的 `agents.list[].tools` 下配置。允许列表/拒绝列表策略控制智能体可以调用哪些工具。
+
+## 基本工具
+
+```ts
+import { Type } from "@sinclair/typebox";
+
+export default function (api) {
+  api.registerTool({
+    name: "my_tool",
+    description: "Do a thing",
+    parameters: Type.Object({
+      input: Type.String(),
+    }),
+    async execute(_id, params) {
+      return { content: [{ type: "text", text: params.input }] };
+    },
+  });
+}
+```
+
+## 可选工具（选择启用）
+
+可选工具**永远不会**自动启用。用户必须将它们添加到智能体允许列表中。
+
+```ts
+export default function (api) {
+  api.registerTool(
+    {
+      name: "workflow_tool",
+      description: "Run a local workflow",
+      parameters: {
+        type: "object",
+        properties: {
+          pipeline: { type: "string" },
+        },
+        required: ["pipeline"],
+      },
+      async execute(_id, params) {
+        return { content: [{ type: "text", text: params.pipeline }] };
+      },
+    },
+    { optional: true },
+  );
+}
+```
+
+在 `agents.list[].tools.allow`（或全局 `tools.allow`）中启用可选工具：
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        tools: {
+          allow: [
+            "workflow_tool", // 特定工具名称
+            "workflow", // 插件 id（启用该插件的所有工具）
+            "group:plugins", // 所有插件工具
+          ],
+        },
+      },
+    ],
+  },
+}
+```
+
+其他影响工具可用性的配置选项：
+
+- 仅包含插件工具名称的允许列表被视为插件选择启用；核心工具保持启用，除非你在允许列表中也包含核心工具或组。
+- `tools.profile` / `agents.list[].tools.profile`（基础允许列表）
+- `tools.byProvider` / `agents.list[].tools.byProvider`（特定提供商的允许/拒绝）
+- `tools.sandbox.tools.*`（沙箱隔离时的沙箱工具策略）
+
+## 规则 + 提示
+
+- 工具名称**不能**与核心工具名称冲突；冲突的工具会被跳过。
+- 允许列表中使用的插件 id 不能与核心工具名称冲突。
+- 对于触发副作用或需要额外二进制文件/凭证的工具，优先使用 `optional: true`。

package/docs/zh-CN/plugins/manifest.md

@@ -0,0 +1,68 @@
+---
+read_when:
+  - 你正在构建一个 QuantumClaw 插件
+  - 你需要提供插件配置 Schema 或调试插件验证错误
+summary: 插件清单及 JSON Schema 要求（严格配置验证）
+title: 插件清单
+x-i18n:
+  generated_at: "2026-02-01T21:34:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 47b3e33c915f47bdd172ae0316af7ef16ca831c317e3f1a7fdfcd67e3bd43f56
+  source_path: plugins/manifest.md
+  workflow: 15
+---
+
+# 插件清单（quantumclaw.plugin.json）
+
+每个插件都**必须**在**插件根目录**下提供一个 `quantumclaw.plugin.json` 文件。QuantumClaw 使用此清单来**在不执行插件代码的情况下**验证配置。缺失或无效的清单将被视为插件错误，并阻止配置验证。
+
+参阅完整的插件系统指南：[插件](/tools/plugin)。
+
+## 必填字段
+
+```json
+{
+  "id": "voice-call",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
+```
+
+必填键：
+
+- `id`（字符串）：插件的规范 id。
+- `configSchema`（对象）：插件配置的 JSON Schema（内联形式）。
+
+可选键：
+
+- `kind`（字符串）：插件类型（例如：`"memory"`）。
+- `channels`（数组）：此插件注册的渠道 id（例如：`["matrix"]`）。
+- `providers`（数组）：此插件注册的提供商 id。
+- `skills`（数组）：要加载的 Skills 目录（相对于插件根目录）。
+- `name`（字符串）：插件的显示名称。
+- `description`（字符串）：插件简短描述。
+- `uiHints`（对象）：用于 UI 渲染的配置字段标签/占位符/敏感标志。
+- `version`（字符串）：插件版本（仅供参考）。
+
+## JSON Schema 要求
+
+- **每个插件都必须提供 JSON Schema**，即使不接受任何配置也是如此。
+- 空 Schema 是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。
+- Schema 在配置读取/写入时进行验证，而非在运行时。
+
+## 验证行为
+
+- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已在插件清单中声明。
+- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
+- 如果插件已安装但清单或 Schema 损坏或缺失，验证将失败，Doctor 会报告插件错误。
+- 如果插件配置存在但插件已**禁用**，配置会被保留，并在 Doctor 和日志中显示**警告**。
+
+## 注意事项
+
+- 清单对**所有插件**都是必需的，包括从本地文件系统加载的插件。
+- 运行时仍然会单独加载插件模块；清单仅用于发现和验证。
+- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器允许列表要求（例如 pnpm 的 `allow-build-scripts` - `pnpm rebuild <package>`）。

package/docs/zh-CN/plugins/voice-call.md

@@ -0,0 +1,250 @@
+---
+read_when:
+  - 你想从 QuantumClaw 发起出站语音通话
+  - 你正在配置或开发 voice-call 插件
+summary: Voice Call 插件：通过 Twilio/Telnyx/Plivo 进行出站 + 入站通话（插件安装 + 配置 + CLI）
+title: Voice Call 插件
+x-i18n:
+  generated_at: "2026-02-03T07:53:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d731c63bf52781cc49262db550d0507d7fc33e5e7ce5d87efaf5d44aedcafef7
+  source_path: plugins/voice-call.md
+  workflow: 15
+---
+
+# Voice Call（插件）
+
+通过插件为 QuantumClaw 提供语音通话。支持出站通知和带有入站策略的多轮对话。
+
+当前提供商：
+
+- `twilio`（Programmable Voice + Media Streams）
+- `telnyx`（Call Control v2）
+- `plivo`（Voice API + XML transfer + GetInput speech）
+- `mock`（开发/无网络）
+
+快速心智模型：
+
+- 安装插件
+- 重启 Gateway 网关
+- 在 `plugins.entries.voice-call.config` 下配置
+- 使用 `quantumclaw voicecall ...` 或 `voice_call` 工具
+
+## 运行位置（本地 vs 远程）
+
+Voice Call 插件运行在 **Gateway 网关进程内部**。
+
+如果你使用远程 Gateway 网关，在**运行 Gateway 网关的机器**上安装/配置插件，然后重启 Gateway 网关以加载它。
+
+## 安装
+
+### 选项 A：从 npm 安装（推荐）
+
+```bash
+quantumclaw plugins install @quantumclaw/voice-call
+```
+
+之后重启 Gateway 网关。
+
+### 选项 B：从本地文件夹安装（开发，不复制）
+
+```bash
+quantumclaw plugins install ./extensions/voice-call
+cd ./extensions/voice-call && pnpm install
+```
+
+之后重启 Gateway 网关。
+
+## 配置
+
+在 `plugins.entries.voice-call.config` 下设置配置：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        enabled: true,
+        config: {
+          provider: "twilio", // 或 "telnyx" | "plivo" | "mock"
+          fromNumber: "+15550001234",
+          toNumber: "+15550005678",
+
+          twilio: {
+            accountSid: "ACxxxxxxxx",
+            authToken: "...",
+          },
+
+          plivo: {
+            authId: "MAxxxxxxxxxxxxxxxxxxxx",
+            authToken: "...",
+          },
+
+          // Webhook 服务器
+          serve: {
+            port: 3334,
+            path: "/voice/webhook",
+          },
+
+          // 公开暴露（选一个）
+          // publicUrl: "https://example.ngrok.app/voice/webhook",
+          // tunnel: { provider: "ngrok" },
+          // tailscale: { mode: "funnel", path: "/voice/webhook" }
+
+          outbound: {
+            defaultMode: "notify", // notify | conversation
+          },
+
+          streaming: {
+            enabled: true,
+            streamPath: "/voice/stream",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- Twilio/Telnyx 需要**可公开访问**的 webhook URL。
+- Plivo 需要**可公开访问**的 webhook URL。
+- `mock` 是本地开发提供商（无网络调用）。
+- `skipSignatureVerification` 仅用于本地测试。
+- 如果你使用 ngrok 免费版，将 `publicUrl` 设置为确切的 ngrok URL；签名验证始终强制执行。
+- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 允许带有无效签名的 Twilio webhooks，**仅当** `tunnel.provider="ngrok"` 且 `serve.bind` 是 loopback（ngrok 本地代理）时。仅用于本地开发。
+- Ngrok 免费版 URL 可能会更改或添加中间页面行为；如果 `publicUrl` 漂移，Twilio 签名将失败。对于生产环境，优先使用稳定域名或 Tailscale funnel。
+
+## 通话的 TTS
+
+Voice Call 使用核心 `messages.tts` 配置（OpenAI 或 ElevenLabs）进行通话中的流式语音。你可以在插件配置下使用**相同的结构**覆盖它——它会与 `messages.tts` 深度合并。
+
+```json5
+{
+  tts: {
+    provider: "elevenlabs",
+    elevenlabs: {
+      voiceId: "pMsXgVXv3BLzUgSXRplE",
+      modelId: "eleven_multilingual_v2",
+    },
+  },
+}
+```
+
+注意事项：
+
+- **语音通话忽略 Edge TTS**（电话音频需要 PCM；Edge 输出不可靠）。
+- 当启用 Twilio 媒体流时使用核心 TTS；否则通话回退到提供商原生语音。
+
+### 更多示例
+
+仅使用核心 TTS（无覆盖）：
+
+```json5
+{
+  messages: {
+    tts: {
+      provider: "openai",
+      openai: { voice: "alloy" },
+    },
+  },
+}
+```
+
+仅为通话覆盖为 ElevenLabs（其他地方保持核心默认）：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            provider: "elevenlabs",
+            elevenlabs: {
+              apiKey: "elevenlabs_key",
+              voiceId: "pMsXgVXv3BLzUgSXRplE",
+              modelId: "eleven_multilingual_v2",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+仅为通话覆盖 OpenAI 模型（深度合并示例）：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            openai: {
+              model: "gpt-4o-mini-tts",
+              voice: "marin",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## 入站通话
+
+入站策略默认为 `disabled`。要启用入站通话，设置：
+
+```json5
+{
+  inboundPolicy: "allowlist",
+  allowFrom: ["+15550001234"],
+  inboundGreeting: "Hello! How can I help?",
+}
+```
+
+自动响应使用智能体系统。通过以下方式调整：
+
+- `responseModel`
+- `responseSystemPrompt`
+- `responseTimeoutMs`
+
+## CLI
+
+```bash
+quantumclaw voicecall call --to "+15555550123" --message "Hello from QuantumClaw"
+quantumclaw voicecall continue --call-id <id> --message "Any questions?"
+quantumclaw voicecall speak --call-id <id> --message "One moment"
+quantumclaw voicecall end --call-id <id>
+quantumclaw voicecall status --call-id <id>
+quantumclaw voicecall tail
+quantumclaw voicecall expose --mode funnel
+```
+
+## 智能体工具
+
+工具名称：`voice_call`
+
+操作：
+
+- `initiate_call`（message、to?、mode?）
+- `continue_call`（callId、message）
+- `speak_to_user`（callId、message）
+- `end_call`（callId）
+- `get_status`（callId）
+
+此仓库在 `skills/voice-call/SKILL.md` 提供了配套的 skill 文档。
+
+## Gateway 网关 RPC
+
+- `voicecall.initiate`（`to?`、`message`、`mode?`）
+- `voicecall.continue`（`callId`、`message`）
+- `voicecall.speak`（`callId`、`message`）
+- `voicecall.end`（`callId`）
+- `voicecall.status`（`callId`）

package/docs/zh-CN/plugins/zalouser.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你想在 QuantumClaw 中支持 Zalo Personal（非官方）
+  - 你正在配置或开发 zalouser 插件
+summary: Zalo Personal 插件：通过 zca-cli 进行 QR 登录 + 消息（插件安装 + 渠道配置 + CLI + 工具）
+title: Zalo Personal 插件
+x-i18n:
+  generated_at: "2026-02-03T07:53:33Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b29b788b023cd50720e24fe6719f02e9f86c8bca9c73b3638fb53c2316718672
+  source_path: plugins/zalouser.md
+  workflow: 15
+---
+
+# Zalo Personal（插件）
+
+通过插件为 QuantumClaw 提供 Zalo Personal 支持，使用 `zca-cli` 自动化普通 Zalo 用户账户。
+
+> **警告：** 非官方自动化可能导致账户被暂停/封禁。使用风险自负。
+
+## 命名
+
+渠道 id 是 `zalouser`，以明确表示这是自动化**个人 Zalo 用户账户**（非官方）。我们保留 `zalo` 用于潜在的未来官方 Zalo API 集成。
+
+## 运行位置
+
+此插件**在 Gateway 网关进程内**运行。
+
+如果你使用远程 Gateway 网关，请在**运行 Gateway 网关的机器**上安装/配置它，然后重启 Gateway 网关。
+
+## 安装
+
+### 选项 A：从 npm 安装
+
+```bash
+quantumclaw plugins install @quantumclaw/zalouser
+```
+
+之后重启 Gateway 网关。
+
+### 选项 B：从本地文件夹安装（开发）
+
+```bash
+quantumclaw plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
+```
+
+之后重启 Gateway 网关。
+
+## 前置条件：zca-cli
+
+Gateway 网关机器必须在 `PATH` 中有 `zca`：
+
+```bash
+zca --version
+```
+
+## 配置
+
+渠道配置位于 `channels.zalouser` 下（不是 `plugins.entries.*`）：
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## CLI
+
+```bash
+quantumclaw channels login --channel zalouser
+quantumclaw channels logout --channel zalouser
+quantumclaw channels status --probe
+quantumclaw message send --channel zalouser --target <threadId> --message "Hello from QuantumClaw"
+quantumclaw directory peers list --channel zalouser --query "name"
+```
+
+## 智能体工具
+
+工具名称：`zalouser`
+
+操作：`send`、`image`、`link`、`friends`、`groups`、`me`、`status`

package/docs/zh-CN/prose.md

@@ -0,0 +1,141 @@
+---
+read_when:
+  - 你想运行或编写 .prose 工作流
+  - 你想启用 OpenProse 插件
+  - 你需要了解状态存储
+summary: OpenProse：QuantumClaw 中的 .prose 工作流、斜杠命令和状态
+title: OpenProse
+x-i18n:
+  generated_at: "2026-02-03T07:53:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cf7301e927b9a46347b498e264aeaa10dd76e85ff2de04775be57435718339f5
+  source_path: prose.md
+  workflow: 15
+---
+
+# OpenProse
+
+OpenProse 是一种可移植的、以 Markdown 为中心的工作流格式，用于编排 AI 会话。在 QuantumClaw 中，它作为插件发布，安装一个 OpenProse Skills 包以及一个 `/prose` 斜杠命令。程序存放在 `.prose` 文件中，可以生成多个具有显式控制流的子智能体。
+
+官方网站：https://www.prose.md
+
+## 它能做什么
+
+- 具有显式并行性的多智能体研究 + 综合。
+- 可重复的批准安全工作流（代码审查、事件分类、内容管道）。
+- 可在支持的智能体运行时之间运行的可重用 `.prose` 程序。
+
+## 安装 + 启用
+
+捆绑的插件默认是禁用的。启用 OpenProse：
+
+```bash
+quantumclaw plugins enable open-prose
+```
+
+启用插件后重启 Gateway 网关。
+
+开发/本地检出：`quantumclaw plugins install ./extensions/open-prose`
+
+相关文档：[插件](/tools/plugin)、[插件清单](/plugins/manifest)、[Skills](/tools/skills)。
+
+## 斜杠命令
+
+OpenProse 将 `/prose` 注册为用户可调用的 Skills 命令。它路由到 OpenProse VM 指令，并在底层使用 QuantumClaw 工具。
+
+常用命令：
+
+```
+/prose help
+/prose run <file.prose>
+/prose run <handle/slug>
+/prose run <https://example.com/file.prose>
+/prose compile <file.prose>
+/prose examples
+/prose update
+```
+
+## 示例：一个简单的 `.prose` 文件
+
+```prose
+# Research + synthesis with two agents running in parallel.
+
+input topic: "What should we research?"
+
+agent researcher:
+  model: sonnet
+  prompt: "You research thoroughly and cite sources."
+
+agent writer:
+  model: opus
+  prompt: "You write a concise summary."
+
+parallel:
+  findings = session: researcher
+    prompt: "Research {topic}."
+  draft = session: writer
+    prompt: "Summarize {topic}."
+
+session "Merge the findings + draft into a final answer."
+context: { findings, draft }
+```
+
+## 文件位置
+
+OpenProse 将状态保存在工作空间的 `.prose/` 下：
+
+```
+.prose/
+├── .env
+├── runs/
+│   └── {YYYYMMDD}-{HHMMSS}-{random}/
+│       ├── program.prose
+│       ├── state.md
+│       ├── bindings/
+│       └── agents/
+└── agents/
+```
+
+用户级持久智能体位于：
+
+```
+~/.prose/agents/
+```
+
+## 状态模式
+
+OpenProse 支持多种状态后端：
+
+- **filesystem**（默认）：`.prose/runs/...`
+- **in-context**：瞬态，用于小程序
+- **sqlite**（实验性）：需要 `sqlite3` 二进制文件
+- **postgres**（实验性）：需要 `psql` 和连接字符串
+
+说明：
+
+- sqlite/postgres 是选择加入的，且处于实验阶段。
+- postgres 凭证会流入子智能体日志；请使用专用的、最小权限的数据库。
+
+## 远程程序
+
+`/prose run <handle/slug>` 解析为 `https://p.prose.md/<handle>/<slug>`。
+直接 URL 按原样获取。这使用 `web_fetch` 工具（或用于 POST 的 `exec`）。
+
+## QuantumClaw 运行时映射
+
+OpenProse 程序映射到 QuantumClaw 原语：
+
+| OpenProse 概念       | QuantumClaw 工具    |
+| -------------------- | ---------------- |
+| 生成会话 / Task 工具 | `sessions_spawn` |
+| 文件读/写            | `read` / `write` |
+| Web 获取             | `web_fetch`      |
+
+如果你的工具白名单阻止这些工具，OpenProse 程序将失败。参见 [Skills 配置](/tools/skills-config)。
+
+## 安全 + 批准
+
+将 `.prose` 文件视为代码。运行前请审查。使用 QuantumClaw 工具白名单和批准门控来控制副作用。
+
+对于确定性的、批准门控的工作流，可与 [Lobster](/tools/lobster) 比较。