@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,96 @@
+---
+read_when:
+  - 需要了解时间戳如何为模型进行规范化
+  - 为系统提示词配置用户时区
+summary: 智能体、信封和提示词的时区处理
+title: 时区
+x-i18n:
+  generated_at: "2026-02-01T20:24:13Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9ee809c96897db1126c7efcaa5bf48a63cdcb2092abd4b3205af224ebd882766
+  source_path: concepts/timezone.md
+  workflow: 14
+---
+
+# 时区
+
+QuantumClaw 对时间戳进行标准化，使模型看到**单一的参考时间**。
+
+## 消息信封（默认为本地时间）
+
+入站消息被包装在如下信封中：
+
+```
+[Provider ... 2026-01-05 16:26 PST] message text
+```
+
+信封中的时间戳**默认为主机本地时间**，精确到分钟。
+
+你可以通过以下配置进行覆盖：
+
+```json5
+{
+  agents: {
+    defaults: {
+      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区
+      envelopeTimestamp: "on", // "on" | "off"
+      envelopeElapsed: "on", // "on" | "off"
+    },
+  },
+}
+```
+
+- `envelopeTimezone: "utc"` 使用 UTC。
+- `envelopeTimezone: "user"` 使用 `agents.defaults.userTimezone`（回退到主机时区）。
+- 使用显式 IANA 时区（例如 `"Europe/Vienna"`）可设置固定偏移量。
+- `envelopeTimestamp: "off"` 从信封头中移除绝对时间戳。
+- `envelopeElapsed: "off"` 移除已用时间后缀（`+2m` 样式）。
+
+### 示例
+
+**本地时间（默认）：**
+
+```
+[Signal Alice +1555 2026-01-18 00:19 PST] hello
+```
+
+**固定时区：**
+
+```
+[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello
+```
+
+**已用时间：**
+
+```
+[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up
+```
+
+## 工具负载（原始提供商数据 + 规范化字段）
+
+工具调用（`channels.discord.readMessages`、`channels.slack.readMessages` 等）返回**原始提供商时间戳**。我们还附加规范化字段以保持一致性：
+
+- `timestampMs`（UTC 纪元毫秒数）
+- `timestampUtc`（ISO 8601 UTC 字符串）
+
+原始提供商字段保持不变。
+
+## 系统提示词的用户时区
+
+设置 `agents.defaults.userTimezone` 来告知模型用户的本地时区。如果未设置，QuantumClaw 会在运行时**解析主机时区**（无需写入配置）。
+
+```json5
+{
+  agents: { defaults: { userTimezone: "America/Chicago" } },
+}
+```
+
+系统提示词包含：
+
+- `Current Date & Time` 部分，显示本地时间和时区
+- `Time format: 12-hour` 或 `24-hour`
+
+你可以通过 `agents.defaults.timeFormat`（`auto` | `12` | `24`）控制提示词格式。
+
+详情参见[日期与时间](/date-time)的完整行为和示例。

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

@@ -0,0 +1,284 @@
+---
+read_when:
+  - 更新协议模式或代码生成
+summary: TypeBox 模式作为 Gateway 网关协议的唯一事实来源
+title: TypeBox
+x-i18n:
+  generated_at: "2026-02-03T07:47:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 233800f4f5fabe8ed0e1b3d8aded2eca27252e08c9b0b24ea9c6293e9282c918
+  source_path: concepts/typebox.md
+  workflow: 15
+---
+
+# TypeBox 作为协议的事实来源
+
+最后更新：2026-01-10
+
+TypeBox 是一个 TypeScript 优先的模式库。我们用它来定义 **Gateway 网关 WebSocket 协议**（握手、请求/响应、服务器事件）。这些模式驱动**运行时验证**、**JSON Schema 导出**和 macOS 应用的 **Swift 代码生成**。一个事实来源；其他一切都是生成的。
+
+如果你想了解更高层次的协议上下文，请从 [Gateway 网关架构](/concepts/architecture)开始。
+
+## 心智模型（30 秒）
+
+每个 Gateway 网关 WS 消息都是以下三种帧之一：
+
+- **Request**：`{ type: "req", id, method, params }`
+- **Response**：`{ type: "res", id, ok, payload | error }`
+- **Event**：`{ type: "event", event, payload, seq?, stateVersion? }`
+
+第一个帧**必须**是 `connect` 请求。之后，客户端可以调用方法（例如 `health`、`send`、`chat.send`）并订阅事件（例如 `presence`、`tick`、`agent`）。
+
+连接流程（最小）：
+
+```
+Client                    Gateway
+  |---- req:connect -------->|
+  |<---- res:hello-ok --------|
+  |<---- event:tick ----------|
+  |---- req:health ---------->|
+  |<---- res:health ----------|
+```
+
+常用方法 + 事件：
+
+| 类别 | 示例                                                      | 说明                            |
+| ---- | --------------------------------------------------------- | ------------------------------- |
+| 核心 | `connect`、`health`、`status`                             | `connect` 必须是第一个          |
+| 消息 | `send`、`poll`、`agent`、`agent.wait`                     | 有副作用的需要 `idempotencyKey` |
+| 聊天 | `chat.history`、`chat.send`、`chat.abort`、`chat.inject`  | WebChat 使用这些                |
+| 会话 | `sessions.list`、`sessions.patch`、`sessions.delete`      | 会话管理                        |
+| 节点 | `node.list`、`node.invoke`、`node.pair.*`                 | Gateway 网关 WS + 节点操作      |
+| 事件 | `tick`、`presence`、`agent`、`chat`、`health`、`shutdown` | 服务器推送                      |
+
+权威列表在 `src/gateway/server.ts`（`METHODS`、`EVENTS`）中。
+
+## 模式所在位置
+
+- 源码：`src/gateway/protocol/schema.ts`
+- 运行时验证器（AJV）：`src/gateway/protocol/index.ts`
+- 服务器握手 + 方法分发：`src/gateway/server.ts`
+- 节点客户端：`src/gateway/client.ts`
+- 生成的 JSON Schema：`dist/protocol.schema.json`
+- 生成的 Swift 模型：`apps/macos/Sources/QuantumClawProtocol/GatewayModels.swift`
+
+## 当前流程
+
+- `pnpm protocol:gen`
+  - 将 JSON Schema（draft‑07）写入 `dist/protocol.schema.json`
+- `pnpm protocol:gen:swift`
+  - 生成 Swift Gateway 网关模型
+- `pnpm protocol:check`
+  - 运行两个生成器并验证输出已提交
+
+## 模式在运行时的使用方式
+
+- **服务器端**：每个入站帧都用 AJV 验证。握手仅接受参数匹配 `ConnectParams` 的 `connect` 请求。
+- **客户端**：JS 客户端在使用之前验证事件和响应帧。
+- **方法表面**：Gateway 网关在 `hello-ok` 中公布支持的 `methods` 和 `events`。
+
+## 示例帧
+
+Connect（第一条消息）：
+
+```json
+{
+  "type": "req",
+  "id": "c1",
+  "method": "connect",
+  "params": {
+    "minProtocol": 2,
+    "maxProtocol": 2,
+    "client": {
+      "id": "quantumclaw-macos",
+      "displayName": "macos",
+      "version": "1.0.0",
+      "platform": "macos 15.1",
+      "mode": "ui",
+      "instanceId": "A1B2"
+    }
+  }
+}
+```
+
+Hello-ok 响应：
+
+```json
+{
+  "type": "res",
+  "id": "c1",
+  "ok": true,
+  "payload": {
+    "type": "hello-ok",
+    "protocol": 2,
+    "server": { "version": "dev", "connId": "ws-1" },
+    "features": { "methods": ["health"], "events": ["tick"] },
+    "snapshot": {
+      "presence": [],
+      "health": {},
+      "stateVersion": { "presence": 0, "health": 0 },
+      "uptimeMs": 0
+    },
+    "policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
+  }
+}
+```
+
+请求 + 响应：
+
+```json
+{ "type": "req", "id": "r1", "method": "health" }
+```
+
+```json
+{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }
+```
+
+事件：
+
+```json
+{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }
+```
+
+## 最小客户端（Node.js）
+
+最小可用流程：connect + health。
+
+```ts
+import { WebSocket } from "ws";
+
+const ws = new WebSocket("ws://127.0.0.1:18789");
+
+ws.on("open", () => {
+  ws.send(
+    JSON.stringify({
+      type: "req",
+      id: "c1",
+      method: "connect",
+      params: {
+        minProtocol: 3,
+        maxProtocol: 3,
+        client: {
+          id: "cli",
+          displayName: "example",
+          version: "dev",
+          platform: "node",
+          mode: "cli",
+        },
+      },
+    }),
+  );
+});
+
+ws.on("message", (data) => {
+  const msg = JSON.parse(String(data));
+  if (msg.type === "res" && msg.id === "c1" && msg.ok) {
+    ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
+  }
+  if (msg.type === "res" && msg.id === "h1") {
+    console.log("health:", msg.payload);
+    ws.close();
+  }
+});
+```
+
+## 实践示例：端到端添加方法
+
+示例：添加一个新的 `system.echo` 请求，返回 `{ ok: true, text }`。
+
+1. **模式（事实来源）**
+
+添加到 `src/gateway/protocol/schema.ts`：
+
+```ts
+export const SystemEchoParamsSchema = Type.Object(
+  { text: NonEmptyString },
+  { additionalProperties: false },
+);
+
+export const SystemEchoResultSchema = Type.Object(
+  { ok: Type.Boolean(), text: NonEmptyString },
+  { additionalProperties: false },
+);
+```
+
+将两者添加到 `ProtocolSchemas` 并导出类型：
+
+```ts
+  SystemEchoParams: SystemEchoParamsSchema,
+  SystemEchoResult: SystemEchoResultSchema,
+```
+
+```ts
+export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
+export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
+```
+
+2. **验证**
+
+在 `src/gateway/protocol/index.ts` 中，导出一个 AJV 验证器：
+
+```ts
+export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);
+```
+
+3. **服务器行为**
+
+在 `src/gateway/server-methods/system.ts` 中添加处理程序：
+
+```ts
+export const systemHandlers: GatewayRequestHandlers = {
+  "system.echo": ({ params, respond }) => {
+    const text = String(params.text ?? "");
+    respond(true, { ok: true, text });
+  },
+};
+```
+
+在 `src/gateway/server-methods.ts` 中注册（已合并 `systemHandlers`），然后将 `"system.echo"` 添加到 `src/gateway/server.ts` 中的 `METHODS`。
+
+4. **重新生成**
+
+```bash
+pnpm protocol:check
+```
+
+5. **测试 + 文档**
+
+在 `src/gateway/server.*.test.ts` 中添加服务器测试，并在文档中记录该方法。
+
+## Swift 代码生成行为
+
+Swift 生成器输出：
+
+- 带有 `req`、`res`、`event` 和 `unknown` 情况的 `GatewayFrame` 枚举
+- 强类型的 payload 结构体/枚举
+- `ErrorCode` 值和 `GATEWAY_PROTOCOL_VERSION`
+
+未知的帧类型保留为原始 payload 以实现向前兼容。
+
+## 版本控制 + 兼容性
+
+- `PROTOCOL_VERSION` 在 `src/gateway/protocol/schema.ts` 中。
+- 客户端发送 `minProtocol` + `maxProtocol`；服务器拒绝不匹配的。
+- Swift 模型保留未知帧类型以避免破坏旧客户端。
+
+## 模式模式和约定
+
+- 大多数对象使用 `additionalProperties: false` 以实现严格的 payload。
+- `NonEmptyString` 是 ID 和方法/事件名称的默认值。
+- 顶层 `GatewayFrame` 在 `type` 上使用**鉴别器**。
+- 有副作用的方法通常需要在 params 中包含 `idempotencyKey`（示例：`send`、`poll`、`agent`、`chat.send`）。
+
+## 实时 schema JSON
+
+生成的 JSON Schema 在仓库的 `dist/protocol.schema.json` 中。发布的原始文件通常可在以下位置获取：
+
+- https://raw.githubusercontent.com/quantumclaw/quantumclaw/main/dist/protocol.schema.json
+
+## 当你更改模式时
+
+1. 更新 TypeBox 模式。
+2. 运行 `pnpm protocol:check`。
+3. 提交重新生成的 schema + Swift 模型。

package/docs/zh-CN/concepts/typing-indicators.md

@@ -0,0 +1,74 @@
+---
+read_when:
+  - 更改输入指示器的行为或默认设置
+summary: QuantumClaw 何时显示输入指示器以及如何调整它们
+title: 输入指示器
+x-i18n:
+  generated_at: "2026-02-01T20:24:47Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8ee82d02829c4ff58462be8bf5bb52f23f519aeda816c2fd8a583e7a317a2e98
+  source_path: concepts/typing-indicators.md
+  workflow: 14
+---
+
+# 输入指示器
+
+在运行活跃期间，输入指示器会发送到聊天渠道。使用
+`agents.defaults.typingMode` 控制输入指示器**何时**开始显示，使用 `typingIntervalSeconds`
+控制**刷新频率**。
+
+## 默认行为
+
+当 `agents.defaults.typingMode` **未设置**时，QuantumClaw 保持旧版行为：
+
+- **私聊**：模型循环开始后立即显示输入指示器。
+- **群聊中被提及**：立即显示输入指示器。
+- **群聊中未被提及**：仅在消息文本开始流式传输时显示输入指示器。
+- **心跳运行**：输入指示器禁用。
+
+## 模式
+
+将 `agents.defaults.typingMode` 设置为以下值之一：
+
+- `never` — 永远不显示输入指示器。
+- `instant` — **模型循环开始后立即**显示输入指示器，即使运行最终只返回静默回复令牌。
+- `thinking` — 在**第一个推理增量**时开始显示输入指示器（需要运行时设置
+  `reasoningLevel: "stream"`）。
+- `message` — 在**第一个非静默文本增量**时开始显示输入指示器（忽略
+  `NO_REPLY` 静默令牌）。
+
+触发时机从晚到早的顺序：
+`never` → `message` → `thinking` → `instant`
+
+## 配置
+
+```json5
+{
+  agent: {
+    typingMode: "thinking",
+    typingIntervalSeconds: 6,
+  },
+}
+```
+
+可以按会话覆盖模式或刷新频率：
+
+```json5
+{
+  session: {
+    typingMode: "message",
+    typingIntervalSeconds: 4,
+  },
+}
+```
+
+## 注意事项
+
+- `message` 模式不会为纯静默回复显示输入指示器（例如用于抑制输出的 `NO_REPLY`
+  令牌）。
+- `thinking` 仅在运行流式传输推理时触发（`reasoningLevel: "stream"`）。
+  如果模型未产生推理增量，则不会显示输入指示器。
+- 无论使用何种模式，心跳运行都不会显示输入指示器。
+- `typingIntervalSeconds` 控制的是**刷新频率**，而非开始时间。
+  默认值为 6 秒。

package/docs/zh-CN/concepts/usage-tracking.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 你正在对接提供商使用量/配额界面
+  - 你需要解释使用量跟踪行为或认证要求
+summary: 使用量跟踪界面及凭据要求
+title: 使用量跟踪
+x-i18n:
+  generated_at: "2026-02-01T20:24:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6f6ed2a70329b2a6206c327aa749a84fbfe979762caca5f0e7fb556f91631cbb
+  source_path: concepts/usage-tracking.md
+  workflow: 14
+---
+
+# 使用量跟踪
+
+## 功能简介
+
+- 直接从提供商的使用量端点拉取使用量/配额数据。
+- 不提供估算费用；仅展示提供商报告的时间窗口数据。
+
+## 展示位置
+
+- 聊天中的 `/status`：包含会话 token 数和估算费用的表情符号丰富的状态卡片（仅限 API 密钥）。当可用时，会显示**当前模型提供商**的使用量。
+- 聊天中的 `/usage off|tokens|full`：每次响应的使用量页脚（OAuth 仅显示 token 数）。
+- 聊天中的 `/usage cost`：从 QuantumClaw 会话日志汇总的本地费用摘要。
+- CLI：`quantumclaw status --usage` 打印完整的按提供商分类的详细信息。
+- CLI：`quantumclaw channels list` 在提供商配置旁打印相同的使用量快照（使用 `--no-usage` 跳过）。
+- macOS 菜单栏：上下文菜单下的"使用量"部分（仅在可用时显示）。
+
+## 提供商及凭据
+
+- **Anthropic (Claude)**：认证配置中的 OAuth 令牌。
+- **GitHub Copilot**：认证配置中的 OAuth 令牌。
+- **Gemini CLI**：认证配置中的 OAuth 令牌。
+- **Antigravity**：认证配置中的 OAuth 令牌。
+- **OpenAI Codex**：认证配置中的 OAuth 令牌（存在时使用 accountId）。
+- **MiniMax**：API 密钥（编程计划密钥；`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_API_KEY`）；使用 5 小时编程计划时间窗口。
+- **z.ai**：通过环境变量/配置/认证存储提供的 API 密钥。
+
+如果没有匹配的 OAuth/API 凭据，使用量信息将被隐藏。

package/docs/zh-CN/date-time.md

@@ -0,0 +1,129 @@
+---
+read_when:
+  - 你正在更改向模型或用户展示时间戳的方式
+  - 你正在调试消息或系统提示词输出中的时间格式问题
+summary: 信封、提示词、工具和连接器中的日期与时间处理
+title: 日期与时间
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 753af5946a006215d6af2467fa478f3abb42b1dff027cf85d5dc4c7ba4b58d39
+  source_path: date-time.md
+  workflow: 14
+---
+
+# 日期与时间
+
+QuantumClaw 默认使用**主机本地时间作为传输时间戳**，并且**仅在系统提示词中使用用户时区**。
+提供商时间戳会被保留，因此工具保持其原生语义（当前时间可通过 `session_status` 获取）。
+
+## 消息信封（默认为本地时间）
+
+入站消息会附带一个时间戳（分钟精度）：
+
+```
+[Provider ... 2026-01-05 16:26 PST] message text
+```
+
+此信封时间戳**默认为主机本地时间**，与提供商时区无关。
+
+你可以覆盖此行为：
+
+```json5
+{
+  agents: {
+    defaults: {
+      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区
+      envelopeTimestamp: "on", // "on" | "off"
+      envelopeElapsed: "on", // "on" | "off"
+    },
+  },
+}
+```
+
+- `envelopeTimezone: "utc"` 使用 UTC。
+- `envelopeTimezone: "local"` 使用主机时区。
+- `envelopeTimezone: "user"` 使用 `agents.defaults.userTimezone`（回退到主机时区）。
+- 使用显式 IANA 时区（例如 `"America/Chicago"`）指定固定时区。
+- `envelopeTimestamp: "off"` 从信封头中移除绝对时间戳。
+- `envelopeElapsed: "off"` 移除已用时间后缀（`+2m` 样式）。
+
+### 示例
+
+**本地时间（默认）：**
+
+```
+[WhatsApp +1555 2026-01-18 00:19 PST] hello
+```
+
+**用户时区：**
+
+```
+[WhatsApp +1555 2026-01-18 00:19 CST] hello
+```
+
+**启用已用时间：**
+
+```
+[WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up
+```
+
+## 系统提示词：当前日期与时间
+
+如果已知用户时区，系统提示词会包含一个专门的**当前日期与时间**部分，其中仅包含**时区**（不含时钟/时间格式），以保持提示词缓存的稳定性：
+
+```
+Time zone: America/Chicago
+```
+
+当智能体需要获取当前时间时，请使用 `session_status` 工具；状态卡中包含时间戳行。
+
+## 系统事件行（默认为本地时间）
+
+插入到智能体上下文中的排队系统事件会带有时间戳前缀，使用与消息信封相同的时区选择（默认：主机本地时间）。
+
+```
+System: [2026-01-12 12:19:17 PST] Model switched.
+```
+
+### 配置用户时区和格式
+
+```json5
+{
+  agents: {
+    defaults: {
+      userTimezone: "America/Chicago",
+      timeFormat: "auto", // auto | 12 | 24
+    },
+  },
+}
+```
+
+- `userTimezone` 设置提示词上下文中的**用户本地时区**。
+- `timeFormat` 控制提示词中的 **12 小时/24 小时显示格式**。`auto` 跟随操作系统偏好设置。
+
+## 时间格式检测（auto）
+
+当 `timeFormat: "auto"` 时，QuantumClaw 会检查操作系统偏好设置（macOS/Windows），并回退到区域格式。检测到的值会**按进程缓存**，以避免重复的系统调用。
+
+## 工具载荷 + 连接器（原始提供商时间 + 标准化字段）
+
+渠道工具返回**提供商原生时间戳**，并添加标准化字段以保持一致性：
+
+- `timestampMs`：纪元毫秒数（UTC）
+- `timestampUtc`：ISO 8601 UTC 字符串
+
+原始提供商字段会被保留，不会丢失任何数据。
+
+- Slack：来自 API 的类纪元字符串
+- Discord：UTC ISO 时间戳
+- Telegram/WhatsApp：提供商特定的数字/ISO 时间戳
+
+如果需要本地时间，请使用已知时区在下游进行转换。
+
+## 相关文档
+
+- [系统提示词](/concepts/system-prompt)
+- [时区](/concepts/timezone)
+- [消息](/concepts/messages)