@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/gateway/discovery.md

@@ -0,0 +1,123 @@
+---
+read_when:
+  - 实现或更改 Bonjour 发现/广播
+  - 调整远程连接模式（直连 vs SSH）
+  - 设计远程节点的节点发现 + 配对
+summary: 用于发现 Gateway 网关的节点发现和传输协议（Bonjour、Tailscale、SSH）
+title: 设备发现 + 传输协议
+x-i18n:
+  generated_at: "2026-02-03T10:06:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e12172c181515bfa6aab8625ed3fbc335b80ba92e2b516c02c6066aeeb9f884c
+  source_path: gateway/discovery.md
+  workflow: 15
+---
+
+# 设备发现 & 传输协议
+
+QuantumClaw 有两个表面上看起来相似的不同问题：
+
+1. **操作员远程控制**：macOS 菜单栏应用控制运行在其他地方的 Gateway 网关。
+2. **节点配对**：iOS/Android（以及未来的节点）发现 Gateway 网关并安全配对。
+
+设计目标是将所有网络发现/广播保留在 **Node Gateway 网关**（`quantumclaw gateway`）中，并让客户端（mac 应用、iOS）作为消费者。
+
+## 术语
+
+- **Gateway 网关**：一个长期运行的 Gateway 网关进程，拥有状态（会话、配对、节点注册表）并运行渠道。大多数设置每台主机使用一个；也可以进行隔离的多 Gateway 网关设置。
+- **Gateway 网关 WS（控制平面）**：默认在 `127.0.0.1:18789` 上的 WebSocket 端点；可通过 `gateway.bind` 绑定到 LAN/tailnet。
+- **直连 WS 传输**：面向 LAN/tailnet 的 Gateway 网关 WS 端点（无 SSH）。
+- **SSH 传输（回退）**：通过 SSH 转发 `127.0.0.1:18789` 进行远程控制。
+- **旧版 TCP 桥接（已弃用/移除）**：旧的节点传输（参见 [桥接协议](/gateway/bridge-protocol)）；不再用于发现广播。
+
+协议详情：
+
+- [Gateway 网关协议](/gateway/protocol)
+- [桥接协议（旧版）](/gateway/bridge-protocol)
+
+## 为什么我们同时保留"直连"和 SSH
+
+- **直连 WS** 在同一网络和 tailnet 内提供最佳用户体验：
+  - 通过 Bonjour 在 LAN 上自动发现
+  - 配对令牌 + ACL 由 Gateway 网关管理
+  - 无需 shell 访问；协议表面可保持紧凑和可审计
+- **SSH** 仍然是通用回退方案：
+  - 只要你有 SSH 访问权限就能工作（即使跨越不相关的网络）
+  - 能应对多播/mDNS 问题
+  - 除 SSH 外无需新的入站端口
+
+## 发现输入（客户端如何了解 Gateway 网关位置）
+
+### 1）Bonjour / mDNS（仅限 LAN）
+
+Bonjour 是尽力而为的，不会跨网络。它仅用于"同一 LAN"的便利性。
+
+目标方向：
+
+- **Gateway 网关**通过 Bonjour 广播其 WS 端点。
+- 客户端浏览并显示"选择一个 Gateway 网关"列表，然后存储选定的端点。
+
+故障排除和信标详情：[Bonjour](/gateway/bonjour)。
+
+#### 服务信标详情
+
+- 服务类型：
+  - `_quantumclaw-gw._tcp`（Gateway 网关传输信标）
+- TXT 键（非机密）：
+  - `role=gateway`
+  - `lanHost=<hostname>.local`
+  - `sshPort=22`（或广播的端口）
+  - `gatewayPort=18789`（Gateway 网关 WS + HTTP）
+  - `gatewayTls=1`（仅当启用 TLS 时）
+  - `gatewayTlsSha256=<sha256>`（仅当启用 TLS 且指纹可用时）
+  - `canvasPort=18793`（默认画布主机端口；服务于 `/__quantumclaw__/canvas/`）
+  - `cliPath=<path>`（可选；可运行的 `quantumclaw` 入口点或二进制文件的绝对路径）
+  - `tailnetDns=<magicdns>`（可选提示；当 Tailscale 可用时自动检测）
+
+禁用/覆盖：
+
+- `QUANTUMCLAW_DISABLE_BONJOUR=1` 禁用广播。
+- `~/.quantumclaw/quantumclaw.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
+- `QUANTUMCLAW_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（默认为 22）。
+- `QUANTUMCLAW_TAILNET_DNS` 发布 `tailnetDns` 提示（MagicDNS）。
+- `QUANTUMCLAW_CLI_PATH` 覆盖广播的 CLI 路径。
+
+### 2）Tailnet（跨网络）
+
+对于伦敦/维也纳风格的设置，Bonjour 无法帮助。推荐的"直连"目标是：
+
+- Tailscale MagicDNS 名称（首选）或稳定的 tailnet IP。
+
+如果 Gateway 网关能检测到它正在 Tailscale 下运行，它会发布 `tailnetDns` 作为客户端的可选提示（包括广域信标）。
+
+### 3）手动 / SSH 目标
+
+当没有直连路由（或直连被禁用）时，客户端始终可以通过 SSH 转发本地回环 Gateway 网关端口来连接。
+
+参见 [远程访问](/gateway/remote)。
+
+## 传输选择（客户端策略）
+
+推荐的客户端行为：
+
+1. 如果已配置且可达已配对的直连端点，使用它。
+2. 否则，如果 Bonjour 在 LAN 上找到 Gateway 网关，提供一键"使用此 Gateway 网关"选择并将其保存为直连端点。
+3. 否则，如果配置了 tailnet DNS/IP，尝试直连。
+4. 否则，回退到 SSH。
+
+## 配对 + 认证（直连传输）
+
+Gateway 网关是节点/客户端准入的唯一权威来源。
+
+- 配对请求在 Gateway 网关中创建/批准/拒绝（参见 [Gateway 网关配对](/gateway/pairing)）。
+- Gateway 网关强制执行：
+  - 认证（令牌 / 密钥对）
+  - 作用域/ACL（Gateway 网关不是每个方法的原始代理）
+  - 速率限制
+
+## 各组件职责
+
+- **Gateway 网关**：广播发现信标，拥有配对决策权，并托管 WS 端点。
+- **macOS 应用**：帮助你选择 Gateway 网关，显示配对提示，仅将 SSH 作为回退方案。
+- **iOS/Android 节点**：将 Bonjour 浏览作为便利功能，连接到已配对的 Gateway 网关 WS。

package/docs/zh-CN/gateway/doctor.md

@@ -0,0 +1,238 @@
+---
+read_when:
+  - 添加或修改 doctor 迁移
+  - 引入破坏性配置更改
+summary: Doctor 命令：健康检查、配置迁移和修复步骤
+title: Doctor
+x-i18n:
+  generated_at: "2026-02-03T07:49:03Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: df7b25f60fd08d508f4c6abfc8e7e06f29bd4bbb34c3320397f47eb72c8de83f
+  source_path: gateway/doctor.md
+  workflow: 15
+---
+
+# Doctor
+
+`quantumclaw doctor` 是 QuantumClaw 的修复 + 迁移工具。它修复过时的配置/状态，检查健康状况，并提供可操作的修复步骤。
+
+## 快速开始
+
+```bash
+quantumclaw doctor
+```
+
+### 无头/自动化
+
+```bash
+quantumclaw doctor --yes
+```
+
+无需提示接受默认值（包括适用时的重启/服务/沙箱修复步骤）。
+
+```bash
+quantumclaw doctor --repair
+```
+
+无需提示应用推荐的修复（安全时进行修复 + 重启）。
+
+```bash
+quantumclaw doctor --repair --force
+```
+
+也应用激进的修复（覆盖自定义 supervisor 配置）。
+
+```bash
+quantumclaw doctor --non-interactive
+```
+
+无需提示运行，仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。
+检测到时自动运行遗留状态迁移。
+
+```bash
+quantumclaw doctor --deep
+```
+
+扫描系统服务以查找额外的 Gateway 网关安装（launchd/systemd/schtasks）。
+
+如果你想在写入前查看更改，请先打开配置文件：
+
+```bash
+cat ~/.quantumclaw/quantumclaw.json
+```
+
+## 功能概述
+
+- git 安装的可选预检更新（仅交互模式）。
+- UI 协议新鲜度检查（当协议 schema 较新时重建 Control UI）。
+- 健康检查 + 重启提示。
+- Skills 状态摘要（符合条件/缺失/被阻止）。
+- 遗留值的配置规范化。
+- OpenCode Zen 提供商覆盖警告（`models.providers.opencode`）。
+- 遗留磁盘状态迁移（会话/智能体目录/WhatsApp 认证）。
+- 状态完整性和权限检查（会话、记录、状态目录）。
+- 本地运行时的配置文件权限检查（chmod 600）。
+- 模型认证健康：检查 OAuth 过期，可刷新即将过期的 token，并报告认证配置文件冷却/禁用状态。
+- 额外工作区目录检测（`~/quantumclaw`）。
+- 启用沙箱隔离时的沙箱镜像修复。
+- 遗留服务迁移和额外 Gateway 网关检测。
+- Gateway 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
+- 渠道状态警告（从运行中的 Gateway 网关探测）。
+- Supervisor 配置审计（launchd/systemd/schtasks）及可选修复。
+- Gateway 网关运行时最佳实践检查（Node vs Bun，版本管理器路径）。
+- Gateway 网关端口冲突诊断（默认 `18789`）。
+- 开放私信策略的安全警告。
+- 未设置 `gateway.auth.token` 时的 Gateway 网关认证警告（本地模式；提供 token 生成）。
+- Linux 上的 systemd linger 检查。
+- 源码安装检查（pnpm workspace 不匹配、缺失 UI 资产、缺失 tsx 二进制文件）。
+- 写入更新后的配置 + 向导元数据。
+
+## 详细行为和原理
+
+### 0）可选更新（git 安装）
+
+如果这是 git 检出且 doctor 以交互模式运行，它会在运行 doctor 之前提供更新（fetch/rebase/build）。
+
+### 1）配置规范化
+
+如果配置包含遗留值形式（例如没有渠道特定覆盖的 `messages.ackReaction`），doctor 会将它们规范化为当前 schema。
+
+### 2）遗留配置键迁移
+
+当配置包含已弃用的键时，其他命令会拒绝运行并要求你运行 `quantumclaw doctor`。
+
+Doctor 将：
+
+- 解释找到了哪些遗留键。
+- 显示它应用的迁移。
+- 使用更新后的 schema 重写 `~/.quantumclaw/quantumclaw.json`。
+
+Gateway 网关在检测到遗留配置格式时也会在启动时自动运行 doctor 迁移，因此过时的配置无需手动干预即可修复。
+
+当前迁移：
+
+- `routing.allowFrom` → `channels.whatsapp.allowFrom`
+- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
+- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
+- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+- `routing.queue` → `messages.queue`
+- `routing.bindings` → 顶级 `bindings`
+- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
+- `routing.agentToAgent` → `tools.agentToAgent`
+- `routing.transcribeAudio` → `tools.media.audio.models`
+- `bindings[].match.accountID` → `bindings[].match.accountId`
+- `identity` → `agents.list[].identity`
+- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
+- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
+  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
+
+### 2b）OpenCode Zen 提供商覆盖
+
+如果你手动添加了 `models.providers.opencode`（或 `opencode-zen`），它会覆盖 `@mariozechner/pi-ai` 中内置的 OpenCode Zen 目录。这可能会强制将每个模型放到单个 API 上或将成本归零。Doctor 会发出警告，以便你可以移除覆盖并恢复每模型 API 路由 + 成本。
+
+### 3）遗留状态迁移（磁盘布局）
+
+Doctor 可以将旧的磁盘布局迁移到当前结构：
+
+- 会话存储 + 记录：
+  - 从 `~/.quantumclaw/sessions/` 到 `~/.quantumclaw/agents/<agentId>/sessions/`
+- 智能体目录：
+  - 从 `~/.quantumclaw/agent/` 到 `~/.quantumclaw/agents/<agentId>/agent/`
+- WhatsApp 认证状态（Baileys）：
+  - 从遗留的 `~/.quantumclaw/credentials/*.json`（除 `oauth.json` 外）
+  - 到 `~/.quantumclaw/credentials/whatsapp/<accountId>/...`（默认账户 id：`default`）
+
+这些迁移是尽力而为且幂等的；当 doctor 将任何遗留文件夹作为备份保留时会发出警告。Gateway 网关/CLI 也会在启动时自动迁移遗留会话 + 智能体目录，因此历史/认证/模型会落在每智能体路径中，无需手动运行 doctor。WhatsApp 认证有意仅通过 `quantumclaw doctor` 迁移。
+
+### 4）状态完整性检查（会话持久化、路由和安全）
+
+状态目录是操作的核心。如果它消失，你会丢失会话、凭证、日志和配置（除非你在别处有备份）。
+
+Doctor 检查：
+
+- **状态目录缺失**：警告灾难性状态丢失，提示重新创建目录，并提醒你它无法恢复丢失的数据。
+- **状态目录权限**：验证可写性；提供修复权限（并在检测到所有者/组不匹配时发出 `chown` 提示）。
+- **会话目录缺失**：`sessions/` 和会话存储目录是持久化历史和避免 `ENOENT` 崩溃所必需的。
+- **记录不匹配**：当最近的会话条目缺少记录文件时发出警告。
+- **主会话"1 行 JSONL"**：当主记录只有一行时标记（历史未累积）。
+- **多个状态目录**：当多个 `~/.quantumclaw` 文件夹存在于不同 home 目录或当 `QUANTUMCLAW_STATE_DIR` 指向别处时发出警告（历史可能在安装之间分裂）。
+- **远程模式提醒**：如果 `gateway.mode=remote`，doctor 会提醒你在远程主机上运行它（状态在那里）。
+- **配置文件权限**：当 `~/.quantumclaw/quantumclaw.json` 对组/其他用户可读时发出警告，并提供收紧到 `600` 的选项。
+
+### 5）模型认证健康（OAuth 过期）
+
+Doctor 检查认证存储中的 OAuth 配置文件，在 token 即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置文件过时，它会建议运行 `claude setup-token`（或粘贴 setup-token）。
+刷新提示仅在交互运行（TTY）时出现；`--non-interactive` 跳过刷新尝试。
+
+Doctor 还会报告由于以下原因暂时不可用的认证配置文件：
+
+- 短冷却（速率限制/超时/认证失败）
+- 长禁用（账单/信用失败）
+
+### 6）Hooks 模型验证
+
+如果设置了 `hooks.gmail.model`，doctor 会根据目录和允许列表验证模型引用，并在无法解析或不允许时发出警告。
+
+### 7）沙箱镜像修复
+
+当启用沙箱隔离时，doctor 检查 Docker 镜像，并在当前镜像缺失时提供构建或切换到遗留名称的选项。
+
+### 8）Gateway 网关服务迁移和清理提示
+
+Doctor 检测遗留的 Gateway 网关服务（launchd/systemd/schtasks），并提供删除它们并使用当前 Gateway 网关端口安装 QuantumClaw 服务的选项。它还可以扫描额外的类 Gateway 网关服务并打印清理提示。
+配置文件命名的 QuantumClaw Gateway 网关服务被视为一等公民，不会被标记为"额外的"。
+
+### 9）安全警告
+
+当提供商对私信开放而没有允许列表，或当策略以危险方式配置时，Doctor 会发出警告。
+
+### 10）systemd linger（Linux）
+
+如果作为 systemd 用户服务运行，doctor 确保启用 lingering，以便 Gateway 网关在注销后保持活动。
+
+### 11）Skills 状态
+
+Doctor 打印当前工作区符合条件/缺失/被阻止的 Skills 的快速摘要。
+
+### 12）Gateway 网关认证检查（本地 token）
+
+当本地 Gateway 网关缺少 `gateway.auth` 时，Doctor 会发出警告并提供生成 token 的选项。使用 `quantumclaw doctor --generate-gateway-token` 在自动化中强制创建 token。
+
+### 13）Gateway 网关健康检查 + 重启
+
+Doctor 运行健康检查，并在 Gateway 网关看起来不健康时提供重启选项。
+
+### 14）渠道状态警告
+
+如果 Gateway 网关健康，doctor 运行渠道状态探测并报告警告及建议的修复。
+
+### 15）Supervisor 配置审计 + 修复
+
+Doctor 检查已安装的 supervisor 配置（launchd/systemd/schtasks）是否有缺失或过时的默认值（例如 systemd network-online 依赖和重启延迟）。当发现不匹配时，它会推荐更新，并可以将服务文件/任务重写为当前默认值。
+
+注意事项：
+
+- `quantumclaw doctor` 在重写 supervisor 配置前提示。
+- `quantumclaw doctor --yes` 接受默认修复提示。
+- `quantumclaw doctor --repair` 无需提示应用推荐的修复。
+- `quantumclaw doctor --repair --force` 覆盖自定义 supervisor 配置。
+- 你始终可以通过 `quantumclaw gateway install --force` 强制完全重写。
+
+### 16）Gateway 网关运行时 + 端口诊断
+
+Doctor 检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还检查 Gateway 网关端口（默认 `18789`）上的端口冲突，并报告可能的原因（Gateway 网关已在运行、SSH 隧道）。
+
+### 17）Gateway 网关运行时最佳实践
+
+当 Gateway 网关服务在 Bun 或版本管理器管理的 Node 路径（`nvm`、`fnm`、`volta`、`asdf` 等）上运行时，Doctor 会发出警告。WhatsApp + Telegram 渠道需要 Node，版本管理器路径在升级后可能会中断，因为服务不会加载你的 shell init。Doctor 会在可用时提供迁移到系统 Node 安装的选项（Homebrew/apt/choco）。
+
+### 18）配置写入 + 向导元数据
+
+Doctor 持久化任何配置更改，并标记向导元数据以记录 doctor 运行。
+
+### 19）工作区提示（备份 + 记忆系统）
+
+当缺失时，Doctor 建议使用工作区记忆系统，并在工作区尚未在 git 下时打印备份提示。
+
+参见 [/concepts/agent-workspace](/concepts/agent-workspace) 了解工作区结构和 git 备份的完整指南（推荐私有 GitHub 或 GitLab）。

package/docs/zh-CN/gateway/gateway-lock.md

@@ -0,0 +1,41 @@
+---
+read_when:
+  - 运行或调试 Gateway 网关进程
+  - 调查单实例强制执行
+summary: 使用 WebSocket 监听器绑定的 Gateway 网关单例保护
+title: Gateway 网关锁
+x-i18n:
+  generated_at: "2026-02-03T07:47:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 15fdfa066d1925da8b4632073a876709f77ca8d40e6828c174a30d953ba4f8e9
+  source_path: gateway/gateway-lock.md
+  workflow: 15
+---
+
+# Gateway 网关锁
+
+最后更新：2025-12-11
+
+## 原因
+
+- 确保同一主机上每个基础端口只运行一个 Gateway 网关实例；额外的 Gateway 网关必须使用隔离的配置文件和唯一的端口。
+- 在崩溃/SIGKILL 后不留下过时的锁文件。
+- 当控制端口已被占用时快速失败并给出清晰的错误。
+
+## 机制
+
+- Gateway 网关在启动时立即使用独占 TCP 监听器绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`）。
+- 如果绑定因 `EADDRINUSE` 失败，启动会抛出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
+- 操作系统在任何进程退出时（包括崩溃和 SIGKILL）自动释放监听器——不需要单独的锁文件或清理步骤。
+- 关闭时，Gateway 网关关闭 WebSocket 服务器和底层 HTTP 服务器以及时释放端口。
+
+## 错误表面
+
+- 如果另一个进程持有端口，启动会抛出 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`。
+- 其他绑定失败会显示为 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`。
+
+## 运维说明
+
+- 如果端口被*另一个*进程占用，错误是相同的；释放端口或使用 `quantumclaw gateway --port <port>` 选择另一个端口。
+- macOS 应用在启动 Gateway 网关之前仍维护自己的轻量级 PID 保护；运行时锁由 WebSocket 绑定强制执行。

package/docs/zh-CN/gateway/health.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 诊断 WhatsApp 渠道健康状况
+summary: 渠道连接的健康检查步骤
+title: 健康检查
+x-i18n:
+  generated_at: "2026-02-03T07:47:59Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 74f242e98244c135e1322682ed6b67d70f3b404aca783b1bb5de96a27c2c1b01
+  source_path: gateway/health.md
+  workflow: 15
+---
+
+# 健康检查（CLI）
+
+验证渠道连接的简短指南，无需猜测。
+
+## 快速检查
+
+- `quantumclaw status` — 本地摘要：Gateway 网关可达性/模式、更新提示、已链接渠道认证时长、会话 + 最近活动。
+- `quantumclaw status --all` — 完整本地诊断（只读、彩色、可安全粘贴用于调试）。
+- `quantumclaw status --deep` — 还会探测运行中的 Gateway 网关（支持时进行每渠道探测）。
+- `quantumclaw health --json` — 向运行中的 Gateway 网关请求完整健康快照（仅 WS；不直接访问 Baileys 套接字）。
+- 在 WhatsApp/WebChat 中单独发送 `/status` 消息可获取状态回复，而不调用智能体。
+- 日志：跟踪 `/tmp/quantumclaw/quantumclaw-*.log` 并过滤 `web-heartbeat`、`web-reconnect`、`web-auto-reply`、`web-inbound`。
+
+## 深度诊断
+
+- 磁盘上的凭证：`ls -l ~/.quantumclaw/credentials/whatsapp/<accountId>/creds.json`（mtime 应该是最近的）。
+- 会话存储：`ls -l ~/.quantumclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。计数和最近收件人通过 `status` 显示。
+- 重新链接流程：当日志中出现状态码 409–515 或 `loggedOut` 时，执行 `quantumclaw channels logout && quantumclaw channels login --verbose`。（注意：配对后状态 515 时 QR 登录流程会自动重启一次。）
+
+## 当出现故障时
+
+- `logged out` 或状态 409–515 → 使用 `quantumclaw channels logout` 然后 `quantumclaw channels login` 重新链接。
+- Gateway 网关不可达 → 启动它：`quantumclaw gateway --port 18789`（如果端口被占用则使用 `--force`）。
+- 没有入站消息 → 确认已链接的手机在线且发送者被允许（`channels.whatsapp.allowFrom`）；对于群聊，确保允许列表 + 提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
+
+## 专用"health"命令
+
+`quantumclaw health --json` 向运行中的 Gateway 网关请求其健康快照（CLI 不直接访问渠道套接字）。它报告已链接凭证/认证时长（如可用）、每渠道探测摘要、会话存储摘要和探测持续时间。如果 Gateway 网关不可达或探测失败/超时，它以非零退出。使用 `--timeout <ms>` 覆盖默认的 10 秒。