<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/farzaa/clicky) · [上游 README](https://github.com/farzaa/clicky/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

更新：2026 年 4 月 27 日。

你好！我是 Farza，做 Clicky 的那个人。

现有代码库仍然是开源的。你可以随便折腾、改造成自己的、用它创业，想做什么都行，我不介意。但我正在开发的新内容会保持私有。要获取最新版 Clicky，可以前往[这里](https://www.heyclicky.com/).

关于这件事，我也发过推文，见[这里](https://x.com/FarzaTV/status/2043402737828962489).

尽情折腾这个仓库吧！！它是 MIT 许可证。

# 你好，这是 Clicky。
它是一个 AI 老师，会作为伙伴住在你光标旁边。它能看到你的屏幕、和你对话，甚至能指向东西。有点像身边有一位真正的老师在教你。

可以免费在[这里](https://www.clicky.so/)下载。

这是当时火爆演示的[原始推文](https://x.com/FarzaTV/status/2041314633978659092)，可以了解更多背景。

![Clicky — 住在你 Mac 上的 AI 伙伴](clicky-demo.gif)

这是 Clicky 的开源版本，适合想动手改、自己加功能，或只是想了解其内部工作原理的人。

## 使用 Claude Code 快速开始

最快跑起来的方式是用 [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

等 Claude 跑起来后，粘贴这个：

```
Hi Claude.

Clone https://github.com/farzaa/clicky.git into my current directory.

Then read the CLAUDE.md. I want to get Clicky running locally on my Mac.

Help me set up everything — the Cloudflare Worker with my own API keys, the proxy URLs, and getting it building in Xcode. Walk me through it.
```

就这样。它会克隆仓库、阅读文档，并带你完成整个配置流程。跑起来之后你可以继续和它对话——开发功能、修 bug，随便来。尽情折腾吧。

## 手动配置

如果你想自己动手，方法如下。

### 前置要求

- macOS 14.2+（用于 ScreenCaptureKit）
- Xcode 15+
- Node.js 18+（用于 Cloudflare Worker）
- 一个 [Cloudflare](https://cloudflare.com) 账号（免费套餐即可）
- 以下服务的 API 密钥：[Anthropic](https://console.anthropic.com),、[AssemblyAI](https://www.assemblyai.com),、[ElevenLabs](https://elevenlabs.io)

### 1. 配置 Cloudflare Worker

Worker 是一个小型代理，用来存放你的 API 密钥。应用与 Worker 通信，Worker 再与各 API 通信。这样你的密钥就不会被打包进应用二进制文件里。

```bash
cd worker
npm install
```

现在添加你的密钥。Wrangler 会提示你逐个粘贴：

```bash
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put ASSEMBLYAI_API_KEY
npx wrangler secret put ELEVENLABS_API_KEY
```

对于 ElevenLabs 的 voice ID，打开 `wrangler.toml` 并在那里设置（这不是敏感信息）：

```toml
[vars]
ELEVENLABS_VOICE_ID = "your-voice-id-here"
```

部署它：

```bash
npx wrangler deploy
```

它会给你一个类似 `https://your-worker-name.your-subdomain.workers.dev` 的 URL。复制下来。

### 2. 本地运行 Worker（用于开发）

如果你想在不部署的情况下测试 Worker 的改动：

```bash
cd worker
npx wrangler dev
```

这会启动一个本地服务器（通常是 `http://localhost:8787`），行为与已部署的 Worker 完全一致。你需要在 `worker/` 目录下创建一个 `.dev.vars` 文件，写入你的密钥：

```
ANTHROPIC_API_KEY=sk-ant-...
ASSEMBLYAI_API_KEY=...
ELEVENLABS_API_KEY=...
ELEVENLABS_VOICE_ID=...
```

然后在开发时，把 Swift 代码中的代理 URL 改为指向 `http://localhost:8787`，而不是已部署的 Worker URL。用 grep 搜索 `clicky-proxy` 可以找到所有相关位置。

### 3. 更新应用中的代理 URL

应用在几处硬编码了 Worker URL。搜索 `your-worker-name.your-subdomain.workers.dev` 并替换为你的 Worker URL：

```bash
grep -r "clicky-proxy" leanring-buddy/
```

你会在以下位置找到它：
- `CompanionManager.swift` — Claude 聊天 + ElevenLabs TTS
- `AssemblyAIStreamingTranscriptionProvider.swift` — AssemblyAI token 端点

### 4. 在 Xcode 中打开并运行

```bash
open leanring-buddy.xcodeproj
```

在 Xcode 中：
1. 选择 `leanring-buddy` scheme（对，这个拼写错误是故意的，说来话长）
2. 在 Signing & Capabilities 中设置你的签名团队
3. 按 **Cmd + R** 构建并运行

应用会出现在菜单栏（而不是程序坞）中。点击图标打开面板，授予它请求的权限，就可以开始用了。

### 应用所需权限

- **麦克风** — 用于按住说话（push-to-talk）的语音采集
- **辅助功能** — 用于全局键盘快捷键（Control + Option）
- **屏幕录制** — 用于在使用快捷键时截图
- **屏幕内容** — 用于 ScreenCaptureKit 访问

## 架构

如果你想看完整技术拆解，请阅读 `CLAUDE.md`。下面是简要版本：

**菜单栏应用**（无程序坞图标），包含两个 `NSPanel` 窗口——一个用于控制面板下拉菜单，一个用于全屏透明光标叠加层。按住说话时，音频通过 websocket 流式传输到 AssemblyAI，转写文本和截图通过流式 SSE 发送给 Claude，再通过 ElevenLabs TTS 播放回复。Claude 可以在回复中嵌入 `[POINT:x,y:label:screenN]` 标签，让光标飞到多块显示器上的特定 UI 元素。三个 API 都通过 Cloudflare Worker 代理。

## 项目结构

```
leanring-buddy/          # Swift source (yes, the typo stays)
  CompanionManager.swift    # Central state machine
  CompanionPanelView.swift  # Menu bar panel UI
  ClaudeAPI.swift           # Claude streaming client
  ElevenLabsTTSClient.swift # Text-to-speech playback
  OverlayWindow.swift       # Blue cursor overlay
  AssemblyAI*.swift         # Real-time transcription
  BuddyDictation*.swift     # Push-to-talk pipeline
worker/                  # Cloudflare Worker proxy
  src/index.ts              # Three routes: /chat, /tts, /transcribe-token
CLAUDE.md                # Full architecture doc (agents read this)
```

## 贡献

欢迎提交 PR。如果你在用 Claude Code，它已经了解这个代码库——告诉它你想做什么，并让它参考 `CLAUDE.md`。

有反馈？在 X 上私信我 [@farzatv](https://x.com/farzatv).