@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/gateway/bridge-protocol.md

@@ -0,0 +1,86 @@
+---
+read_when:
+  - 构建或调试节点客户端（iOS/Android/macOS 节点模式）
+  - 调查配对或 bridge 认证失败
+  - 审计 Gateway 网关暴露的节点接口
+summary: Bridge 协议（旧版节点）：TCP JSONL、配对、作用域 RPC
+title: Bridge 协议
+x-i18n:
+  generated_at: "2026-02-03T07:47:42Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 789bcf3cbc6841fc293e054b919e63d661b3cc4cd205b2094289f00800127fe2
+  source_path: gateway/bridge-protocol.md
+  workflow: 15
+---
+
+# Bridge 协议（旧版节点传输）
+
+Bridge 协议是一个**旧版**节点传输（TCP JSONL）。新的节点客户端应该使用统一的 Gateway 网关 WebSocket 协议。
+
+如果你正在构建操作者或节点客户端，请使用 [Gateway 网关协议](/gateway/protocol)。
+
+**注意：** 当前的 QuantumClaw 构建不再包含 TCP bridge 监听器；本文档仅作历史参考保留。
+旧版 `bridge.*` 配置键不再是配置模式的一部分。
+
+## 为什么我们有两种协议
+
+- **安全边界**：bridge 暴露一个小的允许列表，而不是完整的 Gateway 网关 API 接口。
+- **配对 + 节点身份**：节点准入由 Gateway 网关管理，并与每节点令牌绑定。
+- **设备发现用户体验**：节点可以通过局域网上的 Bonjour 发现 Gateway 网关，或通过 tailnet 直接连接。
+- **Loopback WS**：完整的 WS 控制平面保持本地，除非通过 SSH 隧道。
+
+## 传输
+
+- TCP，每行一个 JSON 对象（JSONL）。
+- 可选 TLS（当 `bridge.tls.enabled` 为 true 时）。
+- 旧版默认监听端口为 `18790`（当前构建不启动 TCP bridge）。
+
+当 TLS 启用时，设备发现 TXT 记录包含 `bridgeTls=1` 加上 `bridgeTlsSha256`，以便节点可以固定证书。
+
+## 握手 + 配对
+
+1. 客户端发送带有节点元数据 + 令牌（如果已配对）的 `hello`。
+2. 如果未配对，Gateway 网关回复 `error`（`NOT_PAIRED`/`UNAUTHORIZED`）。
+3. 客户端发送 `pair-request`。
+4. Gateway 网关等待批准，然后发送 `pair-ok` 和 `hello-ok`。
+
+`hello-ok` 返回 `serverName`，可能包含 `canvasHostUrl`。
+
+## 帧
+
+客户端 → Gateway 网关：
+
+- `req` / `res`：作用域 Gateway 网关 RPC（chat、sessions、config、health、voicewake、skills.bins）
+- `event`：节点信号（语音转录、智能体请求、聊天订阅、exec 生命周期）
+
+Gateway 网关 → 客户端：
+
+- `invoke` / `invoke-res`：节点命令（`canvas.*`、`camera.*`、`screen.record`、`location.get`、`sms.send`）
+- `event`：已订阅会话的聊天更新
+- `ping` / `pong`：保活
+
+旧版允许列表强制执行位于 `src/gateway/server-bridge.ts`（已移除）。
+
+## Exec 生命周期事件
+
+节点可以发出 `exec.finished` 或 `exec.denied` 事件来表面化 system.run 活动。
+这些被映射到 Gateway 网关中的系统事件。（旧版节点可能仍会发出 `exec.started`。）
+
+Payload 字段（除非注明，否则都是可选的）：
+
+- `sessionKey`（必需）：接收系统事件的智能体会话。
+- `runId`：用于分组的唯一 exec id。
+- `command`：原始或格式化的命令字符串。
+- `exitCode`、`timedOut`、`success`、`output`：完成详情（仅限 finished）。
+- `reason`：拒绝原因（仅限 denied）。
+
+## Tailnet 使用
+
+- 将 bridge 绑定到 tailnet IP：在 `~/.quantumclaw/quantumclaw.json` 中设置 `bridge.bind: "tailnet"`。
+- 客户端通过 MagicDNS 名称或 tailnet IP 连接。
+- Bonjour **不**跨网络；需要时使用手动主机/端口或广域 DNS‑SD。
+
+## 版本控制
+
+Bridge 目前是**隐式 v1**（无最小/最大协商）。预期向后兼容；在任何破坏性变更之前添加 bridge 协议版本字段。

package/docs/zh-CN/gateway/cli-backends.md

@@ -0,0 +1,213 @@
+---
+read_when:
+  - 你想要一个在 API 提供商失败时的可靠回退
+  - 你正在运行 Claude Code CLI 或其他本地 AI CLI 并想要复用它们
+  - 你需要一个纯文本、无工具的路径，但仍支持会话和图像
+summary: CLI 后端：通过本地 AI CLI 实现纯文本回退
+title: CLI 后端
+x-i18n:
+  generated_at: "2026-02-03T07:47:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 56a96e83b16a4f6443cbf4a9da7a660c41a5b178af5e13f35352c9d72e1b08dd
+  source_path: gateway/cli-backends.md
+  workflow: 15
+---
+
+# CLI 后端（回退运行时）
+
+当 API 提供商宕机、被限流或暂时异常时，QuantumClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是有意保守的设计：
+
+- **工具被禁用**（无工具调用）。
+- **文本输入 → 文本输出**（可靠）。
+- **支持会话**（因此后续轮次保持连贯）。
+- 如果 CLI 接受图像路径，**图像可以传递**。
+
+这被设计为**安全网**而非主要路径。当你想要"始终有效"的文本响应而不依赖外部 API 时使用它。
+
+## 新手友好快速开始
+
+你可以**无需任何配置**使用 Claude Code CLI（QuantumClaw 自带内置默认值）：
+
+```bash
+quantumclaw agent --message "hi" --model claude-cli/opus-4.5
+```
+
+Codex CLI 也可以开箱即用：
+
+```bash
+quantumclaw agent --message "hi" --model codex-cli/gpt-5.2-codex
+```
+
+如果你的 Gateway 网关在 launchd/systemd 下运行且 PATH 很精简，只需添加命令路径：
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+      },
+    },
+  },
+}
+```
+
+就这样。除了 CLI 本身外，不需要密钥，不需要额外的认证配置。
+
+## 作为回退使用
+
+将 CLI 后端添加到你的回退列表中，这样它只在主要模型失败时运行：
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-5",
+        fallbacks: ["claude-cli/opus-4.5"],
+      },
+      models: {
+        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "claude-cli/opus-4.5": {},
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- 如果你使用 `agents.defaults.models`（允许列表），必须包含 `claude-cli/...`。
+- 如果主要提供商失败（认证、限流、超时），QuantumClaw 将接着尝试 CLI 后端。
+
+## 配置概览
+
+所有 CLI 后端位于：
+
+```
+agents.defaults.cliBackends
+```
+
+每个条目以**提供商 ID**（例如 `claude-cli`、`my-cli`）为键。提供商 ID 成为你的模型引用的左侧部分：
+
+```
+<provider>/<model>
+```
+
+### 配置示例
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          input: "arg",
+          modelArg: "--model",
+          modelAliases: {
+            "claude-opus-4-5": "opus",
+            "claude-sonnet-4-5": "sonnet",
+          },
+          sessionArg: "--session",
+          sessionMode: "existing",
+          sessionIdFields: ["session_id", "conversation_id"],
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          serialize: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## 工作原理
+
+1. **选择后端**基于提供商前缀（`claude-cli/...`）。
+2. **构建系统提示**使用相同的 QuantumClaw 提示 + 工作区上下文。
+3. **执行 CLI**并带有会话 ID（如果支持），使历史记录保持一致。
+4. **解析输出**（JSON 或纯文本）并返回最终文本。
+5. **持久化会话 ID**按后端，使后续请求复用相同的 CLI 会话。
+
+## 会话
+
+- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`）当 ID 需要插入到多个标志中时。
+- 如果 CLI 使用带有不同标志的**恢复子命令**，设置 `resumeArgs`（恢复时替换 `args`）以及可选的 `resumeOutput`（用于非 JSON 恢复）。
+- `sessionMode`：
+  - `always`：始终发送会话 ID（如果没有存储则使用新 UUID）。
+  - `existing`：仅在之前存储了会话 ID 时才发送。
+  - `none`：从不发送会话 ID。
+
+## 图像（传递）
+
+如果你的 CLI 接受图像路径，设置 `imageArg`：
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+QuantumClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些路径作为 CLI 参数传递。如果缺少 `imageArg`，QuantumClaw 会将文件路径附加到提示中（路径注入），这对于从纯路径自动加载本地文件的 CLI 来说已经足够（Claude Code CLI 行为）。
+
+## 输入 / 输出
+
+- `output: "json"`（默认）尝试解析 JSON 并提取文本 + 会话 ID。
+- `output: "jsonl"` 解析 JSONL 流（Codex CLI `--json`）并提取最后一条智能体消息以及存在时的 `thread_id`。
+- `output: "text"` 将 stdout 视为最终响应。
+
+输入模式：
+
+- `input: "arg"`（默认）将提示作为最后一个 CLI 参数传递。
+- `input: "stdin"` 通过 stdin 发送提示。
+- 如果提示很长且设置了 `maxPromptArgChars`，则使用 stdin。
+
+## 默认值（内置）
+
+QuantumClaw 自带 `claude-cli` 的默认值：
+
+- `command: "claude"`
+- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
+- `resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]`
+- `modelArg: "--model"`
+- `systemPromptArg: "--append-system-prompt"`
+- `sessionArg: "--session-id"`
+- `systemPromptWhen: "first"`
+- `sessionMode: "always"`
+
+QuantumClaw 也自带 `codex-cli` 的默认值：
+
+- `command: "codex"`
+- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `output: "jsonl"`
+- `resumeOutput: "text"`
+- `modelArg: "--model"`
+- `imageArg: "--image"`
+- `sessionMode: "existing"`
+
+仅在需要时覆盖（常见：绝对 `command` 路径）。
+
+## 限制
+
+- **无 QuantumClaw 工具**（CLI 后端永远不会收到工具调用）。某些 CLI 可能仍会运行它们自己的智能体工具。
+- **无流式传输**（CLI 输出被收集后返回）。
+- **结构化输出**取决于 CLI 的 JSON 格式。
+- **Codex CLI 会话**通过文本输出恢复（无 JSONL），这比初始的 `--json` 运行结构化程度低。QuantumClaw 会话仍然正常工作。
+
+## 故障排除
+
+- **找不到 CLI**：将 `command` 设置为完整路径。
+- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
+- **无会话连续性**：确保设置了 `sessionArg` 且 `sessionMode` 不是 `none`（Codex CLI 目前无法使用 JSON 输出恢复）。
+- **图像被忽略**：设置 `imageArg`（并验证 CLI 支持文件路径）。