@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/concepts/oauth.md

@@ -0,0 +1,164 @@
+---
+read_when:
+  - 你想端到端了解 QuantumClaw OAuth
+  - 你遇到了令牌失效/登出问题
+  - 你想使用 setup-token 或 OAuth 认证流程
+  - 你想使用多个账户或配置文件路由
+summary: QuantumClaw 中的 OAuth：令牌交换、存储和多账户模式
+title: OAuth
+x-i18n:
+  generated_at: "2026-03-16T06:22:05Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 976668c3e02ee50500fcaaa585a89af718398dc41988318ec3a583c2d5449df3
+  source_path: concepts/oauth.md
+  workflow: 15
+---
+
+# OAuth
+
+QuantumClaw 通过 OAuth 支持提供商提供的“订阅认证”，适用于支持此方式的提供商（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。过去有些用户在 Claude Code 之外使用 Anthropic 订阅时曾受限，因此这应视为用户自行选择承担的风险，你应自行核实 Anthropic 当前的政策。OpenAI Codex OAuth 明确支持在 QuantumClaw 这样的外部工具中使用。本页说明：
+
+对于生产环境中的 Anthropic，相比订阅 setup-token 认证，API 密钥认证是更安全、也更推荐的路径。
+
+- OAuth **令牌交换** 如何工作（PKCE）
+- 令牌**存储**在哪里（以及为什么）
+- 如何处理**多个账户**（配置文件 + 按会话覆盖）
+
+QuantumClaw 也支持自带 OAuth 或 API 密钥流程的**提供商插件**。运行方式如下：
+
+```bash
+quantumclaw models auth login --provider <id>
+```
+
+## 令牌汇点（为什么需要它）
+
+OAuth 提供商通常会在登录/刷新流程中签发一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。
+
+实际症状：
+
+- 你同时通过 QuantumClaw _和_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“被登出”
+
+为减少这种情况，QuantumClaw 将 `auth-profiles.json` 视为一个**令牌汇点**：
+
+- 运行时从**同一个地方**读取凭证
+- 我们可以保留多个配置文件，并进行确定性路由
+
+## 存储（令牌存放位置）
+
+密钥按**每个智能体**存储：
+
+- 认证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`
+- 旧版兼容文件：`~/.quantumclaw/agents/<agentId>/agent/auth.json`
+  （发现静态 `api_key` 条目时会进行清理）
+
+仅用于旧版导入的文件（仍受支持，但不是主存储）：
+
+- `~/.quantumclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）
+
+以上所有位置也都遵循 `$QUANTUMCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
+
+有关静态密钥引用和运行时快照激活行为，请参见 [Secrets Management](/gateway/secrets)。
+
+## Anthropic setup-token（订阅认证）
+
+<Warning>
+Anthropic setup-token 支持是技术兼容性，并非策略保证。
+Anthropic 过去曾阻止过某些在 Claude Code 之外的订阅使用。
+是否使用订阅认证由你自行决定，并请核实 Anthropic 当前的条款。
+</Warning>
+
+在任意机器上运行 `claude setup-token`，然后将其粘贴到 QuantumClaw 中：
+
+```bash
+quantumclaw models auth setup-token --provider anthropic
+```
+
+如果你是在其他地方生成的令牌，可手动粘贴：
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+```
+
+验证：
+
+```bash
+quantumclaw models status
+```
+
+## OAuth 交换（登录如何工作）
+
+QuantumClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并接入到各类向导/命令中。
+
+### Anthropic setup-token
+
+流程形态：
+
+1. 运行 `claude setup-token`
+2. 将令牌粘贴到 QuantumClaw
+3. 存储为令牌认证配置文件（不刷新）
+
+向导路径为 `quantumclaw onboard` → 认证选择 `setup-token`（Anthropic）。
+
+### OpenAI Codex（ChatGPT OAuth）
+
+OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 QuantumClaw 工作流。
+
+流程形态（PKCE）：
+
+1. 生成 PKCE verifier/challenge 和随机 `state`
+2. 打开 `https://auth.openai.com/oauth/authorize?...`
+3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
+4. 如果回调无法绑定（或你是在远程/无头环境中），则粘贴重定向 URL/code
+5. 在 `https://auth.openai.com/oauth/token` 交换令牌
+6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
+
+向导路径为 `quantumclaw onboard` → 认证选择 `openai-codex`。
+
+## 刷新和过期
+
+配置文件会存储一个 `expires` 时间戳。
+
+在运行时：
+
+- 如果 `expires` 尚未到期 → 使用已存储的访问令牌
+- 如果已过期 → 在文件锁下刷新，并覆盖已存储的凭证
+
+刷新流程是自动的；通常你不需要手动管理令牌。
+
+## 多个账户（配置文件）+ 路由
+
+有两种模式：
+
+### 1）推荐：分离的智能体
+
+如果你希望“个人”和“工作”永不交叉，请使用隔离的智能体（独立的会话 + 凭证 + 工作区）：
+
+```bash
+quantumclaw agents add work
+quantumclaw agents add personal
+```
+
+然后按智能体配置认证（使用向导），并将聊天路由到正确的智能体。
+
+### 2）高级：单个智能体中的多个配置文件
+
+`auth-profiles.json` 支持同一提供商下的多个配置文件 ID。
+
+选择使用哪个配置文件：
+
+- 通过配置排序全局选择（`auth.order`）
+- 通过 `/model ...@<profileId>` 按会话选择
+
+示例（会话覆盖）：
+
+- `/model Opus@anthropic:work`
+
+查看现有配置文件 ID 的方法：
+
+- `quantumclaw channels list --json`（显示 `auth[]`）
+
+相关文档：
+
+- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
+- [/tools/slash-commands](/tools/slash-commands)（命令入口）

package/docs/zh-CN/concepts/presence.md

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 调试实例标签页
+  - 排查重复或过期的实例行
+  - 更改 Gateway 网关 WS 连接或系统事件信标
+summary: QuantumClaw 在线状态条目如何生成、合并和显示
+title: 在线状态
+x-i18n:
+  generated_at: "2026-02-03T07:46:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
+  source_path: concepts/presence.md
+  workflow: 15
+---
+
+# 在线状态
+
+QuantumClaw"在线状态"是以下内容的轻量级、尽力而为的视图：
+
+- **Gateway 网关**本身，以及
+- **连接到 Gateway 网关的客户端**（mac 应用、WebChat、CLI 等）
+
+在线状态主要用于渲染 macOS 应用的**实例**标签页，并为运维人员提供快速可见性。
+
+## 在线状态字段（显示的内容）
+
+在线状态条目是具有以下字段的结构化对象：
+
+- `instanceId`（可选但强烈推荐）：稳定的客户端身份（通常是 `connect.client.instanceId`）
+- `host`：人类友好的主机名
+- `ip`：尽力而为的 IP 地址
+- `version`：客户端版本字符串
+- `deviceFamily` / `modelIdentifier`：硬件提示
+- `mode`：`ui`、`webchat`、`cli`、`backend`、`probe`、`test`、`node`，...
+- `lastInputSeconds`："自上次用户输入以来的秒数"（如果已知）
+- `reason`：`self`、`connect`、`node-connected`、`periodic`，...
+- `ts`：最后更新时间戳（自纪元以来的毫秒数）
+
+## 生产者（在线状态来源）
+
+在线状态条目由多个来源生成并**合并**。
+
+### 1）Gateway 网关自身条目
+
+Gateway 网关始终在启动时植入一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway 网关主机。
+
+### 2）WebSocket 连接
+
+每个 WS 客户端都以 `connect` 请求开始。在成功握手后，Gateway 网关为该连接更新插入一个在线状态条目。
+
+#### 为什么一次性 CLI 命令不会显示
+
+CLI 经常为短暂的一次性命令进行连接。为避免实例列表被刷屏，`client.mode === "cli"` **不会**被转换为在线状态条目。
+
+### 3）`system-event` 信标
+
+客户端可以通过 `system-event` 方法发送更丰富的周期性信标。mac 应用使用此方法报告主机名、IP 和 `lastInputSeconds`。
+
+### 4）节点连接（role: node）
+
+当节点通过 Gateway 网关 WebSocket 以 `role: node` 连接时，Gateway 网关为该节点更新插入一个在线状态条目（与其他 WS 客户端流程相同）。
+
+## 合并 + 去重规则（为什么 `instanceId` 很重要）
+
+在线状态条目存储在单个内存映射中：
+
+- 条目以**在线状态键**为索引。
+- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），它在重启后仍然有效。
+- 键不区分大小写。
+
+如果客户端在没有稳定 `instanceId` 的情况下重新连接，它可能会显示为**重复**行。
+
+## TTL 和有界大小
+
+在线状态是有意设计为短暂的：
+
+- **TTL：** 超过 5 分钟的条目会被修剪
+- **最大条目数：** 200（最旧的优先删除）
+
+这使列表保持新鲜并避免无限制的内存增长。
+
+## 远程/隧道注意事项（回环 IP）
+
+当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 网关可能会看到远程地址为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。
+
+## 消费者
+
+### macOS 实例标签页
+
+macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间应用一个小的状态指示器（活跃/空闲/过期）。
+
+## 调试技巧
+
+- 要查看原始列表，对 Gateway 网关调用 `system-presence`。
+- 如果你看到重复项：
+  - 确认客户端在握手中发送稳定的 `client.instanceId`
+  - 确认周期性信标使用相同的 `instanceId`
+  - 检查连接派生的条目是否缺少 `instanceId`（这种情况下重复是预期的）

package/docs/zh-CN/concepts/queue.md

@@ -0,0 +1,94 @@
+---
+read_when:
+  - 更改自动回复执行或并发设置时
+summary: 用于序列化入站自动回复运行的命令队列设计
+title: 命令队列
+x-i18n:
+  generated_at: "2026-02-03T10:05:28Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 2104c24d200fb4f9620e52a19255cd614ababe19d78f3ee42936dc6d0499b73b
+  source_path: concepts/queue.md
+  workflow: 15
+---
+
+# 命令队列（2026-01-16）
+
+我们通过一个小型进程内队列序列化入站自动回复运行（所有渠道），以防止多个智能体运行发生冲突，同时仍允许跨会话的安全并行。
+
+## 为什么需要
+
+- 自动回复运行可能开销很大（LLM 调用），当多条入站消息接近同时到达时可能发生冲突。
+- 序列化可以避免竞争共享资源（会话文件、日志、CLI stdin），并降低上游速率限制的可能性。
+
+## 工作原理
+
+- 一个支持通道感知的 FIFO 队列以可配置的并发上限排空每个通道（未配置的通道默认为 1；main 默认为 4，subagent 为 8）。
+- `runEmbeddedPiAgent` 按**会话键**入队（通道 `session:<key>`），以保证每个会话只有一个活动运行。
+- 然后每个会话运行被排入**全局通道**（默认为 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
+- 启用详细日志时，如果排队运行在开始前等待超过约 2 秒，会发出简短通知。
+- 输入指示器仍在入队时立即触发（当渠道支持时），因此在等待轮次时用户体验不受影响。
+
+## 队列模式（按渠道）
+
+入站消息可以引导当前运行、等待后续轮次，或两者兼顾：
+
+- `steer`：立即注入当前运行（在下一个工具边界后取消待处理的工具调用）。如果未在流式传输，则回退到 followup。
+- `followup`：在当前运行结束后为下一个智能体轮次入队。
+- `collect`：将所有排队消息合并为**单个**后续轮次（默认）。如果消息针对不同的渠道/线程，它们会单独排空以保留路由。
+- `steer-backlog`（又名 `steer+backlog`）：现在引导**并**保留消息用于后续轮次。
+- `interrupt`（旧版）：中止该会话的活动运行，然后运行最新消息。
+- `queue`（旧版别名）：与 `steer` 相同。
+
+steer-backlog 意味着你可以在被引导的运行之后获得后续响应，因此流式传输界面可能看起来像重复。如果你希望每条入站消息只有一个响应，请优先使用 `collect`/`steer`。
+发送 `/queue collect` 作为独立命令（按会话）或设置 `messages.queue.byChannel.discord: "collect"`。
+
+默认值（配置中未设置时）：
+
+- 所有界面 → `collect`
+
+通过 `messages.queue` 全局或按渠道配置：
+
+```json5
+{
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byChannel: { discord: "collect" },
+    },
+  },
+}
+```
+
+## 队列选项
+
+选项适用于 `followup`、`collect` 和 `steer-backlog`（以及当 `steer` 回退到 followup 时）：
+
+- `debounceMs`：在开始后续轮次前等待静默（防止"继续，继续"）。
+- `cap`：每个会话的最大排队消息数。
+- `drop`：溢出策略（`old`、`new`、`summarize`）。
+
+summarize 保留被丢弃消息的简短要点列表，并将其作为合成的后续提示注入。
+默认值：`debounceMs: 1000`、`cap: 20`、`drop: summarize`。
+
+## 按会话覆盖
+
+- 发送 `/queue <mode>` 作为独立命令，为当前会话存储该模式。
+- 选项可以组合：`/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` 或 `/queue reset` 清除会话覆盖。
+
+## 范围和保证
+
+- 适用于所有使用 Gateway 网关回复管道的入站渠道的自动回复智能体运行（WhatsApp 网页版、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
+- 默认通道（`main`）对入站 + 主心跳是进程范围的；设置 `agents.defaults.maxConcurrent` 以允许多个会话并行。
+- 可能存在额外的通道（例如 `cron`、`subagent`），以便后台任务可以并行运行而不阻塞入站回复。
+- 按会话通道保证一次只有一个智能体运行触及给定会话。
+- 无外部依赖或后台工作线程；纯 TypeScript + promises。
+
+## 故障排除
+
+- 如果命令似乎卡住，启用详细日志并查找"queued for …ms"行以确认队列正在排空。
+- 如果你需要查看队列深度，启用详细日志并观察队列计时行。

package/docs/zh-CN/concepts/retry.md

@@ -0,0 +1,76 @@
+---
+read_when:
+  - 更新提供商重试行为或默认值
+  - 调试提供商发送错误或速率限制
+summary: 出站提供商调用的重试策略
+title: 重试策略
+x-i18n:
+  generated_at: "2026-02-01T20:23:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 55bb261ff567f46ce447be9c0ee0c5b5e6d2776287d7662762656c14108dd607
+  source_path: concepts/retry.md
+  workflow: 14
+---
+
+# 重试策略
+
+## 目标
+
+- 按 HTTP 请求重试，而非按多步骤流程重试。
+- 通过仅重试当前步骤来保持顺序。
+- 避免重复执行非幂等操作。
+
+## 默认值
+
+- 尝试次数：3
+- 最大延迟上限：30000 毫秒
+- 抖动：0.1（10%）
+- 提供商默认值：
+  - Telegram 最小延迟：400 毫秒
+  - Discord 最小延迟：500 毫秒
+
+## 行为
+
+### Discord
+
+- 仅在速率限制错误（HTTP 429）时重试。
+- 可用时使用 Discord `retry_after`，否则使用指数退避。
+
+### Telegram
+
+- 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。
+- 可用时使用 `retry_after`，否则使用指数退避。
+- Markdown 解析错误不会重试；会回退为纯文本。
+
+## 配置
+
+在 `~/.quantumclaw/quantumclaw.json` 中按提供商设置重试策略：
+
+```json5
+{
+  channels: {
+    telegram: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 400,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+    discord: {
+      retry: {
+        attempts: 3,
+        minDelayMs: 500,
+        maxDelayMs: 30000,
+        jitter: 0.1,
+      },
+    },
+  },
+}
+```
+
+## 注意事项
+
+- 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。
+- 组合流程不会重试已完成的步骤。

package/docs/zh-CN/concepts/session-pruning.md

@@ -0,0 +1,129 @@
+---
+read_when:
+  - 你想减少工具输出导致的 LLM 上下文增长
+  - 你正在调整 agents.defaults.contextPruning
+summary: 会话剪枝：工具结果修剪以减少上下文膨胀
+x-i18n:
+  generated_at: "2026-02-03T07:46:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9b0aa2d1abea7050ba848a2db038ccc3e6e2d83c6eb4e3843a2ead0ab847574a
+  source_path: concepts/session-pruning.md
+  workflow: 15
+---
+
+# 会话剪枝
+
+会话剪枝在每次 LLM 调用之前从内存上下文中修剪**旧的工具结果**。它**不会**重写磁盘上的会话历史（`*.jsonl`）。
+
+## 运行时机
+
+- 当启用 `mode: "cache-ttl"` 且该会话的最后一次 Anthropic 调用早于 `ttl` 时。
+- 仅影响该请求发送给模型的消息。
+- 仅对 Anthropic API 调用（和 OpenRouter Anthropic 模型）生效。
+- 为获得最佳效果，请将 `ttl` 与你的模型 `cacheControlTtl` 匹配。
+- 剪枝后，TTL 窗口会重置，因此后续请求会保持缓存直到 `ttl` 再次过期。
+
+## 智能默认值（Anthropic）
+
+- **OAuth 或 setup-token** 配置文件：启用 `cache-ttl` 剪枝并将心跳设置为 `1h`。
+- **API 密钥**配置文件：启用 `cache-ttl` 剪枝，将心跳设置为 `30m`，并将 Anthropic 模型的 `cacheControlTtl` 默认为 `1h`。
+- 如果你显式设置了这些值中的任何一个，QuantumClaw **不会**覆盖它们。
+
+## 改进内容（成本 + 缓存行为）
+
+- **为什么要剪枝：** Anthropic 提示缓存仅在 TTL 内适用。如果会话空闲超过 TTL，下一个请求会重新缓存完整提示，除非你先修剪它。
+- **什么变得更便宜：** 剪枝减少了 TTL 过期后第一个请求的 **cacheWrite** 大小。
+- **为什么 TTL 重置很重要：** 一旦剪枝运行，缓存窗口会重置，因此后续请求可以重用新缓存的提示，而不是再次重新缓存完整历史。
+- **它不做什么：** 剪枝不会添加 token 或"双倍"成本；它只改变该 TTL 后第一个请求缓存的内容。
+
+## 可以剪枝的内容
+
+- 仅 `toolResult` 消息。
+- 用户 + 助手消息**永远不会**被修改。
+- 最后 `keepLastAssistants` 条助手消息受保护；该截止点之后的工具结果不会被剪枝。
+- 如果没有足够的助手消息来确定截止点，则跳过剪枝。
+- 包含**图像块**的工具结果会被跳过（永不修剪/清除）。
+
+## 上下文窗口估算
+
+剪枝使用估算的上下文窗口（字符 ≈ token × 4）。基础窗口按以下顺序解析：
+
+1. `models.providers.*.models[].contextWindow` 覆盖。
+2. 模型定义 `contextWindow`（来自模型注册表）。
+3. 默认 `200000` token。
+
+如果设置了 `agents.defaults.contextTokens`，它将被视为解析窗口的上限（最小值）。
+
+## 模式
+
+### cache-ttl
+
+- 仅当最后一次 Anthropic 调用早于 `ttl`（默认 `5m`）时才运行剪枝。
+- 运行时：与之前相同的软修剪 + 硬清除行为。
+
+## 软剪枝 vs 硬剪枝
+
+- **软修剪**：仅用于过大的工具结果。
+  - 保留头部 + 尾部，插入 `...`，并附加一个包含原始大小的注释。
+  - 跳过包含图像块的结果。
+- **硬清除**：用 `hardClear.placeholder` 替换整个工具结果。
+
+## 工具选择
+
+- `tools.allow` / `tools.deny` 支持 `*` 通配符。
+- 拒绝优先。
+- 匹配不区分大小写。
+- 允许列表为空 => 允许所有工具。
+
+## 与其他限制的交互
+
+- 内置工具已经截断自己的输出；会话剪枝是一个额外的层，防止长时间运行的聊天在模型上下文中累积过多的工具输出。
+- 压缩是独立的：压缩进行总结并持久化，剪枝是每个请求的临时操作。参阅 [/concepts/compaction](/concepts/compaction)。
+
+## 默认值（启用时）
+
+- `ttl`：`"5m"`
+- `keepLastAssistants`：`3`
+- `softTrimRatio`：`0.3`
+- `hardClearRatio`：`0.5`
+- `minPrunableToolChars`：`50000`
+- `softTrim`：`{ maxChars: 4000, headChars: 1500, tailChars: 1500 }`
+- `hardClear`：`{ enabled: true, placeholder: "[Old tool result content cleared]" }`
+
+## 示例
+
+默认（关闭）：
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "off" },
+  },
+}
+```
+
+启用 TTL 感知剪枝：
+
+```json5
+{
+  agent: {
+    contextPruning: { mode: "cache-ttl", ttl: "5m" },
+  },
+}
+```
+
+限制剪枝到特定工具：
+
+```json5
+{
+  agent: {
+    contextPruning: {
+      mode: "cache-ttl",
+      tools: { allow: ["exec", "read"], deny: ["*image*"] },
+    },
+  },
+}
+```
+
+参阅配置参考：[Gateway 网关配置](/gateway/configuration)