@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/gateway/openresponses-http-api.md

@@ -0,0 +1,317 @@
+---
+read_when:
+  - 集成使用 OpenResponses API 的客户端
+  - 你需要基于 item 的输入、客户端工具调用或 SSE 事件
+summary: 从 Gateway 网关暴露兼容 OpenResponses 的 /v1/responses HTTP 端点
+title: OpenResponses API
+x-i18n:
+  generated_at: "2026-02-03T07:48:43Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0597714837f8b210c38eeef53561894220c1473e54c56a5c69984847685d518c
+  source_path: gateway/openresponses-http-api.md
+  workflow: 15
+---
+
+# OpenResponses API（HTTP）
+
+QuantumClaw 的 Gateway 网关可以提供兼容 OpenResponses 的 `POST /v1/responses` 端点。
+
+此端点**默认禁用**。请先在配置中启用。
+
+- `POST /v1/responses`
+- 与 Gateway 网关相同的端口（WS + HTTP 多路复用）：`http://<gateway-host>:<port>/v1/responses`
+
+底层实现中，请求作为正常的 Gateway 网关智能体运行执行（与 `quantumclaw agent` 相同的代码路径），因此路由/权限/配置与你的 Gateway 网关一致。
+
+## 认证
+
+使用 Gateway 网关认证配置。发送 bearer 令牌：
+
+- `Authorization: Bearer <token>`
+
+说明：
+
+- 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `QUANTUMCLAW_GATEWAY_TOKEN`）。
+- 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `QUANTUMCLAW_GATEWAY_PASSWORD`）。
+
+## 选择智能体
+
+无需自定义头：在 OpenResponses `model` 字段中编码智能体 id：
+
+- `model: "quantumclaw:<agentId>"`（示例：`"quantumclaw:main"`、`"quantumclaw:beta"`）
+- `model: "agent:<agentId>"`（别名）
+
+或通过头指定特定的 QuantumClaw 智能体：
+
+- `x-quantumclaw-agent-id: <agentId>`（默认：`main`）
+
+高级：
+
+- `x-quantumclaw-session-key: <sessionKey>` 完全控制会话路由。
+
+## 启用端点
+
+将 `gateway.http.endpoints.responses.enabled` 设置为 `true`：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: { enabled: true },
+      },
+    },
+  },
+}
+```
+
+## 禁用端点
+
+将 `gateway.http.endpoints.responses.enabled` 设置为 `false`：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: { enabled: false },
+      },
+    },
+  },
+}
+```
+
+## 会话行为
+
+默认情况下，端点**每个请求都是无状态的**（每次调用生成新的会话键）。
+
+如果请求包含 OpenResponses `user` 字符串，Gateway 网关会从中派生稳定的会话键，这样重复调用可以共享智能体会话。
+
+## 请求结构（支持的）
+
+请求遵循 OpenResponses API，使用基于 item 的输入。当前支持：
+
+- `input`：字符串或 item 对象数组。
+- `instructions`：合并到系统提示中。
+- `tools`：客户端工具定义（函数工具）。
+- `tool_choice`：过滤或要求客户端工具。
+- `stream`：启用 SSE 流式传输。
+- `max_output_tokens`：尽力而为的输出限制（取决于提供商）。
+- `user`：稳定的会话路由。
+
+接受但**当前忽略**：
+
+- `max_tool_calls`
+- `reasoning`
+- `metadata`
+- `store`
+- `previous_response_id`
+- `truncation`
+
+## Item（输入）
+
+### `message`
+
+角色：`system`、`developer`、`user`、`assistant`。
+
+- `system` 和 `developer` 追加到系统提示。
+- 最近的 `user` 或 `function_call_output` item 成为"当前消息"。
+- 较早的 user/assistant 消息作为上下文历史包含。
+
+### `function_call_output`（基于回合的工具）
+
+将工具结果发送回模型：
+
+```json
+{
+  "type": "function_call_output",
+  "call_id": "call_123",
+  "output": "{\"temperature\": \"72F\"}"
+}
+```
+
+### `reasoning` 和 `item_reference`
+
+为了 schema 兼容性而接受，但在构建提示时忽略。
+
+## 工具（客户端函数工具）
+
+使用 `tools: [{ type: "function", function: { name, description?, parameters? } }]` 提供工具。
+
+如果智能体决定调用工具，响应返回一个 `function_call` 输出 item。然后你发送带有 `function_call_output` 的后续请求以继续回合。
+
+## 图像（`input_image`）
+
+支持 base64 或 URL 来源：
+
+```json
+{
+  "type": "input_image",
+  "source": { "type": "url", "url": "https://example.com/image.png" }
+}
+```
+
+允许的 MIME 类型（当前）：`image/jpeg`、`image/png`、`image/gif`、`image/webp`。
+最大大小（当前）：10MB。
+
+## 文件（`input_file`）
+
+支持 base64 或 URL 来源：
+
+```json
+{
+  "type": "input_file",
+  "source": {
+    "type": "base64",
+    "media_type": "text/plain",
+    "data": "SGVsbG8gV29ybGQh",
+    "filename": "hello.txt"
+  }
+}
+```
+
+允许的 MIME 类型（当前）：`text/plain`、`text/markdown`、`text/html`、`text/csv`、`application/json`、`application/pdf`。
+
+最大大小（当前）：5MB。
+
+当前行为：
+
+- 文件内容被解码并添加到**系统提示**，而不是用户消息，所以它保持临时性（不持久化在会话历史中）。
+- PDF 被解析提取文本。如果发现的文本很少，前几页会被栅格化为图像并传递给模型。
+
+PDF 解析使用 Node 友好的 `pdfjs-dist` legacy 构建（无 worker）。现代 PDF.js 构建期望浏览器 worker/DOM 全局变量，因此不在 Gateway 网关中使用。
+
+URL 获取默认值：
+
+- `files.allowUrl`：`true`
+- `images.allowUrl`：`true`
+- 请求受到保护（DNS 解析、私有 IP 阻止、重定向限制、超时）。
+
+## 文件 + 图像限制（配置）
+
+默认值可在 `gateway.http.endpoints.responses` 下调整：
+
+```json5
+{
+  gateway: {
+    http: {
+      endpoints: {
+        responses: {
+          enabled: true,
+          maxBodyBytes: 20000000,
+          files: {
+            allowUrl: true,
+            allowedMimes: [
+              "text/plain",
+              "text/markdown",
+              "text/html",
+              "text/csv",
+              "application/json",
+              "application/pdf",
+            ],
+            maxBytes: 5242880,
+            maxChars: 200000,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+            pdf: {
+              maxPages: 4,
+              maxPixels: 4000000,
+              minTextChars: 200,
+            },
+          },
+          images: {
+            allowUrl: true,
+            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+            maxBytes: 10485760,
+            maxRedirects: 3,
+            timeoutMs: 10000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+省略时的默认值：
+
+- `maxBodyBytes`：20MB
+- `files.maxBytes`：5MB
+- `files.maxChars`：200k
+- `files.maxRedirects`：3
+- `files.timeoutMs`：10s
+- `files.pdf.maxPages`：4
+- `files.pdf.maxPixels`：4,000,000
+- `files.pdf.minTextChars`：200
+- `images.maxBytes`：10MB
+- `images.maxRedirects`：3
+- `images.timeoutMs`：10s
+
+## 流式传输（SSE）
+
+设置 `stream: true` 接收 Server-Sent Events（SSE）：
+
+- `Content-Type: text/event-stream`
+- 每个事件行是 `event: <type>` 和 `data: <json>`
+- 流以 `data: [DONE]` 结束
+
+当前发出的事件类型：
+
+- `response.created`
+- `response.in_progress`
+- `response.output_item.added`
+- `response.content_part.added`
+- `response.output_text.delta`
+- `response.output_text.done`
+- `response.content_part.done`
+- `response.output_item.done`
+- `response.completed`
+- `response.failed`（出错时）
+
+## 用量
+
+当底层提供商报告令牌计数时，`usage` 会被填充。
+
+## 错误
+
+错误使用如下 JSON 对象：
+
+```json
+{ "error": { "message": "...", "type": "invalid_request_error" } }
+```
+
+常见情况：
+
+- `401` 缺少/无效认证
+- `400` 无效请求体
+- `405` 错误的方法
+
+## 示例
+
+非流式：
+
+```bash
+curl -sS http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "input": "hi"
+  }'
+```
+
+流式：
+
+```bash
+curl -N http://127.0.0.1:18789/v1/responses \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'x-quantumclaw-agent-id: main' \
+  -d '{
+    "model": "quantumclaw",
+    "stream": true,
+    "input": "hi"
+  }'
+```

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

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 在没有 macOS UI 的情况下实现节点配对审批
+  - 添加用于审批远程节点的 CLI 流程
+  - 扩展 Gateway 网关协议以支持节点管理
+summary: Gateway 网关拥有的节点配对（选项 B），用于 iOS 和其他远程节点
+title: Gateway 网关拥有的配对
+x-i18n:
+  generated_at: "2026-02-03T07:48:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1f5154292a75ea2c1470324babc99c6c46a5e4e16afb394ed323d28f6168f459
+  source_path: gateway/pairing.md
+  workflow: 15
+---
+
+# Gateway 网关拥有的配对（选项 B）
+
+在 Gateway 网关拥有的配对中，**Gateway 网关**是允许哪些节点加入的唯一信息源。UI（macOS 应用、未来的客户端）只是审批或拒绝待处理请求的前端。
+
+**重要：**WS 节点在 `connect` 期间使用**设备配对**（角色 `node`）。`node.pair.*` 是一个独立的配对存储，**不会**限制 WS 握手。只有显式调用 `node.pair.*` 的客户端使用此流程。
+
+## 概念
+
+- **待处理请求**：一个节点请求加入；需要审批。
+- **已配对节点**：已批准的节点，带有已颁发的认证令牌。
+- **传输层**：Gateway 网关 WS 端点转发请求但不决定成员资格。（旧版 TCP 桥接支持已弃用/移除。）
+
+## 配对工作原理
+
+1. 节点连接到 Gateway 网关 WS 并请求配对。
+2. Gateway 网关存储一个**待处理请求**并发出 `node.pair.requested`。
+3. 你审批或拒绝该请求（CLI 或 UI）。
+4. 审批后，Gateway 网关颁发一个**新令牌**（重新配对时令牌会轮换）。
+5. 节点使用该令牌重新连接，现在是"已配对"状态。
+
+待处理请求在 **5 分钟**后自动过期。
+
+## CLI 工作流程（支持无头模式）
+
+```bash
+quantumclaw nodes pending
+quantumclaw nodes approve <requestId>
+quantumclaw nodes reject <requestId>
+quantumclaw nodes status
+quantumclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
+```
+
+`nodes status` 显示已配对/已连接的节点及其功能。
+
+## API 接口（Gateway 网关协议）
+
+事件：
+
+- `node.pair.requested` — 创建新的待处理请求时发出。
+- `node.pair.resolved` — 请求被批准/拒绝/过期时发出。
+
+方法：
+
+- `node.pair.request` — 创建或复用待处理请求。
+- `node.pair.list` — 列出待处理 + 已配对的节点。
+- `node.pair.approve` — 批准待处理请求（颁发令牌）。
+- `node.pair.reject` — 拒绝待处理请求。
+- `node.pair.verify` — 验证 `{ nodeId, token }`。
+
+注意事项：
+
+- `node.pair.request` 对每个节点是幂等的：重复调用返回相同的待处理请求。
+- 审批**总是**生成新的令牌；`node.pair.request` 永远不会返回令牌。
+- 请求可以包含 `silent: true` 作为自动审批流程的提示。
+
+## 自动审批（macOS 应用）
+
+当满足以下条件时，macOS 应用可以选择尝试**静默审批**：
+
+- 请求标记为 `silent`，且
+- 应用可以使用相同用户验证到 Gateway 网关主机的 SSH 连接。
+
+如果静默审批失败，则回退到正常的"批准/拒绝"提示。
+
+## 存储（本地，私有）
+
+配对状态存储在 Gateway 网关状态目录下（默认 `~/.quantumclaw`）：
+
+- `~/.quantumclaw/nodes/paired.json`
+- `~/.quantumclaw/nodes/pending.json`
+
+如果你覆盖了 `QUANTUMCLAW_STATE_DIR`，`nodes/` 文件夹会随之移动。
+
+安全注意事项：
+
+- 令牌是机密信息；将 `paired.json` 视为敏感文件。
+- 轮换令牌需要重新审批（或删除节点条目）。
+
+## 传输层行为
+
+- 传输层是**无状态的**；它不存储成员资格。
+- 如果 Gateway 网关离线或配对被禁用，节点无法配对。
+- 如果 Gateway 网关处于远程模式，配对仍然针对远程 Gateway 网关的存储进行。

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

@@ -0,0 +1,220 @@
+---
+read_when:
+  - 实现或更新 Gateway 网关 WS 客户端
+  - 调试协议不匹配或连接失败
+  - 重新生成协议模式/模型
+summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
+title: Gateway 网关协议
+x-i18n:
+  generated_at: "2026-02-03T07:48:42Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bdafac40d53565901b2df450617287664d77fe4ff52681fa00cab9046b2fd850
+  source_path: gateway/protocol.md
+  workflow: 15
+---
+
+# Gateway 网关协议（WebSocket）
+
+Gateway 网关 WS 协议是 QuantumClaw 的**单一控制平面 + 节点传输**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
+
+## 传输
+
+- WebSocket，带有 JSON 负载的文本帧。
+- 第一帧**必须**是 `connect` 请求。
+
+## 握手（connect）
+
+Gateway 网关 → 客户端（连接前质询）：
+
+```json
+{
+  "type": "event",
+  "event": "connect.challenge",
+  "payload": { "nonce": "…", "ts": 1737264000000 }
+}
+```
+
+客户端 → Gateway 网关：
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "cli",
+      "version": "1.2.3",
+      "platform": "macos",
+      "mode": "operator"
+    },
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"],
+    "caps": [],
+    "commands": [],
+    "permissions": {},
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "quantumclaw-cli/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+Gateway 网关 → 客户端：
+
+```json
+{
+  "type": "res",
+  "id": "…",
+  "ok": true,
+  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
+}
+```
+
+当颁发设备令牌时，`hello-ok` 还包含：
+
+```json
+{
+  "auth": {
+    "deviceToken": "…",
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"]
+  }
+}
+```
+
+### 节点示例
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "ios-node",
+      "version": "1.2.3",
+      "platform": "ios",
+      "mode": "node"
+    },
+    "role": "node",
+    "scopes": [],
+    "caps": ["camera", "canvas", "screen", "location", "voice"],
+    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
+    "permissions": { "camera.capture": true, "screen.record": false },
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "quantumclaw-ios/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000,
+      "nonce": "…"
+    }
+  }
+}
+```
+
+## 帧格式
+
+- **Request**：`{type:"req", id, method, params}`
+- **Response**：`{type:"res", id, ok, payload|error}`
+- **Event**：`{type:"event", event, payload, seq?, stateVersion?}`
+
+有副作用的方法需要**幂等键**（见模式）。
+
+## 角色 + 作用域
+
+### 角色
+
+- `operator` = 控制平面客户端（CLI/UI/自动化）。
+- `node` = 能力宿主（camera/screen/canvas/system.run）。
+
+### 作用域（operator）
+
+常用作用域：
+
+- `operator.read`
+- `operator.write`
+- `operator.admin`
+- `operator.approvals`
+- `operator.pairing`
+
+### 能力/命令/权限（node）
+
+节点在连接时声明能力声明：
+
+- `caps`：高级能力类别。
+- `commands`：invoke 的命令允许列表。
+- `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
+
+Gateway 网关将这些视为**声明**并强制执行服务器端允许列表。
+
+## 在线状态
+
+- `system-presence` 返回以设备身份为键的条目。
+- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，以便 UI 可以为每个设备显示单行，
+  即使它同时以 **operator** 和 **node** 身份连接。
+
+### 节点辅助方法
+
+- 节点可以调用 `skills.bins` 来获取当前的 skill 可执行文件列表，
+  用于自动允许检查。
+
+## Exec 审批
+
+- 当 exec 请求需要审批时，Gateway 网关广播 `exec.approval.requested`。
+- 操作者客户端通过调用 `exec.approval.resolve` 来解决（需要 `operator.approvals` 作用域）。
+
+## 版本控制
+
+- `PROTOCOL_VERSION` 在 `src/gateway/protocol/schema.ts` 中。
+- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的。
+- 模式 + 模型从 TypeBox 定义生成：
+  - `pnpm protocol:gen`
+  - `pnpm protocol:gen:swift`
+  - `pnpm protocol:check`
+
+## 认证
+
+- 如果设置了 `QUANTUMCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token`
+  必须匹配，否则套接字将被关闭。
+- 配对后，Gateway 网关会颁发一个作用于连接角色 + 作用域的**设备令牌**。它在 `hello-ok.auth.deviceToken` 中返回，
+  客户端应将其持久化以供将来连接使用。
+- 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
+
+## 设备身份 + 配对
+
+- 节点应包含从密钥对指纹派生的稳定设备身份（`device.id`）。
+- Gateway 网关为每个设备 + 角色颁发令牌。
+- 新设备 ID 需要配对批准，除非启用了本地自动批准。
+- **本地**连接包括 loopback 和 Gateway 网关主机自身的 tailnet 地址
+  （因此同主机 tailnet 绑定仍可自动批准）。
+- 所有 WS 客户端在 `connect` 期间必须包含 `device` 身份（operator + node）。
+  控制 UI **仅**在启用 `gateway.controlUi.allowInsecureAuth` 时可以省略它
+  （或使用 `gateway.controlUi.dangerouslyDisableDeviceAuth` 用于紧急情况）。
+- 非本地连接必须签署服务器提供的 `connect.challenge` nonce。
+
+## TLS + 固定
+
+- WS 连接支持 TLS。
+- 客户端可以选择性地固定 Gateway 网关证书指纹（见 `gateway.tls`
+  配置加上 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
+
+## 范围
+
+此协议暴露**完整的 Gateway 网关 API**（status、channels、models、chat、
+agent、sessions、nodes、approvals 等）。确切的接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox 模式定义。