@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/cli/uninstall.md

@@ -0,0 +1,24 @@
+---
+read_when:
+  - 你想移除 Gateway 网关服务和/或本地状态
+  - 你想先进行试运行
+summary: "`quantumclaw uninstall` 的 CLI 参考（移除 Gateway 网关服务 + 本地数据）"
+title: uninstall
+x-i18n:
+  generated_at: "2026-02-03T10:04:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8d6c3890923f18f95c12b76443d649a6b404934ebd054fb86a9fa1abae843fe4
+  source_path: cli/uninstall.md
+  workflow: 15
+---
+
+# `quantumclaw uninstall`
+
+卸载 Gateway 网关服务 + 本地数据（CLI 保留）。
+
+```bash
+quantumclaw uninstall
+quantumclaw uninstall --all --yes
+quantumclaw uninstall --dry-run
+```

package/docs/zh-CN/cli/update.md

@@ -0,0 +1,101 @@
+---
+read_when:
+  - 你想安全地更新源码检出
+  - 你需要了解 `--update` 简写行为
+summary: "`quantumclaw update` 的 CLI 参考（相对安全的源码更新 + Gateway 网关自动重启）"
+title: update
+x-i18n:
+  generated_at: "2026-02-03T07:45:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3a08e8ac797612c498eef54ecb83e61c9a1ee5de09162a01dbb4b3bd72897206
+  source_path: cli/update.md
+  workflow: 15
+---
+
+# `quantumclaw update`
+
+安全更新 QuantumClaw 并在 stable/beta/dev 渠道之间切换。
+
+如果你通过 **npm/pnpm** 安装（全局安装，无 git 元数据），更新通过 [更新](/install/updating) 中的包管理器流程进行。
+
+## 用法
+
+```bash
+quantumclaw update
+quantumclaw update status
+quantumclaw update wizard
+quantumclaw update --channel beta
+quantumclaw update --channel dev
+quantumclaw update --tag beta
+quantumclaw update --no-restart
+quantumclaw update --json
+quantumclaw --update
+```
+
+## 选项
+
+- `--no-restart`：成功更新后跳过重启 Gateway 网关服务。
+- `--channel <stable|beta|dev>`：设置更新渠道（git + npm；持久化到配置中）。
+- `--tag <dist-tag|version>`：仅为本次更新覆盖 npm dist-tag 或版本。
+- `--json`：打印机器可读的 `UpdateRunResult` JSON。
+- `--timeout <seconds>`：每步超时时间（默认 1200 秒）。
+
+注意：降级需要确认，因为旧版本可能会破坏配置。
+
+## `update status`
+
+显示当前更新渠道 + git 标签/分支/SHA（对于源码检出），以及更新可用性。
+
+```bash
+quantumclaw update status
+quantumclaw update status --json
+quantumclaw update status --timeout 10
+```
+
+选项：
+
+- `--json`：打印机器可读的状态 JSON。
+- `--timeout <seconds>`：检查超时时间（默认 3 秒）。
+
+## `update wizard`
+
+交互式流程，用于选择更新渠道并确认是否在更新后重启 Gateway 网关（默认重启）。如果你选择 `dev` 但没有 git 检出，它会提供创建一个的选项。
+
+## 工作原理
+
+当你显式切换渠道（`--channel ...`）时，QuantumClaw 也会保持安装方式一致：
+
+- `dev` → 确保存在 git 检出（默认：`~/quantumclaw`，可通过 `QUANTUMCLAW_GIT_DIR` 覆盖），更新它，并从该检出安装全局 CLI。
+- `stable`/`beta` → 使用匹配的 dist-tag 从 npm 安装。
+
+## Git 检出流程
+
+渠道：
+
+- `stable`：检出最新的非 beta 标签，然后构建 + doctor。
+- `beta`：检出最新的 `-beta` 标签，然后构建 + doctor。
+- `dev`：检出 `main`，然后 fetch + rebase。
+
+高层概述：
+
+1. 需要干净的工作树（无未提交的更改）。
+2. 切换到所选渠道（标签或分支）。
+3. 获取上游（仅 dev）。
+4. 仅 dev：在临时工作树中预检 lint + TypeScript 构建；如果最新提交失败，回退最多 10 个提交以找到最新的干净构建。
+5. Rebase 到所选提交（仅 dev）。
+6. 安装依赖（优先使用 pnpm；npm 作为备选）。
+7. 构建 + 构建控制界面。
+8. 运行 `quantumclaw doctor` 作为最终的"安全更新"检查。
+9. 将插件同步到当前渠道（dev 使用捆绑的扩展；stable/beta 使用 npm）并更新 npm 安装的插件。
+
+## `--update` 简写
+
+`quantumclaw --update` 会重写为 `quantumclaw update`（便于 shell 和启动脚本使用）。
+
+## 另请参阅
+
+- `quantumclaw doctor`（在 git 检出上会提供先运行更新的选项）
+- [开发渠道](/install/development-channels)
+- [更新](/install/updating)
+- [CLI 参考](/cli)

package/docs/zh-CN/cli/voicecall.md

@@ -0,0 +1,41 @@
+---
+read_when:
+  - 使用语音通话插件并想了解 CLI 入口
+  - 想要 `voicecall call|continue|status|tail|expose` 的快速示例
+summary: 语音通话插件命令的 `quantumclaw voicecall` CLI 参考
+title: voicecall
+x-i18n:
+  generated_at: "2026-02-01T20:21:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d93aaee6f6f5c9ac468d8d2905cb23f0f2db75809408cb305c055505be9936f2
+  source_path: cli/voicecall.md
+  workflow: 14
+---
+
+# `quantumclaw voicecall`
+
+`voicecall` 是一个由插件提供的命令。只有在安装并启用了语音通话插件时才会出现。
+
+主要文档：
+
+- 语音通话插件：[语音通话](/plugins/voice-call)
+
+## 常用命令
+
+```bash
+quantumclaw voicecall status --call-id <id>
+quantumclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
+quantumclaw voicecall continue --call-id <id> --message "Any questions?"
+quantumclaw voicecall end --call-id <id>
+```
+
+## 暴露 Webhook（Tailscale）
+
+```bash
+quantumclaw voicecall expose --mode serve
+quantumclaw voicecall expose --mode funnel
+quantumclaw voicecall unexpose
+```
+
+安全提示：仅将 webhook 端点暴露给你信任的网络。尽可能优先使用 Tailscale Serve 而非 Funnel。

package/docs/zh-CN/cli/webhooks.md

@@ -0,0 +1,32 @@
+---
+read_when:
+  - 你想将 Gmail Pub/Sub 事件接入 QuantumClaw
+  - 你需要 Webhook 辅助命令
+summary: "`quantumclaw webhooks`（Webhook 辅助工具 + Gmail Pub/Sub）的 CLI 参考"
+title: webhooks
+x-i18n:
+  generated_at: "2026-02-01T20:21:38Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 785ec62afe6631b340ce4a4541ceb34cd6b97704cf7a9889762cb4c1f29a5ca0
+  source_path: cli/webhooks.md
+  workflow: 14
+---
+
+# `quantumclaw webhooks`
+
+Webhook 辅助工具和集成（Gmail Pub/Sub、Webhook 辅助工具）。
+
+相关内容：
+
+- Webhook：[Webhook](/automation/webhook)
+- Gmail Pub/Sub：[Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+quantumclaw webhooks gmail setup --account you@example.com
+quantumclaw webhooks gmail run
+```
+
+详情请参阅 [Gmail Pub/Sub 文档](/automation/gmail-pubsub)。

package/docs/zh-CN/concepts/agent-loop.md

@@ -0,0 +1,146 @@
+---
+read_when:
+  - 你需要智能体循环或生命周期事件的详细说明
+summary: 智能体循环生命周期、流和等待语义
+title: 智能体循环
+x-i18n:
+  generated_at: "2026-02-03T10:05:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0775b96eb3451e137297661a1095eaefb2bafeebb5f78123174a46290e18b014
+  source_path: concepts/agent-loop.md
+  workflow: 15
+---
+
+# 智能体循环（QuantumClaw）
+
+智能体循环是智能体的完整"真实"运行：接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。这是将消息转化为操作和最终回复的权威路径，同时保持会话状态的一致性。
+
+在 QuantumClaw 中，循环是每个会话的单次序列化运行，在模型思考、调用工具和流式输出时发出生命周期和流事件。本文档解释了这个真实循环是如何端到端连接的。
+
+## 入口点
+
+- Gateway 网关 RPC：`agent` 和 `agent.wait`。
+- CLI：`agent` 命令。
+
+## 工作原理（高层次）
+
+1. `agent` RPC 验证参数，解析会话（sessionKey/sessionId），持久化会话元数据，立即返回 `{ runId, acceptedAt }`。
+2. `agentCommand` 运行智能体：
+   - 解析模型 + 思考/详细模式默认值
+   - 加载 Skills 快照
+   - 调用 `runEmbeddedPiAgent`（pi-agent-core 运行时）
+   - 如果嵌入式循环未发出**生命周期结束/错误**事件，则发出该事件
+3. `runEmbeddedPiAgent`：
+   - 通过每会话 + 全局队列序列化运行
+   - 解析模型 + 认证配置文件并构建 pi 会话
+   - 订阅 pi 事件并流式传输助手/工具增量
+   - 强制执行超时 -> 超时则中止运行
+   - 返回有效负载 + 使用元数据
+4. `subscribeEmbeddedPiSession` 将 pi-agent-core 事件桥接到 QuantumClaw `agent` 流：
+   - 工具事件 => `stream: "tool"`
+   - 助手增量 => `stream: "assistant"`
+   - 生命周期事件 => `stream: "lifecycle"`（`phase: "start" | "end" | "error"`）
+5. `agent.wait` 使用 `waitForAgentJob`：
+   - 等待 `runId` 的**生命周期结束/错误**
+   - 返回 `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## 队列 + 并发
+
+- 运行按会话键（会话通道）序列化，可选择通过全局通道。
+- 这可以防止工具/会话竞争并保持会话历史的一致性。
+- 消息渠道可以选择队列模式（collect/steer/followup）来馈送此通道系统。参见[命令队列](/concepts/queue)。
+
+## 会话 + 工作区准备
+
+- 解析并创建工作区；沙箱隔离运行可能会重定向到沙箱工作区根目录。
+- 加载 Skills（或从快照中复用）并注入到环境和提示中。
+- 解析引导/上下文文件并注入到系统提示报告中。
+- 获取会话写锁；在流式传输之前打开并准备 `SessionManager`。
+
+## 提示组装 + 系统提示
+
+- 系统提示由 QuantumClaw 的基础提示、Skills 提示、引导上下文和每次运行的覆盖构建。
+- 强制执行模型特定的限制和压缩保留令牌。
+- 参见[系统提示](/concepts/system-prompt)了解模型看到的内容。
+
+## 钩子点（可以拦截的位置）
+
+QuantumClaw 有两个钩子系统：
+
+- **内部钩子**（Gateway 网关钩子）：用于命令和生命周期事件的事件驱动脚本。
+- **插件钩子**：智能体/工具生命周期和 Gateway 网关管道中的扩展点。
+
+### 内部钩子（Gateway 网关钩子）
+
+- **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。用于添加/删除引导上下文文件。
+- **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。
+
+参见[钩子](/automation/hooks)了解设置和示例。
+
+### 插件钩子（智能体 + Gateway 网关生命周期）
+
+这些在智能体循环或 Gateway 网关管道内运行：
+
+- **`before_agent_start`**：在运行开始前注入上下文或覆盖系统提示。
+- **`agent_end`**：在完成后检查最终消息列表和运行元数据。
+- **`before_compaction` / `after_compaction`**：观察或注释压缩周期。
+- **`before_tool_call` / `after_tool_call`**：拦截工具参数/结果。
+- **`tool_result_persist`**：在工具结果写入会话记录之前同步转换它们。
+- **`message_received` / `message_sending` / `message_sent`**：入站 + 出站消息钩子。
+- **`session_start` / `session_end`**：会话生命周期边界。
+- **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。
+
+参见[插件](/tools/plugin#plugin-hooks)了解钩子 API 和注册详情。
+
+## 流式传输 + 部分回复
+
+- 助手增量从 pi-agent-core 流式传输并作为 `assistant` 事件发出。
+- 分块流式传输可以在 `text_end` 或 `message_end` 时发出部分回复。
+- 推理流式传输可以作为单独的流或作为块回复发出。
+- 参见[流式传输](/concepts/streaming)了解分块和块回复行为。
+
+## 工具执行 + 消息工具
+
+- 工具开始/更新/结束事件在 `tool` 流上发出。
+- 工具结果在记录/发出之前会对大小和图像有效负载进行清理。
+- 消息工具发送会被跟踪以抑制重复的助手确认。
+
+## 回复整形 + 抑制
+
+- 最终有效负载由以下内容组装：
+  - 助手文本（和可选的推理）
+  - 内联工具摘要（当详细模式 + 允许时）
+  - 模型出错时的助手错误文本
+- `NO_REPLY` 被视为静默令牌，从出站有效负载中过滤。
+- 消息工具重复项从最终有效负载列表中移除。
+- 如果没有剩余可渲染的有效负载且工具出错，则发出回退工具错误回复（除非消息工具已经发送了用户可见的回复）。
+
+## 压缩 + 重试
+
+- 自动压缩发出 `compaction` 流事件，可以触发重试。
+- 重试时，内存缓冲区和工具摘要会重置以避免重复输出。
+- 参见[压缩](/concepts/compaction)了解压缩管道。
+
+## 事件流（当前）
+
+- `lifecycle`：由 `subscribeEmbeddedPiSession` 发出（以及作为 `agentCommand` 的回退）
+- `assistant`：从 pi-agent-core 流式传输的增量
+- `tool`：从 pi-agent-core 流式传输的工具事件
+
+## 聊天渠道处理
+
+- 助手增量被缓冲到聊天 `delta` 消息中。
+- 在**生命周期结束/错误**时发出聊天 `final`。
+
+## 超时
+
+- `agent.wait` 默认：30 秒（仅等待）。`timeoutMs` 参数可覆盖。
+- 智能体运行时：`agents.defaults.timeoutSeconds` 默认 600 秒；在 `runEmbeddedPiAgent` 中止计时器中强制执行。
+
+## 可能提前结束的情况
+
+- 智能体超时（中止）
+- AbortSignal（取消）
+- Gateway 网关断开连接或 RPC 超时
+- `agent.wait` 超时（仅等待，不会停止智能体）

package/docs/zh-CN/concepts/agent-workspace.md

@@ -0,0 +1,219 @@
+---
+read_when:
+  - 你需要解释智能体工作区或其文件布局
+  - 你想备份或迁移智能体工作区
+summary: 智能体工作区：位置、布局和备份策略
+title: 智能体工作区
+x-i18n:
+  generated_at: "2026-03-16T06:21:45Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 6854ddbebe2d21da08c4e1773da6a44f02c815070677821996dab4c91cfb9cd4
+  source_path: concepts/agent-workspace.md
+  workflow: 15
+---
+
+# 智能体工作区
+
+工作区是智能体的“家”。它是文件工具和工作区上下文所使用的唯一工作目录。请将其保持为私有，并将其视为记忆。
+
+这与存储配置、凭证和会话的 `~/.quantumclaw/` 是分开的。
+
+**重要：**工作区是**默认 cwd**，而不是硬性沙箱。工具会相对于工作区解析相对路径，但除非启用沙箱隔离，否则绝对路径仍然可以访问主机上的其他位置。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体配置的沙箱）。启用沙箱隔离后，如果 `workspaceAccess` 不是 `"rw"`，工具会在 `~/.quantumclaw/sandboxes` 下的沙箱工作区中运行，而不是在你的主机工作区中运行。
+
+## 默认位置
+
+- 默认值：`~/.quantumclaw/workspace`
+- 如果设置了 `QUANTUMCLAW_PROFILE` 且其值不是 `"default"`，默认值将变为
+  `~/.quantumclaw/workspace-<profile>`。
+- 在 `~/.quantumclaw/quantumclaw.json` 中覆盖：
+
+```json5
+{
+  agent: {
+    workspace: "~/.quantumclaw/workspace",
+  },
+}
+```
+
+`quantumclaw onboard`、`quantumclaw configure` 或 `quantumclaw setup` 会在工作区缺失时创建工作区并植入引导文件。
+沙箱种子复制仅接受工作区内的常规文件；解析到源工作区外部的符号链接/硬链接别名会被忽略。
+
+如果你已经自行管理工作区文件，可以禁用引导文件创建：
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## 额外的工作区文件夹
+
+较旧的安装可能创建过 `~/quantumclaw`。保留多个工作区目录可能会导致令人困惑的凭证或状态漂移，因为同一时间只有一个工作区处于活动状态。
+
+**建议：**只保留一个活动工作区。如果你不再使用额外的文件夹，请将其归档或移到废纸篓（例如 `trash ~/quantumclaw`）。
+如果你有意保留多个工作区，请确保
+`agents.defaults.workspace` 指向当前活动的那个。
+
+当 `quantumclaw doctor` 检测到额外的工作区目录时，会发出警告。
+
+## 工作区文件映射（每个文件的含义）
+
+以下是 QuantumClaw 在工作区内预期的标准文件：
+
+- `AGENTS.md`
+  - 智能体的操作说明，以及它应如何使用记忆。
+  - 每次会话开始时加载。
+  - 很适合放置规则、优先级和“如何表现”之类的细节。
+
+- `SOUL.md`
+  - 人设、语气和边界。
+  - 每次会话都会加载。
+
+- `USER.md`
+  - 用户是谁，以及应如何称呼他们。
+  - 每次会话都会加载。
+
+- `IDENTITY.md`
+  - 智能体的名称、风格和 emoji。
+  - 在引导仪式期间创建/更新。
+
+- `TOOLS.md`
+  - 关于你的本地工具和约定的说明。
+  - 它不控制工具可用性；仅提供指导。
+
+- `HEARTBEAT.md`
+  - 可选的心跳运行微型检查清单。
+  - 保持简短以避免消耗过多 token。
+
+- `BOOT.md`
+  - 可选的启动检查清单；当启用内部 hooks 时，会在 Gateway 网关重启时执行。
+  - 保持简短；出站发送请使用消息工具。
+
+- `BOOTSTRAP.md`
+  - 一次性的首次运行仪式。
+  - 仅为全新的工作区创建。
+  - 仪式完成后请将其删除。
+
+- `memory/YYYY-MM-DD.md`
+  - 每日记忆日志（每天一个文件）。
+  - 建议在会话开始时阅读今天和昨天的内容。
+
+- `MEMORY.md`（可选）
+  - 精选的长期记忆。
+  - 仅在主私有会话中加载（不在共享/群组上下文中加载）。
+
+有关工作流和自动记忆刷新，请参见[记忆](/concepts/memory)。
+
+- `skills/`（可选）
+  - 工作区专用技能。
+  - 名称冲突时会覆盖托管/捆绑的 Skills。
+
+- `canvas/`（可选）
+  - 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
+
+如果任何引导文件缺失，QuantumClaw 会在会话中注入一个“缺失文件”标记并继续执行。注入时，大型引导文件会被截断；可使用 `agents.defaults.bootstrapMaxChars`（默认：20000）和 `agents.defaults.bootstrapTotalMaxChars`（默认：150000）调整限制。
+`quantumclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有文件。
+
+## 不在工作区中的内容
+
+这些内容位于 `~/.quantumclaw/` 下，**不应**提交到工作区仓库：
+
+- `~/.quantumclaw/quantumclaw.json`（配置）
+- `~/.quantumclaw/credentials/`（OAuth 令牌、API 密钥）
+- `~/.quantumclaw/agents/<agentId>/sessions/`（会话记录和元数据）
+- `~/.quantumclaw/skills/`（托管 Skills）
+
+如果你需要迁移会话或配置，请单独复制它们，并确保不要将其纳入版本控制。
+
+## Git 备份（推荐，私有）
+
+将工作区视为私有记忆。把它放进一个**私有** git 仓库，以便备份并可恢复。
+
+请在 Gateway 网关运行的机器上执行这些步骤（工作区就位于那里）。
+
+### 1）初始化仓库
+
+如果已安装 git，全新工作区会自动初始化。如果这个工作区还不是仓库，请运行：
+
+```bash
+cd ~/.quantumclaw/workspace
+git init
+git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
+git commit -m "Add agent workspace"
+```
+
+### 2）添加私有远程仓库（适合新手的选项）
+
+选项 A：GitHub Web UI
+
+1. 在 GitHub 上创建一个新的**私有**仓库。
+2. 不要使用 README 初始化（以避免合并冲突）。
+3. 复制 HTTPS 远程 URL。
+4. 添加远程仓库并推送：
+
+```bash
+git branch -M main
+git remote add origin <https-url>
+git push -u origin main
+```
+
+选项 B：GitHub CLI（`gh`）
+
+```bash
+gh auth login
+gh repo create quantumclaw-workspace --private --source . --remote origin --push
+```
+
+选项 C：GitLab Web UI
+
+1. 在 GitLab 上创建一个新的**私有**仓库。
+2. 不要使用 README 初始化（以避免合并冲突）。
+3. 复制 HTTPS 远程 URL。
+4. 添加远程仓库并推送：
+
+```bash
+git branch -M main
+git remote add origin <https-url>
+git push -u origin main
+```
+
+### 3）持续更新
+
+```bash
+git status
+git add .
+git commit -m "Update memory"
+git push
+```
+
+## 不要提交密钥
+
+即使在私有仓库中，也应避免在工作区中存储密钥：
+
+- API 密钥、OAuth 令牌、密码或私有凭证。
+- `~/.quantumclaw/` 下的任何内容。
+- 聊天原始转储或敏感附件。
+
+如果你必须存储敏感引用，请使用占位符，并将真实密钥保存在其他地方（密码管理器、环境变量或 `~/.quantumclaw/`）。
+
+建议的 `.gitignore` 起始内容：
+
+```gitignore
+.DS_Store
+.env
+**/*.key
+**/*.pem
+**/secrets*
+```
+
+## 将工作区迁移到新机器
+
+1. 将仓库克隆到所需路径（默认是 `~/.quantumclaw/workspace`）。
+2. 在 `~/.quantumclaw/quantumclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
+3. 运行 `quantumclaw setup --workspace <path>` 以植入任何缺失的文件。
+4. 如果你需要会话，请将旧机器上的 `~/.quantumclaw/agents/<agentId>/sessions/` 单独复制过来。
+
+## 高级说明
+
+- 多智能体路由可以为不同智能体使用不同的工作区。有关路由配置，请参见
+  [渠道路由](/channels/channel-routing)。
+- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话划分的沙箱工作区。

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

@@ -0,0 +1,115 @@
+---
+read_when:
+  - 更改智能体运行时、工作区引导或会话行为时
+summary: 智能体运行时（嵌入式 pi-mono）、工作区契约和会话引导
+title: 智能体运行时
+x-i18n:
+  generated_at: "2026-02-03T10:04:53Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 04b4e0bc6345d2afd9a93186e5d7a02a393ec97da2244e531703cb6a1c182325
+  source_path: concepts/agent.md
+  workflow: 15
+---
+
+# 智能体运行时 🤖
+
+QuantumClaw 运行一个源自 **pi-mono** 的嵌入式智能体运行时。
+
+## 工作区（必需）
+
+QuantumClaw 使用单一智能体工作区目录（`agents.defaults.workspace`）作为智能体**唯一**的工作目录（`cwd`），用于工具和上下文。
+
+建议：使用 `quantumclaw setup` 在缺失时创建 `~/.quantumclaw/quantumclaw.json` 并初始化工作区文件。
+
+完整工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
+
+如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话隔离的工作区覆盖此设置（参见 [Gateway 网关配置](/gateway/configuration)）。
+
+## 引导文件（注入）
+
+在 `agents.defaults.workspace` 内，QuantumClaw 期望以下用户可编辑的文件：
+
+- `AGENTS.md` — 操作指令 + "记忆"
+- `SOUL.md` — 人设、边界、语气
+- `TOOLS.md` — 用户维护的工具说明（例如 `imsg`、`sag`、约定）
+- `BOOTSTRAP.md` — 一次性首次运行仪式（完成后删除）
+- `IDENTITY.md` — 智能体名称/风格/表情
+- `USER.md` — 用户档案 + 偏好称呼
+
+在新会话的第一轮，QuantumClaw 将这些文件的内容直接注入智能体上下文。
+
+空文件会被跳过。大文件会被修剪和截断并添加标记，以保持提示词精简（阅读文件获取完整内容）。
+
+如果文件缺失，QuantumClaw 会注入一行"文件缺失"标记（`quantumclaw setup` 将创建安全的默认模板）。
+
+`BOOTSTRAP.md` 仅在**全新工作区**（没有其他引导文件存在）时创建。如果你在完成仪式后删除它，后续重启不应重新创建。
+
+要完全禁用引导文件创建（用于预置工作区），请设置：
+
+```json5
+{ agent: { skipBootstrap: true } }
+```
+
+## 内置工具
+
+核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。`apply_patch` 是可选的，由 `tools.exec.applyPatch` 控制。`TOOLS.md` **不**控制哪些工具存在；它是关于*你*希望如何使用它们的指导。
+
+## Skills
+
+QuantumClaw 从三个位置加载 Skills（名称冲突时工作区优先）：
+
+- 内置（随安装包提供）
+- 托管/本地：`~/.quantumclaw/skills`
+- 工作区：`<workspace>/skills`
+
+Skills 可通过配置/环境变量控制（参见 [Gateway 网关配置](/gateway/configuration) 中的 `skills`）。
+
+## pi-mono 集成
+
+QuantumClaw 复用 pi-mono 代码库的部分内容（模型/工具），但**会话管理、设备发现和工具连接由 QuantumClaw 负责**。
+
+- 无 pi-coding 智能体运行时。
+- 不读取 `~/.pi/agent` 或 `<workspace>/.pi` 设置。
+
+## 会话
+
+会话记录以 JSONL 格式存储在：
+
+- `~/.quantumclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
+
+会话 ID 是稳定的，由 QuantumClaw 选择。
+**不**读取旧版 Pi/Tau 会话文件夹。
+
+## 流式传输中的引导
+
+当队列模式为 `steer` 时，入站消息会注入当前运行。
+队列在**每次工具调用后**检查；如果存在排队消息，当前助手消息的剩余工具调用将被跳过（工具结果显示错误"Skipped due to queued user message."），然后在下一个助手响应前注入排队的用户消息。
+
+当队列模式为 `followup` 或 `collect` 时，入站消息会保留到当前轮次结束，然后使用排队的载荷开始新的智能体轮次。参见 [队列](/concepts/queue) 了解模式 + 防抖/上限行为。
+
+分块流式传输在助手块完成后立即发送；默认为**关闭**（`agents.defaults.blockStreamingDefault: "off"`）。
+通过 `agents.defaults.blockStreamingBreak` 调整边界（`text_end` 与 `message_end`；默认为 text_end）。
+使用 `agents.defaults.blockStreamingChunk` 控制软块分块（默认 800–1200 字符；优先段落分隔，其次换行；最后是句子）。
+使用 `agents.defaults.blockStreamingCoalesce` 合并流式块以减少单行刷屏（发送前基于空闲的合并）。非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 以启用分块回复。
+工具启动时发出详细工具摘要（无防抖）；Control UI 在可用时通过智能体事件流式传输工具输出。
+更多详情：[流式传输 + 分块](/concepts/streaming)。
+
+## 模型引用
+
+配置中的模型引用（例如 `agents.defaults.model` 和 `agents.defaults.models`）通过在**第一个** `/` 处分割来解析。
+
+- 配置模型时使用 `provider/model`。
+- 如果模型 ID 本身包含 `/`（OpenRouter 风格），请包含提供商前缀（例如：`openrouter/moonshotai/kimi-k2`）。
+- 如果省略提供商，QuantumClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
+
+## 配置（最小）
+
+至少需要设置：
+
+- `agents.defaults.workspace`
+- `channels.whatsapp.allowFrom`（强烈建议）
+
+---
+
+_下一篇：[群聊](/channels/group-messages)_ 🦞