@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/cli/logs.md

@@ -0,0 +1,31 @@
+---
+read_when:
+  - 你需要远程跟踪 Gateway 网关日志（无需 SSH）
+  - 你需要 JSON 日志行用于工具处理
+summary: "`quantumclaw logs` 的 CLI 参考（通过 RPC 跟踪 Gateway 网关日志）"
+title: logs
+x-i18n:
+  generated_at: "2026-02-03T07:44:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 911a57f0f3b78412c26312f7bf87a5a26418ab7b74e5e2eb40f16edefb6c6b8e
+  source_path: cli/logs.md
+  workflow: 15
+---
+
+# `quantumclaw logs`
+
+通过 RPC 跟踪 Gateway 网关文件日志（在远程模式下可用）。
+
+相关内容：
+
+- 日志概述：[日志](/logging)
+
+## 示例
+
+```bash
+quantumclaw logs
+quantumclaw logs --follow
+quantumclaw logs --json
+quantumclaw logs --limit 500
+```

package/docs/zh-CN/cli/memory.md

@@ -0,0 +1,52 @@
+---
+read_when:
+  - 你想要索引或搜索语义记忆
+  - 你正在调试记忆可用性或索引问题
+summary: "`quantumclaw memory`（status/index/search）的 CLI 参考"
+title: memory
+x-i18n:
+  generated_at: "2026-02-01T20:21:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 95a9e94306f95be2218a909be59be5bbaa5d31322b71b23564c71a89c3a3941a
+  source_path: cli/memory.md
+  workflow: 14
+---
+
+# `quantumclaw memory`
+
+管理语义记忆的索引和搜索。
+由活跃的记忆插件提供（默认：`memory-core`；设置 `plugins.slots.memory = "none"` 可禁用）。
+
+相关内容：
+
+- 记忆概念：[记忆](/concepts/memory)
+- 插件：[插件](/tools/plugin)
+
+## 示例
+
+```bash
+quantumclaw memory status
+quantumclaw memory status --deep
+quantumclaw memory status --deep --index
+quantumclaw memory status --deep --index --verbose
+quantumclaw memory index
+quantumclaw memory index --verbose
+quantumclaw memory search "release checklist"
+quantumclaw memory status --agent main
+quantumclaw memory index --agent main --verbose
+```
+
+## 选项
+
+通用选项：
+
+- `--agent <id>`：限定到单个智能体（默认：所有已配置的智能体）。
+- `--verbose`：在探测和索引期间输出详细日志。
+
+说明：
+
+- `memory status --deep` 探测向量存储和嵌入模型的可用性。
+- `memory status --deep --index` 在存储有未同步变更时运行重新索引。
+- `memory index --verbose` 打印每个阶段的详细信息（提供商、模型、数据源、批处理活动）。
+- `memory status` 包含通过 `memorySearch.extraPaths` 配置的所有额外路径。

package/docs/zh-CN/cli/message.md

@@ -0,0 +1,246 @@
+---
+read_when:
+  - 添加或修改消息 CLI 操作
+  - 更改出站渠道行为
+summary: "`quantumclaw message`（发送 + 渠道操作）的 CLI 参考"
+title: message
+x-i18n:
+  generated_at: "2026-02-01T20:21:30Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 35159baf1ef7136252e3ab1e5e03881ebc4196dd43425e2319a39306ced7f48c
+  source_path: cli/message.md
+  workflow: 14
+---
+
+# `quantumclaw message`
+
+用于发送消息和渠道操作的单一出站命令
+（Discord/Google Chat/Slack/Mattermost（插件）/Telegram/WhatsApp/Signal/iMessage/MS Teams）。
+
+## 用法
+
+```
+quantumclaw message <subcommand> [flags]
+```
+
+渠道选择：
+
+- 如果配置了多个渠道，则必须指定 `--channel`。
+- 如果只配置了一个渠道，则该渠道为默认值。
+- 可选值：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`（Mattermost 需要插件）
+
+目标格式（`--target`）：
+
+- WhatsApp：E.164 或群组 JID
+- Telegram：聊天 ID 或 `@username`
+- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；纯数字 ID 被视为频道）
+- Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
+- Slack：`channel:<id>` 或 `user:<id>`（接受纯频道 ID）
+- Mattermost（插件）：`channel:<id>`、`user:<id>` 或 `@username`（纯 ID 被视为频道）
+- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>` 或 `username:<name>`/`u:<name>`
+- iMessage：句柄、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
+- MS Teams：会话 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
+
+名称查找：
+
+- 对于支持的提供商（Discord/Slack 等），如 `Help` 或 `#help` 之类的频道名称会通过目录缓存进行解析。
+- 缓存未命中时，如果提供商支持，QuantumClaw 将尝试实时目录查找。
+
+## 通用标志
+
+- `--channel <name>`
+- `--account <id>`
+- `--target <dest>`（用于 send/poll/read 等的目标渠道或用户）
+- `--targets <name>`（可重复；仅限广播）
+- `--json`
+- `--dry-run`
+- `--verbose`
+
+## 操作
+
+### 核心
+
+- `send`
+  - 渠道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/MS Teams
+  - 必需：`--target`，以及 `--message` 或 `--media`
+  - 可选：`--media`、`--reply-to`、`--thread-id`、`--gif-playback`
+  - 仅限 Telegram：`--buttons`（需要 `channels.telegram.capabilities.inlineButtons` 以启用）
+  - 仅限 Telegram：`--thread-id`（论坛主题 ID）
+  - 仅限 Slack：`--thread-id`（线程时间戳；`--reply-to` 使用相同字段）
+  - 仅限 WhatsApp：`--gif-playback`
+
+- `poll`
+  - 渠道：WhatsApp/Discord/MS Teams
+  - 必需：`--target`、`--poll-question`、`--poll-option`（可重复）
+  - 可选：`--poll-multi`
+  - 仅限 Discord：`--poll-duration-hours`、`--message`
+
+- `react`
+  - 渠道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal
+  - 必需：`--message-id`、`--target`
+  - 可选：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
+  - 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可清除自己的表情回应（如果支持）；参见 /tools/reactions）
+  - 仅限 WhatsApp：`--participant`、`--from-me`
+  - Signal 群组表情回应：需要 `--target-author` 或 `--target-author-uuid`
+
+- `reactions`
+  - 渠道：Discord/Google Chat/Slack
+  - 必需：`--message-id`、`--target`
+  - 可选：`--limit`
+
+- `read`
+  - 渠道：Discord/Slack
+  - 必需：`--target`
+  - 可选：`--limit`、`--before`、`--after`
+  - 仅限 Discord：`--around`
+
+- `edit`
+  - 渠道：Discord/Slack
+  - 必需：`--message-id`、`--message`、`--target`
+
+- `delete`
+  - 渠道：Discord/Slack/Telegram
+  - 必需：`--message-id`、`--target`
+
+- `pin` / `unpin`
+  - 渠道：Discord/Slack
+  - 必需：`--message-id`、`--target`
+
+- `pins`（列表）
+  - 渠道：Discord/Slack
+  - 必需：`--target`
+
+- `permissions`
+  - 渠道：Discord
+  - 必需：`--target`
+
+- `search`
+  - 渠道：Discord
+  - 必需：`--guild-id`、`--query`
+  - 可选：`--channel-id`、`--channel-ids`（可重复）、`--author-id`、`--author-ids`（可重复）、`--limit`
+
+### 线程
+
+- `thread create`
+  - 渠道：Discord
+  - 必需：`--thread-name`、`--target`（频道 ID）
+  - 可选：`--message-id`、`--auto-archive-min`
+
+- `thread list`
+  - 渠道：Discord
+  - 必需：`--guild-id`
+  - 可选：`--channel-id`、`--include-archived`、`--before`、`--limit`
+
+- `thread reply`
+  - 渠道：Discord
+  - 必需：`--target`（线程 ID）、`--message`
+  - 可选：`--media`、`--reply-to`
+
+### 表情符号
+
+- `emoji list`
+  - Discord：`--guild-id`
+  - Slack：无需额外标志
+
+- `emoji upload`
+  - 渠道：Discord
+  - 必需：`--guild-id`、`--emoji-name`、`--media`
+  - 可选：`--role-ids`（可重复）
+
+### 贴纸
+
+- `sticker send`
+  - 渠道：Discord
+  - 必需：`--target`、`--sticker-id`（可重复）
+  - 可选：`--message`
+
+- `sticker upload`
+  - 渠道：Discord
+  - 必需：`--guild-id`、`--sticker-name`、`--sticker-desc`、`--sticker-tags`、`--media`
+
+### 角色 / 频道 / 成员 / 语音
+
+- `role info`（Discord）：`--guild-id`
+- `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id`
+- `channel info`（Discord）：`--target`
+- `channel list`（Discord）：`--guild-id`
+- `member info`（Discord/Slack）：`--user-id`（Discord 还需要 `--guild-id`）
+- `voice status`（Discord）：`--guild-id`、`--user-id`
+
+### 事件
+
+- `event list`（Discord）：`--guild-id`
+- `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
+  - 可选：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
+
+### 管理（Discord）
+
+- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除超时）
+- `kick`：`--guild-id`、`--user-id`（+ `--reason`）
+- `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
+  - `timeout` 也支持 `--reason`
+
+### 广播
+
+- `broadcast`
+  - 渠道：任何已配置的渠道；使用 `--channel all` 可针对所有提供商
+  - 必需：`--targets`（可重复）
+  - 可选：`--message`、`--media`、`--dry-run`
+
+## 示例
+
+发送 Discord 回复：
+
+```
+quantumclaw message send --channel discord \
+  --target channel:123 --message "hi" --reply-to 456
+```
+
+创建 Discord 投票：
+
+```
+quantumclaw message poll --channel discord \
+  --target channel:123 \
+  --poll-question "Snack?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-multi --poll-duration-hours 48
+```
+
+发送 Teams 主动消息：
+
+```
+quantumclaw message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 --message "hi"
+```
+
+创建 Teams 投票：
+
+```
+quantumclaw message poll --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi
+```
+
+在 Slack 中添加表情回应：
+
+```
+quantumclaw message react --channel slack \
+  --target C123 --message-id 456 --emoji "✅"
+```
+
+在 Signal 群组中添加表情回应：
+
+```
+quantumclaw message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
+发送 Telegram 内联按钮：
+
+```
+quantumclaw message send --channel telegram --target @mychat --message "Choose:" \
+  --buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
+```

package/docs/zh-CN/cli/models.md

@@ -0,0 +1,85 @@
+---
+read_when:
+  - 你想更改默认模型或查看提供商认证状态
+  - 你想扫描可用的模型/提供商并调试认证配置
+summary: "`quantumclaw models` 的 CLI 参考（status/list/set/scan、别名、回退、认证）"
+title: models
+x-i18n:
+  generated_at: "2026-02-01T20:21:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 923b6ffc7de382ba25bc6e699f0515607e74877b39f2136ccdba2d99e1b1e9c3
+  source_path: cli/models.md
+  workflow: 14
+---
+
+# `quantumclaw models`
+
+模型发现、扫描和配置（默认模型、回退、认证配置）。
+
+相关内容：
+
+- 提供商 + 模型：[模型](/providers/models)
+- 提供商认证设置：[快速开始](/start/getting-started)
+
+## 常用命令
+
+```bash
+quantumclaw models status
+quantumclaw models list
+quantumclaw models set <model-or-alias>
+quantumclaw models scan
+```
+
+`quantumclaw models status` 显示已解析的默认模型/回退配置以及认证概览。
+当提供商使用快照可用时，OAuth/令牌状态部分会包含提供商使用头信息。
+添加 `--probe` 可对每个已配置的提供商配置运行实时认证探测。
+探测会发送真实请求（可能消耗令牌并触发速率限制）。
+使用 `--agent <id>` 可检查已配置智能体的模型/认证状态。省略时，
+命令会使用 `QUANTUMCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`（如已设置），否则使用
+已配置的默认智能体。
+
+注意事项：
+
+- `models set <model-or-alias>` 接受 `provider/model` 或别名。
+- 模型引用通过在**第一个** `/` 处拆分来解析。如果模型 ID 包含 `/`（OpenRouter 风格），需包含提供商前缀（示例：`openrouter/moonshotai/kimi-k2`）。
+- 如果省略提供商，QuantumClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 不包含 `/` 时有效）。
+
+### `models status`
+
+选项：
+
+- `--json`
+- `--plain`
+- `--check`（退出码 1=已过期/缺失，2=即将过期）
+- `--probe`（对已配置的认证配置进行实时探测）
+- `--probe-provider <name>`（探测单个提供商）
+- `--probe-profile <id>`（可重复或逗号分隔的配置 ID）
+- `--probe-timeout <ms>`
+- `--probe-concurrency <n>`
+- `--probe-max-tokens <n>`
+- `--agent <id>`（已配置的智能体 ID；覆盖 `QUANTUMCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
+
+## 别名 + 回退
+
+```bash
+quantumclaw models aliases list
+quantumclaw models fallbacks list
+```
+
+## 认证配置
+
+```bash
+quantumclaw models auth add
+quantumclaw models auth login --provider <id>
+quantumclaw models auth setup-token
+quantumclaw models auth paste-token
+```
+
+`models auth login` 运行提供商插件的认证流程（OAuth/API 密钥）。使用
+`quantumclaw plugins list` 查看已安装的提供商。
+
+注意事项：
+
+- `setup-token` 会提示输入 setup-token 值（在任意机器上使用 `claude setup-token` 生成）。
+- `paste-token` 接受在其他地方或通过自动化生成的令牌字符串。

package/docs/zh-CN/cli/node.md

@@ -0,0 +1,115 @@
+---
+read_when:
+  - 运行无头节点主机
+  - 为 system.run 配对非 macOS 节点
+summary: "`quantumclaw node` 的 CLI 参考（无头节点主机）"
+title: node
+x-i18n:
+  generated_at: "2026-02-03T07:45:07Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a8b1a57712663e2285c9ecd306fe57d067eb3e6820d7d8aec650b41b022d995a
+  source_path: cli/node.md
+  workflow: 15
+---
+
+# `quantumclaw node`
+
+运行一个**无头节点主机**，连接到 Gateway 网关 WebSocket 并在此机器上暴露
+`system.run` / `system.which`。
+
+## 为什么使用节点主机？
+
+当你希望智能体**在网络中的其他机器上运行命令**，而无需在那里安装完整的 macOS 配套应用时，请使用节点主机。
+
+常见用例：
+
+- 在远程 Linux/Windows 机器上运行命令（构建服务器、实验室机器、NAS）。
+- 在 Gateway 网关上保持执行的**沙箱隔离**，但将批准的运行委托给其他主机。
+- 为自动化或 CI 节点提供轻量级、无头的执行目标。
+
+执行仍然受**执行批准**和节点主机上的每智能体允许列表保护，因此你可以保持命令访问的范围明确。
+
+## 浏览器代理（零配置）
+
+如果节点上的 `browser.enabled` 未被禁用，节点主机会自动广播浏览器代理。这让智能体无需额外配置即可在该节点上使用浏览器自动化。
+
+如需在节点上禁用：
+
+```json5
+{
+  nodeHost: {
+    browserProxy: {
+      enabled: false,
+    },
+  },
+}
+```
+
+## 运行（前台）
+
+```bash
+quantumclaw node run --host <gateway-host> --port 18789
+```
+
+选项：
+
+- `--host <host>`：Gateway 网关 WebSocket 主机（默认：`127.0.0.1`）
+- `--port <port>`：Gateway 网关 WebSocket 端口（默认：`18789`）
+- `--tls`：为 Gateway 网关连接使用 TLS
+- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
+- `--node-id <id>`：覆盖节点 id（清除配对 token）
+- `--display-name <name>`：覆盖节点显示名称
+
+## 服务（后台）
+
+将无头节点主机安装为用户服务。
+
+```bash
+quantumclaw node install --host <gateway-host> --port 18789
+```
+
+选项：
+
+- `--host <host>`：Gateway 网关 WebSocket 主机（默认：`127.0.0.1`）
+- `--port <port>`：Gateway 网关 WebSocket 端口（默认：`18789`）
+- `--tls`：为 Gateway 网关连接使用 TLS
+- `--tls-fingerprint <sha256>`：预期的 TLS 证书指纹（sha256）
+- `--node-id <id>`：覆盖节点 id（清除配对 token）
+- `--display-name <name>`：覆盖节点显示名称
+- `--runtime <runtime>`：服务运行时（`node` 或 `bun`）
+- `--force`：如果已安装则重新安装/覆盖
+
+管理服务：
+
+```bash
+quantumclaw node status
+quantumclaw node stop
+quantumclaw node restart
+quantumclaw node uninstall
+```
+
+使用 `quantumclaw node run` 运行前台节点主机（无服务）。
+
+服务命令接受 `--json` 以获取机器可读输出。
+
+## 配对
+
+首次连接会在 Gateway 网关上创建待处理的节点配对请求。
+通过以下方式批准：
+
+```bash
+quantumclaw nodes pending
+quantumclaw nodes approve <requestId>
+```
+
+节点主机将其节点 id、token、显示名称和 Gateway 网关连接信息存储在
+`~/.quantumclaw/node.json` 中。
+
+## 执行批准
+
+`system.run` 受本地执行批准限制：
+
+- `~/.quantumclaw/exec-approvals.json`
+- [执行批准](/tools/exec-approvals)
+- `quantumclaw approvals --node <id|name|ip>`（从 Gateway 网关编辑）

package/docs/zh-CN/cli/nodes.md

@@ -0,0 +1,80 @@
+---
+read_when:
+  - 你正在管理已配对的节点（摄像头、屏幕、画布）
+  - 你需要批准请求或调用节点命令
+summary: "`quantumclaw nodes` 的 CLI 参考（列表/状态/批准/调用，摄像头/画布/屏幕）"
+title: nodes
+x-i18n:
+  generated_at: "2026-02-03T10:04:26Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 23da6efdd659a82dbbc4afd18eb4ab1020a2892f69c28d610f912c8a799f734c
+  source_path: cli/nodes.md
+  workflow: 15
+---
+
+# `quantumclaw nodes`
+
+管理已配对的节点（设备）并调用节点功能。
+
+相关内容：
+
+- 节点概述：[节点](/nodes)
+- 摄像头：[摄像头节点](/nodes/camera)
+- 图像：[图像节点](/nodes/images)
+
+通用选项：
+
+- `--url`、`--token`、`--timeout`、`--json`
+
+## 常用命令
+
+```bash
+quantumclaw nodes list
+quantumclaw nodes list --connected
+quantumclaw nodes list --last-connected 24h
+quantumclaw nodes pending
+quantumclaw nodes approve <requestId>
+quantumclaw nodes status
+quantumclaw nodes status --connected
+quantumclaw nodes status --last-connected 24h
+```
+
+`nodes list` 打印待处理/已配对表格。已配对行包含最近连接时长（Last Connect）。
+使用 `--connected` 仅显示当前已连接的节点。使用 `--last-connected <duration>`
+筛选在指定时间段内连接过的节点（例如 `24h`、`7d`）。
+
+## 调用 / 运行
+
+```bash
+quantumclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
+quantumclaw nodes run --node <id|name|ip> <command...>
+quantumclaw nodes run --raw "git status"
+quantumclaw nodes run --agent main --node <id|name|ip> --raw "git status"
+```
+
+调用标志：
+
+- `--params <json>`：JSON 对象字符串（默认 `{}`）。
+- `--invoke-timeout <ms>`：节点调用超时（默认 `15000`）。
+- `--idempotency-key <key>`：可选的幂等键。
+
+### Exec 风格默认值
+
+`nodes run` 与模型的 exec 行为一致（默认值 + 审批）：
+
+- 读取 `tools.exec.*`（以及 `agents.list[].tools.exec.*` 覆盖）。
+- 在调用 `system.run` 前使用 exec 审批（`exec.approval.request`）。
+- 当设置了 `tools.exec.node` 时可省略 `--node`。
+- 需要支持 `system.run` 的节点（macOS 配套应用或无头节点主机）。
+
+标志：
+
+- `--cwd <path>`：工作目录。
+- `--env <key=val>`：环境变量覆盖（可重复）。
+- `--command-timeout <ms>`：命令超时。
+- `--invoke-timeout <ms>`：节点调用超时（默认 `30000`）。
+- `--needs-screen-recording`：要求屏幕录制权限。
+- `--raw <command>`：运行 shell 字符串（`/bin/sh -lc` 或 `cmd.exe /c`）。
+- `--agent <id>`：智能体范围的审批/白名单（默认为已配置的智能体）。
+- `--ask <off|on-miss|always>`、`--security <deny|allowlist|full>`：覆盖选项。