petdex-cc 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +311 -311
  3. package/README_CN.md +323 -323
  4. package/dist/bin/cli.js +13 -13
  5. package/dist/src/hooks/write-scripts.js +21 -21
  6. package/dist/src/renderer/index.html +264 -264
  7. package/package.json +48 -48
  8. package/src/hooks/bridge.ps1 +11 -11
  9. package/src/hooks/bridge.sh +9 -9
  10. package/dist/src/renderer/wander.d.ts +0 -8
  11. package/dist/src/renderer/wander.d.ts.map +0 -1
  12. package/dist/src/renderer/wander.js +0 -137
  13. package/dist/src/renderer/wander.js.map +0 -1
package/README_CN.md CHANGED
@@ -1,323 +1,323 @@
1
- <div align="center">
2
-
3
- # petdex-cc
4
-
5
- **Claude Code 桌面宠物伴侣**
6
-
7
- *住在屏幕上的动画宠物，实时响应你的每一次编码操作*
8
-
9
- [![npm version](https://img.shields.io/badge/version-0.1.1-8b5cf6?style=flat-square)](https://www.npmjs.com/package/petdex-cc)
10
- [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=flat-square)]()
11
- [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=flat-square)]()
12
- [![license](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)]()
13
- [![pets](https://img.shields.io/badge/pets-1%2C569%20%E6%AC%BE-ec4899?style=flat-square)](https://petdex.crafter.run/zh)
14
-
15
- [English](./README.md) · [中文文档](./README_CN.md)
16
-
17
- </div>
18
-
19
- ---
20
-
21
- ## petdex-cc 是什么？
22
-
23
- petdex-cc 为你的 Claude Code 工作流带来**动画桌面宠物**。从 [Petdex 宠物库](https://petdex.crafter.run/zh)（1,569+ 款社区宠物）挑选一只，一条命令安装，宠物立刻出现在桌面上 —— 陪你读代码、庆祝任务完成、在你遇到错误时加油打气，随你的编码而成长。
24
-
25
- > **和 `npx petdex install` 有什么区别？**
26
- > 原始的 `petdex` 命令提供基础宠物展示。`petdex-cc` 额外增加了**深度 Claude Code 集成** —— 通过 hooks 接入你的编码流程，包含等级成长系统、AI 生成语音、时段问候、互动特效。你的宠物不只是一个装饰，它*参与*你的编码过程。
27
-
28
- > **目前仅支持 Claude Code，后续将扩展到 Cursor、Windsurf、Copilot 等 AI 编码工具。**
29
-
30
- ### 功能一览
31
-
32
- - **实时反应** —— 你读文件、编辑代码、运行命令、完成任务、遇到错误时，宠物同步改变动画
33
- - **8 级成长体系** —— Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity，逐级解锁视觉特效
34
- - **AI 语音气泡** —— 基于 Claude 生成的上下文感知中文对话（无 API Key 时使用内置台词）
35
- - **时段问候** —— 早上好、午安、下午茶、下班、晚安、凌晨问候
36
- - **互动体验** —— 拖拽宠物、右键菜单、快速点击彩蛋
37
- - **系统托盘** —— 任务栏图标，可显示/隐藏、查看关于、退出
38
- - **状态持久化** —— 等级和事件数重启不丢失（HMAC 签名防篡改）
39
- - **1,569+ 款宠物** —— 浏览 [petdex.crafter.run/zh](https://petdex.crafter.run/zh)，安装任意社区宠物
40
-
41
- ---
42
-
43
- ## 快速开始
44
-
45
- ### 环境要求
46
-
47
- - [Node.js](https://nodejs.org/) >= 18
48
- - 已安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
49
-
50
- ### 安装
51
-
52
- ```bash
53
- # 1. 浏览宠物 → https://petdex.crafter.run/zh
54
- # 2. 看中哪只，记下它的 slug（比如 "boba"）
55
- # 3. 安装：
56
-
57
- npx petdex-cc install boba
58
- ```
59
-
60
- 宠物立刻出现在桌面上，开始响应你的 Claude Code 操作。
61
-
62
- ### 热门宠物
63
-
64
- | Slug | 名称 | 描述 |
65
- |---|---|---|
66
- | `boba` | Boba | 喝着珍珠奶茶的小水獭 |
67
- | `doraemon` | 哆啦A梦 | 来自未来的蓝色机器猫 |
68
- | `noir-webling` | Noir Webling | 戴礼帽的单色蜘蛛侦探 |
69
- | `ikun-hoops` | IKUN Hoops | 穿卫衣拿篮球的小鸡 |
70
- | `ddo-zvzo` | ddo-zvzo | 会戴墨镜的紫色吉祥物 |
71
- | `mochi` | Mochi | 橘白色可爱小猫 |
72
-
73
- > 浏览全部 1,569+ 款宠物 → [**petdex.crafter.run/zh**](https://petdex.crafter.run/zh)
74
-
75
- ---
76
-
77
- ## 你的宠物会做什么
78
-
79
- Claude Code 的每一次操作都会触发宠物反应：
80
-
81
- | Claude Code 事件 | 宠物动画 | 语音气泡 |
82
- |---|---|---|
83
- | 会话开始 | 挥手 | "Let's get to work!" |
84
- | 读取文件 | 审视 | "Reading 文件名..." |
85
- | 编辑文件 | 待机 | "Edited 文件名" |
86
- | 运行命令 | 奔跑 | "Running command..." |
87
- | 搜索文件 | 等待 | "Searching..." |
88
- | 工具失败 | 垂头 | "Oops, something went wrong" + AI 鼓励 |
89
- | 任务完成 | 跳跃 | "Task complete!" + AI 庆祝 |
90
- | Claude 停止 | 跳跃 | "Task complete!"（60% 概率触发 AI） |
91
- | Claude 报错 | 垂头 | 错误信息 + AI 安慰 |
92
- | 空闲 10+ 分钟 | 挥手 | 时段问候（中文） |
93
- | 等级提升 | 当前状态 | "Level up! Kernel!" + 特效激活 |
94
-
95
- ### 互动操作
96
-
97
- - **拖拽** —— 点击拖动宠物到屏幕任意位置
98
- - **右键** —— 上下文菜单：显示/隐藏、关于、退出
99
- - **系统托盘** —— 右下角任务栏图标
100
- - **彩蛋** —— 快速连续点击宠物，触发递进式反应（2 → 4 → 6 → 9 → 12 → 15 次）
101
-
102
- ---
103
-
104
- ## 等级系统
105
-
106
- 你的宠物随你的编码而成长。每次 Claude Code 操作算一次事件，累积升级：
107
-
108
- | 等级 | 名称 | 所需事件数 | 颜色 | 视觉效果 |
109
- |:---:|---|---:|---|---|
110
- | 1 | **Byte** | 0 | 银色 | 基础宠物 |
111
- | 2 | **Process** | 50 | 绿色 | 呼吸式发光 |
112
- | 3 | **Thread** | 200 | 蓝色 | 旋转光环 |
113
- | 4 | **Module** | 500 | 紫色 | 增强光环 |
114
- | 5 | **Kernel** | 1,000 | 琥珀 | 漂浮光点粒子 |
115
- | 6 | **Neural** | 2,000 | 粉色 | 粒子风暴 |
116
- | 7 | **Quantum** | 5,000 | 青色 | 能量场 |
117
- | 8 | **Singularity** | 10,000 | 金色 | 金色光环 + 全部特效 |
118
-
119
- ---
120
-
121
- ## AI 语音
122
-
123
- 当 Anthropic API Key 可用时（自动从 Claude Code 设置读取，或通过 `petdex-cc config` 配置），宠物会生成**上下文感知的中文语音**：
124
-
125
- | 场景 | 触发时机 | AI 生成示例 |
126
- |---|---|---|
127
- | `task_complete` | 任务完成 | "做得好！继续加油！" |
128
- | `error` | 工具失败 | "别担心，bugs难免的~" |
129
- | `idle` | 空闲超过 10 分钟 | "还在吗？" |
130
- | `level_up` | 等级跨越阈值 | "升级啦！太厉害了！" |
131
-
132
- - **2 分钟冷却** —— 连续 AI 调用间隔（升级时自动跳过冷却）
133
- - **5 秒超时** —— API 响应超过 5 秒自动回退到预设台词
134
- - **没有 API Key？** 内置预设台词完全够用 —— 7 条任务、5 条错误、5 条空闲、4 条升级
135
-
136
- ---
137
-
138
- ## 命令参考
139
-
140
- ```bash
141
- petdex-cc install <slug> # 下载宠物、配置 hooks、启动
142
- petdex-cc start # 启动桌面宠物
143
- petdex-cc stop # 优雅停止宠物
144
- petdex-cc list # 浏览 Petdex 宠物库
145
- petdex-cc switch <slug> # 运行时切换宠物（自动下载）
146
- petdex-cc status # 查看宠物名称、等级、事件数、运行状态
147
- petdex-cc uninstall # 移除 hooks、停止宠物、删除所有数据
148
- petdex-cc config [选项] # 配置设置
149
- ```
150
-
151
- ### 配置选项
152
-
153
- ```bash
154
- petdex-cc config --api-key <key> # Anthropic API Key（用于 AI 语音）
155
- petdex-cc config --api-base-url <url> # API 基础 URL
156
- petdex-cc config --cooldown <分钟> # AI 调用冷却时间（默认 2 分钟）
157
- ```
158
-
159
- > API 凭据会自动从 `~/.claude/settings.json` 读取，大多数用户无需手动配置。
160
-
161
- ---
162
-
163
- ## 架构设计
164
-
165
- ```
166
- ┌─────────────────────────────────────────────────┐
167
- │ Claude Code │
168
- │ （工具调用、任务完成、错误、空闲等事件） │
169
- └──────────────────────┬──────────────────────────┘
170
- │ hooks（写入 settings.json）
171
- ▼
172
- ┌──────────────────┐
173
- │ bridge.ps1/.sh │ 异步，10 秒超时
174
- └────────┬─────────┘
175
- │ HTTP POST /event
176
- ▼
177
- ┌─────────────────────────────────────────────────┐
178
- │ petdex-cc（Electron 主进程） │
179
- │ │
180
- │ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
181
- │ │ event-mapper │ │ storage │ │ ai-speech │ │
182
- │ │ 事件 → 动作 │ │ 等级、XP │ │ Claude Haiku│ │
183
- │ └──────┬───────┘ └─────┬────┘ └─────┬──────┘ │
184
- │ │ │ │ │
185
- │ └─────────┬───────┘ │ │
186
- │ ▼ │ │
187
- │ ┌─────────────────┐ │ │
188
- │ │ IPC → 渲染窗口 │◀─────────────┘ │
189
- │ └────────┬────────┘ │
190
- └──────────────────┼──────────────────────────────────┘
191
- ▼
192
- ┌──────────────────┐
193
- │ 宠物窗口（HTML） │ 透明、始终置顶
194
- │ │
195
- │ ┌─── sprite ───┐ │ 9 种动画状态
196
- │ │ 气泡 │ │ 3s / 8s 自动消失
197
- │ │ 等级徽章 │ │ 等级标签 + 颜色
198
- │ │ 特效 │ │ 光晕/光环/粒子/光环
199
- │ └──────────────┘ │
200
- └──────────────────┘
201
- ```
202
-
203
- ---
204
-
205
- ## 开发者安装
206
-
207
- ```bash
208
- git clone https://github.com/devnomad-byte/petdex-cc.git
209
- cd petdex-cc
210
- npm install
211
- npm run build
212
-
213
- # 开发模式启动
214
- npx electron .
215
-
216
- # 全局安装使用 CLI
217
- npm link
218
- petdex-cc install boba
219
- ```
220
-
221
- ### 项目结构
222
-
223
- ```
224
- petdex-cc/
225
- ├── bin/cli.ts CLI 入口（8 个命令）
226
- ├── src/
227
- │ ├── main/ Electron 主进程
228
- │ │ ├── index.ts 窗口创建、事件循环、IPC
229
- │ │ ├── server.ts HTTP 服务器（hooks → 宠物，端口 17321）
230
- │ │ ├── ai-speech.ts AI 语音（Anthropic Messages API）
231
- │ │ ├── storage.ts HMAC 签名状态持久化
232
- │ │ ├── tray.ts 系统托盘（像素猫脸图标）
233
- │ │ └── event-mapper.ts 8 种 hook 事件 → 宠物动作
234
- │ ├── renderer/ Electron 渲染进程（宠物 UI）
235
- │ │ ├── index.html 透明窗口 + CSS 特效
236
- │ │ ├── renderer.ts IPC 协调 + 等级特效
237
- │ │ ├── pet-sprite.ts 9 状态精灵图引擎
238
- │ │ ├── bubble.ts 语音气泡系统
239
- │ │ ├── click-through.ts 透明点击穿透
240
- │ │ ├── drag.ts 拖拽 + 点击彩蛋
241
- │ │ └── context-menu.ts 右键菜单
242
- │ ├── cli/ CLI 命令实现
243
- │ ├── hooks/ Claude Code hooks 注册
244
- │ │ ├── register.ts 写入 ~/.claude/settings.json
245
- │ │ ├── write-scripts.ts 跨平台 bridge 脚本
246
- │ │ ├── bridge.ps1 Windows PowerShell bridge
247
- │ │ └── bridge.sh Unix bash bridge
248
- │ ├── petdex-api/ Petdex 注册中心客户端
249
- │ │ ├── client.ts 清单获取 + slug 查询
250
- │ │ └── download.ts 流式下载 + 进度回调
251
- │ └── shared/ 共享类型和常量
252
- ```
253
-
254
- ---
255
-
256
- ## 配置参考
257
-
258
- ### 自动检测
259
-
260
- petdex-cc 自动从 `~/.claude/settings.json` 读取以下配置：
261
-
262
- | 配置项 | 用途 |
263
- |---|---|
264
- | `ANTHROPIC_AUTH_TOKEN` | AI 语音的 API Key |
265
- | `ANTHROPIC_BASE_URL` | AI 语音的 API 端点 |
266
-
267
- ### 手动配置
268
-
269
- 存储在 `~/.petdex-cc/config.json`：
270
-
271
- ```bash
272
- petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
273
- ```
274
-
275
- ### 数据目录
276
-
277
- | 路径 | 内容 |
278
- |---|---|
279
- | `~/.petdex-cc/pets/<slug>/` | 下载的精灵图 + pet.json |
280
- | `~/.petdex-cc/data/state.json` | 等级、事件数、宠物 slug（HMAC 签名） |
281
- | `~/.petdex-cc/data/state.sig` | HMAC-SHA256 签名 |
282
- | `~/.petdex-cc/hooks/` | Bridge 脚本 |
283
- | `~/.petdex-cc/config.json` | 用户配置（API Key、冷却时间） |
284
-
285
- ---
286
-
287
- ## Hooks 参考
288
-
289
- petdex-cc 在 `~/.claude/settings.json` 中注册以下 hooks：
290
-
291
- | Hook | 匹配器 | 触发时机 |
292
- |---|---|---|
293
- | `PostToolUse` | `Read\|Edit\|Write\|Bash\|Glob\|Grep` | 工具调用之后 |
294
- | `PostToolUseFailure` | — | 工具调用失败时 |
295
- | `Stop` | — | Claude 完成响应时 |
296
- | `StopFailure` | — | Claude 停止并报错时 |
297
- | `Notification` | `idle_prompt` | 空闲通知 |
298
- | `SessionStart` | `startup\|resume` | Claude Code 启动或恢复时 |
299
- | `SessionEnd` | — | Claude Code 会话结束时 |
300
- | `TaskCompleted` | — | 任务标记完成时 |
301
-
302
- ---
303
-
304
- ## 后续计划
305
-
306
- - [ ] 支持 Cursor
307
- - [ ] 支持 Windsurf
308
- - [ ] 支持 GitHub Copilot
309
- - [ ] 更多宠物互动动作
310
- - [ ] 宠物换装系统
311
-
312
- ---
313
-
314
- ## 许可证
315
-
316
- [MIT](./LICENSE)
317
-
318
- ---
319
-
320
- <div align="center">
321
- <sub>为 <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> 社区用心打造</sub><br />
322
- <sub>宠物来自 <a href="https://petdex.crafter.run/zh">Petdex</a></sub>
323
- </div>
1
+ <div align="center">
2
+
3
+ # petdex-cc
4
+
5
+ **Claude Code 桌面宠物伴侣**
6
+
7
+ *住在屏幕上的动画宠物，实时响应你的每一次编码操作*
8
+
9
+ [![npm version](https://img.shields.io/badge/version-0.1.1-8b5cf6?style=flat-square)](https://www.npmjs.com/package/petdex-cc)
10
+ [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0ea5e9?style=flat-square)]()
11
+ [![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?style=flat-square)]()
12
+ [![license](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)]()
13
+ [![pets](https://img.shields.io/badge/pets-1%2C569%20%E6%AC%BE-ec4899?style=flat-square)](https://petdex.crafter.run/zh)
14
+
15
+ [English](./README.md) · [中文文档](./README_CN.md)
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ ## petdex-cc 是什么？
22
+
23
+ petdex-cc 为你的 Claude Code 工作流带来**动画桌面宠物**。从 [Petdex 宠物库](https://petdex.crafter.run/zh)（1,569+ 款社区宠物）挑选一只，一条命令安装，宠物立刻出现在桌面上 —— 陪你读代码、庆祝任务完成、在你遇到错误时加油打气，随你的编码而成长。
24
+
25
+ > **和 `npx petdex install` 有什么区别？**
26
+ > 原始的 `petdex` 命令提供基础宠物展示。`petdex-cc` 额外增加了**深度 Claude Code 集成** —— 通过 hooks 接入你的编码流程，包含等级成长系统、AI 生成语音、时段问候、互动特效。你的宠物不只是一个装饰，它*参与*你的编码过程。
27
+
28
+ > **目前仅支持 Claude Code，后续将扩展到 Cursor、Windsurf、Copilot 等 AI 编码工具。**
29
+
30
+ ### 功能一览
31
+
32
+ - **实时反应** —— 你读文件、编辑代码、运行命令、完成任务、遇到错误时，宠物同步改变动画
33
+ - **8 级成长体系** —— Byte → Process → Thread → Module → Kernel → Neural → Quantum → Singularity，逐级解锁视觉特效
34
+ - **AI 语音气泡** —— 基于 Claude 生成的上下文感知中文对话（无 API Key 时使用内置台词）
35
+ - **时段问候** —— 早上好、午安、下午茶、下班、晚安、凌晨问候
36
+ - **互动体验** —— 拖拽宠物、右键菜单、快速点击彩蛋
37
+ - **系统托盘** —— 任务栏图标，可显示/隐藏、查看关于、退出
38
+ - **状态持久化** —— 等级和事件数重启不丢失（HMAC 签名防篡改）
39
+ - **1,569+ 款宠物** —— 浏览 [petdex.crafter.run/zh](https://petdex.crafter.run/zh)，安装任意社区宠物
40
+
41
+ ---
42
+
43
+ ## 快速开始
44
+
45
+ ### 环境要求
46
+
47
+ - [Node.js](https://nodejs.org/) >= 18
48
+ - 已安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
49
+
50
+ ### 安装
51
+
52
+ ```bash
53
+ # 1. 浏览宠物 → https://petdex.crafter.run/zh
54
+ # 2. 看中哪只，记下它的 slug（比如 "boba"）
55
+ # 3. 安装：
56
+
57
+ npx petdex-cc install boba
58
+ ```
59
+
60
+ 宠物立刻出现在桌面上，开始响应你的 Claude Code 操作。
61
+
62
+ ### 热门宠物
63
+
64
+ | Slug | 名称 | 描述 |
65
+ |---|---|---|
66
+ | `boba` | Boba | 喝着珍珠奶茶的小水獭 |
67
+ | `doraemon` | 哆啦A梦 | 来自未来的蓝色机器猫 |
68
+ | `noir-webling` | Noir Webling | 戴礼帽的单色蜘蛛侦探 |
69
+ | `ikun-hoops` | IKUN Hoops | 穿卫衣拿篮球的小鸡 |
70
+ | `ddo-zvzo` | ddo-zvzo | 会戴墨镜的紫色吉祥物 |
71
+ | `mochi` | Mochi | 橘白色可爱小猫 |
72
+
73
+ > 浏览全部 1,569+ 款宠物 → [**petdex.crafter.run/zh**](https://petdex.crafter.run/zh)
74
+
75
+ ---
76
+
77
+ ## 你的宠物会做什么
78
+
79
+ Claude Code 的每一次操作都会触发宠物反应：
80
+
81
+ | Claude Code 事件 | 宠物动画 | 语音气泡 |
82
+ |---|---|---|
83
+ | 会话开始 | 挥手 | "Let's get to work!" |
84
+ | 读取文件 | 审视 | "Reading 文件名..." |
85
+ | 编辑文件 | 待机 | "Edited 文件名" |
86
+ | 运行命令 | 奔跑 | "Running command..." |
87
+ | 搜索文件 | 等待 | "Searching..." |
88
+ | 工具失败 | 垂头 | "Oops, something went wrong" + AI 鼓励 |
89
+ | 任务完成 | 跳跃 | "Task complete!" + AI 庆祝 |
90
+ | Claude 停止 | 跳跃 | "Task complete!"（60% 概率触发 AI） |
91
+ | Claude 报错 | 垂头 | 错误信息 + AI 安慰 |
92
+ | 空闲 10+ 分钟 | 挥手 | 时段问候（中文） |
93
+ | 等级提升 | 当前状态 | "Level up! Kernel!" + 特效激活 |
94
+
95
+ ### 互动操作
96
+
97
+ - **拖拽** —— 点击拖动宠物到屏幕任意位置
98
+ - **右键** —— 上下文菜单：显示/隐藏、关于、退出
99
+ - **系统托盘** —— 右下角任务栏图标
100
+ - **彩蛋** —— 快速连续点击宠物，触发递进式反应（2 → 4 → 6 → 9 → 12 → 15 次）
101
+
102
+ ---
103
+
104
+ ## 等级系统
105
+
106
+ 你的宠物随你的编码而成长。每次 Claude Code 操作算一次事件，累积升级：
107
+
108
+ | 等级 | 名称 | 所需事件数 | 颜色 | 视觉效果 |
109
+ |:---:|---|---:|---|---|
110
+ | 1 | **Byte** | 0 | 银色 | 基础宠物 |
111
+ | 2 | **Process** | 50 | 绿色 | 呼吸式发光 |
112
+ | 3 | **Thread** | 200 | 蓝色 | 旋转光环 |
113
+ | 4 | **Module** | 500 | 紫色 | 增强光环 |
114
+ | 5 | **Kernel** | 1,000 | 琥珀 | 漂浮光点粒子 |
115
+ | 6 | **Neural** | 2,000 | 粉色 | 粒子风暴 |
116
+ | 7 | **Quantum** | 5,000 | 青色 | 能量场 |
117
+ | 8 | **Singularity** | 10,000 | 金色 | 金色光环 + 全部特效 |
118
+
119
+ ---
120
+
121
+ ## AI 语音
122
+
123
+ 当 Anthropic API Key 可用时（自动从 Claude Code 设置读取，或通过 `petdex-cc config` 配置），宠物会生成**上下文感知的中文语音**：
124
+
125
+ | 场景 | 触发时机 | AI 生成示例 |
126
+ |---|---|---|
127
+ | `task_complete` | 任务完成 | "做得好！继续加油！" |
128
+ | `error` | 工具失败 | "别担心，bugs难免的~" |
129
+ | `idle` | 空闲超过 10 分钟 | "还在吗？" |
130
+ | `level_up` | 等级跨越阈值 | "升级啦！太厉害了！" |
131
+
132
+ - **2 分钟冷却** —— 连续 AI 调用间隔（升级时自动跳过冷却）
133
+ - **5 秒超时** —— API 响应超过 5 秒自动回退到预设台词
134
+ - **没有 API Key？** 内置预设台词完全够用 —— 7 条任务、5 条错误、5 条空闲、4 条升级
135
+
136
+ ---
137
+
138
+ ## 命令参考
139
+
140
+ ```bash
141
+ petdex-cc install <slug> # 下载宠物、配置 hooks、启动
142
+ petdex-cc start # 启动桌面宠物
143
+ petdex-cc stop # 优雅停止宠物
144
+ petdex-cc list # 浏览 Petdex 宠物库
145
+ petdex-cc switch <slug> # 运行时切换宠物（自动下载）
146
+ petdex-cc status # 查看宠物名称、等级、事件数、运行状态
147
+ petdex-cc uninstall # 移除 hooks、停止宠物、删除所有数据
148
+ petdex-cc config [选项] # 配置设置
149
+ ```
150
+
151
+ ### 配置选项
152
+
153
+ ```bash
154
+ petdex-cc config --api-key <key> # Anthropic API Key（用于 AI 语音）
155
+ petdex-cc config --api-base-url <url> # API 基础 URL
156
+ petdex-cc config --cooldown <分钟> # AI 调用冷却时间（默认 2 分钟）
157
+ ```
158
+
159
+ > API 凭据会自动从 `~/.claude/settings.json` 读取，大多数用户无需手动配置。
160
+
161
+ ---
162
+
163
+ ## 架构设计
164
+
165
+ ```
166
+ ┌─────────────────────────────────────────────────┐
167
+ │ Claude Code │
168
+ │ （工具调用、任务完成、错误、空闲等事件） │
169
+ └──────────────────────┬──────────────────────────┘
170
+ │ hooks（写入 settings.json）
171
+ ▼
172
+ ┌──────────────────┐
173
+ │ bridge.ps1/.sh │ 异步，10 秒超时
174
+ └────────┬─────────┘
175
+ │ HTTP POST /event
176
+ ▼
177
+ ┌─────────────────────────────────────────────────┐
178
+ │ petdex-cc（Electron 主进程） │
179
+ │ │
180
+ │ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
181
+ │ │ event-mapper │ │ storage │ │ ai-speech │ │
182
+ │ │ 事件 → 动作 │ │ 等级、XP │ │ Claude Haiku│ │
183
+ │ └──────┬───────┘ └─────┬────┘ └─────┬──────┘ │
184
+ │ │ │ │ │
185
+ │ └─────────┬───────┘ │ │
186
+ │ ▼ │ │
187
+ │ ┌─────────────────┐ │ │
188
+ │ │ IPC → 渲染窗口 │◀─────────────┘ │
189
+ │ └────────┬────────┘ │
190
+ └──────────────────┼──────────────────────────────────┘
191
+ ▼
192
+ ┌──────────────────┐
193
+ │ 宠物窗口（HTML） │ 透明、始终置顶
194
+ │ │
195
+ │ ┌─── sprite ───┐ │ 9 种动画状态
196
+ │ │ 气泡 │ │ 3s / 8s 自动消失
197
+ │ │ 等级徽章 │ │ 等级标签 + 颜色
198
+ │ │ 特效 │ │ 光晕/光环/粒子/光环
199
+ │ └──────────────┘ │
200
+ └──────────────────┘
201
+ ```
202
+
203
+ ---
204
+
205
+ ## 开发者安装
206
+
207
+ ```bash
208
+ git clone https://github.com/devnomad-byte/petdex-cc.git
209
+ cd petdex-cc
210
+ npm install
211
+ npm run build
212
+
213
+ # 开发模式启动
214
+ npx electron .
215
+
216
+ # 全局安装使用 CLI
217
+ npm link
218
+ petdex-cc install boba
219
+ ```
220
+
221
+ ### 项目结构
222
+
223
+ ```
224
+ petdex-cc/
225
+ ├── bin/cli.ts CLI 入口（8 个命令）
226
+ ├── src/
227
+ │ ├── main/ Electron 主进程
228
+ │ │ ├── index.ts 窗口创建、事件循环、IPC
229
+ │ │ ├── server.ts HTTP 服务器（hooks → 宠物，端口 17321）
230
+ │ │ ├── ai-speech.ts AI 语音（Anthropic Messages API）
231
+ │ │ ├── storage.ts HMAC 签名状态持久化
232
+ │ │ ├── tray.ts 系统托盘（像素猫脸图标）
233
+ │ │ └── event-mapper.ts 8 种 hook 事件 → 宠物动作
234
+ │ ├── renderer/ Electron 渲染进程（宠物 UI）
235
+ │ │ ├── index.html 透明窗口 + CSS 特效
236
+ │ │ ├── renderer.ts IPC 协调 + 等级特效
237
+ │ │ ├── pet-sprite.ts 9 状态精灵图引擎
238
+ │ │ ├── bubble.ts 语音气泡系统
239
+ │ │ ├── click-through.ts 透明点击穿透
240
+ │ │ ├── drag.ts 拖拽 + 点击彩蛋
241
+ │ │ └── context-menu.ts 右键菜单
242
+ │ ├── cli/ CLI 命令实现
243
+ │ ├── hooks/ Claude Code hooks 注册
244
+ │ │ ├── register.ts 写入 ~/.claude/settings.json
245
+ │ │ ├── write-scripts.ts 跨平台 bridge 脚本
246
+ │ │ ├── bridge.ps1 Windows PowerShell bridge
247
+ │ │ └── bridge.sh Unix bash bridge
248
+ │ ├── petdex-api/ Petdex 注册中心客户端
249
+ │ │ ├── client.ts 清单获取 + slug 查询
250
+ │ │ └── download.ts 流式下载 + 进度回调
251
+ │ └── shared/ 共享类型和常量
252
+ ```
253
+
254
+ ---
255
+
256
+ ## 配置参考
257
+
258
+ ### 自动检测
259
+
260
+ petdex-cc 自动从 `~/.claude/settings.json` 读取以下配置：
261
+
262
+ | 配置项 | 用途 |
263
+ |---|---|
264
+ | `ANTHROPIC_AUTH_TOKEN` | AI 语音的 API Key |
265
+ | `ANTHROPIC_BASE_URL` | AI 语音的 API 端点 |
266
+
267
+ ### 手动配置
268
+
269
+ 存储在 `~/.petdex-cc/config.json`：
270
+
271
+ ```bash
272
+ petdex-cc config --api-key <key> --api-base-url <url> --cooldown 2
273
+ ```
274
+
275
+ ### 数据目录
276
+
277
+ | 路径 | 内容 |
278
+ |---|---|
279
+ | `~/.petdex-cc/pets/<slug>/` | 下载的精灵图 + pet.json |
280
+ | `~/.petdex-cc/data/state.json` | 等级、事件数、宠物 slug（HMAC 签名） |
281
+ | `~/.petdex-cc/data/state.sig` | HMAC-SHA256 签名 |
282
+ | `~/.petdex-cc/hooks/` | Bridge 脚本 |
283
+ | `~/.petdex-cc/config.json` | 用户配置（API Key、冷却时间） |
284
+
285
+ ---
286
+
287
+ ## Hooks 参考
288
+
289
+ petdex-cc 在 `~/.claude/settings.json` 中注册以下 hooks：
290
+
291
+ | Hook | 匹配器 | 触发时机 |
292
+ |---|---|---|
293
+ | `PostToolUse` | `Read\|Edit\|Write\|Bash\|Glob\|Grep` | 工具调用之后 |
294
+ | `PostToolUseFailure` | — | 工具调用失败时 |
295
+ | `Stop` | — | Claude 完成响应时 |
296
+ | `StopFailure` | — | Claude 停止并报错时 |
297
+ | `Notification` | `idle_prompt` | 空闲通知 |
298
+ | `SessionStart` | `startup\|resume` | Claude Code 启动或恢复时 |
299
+ | `SessionEnd` | — | Claude Code 会话结束时 |
300
+ | `TaskCompleted` | — | 任务标记完成时 |
301
+
302
+ ---
303
+
304
+ ## 后续计划
305
+
306
+ - [ ] 支持 Cursor
307
+ - [ ] 支持 Windsurf
308
+ - [ ] 支持 GitHub Copilot
309
+ - [ ] 更多宠物互动动作
310
+ - [ ] 宠物换装系统
311
+
312
+ ---
313
+
314
+ ## 许可证
315
+
316
+ [MIT](./LICENSE)
317
+
318
+ ---
319
+
320
+ <div align="center">
321
+ <sub>为 <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a> 社区用心打造</sub><br />
322
+ <sub>宠物来自 <a href="https://petdex.crafter.run/zh">Petdex</a></sub>
323
+ </div>