cc-pets 2.0.0 → 2.0.1
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.
- package/CHANGELOG.md +47 -30
- package/CHANGELOG.zh-CN.md +64 -0
- package/CONTRIBUTING.md +18 -15
- package/CONTRIBUTING.zh-CN.md +22 -0
- package/LICENSE +1 -1
- package/PROVIDER_PROTOCOL.md +50 -41
- package/PROVIDER_PROTOCOL.zh-CN.md +58 -0
- package/README.md +220 -502
- package/README.zh-CN.md +601 -0
- package/Resources/phrases.default.txt +48 -49
- package/SECURITY.md +13 -10
- package/SECURITY.zh-CN.md +18 -0
- package/Sources/CCPets/CCPetsAppDelegate.m +0 -9
- package/Sources/CCPets/CCPetsCodexRateLimits.h +13 -0
- package/Sources/CCPets/CCPetsCodexRateLimits.m +383 -0
- package/Sources/CCPets/CCPetsPhrases.h +1 -24
- package/Sources/CCPets/CCPetsPhrases.m +1 -82
- package/Sources/CCPets/CCPetsPhrasesEditor.m +0 -28
- package/Sources/CCPets/CCPetsQuotaHistory.m +4 -4
- package/Sources/CCPets/CCPetsUsage.m +135 -14
- package/Sources/CCPets/CCPetsUsageMonitor.m +41 -3
- package/Sources/CCPets/PetView.m +17 -10
- package/Sources/CCPets/QuotaDashboardView.m +23 -14
- package/THIRD_PARTY_NOTICES.md +13 -7
- package/THIRD_PARTY_NOTICES.zh-CN.md +12 -0
- package/package.json +14 -5
- package/scripts/pet-store.mjs +1 -1
package/README.md
CHANGED
|
@@ -1,578 +1,293 @@
|
|
|
1
1
|
# CC Pets
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
并从本机 `~/.codex/sessions` 与 Claude Code 官方 status line 数据中读取 5 小时额度、周额度和周重置时间。
|
|
5
|
-
|
|
6
|
-
## 功能
|
|
7
|
-
|
|
8
|
-
- 随 Codex CLI 或 Claude Code CLI 自动启动,无需打开对应桌面版
|
|
9
|
-
- 多个 Codex/Claude CLI 共用一个桌宠,最后一个 CLI 退出后桌宠自动关闭
|
|
10
|
-
- 鼠标悬停口袋时展开额度详情面板,用两张卡分别显示 Codex、Claude 的剩余 5 小时额度、周额度和精确到秒的周重置时间
|
|
11
|
-
- reset 时间自动转换为 Mac 当前系统时区,例如 `Jul 22 3pm America/Los_Angeles` 在上海时区显示为 `7/23 06:00:00`
|
|
12
|
-
- 支持待机、左右拖动、身体两侧感应、头部/脚部悬停和点击反馈动画
|
|
13
|
-
- 待机呼吸、随机小动作(11 行素材会转头看鼠标)、拖动时的水平滞后与落脚回弹
|
|
14
|
-
- 桌宠以自己的口吻播报 Agent 状态,闲着时还会自己碎碎念,台词和频率都可自定义
|
|
15
|
-
- 支持拖动桌宠位置,右键刷新用量、检查更新或退出
|
|
16
|
-
- 响应 Codex 与 Claude Code Agent 的思考、工具调用、审批、子 Agent、完成和失败状态
|
|
17
|
-
- 在桌宠旁显示脱敏后的玻璃 Agent 状态卡片,可展开、折叠并显示活跃 CLI 会话数
|
|
18
|
-
- 支持第三方 CLI Agent 通过统一 Provider 事件协议接入动画和状态
|
|
19
|
-
- 可选记录最近 7 天的本地额度历史,并在额度卡片中显示趋势
|
|
20
|
-
- 可分别启用任务完成、失败和等待审批的 macOS 系统通知
|
|
21
|
-
- 内置一个原创素材,更多桌宠可从兼容 PetDex 的素材源按需下载到本机
|
|
22
|
-
- 使用原生 AppKit,运行时不依赖 Electron
|
|
23
|
-
|
|
24
|
-
## 互动方式
|
|
25
|
-
|
|
26
|
-
### Agent 工作状态
|
|
27
|
-
|
|
28
|
-
| Agent 事件 | 桌宠反馈 |
|
|
29
|
-
| --- | --- |
|
|
30
|
-
| 新会话启动 | 挥手唤醒 |
|
|
31
|
-
| 提交用户提示、Agent 思考 | 思考动画 |
|
|
32
|
-
| 执行 Shell 命令 | 跑动动画 |
|
|
33
|
-
| 编辑或写入文件 | 工作动画 |
|
|
34
|
-
| 读取、搜索或调用 MCP | 观察动画 |
|
|
35
|
-
| 等待审批 | 提醒动画 |
|
|
36
|
-
| 启动子 Agent | 子 Agent 动画 |
|
|
37
|
-
| 工具执行成功 | 完成动画 |
|
|
38
|
-
| 工具执行失败 | 失败动画 |
|
|
39
|
-
| 当前回合或子 Agent 结束 | 告别后恢复待机 |
|
|
40
|
-
|
|
41
|
-
Agent 动画分别由 Codex Hooks 和 Claude Code Hooks 驱动。首次安装或 Codex Hook 内容更新后,启动 Codex 并执行
|
|
42
|
-
`/hooks`,检查并信任 CC Pets Hook;未经信任的用户级 Hook 会被 Codex 安全机制跳过。
|
|
43
|
-
Claude Code Hook 会合并到 `~/.claude/settings.json`,现有的 `env`、`model`、`statusLine`
|
|
44
|
-
以及其他 Hooks 都会保留。额度采集块会注入现有 status line 脚本,但配置中的 `command`
|
|
45
|
-
仍保持原脚本路径,Claude Code 可以继续查找和修改该脚本;脚本输入会同时提供给原状态栏
|
|
46
|
-
和桌宠,原有输出不变。
|
|
47
|
-
通过 npm 安装或升级时会自动重新构建应用、安装或更新两套 Hooks,并配置 shell 集成;如果旧版桌宠正在运行,
|
|
48
|
-
安装器会自动重启桌宠,使新版本生效。`cc-pets install` 用于手动修复或重新初始化。
|
|
49
|
-
|
|
50
|
-
### 鼠标互动
|
|
51
|
-
|
|
52
|
-
| 操作 | 桌宠反馈 |
|
|
53
|
-
|--------------------|----------------------------------------------------------|
|
|
54
|
-
| 鼠标移动到头部 | 播放头部互动动画 |
|
|
55
|
-
| 鼠标移动到口袋 | 播放口袋互动动画,并从桌宠左侧展开 Codex/Claude 额度面板 |
|
|
56
|
-
| 鼠标移动到脚部 | 播放脚部互动动画 |
|
|
57
|
-
| 鼠标移动到身体右侧 | 播放右侧感应动画 |
|
|
58
|
-
| 鼠标移动到身体左侧 | 播放左侧感应动画 |
|
|
59
|
-
| 单击桌宠 | 播放一次俏皮反馈动画 |
|
|
60
|
-
| 按住并向右拖动 | 播放向右拖行动画,同时移动桌宠 |
|
|
61
|
-
| 按住并向左拖动 | 播放向左拖行动画,同时移动桌宠 |
|
|
62
|
-
| 鼠标移开或拖动结束 | 恢复默认待机动画 |
|
|
63
|
-
| 右键桌宠 | 切换桌宠、刷新用量、设置历史/通知、检查更新或退出 |
|
|
64
|
-
|
|
65
|
-
右键菜单中的“切换桌宠”只扫描 `~/.cc-pets/pets/`(见 [素材管理](#素材管理))和包内素材,
|
|
66
|
-
**不会**去读 `~/.petdex/pets/` 和 `~/.codex/pets/`——那两个目录由 PetDex CLI 和 Codex 写入,
|
|
67
|
-
混在一起就找不到自己装的宠物了。要用 Codex 那边的素材,打开右键菜单里的“导入 Codex
|
|
68
|
-
素材”开关,它们会被复制进你自己的目录(见 [导入 Codex 素材](#导入-codex-素材))。
|
|
69
|
-
|
|
70
|
-
外部桌宠使用目录名作为菜单名称,内置桌宠使用素材文件名(不显示扩展名)。选择后立即
|
|
71
|
-
切换并持久保存;下次启动会继续使用上次选择的桌宠。该菜单只负责切换已有素材,不提供
|
|
72
|
-
添加或删除功能。
|
|
73
|
-
|
|
74
|
-
素材列表在启动时加载一次,之后按 `~/.cc-pets/pets/` 的修改时间判断是否需要重扫:
|
|
75
|
-
`cc-pets pet add` / `remove` 会改动这个目录,因此增删素材后打开菜单就能看到,
|
|
76
|
-
不需要重启桌宠,也不需要重新编译;没有增删时打开菜单只做一次 `stat`,不会遍历目录。
|
|
77
|
-
|
|
78
|
-
当 `~/.petdex/pets/<name>/` 只有 `pet.json` 时,程序会自动到
|
|
79
|
-
`~/.codex/pets/<name>/` 查找同名桌宠的 `spritesheet.webp` 或 `spritesheet.png`。
|
|
80
|
-
外部素材遵循 Codex 桌面端的 `spriteVersionNumber` 协议:字段缺失或为 `1` 时按
|
|
81
|
-
`1536×1872`、`8×9` 网格解析;为 `2` 时按 `1536×2288`、`8×11` 网格解析。
|
|
82
|
-
v2 新增的最后两行用于十六向鼠标跟随;只在桌宠空闲时启用,拖动、悬停互动和
|
|
83
|
-
Agent 状态动画会优先播放。
|
|
84
|
-
|
|
85
|
-
交互区域存在重叠时,按“口袋、头部、脚部、身体左右侧”的优先级识别。拖动超过
|
|
86
|
-
3 像素后才进入拖动状态,避免普通点击被误判为拖动。
|
|
87
|
-
|
|
88
|
-
素材行与行为的对应关系:
|
|
89
|
-
|
|
90
|
-
1. 默认待机(6 帧)
|
|
91
|
-
2. 向右拖动(8 帧)
|
|
92
|
-
3. 向左拖动(8 帧)
|
|
93
|
-
4. 身体右侧感应(4 帧)
|
|
94
|
-
5. 头部悬停(5 帧)
|
|
95
|
-
6. 口袋悬停与额度展示(8 帧)
|
|
96
|
-
7. 脚部悬停(6 帧)
|
|
97
|
-
8. 点击反馈(6 帧)
|
|
98
|
-
9. 身体左侧感应(6 帧)
|
|
99
|
-
|
|
100
|
-
右键菜单中的“记录本地额度历史”默认关闭。启用后只在本机
|
|
101
|
-
`~/Library/Application Support/CC Pets/quota-history.json` 保存最近 7 天的数据,
|
|
102
|
-
每 15 分钟最多记录一次。系统通知也默认关闭,可在“系统通知”子菜单中分别启用任务完成、
|
|
103
|
-
任务失败和等待审批通知。
|
|
104
|
-
|
|
105
|
-
Agent 状态卡片会根据屏幕剩余空间自动显示在桌宠上方或下方。点击桌宠旁的圆形箭头可以
|
|
106
|
-
折叠卡片;折叠后圆钮会显示当前活跃的 Codex/Claude CLI 会话数,点击后重新展开。卡片只展示
|
|
107
|
-
Provider、脱敏状态和通用说明,不提供消息输入,也不会显示提示词、命令正文或模型输出。
|
|
108
|
-
连续 1 分钟没有收到新的 Agent 状态事件时,卡片和圆钮会一起自动隐藏;下一次收到事件时
|
|
109
|
-
会重新显示并重新计时。
|
|
110
|
-
|
|
111
|
-
## 碎碎念
|
|
112
|
-
|
|
113
|
-
桌宠会以自己的口吻讲话:Agent 干活时讲的话直接写在状态卡副行上,闲着的时候单独冒气泡。
|
|
114
|
-
右键菜单「碎碎念」里可以整体开关、调频率、改台词。
|
|
115
|
-
|
|
116
|
-
### 频率
|
|
117
|
-
|
|
118
|
-
四个档位,一个开关同时管住四道闸——它们互相牵制,单调其中任何一道都不会真的变频繁:
|
|
119
|
-
|
|
120
|
-
| 档位 | 每小时最多 | 两句最短间隔 | 静默多久才算闲 | 每次判定的出话概率 |
|
|
121
|
-
|--------------|------------|--------------|----------------|--------------------|
|
|
122
|
-
| 很少 | 2 句 | 480 秒 | 300 秒 | 15% |
|
|
123
|
-
| 正常(默认) | 4 句 | 240 秒 | 180 秒 | 25% |
|
|
124
|
-
| 较多 | 8 句 | 120 秒 | 90 秒 | 45% |
|
|
125
|
-
| 话痨 | 20 句 | 45 秒 | 45 秒 | 70% |
|
|
126
|
-
|
|
127
|
-
Agent **正在干活**时(思考、调用工具、等待审批、子 Agent 工作等)不会插嘴,状态卡上的
|
|
128
|
-
工作文案优先级最高。只有状态卡处于「待机中」或压根没显示时才会碎碎念——所以开着终端
|
|
129
|
-
也照样会说话,不需要退出 CLI。借走状态卡副行说完一句后,副行会自动还原成状态文案。
|
|
130
|
-
|
|
131
|
-
### 编辑台词
|
|
132
|
-
|
|
133
|
-
右键菜单「碎碎念 → 编辑台词…」打开内置编辑器。桌宠说的**所有**话都在
|
|
134
|
-
`~/.cc-pets/speech.txt` 里,代码里没有第二份词库——首次启动时从 app 内的默认词库
|
|
135
|
-
拷一份出来,之后就只认这个文件。
|
|
136
|
-
|
|
137
|
-
语义只有一条:**文件里有什么就说什么**。没有合并、没有 replace、没有兜底,
|
|
138
|
-
删掉一节就是那个情境不吭声。
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
# 井号开头是注释,行尾的 " #" 之后也是注释
|
|
142
|
-
[idle] # 闲着没事
|
|
143
|
-
又没人理我。
|
|
144
|
-
今天也是划水的一天。
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
- `[情境]` 起一节,下面一行一句,直接改字、加行、删行
|
|
148
|
-
- 每句 30 字以内,超了那一行会被丢掉
|
|
149
|
-
- 写错只丢那一行,不会让整个文件失效
|
|
150
|
-
|
|
151
|
-
可以插入这些实时数据(连花括号一起写):`{quota5h}` `{resetTime}` `{toolName}`
|
|
152
|
-
`{sessionMin}` `{failCount}` `{hour}`。取不到值时,用到该槽位的那一句会被整条跳过,
|
|
153
|
-
不会显示占位符。
|
|
154
|
-
|
|
155
|
-
编辑器的三个按钮:
|
|
156
|
-
|
|
157
|
-
- **试说一句** —— 选一个情境,桌宠当场把那一节里的一句说出来。读的是编辑器里
|
|
158
|
-
**还没保存**的文本,槽位用示例数据填,所以不用等到真的额度告急才能看到效果
|
|
159
|
-
- **恢复默认台词…** —— 把编辑器内容换成默认词库,按 ⌘Z 可撤销,不保存不写文件
|
|
160
|
-
- **保存**(⌘S)/ **保存并关闭**(⏎)—— 保存时校验,问题当场列出来。
|
|
161
|
-
校验没过或被 mtime 冲突取消时不会关窗,改动不会跟着窗口一起消失
|
|
162
|
-
|
|
163
|
-
### 给单只宠物写专属台词
|
|
164
|
-
|
|
165
|
-
上面那份 `speech.txt` 是**所有**宠物的通用台词。想让某一只换个口吻,编辑器顶部有一个
|
|
166
|
-
「**通用** / **当前宠物 · ×××**」的切换——切到右边,写的就只属于当前这只宠物,
|
|
167
|
-
存在 `~/.cc-pets/speech/<宠物名>.txt`(内置素材是 `builtin-默认.txt`)。
|
|
168
|
-
|
|
169
|
-
这一页**初次打开是空白的,这是正常的**:空白 = 这只宠物全部沿用通用台词。
|
|
170
|
-
不知道能写什么就点右上角 **填入默认模板**,它会把整份默认台词以**注释状态**填进来
|
|
171
|
-
(每行都以 `#` 开头,一句都不生效,这只宠物说的还是通用台词)。想让哪一节归它自己管,
|
|
172
|
-
把那一节行首的 `#` 去掉再改字就行。
|
|
173
|
-
|
|
174
|
-
手写的话,**只写想改的小节**就行:
|
|
175
|
-
|
|
176
|
-
```
|
|
177
|
-
# ~/.cc-pets/speech/external-哆啦A梦.txt
|
|
178
|
-
[idle]
|
|
179
|
-
铜锣烧…
|
|
180
|
-
口袋里好像有点东西。
|
|
181
|
-
|
|
182
|
-
[done]
|
|
183
|
-
诺,任意门给你。
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
这样它闲着和完工时说自己的话,其余情境照旧用通用的。三种写法对应三种结果:
|
|
187
|
-
|
|
188
|
-
| 专属文件里 | 结果 |
|
|
189
|
-
| --- | --- |
|
|
190
|
-
| 没写这一节 | 用通用的 |
|
|
191
|
-
| 写了,下面有台词 | **整节接管**,通用的那一节一句都不参与 |
|
|
192
|
-
| 写了标签,下面空着 | 这只宠物在这个情境不吭声 |
|
|
3
|
+
English | [简体中文](./README.zh-CN.md)
|
|
193
4
|
|
|
194
|
-
|
|
5
|
+
A native macOS desktop pet for Codex CLI and Claude Code CLI. CC Pets runs without
|
|
6
|
+
either desktop app and reads five-hour and weekly quota data from local Codex
|
|
7
|
+
sessions and Claude Code's official status line input.
|
|
195
8
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
「试说一句」在专属没写该小节时会照实说出通用的那一句,并注明「这一节来自通用台词」。
|
|
199
|
-
按钮此时也变成 **清空这一页…**:清空即全部回落到通用,专属词库没有「默认」这个概念。
|
|
200
|
-
「填入默认模板」填的是注释版而不是直接可用的整份台词,也是同一个道理——直接填进
|
|
201
|
-
22 节未注释的台词,这只宠物就每一节都自己管、再也不会回落了,那正好毁掉这一页的用法。
|
|
9
|
+
> The application UI and the screenshots below are currently in Simplified Chinese.
|
|
10
|
+
> English UI localization and English screenshots are planned for v2.1.0.
|
|
202
11
|
|
|
203
|
-
|
|
204
|
-
删掉某只宠物的素材不会删它的专属台词文件,重新装回同名素材时台词还在。
|
|
12
|
+
## Screenshots
|
|
205
13
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
标签行是配置项,22 个一个都不能删。删掉之后编辑器里就看不见它了,用户既不知道少的是
|
|
209
|
-
哪个也不知道该写成什么样,所以保存时会**自动把标签加回原位**——台词还在的话会连同台词
|
|
210
|
-
一起归位——并在提示里说明补了哪些。能不能留空才分两种:
|
|
211
|
-
|
|
212
|
-
| | 行为 |
|
|
14
|
+
| Subscription view | API usage view |
|
|
213
15
|
| --- | --- |
|
|
214
|
-
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
-
|
|
225
|
-
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
```sh
|
|
237
|
-
defaults write com.universewang.cc-pets CCPetsSpeechFrequency -string chatty
|
|
238
|
-
defaults write com.universewang.cc-pets CCPetsSpeechCooldown -float 0 # 覆盖档位里的间隔
|
|
239
|
-
defaults write com.universewang.cc-pets CCPetsSpeechHourlyBudget -int 100 # 覆盖档位里的预算
|
|
240
|
-
defaults write com.universewang.cc-pets CCPetsBoredomScale -float 0.1 # 压缩无聊曲线与静默门槛
|
|
241
|
-
defaults write com.universewang.cc-pets CCPetsSpeechDebugTag -string quota_low # 立刻弹一次,弹完自动清
|
|
242
|
-
defaults delete com.universewang.cc-pets CCPetsSpeechCooldown # 交回档位
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
## 系统要求
|
|
246
|
-
|
|
247
|
-
- macOS 13 或更高版本
|
|
248
|
-
- Node.js 18 或更高版本
|
|
249
|
-
- 已安装并登录 Codex CLI 和/或 Claude Code CLI
|
|
16
|
+
|  |  |
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
- Starts with Codex CLI or Claude Code CLI and closes after the last managed CLI exits.
|
|
21
|
+
- Shares one pet across multiple simultaneous Codex and Claude sessions.
|
|
22
|
+
- Shows five-hour and weekly remaining quota, reset times, local token totals, and seven-day trends.
|
|
23
|
+
- Converts reset times to the Mac's current system time zone.
|
|
24
|
+
- Responds to thinking, tool, approval, subagent, completion, and failure events.
|
|
25
|
+
- Displays a redacted glass status card with the active CLI session count.
|
|
26
|
+
- Supports optional local quota history and macOS notifications.
|
|
27
|
+
- Supports third-party CLI agents through a provider event protocol.
|
|
28
|
+
- Includes editable global and per-pet speech.
|
|
29
|
+
- Includes one original pet and can download compatible assets from PetDex.
|
|
30
|
+
- Uses native AppKit with no Electron runtime.
|
|
31
|
+
|
|
32
|
+
## Requirements
|
|
33
|
+
|
|
34
|
+
- macOS 13 or later
|
|
35
|
+
- Node.js 18 or later
|
|
36
|
+
- Codex CLI and/or Claude Code CLI installed and signed in
|
|
250
37
|
- zsh
|
|
251
|
-
- Xcode Command Line Tools
|
|
38
|
+
- Xcode Command Line Tools (`xcode-select --install`)
|
|
252
39
|
|
|
253
|
-
##
|
|
40
|
+
## Installation
|
|
254
41
|
|
|
255
|
-
### npm
|
|
42
|
+
### Install from npm
|
|
256
43
|
|
|
257
44
|
```bash
|
|
258
45
|
npm install -g cc-pets@latest --allow-scripts=cc-pets
|
|
259
|
-
#
|
|
46
|
+
# Open a new terminal after the first installation.
|
|
260
47
|
codex
|
|
261
|
-
#
|
|
48
|
+
# or
|
|
262
49
|
claude
|
|
263
50
|
```
|
|
264
51
|
|
|
265
|
-
`--allow-scripts=cc-pets`
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
如果已经只执行了 `npm install -g cc-pets@latest`,并看到 npm 提示安装脚本尚未获准,
|
|
270
|
-
可以在包安装完成后手动初始化:
|
|
52
|
+
The `--allow-scripts=cc-pets` option allows recent npm versions to run the
|
|
53
|
+
package's `postinstall`. That step builds the native app, installs both hook
|
|
54
|
+
integrations, configures shell shims, and installs `~/Applications/CC Pets.app`.
|
|
55
|
+
If npm installed the package without running its scripts, initialize it manually:
|
|
271
56
|
|
|
272
57
|
```bash
|
|
273
58
|
cc-pets install
|
|
274
59
|
```
|
|
275
60
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
npm 12 起默认启用安装脚本白名单:不在白名单里的包不会执行 `postinstall`,而安装过程仍以
|
|
279
|
-
成功退出。此时原生应用、Hooks 和 shell 集成都没有装上,表现为敲 `codex` / `claude` 时
|
|
280
|
-
桌宠不出现。不想每次都带 `--allow-scripts` 参数的话,可以配置一次持久白名单:
|
|
61
|
+
To persist the npm install-script allowlist for future installations:
|
|
281
62
|
|
|
282
63
|
```bash
|
|
283
64
|
npm config set allow-scripts=cc-pets --location=user
|
|
284
65
|
```
|
|
285
66
|
|
|
286
|
-
|
|
67
|
+
The allowlist only affects future installs, so reinstall the package or run
|
|
68
|
+
`cc-pets install` after changing it.
|
|
287
69
|
|
|
288
|
-
###
|
|
70
|
+
### Install from source
|
|
289
71
|
|
|
290
72
|
```bash
|
|
291
|
-
git clone https://github.com/
|
|
73
|
+
git clone https://github.com/Sunnyshinnny776/cc-pets.git
|
|
292
74
|
cd cc-pets
|
|
293
75
|
npm install -g . --ignore-scripts
|
|
294
76
|
cc-pets install
|
|
295
|
-
#
|
|
77
|
+
# Open a new terminal after the first installation.
|
|
296
78
|
codex
|
|
297
|
-
#
|
|
79
|
+
# or
|
|
298
80
|
claude
|
|
299
81
|
```
|
|
300
82
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
npm 的安装后脚本会自动构建原生应用、安装两套 Agent Hooks,并在 `~/.cc-pets/shims` 下生成指向包装脚本的
|
|
306
|
-
`codex` 与 `claude` 软链,再向 `~/.zshrc` 追加带明确标记的一行把该目录前置到 `PATH`,不会覆盖真实的 CLI 二进制。
|
|
307
|
-
用 shim 而不是 alias,是因为 alias 名区分大小写而 macOS 文件系统默认不区分:`Claude`、`CODEX` 这类写法
|
|
308
|
-
匹配不到 alias,会直接命中真二进制,桌宠不会被拉起。shim 让任意大小写写法都落到同一个文件上。
|
|
309
|
-
首次安装需要新开终端让 `PATH` 生效;以后升级只需执行 npm 命令。
|
|
310
|
-
同时会将标准 macOS 应用安装到 `~/Applications/CC Pets.app`,可从 Finder 或 Launchpad 启动,
|
|
311
|
-
不需要管理员权限。npm 升级时会同步更新该应用。
|
|
83
|
+
CC Pets installs `cc-pets`, `codex-with-pet`, and `claude-with-pet`. It creates
|
|
84
|
+
`codex` and `claude` shims under `~/.cc-pets/shims` and adds one marked block to
|
|
85
|
+
`~/.zshrc`; the real CLI binaries are not replaced. The shims also handle casing
|
|
86
|
+
variants on the default case-insensitive macOS filesystem.
|
|
312
87
|
|
|
313
|
-
|
|
314
|
-
随后在后台复用首次安装时记录的 Node.js/npm 完成升级;用户无需打开终端。升级会同步更新原生应用、
|
|
315
|
-
Codex/Claude Hooks 和 shell 集成,并自动重启正在运行的桌宠。自动更新不会请求管理员权限;如果原来的
|
|
316
|
-
全局 npm 目录不可写或 Node.js/npm 已被移动,应用会保留旧版本并显示更新日志和手动升级命令。
|
|
317
|
-
|
|
318
|
-
### 指定真实 CLI 路径
|
|
319
|
-
|
|
320
|
-
如果真实 Codex CLI 不在当前 `PATH`,可以显式指定:
|
|
88
|
+
If a real CLI is not on the current `PATH`, set its absolute path:
|
|
321
89
|
|
|
322
90
|
```bash
|
|
323
91
|
export CODEX_REAL_BIN=/absolute/path/to/codex
|
|
92
|
+
export CLAUDE_REAL_BIN=/absolute/path/to/claude
|
|
324
93
|
```
|
|
325
94
|
|
|
326
|
-
|
|
327
|
-
|
|
95
|
+
The wrappers pass the current terminal environment through unchanged. They do not
|
|
96
|
+
load or execute `.env` files.
|
|
328
97
|
|
|
329
|
-
|
|
98
|
+
## Commands
|
|
330
99
|
|
|
331
100
|
```bash
|
|
332
|
-
|
|
101
|
+
cc-pets build # Build the native app.
|
|
102
|
+
cc-pets # Start independently from a CLI session.
|
|
103
|
+
cc-pets --foreground # Run in the foreground for debugging.
|
|
104
|
+
cc-pets --version # Print the installed version.
|
|
105
|
+
cc-pets --status # Print parsed Codex quota data.
|
|
106
|
+
cc-pets --history # Print local quota history as JSON.
|
|
107
|
+
cc-pets clean # Remove rebuildable state and caches.
|
|
108
|
+
|
|
109
|
+
cc-pets pet search otter # Search the configured asset source.
|
|
110
|
+
cc-pets pet add boba # Install an asset into CC Pets' own directory.
|
|
111
|
+
cc-pets pet list # List installed assets.
|
|
112
|
+
cc-pets pet remove boba # Remove an installed asset.
|
|
113
|
+
|
|
114
|
+
cc-pets install # Repair or reinitialize integrations.
|
|
115
|
+
cc-pets uninstall # Remove integrations and restore the status line.
|
|
116
|
+
cc-pets uninstall --purge # Also remove the app and all local data after confirmation.
|
|
117
|
+
cc-pets uninstall-app # Remove only ~/Applications/CC Pets.app.
|
|
118
|
+
|
|
119
|
+
codex-with-pet # Start the pet and enter Codex CLI.
|
|
120
|
+
claude-with-pet # Start the pet and enter Claude Code CLI.
|
|
333
121
|
```
|
|
334
122
|
|
|
335
|
-
|
|
123
|
+
`package.json` is the single version source. Use `npm version patch`, `minor`, or
|
|
124
|
+
`major` for a future release; npm runs the test suite and the build writes the
|
|
125
|
+
version into the generated app's `Info.plist`.
|
|
336
126
|
|
|
337
|
-
|
|
338
|
-
# 构建原生程序
|
|
339
|
-
cc-pets build
|
|
340
|
-
|
|
341
|
-
# 独立启动桌宠;独立启动时不会随 CLI 自动退出
|
|
342
|
-
cc-pets
|
|
343
|
-
|
|
344
|
-
# 前台运行,便于调试
|
|
345
|
-
cc-pets --foreground
|
|
346
|
-
|
|
347
|
-
# 查看当前安装版本(也支持 cc-pets -v)
|
|
348
|
-
cc-pets --version
|
|
349
|
-
|
|
350
|
-
# 查看当前解析到的 Codex 额度
|
|
351
|
-
cc-pets --status
|
|
127
|
+
## Agent integration
|
|
352
128
|
|
|
353
|
-
|
|
354
|
-
|
|
129
|
+
Codex Hooks and Claude Code Hooks drive the pet's agent-state animations. After a
|
|
130
|
+
first installation or a Codex Hook update, start Codex and run `/hooks` to review
|
|
131
|
+
and trust the CC Pets Hook. Codex skips untrusted user hooks.
|
|
355
132
|
|
|
356
|
-
|
|
357
|
-
|
|
133
|
+
The Claude Code integration merges into `~/.claude/settings.json` while preserving
|
|
134
|
+
existing `env`, `model`, `statusLine`, and hook settings. Its quota collector is
|
|
135
|
+
injected into the existing status line script without changing the configured
|
|
136
|
+
script path or output.
|
|
358
137
|
|
|
359
|
-
|
|
360
|
-
cc-pets pet search otter
|
|
361
|
-
cc-pets pet add boba
|
|
362
|
-
cc-pets pet list
|
|
138
|
+
Third-party CLI agents can send redacted state events through standard input:
|
|
363
139
|
|
|
364
|
-
|
|
140
|
+
```bash
|
|
365
141
|
printf '%s' '{"schemaVersion":1,"provider":"MyAgent","state":"thinking"}' \
|
|
366
142
|
| cc-pets provider-event
|
|
367
|
-
|
|
368
|
-
# 手动修复或重新初始化 Hooks、shell 集成,并让已运行桌宠加载当前版本
|
|
369
|
-
cc-pets install
|
|
370
|
-
|
|
371
|
-
# 安全移除 Hooks、恢复 Claude status line,并清理 shell 集成
|
|
372
|
-
cc-pets uninstall
|
|
373
|
-
|
|
374
|
-
# 完整移除集成、应用和全部本地数据;执行前会再次确认
|
|
375
|
-
cc-pets uninstall --purge
|
|
376
|
-
|
|
377
|
-
# 仅删除 ~/Applications 中的 macOS 应用(不会删除 npm 包或 Hooks)
|
|
378
|
-
cc-pets uninstall-app
|
|
379
|
-
|
|
380
|
-
# 启动桌宠后进入 Codex CLI
|
|
381
|
-
codex-with-pet
|
|
382
|
-
|
|
383
|
-
# 启动桌宠后进入 Claude Code CLI
|
|
384
|
-
claude-with-pet
|
|
385
143
|
```
|
|
386
144
|
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
生成的 App `Info.plist`,无需手动修改 `Resources/Info.plist`。
|
|
390
|
-
|
|
391
|
-
## 用量数据
|
|
392
|
-
|
|
393
|
-
Codex 用量来自 `~/.codex/sessions` 的本地 `token_count` 事件:
|
|
394
|
-
|
|
395
|
-
- `window_minutes = 300` 对应 5 小时额度
|
|
396
|
-
- `window_minutes = 10080` 对应周额度
|
|
397
|
-
- 桌宠将 `used_percent` 换算为剩余百分比后显示
|
|
398
|
-
- Codex 本地 Token 按服务端 `resets_at - window_minutes` 到 `resets_at` 聚合,
|
|
399
|
-
与官方 5 小时和 7 天额度周期保持一致
|
|
400
|
-
- Token 统计包含输入、缓存输入、缓存写入、输出、推理输出与总量;面板展示总量
|
|
401
|
-
- Codex 当前事件未提供某个额度窗口时显示 `--`,不会使用已过期的历史额度冒充当前值
|
|
402
|
-
|
|
403
|
-
Claude 用量来自官方 status line 输入中的 `rate_limits.five_hour` 与
|
|
404
|
-
`rate_limits.seven_day`。其中的 `used_percentage` 会换算为剩余百分比。该字段仅面向
|
|
405
|
-
Claude.ai Pro/Max 订阅账号,并在会话完成首次 API 响应后出现;字段尚不可用时显示 `--`。
|
|
406
|
-
|
|
407
|
-
Claude Code 本地 Token 来自 `~/.claude/projects` 下的会话转录:
|
|
408
|
-
|
|
409
|
-
- 每条 `type = assistant` 的记录带 `message.usage`,是**单次请求的增量**,与 Codex 的
|
|
410
|
-
会话累计值不同,因此按时间戳逐条落窗口累加
|
|
411
|
-
- 窗口同样对齐 `resets_at`;Claude 的 `rate_limits` 不含 `window_minutes`,窗长按官方
|
|
412
|
-
订阅固定为 300 / 10080 分钟
|
|
413
|
-
- `--resume`、fork 和 compact 会把旧记录原样复制进新的转录文件,因此按
|
|
414
|
-
`message.id + requestId` 全局去重(两者缺失时回退行级 `uuid`),否则用量会明显虚高
|
|
415
|
-
- 统计包含输入、缓存读取、缓存写入、输出与总量;Claude 的思考 token 已计入
|
|
416
|
-
`output_tokens`,不单列推理项
|
|
417
|
-
|
|
418
|
-
Claude Code 支持用 `CLAUDE_CONFIG_DIR` 把配置目录指到别处,同一台机器因此可能存在多个
|
|
419
|
-
配置目录(不同账号、各自独立的额度周期)。桌宠**固定只统计 `~/.claude`**,不读
|
|
420
|
-
`CLAUDE_CONFIG_DIR`:桌宠是被某个客户端启动的常驻进程,会一直带着启动时的环境,用它选
|
|
421
|
-
目录等于永久绑定到"第一个拉起桌宠的账号"。确实把配置目录整体搬走的用户可以设
|
|
422
|
-
`CC_PETS_CLAUDE_CONFIG_DIR`(与 `CC_PETS_STATE_DIR` 等覆盖变量同一套约定),正常使用下
|
|
423
|
-
不需要设置。
|
|
424
|
-
|
|
425
|
-
额度文件按配置目录分开存放,因此多个配置目录的 status line 不会互相覆盖——否则面板会
|
|
426
|
-
把一个账号的剩余百分比配上另一个账号的用量。
|
|
427
|
-
|
|
428
|
-
Codex 侧同理:桌宠固定只统计 `~/.codex`,不读继承来的 `CODEX_HOME`,需要时用
|
|
429
|
-
`CC_PETS_CODEX_HOME` 覆盖。跑在 Codex 会话里的记录端(Agent Hooks、安装脚本)照常认
|
|
430
|
-
`CODEX_HOME`,那是会话级的、不存在被常驻进程带跑的问题。
|
|
431
|
-
|
|
432
|
-
本地 Token 是 CLI 会话事件的原始计数,不等同于订阅额度。官方额度可能受模型、缓存和
|
|
433
|
-
请求复杂度等因素影响,应始终以服务端返回的百分比为准。
|
|
434
|
-
|
|
435
|
-
额度详情面板使用青色区分 Codex、紫色区分 Claude。标题行显示在线 Agent 数,下方汇总条
|
|
436
|
-
分别展示 Codex、Claude 的「今日」与「最近 7 天」Token,并显示最近刷新时间。统计用的是与订阅无关的
|
|
437
|
-
自然日窗口(今日 = 本机零点至今,最近 7 天 = 含今天在内的 7 个自然日),因为两家的
|
|
438
|
-
`resets_at` 并不一致,按各自订阅窗口算出的数不在同一区间上,相加没有意义。每个 Agent 卡片按 5 小时和 7 天两列
|
|
439
|
-
展示官方剩余百分比(主值)、本机 Token 用量和重置时间,右侧是近 7 天额度趋势。右键菜单的
|
|
440
|
-
“用量展示模式”可分别为 Codex、Claude 选择“订阅额度”或“API 用量”;API 用量模式只替换对应
|
|
441
|
-
卡片内部,展示本月调用次数、本月输入/输出 Token、较上月同期变化和本月按日 Token 趋势。
|
|
442
|
-
“调用次数”来自本机会话记录:Claude 按请求标识去重,Codex 按去重后的累计 Token 快照计数。
|
|
443
|
-
某个窗口
|
|
444
|
-
当前没有额度数据时该列标注"当前无活跃窗口"。卡片上的在线徽章表示该 Provider 是否还有
|
|
445
|
-
运行中的客户端(包装脚本写出的 pid 文件,或该 Provider 最近 60 秒内仍在发事件),与是否
|
|
446
|
-
已采集到额度数据无关;客户端退出后显示"离线",从未采集到数据时显示"等待数据"。经
|
|
447
|
-
`codex-with-pet` / `claude-with-pet` 启动的会话退出后 3 秒内转为离线;直接运行 `codex` /
|
|
448
|
-
`claude` 时没有可靠的退出信号,最多需要 60 秒静默才会转为离线。服务端的 Unix 时间戳会使用 Mac 当前系统时区
|
|
449
|
-
格式化为 `M/d HH:mm`;因此它与 CLI 中标注其他时区的同一时刻可能日期和小时不同,但代表
|
|
450
|
-
同一个真实时间。
|
|
451
|
-
应用通过文件事件实时读取额度,并保留 120 秒容错刷新;右上角刷新按钮也可立即读取本地数据。Codex 数据随本地 session 更新,Claude 数据则要等 Claude Code
|
|
452
|
-
下一次把 `rate_limits` 传给 status line 后才会变化,按钮不会主动请求 Claude 服务端。
|
|
453
|
-
面板使用原生 AppKit 毛玻璃材质,以紧凑悬浮卡片形式显示在桌宠左上方,并优先使用本机官方 Codex、Claude 应用
|
|
454
|
-
图标。鼠标从口袋移动到面板后可继续停留查看,移出两者后面板会延迟收起;拖动桌宠时
|
|
455
|
-
面板会保持显示并实时跟随位置。
|
|
456
|
-
|
|
457
|
-
第三方 CLI Agent 可以使用统一 Provider 事件协议复用状态气泡、动画和通知能力,协议说明见
|
|
458
|
-
[PROVIDER_PROTOCOL.md](./PROVIDER_PROTOCOL.md)。协议不接收命令正文、提示词或模型输出。
|
|
459
|
-
|
|
460
|
-
可以独立验证解析结果:
|
|
145
|
+
See [Provider protocol](./PROVIDER_PROTOCOL.md). The protocol does not accept
|
|
146
|
+
prompts, command text, file contents, or model output.
|
|
461
147
|
|
|
462
|
-
|
|
463
|
-
./scripts/build.sh
|
|
464
|
-
./.build/release/cc-pets --status
|
|
465
|
-
```
|
|
148
|
+
## Pet interaction
|
|
466
149
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
150
|
+
| Interaction | Response |
|
|
151
|
+
| --- | --- |
|
|
152
|
+
| Hover over the head | Head interaction animation |
|
|
153
|
+
| Hover over the pocket | Pocket animation and quota panel |
|
|
154
|
+
| Hover over the feet | Foot interaction animation |
|
|
155
|
+
| Hover on either body side | Directional interaction animation |
|
|
156
|
+
| Click | Playful response animation |
|
|
157
|
+
| Drag left or right | Directional drag animation |
|
|
158
|
+
| Right-click | Pet, quota, notification, update, and exit menu |
|
|
159
|
+
|
|
160
|
+
The pet switcher scans only built-in assets and `~/.cc-pets/pets/`. It does not
|
|
161
|
+
scan `~/.petdex/pets/` or `~/.codex/pets/`. To use assets installed by Codex,
|
|
162
|
+
enable **Import Codex pets** in the app's right-click menu; CC Pets copies valid
|
|
163
|
+
assets into its own directory without overwriting names already present.
|
|
164
|
+
|
|
165
|
+
External assets use their directory name in the menu. The app caches the list and
|
|
166
|
+
rescans when the modification time of `~/.cc-pets/pets/` changes, so CLI add/remove
|
|
167
|
+
operations do not require a restart or rebuild.
|
|
168
|
+
|
|
169
|
+
CC Pets supports the Codex `spriteVersionNumber` layouts:
|
|
170
|
+
|
|
171
|
+
- v1 or a missing version: `1536×1872`, an `8×9` grid
|
|
172
|
+
- v2: `1536×2288`, an `8×11` grid
|
|
173
|
+
- cell size: `192×208`
|
|
174
|
+
|
|
175
|
+
The first nine rows contain idle, right drag, left drag, right-side interaction,
|
|
176
|
+
head, pocket, feet, click, and left-side interaction animations. The two v2 rows
|
|
177
|
+
add 16-direction mouse tracking while idle.
|
|
178
|
+
|
|
179
|
+
## Quota and local usage data
|
|
180
|
+
|
|
181
|
+
Codex quota data comes from local `token_count` events under
|
|
182
|
+
`~/.codex/sessions`. A `window_minutes` value of `300` is the five-hour window and
|
|
183
|
+
`10080` is the weekly window. CC Pets displays remaining percentage and does not
|
|
184
|
+
substitute expired history when a current window is unavailable.
|
|
185
|
+
|
|
186
|
+
Claude quota data comes from `rate_limits.five_hour` and
|
|
187
|
+
`rate_limits.seven_day` in Claude Code's official status line input. These values
|
|
188
|
+
are available for Claude.ai Pro/Max subscriptions after the session's first API
|
|
189
|
+
response. Missing values display as `--`.
|
|
190
|
+
|
|
191
|
+
Local token counts are usage observations, not subscription quota. Codex counts
|
|
192
|
+
come from local session events. Claude counts come from assistant usage records
|
|
193
|
+
under `~/.claude/projects`, aligned to the server reset window and deduplicated
|
|
194
|
+
across resume, fork, and compaction copies.
|
|
195
|
+
|
|
196
|
+
The persistent app reads `~/.codex` and `~/.claude` by default instead of inheriting
|
|
197
|
+
session-specific `CODEX_HOME` or `CLAUDE_CONFIG_DIR` values. Advanced users can
|
|
198
|
+
override these with `CC_PETS_CODEX_HOME` and `CC_PETS_CLAUDE_CONFIG_DIR`.
|
|
199
|
+
|
|
200
|
+
Local seven-day quota history is disabled by default. When enabled, it is stored
|
|
201
|
+
only at `~/Library/Application Support/CC Pets/quota-history.json`, retains seven
|
|
202
|
+
days, and records at most once every 15 minutes.
|
|
203
|
+
|
|
204
|
+
## Speech
|
|
205
|
+
|
|
206
|
+
The pet's speech comes from `~/.cc-pets/speech.txt`. Open **Speech → Edit lines…**
|
|
207
|
+
in the right-click menu to edit, validate, preview, or restore it. Lines are grouped
|
|
208
|
+
under stable situation tags such as `[idle]`, `[done]`, and `[state_thinking]`.
|
|
209
|
+
Each spoken line is limited to 30 characters in the current UI.
|
|
210
|
+
|
|
211
|
+
Supported live placeholders are `{quota5h}`, `{resetTime}`, `{toolName}`,
|
|
212
|
+
`{sessionMin}`, `{failCount}`, and `{hour}`. A line is skipped if one of its values
|
|
213
|
+
is unavailable.
|
|
214
|
+
|
|
215
|
+
Per-pet overrides live at `~/.cc-pets/speech/<pet-name>.txt` (the built-in asset
|
|
216
|
+
uses `builtin-默认.txt`). A missing section falls back to global speech; a present
|
|
217
|
+
section replaces that global section; an empty present section keeps the pet silent
|
|
218
|
+
for that situation.
|
|
219
|
+
|
|
220
|
+
The four speech-frequency presets coordinate an hourly budget, cooldown, idle
|
|
221
|
+
threshold, and probability. Speech stays silent while an agent is actively working.
|
|
222
|
+
Advanced debugging values use the existing app preferences domain:
|
|
490
223
|
|
|
491
224
|
```bash
|
|
492
|
-
cc-pets
|
|
493
|
-
cc-pets
|
|
494
|
-
cc-pets
|
|
495
|
-
cc-pets
|
|
496
|
-
cc-pets
|
|
497
|
-
cc-pets
|
|
498
|
-
cc-pets pet dir # 打印素材目录路径
|
|
225
|
+
defaults write com.universewang.cc-pets CCPetsSpeechFrequency -string chatty
|
|
226
|
+
defaults write com.universewang.cc-pets CCPetsSpeechCooldown -float 0
|
|
227
|
+
defaults write com.universewang.cc-pets CCPetsSpeechHourlyBudget -int 100
|
|
228
|
+
defaults write com.universewang.cc-pets CCPetsBoredomScale -float 0.1
|
|
229
|
+
defaults write com.universewang.cc-pets CCPetsSpeechDebugTag -string quota_low
|
|
230
|
+
defaults delete com.universewang.cc-pets CCPetsSpeechCooldown
|
|
499
231
|
```
|
|
500
232
|
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
素材来自「源」(source),当前内置 [PetDex](https://petdex.dev)(默认)。名称可以带源前缀,
|
|
504
|
-
不带就用默认源:
|
|
505
|
-
|
|
506
|
-
```bash
|
|
507
|
-
cc-pets pet add petdex:boba
|
|
508
|
-
cc-pets pet search petdex:otter
|
|
509
|
-
```
|
|
233
|
+
`com.universewang.cc-pets` is the existing technical bundle/preferences identifier.
|
|
510
234
|
|
|
511
|
-
|
|
512
|
-
`scripts/pet-store.mjs` 顶部的 `SOURCES` 表里。以后接自建 registry 时在表里加一行即可,
|
|
513
|
-
命令、目录结构和桌宠端都不用改。默认源用 `CC_PETS_SOURCE` 切换。
|
|
235
|
+
## Pet assets
|
|
514
236
|
|
|
515
|
-
|
|
516
|
-
`
|
|
517
|
-
|
|
237
|
+
This project does not operate an asset registry. The repository and npm package
|
|
238
|
+
contain one original built-in asset, ByteMochi (`默认.webp`), distributed under the
|
|
239
|
+
MIT License. All other assets are downloaded by the user to
|
|
240
|
+
`~/.cc-pets/pets/<name>/` and are not part of this repository or npm package.
|
|
518
241
|
|
|
519
|
-
|
|
520
|
-
|
|
242
|
+
The `cc-pets pet` command consumes PetDex's public manifest at
|
|
243
|
+
`https://petdex.dev/api/manifest` and accepts downloads only from allowlisted
|
|
244
|
+
`assets.petdex.dev` URLs. CC Pets downloads and renders those files locally; their
|
|
245
|
+
licenses, copyrights, and terms remain with their respective authors and platforms.
|
|
521
246
|
|
|
522
247
|
```bash
|
|
248
|
+
cc-pets pet search otter
|
|
249
|
+
cc-pets pet add boba doraemon
|
|
523
250
|
cc-pets pet add petdex:boba --as boba-petdex
|
|
524
|
-
cc-pets pet
|
|
251
|
+
cc-pets pet list
|
|
252
|
+
cc-pets pet remove boba
|
|
253
|
+
cc-pets pet source
|
|
254
|
+
cc-pets pet dir
|
|
525
255
|
```
|
|
526
256
|
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
#### 导入 Codex 素材
|
|
532
|
-
|
|
533
|
-
桌宠不读 `~/.codex/pets/`。如果你在 Codex 桌面端已经装了一批素材,打开右键菜单里的
|
|
534
|
-
**“导入 Codex 素材”** 开关,桌宠会把那里的素材**复制**进 `~/.cc-pets/pets/`:开关打开的
|
|
535
|
-
当下导入一次,之后每次启动再导入一次。
|
|
536
|
-
|
|
537
|
-
- 复制而不是关联:导入之后 Codex 那边再改再删都不影响桌宠,桌宠也仍然只需要扫一个目录。
|
|
538
|
-
- 只导入真正有精灵图的目录,没有 `spritesheet.webp` / `spritesheet.png` 的会跳过。
|
|
539
|
-
- **同名目录一律跳过、绝不覆盖**——你自己 `cc-pets pet add` 装的素材优先。
|
|
540
|
-
- 导入的素材会写上 `.source.json`(`source: "codex"`),`cc-pets pet list` 里单独分一组。
|
|
541
|
-
|
|
542
|
-
反复启动是幂等的:已经导入过的素材因为同名而跳过,不会重复复制。关掉开关不会删除已经
|
|
543
|
-
导入的素材,想删用 `cc-pets pet remove`。
|
|
257
|
+
The source and installation record is stored separately in `.source.json`; upstream
|
|
258
|
+
`pet.json` remains unchanged. A conflicting local name is never overwritten. The
|
|
259
|
+
`--as` option accepts localized names but rejects path separators, whitespace, and
|
|
260
|
+
consecutive `..` sequences.
|
|
544
261
|
|
|
545
|
-
|
|
262
|
+
### Importing Codex assets
|
|
546
263
|
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
的限制一致。
|
|
264
|
+
CC Pets never renders directly from `~/.codex/pets/`. Enable **Import Codex pets**
|
|
265
|
+
to copy assets containing `spritesheet.webp` or `spritesheet.png` into
|
|
266
|
+
`~/.cc-pets/pets/`. Existing names are skipped, imports are idempotent, and disabling
|
|
267
|
+
the option does not delete previously copied files.
|
|
552
268
|
|
|
553
|
-
|
|
554
|
-
`
|
|
555
|
-
归到「本地素材(无来源记录)」下。
|
|
269
|
+
PetDex's own CLI installs to `~/.petdex/pets/`, which CC Pets does not scan. Use
|
|
270
|
+
`cc-pets pet add` when you want an asset installed into CC Pets' own directory.
|
|
556
271
|
|
|
557
|
-
|
|
558
|
-
|
|
272
|
+
Set `CC_PETS_PETS_DIR` to use another asset directory. Apps started through `open`
|
|
273
|
+
do not inherit shell variables; use `cc-pets --foreground` or `launchctl setenv` if
|
|
274
|
+
the native app also needs the override.
|
|
559
275
|
|
|
560
|
-
|
|
561
|
-
|
|
276
|
+
See [Third-party notices](./THIRD_PARTY_NOTICES.md) before using or redistributing
|
|
277
|
+
external assets.
|
|
562
278
|
|
|
563
|
-
##
|
|
279
|
+
## Privacy
|
|
564
280
|
|
|
565
|
-
-
|
|
566
|
-
-
|
|
567
|
-
-
|
|
568
|
-
-
|
|
569
|
-
-
|
|
570
|
-
-
|
|
571
|
-
- 右键“退出桌宠”或执行 `cc-pets uninstall` 后,不会继续运行后台守护进程。
|
|
281
|
+
- Quota and token data are read from local Codex and Claude Code files.
|
|
282
|
+
- Hooks write only redacted state events and quota cache files to the current user's temporary directory.
|
|
283
|
+
- Local quota history is disabled by default and retains seven days when enabled.
|
|
284
|
+
- Status cards and notifications show only provider, state, and redacted tool category.
|
|
285
|
+
- CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
|
|
286
|
+
- Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
|
|
572
287
|
|
|
573
|
-
##
|
|
288
|
+
## Uninstall
|
|
574
289
|
|
|
575
|
-
|
|
290
|
+
Remove integrations while the npm package is still installed:
|
|
576
291
|
|
|
577
292
|
```bash
|
|
578
293
|
cc-pets uninstall
|
|
@@ -581,15 +296,18 @@ source ~/.zshrc
|
|
|
581
296
|
npm uninstall -g cc-pets
|
|
582
297
|
```
|
|
583
298
|
|
|
584
|
-
|
|
585
|
-
|
|
299
|
+
The uninstaller removes only CC Pets-marked hooks, shell configuration, and shims,
|
|
300
|
+
and restores the previous Claude status line. Other user settings and hooks remain.
|
|
586
301
|
|
|
587
|
-
##
|
|
302
|
+
## Project status and trademarks
|
|
588
303
|
|
|
589
|
-
CC Pets
|
|
590
|
-
|
|
304
|
+
CC Pets is a community open-source project with no affiliation, authorization, or
|
|
305
|
+
official partnership with OpenAI, Anthropic, PetDex, or any character rights holder.
|
|
306
|
+
Codex, ChatGPT, Claude, their icons, and their trademarks belong to their respective
|
|
307
|
+
owners.
|
|
591
308
|
|
|
592
309
|
## License
|
|
593
310
|
|
|
594
|
-
|
|
595
|
-
|
|
311
|
+
The code and the original ByteMochi built-in asset use the [MIT License](./LICENSE).
|
|
312
|
+
External assets do not automatically receive this project's license. See
|
|
313
|
+
[Third-party notices](./THIRD_PARTY_NOTICES.md).
|