@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/reference/AGENTS.default.md

@@ -0,0 +1,131 @@
+---
+read_when:
+  - 启动新的 QuantumClaw 智能体会话
+  - 启用或审计默认 Skills
+summary: 个人助手设置的默认 QuantumClaw 智能体指令和 Skills 列表
+x-i18n:
+  generated_at: "2026-02-03T10:09:19Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 20ec2b8d8fc03c16bbf0a75f011092e86382ca4182e8c0a4bc5f8ffd2be9c647
+  source_path: reference/AGENTS.default.md
+  workflow: 15
+---
+
+# AGENTS.md — QuantumClaw 个人助手（默认）
+
+## 首次运行（推荐）
+
+QuantumClaw 为智能体使用专用的工作区目录。默认：`~/.quantumclaw/workspace`（可通过 `agents.defaults.workspace` 配置）。
+
+1. 创建工作区（如果尚不存在）：
+
+```bash
+mkdir -p ~/.quantumclaw/workspace
+```
+
+2. 将默认工作区模板复制到工作区：
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.quantumclaw/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.quantumclaw/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.quantumclaw/workspace/TOOLS.md
+```
+
+3. 可选：如果你想要个人助手 Skills 列表，用此文件替换 AGENTS.md：
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.quantumclaw/workspace/AGENTS.md
+```
+
+4. 可选：通过设置 `agents.defaults.workspace` 选择不同的工作区（支持 `~`）：
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.quantumclaw/workspace" } },
+}
+```
+
+## 安全默认值
+
+- 不要将目录或密钥转储到聊天中。
+- 除非明确要求，否则不要运行破坏性命令。
+- 不要向外部消息界面发送部分/流式回复（仅发送最终回复）。
+
+## 会话开始（必需）
+
+- 读取 `SOUL.md`、`USER.md`、`memory.md`，以及 `memory/` 中的今天和昨天的文件。
+- 在回复之前完成此操作。
+
+## Soul（必需）
+
+- `SOUL.md` 定义身份、语气和边界。保持其更新。
+- 如果你更改了 `SOUL.md`，告知用户。
+- 你是每个会话的新实例；连续性存在于这些文件中。
+
+## 共享空间（推荐）
+
+- 你不是用户的代言人；在群聊或公共频道中要小心。
+- 不要分享私人数据、联系信息或内部笔记。
+
+## 记忆系统（推荐）
+
+- 每日日志：`memory/YYYY-MM-DD.md`（如需要请创建 `memory/`）。
+- 长期记忆：`memory.md` 用于持久的事实、偏好和决定。
+- 会话开始时，读取今天 + 昨天 + `memory.md`（如果存在）。
+- 捕获：决定、偏好、约束、待办事项。
+- 除非明确要求，否则避免存储密钥。
+
+## 工具和 Skills
+
+- 工具存在于 Skills 中；需要时遵循每个 Skill 的 `SKILL.md`。
+- 在 `TOOLS.md` 中保存环境特定的笔记（Skills 注意事项）。
+
+## 备份提示（推荐）
+
+如果你将此工作区视为 Clawd 的"记忆"，请将其设为 git 仓库（最好是私有的），这样 `AGENTS.md` 和你的记忆文件就会被备份。
+
+```bash
+cd ~/.quantumclaw/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# 可选：添加私有远程仓库 + push
+```
+
+## QuantumClaw 的功能
+
+- 运行 WhatsApp Gateway 网关 + Pi 编程智能体，使助手可以读写聊天、获取上下文，并通过主机 Mac 运行 Skills。
+- macOS 应用管理权限（屏幕录制、通知、麦克风）并通过其内置二进制文件暴露 `quantumclaw` CLI。
+- 私聊默认折叠到智能体的 `main` 会话；群组保持隔离为 `agent:<agentId>:<channel>:group:<id>`（房间/频道：`agent:<agentId>:<channel>:channel:<id>`）；心跳保持后台任务存活。
+
+## 核心 Skills（在设置 → Skills 中启用）
+
+- **mcporter** — 用于管理外部 Skill 后端的工具服务器运行时/CLI。
+- **Peekaboo** — 快速 macOS 截图，可选 AI 视觉分析。
+- **camsnap** — 从 RTSP/ONVIF 安防摄像头捕获帧、片段或运动警报。
+- **oracle** — 支持 OpenAI 的智能体 CLI，具有会话回放和浏览器控制。
+- **eightctl** — 从终端控制你的睡眠。
+- **imsg** — 发送、读取、流式传输 iMessage 和短信。
+- **wacli** — WhatsApp CLI：同步、搜索、发送。
+- **discord** — Discord 操作：回应、贴纸、投票。使用 `user:<id>` 或 `channel:<id>` 目标（纯数字 id 有歧义）。
+- **gog** — Google Suite CLI：Gmail、日历、云端硬盘、通讯录。
+- **spotify-player** — 终端 Spotify 客户端，用于搜索/排队/控制播放。
+- **sag** — 具有 mac 风格 say UX 的 ElevenLabs 语音；默认流式输出到扬声器。
+- **Sonos CLI** — 从脚本控制 Sonos 扬声器（发现/状态/播放/音量/分组）。
+- **blucli** — 从脚本播放、分组和自动化 BluOS 播放器。
+- **OpenHue CLI** — 用于场景和自动化的 Philips Hue 照明控制。
+- **OpenAI Whisper** — 本地语音转文字，用于快速听写和语音邮件转录。
+- **Gemini CLI** — 从终端使用 Google Gemini 模型进行快速问答。
+- **bird** — X/Twitter CLI，无需浏览器即可发推、回复、阅读话题和搜索。
+- **agent-tools** — 用于自动化和辅助脚本的实用工具包。
+
+## 使用说明
+
+- 脚本编写优先使用 `quantumclaw` CLI；mac 应用处理权限。
+- 从 Skills 标签页运行安装；如果二进制文件已存在，它会隐藏按钮。
+- 保持心跳启用，以便助手可以安排提醒、监控收件箱和触发摄像头捕获。
+- Canvas UI 以全屏运行并带有原生叠加层。避免在左上/右上/底部边缘放置关键控件；在布局中添加显式边距，不要依赖安全区域内边距。
+- 对于浏览器驱动的验证，使用带有 QuantumClaw 管理的 Chrome 配置文件的 `quantumclaw browser`（tabs/status/screenshot）。
+- 对于 DOM 检查，使用 `quantumclaw browser eval|query|dom|snapshot`（需要机器输出时使用 `--json`/`--out`）。
+- 对于交互，使用 `quantumclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click/type 需要 snapshot 引用；CSS 选择器使用 `evaluate`）。

package/docs/zh-CN/reference/RELEASING.md

@@ -0,0 +1,48 @@
+---
+read_when:
+  - 查找公开发布渠道的定义
+  - 查找版本命名与发布节奏
+summary: 公开发布渠道、版本命名与发布节奏
+title: 发布策略
+x-i18n:
+  generated_at: "2026-03-15T19:23:11Z"
+  model: claude-opus-4-6
+  provider: pi
+  source_hash: df332d3169de7099661725d9266955456e80fc3d3ff95cb7aaf9997a02f0baaf
+  source_path: reference/RELEASING.md
+  workflow: 15
+---
+
+# 发布策略
+
+QuantumClaw 有三个公开发布渠道：
+
+- stable：带标签的正式发布，发布到 npm `latest`
+- beta：预发布标签，发布到 npm `beta`
+- dev：`main` 分支的最新提交
+
+## 版本命名
+
+- 正式发布版本号：`YYYY.M.D`
+  - Git 标签：`vYYYY.M.D`
+- Beta 预发布版本号：`YYYY.M.D-beta.N`
+  - Git 标签：`vYYYY.M.D-beta.N`
+- 月份和日期不补零
+- `latest` 表示当前 npm 正式发布版本
+- `beta` 表示当前 npm 预发布版本
+- Beta 版本可能会在 macOS 应用跟进之前发布
+
+## 发布节奏
+
+- 发布遵循 beta 优先原则
+- 仅在最新的 beta 版本验证通过后才会发布正式版本
+- 详细的发布流程、审批、凭证和恢复说明仅限维护者查阅
+
+## 公开参考
+
+- [`.github/workflows/quantumclaw-npm-release.yml`](https://github.com/quantumclaw/quantumclaw/blob/main/.github/workflows/quantumclaw-npm-release.yml)
+- [`scripts/quantumclaw-npm-release-check.ts`](https://github.com/quantumclaw/quantumclaw/blob/main/scripts/quantumclaw-npm-release-check.ts)
+
+维护者使用
+[`quantumclaw/maintainers/release/README.md`](https://github.com/quantumclaw/maintainers/blob/main/release/README.md)
+中的私有发布文档作为实际操作手册。

package/docs/zh-CN/reference/api-usage-costs.md

@@ -0,0 +1,141 @@
+---
+read_when:
+  - 你想了解哪些功能可能调用付费 API
+  - 你需要审核密钥、费用和用量可见性
+  - 你正在解释 /status 或 /usage 的费用报告
+summary: 审核哪些功能会产生费用、使用了哪些密钥以及如何查看用量
+title: API 用量与费用
+x-i18n:
+  generated_at: "2026-02-01T21:37:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 807d0d88801e919a8246517820644db1e6271d165fa376b2e637f05a9121d8b1
+  source_path: reference/api-usage-costs.md
+  workflow: 15
+---
+
+# API 用量与费用
+
+本文档列出了**可能调用 API 密钥的功能**及其费用的显示位置。重点介绍 QuantumClaw 中可能产生提供商用量或付费 API 调用的功能。
+
+## 费用显示位置（聊天 + CLI）
+
+**每会话费用快照**
+
+- `/status` 显示当前会话模型、上下文用量和上次响应的 token 数。
+- 如果模型使用 **API 密钥认证**，`/status` 还会显示上次回复的**预估费用**。
+
+**每条消息费用页脚**
+
+- `/usage full` 在每条回复后附加用量页脚，包括**预估费用**（仅限 API 密钥）。
+- `/usage tokens` 仅显示 token 数；OAuth 流程会隐藏美元费用。
+
+**CLI 用量窗口（提供商配额）**
+
+- `quantumclaw status --usage` 和 `quantumclaw channels list` 显示提供商**用量窗口**（配额快照，非每条消息的费用）。
+
+详情和示例请参阅 [Token 用量与费用](/reference/token-use)。
+
+## 密钥的发现方式
+
+QuantumClaw 可以从以下来源获取凭据：
+
+- **认证配置文件**（按智能体配置，存储在 `auth-profiles.json` 中）。
+- **环境变量**（例如 `OPENAI_API_KEY`、`BRAVE_API_KEY`、`FIRECRAWL_API_KEY`）。
+- **配置文件**（`models.providers.*.apiKey`、`tools.web.search.*`、`tools.web.fetch.firecrawl.*`、`memorySearch.*`、`talk.apiKey`）。
+- **Skills**（`skills.entries.<name>.apiKey`），可能会将密钥导出到 Skills 进程的环境变量中。
+
+## 可能消耗密钥的功能
+
+### 1）核心模型响应（聊天 + 工具）
+
+每次回复或工具调用都使用**当前模型提供商**（OpenAI、Anthropic 等）。这是用量和费用的主要来源。
+
+定价配置请参阅[模型](/providers/models)，显示方式请参阅 [Token 用量与费用](/reference/token-use)。
+
+### 2）媒体理解（音频/图像/视频）
+
+入站媒体可以在回复生成前进行摘要/转录。这会使用模型/提供商 API。
+
+- 音频：OpenAI / Groq / Deepgram（当密钥存在时**自动启用**）。
+- 图像：OpenAI / Anthropic / Google。
+- 视频：Google。
+
+请参阅[媒体理解](/nodes/media-understanding)。
+
+### 3）记忆嵌入 + 语义搜索
+
+语义记忆搜索在配置为远程提供商时使用**嵌入 API**：
+
+- `memorySearch.provider = "openai"` → OpenAI 嵌入
+- `memorySearch.provider = "gemini"` → Gemini 嵌入
+- 本地嵌入失败时可选回退到 OpenAI
+
+你可以使用 `memorySearch.provider = "local"` 保持本地运行（无 API 用量）。
+
+请参阅[记忆](/concepts/memory)。
+
+### 4）网页搜索工具（Brave / 通过 OpenRouter 使用 Perplexity）
+
+`web_search` 使用 API 密钥，可能产生使用费用：
+
+- **Brave Search API**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
+- **Gemini**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey`
+- **Grok**：`XAI_API_KEY` 或 `plugins.entries.xai.config.webSearch.apiKey`
+- **Kimi**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey`
+- **Perplexity**：`PERPLEXITY_API_KEY`、`OPENROUTER_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
+
+旧的 `tools.web.search.*` 提供商路径仍会通过兼容层加载，但不再是推荐配置方式。
+
+**Brave 免费套餐（额度充裕）：**
+
+- **每月 2,000 次请求**
+- **每秒 1 次请求**
+- **需要信用卡**进行验证（除非升级否则不会收费）
+
+请参阅[网页工具](/tools/web)。
+
+### 5）网页抓取工具（Firecrawl）
+
+`web_fetch` 在存在 API 密钥时可以调用 **Firecrawl**：
+
+- `FIRECRAWL_API_KEY` 或 `tools.web.fetch.firecrawl.apiKey`
+
+如果未配置 Firecrawl，该工具会回退到直接抓取 + 可读性提取（无付费 API）。
+
+请参阅[网页工具](/tools/web)。
+
+### 6）提供商用量快照（状态/健康检查）
+
+某些状态命令会调用**提供商用量端点**以显示配额窗口或认证健康状态。这些通常是低频调用，但仍会访问提供商 API：
+
+- `quantumclaw status --usage`
+- `quantumclaw models status --json`
+
+请参阅[模型 CLI](/cli/models)。
+
+### 7）压缩保护摘要
+
+压缩保护功能可以使用**当前模型**对会话历史进行摘要，运行时会调用提供商 API。
+
+请参阅[会话管理 + 压缩](/reference/session-management-compaction)。
+
+### 8）模型扫描/探测
+
+`quantumclaw models scan` 可以探测 OpenRouter 模型，启用探测时会使用 `OPENROUTER_API_KEY`。
+
+请参阅[模型 CLI](/cli/models)。
+
+### 9）语音对话（Talk）
+
+语音对话模式在配置后可以调用 **ElevenLabs**：
+
+- `ELEVENLABS_API_KEY` 或 `talk.apiKey`
+
+请参阅[语音对话模式](/nodes/talk)。
+
+### 10）Skills（第三方 API）
+
+Skills 可以在 `skills.entries.<name>.apiKey` 中存储 `apiKey`。如果 Skills 使用该密钥调用外部 API，则会根据 Skills 的提供商产生费用。
+
+请参阅[Skills](/tools/skills)。

package/docs/zh-CN/reference/credits.md

@@ -0,0 +1,34 @@
+---
+read_when:
+  - 你想了解项目背景故事或贡献者致谢信息
+summary: 项目起源、贡献者和许可证。
+title: 致谢
+x-i18n:
+  generated_at: "2026-02-04T17:53:19Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d55e520313e131025b22cb20b3d2fbd44619e1668d09b5bd9d56d7df019bc46c
+  source_path: reference/credits.md
+  workflow: 15
+---
+
+## 名称由来
+
+QuantumClaw = CLAW + TARDIS，因为每只太空龙虾都需要一台时空机器。
+
+## 致谢
+
+- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - 创建者，龙虾语者
+- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi 创建者，安全渗透测试员
+- **Clawd** - 那只要求取个更好名字的太空龙虾
+
+## 核心贡献者
+
+- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - 位置解析（Telegram 和 WhatsApp）
+
+## 许可证
+
+MIT - 像海洋中的龙虾一样自由。
+
+> "我们都只是在玩自己的提示词而已。"（某个 AI，大概是 token 吸多了）

package/docs/zh-CN/reference/device-models.md

@@ -0,0 +1,54 @@
+---
+read_when:
+  - 更新设备型号标识符映射或 NOTICE/许可证文件
+  - 更改实例 UI 中设备名称的显示方式
+summary: QuantumClaw 如何内置 Apple 设备型号标识符以在 macOS 应用中显示友好名称。
+title: 设备型号数据库
+x-i18n:
+  generated_at: "2026-02-01T21:37:07Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1d99c2538a0d8fdd80fa468fa402f63479ef2522e83745a0a46527a86238aeb2
+  source_path: reference/device-models.md
+  workflow: 15
+---
+
+# 设备型号数据库（友好名称）
+
+macOS 配套应用通过将 Apple 型号标识符（例如 `iPad16,6`、`Mac16,6`）映射为人类可读的名称，在**实例** UI 中显示友好的 Apple 设备型号名称。
+
+该映射以 JSON 形式内置于：
+
+- `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/`
+
+## 数据来源
+
+我们目前内置的映射来自 MIT 许可的仓库：
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+为保持构建的确定性，JSON 文件固定到特定的上游提交（记录在 `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/NOTICE.md` 中）。
+
+## 更新数据库
+
+1. 选择要固定的上游提交（iOS 和 macOS 各一个）。
+2. 更新 `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/NOTICE.md` 中的提交哈希。
+3. 重新下载固定到这些提交的 JSON 文件：
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/QuantumClaw/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/QuantumClaw/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. 确保 `apps/macos/Sources/QuantumClaw/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` 仍与上游一致（如果上游许可证发生变更，请替换该文件）。
+5. 验证 macOS 应用能够正常构建（无警告）：
+
+```bash
+swift build --package-path apps/macos
+```

package/docs/zh-CN/reference/rpc.md

@@ -0,0 +1,48 @@
+---
+read_when:
+  - 添加或更改外部 CLI 集成
+  - 调试 RPC 适配器（signal-cli、imsg）
+summary: 外部 CLI（signal-cli、imsg）的 RPC 适配器和 Gateway 网关模式
+title: RPC 适配器
+x-i18n:
+  generated_at: "2026-02-03T07:53:44Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c04edc952390304a22a3a4763aca00a0311b38d390477ec0be5fe485ec257fa7
+  source_path: reference/rpc.md
+  workflow: 15
+---
+
+# RPC 适配器
+
+QuantumClaw 通过 JSON-RPC 集成外部 CLI。目前使用两种模式。
+
+## 模式 A：HTTP 守护进程（signal-cli）
+
+- `signal-cli` 作为守护进程运行，通过 HTTP 使用 JSON-RPC。
+- 事件流是 SSE（`/api/v1/events`）。
+- 健康探测：`/api/v1/check`。
+- 当 `channels.signal.autoStart=true` 时，QuantumClaw 负责生命周期管理。
+
+设置和端点参见 [Signal](/channels/signal)。
+
+## 模式 B：stdio 子进程（imsg）
+
+- QuantumClaw 将 `imsg rpc` 作为子进程生成。
+- JSON-RPC 是通过 stdin/stdout 的行分隔格式（每行一个 JSON 对象）。
+- 无需 TCP 端口，无需守护进程。
+
+使用的核心方法：
+
+- `watch.subscribe` → 通知（`method: "message"`）
+- `watch.unsubscribe`
+- `send`
+- `chats.list`（探测/诊断）
+
+设置和寻址（首选 `chat_id`）参见 [iMessage](/channels/imessage)。
+
+## 适配器指南
+
+- Gateway 网关负责进程（启动/停止与提供商生命周期绑定）。
+- 保持 RPC 客户端弹性：超时、退出时重启。
+- 优先使用稳定 ID（例如 `chat_id`）而非显示字符串。