@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/help/debugging.md

@@ -0,0 +1,160 @@
+---
+read_when:
+  - 你需要检查原始模型输出以查找推理泄漏
+  - 你想在迭代时以监视模式运行 Gateway 网关
+  - 你需要可重复的调试工作流
+summary: 调试工具：监视模式、原始模型流和追踪推理泄漏
+title: 调试
+x-i18n:
+  generated_at: "2026-02-03T07:47:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a
+  source_path: help/debugging.md
+  workflow: 15
+---
+
+# 调试
+
+本页介绍用于流式输出的调试辅助工具，特别是当提供商将推理混入正常文本时。
+
+## 运行时调试覆盖
+
+在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（内存中，不写入磁盘）。
+`/debug` 默认禁用；通过 `commands.debug: true` 启用。
+当你需要切换不常用的设置而不编辑 `quantumclaw.json` 时，这非常方便。
+
+示例：
+
+```
+/debug show
+/debug set messages.responsePrefix="[quantumclaw]"
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+`/debug reset` 清除所有覆盖并返回到磁盘上的配置。
+
+## Gateway 网关监视模式
+
+为了快速迭代，在文件监视器下运行 Gateway 网关：
+
+```bash
+pnpm gateway:watch --force
+```
+
+这映射到：
+
+```bash
+tsx watch src/entry.ts gateway --force
+```
+
+在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们将在每次重启时传递。
+
+## Dev 配置文件 + dev Gateway 网关（--dev）
+
+使用 dev 配置文件来隔离状态，并启动一个安全、可丢弃的调试设置。有**两个** `--dev` 标志：
+
+- **全局 `--dev`（配置文件）：** 将状态隔离到 `~/.quantumclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之移动）。
+- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+
+推荐流程（dev 配置文件 + dev 引导）：
+
+```bash
+pnpm gateway:dev
+QUANTUMCLAW_PROFILE=dev quantumclaw tui
+```
+
+如果你还没有全局安装，请通过 `pnpm quantumclaw ...` 运行 CLI。
+
+这会执行：
+
+1. **配置文件隔离**（全局 `--dev`）
+   - `QUANTUMCLAW_PROFILE=dev`
+   - `QUANTUMCLAW_STATE_DIR=~/.quantumclaw-dev`
+   - `QUANTUMCLAW_CONFIG_PATH=~/.quantumclaw-dev/quantumclaw.json`
+   - `QUANTUMCLAW_GATEWAY_PORT=19001`（浏览器/画布相应移动）
+
+2. **Dev 引导**（`gateway --dev`）
+   - 如果缺失则写入最小配置（`gateway.mode=local`，绑定 loopback）。
+   - 将 `agent.workspace` 设置为 dev 工作区。
+   - 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
+   - 如果缺失则填充工作区文件：
+     `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
+   - 默认身份：**C3‑PO**（礼仪机器人）。
+   - 在 dev 模式下跳过渠道提供商（`QUANTUMCLAW_SKIP_CHANNELS=1`）。
+
+重置流程（全新开始）：
+
+```bash
+pnpm gateway:dev:reset
+```
+
+注意：`--dev` 是**全局**配置文件标志，会被某些运行器吞掉。
+如果你需要明确拼写，请使用环境变量形式：
+
+```bash
+QUANTUMCLAW_PROFILE=dev quantumclaw gateway --dev --reset
+```
+
+`--reset` 清除配置、凭证、会话和 dev 工作区（使用 `trash`，而非 `rm`），然后重新创建默认的 dev 设置。
+
+提示：如果非 dev Gateway 网关已在运行（launchd/systemd），请先停止它：
+
+```bash
+quantumclaw gateway stop
+```
+
+## 原始流日志（QuantumClaw）
+
+QuantumClaw 可以在任何过滤/格式化之前记录**原始助手流**。
+这是查看推理是否作为纯文本增量到达（或作为单独的思考块）的最佳方式。
+
+通过 CLI 启用：
+
+```bash
+pnpm gateway:watch --force --raw-stream
+```
+
+可选路径覆盖：
+
+```bash
+pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.quantumclaw/logs/raw-stream.jsonl
+```
+
+等效环境变量：
+
+```bash
+QUANTUMCLAW_RAW_STREAM=1
+QUANTUMCLAW_RAW_STREAM_PATH=~/.quantumclaw/logs/raw-stream.jsonl
+```
+
+默认文件：
+
+`~/.quantumclaw/logs/raw-stream.jsonl`
+
+## 原始块日志（pi-mono）
+
+要在解析为块之前捕获**原始 OpenAI 兼容块**，pi-mono 暴露了一个单独的日志记录器：
+
+```bash
+PI_RAW_STREAM=1
+```
+
+可选路径：
+
+```bash
+PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
+```
+
+默认文件：
+
+`~/.pi-mono/logs/raw-openai-completions.jsonl`
+
+> 注意：这仅由使用 pi-mono 的 `openai-completions` 提供商的进程发出。
+
+## 安全注意事项
+
+- 原始流日志可能包含完整提示、工具输出和用户数据。
+- 保持日志在本地并在调试后删除它们。
+- 如果你分享日志，请先清除密钥和个人身份信息。

package/docs/zh-CN/help/environment.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你需要知道哪些环境变量被加载，以及加载顺序
+  - 你在调试 Gateway 网关中缺失的 API 密钥
+  - 你在编写提供商认证或部署环境的文档
+summary: QuantumClaw 从哪里加载环境变量以及优先级顺序
+title: 环境变量
+x-i18n:
+  generated_at: "2026-02-03T07:47:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546
+  source_path: help/environment.md
+  workflow: 15
+---
+
+# 环境变量
+
+QuantumClaw 从多个来源拉取环境变量。规则是**永不覆盖现有值**。
+
+## 优先级（从高到低）
+
+1. **进程环境**（Gateway 网关进程从父 shell/守护进程已有的内容）。
+2. **当前工作目录中的 `.env`**（dotenv 默认；不覆盖）。
+3. **全局 `.env`** 位于 `~/.quantumclaw/.env`（即 `$QUANTUMCLAW_STATE_DIR/.env`；不覆盖）。
+4. **配置 `env` 块** 位于 `~/.quantumclaw/quantumclaw.json`（仅在缺失时应用）。
+5. **可选的登录 shell 导入**（`env.shellEnv.enabled` 或 `QUANTUMCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键名应用。
+
+如果配置文件完全缺失，步骤 4 将被跳过；如果启用了 shell 导入，它仍会运行。
+
+## 配置 `env` 块
+
+两种等效方式设置内联环境变量（都是非覆盖的）：
+
+```json5
+{
+  env: {
+    OPENROUTER_API_KEY: "sk-or-...",
+    vars: {
+      GROQ_API_KEY: "gsk-...",
+    },
+  },
+}
+```
+
+## Shell 环境导入
+
+`env.shellEnv` 运行你的登录 shell 并仅导入**缺失的**预期键名：
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000,
+    },
+  },
+}
+```
+
+环境变量等效项：
+
+- `QUANTUMCLAW_LOAD_SHELL_ENV=1`
+- `QUANTUMCLAW_SHELL_ENV_TIMEOUT_MS=15000`
+
+## 配置中的环境变量替换
+
+你可以使用 `${VAR_NAME}` 语法在配置字符串值中直接引用环境变量：
+
+```json5
+{
+  models: {
+    providers: {
+      "vercel-gateway": {
+        apiKey: "${VERCEL_GATEWAY_API_KEY}",
+      },
+    },
+  },
+}
+```
+
+完整详情参见[配置：环境变量替换](/gateway/configuration#env-var-substitution-in-config)。
+
+## 相关内容
+
+- [Gateway 网关配置](/gateway/configuration)
+- [常见问题：环境变量和 .env 加载](/help/faq#env-vars-and-env-loading)
+- [模型概述](/concepts/models)