@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/platforms/mac/bundled-gateway.md

@@ -0,0 +1,75 @@
+---
+read_when:
+  - 打包 QuantumClaw.app
+  - 调试 macOS Gateway 网关 launchd 服务
+  - 为 macOS 安装 Gateway 网关 CLI
+summary: macOS 上的 Gateway 网关运行时（外部 launchd 服务）
+title: macOS 上的 Gateway 网关
+x-i18n:
+  generated_at: "2026-02-03T07:52:30Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4a3e963d13060b123538005439213e786e76127b370a6c834d85a369e4626fe5
+  source_path: platforms/mac/bundled-gateway.md
+  workflow: 15
+---
+
+# macOS 上的 Gateway 网关（外部 launchd）
+
+QuantumClaw.app 不再捆绑 Node/Bun 或 Gateway 网关运行时。macOS 应用期望有一个**外部**的 `quantumclaw` CLI 安装，不会将 Gateway 网关作为子进程启动，而是管理一个每用户的 launchd 服务来保持 Gateway 网关运行（或者如果已有本地 Gateway 网关正在运行，则连接到现有的）。
+
+## 安装 CLI（本地模式必需）
+
+你需要在 Mac 上安装 Node 22+，然后全局安装 `quantumclaw`：
+
+```bash
+npm install -g quantumclaw@<version>
+```
+
+macOS 应用的**安装 CLI**按钮通过 npm/pnpm 运行相同的流程（不推荐使用 bun 作为 Gateway 网关运行时）。
+
+## Launchd（Gateway 网关作为 LaunchAgent）
+
+标签：
+
+- `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.quantumclaw.*` 可能仍然存在）
+
+Plist 位置（每用户）：
+
+- `~/Library/LaunchAgents/bot.molt.gateway.plist`
+  （或 `~/Library/LaunchAgents/bot.molt.<profile>.plist`）
+
+管理者：
+
+- macOS 应用在本地模式下拥有 LaunchAgent 的安装/更新权限。
+- CLI 也可以安装它：`quantumclaw gateway install`。
+
+行为：
+
+- "QuantumClaw Active"启用/禁用 LaunchAgent。
+- 应用退出**不会**停止 Gateway 网关（launchd 保持其存活）。
+- 如果 Gateway 网关已经在配置的端口上运行，应用会连接到它而不是启动新的。
+
+日志：
+
+- launchd stdout/err：`/tmp/quantumclaw/quantumclaw-gateway.log`
+
+## 版本兼容性
+
+macOS 应用会检查 Gateway 网关版本与其自身版本是否匹配。如果不兼容，请更新全局 CLI 以匹配应用版本。
+
+## 冒烟测试
+
+```bash
+quantumclaw --version
+
+QUANTUMCLAW_SKIP_CHANNELS=1 \
+QUANTUMCLAW_SKIP_CANVAS_HOST=1 \
+quantumclaw gateway --port 18999 --bind loopback
+```
+
+然后：
+
+```bash
+quantumclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```

package/docs/zh-CN/platforms/mac/canvas.md

@@ -0,0 +1,128 @@
+---
+read_when:
+  - 实现 macOS Canvas 面板
+  - 为可视化工作区添加智能体控制
+  - 调试 WKWebView canvas 加载
+summary: 通过 WKWebView + 自定义 URL 方案嵌入的智能体控制 Canvas 面板
+title: Canvas
+x-i18n:
+  generated_at: "2026-02-03T07:52:39Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e39caa21542e839d9f59ad0bf7ecefb379225ed7e8f00cd59131d188f193bec6
+  source_path: platforms/mac/canvas.md
+  workflow: 15
+---
+
+# Canvas（macOS 应用）
+
+macOS 应用使用 `WKWebView` 嵌入一个智能体控制的 **Canvas 面板**。它是一个用于 HTML/CSS/JS、A2UI 和小型交互式界面的轻量级可视化工作区。
+
+## Canvas 存储位置
+
+Canvas 状态存储在 Application Support 下：
+
+- `~/Library/Application Support/QuantumClaw/canvas/<session>/...`
+
+Canvas 面板通过**自定义 URL 方案**提供这些文件：
+
+- `quantumclaw-canvas://<session>/<path>`
+
+示例：
+
+- `quantumclaw-canvas://main/` → `<canvasRoot>/main/index.html`
+- `quantumclaw-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+- `quantumclaw-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
+
+如果根目录下没有 `index.html`，应用会显示一个**内置脚手架页面**。
+
+## 面板行为
+
+- 无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。
+- 记住每个会话的大小/位置。
+- 当本地 canvas 文件更改时自动重新加载。
+- 一次只显示一个 Canvas 面板（根据需要切换会话）。
+
+可以从设置 → **允许 Canvas** 禁用 Canvas。禁用时，canvas 节点命令返回 `CANVAS_DISABLED`。
+
+## 智能体 API 接口
+
+Canvas 通过 **Gateway 网关 WebSocket** 暴露，因此智能体可以：
+
+- 显示/隐藏面板
+- 导航到路径或 URL
+- 执行 JavaScript
+- 捕获快照图像
+
+CLI 示例：
+
+```bash
+quantumclaw nodes canvas present --node <id>
+quantumclaw nodes canvas navigate --node <id> --url "/"
+quantumclaw nodes canvas eval --node <id> --js "document.title"
+quantumclaw nodes canvas snapshot --node <id>
+```
+
+注意事项：
+
+- `canvas.navigate` 接受**本地 canvas 路径**、`http(s)` URL 和 `file://` URL。
+- 如果传递 `"/"`，Canvas 会显示本地脚手架或 `index.html`。
+
+## Canvas 中的 A2UI
+
+A2UI 由 Gateway 网关 canvas 主机托管并在 Canvas 面板内渲染。
+当 Gateway 网关广播 Canvas 主机时，macOS 应用在首次打开时自动导航到 A2UI 主机页面。
+
+默认 A2UI 主机 URL：
+
+```
+http://<gateway-host>:18793/__quantumclaw__/a2ui/
+```
+
+### A2UI 命令（v0.8）
+
+Canvas 目前接受 **A2UI v0.8** 服务器→客户端消息：
+
+- `beginRendering`
+- `surfaceUpdate`
+- `dataModelUpdate`
+- `deleteSurface`
+
+`createSurface`（v0.9）不受支持。
+
+CLI 示例：
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOFA2
+
+quantumclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+快速测试：
+
+```bash
+quantumclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
+```
+
+## 从 Canvas 触发智能体运行
+
+Canvas 可以通过深层链接触发新的智能体运行：
+
+- `quantumclaw://agent?...`
+
+示例（在 JS 中）：
+
+```js
+window.location.href = "quantumclaw://agent?message=Review%20this%20design";
+```
+
+除非提供有效密钥，否则应用会提示确认。
+
+## 安全注意事项
+
+- Canvas 方案阻止目录遍历；文件必须位于会话根目录下。
+- 本地 Canvas 内容使用自定义方案（不需要 loopback 服务器）。
+- 仅在显式导航时允许外部 `http(s)` URL。

package/docs/zh-CN/platforms/mac/child-process.md

@@ -0,0 +1,73 @@
+---
+read_when:
+  - 将 mac 应用与 Gateway 网关生命周期集成时
+summary: macOS 上的 Gateway 网关生命周期（launchd）
+title: Gateway 网关生命周期
+x-i18n:
+  generated_at: "2026-02-03T07:52:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9b910f574b723bc194ac663a5168e48d95f55cb468ce34c595d8ca60d3463c6a
+  source_path: platforms/mac/child-process.md
+  workflow: 15
+---
+
+# macOS 上的 Gateway 网关生命周期
+
+macOS 应用**默认通过 launchd 管理 Gateway 网关**，不会将
+Gateway 网关作为子进程生成。它首先尝试连接到配置端口上已运行的
+Gateway 网关；如果无法访问，它会通过外部 `quantumclaw` CLI（无嵌入式运行时）启用 launchd
+服务。这为你提供了可靠的登录时自动启动和崩溃后重启。
+
+子进程模式（由应用直接生成 Gateway 网关）**目前未使用**。
+如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway 网关。
+
+## 默认行为（launchd）
+
+- 应用安装标记为 `bot.molt.gateway` 的按用户 LaunchAgent
+  （使用 `--profile`/`QUANTUMCLAW_PROFILE` 时为 `bot.molt.<profile>`；支持旧版 `com.quantumclaw.*`）。
+- 当启用本地模式时，应用确保 LaunchAgent 已加载，并
+  在需要时启动 Gateway 网关。
+- 日志写入 launchd Gateway 网关日志路径（在调试设置中可见）。
+
+常用命令：
+
+```bash
+launchctl kickstart -k gui/$UID/bot.molt.gateway
+launchctl bootout gui/$UID/bot.molt.gateway
+```
+
+运行命名配置文件时，将标签替换为 `bot.molt.<profile>`。
+
+## 未签名的开发构建
+
+`scripts/restart-mac.sh --no-sign` 用于在没有签名密钥时的快速本地构建。为了防止 launchd 指向未签名的中继二进制文件，它：
+
+- 写入 `~/.quantumclaw/disable-launchagent`。
+
+已签名运行的 `scripts/restart-mac.sh` 会在标记存在时清除此覆盖。要手动重置：
+
+```bash
+rm ~/.quantumclaw/disable-launchagent
+```
+
+## 仅连接模式
+
+要强制 macOS 应用**永不安装或管理 launchd**，请使用
+`--attach-only`（或 `--no-launchd`）启动它。这会设置 `~/.quantumclaw/disable-launchagent`，
+因此应用只会连接到已运行的 Gateway 网关。你可以在调试设置中切换相同的
+行为。
+
+## 远程模式
+
+远程模式永远不会启动本地 Gateway 网关。应用使用到
+远程主机的 SSH 隧道并通过该隧道连接。
+
+## 为什么我们更喜欢 launchd
+
+- 登录时自动启动。
+- 内置的重启/KeepAlive 语义。
+- 可预测的日志和监管。
+
+如果将来再次需要真正的子进程模式，它应该被记录为
+单独的、明确的仅开发模式。

package/docs/zh-CN/platforms/mac/dev-setup.md

@@ -0,0 +1,109 @@
+---
+read_when:
+  - 设置 macOS 开发环境
+summary: 为在 QuantumClaw macOS 应用上工作的开发者提供的设置指南
+title: macOS 开发设置
+x-i18n:
+  generated_at: "2026-02-03T07:52:36Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4ea67701bd58b7512f945fce58d79e1b3d990fbf45183323a1e3ab9688827623
+  source_path: platforms/mac/dev-setup.md
+  workflow: 15
+---
+
+# macOS 开发者设置
+
+本指南涵盖从源代码构建和运行 QuantumClaw macOS 应用程序的必要步骤。
+
+## 前置条件
+
+在构建应用之前，确保你已安装以下内容：
+
+1.  **Xcode 26.2+**：Swift 开发所需。
+2.  **Node.js 22+ & pnpm**：Gateway 网关、CLI 和打包脚本所需。
+
+## 1. 安装依赖
+
+安装项目范围的依赖：
+
+```bash
+pnpm install
+```
+
+## 2. 构建和打包应用
+
+要构建 macOS 应用并将其打包到 `dist/QuantumClaw.app`，运行：
+
+```bash
+./scripts/package-mac-app.sh
+```
+
+如果你没有 Apple Developer ID 证书，脚本将自动使用 **ad-hoc 签名**（`-`）。
+
+有关开发运行模式、签名标志和 Team ID 故障排除，请参阅 macOS 应用 README：
+https://github.com/quantumclaw/quantumclaw/blob/main/apps/macos/README.md
+
+> **注意**：Ad-hoc 签名的应用可能会触发安全提示。如果应用立即崩溃并显示"Abort trap 6"，请参阅[故障排除](#troubleshooting)部分。
+
+## 3. 安装 CLI
+
+macOS 应用期望全局安装 `quantumclaw` CLI 来管理后台任务。
+
+**安装方法（推荐）：**
+
+1.  打开 QuantumClaw 应用。
+2.  转到 **General** 设置标签页。
+3.  点击 **"Install CLI"**。
+
+或者，手动安装：
+
+```bash
+npm install -g quantumclaw@<version>
+```
+
+## 故障排除
+
+### 构建失败：工具链或 SDK 不匹配
+
+macOS 应用构建期望最新的 macOS SDK 和 Swift 6.2 工具链。
+
+**系统依赖（必需）：**
+
+- **软件更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 所需）
+- **Xcode 26.2**（Swift 6.2 工具链）
+
+**检查：**
+
+```bash
+xcodebuild -version
+xcrun swift --version
+```
+
+如果版本不匹配，更新 macOS/Xcode 并重新运行构建。
+
+### 授予权限时应用崩溃
+
+如果在尝试允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于 TCC 缓存损坏或签名不匹配。
+
+**修复：**
+
+1. 重置 TCC 权限：
+   ```bash
+   tccutil reset All bot.molt.mac.debug
+   ```
+2. 如果这不起作用，在 [`scripts/package-mac-app.sh`](https://github.com/quantumclaw/quantumclaw/blob/main/scripts/package-mac-app.sh) 中临时更改 `BUNDLE_ID` 以强制 macOS 从"全新状态"开始。
+
+### Gateway 网关无限期"Starting..."
+
+如果 Gateway 网关状态一直停留在"Starting..."，检查是否有僵尸进程占用端口：
+
+```bash
+quantumclaw gateway status
+quantumclaw gateway stop
+
+# 如果你没有使用 LaunchAgent（开发模式/手动运行），找到监听器：
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+```
+
+如果手动运行占用了端口，停止该进程（Ctrl+C）。作为最后手段，杀死你找到的 PID。

package/docs/zh-CN/platforms/mac/health.md

@@ -0,0 +1,41 @@
+---
+read_when:
+  - 调试 Mac 应用健康指示器
+summary: macOS 应用如何报告 Gateway 网关/Baileys 健康状态
+title: 健康检查
+x-i18n:
+  generated_at: "2026-02-03T07:52:40Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0560e96501ddf53a499f8960cfcf11c2622fcb9056bfd1bcc57876e955cab03d
+  source_path: platforms/mac/health.md
+  workflow: 15
+---
+
+# macOS 上的健康检查
+
+如何从菜单栏应用查看关联渠道是否健康。
+
+## 菜单栏
+
+- 状态圆点现在反映 Baileys 健康状态：
+  - 绿色：已关联 + socket 最近已打开。
+  - 橙色：正在连接/重试。
+  - 红色：已登出或探测失败。
+- 第二行显示"linked · auth 12m"或显示失败原因。
+- "Run Health Check"菜单项触发按需探测。
+
+## 设置
+
+- 通用选项卡新增健康卡片，显示：关联认证时间、会话存储路径/数量、上次检查时间、上次错误/状态码，以及运行健康检查/显示日志按钮。
+- 使用缓存快照，因此 UI 立即加载，离线时优雅降级。
+- **渠道选项卡**显示渠道状态 + WhatsApp/Telegram 的控制（登录二维码、登出、探测、上次断开/错误）。
+
+## 探测工作原理
+
+- 应用每约 60 秒和按需时通过 `ShellExecutor` 运行 `quantumclaw health --json`。探测加载凭证并报告状态，不发送消息。
+- 分别缓存上次成功的快照和上次错误以避免闪烁；显示每个的时间戳。
+
+## 有疑问时
+
+- 你仍然可以使用 [Gateway 网关健康](/gateway/health) 中的 CLI 流程（`quantumclaw status`、`quantumclaw status --deep`、`quantumclaw health --json`），并在 `/tmp/quantumclaw/quantumclaw-*.log` 中跟踪 `web-heartbeat` / `web-reconnect`。

package/docs/zh-CN/platforms/mac/icon.md

@@ -0,0 +1,38 @@
+---
+read_when:
+  - 更改菜单栏图标行为
+summary: macOS 上 QuantumClaw 菜单栏图标的状态和动画
+title: 菜单栏图标
+x-i18n:
+  generated_at: "2026-02-01T21:32:49Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a67a6e6bbdc2b611ba365d3be3dd83f9e24025d02366bc35ffcce9f0b121872b
+  source_path: platforms/mac/icon.md
+  workflow: 15
+---
+
+# 菜单栏图标状态
+
+作者：steipete · 更新时间：2025-12-06 · 范围：macOS 应用（`apps/macos`）
+
+- **空闲：** 正常图标动画（眨眼、偶尔摆动）。
+- **暂停：** 状态项使用 `appearsDisabled`；无动画。
+- **语音触发（大耳朵）：** 语音唤醒检测器在听到唤醒词时调用 `AppState.triggerVoiceEars(ttl: nil)`，在捕获语音期间保持 `earBoostActive=true`。耳朵放大（1.9 倍），显示圆形耳孔以提高可读性，然后在 1 秒静音后通过 `stopVoiceEars()` 恢复。仅由应用内语音管道触发。
+- **工作中（智能体运行中）：** `AppState.isWorking=true` 驱动"尾巴/腿部快速摆动"微动画：工作进行中腿部摆动加快并略有偏移。目前在 WebChat 智能体运行时切换；在接入其他长时间任务时请添加相同的切换逻辑。
+
+接入点
+
+- 语音唤醒：运行时/测试器在触发时调用 `AppState.triggerVoiceEars(ttl: nil)`，在 1 秒静音后调用 `stopVoiceEars()` 以匹配捕获窗口。
+- 智能体活动：在工作区间前后设置 `AppStateStore.shared.setWorking(true/false)`（已在 WebChat 智能体调用中完成）。保持区间简短，并在 `defer` 块中重置以避免动画卡住。
+
+形状与尺寸
+
+- 基础图标在 `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)` 中绘制。
+- 耳朵缩放默认为 `1.0`；语音增强时设置 `earScale=1.9` 并切换 `earHoles=true`，不改变整体框架（18×18 pt 模板图像渲染到 36×36 px Retina 后备存储）。
+- 快速摆动使用最高约 1.0 的腿部摆幅并带有轻微的水平抖动；它与现有的空闲摆动叠加。
+
+行为说明
+
+- 耳朵/工作状态没有外部 CLI/代理切换；保持仅由应用自身信号控制，以避免意外的状态抖动。
+- 保持 TTL 较短（<10 秒），以便在任务挂起时图标能快速恢复到基准状态。

package/docs/zh-CN/platforms/mac/logging.md

@@ -0,0 +1,64 @@
+---
+read_when:
+  - 捕获 macOS 日志或调查隐私数据日志记录
+  - 调试语音唤醒/会话生命周期问题
+summary: QuantumClaw 日志：滚动诊断文件日志 + 统一日志隐私标志
+title: macOS 日志
+x-i18n:
+  generated_at: "2026-02-01T21:32:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c4c201d154915e0eb08bf5e32bac98fa93766f50f2a24bf56ab4424eb7781526
+  source_path: platforms/mac/logging.md
+  workflow: 15
+---
+
+# 日志（macOS）
+
+## 滚动诊断文件日志（Debug 面板）
+
+QuantumClaw 通过 swift-log（默认使用统一日志）路由 macOS 应用日志，并且在需要持久化捕获时可以将本地轮转文件日志写入磁盘。
+
+- 详细级别：**Debug 面板 → Logs → App logging → Verbosity**
+- 启用：**Debug 面板 → Logs → App logging → "Write rolling diagnostics log (JSONL)"**
+- 位置：`~/Library/Logs/QuantumClaw/diagnostics.jsonl`（自动轮转；旧文件以 `.1`、`.2`、… 为后缀）
+- 清除：**Debug 面板 → Logs → App logging → "Clear"**
+
+注意事项：
+
+- 此功能**默认关闭**。仅在主动调试时启用。
+- 该文件包含敏感信息；分享前请先审查内容。
+
+## macOS 上统一日志的隐私数据
+
+统一日志会屏蔽大部分负载内容，除非子系统选择启用 `privacy -off`。根据 Peter 关于 macOS [日志隐私机制](https://steipete.me/posts/2025/logging-privacy-shenanigans)（2025）的文章，这通过 `/Library/Preferences/Logging/Subsystems/` 中以子系统名称为键的 plist 文件来控制。只有新的日志条目才会应用该标志，因此请在复现问题之前启用它。
+
+## 为 QuantumClaw 启用（`bot.molt`）
+
+- 先将 plist 写入临时文件，然后以 root 身份原子性地安装：
+
+```bash
+cat <<'EOF' >/tmp/bot.molt.plist
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>DEFAULT-OPTIONS</key>
+    <dict>
+        <key>Enable-Private-Data</key>
+        <true/>
+    </dict>
+</dict>
+</plist>
+EOF
+sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist
+```
+
+- 无需重启；logd 会很快检测到该文件，但只有新的日志行才会包含隐私负载。
+- 使用现有的辅助脚本查看更丰富的输出，例如 `./scripts/clawlog.sh --category WebChat --last 5m`。
+
+## 调试后禁用
+
+- 移除覆盖配置：`sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist`。
+- 可选择运行 `sudo log config --reload` 强制 logd 立即丢弃覆盖配置。
+- 请注意此数据可能包含电话号码和消息正文；仅在确实需要额外详细信息时才保留该 plist 文件。

package/docs/zh-CN/platforms/mac/menu-bar.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 调整 Mac 菜单 UI 或状态逻辑
+summary: 菜单栏状态逻辑及向用户展示的内容
+title: 菜单栏
+x-i18n:
+  generated_at: "2026-02-01T21:33:00Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8eb73c0e671a76aae4ebb653c65147610bf3e6d3c9c0943d150e292e7761d16d
+  source_path: platforms/mac/menu-bar.md
+  workflow: 15
+---
+
+# 菜单栏状态逻辑
+
+## 显示内容
+
+- 我们在菜单栏图标和菜单的第一行状态行中展示当前智能体的工作状态。
+- 工作活跃时隐藏健康状态；当所有会话空闲时恢复显示。
+- 菜单中的"节点"区块仅列出**设备**（通过 `node.list` 配对的节点），不包括客户端/在线状态条目。
+- 当提供商用量快照可用时，"用量"部分会显示在上下文下方。
+
+## 状态模型
+
+- 会话：事件携带 `runId`（每次运行）以及载荷中的 `sessionKey`。"main" 会话的键为 `main`；如果不存在，则回退到最近更新的会话。
+- 优先级：main 始终优先。如果 main 处于活跃状态，立即显示其状态。如果 main 空闲，则显示最近活跃的非 main 会话。活动进行中不会来回切换；仅在当前会话进入空闲或 main 变为活跃时才切换。
+- 活动类型：
+  - `job`：高层命令执行（`state: started|streaming|done|error`）。
+  - `tool`：`phase: start|result`，包含 `toolName` 和 `meta/args`。
+
+## IconState 枚举（Swift）
+
+- `idle`
+- `workingMain(ActivityKind)`
+- `workingOther(ActivityKind)`
+- `overridden(ActivityKind)`（调试覆盖）
+
+### ActivityKind → 图标符号
+
+- `exec` → 💻
+- `read` → 📄
+- `write` → ✍️
+- `edit` → 📝
+- `attach` → 📎
+- 默认 → 🛠️
+
+### 视觉映射
+
+- `idle`：正常小动物图标。
+- `workingMain`：带图标符号的徽章，完整色调，腿部"工作"动画。
+- `workingOther`：带图标符号的徽章，柔和色调，无快跑动画。
+- `overridden`：无论活动状态如何，使用所选的图标符号/色调。
+
+## 状态行文本（菜单）
+
+- 工作活跃时：`<会话角色> · <活动标签>`
+  - 示例：`Main · exec: pnpm test`、`Other · read: apps/macos/Sources/QuantumClaw/AppState.swift`。
+- 空闲时：回退显示健康摘要。
+
+## 事件接收
+
+- 来源：控制渠道 `agent` 事件（`ControlChannel.handleAgentEvent`）。
+- 解析字段：
+  - `stream: "job"`，包含 `data.state` 用于启动/停止。
+  - `stream: "tool"`，包含 `data.phase`、`name`，可选 `meta`/`args`。
+- 标签：
+  - `exec`：`args.command` 的第一行。
+  - `read`/`write`：缩短的路径。
+  - `edit`：路径加上从 `meta`/diff 计数推断的变更类型。
+  - 回退：工具名称。
+
+## 调试覆盖
+
+- 设置 ▸ 调试 ▸ "图标覆盖" 选择器：
+  - `系统（自动）`（默认）
+  - `工作中：main`（按工具类型）
+  - `工作中：other`（按工具类型）
+  - `空闲`
+- 通过 `@AppStorage("iconOverride")` 存储；映射到 `IconState.overridden`。
+
+## 测试清单
+
+- 触发 main 会话任务：验证图标立即切换且状态行显示 main 标签。
+- main 空闲时触发非 main 会话任务：图标/状态显示非 main；保持稳定直到完成。
+- 在 other 活跃时启动 main：图标立即切换到 main。
+- 快速连续工具调用：确保徽章不会闪烁（工具结果的 TTL 宽限期）。
+- 所有会话空闲后健康行重新出现。

package/docs/zh-CN/platforms/mac/peekaboo.md

@@ -0,0 +1,62 @@
+---
+read_when:
+  - 在 QuantumClaw.app 中托管 PeekabooBridge
+  - 通过 Swift Package Manager 集成 Peekaboo
+  - 更改 PeekabooBridge 协议/路径
+summary: 用于 macOS UI 自动化的 PeekabooBridge 集成
+title: Peekaboo Bridge
+x-i18n:
+  generated_at: "2026-02-01T21:32:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b5b9ddb9a7c59e153a1d5d23c33616bb1542b5c7dadedc3af340aeee9ba03487
+  source_path: platforms/mac/peekaboo.md
+  workflow: 15
+---
+
+# Peekaboo Bridge（macOS UI 自动化）
+
+QuantumClaw 可以将 **PeekabooBridge** 作为本地的、权限感知的 UI 自动化代理进行托管。这使得 `peekaboo` CLI 能够驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。
+
+## 这是什么（以及不是什么）
+
+- **宿主**：QuantumClaw.app 可以作为 PeekabooBridge 宿主。
+- **客户端**：使用 `peekaboo` CLI（无需单独的 `quantumclaw ui ...` 界面）。
+- **界面**：视觉叠加层保留在 Peekaboo.app 中；QuantumClaw 只是一个轻量代理宿主。
+
+## 启用桥接
+
+在 macOS 应用中：
+
+- 设置 → **启用 Peekaboo Bridge**
+
+启用后，QuantumClaw 会启动一个本地 UNIX 套接字服务器。如果禁用，宿主会停止，`peekaboo` 将回退到其他可用宿主。
+
+## 客户端发现顺序
+
+Peekaboo 客户端通常按以下顺序尝试宿主：
+
+1. Peekaboo.app（完整用户体验）
+2. Claude.app（如已安装）
+3. QuantumClaw.app（轻量代理）
+
+使用 `peekaboo bridge status --verbose` 查看当前活跃的宿主及使用的套接字路径。你可以通过以下方式覆盖：
+
+```bash
+export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
+```
+
+## 安全与权限
+
+- 桥接会验证**调用方的代码签名**；强制执行 TeamID 白名单（Peekaboo 宿主 TeamID + QuantumClaw 应用 TeamID）。
+- 请求在约 10 秒后超时。
+- 如果缺少所需权限，桥接会返回清晰的错误信息，而不是启动系统设置。
+
+## 快照行为（自动化）
+
+快照存储在内存中，并在短暂窗口期后自动过期。如果需要更长的保留时间，请从客户端重新捕获。
+
+## 故障排除
+
+- 如果 `peekaboo` 报告"bridge client is not authorized"，请确保客户端已正确签名，或仅在**调试**模式下使用 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` 运行宿主。
+- 如果未找到宿主，请打开其中一个宿主应用（Peekaboo.app 或 QuantumClaw.app）并确认已授予权限。