@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,200 @@
+---
+read_when:
+  - 添加或修改会话工具时
+summary: 用于列出会话、获取历史记录和发送跨会话消息的智能体会话工具
+title: 会话工具
+x-i18n:
+  generated_at: "2026-02-03T07:46:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cb6e0982ebf507bcf9de4bb17719759c2b6d3e519731c845580a55279084e4c8
+  source_path: concepts/session-tool.md
+  workflow: 15
+---
+
+# 会话工具
+
+目标：小型、不易误用的工具集，使智能体能够列出会话、获取历史记录并向另一个会话发送消息。
+
+## 工具名称
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+## 键模型
+
+- 主直接聊天桶始终是字面键 `"main"`（解析为当前智能体的主键）。
+- 群聊使用 `agent:<agentId>:<channel>:group:<id>` 或 `agent:<agentId>:<channel>:channel:<id>`（传递完整键）。
+- 定时任务使用 `cron:<job.id>`。
+- Hooks 使用 `hook:<uuid>`，除非明确设置。
+- Node 会话使用 `node-<nodeId>`，除非明确设置。
+
+`global` 和 `unknown` 是保留值，永远不会被列出。如果 `session.scope = "global"`，我们会将其别名为 `main` 用于所有工具，这样调用者永远不会看到 `global`。
+
+## sessions_list
+
+将会话列为行数组。
+
+参数：
+
+- `kinds?: string[]` 过滤器：`"main" | "group" | "cron" | "hook" | "node" | "other"` 中的任意一个
+- `limit?: number` 最大行数（默认：服务器默认值，限制如 200）
+- `activeMinutes?: number` 仅在 N 分钟内更新的会话
+- `messageLimit?: number` 0 = 无消息（默认 0）；>0 = 包含最后 N 条消息
+
+行为：
+
+- `messageLimit > 0` 获取每个会话的 `chat.history` 并包含最后 N 条消息。
+- 工具结果在列表输出中被过滤；使用 `sessions_history` 获取工具消息。
+- 在**沙箱隔离**的智能体会话中运行时，会话工具默认为**仅生成的可见性**（见下文）。
+
+行结构（JSON）：
+
+- `key`：会话键（字符串）
+- `kind`：`main | group | cron | hook | node | other`
+- `channel`：`whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown`
+- `displayName`（如果可用的群组显示标签）
+- `updatedAt`（毫秒）
+- `sessionId`
+- `model`、`contextTokens`、`totalTokens`
+- `thinkingLevel`、`verboseLevel`、`systemSent`、`abortedLastRun`
+- `sendPolicy`（如果设置的会话覆盖）
+- `lastChannel`、`lastTo`
+- `deliveryContext`（可用时的规范化 `{ channel, to, accountId }`）
+- `transcriptPath`（从存储目录 + sessionId 派生的尽力路径）
+- `messages?`（仅当 `messageLimit > 0` 时）
+
+## sessions_history
+
+获取一个会话的记录。
+
+参数：
+
+- `sessionKey`（必填；接受会话键或来自 `sessions_list` 的 `sessionId`）
+- `limit?: number` 最大消息数（服务器限制）
+- `includeTools?: boolean`（默认 false）
+
+行为：
+
+- `includeTools=false` 过滤 `role: "toolResult"` 消息。
+- 以原始记录格式返回消息数组。
+- 当给定 `sessionId` 时，QuantumClaw 将其解析为相应的会话键（缺失的 id 会报错）。
+
+## sessions_send
+
+向另一个会话发送消息。
+
+参数：
+
+- `sessionKey`（必填；接受会话键或来自 `sessions_list` 的 `sessionId`）
+- `message`（必填）
+- `timeoutSeconds?: number`（默认 >0；0 = 即发即忘）
+
+行为：
+
+- `timeoutSeconds = 0`：入队并返回 `{ runId, status: "accepted" }`。
+- `timeoutSeconds > 0`：等待最多 N 秒完成，然后返回 `{ runId, status: "ok", reply }`。
+- 如果等待超时：`{ runId, status: "timeout", error }`。运行继续；稍后调用 `sessions_history`。
+- 如果运行失败：`{ runId, status: "error", error }`。
+- 通告投递在主运行完成后运行，且为尽力而为；`status: "ok"` 不保证通告已投递。
+- 通过 Gateway 网关 `agent.wait`（服务器端）等待，因此重连不会丢失等待。
+- 智能体到智能体的消息上下文会为主运行注入。
+- 主运行完成后，QuantumClaw 运行**回复循环**：
+  - 第 2 轮及以后在请求者和目标智能体之间交替。
+  - 精确回复 `REPLY_SKIP` 以停止来回。
+  - 最大轮数为 `session.agentToAgent.maxPingPongTurns`（0–5，默认 5）。
+- 循环结束后，QuantumClaw 运行**智能体到智能体通告步骤**（仅目标智能体）：
+  - 精确回复 `ANNOUNCE_SKIP` 以保持静默。
+  - 任何其他回复都会发送到目标渠道。
+  - 通告步骤包括原始请求 + 第 1 轮回复 + 最新的来回回复。
+
+## Channel 字段
+
+- 对于群组，`channel` 是会话条目上记录的渠道。
+- 对于直接聊天，`channel` 从 `lastChannel` 映射。
+- 对于 cron/hook/node，`channel` 是 `internal`。
+- 如果缺失，`channel` 是 `unknown`。
+
+## 安全 / 发送策略
+
+基于策略的按渠道/聊天类型阻止（不是按会话 id）。
+
+```json
+{
+  "session": {
+    "sendPolicy": {
+      "rules": [
+        {
+          "match": { "channel": "discord", "chatType": "group" },
+          "action": "deny"
+        }
+      ],
+      "default": "allow"
+    }
+  }
+}
+```
+
+运行时覆盖（按会话条目）：
+
+- `sendPolicy: "allow" | "deny"`（未设置 = 继承配置）
+- 可通过 `sessions.patch` 或仅所有者的 `/send on|off|inherit`（独立消息）设置。
+
+执行点：
+
+- `chat.send` / `agent`（Gateway 网关）
+- 自动回复投递逻辑
+
+## sessions_spawn
+
+在隔离会话中生成子智能体运行，并将结果通告回请求者聊天渠道。
+
+参数：
+
+- `task`（必填）
+- `label?`（可选；用于日志/UI）
+- `agentId?`（可选；如果允许，在另一个智能体 id 下生成）
+- `model?`（可选；覆盖子智能体模型；无效值会报错）
+- `runTimeoutSeconds?`（默认 0；设置时，在 N 秒后中止子智能体运行）
+- `cleanup?`（`delete|keep`，默认 `keep`）
+
+允许列表：
+
+- `agents.list[].subagents.allowAgents`：通过 `agentId` 允许的智能体 id 列表（`["*"]` 允许任意）。默认：仅请求者智能体。
+
+发现：
+
+- 使用 `agents_list` 发现哪些智能体 id 允许用于 `sessions_spawn`。
+
+行为：
+
+- 使用 `deliver: false` 启动新的 `agent:<agentId>:subagent:<uuid>` 会话。
+- 子智能体默认使用完整工具集**减去会话工具**（可通过 `tools.subagents.tools` 配置）。
+- 子智能体不允许调用 `sessions_spawn`（无子智能体 → 子智能体生成）。
+- 始终非阻塞：立即返回 `{ status: "accepted", runId, childSessionKey }`。
+- 完成后，QuantumClaw 运行子智能体**通告步骤**并将结果发布到请求者聊天渠道。
+- 在通告步骤中精确回复 `ANNOUNCE_SKIP` 以保持静默。
+- 通告回复规范化为 `Status`/`Result`/`Notes`；`Status` 来自运行时结果（不是模型文本）。
+- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes` 后自动归档（默认：60）。
+- 通告回复包含统计行（运行时间、token 数、sessionKey/sessionId、记录路径和可选成本）。
+
+## 沙箱会话可见性
+
+沙箱隔离的会话可以使用会话工具，但默认情况下它们只能看到通过 `sessions_spawn` 生成的会话。
+
+配置：
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        // 默认："spawned"
+        sessionToolsVisibility: "spawned", // 或 "all"
+      },
+    },
+  },
+}
+```

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

@@ -0,0 +1,166 @@
+---
+read_when:
+  - 修改会话处理或存储
+summary: 聊天的会话管理规则、键和持久化
+title: 会话管理
+x-i18n:
+  generated_at: "2026-02-03T07:47:44Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 147c8d1a4b6b4864cb16ad942feba80181b6b0e29afa765e7958f8c2483746b5
+  source_path: concepts/session.md
+  workflow: 15
+---
+
+# 会话管理
+
+QuantumClaw 将**每个智能体的一个直接聊天会话**视为主会话。直接聊天折叠为 `agent:<agentId>:<mainKey>`（默认 `main`），而群组/频道聊天获得各自的键。`session.mainKey` 会被遵循。
+
+使用 `session.dmScope` 控制**私信**如何分组：
+
+- `main`（默认）：所有私信共享主会话以保持连续性。
+- `per-peer`：跨渠道按发送者 ID 隔离。
+- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
+- `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户收件箱）。
+  使用 `session.identityLinks` 将带提供商前缀的对等 ID 映射到规范身份，这样在使用 `per-peer`、`per-channel-peer` 或 `per-account-channel-peer` 时，同一个人可以跨渠道共享私信会话。
+
+## Gateway 网关是唯一数据源
+
+所有会话状态都**由 Gateway 网关拥有**（"主" QuantumClaw）。UI 客户端（macOS 应用、WebChat 等）必须向 Gateway 网关查询会话列表和令牌计数，而不是读取本地文件。
+
+- 在**远程模式**下，你关心的会话存储位于远程 Gateway 网关主机上，而不是你的 Mac 上。
+- UI 中显示的令牌计数来自 Gateway 网关的存储字段（`inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`）。客户端不会解析 JSONL 对话记录来"修正"总数。
+
+## 状态存储位置
+
+- 在 **Gateway 网关主机**上：
+  - 存储文件：`~/.quantumclaw/agents/<agentId>/sessions/sessions.json`（每个智能体）。
+- 对话记录：`~/.quantumclaw/agents/<agentId>/sessions/<SessionId>.jsonl`（Telegram 话题会话使用 `.../<SessionId>-topic-<threadId>.jsonl`）。
+- 存储是一个映射 `sessionKey -> { sessionId, updatedAt, ... }`。删除条目是安全的；它们会按需重新创建。
+- 群组条目可能包含 `displayName`、`channel`、`subject`、`room` 和 `space` 以在 UI 中标记会话。
+- 会话条目包含 `origin` 元数据（标签 + 路由提示），以便 UI 可以解释会话的来源。
+- QuantumClaw **不**读取旧版 Pi/Tau 会话文件夹。
+
+## 会话修剪
+
+默认情况下，QuantumClaw 在 LLM 调用之前从内存上下文中修剪**旧的工具结果**。
+这**不会**重写 JSONL 历史记录。参见 [/concepts/session-pruning](/concepts/session-pruning)。
+
+## 压缩前记忆刷新
+
+当会话接近自动压缩时，QuantumClaw 可以运行一个**静默记忆刷新**轮次，提醒模型将持久性笔记写入磁盘。这仅在工作区可写时运行。参见[记忆](/concepts/memory)和[压缩](/concepts/compaction)。
+
+## 传输到会话键的映射
+
+- 直接聊天遵循 `session.dmScope`（默认 `main`）。
+  - `main`：`agent:<agentId>:<mainKey>`（跨设备/渠道的连续性）。
+    - 多个电话号码和渠道可以映射到同一个智能体主键；它们作为进入同一个对话的传输通道。
+  - `per-peer`：`agent:<agentId>:dm:<peerId>`。
+  - `per-channel-peer`：`agent:<agentId>:<channel>:dm:<peerId>`。
+  - `per-account-channel-peer`：`agent:<agentId>:<channel>:<accountId>:dm:<peerId>`（accountId 默认为 `default`）。
+  - 如果 `session.identityLinks` 匹配带提供商前缀的对等 ID（例如 `telegram:123`），则规范键替换 `<peerId>`，这样同一个人可以跨渠道共享会话。
+- 群组聊天隔离状态：`agent:<agentId>:<channel>:group:<id>`（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
+  - Telegram 论坛话题在群组 ID 后附加 `:topic:<threadId>` 以进行隔离。
+  - 旧版 `group:<id>` 键仍被识别以进行迁移。
+- 入站上下文可能仍使用 `group:<id>`；渠道从 `Provider` 推断并规范化为规范的 `agent:<agentId>:<channel>:group:<id>` 形式。
+- 其他来源：
+  - 定时任务：`cron:<job.id>`
+  - Webhooks：`hook:<uuid>`（除非由 hook 显式设置）
+  - 节点运行：`node-<nodeId>`
+
+## 生命周期
+
+- 重置策略：会话被重用直到过期，过期在下一条入站消息时评估。
+- 每日重置：默认为 **Gateway 网关主机本地时间凌晨 4:00**。当会话的最后更新早于最近的每日重置时间时，会话即为过期。
+- 空闲重置（可选）：`idleMinutes` 添加一个滑动空闲窗口。当同时配置每日和空闲重置时，**先过期者**强制新会话。
+- 旧版仅空闲模式：如果你设置了 `session.idleMinutes` 而没有任何 `session.reset`/`resetByType` 配置，QuantumClaw 会保持仅空闲模式以保持向后兼容。
+- 按类型覆盖（可选）：`resetByType` 允许你覆盖 `dm`、`group` 和 `thread` 会话的策略（thread = Slack/Discord 线程、Telegram 话题、连接器提供的 Matrix 线程）。
+- 按渠道覆盖（可选）：`resetByChannel` 覆盖渠道的重置策略（适用于该渠道的所有会话类型，优先于 `reset`/`resetByType`）。
+- 重置触发器：精确的 `/new` 或 `/reset`（加上 `resetTriggers` 中的任何额外项）启动新的会话 ID 并传递消息的其余部分。`/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）来设置新会话模型。如果单独发送 `/new` 或 `/reset`，QuantumClaw 会运行一个简短的"问候"轮次来确认重置。
+- 手动重置：从存储中删除特定键或删除 JSONL 对话记录；下一条消息会重新创建它们。
+- 隔离的定时任务总是每次运行生成新的 `sessionId`（没有空闲重用）。
+
+## 发送策略（可选）
+
+阻止特定会话类型的投递，无需列出单个 ID。
+
+```json5
+{
+  session: {
+    sendPolicy: {
+      rules: [
+        { action: "deny", match: { channel: "discord", chatType: "group" } },
+        { action: "deny", match: { keyPrefix: "cron:" } },
+      ],
+      default: "allow",
+    },
+  },
+}
+```
+
+运行时覆盖（仅所有者）：
+
+- `/send on` → 为此会话允许
+- `/send off` → 为此会话拒绝
+- `/send inherit` → 清除覆盖并使用配置规则
+  将这些作为独立消息发送以使其生效。
+
+## 配置（可选重命名示例）
+
+```json5
+// ~/.quantumclaw/quantumclaw.json
+{
+  session: {
+    scope: "per-sender", // keep group keys separate
+    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
+    identityLinks: {
+      alice: ["telegram:123456789", "discord:987654321012345678"],
+    },
+    reset: {
+      // Defaults: mode=daily, atHour=4 (gateway host local time).
+      // If you also set idleMinutes, whichever expires first wins.
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 120,
+    },
+    resetByType: {
+      thread: { mode: "daily", atHour: 4 },
+      dm: { mode: "idle", idleMinutes: 240 },
+      group: { mode: "idle", idleMinutes: 120 },
+    },
+    resetByChannel: {
+      discord: { mode: "idle", idleMinutes: 10080 },
+    },
+    resetTriggers: ["/new", "/reset"],
+    store: "~/.quantumclaw/agents/{agentId}/sessions/sessions.json",
+    mainKey: "main",
+  },
+}
+```
+
+## 检查
+
+- `quantumclaw status` — 显示存储路径和最近的会话。
+- `quantumclaw sessions --json` — 导出每个条目（使用 `--active <minutes>` 过滤）。
+- `quantumclaw gateway call sessions.list --params '{}'` — 从运行中的 Gateway 网关获取会话（使用 `--url`/`--token` 进行远程 Gateway 网关访问）。
+- 在聊天中单独发送 `/status` 消息可查看智能体是否可达、会话上下文使用了多少、当前的思考/详细模式开关，以及你的 WhatsApp Web 凭证上次刷新时间（有助于发现重新链接需求）。
+- 发送 `/context list` 或 `/context detail` 查看系统提示中的内容和注入的工作区文件（以及最大的上下文贡献者）。
+- 单独发送 `/stop` 消息可中止当前运行、清除该会话的排队后续操作，并停止从中生成的任何子智能体运行（回复包含已停止的数量）。
+- 单独发送 `/compact`（可选指令）消息可总结旧上下文并释放窗口空间。参见 [/concepts/compaction](/concepts/compaction)。
+- 可以直接打开 JSONL 对话记录查看完整轮次。
+
+## 提示
+
+- 将主键专用于 1:1 通信；让群组保留各自的键。
+- 自动清理时，删除单个键而不是整个存储，以保留其他地方的上下文。
+
+## 会话来源元数据
+
+每个会话条目记录其来源（尽力而为）在 `origin` 中：
+
+- `label`：人类可读标签（从对话标签 + 群组主题/频道解析）
+- `provider`：规范化的渠道 ID（包括扩展）
+- `from`/`to`：入站信封中的原始路由 ID
+- `accountId`：提供商账户 ID（多账户时）
+- `threadId`：渠道支持时的线程/话题 ID
+  来源字段为私信、频道和群组填充。如果连接器仅更新投递路由（例如，保持私信主会话新鲜），它仍应提供入站上下文，以便会话保留其解释器元数据。扩展可以通过在入站上下文中发送 `ConversationLabel`、`GroupSubject`、`GroupChannel`、`GroupSpace` 和 `SenderName` 并调用 `recordSessionMetaFromInbound`（或将相同上下文传递给 `updateLastRoute`）来实现。

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

@@ -0,0 +1,133 @@
+---
+read_when:
+  - 解释流式传输或分块在渠道上如何工作
+  - 更改分块流式传输或渠道分块行为
+  - 调试重复/提前的块回复或草稿流式传输
+summary: 流式传输 + 分块行为（块回复、草稿流式传输、限制）
+title: 流式传输和分块
+x-i18n:
+  generated_at: "2026-02-03T10:05:41Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f014eb1898c4351b1d6b812223226d91324701e3e809cd0f3faf6679841bc353
+  source_path: concepts/streaming.md
+  workflow: 15
+---
+
+# 流式传输 + 分块
+
+QuantumClaw 有两个独立的"流式传输"层：
+
+- **分块流式传输（渠道）：** 在助手写入时发出已完成的**块**。这些是普通的渠道消息（不是令牌增量）。
+- **类令牌流式传输（仅限 Telegram）：** 在生成时用部分文本更新**草稿气泡**；最终消息在结束时发送。
+
+目前**没有真正的令牌流式传输**到外部渠道消息。Telegram 草稿流式传输是唯一的部分流式传输界面。
+
+## 分块流式传输（渠道消息）
+
+分块流式传输在助手输出可用时以粗粒度块发送。
+
+```
+模型输出
+  └─ text_delta/events
+       ├─ (blockStreamingBreak=text_end)
+       │    └─ 分块器在缓冲区增长时发出块
+       └─ (blockStreamingBreak=message_end)
+            └─ 分块器在 message_end 时刷新
+                   └─ 渠道发送（块回复）
+```
+
+图例：
+
+- `text_delta/events`：模型流事件（对于非流式模型可能稀疏）。
+- `chunker`：应用最小/最大边界 + 断点偏好的 `EmbeddedBlockChunker`。
+- `channel send`：实际的出站消息（块回复）。
+
+**控制项：**
+
+- `agents.defaults.blockStreamingDefault`：`"on"`/`"off"`（默认关闭）。
+- 渠道覆盖：`*.blockStreaming`（以及每账户变体）可为每个渠道强制设置 `"on"`/`"off"`。
+- `agents.defaults.blockStreamingBreak`：`"text_end"` 或 `"message_end"`。
+- `agents.defaults.blockStreamingChunk`：`{ minChars, maxChars, breakPreference? }`。
+- `agents.defaults.blockStreamingCoalesce`：`{ minChars?, maxChars?, idleMs? }`（发送前合并流式块）。
+- 渠道硬上限：`*.textChunkLimit`（例如 `channels.whatsapp.textChunkLimit`）。
+- 渠道分块模式：`*.chunkMode`（默认 `length`，`newline` 在长度分块之前按空行（段落边界）分割）。
+- Discord 软上限：`channels.discord.maxLinesPerMessage`（默认 17）分割高度较大的回复以避免 UI 裁剪。
+
+**边界语义：**
+
+- `text_end`：分块器发出时立即流式传输块；在每个 `text_end` 时刷新。
+- `message_end`：等到助手消息完成，然后刷新缓冲的输出。
+
+如果缓冲文本超过 `maxChars`，`message_end` 仍然使用分块器，因此可能在最后发出多个块。
+
+## 分块算法（低/高边界）
+
+块分块由 `EmbeddedBlockChunker` 实现：
+
+- **低边界：** 在缓冲区 >= `minChars` 之前不发出（除非强制）。
+- **高边界：** 优先在 `maxChars` 之前分割；如果强制，则在 `maxChars` 处分割。
+- **断点偏好：** `paragraph` → `newline` → `sentence` → `whitespace` → 硬断点。
+- **代码围栏：** 从不在围栏内分割；当在 `maxChars` 处强制分割时，关闭 + 重新打开围栏以保持 Markdown 有效。
+
+`maxChars` 被限制在渠道 `textChunkLimit` 内，因此你无法超过每渠道的上限。
+
+## 合并（合并流式块）
+
+启用分块流式传输时，QuantumClaw 可以在发送前**合并连续的块分块**。这减少了"单行刷屏"，同时仍提供渐进式输出。
+
+- 合并在**空闲间隙**（`idleMs`）后刷新。
+- 缓冲区受 `maxChars` 限制，超过时将刷新。
+- `minChars` 防止微小片段发送，直到累积足够文本（最终刷新始终发送剩余文本）。
+- 连接符从 `blockStreamingChunk.breakPreference` 派生（`paragraph` → `\n\n`，`newline` → `\n`，`sentence` → 空格）。
+- 渠道覆盖通过 `*.blockStreamingCoalesce` 可用（包括每账户配置）。
+- 除非覆盖，Signal/Slack/Discord 的默认合并 `minChars` 提高到 1500。
+
+## 块之间的类人节奏
+
+启用分块流式传输时，你可以在块回复之间添加**随机暂停**（在第一个块之后）。这使多气泡响应感觉更自然。
+
+- 配置：`agents.defaults.humanDelay`（通过 `agents.list[].humanDelay` 按智能体覆盖）。
+- 模式：`off`（默认）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
+- 仅适用于**块回复**，不适用于最终回复或工具摘要。
+
+## "流式传输块或全部内容"
+
+这映射到：
+
+- **流式传输块：** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（边生成边发出）。非 Telegram 渠道还需要 `*.blockStreaming: true`。
+- **最后流式传输全部内容：** `blockStreamingBreak: "message_end"`（刷新一次，如果很长可能有多个块）。
+- **无分块流式传输：** `blockStreamingDefault: "off"`（只有最终回复）。
+
+**渠道说明：** 对于非 Telegram 渠道，分块流式传输**默认关闭**，除非 `*.blockStreaming` 明确设置为 `true`。Telegram 可以在没有块回复的情况下流式传输草稿（`channels.telegram.streamMode`）。
+
+配置位置提醒：`blockStreaming*` 默认值位于 `agents.defaults` 下，而不是根配置。
+
+## Telegram 草稿流式传输（类令牌）
+
+Telegram 是唯一支持草稿流式传输的渠道：
+
+- 在**带主题的私聊**中使用 Bot API `sendMessageDraft`。
+- `channels.telegram.streamMode: "partial" | "block" | "off"`。
+  - `partial`：用最新的流式文本更新草稿。
+  - `block`：以分块方式更新草稿（相同的分块器规则）。
+  - `off`：无草稿流式传输。
+- 草稿分块配置（仅用于 `streamMode: "block"`）：`channels.telegram.draftChunk`（默认值：`minChars: 200`，`maxChars: 800`）。
+- 草稿流式传输与分块流式传输分开；块回复默认关闭，仅在非 Telegram 渠道上通过 `*.blockStreaming: true` 启用。
+- 最终回复仍然是普通消息。
+- `/reasoning stream` 将推理写入草稿气泡（仅限 Telegram）。
+
+当草稿流式传输活跃时，QuantumClaw 会为该回复禁用分块流式传输以避免双重流式传输。
+
+```
+Telegram（私聊 + 主题）
+  └─ sendMessageDraft（草稿气泡）
+       ├─ streamMode=partial → 更新最新文本
+       └─ streamMode=block   → 分块器更新草稿
+  └─ 最终回复 → 普通消息
+```
+
+图例：
+
+- `sendMessageDraft`：Telegram 草稿气泡（不是真正的消息）。
+- `final reply`：普通 Telegram 消息发送。

package/docs/zh-CN/concepts/system-prompt.md

@@ -0,0 +1,101 @@
+---
+read_when:
+  - 编辑系统提示词文本、工具列表或时间/心跳部分
+  - 更改工作区引导或 Skills 注入行为
+summary: QuantumClaw 系统提示词包含的内容及其组装方式
+title: 系统提示词
+x-i18n:
+  generated_at: "2026-02-03T07:46:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: bef4b2674ba0414ce28fd08a4c3ead0e0ebe989e7df3c88ca8a0b2abfec2a50b
+  source_path: concepts/system-prompt.md
+  workflow: 15
+---
+
+# 系统提示词
+
+QuantumClaw 为每次智能体运行构建自定义系统提示词。该提示词由 **QuantumClaw 拥有**，不使用 pi-coding-agent 默认提示词。
+
+该提示词由 QuantumClaw 组装并注入到每次智能体运行中。
+
+## 结构
+
+该提示词设计紧凑，使用固定部分：
+
+- **Tooling**：当前工具列表 + 简短描述。
+- **Safety**：简短的防护提醒，避免追求权力的行为或绕过监督。
+- **Skills**（如果可用）：告诉模型如何按需加载 Skill 指令。
+- **QuantumClaw Self-Update**：如何运行 `config.apply` 和 `update.run`。
+- **Workspace**：工作目录（`agents.defaults.workspace`）。
+- **Documentation**：QuantumClaw 文档的本地路径（仓库或 npm 包）以及何时阅读它们。
+- **Workspace Files (injected)**：表示下方包含引导文件。
+- **Sandbox**（启用时）：表示沙箱隔离运行时、沙箱路径，以及是否可用提权执行。
+- **Current Date & Time**：用户本地时间、时区和时间格式。
+- **Reply Tags**：支持的提供商的可选回复标签语法。
+- **Heartbeats**：心跳提示词和确认行为。
+- **Runtime**：主机、操作系统、node、模型、仓库根目录（检测到时）、思考级别（一行）。
+- **Reasoning**：当前可见性级别 + /reasoning 切换提示。
+
+系统提示词中的安全防护是建议性的。它们指导模型行为但不强制执行策略。使用工具策略、执行审批、沙箱隔离和渠道允许列表进行硬性执行；运维人员可以按设计禁用这些。
+
+## 提示词模式
+
+QuantumClaw 可以为子智能体渲染更小的系统提示词。运行时为每次运行设置一个 `promptMode`（不是面向用户的配置）：
+
+- `full`（默认）：包含上述所有部分。
+- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**QuantumClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies** 和 **Heartbeats**。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（已知时）、Runtime 和注入的上下文仍然可用。
+- `none`：仅返回基本身份行。
+
+当 `promptMode=minimal` 时，额外注入的提示词标记为 **Subagent Context** 而不是 **Group Chat Context**。
+
+## 工作区引导注入
+
+引导文件被修剪后附加在 **Project Context** 下，这样模型无需显式读取即可看到身份和配置上下文：
+
+- `AGENTS.md`
+- `SOUL.md`
+- `TOOLS.md`
+- `IDENTITY.md`
+- `USER.md`
+- `HEARTBEAT.md`
+- `BOOTSTRAP.md`（仅在全新工作区上）
+
+大文件会带截断标记被截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：20000）。缺失的文件会注入一个简短的缺失文件标记。
+
+内部钩子可以通过 `agent:bootstrap` 拦截此步骤以修改或替换注入的引导文件（例如将 `SOUL.md` 替换为其他角色）。
+
+要检查每个注入文件贡献了多少（原始 vs 注入、截断，加上工具 schema 开销），使用 `/context list` 或 `/context detail`。参见[上下文](/concepts/context)。
+
+## 时间处理
+
+当用户时区已知时，系统提示词包含专用的 **Current Date & Time** 部分。为保持提示词缓存稳定，它现在只包含**时区**（没有动态时钟或时间格式）。
+
+当智能体需要当前时间时使用 `session_status`；状态卡片包含时间戳行。
+
+配置方式：
+
+- `agents.defaults.userTimezone`
+- `agents.defaults.timeFormat`（`auto` | `12` | `24`）
+
+完整行为详情参见[日期和时间](/date-time)。
+
+## Skills
+
+当存在符合条件的 Skills 时，QuantumClaw 注入一个紧凑的**可用 Skills 列表**（`formatSkillsForPrompt`），其中包含每个 Skill 的**文件路径**。提示词指示模型使用 `read` 加载列出位置（工作区、托管或内置）的 SKILL.md。如果没有符合条件的 Skills，则省略 Skills 部分。
+
+```
+<available_skills>
+  <skill>
+    <name>...</name>
+    <description>...</description>
+    <location>...</location>
+  </skill>
+</available_skills>
+```
+
+这使基础提示词保持小巧，同时仍然支持有针对性的 Skill 使用。
+
+## 文档
+
+如果可用，系统提示词包含一个 **Documentation** 部分，指向本地 QuantumClaw 文档目录（仓库工作区中的 `docs/` 或打包的 npm 包文档），并注明公共镜像、源仓库、社区 Discord 和 ClawHub (https://clawhub.com) 用于 Skills 发现。提示词指示模型首先查阅本地文档了解 QuantumClaw 行为、命令、配置或架构，并尽可能自己运行 `quantumclaw status`（仅在无法访问时询问用户）。