wehub-resource-sync
169 lines
6.4 KiB
Markdown
169 lines
6.4 KiB
Markdown
<!-- 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 的开源版本，适合想动手改、自己加功能，或只是想了解其内部工作原理的人。
|
||
|
||
## 使用 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).
|