@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,123 @@
+---
+read_when:
+  - 正在开发 Gateway 网关协议、客户端或传输层
+summary: WebSocket Gateway 网关架构、组件和客户端流程
+title: Gateway 网关架构
+x-i18n:
+  generated_at: "2026-02-03T07:45:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c636d5d8a5e628067432b30671466309e3d630b106d413f1708765bf2a9399a1
+  source_path: concepts/architecture.md
+  workflow: 15
+---
+
+# Gateway 网关架构
+
+最后更新：2026-01-22
+
+## 概述
+
+- 单个长期运行的 **Gateway 网关**拥有所有消息平台（通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
+- 控制平面客户端（macOS 应用、CLI、Web 界面、自动化）通过配置的绑定主机（默认 `127.0.0.1:18789`）上的 **WebSocket** 连接到 Gateway 网关。
+- **节点**（macOS/iOS/Android/无头设备）也通过 **WebSocket** 连接，但声明 `role: node` 并带有明确的能力/命令。
+- 每台主机一个 Gateway 网关；它是唯一打开 WhatsApp 会话的位置。
+- **canvas 主机**（默认 `18793`）提供智能体可编辑的 HTML 和 A2UI。
+
+## 组件和流程
+
+### Gateway 网关（守护进程）
+
+- 维护提供商连接。
+- 暴露类型化的 WS API（请求、响应、服务器推送事件）。
+- 根据 JSON Schema 验证入站帧。
+- 发出事件如 `agent`、`chat`、`presence`、`health`、`heartbeat`、`cron`。
+
+### 客户端（mac 应用 / CLI / web 管理）
+
+- 每个客户端一个 WS 连接。
+- 发送请求（`health`、`status`、`send`、`agent`、`system-presence`）。
+- 订阅事件（`tick`、`agent`、`presence`、`shutdown`）。
+
+### 节点（macOS / iOS / Android / 无头设备）
+
+- 以 `role: node` 连接到**同一个 WS 服务器**。
+- 在 `connect` 中提供设备身份；配对是**基于设备**的（角色为 `node`），批准存储在设备配对存储中。
+- 暴露命令如 `canvas.*`、`camera.*`、`screen.record`、`location.get`。
+
+协议详情：
+
+- [Gateway 网关协议](/gateway/protocol)
+
+### WebChat
+
+- 静态界面，使用 Gateway 网关 WS API 获取聊天历史和发送消息。
+- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。
+
+## 连接生命周期（单个客户端）
+
+```
+Client                    Gateway
+  |                          |
+  |---- req:connect -------->|
+  |<------ res (ok) ---------|   (or res error + close)
+  |   (payload=hello-ok carries snapshot: presence + health)
+  |                          |
+  |<------ event:presence ---|
+  |<------ event:tick -------|
+  |                          |
+  |------- req:agent ------->|
+  |<------ res:agent --------|   (ack: {runId,status:"accepted"})
+  |<------ event:agent ------|   (streaming)
+  |<------ res:agent --------|   (final: {runId,status,summary})
+  |                          |
+```
+
+## 线路协议（摘要）
+
+- 传输：WebSocket，带 JSON 载荷的文本帧。
+- 第一帧**必须**是 `connect`。
+- 握手后：
+  - 请求：`{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - 事件：`{type:"event", event, payload, seq?, stateVersion?}`
+- 如果设置了 `QUANTUMCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token` 必须匹配，否则套接字关闭。
+- 有副作用的方法（`send`、`agent`）需要幂等键以安全重试；服务器保持短期去重缓存。
+- 节点必须在 `connect` 中包含 `role: "node"` 以及能力/命令/权限。
+
+## 配对 + 本地信任
+
+- 所有 WS 客户端（操作员 + 节点）在 `connect` 时包含**设备身份**。
+- 新设备 ID 需要配对批准；Gateway 网关为后续连接颁发**设备令牌**。
+- **本地**连接（loopback 或 Gateway 网关主机自身的 tailnet 地址）可以自动批准以保持同主机用户体验流畅。
+- **非本地**连接必须签名 `connect.challenge` nonce 并需要明确批准。
+- Gateway 网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。
+
+详情：[Gateway 网关协议](/gateway/protocol)、[配对](/channels/pairing)、[安全](/gateway/security)。
+
+## 协议类型和代码生成
+
+- TypeBox 模式定义协议。
+- 从这些模式生成 JSON Schema。
+- 从 JSON Schema 生成 Swift 模型。
+
+## 远程访问
+
+- 推荐：Tailscale 或 VPN。
+- 替代方案：SSH 隧道
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+- 相同的握手 + 认证令牌适用于隧道连接。
+- 远程设置中可以为 WS 启用 TLS + 可选的证书固定。
+
+## 操作快照
+
+- 启动：`quantumclaw gateway`（前台，日志输出到 stdout）。
+- 健康检查：通过 WS 的 `health`（也包含在 `hello-ok` 中）。
+- 监控：使用 launchd/systemd 自动重启。
+
+## 不变量
+
+- 每台主机恰好一个 Gateway 网关控制单个 Baileys 会话。
+- 握手是强制的；任何非 JSON 或非 connect 的第一帧都会导致硬关闭。
+- 事件不会重放；客户端必须在出现间隙时刷新。

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

@@ -0,0 +1,67 @@
+---
+read_when:
+  - 你想了解自动压缩和 /compact
+  - 你正在调试长会话触及上下文限制的问题
+summary: 上下文窗口 + 压缩：QuantumClaw 如何将会话保持在模型限制内
+title: 压缩
+x-i18n:
+  generated_at: "2026-02-01T20:22:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e1d6791f2902044b5798ebf9320a7d055d37211eff4be03caa35d7e328ae803c
+  source_path: concepts/compaction.md
+  workflow: 14
+---
+
+# 上下文窗口与压缩
+
+每个模型都有一个**上下文窗口**（可见的最大 token 数）。长时间运行的对话会累积消息和工具结果；一旦窗口空间紧张，QuantumClaw 会**压缩**较早的历史记录以保持在限制范围内。
+
+## 什么是压缩
+
+压缩会将**较早的对话总结**为一条紧凑的摘要条目，并保持近期消息不变。摘要存储在会话历史中，因此后续请求使用的是：
+
+- 压缩摘要
+- 压缩点之后的近期消息
+
+压缩会**持久化**到会话的 JSONL 历史记录中。
+
+## 配置
+
+有关 `agents.defaults.compaction` 设置，请参阅[压缩配置与模式](/concepts/compaction)。
+
+## 自动压缩（默认开启）
+
+当会话接近或超过模型的上下文窗口时，QuantumClaw 会触发自动压缩，并可能使用压缩后的上下文重试原始请求。
+
+你会看到：
+
+- 详细模式下显示 `🧹 Auto-compaction complete`
+- `/status` 显示 `🧹 Compactions: <count>`
+
+在压缩之前，QuantumClaw 可以运行一次**静默记忆刷写**轮次，将持久化笔记写入磁盘。详情及配置请参阅[记忆](/concepts/memory)。
+
+## 手动压缩
+
+使用 `/compact`（可选附带指令）强制执行一次压缩：
+
+```
+/compact Focus on decisions and open questions
+```
+
+## 上下文窗口来源
+
+上下文窗口因模型而异。QuantumClaw 使用已配置提供商目录中的模型定义来确定限制。
+
+## 压缩与修剪
+
+- **压缩**：总结并**持久化**到 JSONL 中。
+- **会话修剪**：仅裁剪旧的**工具结果**，**在内存中**按请求进行。
+
+有关修剪的详情，请参阅 [/concepts/session-pruning](/concepts/session-pruning)。
+
+## 提示
+
+- 当会话感觉过时或上下文臃肿时，使用 `/compact`。
+- 大型工具输出已被截断；修剪可以进一步减少工具结果的堆积。
+- 如果你需要全新开始，`/new` 或 `/reset` 会启动一个新的会话 ID。

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

@@ -0,0 +1,168 @@
+---
+read_when:
+  - 你想了解 QuantumClaw 中"上下文"的含义
+  - 你在调试为什么模型"知道"某些内容（或忘记了）
+  - 你想减少上下文开销（/context、/status、/compact）
+summary: 上下文：模型看到的内容、如何构建以及如何检查
+title: 上下文
+x-i18n:
+  generated_at: "2026-02-03T07:46:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b32867b9b93254fdd1077d0d97c203cabfdba3330bb941693c83feba8e5db0cc
+  source_path: concepts/context.md
+  workflow: 15
+---
+
+# 上下文
+
+"上下文"是 **QuantumClaw 在一次运行中发送给模型的所有内容**。它受模型的**上下文窗口**（token 限制）约束。
+
+新手心智模型：
+
+- **系统提示词**（QuantumClaw 构建）：规则、工具、Skills 列表、时间/运行时，以及注入的工作区文件。
+- **对话历史**：你的消息 + 助手在此会话中的消息。
+- **工具调用/结果 + 附件**：命令输出、文件读取、图片/音频等。
+
+上下文与"记忆"_不是同一回事_：记忆可以存储在磁盘上并稍后重新加载；上下文是模型当前窗口内的内容。
+
+## 快速开始（检查上下文）
+
+- `/status` → 快速查看"我的窗口有多满？" + 会话设置。
+- `/context list` → 注入了什么 + 大致大小（每个文件 + 总计）。
+- `/context detail` → 更深入的分解：每个文件、每个工具 schema 大小、每个 Skills 条目大小和系统提示词大小。
+- `/usage tokens` → 在正常回复后附加每次回复的使用量页脚。
+- `/compact` → 将较旧的历史总结为紧凑条目以释放窗口空间。
+
+另请参阅：[斜杠命令](/tools/slash-commands)、[Token 使用与成本](/reference/token-use)、[压缩](/concepts/compaction)。
+
+## 示例输出
+
+数值因模型、提供商、工具策略和工作区内容而异。
+
+### `/context list`
+
+```
+🧠 Context breakdown
+Workspace: <workspaceDir>
+Bootstrap max/file: 20,000 chars
+Sandbox: mode=non-main sandboxed=false
+System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
+
+Injected workspace files:
+- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
+- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
+- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
+- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
+- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
+- HEARTBEAT.md: MISSING | raw 0 | injected 0
+- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
+
+Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
+Tools: read, edit, write, exec, process, browser, message, sessions_send, …
+Tool list (system prompt text): 1,032 chars (~258 tok)
+Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
+Tools: (same as above)
+
+Session tokens (cached): 14,250 total / ctx=32,000
+```
+
+### `/context detail`
+
+```
+🧠 Context breakdown (detailed)
+…
+Top skills (prompt entry size):
+- frontend-design: 412 chars (~103 tok)
+- oracle: 401 chars (~101 tok)
+… (+10 more skills)
+
+Top tools (schema size):
+- browser: 9,812 chars (~2,453 tok)
+- exec: 6,240 chars (~1,560 tok)
+… (+N more tools)
+```
+
+## 什么计入上下文窗口
+
+模型接收的所有内容都计入，包括：
+
+- 系统提示词（所有部分）。
+- 对话历史。
+- 工具调用 + 工具结果。
+- 附件/转录（图片/音频/文件）。
+- 压缩摘要和修剪产物。
+- 提供商"包装器"或隐藏头部（不可见，仍然计数）。
+
+## QuantumClaw 如何构建系统提示词
+
+系统提示词由 **QuantumClaw 拥有**，每次运行时重建。它包括：
+
+- 工具列表 + 简短描述。
+- Skills 列表（仅元数据；见下文）。
+- 工作区位置。
+- 时间（UTC + 如果配置了则转换为用户时间）。
+- 运行时元数据（主机/操作系统/模型/思考）。
+- 在**项目上下文**下注入的工作区引导文件。
+
+完整分解：[系统提示词](/concepts/system-prompt)。
+
+## 注入的工作区文件（项目上下文）
+
+默认情况下，QuantumClaw 注入一组固定的工作区文件（如果存在）：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md`（仅首次运行）
+
+大文件按文件使用 `agents.defaults.bootstrapMaxChars`（默认 `20000` 字符）截断。`/context` 显示**原始 vs 注入**大小以及是否发生了截断。
+
+## Skills：注入的内容 vs 按需加载的内容
+
+系统提示词包含一个紧凑的 **Skills 列表**（名称 + 描述 + 位置）。此列表有实际开销。
+
+Skill 指令默认*不*包含。模型应该**仅在需要时**`read` Skill 的 `SKILL.md`。
+
+## 工具：有两种成本
+
+工具以两种方式影响上下文：
+
+1. 系统提示词中的**工具列表文本**（你看到的"Tooling"）。
+2. **工具 schema**（JSON）。这些发送给模型以便它可以调用工具。它们计入上下文，即使你看不到它们作为纯文本。
+
+`/context detail` 分解最大的工具 schema，以便你可以看到什么占主导。
+
+## 命令、指令和"内联快捷方式"
+
+斜杠命令由 Gateway 网关处理。有几种不同的行为：
+
+- **独立命令**：仅为 `/...` 的消息作为命令运行。
+- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/model`、`/queue` 在模型看到消息之前被剥离。
+  - 仅指令消息会持久化会话设置。
+  - 正常消息中的内联指令作为每条消息的提示。
+- **内联快捷方式**（仅允许列表中的发送者）：正常消息中的某些 `/...` token 可以立即运行（例如："hey /status"），并在模型看到剩余文本之前被剥离。
+
+详情：[斜杠命令](/tools/slash-commands)。
+
+## 会话、压缩和修剪（什么会持久化）
+
+什么在消息之间持久化取决于机制：
+
+- **正常历史**在会话记录中持久化，直到被策略压缩/修剪。
+- **压缩**将摘要持久化到记录中，并保持最近的消息不变。
+- **修剪**从运行的*内存中*提示词中删除旧的工具结果，但不重写记录。
+
+文档：[会话](/concepts/session)、[压缩](/concepts/compaction)、[会话修剪](/concepts/session-pruning)。
+
+## `/context` 实际报告什么
+
+`/context` 在可用时优先使用最新的**运行构建的**系统提示词报告：
+
+- `System prompt (run)` = 从最后一次嵌入式（具有工具能力的）运行中捕获，并持久化在会话存储中。
+- `System prompt (estimate)` = 当没有运行报告存在时（或通过不生成报告的 CLI 后端运行时）即时计算。
+
+无论哪种方式，它都报告大小和主要贡献者；它**不会**转储完整的系统提示词或工具 schema。

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

@@ -0,0 +1,59 @@
+---
+read_when:
+  - 你想了解 QuantumClaw 支持的完整功能列表
+summary: QuantumClaw 在渠道、路由、媒体和用户体验方面的功能。
+title: 功能
+x-i18n:
+  generated_at: "2026-02-04T17:53:22Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1b6aee0bfda751824cb6b3a99080b4c80c00ffb355a96f9cff1b596d55d15ed4
+  source_path: concepts/features.md
+  workflow: 15
+---
+
+## 亮点
+
+<Columns>
+  <Card title="渠道" icon="message-square">
+    通过单个 Gateway 网关支持 WhatsApp、Telegram、Discord 和 iMessage。
+  </Card>
+  <Card title="插件" icon="plug">
+    通过扩展添加 Mattermost 等更多平台。
+  </Card>
+  <Card title="路由" icon="route">
+    多智能体路由，支持隔离会话。
+  </Card>
+  <Card title="媒体" icon="image">
+    支持图片、音频和文档的收发。
+  </Card>
+  <Card title="应用与界面" icon="monitor">
+    Web 控制界面和 macOS 配套应用。
+  </Card>
+  <Card title="移动节点" icon="smartphone">
+    iOS 和 Android 节点，支持 Canvas。
+  </Card>
+</Columns>
+
+## 完整列表
+
+- 通过 WhatsApp Web（Baileys）集成 WhatsApp
+- Telegram 机器人支持（grammY）
+- Discord 机器人支持（channels.discord.js）
+- Mattermost 机器人支持（插件）
+- 通过本地 imsg CLI 集成 iMessage（macOS）
+- Pi 的智能体桥接，支持 RPC 模式和工具流式传输
+- 长响应的流式传输和分块处理
+- 多智能体路由，按工作区或发送者隔离会话
+- 通过 OAuth 进行 Anthropic 和 OpenAI 的订阅认证
+- 会话：私信合并为共享的 `main`；群组相互隔离
+- 群聊支持，通过提及激活
+- 图片、音频和文档的媒体支持
+- 可选的语音消息转录钩子
+- WebChat 和 macOS 菜单栏应用
+- iOS 节点，支持配对和 Canvas 界面
+- Android 节点，支持配对、Canvas、聊天和相机
+
+<Note>
+旧版 Claude、Codex、Gemini 和 Opencode 路径已被移除。Pi 是唯一的编程智能体路径。
+</Note>

package/docs/zh-CN/concepts/markdown-formatting.md

@@ -0,0 +1,117 @@
+---
+read_when:
+  - 你正在更改出站渠道的 Markdown 格式化或分块逻辑
+  - 你正在添加新的渠道格式化器或样式映射
+  - 你正在调试跨渠道的格式化回归问题
+summary: 出站渠道的 Markdown 格式化管道
+title: Markdown 格式化
+x-i18n:
+  generated_at: "2026-02-01T20:22:42Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f9cbf9b744f9a218860730f29435bcad02d3db80b1847fed5f17c063c97d4820
+  source_path: concepts/markdown-formatting.md
+  workflow: 14
+---
+
+# Markdown 格式化
+
+QuantumClaw 通过将出站 Markdown 转换为共享的中间表示（IR），然后再渲染为特定渠道的输出来进行格式化。IR 保留源文本不变，同时携带样式/链接跨度信息，使分块和渲染在各渠道间保持一致。
+
+## 目标
+
+- **一致性：**一次解析，多个渲染器。
+- **安全分块：**在渲染前拆分文本，确保行内格式不会跨块断裂。
+- **渠道适配：**将同一 IR 映射到 Slack mrkdwn、Telegram HTML 和 Signal 样式范围，无需重新解析 Markdown。
+
+## 管道
+
+1. **解析 Markdown -> IR**
+   - IR 是纯文本加上样式跨度（粗体/斜体/删除线/代码/剧透）和链接跨度。
+   - 偏移量使用 UTF-16 代码单元，以便 Signal 样式范围与其 API 对齐。
+   - 仅当渠道启用了表格转换时才会解析表格。
+2. **分块 IR（格式优先）**
+   - 分块在渲染前对 IR 文本进行操作。
+   - 行内格式不会跨块拆分；跨度按块进行切片。
+3. **按渠道渲染**
+   - **Slack：** mrkdwn 标记（粗体/斜体/删除线/代码），链接格式为 `<url|label>`。
+   - **Telegram：** HTML 标签（`<b>`、`<i>`、`<s>`、`<code>`、`<pre><code>`、`<a href>`）。
+   - **Signal：** 纯文本 + `text-style` 范围；当标签与 URL 不同时，链接变为 `label (url)`。
+
+## IR 示例
+
+输入 Markdown：
+
+```markdown
+Hello **world** — see [docs](https://docs.quantumclaw.ai).
+```
+
+IR（示意）：
+
+```json
+{
+  "text": "Hello world — see docs.",
+  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
+  "links": [{ "start": 19, "end": 23, "href": "https://docs.quantumclaw.ai" }]
+}
+```
+
+## 使用场景
+
+- Slack、Telegram 和 Signal 的出站适配器从 IR 进行渲染。
+- 其他渠道（WhatsApp、iMessage、Microsoft Teams、Discord）仍使用纯文本或各自的格式化规则，启用时会在分块前应用 Markdown 表格转换。
+
+## 表格处理
+
+Markdown 表格在各聊天客户端中的支持并不一致。使用 `markdown.tables` 按渠道（和按账户）控制转换方式。
+
+- `code`：将表格渲染为代码块（大多数渠道的默认设置）。
+- `bullets`：将每行转换为项目符号列表（Signal + WhatsApp 的默认设置）。
+- `off`：禁用表格解析和转换；原始表格文本直接透传。
+
+配置键：
+
+```yaml
+channels:
+  discord:
+    markdown:
+      tables: code
+    accounts:
+      work:
+        markdown:
+          tables: off
+```
+
+## 分块规则
+
+- 分块限制来自渠道适配器/配置，应用于 IR 文本。
+- 代码围栏作为单个块保留，并带有尾部换行符，以确保渠道正确渲染。
+- 列表前缀和引用块前缀是 IR 文本的一部分，因此分块不会在前缀中间拆分。
+- 行内样式（粗体/斜体/删除线/行内代码/剧透）不会跨块拆分；渲染器会在每个块内重新打开样式。
+
+如需了解更多跨渠道的分块行为，请参见[流式传输 + 分块](/concepts/streaming)。
+
+## 链接策略
+
+- **Slack：** `[label](url)` -> `<url|label>`；裸 URL 保持原样。解析时禁用自动链接以避免重复链接。
+- **Telegram：** `[label](url)` -> `<a href="url">label</a>`（HTML 解析模式）。
+- **Signal：** `[label](url)` -> `label (url)`，除非标签与 URL 匹配。
+
+## 剧透
+
+剧透标记（`||spoiler||`）仅为 Signal 解析，映射为 SPOILER 样式范围。其他渠道将其视为纯文本。
+
+## 如何添加或更新渠道格式化器
+
+1. **解析一次：**使用共享的 `markdownToIR(...)` 辅助函数，传入适合渠道的选项（自动链接、标题样式、引用块前缀）。
+2. **渲染：**使用 `renderMarkdownWithMarkers(...)` 和样式标记映射（或 Signal 样式范围）实现渲染器。
+3. **分块：**在渲染前调用 `chunkMarkdownIR(...)`；逐块渲染。
+4. **接入适配器：**更新渠道出站适配器以使用新的分块器和渲染器。
+5. **测试：**添加或更新格式测试，如果渠道使用分块，还需添加出站投递测试。
+
+## 常见陷阱
+
+- Slack 尖括号标记（`<@U123>`、`<#C123>`、`<https://...>`）必须保留；安全转义原始 HTML。
+- Telegram HTML 要求对标签外的文本进行转义，以避免标记损坏。
+- Signal 样式范围依赖 UTF-16 偏移量；不要使用码点偏移量。
+- 保留代码围栏的尾部换行符，以确保闭合标记独占一行。