在 macOS 上为 Claude Code 安装和使用…

当你需要在 macOS 上用浮动覆盖层操作 Claude Code，并管理多标签会话、工具权限审批、本地语音输入和技能安装时使用。

适用场景

解决思路

1. 确认前置条件：macOS 13+、Node.js 18+（推荐 LTS 20 或 22）、Python 3.10+（3.12+ 需 setuptools）、已认证的 Claude Code CLI、用于语音输入的 Whisper CLI。
2. 安装 Xcode CLI tools 以编译原生模块：`xcode-select --install`。
3. 通过 Homebrew 安装 Node.js：`brew install node`，并用 `node --version` 确认版本 ≥18。
4. 在 Python 3.12+ 上安装/升级 setuptools：`python3 -m pip install --upgrade pip setuptools`。
5. 安装 Claude Code CLI：`npm install -g @anthropic-ai/claude-code`。
6. 认证 Claude Code：运行 `claude`。
7. 安装 Whisper 用于语音输入：`brew install whisper-cli`。
8. 推荐非开发者使用 App 安装器：`git clone https://github.com/lcoutodemos/clui-cc.git`，然后在 Finder 打开 clui-cc 文件夹并双击 `install-app.command`。
9. 首次启动时若 macOS 阻止未签名应用，前往“系统设置 → 隐私与安全性 → Open Anyway”。
10. 开发者工作流安装：`git clone https://github.com/lcoutodemos/clui-cc.git`，`cd clui-cc`，`npm install`，`npm run dev`；renderer 热重载，main-process 变更需重启。
11. 使用命令脚本：`./commands/setup.command` 做环境检查并安装依赖；`./commands/start.command` 从源码构建并启动；`./commands/stop.command` 停止所有 Clui CC 进程。
12. 使用构建与诊断命令：`npm run build` 做生产构建（不打包）；`npm run dist` 打包为 macOS `.app` 到 `release/`；`npm run doctor` 做环境诊断。
13. 使用快捷键：`⌥ + Space` 显示/隐藏 overlay；若被占用，用 `Cmd + Shift + K` 备用切换。
14. 按运行流程使用：每个标签页启动 `claude -p --output-format stream-json` 子进程；`RunManager` 解析 NDJSON；`EventNormalizer` 规范化事件；`ControlPlane` 管理标签生命周期 `connecting → idle → running → completed/failed/dead`；工具权限请求通过 HTTP hooks 到 `PermissionServer`（仅 localhost）；renderer 每 1.5 秒轮询后端健康并协调标签状态；会话用 `--resume <session-id>` 恢复。
15. 了解项目结构以便修改：`src/main/claude/` 放 ControlPlane、RunManager、EventNormalizer；`src/main/hooks/` 放 PermissionServer（PreToolUse HTTP hooks）；`src/main/marketplace/` 放插件目录获取与安装；`src/main/skills/` 放技能自动安装器；`src/main/index.ts` 放窗口创建、IPC handlers、tray；`src/renderer/components/` 放 TabStrip、ConversationView、InputBar 等；`src/renderer/stores/` 放 Zustand session store；`src/renderer/hooks/` 放事件监听与健康协调；`src/renderer/theme.ts` 放双调色板与 CSS custom properties；`src/preload/` 放安全 IPC 桥（`window.clui` API）；`src/shared/` 放规范类型与 IPC channel 定义。
16. 使用 `window.clui` IPC API：`window.clui.sendPrompt(tabId: string, text: string): Promise<void>` 发送提示到活动标签的 claude 进程；`window.clui.resolvePermission(requestId: string, approved: boolean): Promise<void>` 批准或拒绝待处理工具使用权限；`window.clui.createTab(): Promise<{ tabId: string }>` 创建新标签（启动新的 `claude -p` 进程）；`window.clui.resumeSession(tabId: string, sessionId: string): Promise<void>` 按 id 恢复过去会话；`window.clui.onTabEvent(tabId: string, callback: (event: NormalizedEvent) => void): () => void` 订阅标签规范化事件并返回取消订阅函数；`window.clui.getHistory(): Promise<SessionMeta[]>` 获取会话历史列表。
17. 创建标签并发送提示（renderer）：用 `window.clui.createTab()` 获取 `tabId`；用 `window.clui.onTabEvent(tabId, (event) => ...)` 订阅事件；调用 `window.clui.sendPrompt(tabId, text)` 发送文本。
18. 恢复过去会话：`await window.clui.getHistory()` 获取历史；若无历史则返回；`const { tabId } = await window.clui.createTab()`；取 `history[0]`（最近优先）；`await window.clui.resumeSession(tabId, lastSession.sessionId)`。
19. 实现权限审批 UI：工具调用执行前由 `PermissionServer` 通过 PreToolUse HTTP hooks 拦截；renderer 接收 `permission_request` 事件；在 `onTabEvent` 中判断 `event.type !== 'permission_request'` 则返回；取 `requestId, toolName, toolInput`；显示审批对话框；调用 `window.clui.resolvePermission(requestId, approved)`。
20. 按主进程 hook 协议处理权限请求：`PermissionServer` 注册 hook 到 `claude -p`；hook endpoint 接收 Claude Code 的 POST，例如 `{ "tool": "bash", "input": { "command": "rm -rf dist/" }, "session_id": "..." }`；它保持请求直到 renderer 解决。
21. 使用语音输入：Whisper 本地运行，由 `install-app.command` 自动安装或 `brew install whisper-cli`；无需 API key，转录完全在设备上；从 InputBar 组件通过 IPC 触发 `window.clui.startVoiceInput(): Promise<void>` 和 `window.clui.stopVoiceInput(): Promise<{ transcript: string }>`。
22. 使用技能市场：调用 `window.clui.marketplace.list()` 获取可用技能（缓存 5 分钟，从 `raw.githubusercontent.com` 获取），返回 `[{ id, name, description, repoUrl, version }, ...]`；调用 `window.clui.marketplace.install(skillId: string)` 安装技能（从 `api.github.com` 下载 tarball）；调用 `window.clui.marketplace.listInstalled()` 列出已安装技能。
23. 了解技能市场网络调用：`raw.githubusercontent.com/anthropics/*` 用于技能目录（5 分钟缓存，非必需，优雅降级）；`api.github.com/repos/anthropics/*/tarball/*` 用于技能 tarball 下载（非必需，失败时跳过）。
24. 配置主题：在 `src/renderer/theme.ts` 中使用双调色板与 CSS custom properties；通过 UI 或编程方式调用 `window.clui.setTheme('dark' | 'light' | 'system')` 切换；CSS 自定义属性应用到 `:root`，可在 renderer 样式表中覆盖，例如 `--clui-bg: rgba(20, 20, 20, 0.85); --clui-text: #f0f0f0; --clui-accent: #7c5cfc; --clui-pill-radius: 24px;`。
25. 添加自定义技能：技能从 `~/.clui/skills/` 自动加载；技能是一个目录，包含 `skill.js` 入口；示例 `module.exports = { name: 'my-skill', version: '1.0.0', description: 'Does something useful', async onPrompt(context) { const { prompt, tabId, clui } = context; if (!prompt.includes('my trigger')) return false; await clui.sendMessage(tabId, `Handled by my-skill: ${prompt}`); return true; } }`；当技能被匹配提示激活时调用；返回 `false` 表示透传，返回 `true` 表示已消费、不转发给 claude。
26. 排障自检：运行 `npm run doctor`。
27. 处理 App 首次启动被阻止：前往“系统设置 → 隐私与安全性 → Open Anyway”。
28. 处理 `node-pty` 编译失败：运行 `xcode-select --install`，`python3 -m pip install --upgrade pip setuptools`，然后 `npm install`。
29. 处理 `claude` 未找到：运行 `npm install -g @anthropic-ai/claude-code`，运行 `claude` 认证，运行 `which claude` 确认在 PATH。
30. 处理 Whisper 未找到：运行 `brew install whisper-cli`，运行 `which whisper-cli`。
31. 处理 `PermissionServer` 端口冲突：HTTP hook server 仅运行在 localhost；若其他进程占用端口，运行 `./commands/stop.command` 和 `./commands/start.command` 重启。
32. 处理 `setuptools` 缺失（Python 3.12+）：运行 `python3 -m pip install --upgrade pip setuptools`。
33. 处理 overlay 不显示：尝试备用快捷键 `Cmd + Shift + K`；检查 Clui CC 是否有辅助功能权限：“系统设置 → 隐私与安全性 → 辅助功能”。
34. 核对已测试版本：macOS 15.x Sequoia、Node.js 20.x LTS 或 22.x、Python 3.12 (+setuptools)、Electron 33.x、Claude Code CLI 2.1.71。
35. 查阅参考资料：Claude Code docs（`https://docs.anthropic.com/en/docs/claude-code`）、架构深入 `docs/ARCHITECTURE.md`、排障指南 `docs/TROUBLESHOOTING.md`、MIT License `LICENSE`。

适用边界 · 注意事项

• 仅支持 macOS 13+，非 macOS 环境不适用。
• 依赖已认证的 Claude Code CLI、Whisper CLI、Node.js、Python 等前置工具；未安装或未认证时不可用。
• 技能市场依赖 GitHub 网络访问，离线或 GitHub 不可达时相关功能会降级或不可用。