cc-pets 1.4.8 → 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 CHANGED
@@ -1,302 +1,63 @@
1
- # 更新记录
1
+ # Changelog
2
2
 
3
- 本项目遵循语义化版本号。
3
+ English | [简体中文](./CHANGELOG.zh-CN.md)
4
4
 
5
- ## [Unreleased]
5
+ This project follows Semantic Versioning. `package.json` is the single source of
6
+ truth for the version.
6
7
 
7
- - 修复长期续写同一个会话的用户,面板上 Codex 的「今日 / 最近 7 天」Token 恒为 0。
8
- `codex resume` 会一直往**建会话那天**的目录里追加,实测有用户近 8 天的全部 `token_count`
9
- 都写在 15 天前的 `sessions/2026/08/06/` 下。此前候选文件按 `YYYY/MM/DD` 目录名剪枝,
10
- 扫到过期目录就整个收手,这个仍在被写的文件一次都没被打开过——而额度百分比走的是另一条
11
- 按 mtime 找文件的路径,照常显示,于是现象是"额度有、Token 是 0",很难往这里想。
12
- - 窗口之前的日期目录不再收手,改成继续扫、只收 **mtime** 落在窗口内的文件;连续 60 个
13
- 这样的目录都没捞到活跃文件才停,成本上界与历史长度无关(本机 47 个日期目录实测
14
- `--status` 耗时无变化)。天数上限用完时同样降级成 mtime 过滤而不是 `return`,
15
- 否则上限之外那个正在续写的旧会话又会被切掉一次。
16
- - 判据是 mtime 而不是文件里的时间戳:回填或伪造的时间戳不该把三个月前的会话拉回今天。
17
- 两条测试互为对照——事件时间戳新但 mtime 老的不计入,目录老但 mtime 新的必须计入。
18
- - 当前正在增量读取的会话、以及 FSEvents 这一轮点名的并发会话,一律无条件参与聚合。
19
- 内核已经确认它们刚被写过,这个结论比任何按路径名或 mtime 的推断都可靠。此前额度竞选
20
- 落选的会话直接被丢掉,可它们同样带着新的 `token_count`。
21
- - 月度归档带上 schema 版本号:旧口径归出来的档本身缺数,且一旦落盘就不再重算,
22
- 换了扫描方式也不会自愈,因此版本对不上就整份丢掉重算一次。
23
- - 顺带修好了额度兜底路径 `LatestQuotaInRecentSessions`:它共用同一份候选列表,此前
24
- 在这类机器上同样看不见活跃会话,只是碰巧没被触发。
8
+ ## [2.0.1] - 2026-09-07
25
9
 
26
- - 台词可以按宠物分别配置了。`~/.cc-pets/speech.txt` 仍是所有宠物的通用台词,某一只想换
27
- 口吻时在 `~/.cc-pets/speech/<宠物名>.txt` 里**只写想改的小节**,没写的照旧走通用。
28
- 台词编辑器顶部多了「通用 / 当前宠物」的切换,切换宠物时自动跟随。
29
- - 回落按**小节整体**做,不按行合并:专属写了 `[idle]` 就只说专属那几句,通用那一节
30
- 一句都不参与。按行合并的话,用户没有任何写法能表达"这只宠物这句话不要说"。
31
- - 判据是"这一节在不在"而不是"有没有内容":专属里写了标签却不写台词,表示这只宠物在
32
- 这个情境闭嘴。当成"空的等于没写"去回落的话,这个意图就再也写不出来了。
33
- - 专属词库的校验规则单独一套:缺小节是常态(缺就回落),所以"标签不能删"和
34
- "`[state_*]` 至少留一句"都不适用。套通用规则的话,用户想改一句话得先抄一整份
35
- 22 节的文件过来。同理,保存时不给专属文件补标签——补完之后每一节都"存在",
36
- 这只宠物就再也不会回落了。
37
- - 专属页右上角有「填入出厂模板」,解决空白页无从下手。填进来的是整份**注释状态**的
38
- 出厂台词:用户看得见每一节能写什么,而注释一行都不算数,所以填完之后仍然全部回落到
39
- 通用,想让哪一节归这只宠物管就去掉那一节的 `#`。直接填未注释的完整出厂台词是错的——
40
- 那样 22 节全被接管,再也不会回落;只填小节头的空骨架更糟,等于这只宠物全情境闭嘴。
41
- - 专属文件懒创建,不预先给每只宠物生成空文件:空文件和没有文件语义完全一样,
42
- 凭空造一堆只会让目录全是噪音。删掉宠物素材也不删它的台词文件,装回来还在。
10
+ Bug fixes for quota display and panel stability.
43
11
 
44
- - 修复台词编辑器里 ⌘C/⌘V/⌘X/⌘A/⌘Z/⌘⇧Z 全部没反应。这些快捷键不是 `NSTextView` 自己
45
- 处理的:按键先走 `NSApp.mainMenu` 的 `performKeyEquivalent:`,命中菜单项之后才沿响应者链
46
- 发 `copy:` / `paste:` 这些消息。这个 app 是 `LSUIElement`,此前从没设过主菜单,所以全部
47
- 落空。现在装一个只有「编辑」的主菜单——`LSUIElement` 按定义不显示自己的菜单栏,它只是
48
- 一张快捷键路由表,用户看不见。菜单项的 target 一律留空交给响应者链,以后新加的文本框
49
- 自动就有这些快捷键。
50
- - 修复 `npm install` 失败:`package.json` 的 `files` 白名单逐个列 `Resources/` 下的文件,
51
- 新增的 `Resources/phrases.default.txt` 没进去,发布包里没有这个文件,`build.sh` 拷贝那一步
52
- 直接失败。本地从工作树构建看不出来,所以给发布包完整性测试补上了资源文件这一档。
12
+ ### Quota and usage
53
13
 
54
- - 用户词库改名 `~/.cc-pets/phrases.txt` → `~/.cc-pets/speech.txt`。换名字是为了让"迁移过
55
- 没有"变成一个平凡的判断(新文件在就是迁移过了)——靠猜内容特征(有没有 replace 行、
56
- 缺不缺某个小节)都不可靠,用户改过之后更没法判断。
57
- - 老词库在**启动时**就自动合并进新文件,不等用户打开编辑器:拖到那时候再迁移的话,
58
- 从升级到他第一次点"编辑台词"这段时间,桌宠说的会是出厂台词而不是他自己写的,
59
- 而没人会把这件事和"我该去点一下编辑台词"联系起来。合并规则是"出厂 + 用户"取并集,
60
- 因为老语义就是两者混着说;老文件里写过 `replace` 的,他写过的那几节按他的来,
61
- 没写过的仍旧用出厂内容(照搬老语义会让 15 个 `state_` 小节全空,而新版没有兜底文案,
62
- 状态卡副行会直接残掉)。老文件里的注释一概不搬,按新模板的来。
63
- - 老文件合并后先留着,第一次打开编辑器时问一次要不要改名成 `phrases.txt.bak` 收起来——
64
- 合并是我们替用户做的,动他的文件得他自己点头。改名而不是删除:内容还在原地,万一合并
65
- 合错了还能翻出来对;而 `PetPhrasesLegacyFilePath` 只认 `phrases.txt`,改完名它既不会
66
- 再被当成迁移源,也不会再弹询问。留着原名不动有两个坑:改它不会有任何效果,而且哪天
67
- `speech.txt` 丢了,启动时会再从它合并一遍,把用户迁移之后写的台词全冲掉。
68
- - 台词改成"文件即全部":删掉代码里的内置词库,默认台词变成随 app 打包的
69
- `Resources/phrases.default.txt`,首次启动拷到 `~/.cc-pets/phrases.txt`,之后运行时
70
- 只认这个文件。同时删掉 merge / `replace` 两种模式——运行期同时存在两份词库就必然
71
- 要回答"以谁为准",而那正是原来那套配置让人看不懂的根源。现在删掉一节就是那个情境
72
- 不吭声,用户看到的文件就是桌宠的全部台词。
73
- - 台词编辑从「交给系统文本编辑器」换成 app 内置编辑器。原来那条路没有任何反馈:
74
- 小节名拼错、句子超 30 字、槽位写错名字全是静默失效,用户只知道"改了没用"。
75
- - 标签行被删掉时,保存会自动把它加回原位并告知补了哪些(⌘Z 可撤销)。光报错等于把人
76
- 卡死:编辑器里已经看不到那一行,用户既不知道少的是哪个,也不知道该写成什么样,
77
- 只能翻文档或者点"恢复出厂"把自己的改动全丢掉。标签被删而台词还在时,那串台词会并进
78
- 上一节,所以标签要插回那串台词**前面**才能带着它们一起归位;标签连着台词一起删掉的
79
- 情况下只补标签,不能顺手把上一节的台词抢过来。
80
- - 保存时校验并当场列出问题。标签行是配置项,22 个一个都不能删;
81
- 能不能留空才分两种——`[state_*]` 是状态卡副行的唯一正文来源,空了也拦,情绪句留空
82
- 只提示(就是那个情境不主动开口)。"整行被删"和"还在但空了"分开报,因为要做的动作
83
- 不一样:一个是把 `[标签]` 那行加回来,一个是补句台词。槽位名拼错也会报——这类最难自查。
84
- - 连续的"不在任何 [情境] 下面"的散句合并成一条提示。删掉一个小节头会让它下面整串台词
85
- 变成散句,逐行报的话十几条提示会把真正该看的那条错误挤下去。
86
- - 编辑器的保存分成「保存」(⌘S)和「保存并关闭」(⏎)。⌘S 而不是回车是因为这是多行
87
- 文本编辑器,回车要用来换行。校验没过或 mtime 冲突被取消时不关窗,避免改动跟着窗口一起没。
88
- - 编辑器新增「试说一句」:选一个情境,桌宠当场说出来。读的是还没保存的文本,槽位用
89
- 示例数据填,不用等真的额度告急才能看到效果。另有「恢复出厂台词…」(可 ⌘Z 撤销)。
90
- - 保存前比对 mtime,文件被外部改过时问一次,可选覆盖或重新载入,不静默吃掉别人的改动。
91
- - 状态卡副行没有内容时收成单行,不再留一块空白——代码里已经没有兜底文案了,
92
- 外部编辑器清空某个 `state_` 小节时显示层必须自己站得住。
14
+ - Read live Codex quota windows from the Codex App Server and overlay them on locally aggregated token usage, with a persistent background connection that handles refresh, notifications, timeouts, and fallback.
15
+ - Fix Codex quota not showing again after a quota reset: expired session quota windows are now discarded independently, and exhaustion state is preserved correctly across resets.
16
+ - Show a pending refresh state when official quota data is not yet available.
93
17
 
94
- - 碎碎念不再受"agent 是否在线"影响。原来的闸门是"状态卡可见就闭嘴",而状态卡只要客户端
95
- 活着就常驻,等于开着终端就永远不会碎碎念——独立气泡那条路径实际上从来没跑到过。
96
- 改成按"agent 在不在干活"判断:只有状态卡处于 idle 或根本没显示时才说话,thinking /
97
- tool / approval / notification / completed / failed 的工作文案优先级最高,闲话一律让路。
98
- - 碎碎念借走状态卡副行说完一句后会自动还原状态文案(`restoreStatusDetail`),此前借走就
99
- 不还,副行会一直挂着上一句闲话;同时不再用闲话覆盖 `lastPetVoiceText`,那是状态文案的
100
- 去重缓存,被污染后下一次同状态事件会把闲话当成该状态的文案复读出来。
101
- - 右键菜单「碎碎念」新增频率四档(很少 / 正常 / 较多 / 话痨)。每小时预算、两句间隔、
102
- 静默门槛、出话概率这四道闸互相牵制,单调任何一道都不会真的变频繁,所以只对用户暴露
103
- 一个档位、四个值一起走;正常档即改造前的原值。`CCPetsSpeechCooldown` 与
104
- `CCPetsSpeechHourlyBudget` 保留为更细的手动覆盖,写了就压过档位。
105
- - README 补齐「碎碎念」一节:频率档位表、`phrases.txt` 写法、槽位与情境标签契约、
106
- 调试用的 `defaults` 键(含域名必须是 bundle identifier 这一点)。
18
+ ### Pet and interaction
107
19
 
108
- ## [1.3.2] - 2026-08-19
109
- ### 桌宠活物感改造
20
+ - Fix the panel occasionally failing to show.
21
+ - Unify pet speech to first person: the pet now speaks as the agent instead of narrating it from the outside.
110
22
 
111
- - 渲染层从 `drawRect:` 改为 layer-backed,精灵内容挂在独立的 `CALayer` 上,为呼吸和拖动
112
- 物理让路——这两样必须走 Core Animation:插值和合成都在 render server 侧,主进程零唤醒;
113
- 若走 `drawRect:`,呼吸要平滑就得约 20fps,而动画定时器原本才 4.5 次/秒,一项就能把
114
- 常驻开销全部吐回去。为此新增 `--render-pet` 逐格渲染 PetView 并逐字节比对(原有三个
115
- `--render-*` 一格宠物都不画,改坏 PetView 它们照样全绿)。改造过程中它抓到两次
116
- 等价性破坏:素材经 `LoadPetSpriteImage` 缩略后未必能被行列整除(默认素材单格高
117
- 151.67px),`CGImageCreateWithImageInRect` 预裁会把小数矩形取整、`contentsRect` 交给
118
- CA 缩放也有自己的采样相位,两者都和原来的 `drawInRect:fromRect:` 对不上,边缘整行错位。
119
- 最终照搬原绘制调用按格预栅格化并缓存,9 行与 11 行素材均逐字节一致。
120
- - 屏幕睡眠时一并冻结 layer 时间轴并清空栅格化缓存。停表只管得住 `NSTimer` 驱动的逐帧
121
- 动画,CA 动画的时钟在 render server 那边,屏幕睡了照跑。
122
- - 待机加入呼吸(1.5px 上浮,`reduceMotion` 下不启用)。只向上不做对称摆动:宠物视图在
123
- 230×170 窗口里位于 (43,0,144,150),下方没有余量,往下 1px 就被窗口裁掉。
124
- - 拖动加入水平滞后与落脚 squash。拖动由窗口服务器接管、拿不到连续事件,改从
125
- `NSWindowDidMoveNotification` 取位移。只做水平方向:左右各有 43px 余量,垂直方向下方是 0。
126
- - 待机微动层:每 8~25 秒(泊松随机)做一个有始有终的小动作。11 行素材按角度顺序连播
127
- row 9/10 的朝向格,等于白捡一个转头动画——那 16 格本是静止姿势,连起来就是转头,不需要
128
- 任何新素材;9 行素材退到 row 3 张望。**不再改待机循环本身的节奏**:随机长停某一帧和整轮
129
- 变速都试过,素材不受控(第 0 帧不保证是自然站姿),一律被读成"动画卡住了"。
130
- - 内在状态:无聊曲线(闲置 2/10/30 分钟三档,微动频率先升后降)、生理余韵(agent 事件累积
131
- 用力值,25 秒半衰期,呼吸分三档快慢)、注意力惯性(鼠标移动 88% 被忽略,被吸引后 3~8 秒
132
- 失去兴趣,再冷却 4~12 秒)。注意力惯性顺带把绕宠物移动鼠标时的开销压了下来。
133
- - 无聊曲线的计时基准是真实事件流而不是 `agentActive`:`mouseDown:` 会无条件清掉后者,
134
- 用户随手点一下宠物就会让曲线误启动。上次交互时间落盘,隔几小时再开机从"打盹"档开始。
135
- - 素材能力(是否有十六向朝向行)在换素材时算一次,微动改为按能力过滤的数据表;行数判断从
136
- 四处收敛到一处,两档行为密度保持一致,切换素材应读作"性格不同"而非"功能残缺"。
23
+ ## [2.0.0] - 2026-08-23
137
24
 
138
- ### 状态卡改由宠物口吻叙述
25
+ First open-source release.
139
26
 
140
- - 每个 hook 状态的副行文案改为宠物口吻,从台词库随机取、带最近使用抑制,同一状态每次读到的
141
- 不一样。原来"正在调用工具…"一句覆盖四类工具,现在执行命令/编辑文件/查找资料/子 Agent
142
- 各说各的,信息量反而更大。取不到台词时回落原系统文案。
143
- - 排版层级反转:事实降为眉标(11pt Medium 浅灰),宠物的话升为正文(14pt Medium 深色)。
144
- - 状态卡与说话气泡按文案长度伸缩,不再是固定宽度。宽度用控件自身的 `fittingSize` 量——
145
- 按字符串量的 `sizeWithAttributes:` 比 `NSTextField` 真正需要的窄几个点,会让"刚好够"
146
- 变成省略号。
147
- - 新增"碎碎念":额度告急、连续失败、深夜、久坐、久别重逢等时刻主动说一句。每小时上限 4 句
148
- 且两句间隔至少 4 分钟——状态播报不受此限,那是替换样板文案而非额外说话。有状态卡时话并入
149
- 它的副行,没有才起独立气泡,同一时刻屏幕上只有一个东西在说话。
150
- - 额度台词按档位下穿触发(20%/10%/5%),不是"低于阈值就一直说";额度是分钟级刷新的,
151
- 不设档一小时预算瞬间烧光。回血后档位回升,下个周期才能再触发。
27
+ ### Pet and interaction
152
28
 
153
- ### 自定义台词
29
+ - Native macOS AppKit desktop pet with no Electron runtime and no dependency on the Codex or Claude desktop apps.
30
+ - Idle breathing, random movements, drag lag and landing bounce, plus hover and click feedback for the head, pocket, feet, and both body sides.
31
+ - The right-click menu can switch pets, refresh usage, toggle quota history and system notifications, check for updates, or exit.
32
+ - Supports built-in assets and external assets under `~/.cc-pets/pets/`, with `spriteVersionNumber` v1 and v2 grids.
154
33
 
155
- - 支持 `~/.cc-pets/phrases.txt` 自定义台词,右键菜单"碎碎念 → 自定义台词…"生成模板并打开。
156
- 模板写满中文说明与逐条示例,取消注释即生效。
157
- - 格式是纯文本而非 JSON:普通用户写不了 JSON,且少个逗号就整个文件失效、我们静默回落内置,
158
- 用户只会觉得"改了没用"。纯文本逐行解析,写错只丢那一行。
159
- - 用户台词永远按数据处理,绝不交给 `stringWithFormat:`——一个 `%@` 就会让桌宠当场崩溃。
160
- 测试里有断言守着这条,以及行尾注释剥离、超长条目丢弃、槽位缺值时整条作废(宁可不说,
161
- 也不吐出带花括号的半成品)。
34
+ ### Quota and usage
162
35
 
163
- ### 已知未完成
36
+ - Reads five-hour quota, weekly quota, and reset times from local `~/.codex/sessions` data and Claude Code's official status line input.
37
+ - Hovering over the pocket opens a panel with separate Codex and Claude cards for remaining percentage, local tokens, and seven-day trends.
38
+ - Optionally records seven days of local quota history; disabled by default and stored only on the local machine.
39
+ - Supports Subscription quota and API usage display modes.
164
40
 
165
- - README 尚未记录台词文件、情境标签契约与调试用的 defaults 键。
166
- - 呼吸、微动、拖动物理没有总开关(碎碎念有)。
167
- - 常驻内存较改造前上升,栅格化缓存上限已从 48 格降到 20 格并在息屏时清空,实际效果待复测。
41
+ ### Agent status
168
42
 
169
- ## [1.3.2] - 2026-08-17
170
- - 优化“切换桌宠”子菜单:素材名称按 5 个中文字符的视觉宽度展示,超出后追加 `...`;外部素材增加
171
- 垃圾桶删除入口,首次点击后原位置变为红字“确认”,再次点击才执行删除。切换或删除素材时
172
- 子菜单保持展开,并立即更新当前项勾选和删除状态;内置素材及当前已应用素材不显示删除图标。
43
+ - Codex Hooks and Claude Code Hooks drive animations for thinking, tool calls, approvals, subagents, completion, and failure.
44
+ - Displays a redacted glass status card beside the pet, which can be collapsed and shows the active CLI session count.
45
+ - macOS notifications can be enabled separately for completion, failure, and approval requests.
46
+ - Third-party CLI agents can integrate through the unified Provider event protocol; see [`PROVIDER_PROTOCOL.md`](./PROVIDER_PROTOCOL.md).
173
47
 
174
- ## [1.3.1] - 2026-08-17
175
- - 修复长期使用后桌宠崩溃、且此后每次启动都在 0.2 秒内再崩(表现为"打不开了"):Claude
176
- Token 摘要缓存落盘后,下次启动读回时会对同一块缓冲区继续追加新记录,而判断它可不可变
177
- 用的是 `isKindOfClass:NSMutableData`——`NSData` 是类簇,二进制 plist 解析出来的**不可变**
178
- `__NSCFData` 对这个判断同样返回 YES。于是只读缓冲区被当成可变的原地 `appendBytes`,
179
- 每条记录写出界 48 字节(ASan:`heap-buffer-overflow`,`0 bytes after 6640-byte region`,
180
- 分配点在 `__CFBinaryPlistCreateObjectFiltered`)。越界写破坏的是堆元数据,进程不会当场
181
- 死,而是在之后任意一次内存分配上倒下,所以三份崩溃报告的落点(`EnumerateLines`、
182
- `SaveTokenSummaryCache`)和真正的写入点毫无关系,只是先撞上的受害者。
183
- 触发要同时满足"缓存已落盘、重启后读回、该会话文件之后又变长",因此新装的机器碰不到,
184
- 攒够会话的老用户则一旦中招每次启动必崩。改为缓存一读回来就把记录换成本进程创建的可变
185
- 副本,只替换记录本身、其余字段原样保留(Codex 侧条目形状不同,整条重建会抹掉
186
- `start`/`total`/`segments`/`days`);追加处那个失效的可变性判断一并删除,避免再写回去。
187
- - `cc-pets --clean` 补上 Token 摘要缓存(`*-token-cache-*.plist`、`*-monthly-usage-*.plist`
188
- 及落盘中断留下的 `.tmp`)。它同样只是缓存,丢了只意味着重新解析一遍会话文件,原先却漏在
189
- 清理之外,于是缓存一旦出问题,`clean` 救不回来,只能让用户手动删文件。
190
- ## [1.3.0] - 2026-08-12
191
- - 修复面板上的剩余额度来回跳(实测 Claude 5 小时窗口 99% → 94% → 又回 99%):多个会话的
192
- status line 各写各的额度快照到同一个文件,而"响应更早、落盘更晚"在并发下完全正常,
193
- 无条件覆盖会让旧快照盖掉新快照。改为逐窗口按"同一 `resets_at` 内用量只增不减"取舍,
194
- 窗口滚动(`resets_at` 变大)时无条件接受,某个窗口超过 10 分钟没有被接受过时也放行,
195
- 免得官方口径调整(例如临时提额)后面板被钉死——这个逃生阀按窗口各记各的接受时刻,
196
- 被拒绝的快照不会把它续期,否则只要还有会话在持续上报就永远到不了。读改写全程用独立
197
- 锁文件加 `flock` 串行化,数据文件仍由 rename 整体替换;加锁是非阻塞加有限重试,拿不到
198
- 就放弃这次采样,免得一个卡死的写者把之后每一次 status line 渲染永久挂住。响应缺某个
199
- 窗口时保留旧值,不再整块覆盖。
200
- Codex 侧同一问题一并修,判据统一成"按额度采样时刻取最新":兜底扫描近期会话时不再按
201
- 文件 mtime 命中即返回;一批文件事件里有多个会话同时变更时,也不再取遍历到的最后一个,
202
- 而是读各自的尾巴比采样时刻(会话拿到额度后还会追加别的行,mtime 顺序和采样顺序并不
203
- 一致)。内核已经点名变更文件的路径不再重跑基于 mtime 的会话发现,否则刚选中的结果会
204
- 立刻被推翻。`cc-pets --clean` / 完整卸载会一并删除额度写锁;7 天启动清理刻意放过它,
205
- 锁文件 mtime 创建后不再更新,删掉一个正被持有的锁会让互斥失效。
206
- - 修复敲 `Claude` / `Codex`(任意非全小写写法)时桌宠不启动:shell 集成从 alias 改为
207
- `~/.cc-pets/shims` 下的软链加 `PATH` 前置。alias 名区分大小写,而 macOS 文件系统默认
208
- 不区分,`Claude` 匹配不到 alias 就直接命中真二进制,绕过了包装脚本。shim 靠文件系统
209
- 自身的大小写不敏感覆盖全部写法。包装脚本随之不再用 `whence -p` 找真二进制(会先命中
210
- shim 自己导致无限 `exec`),改为遍历候选并跳过 shim。升级会自动把旧 alias 段迁移成
211
- shim 段,卸载会一并删除软链和目录。
212
- - 新增 `cc-pets pet` 素材管理命令(`search` / `add` / `list` / `remove` / `source` / `dir`),
213
- 把素材下载到 cc-pets 自己的目录 `~/.cc-pets/pets/`,不再写 `~/.petdex/pets/` 和
214
- `~/.codex/pets/`。两端都认 `CC_PETS_PETS_DIR` 覆盖。
215
- - 桌宠端只扫 `~/.cc-pets/pets/` 和包内素材,无条件不再读 `~/.petdex/pets/` 和
216
- `~/.codex/pets/`——那两个目录由别的工具写入,混在一起就挑不出自己装的宠物。
217
- - 新增“导入 Codex 素材”开关(右键菜单,默认关):打开时立即把 `~/.codex/pets/` 里
218
- 有精灵图的素材**复制**进自己的目录,之后每次启动再导入一次。复制而非关联,Codex
219
- 那边的后续改动不影响桌宠;同名目录一律跳过不覆盖,自己装的素材优先;导入的素材写
220
- `.source.json`(`source: "codex"`),`cc-pets pet list` 里单独分组。重复导入是幂等的。
221
- - 素材列表改为启动时加载一次,之后按素材目录的 mtime 判断是否重扫。`add` / `remove`
222
- 会改动目录因而立即生效,没有增删时打开右键菜单只做一次 `stat`,不再每次遍历目录。
223
- - 素材来源抽象成「源」:`SOURCES` 表里一行就是一个源(清单地址、资源 host 白名单、
224
- Referer),当前内置 PetDex,名称支持 `petdex:boba` 这样的源前缀,默认源用
225
- `CC_PETS_SOURCE` 切换。这样以后接自建 registry 不用动命令面和目录结构。
226
- 清单按源分别缓存 6 小时,下载只接受源白名单内的 host。
227
- - 素材来源记在宠物目录内的 `.source.json`,目录名保持素材本名,桌宠菜单不受影响;
228
- `list` 按来源分组。跨源同名或覆盖手放素材时 `add` 会拒绝并提示用 `--as` 改名安装,
229
- 同源重装则直接更新。
230
- - 新增 Codex 与 Claude Code 本地 Token 用量统计,按官方重置时间对齐 5 小时与 7 天窗口;
231
- Claude 侧按 `message.id + requestId` 去重,避免 `--resume`/fork 复制的记录重复计数。
232
- 官方订阅额度仍以服务端百分比为准。
233
- - Token 聚合改为增量跟读并按额度窗口节流,事件驱动的高频刷新不再重复扫描近 7 天会话;
234
- 过期日期目录按目录名剪枝,无 Token 数据的会话文件缓存失败结果不再反复重读。
235
- - 新开 Codex 会话时不再因为尚无 `rate_limits` 而清空面板上已知的额度。
236
- - 修正跨窗口 Codex 会话的 Token 高估:Codex 会把同一份 `token_count` 重复写进会话
237
- (实测近 7 天 68 个会话里 14 个存在重复,累加值整体偏高约 1%,最差的单个会话偏高
238
- 7.7%),窗口内那一段改为按 `total_token_usage` 求差,累计值对重复事件是幂等的。
239
- - 桌宠端不再跟随继承来的 `CODEX_HOME`,与 `CLAUDE_CONFIG_DIR` 的处理对齐:常驻进程会一直
240
- 带着启动时的环境,用它选目录等于永久绑定到第一个拉起桌宠的那份 Codex 配置。需要时用
241
- `CC_PETS_CODEX_HOME` 覆盖;跑在会话里的记录端仍认 `CODEX_HOME`。
242
- - 修复存在多个 Claude 配置目录时统计错账号:桌宠是被客户端启动的常驻进程,会一直带着
243
- 启动时的 `CLAUDE_CONFIG_DIR`,等于永久绑定到"第一个拉起它的账号"。现固定只统计
244
- `~/.claude`(可用 `CC_PETS_CLAUDE_CONFIG_DIR` 覆盖),包装脚本启动桌宠时也不再透传该
245
- 变量。额度文件改为按配置目录分开存放,多个配置目录的 status line 不再互相覆盖——此前
246
- 面板可能把一个账号的剩余百分比配上另一个账号的用量。
247
- - 应用内更新遇到暂时性故障时自动重试一次,不再直接弹"更新失败"。刚发布的版本存在
248
- registry 传播竞态:`/latest` 已经报出新版本,而同一时刻 `npm install cc-pets@<新版本>`
249
- 解析到的包元数据可能还是旧的并报 `ETARGET`。重试改用一次性缓存目录强制冷取
250
- (`--prefer-online` 命中 304 时仍会拿到旧元数据),不影响用户真正的 npm 缓存。
251
- 权限、磁盘、脚本失败等真实故障不重试,照常上报。
252
- - 修复状态气泡在任务完成后被打回"正在思考":`Stop` 之后仍会飘来 `SubagentStop` /
253
- `PostToolUse` 等尾巴事件,它们与 `UserPromptSubmit` 归一成同一个状态,现按事件名拦截,
254
- 终态只能被新一轮真实动作解除。
255
- - 状态气泡新增"待机中":`正在启动` 超过 8 秒没有后续事件即落到待机,不再让启动态和
256
- 空闲态显示成同一句"正在准备当前会话…"。
257
- - 修复测试污染用户真实事件流:跑包装脚本的用例只隔离了 `TMPDIR`,而事件文件走
258
- `NSTemporaryDirectory()` 不认它,每次跑测试都会写入 3 条 `SessionStart`,把正在运行的
259
- 桌宠打回"正在启动"。相关用例补上 `CC_PETS_STATE_DIR`,并加了基线校验防止再犯。
260
- - 修复额度卡片的在线徽章恒亮:此前按"有没有额度数据"判定,而额度会一直缓存,导致
261
- 客户端早已退出、甚至单独打开 App 从未运行过 Agent 时两张卡片也显示在线。现改为按该
262
- provider 是否还有存活客户端判定,并用事件活跃度覆盖不经包装脚本启动的会话。包装脚本
263
- 启动的会话退出后 3 秒内转为"离线",不再被为直接启动会话准备的 60 秒静默宽限拖住。
264
- - 额度面板调整信息层级:官方剩余百分比升为主值、本机 Token 降为次级;汇总条改为
265
- 分别展示 Codex、Claude 的「今日」与「最近 7 天」Token;统计改用与订阅无关的自然日窗口,
266
- 并保留 Provider 归属;"数据刷新"改由面板自身定时器走字;无 Agent 在线时
267
- 状态配色转灰;额度窗口缺失的列标注"当前无活跃窗口"。
268
- - 新增 `cc-pets clean` 和带确认的 `cc-pets uninstall --purge`,并自动清理测试临时目录与过期运行状态。
269
- - 更新日志每次更新前截断,并限制为最近 1 MB,避免长期残留增长。
270
- - Codex/Claude 额度读取改为 FSEvents/VNODE 事件监听,并保留 120 秒容错刷新,降低空闲文件扫描与 JSON 解析。
271
- - 精灵图按显示尺寸降采样,菜单预览改用有限缓存;待审批记录增加 TTL 与容量上限。
272
- - 低电量模式和系统“减少动态效果”开启时自动降低动画刷新频率。
273
- - 新增可展开折叠的玻璃 Agent 状态卡片、活跃 CLI 会话数徽标和可选的完成、失败、审批系统通知。
274
- - 历史记录与系统通知设置改用右侧高对比度迷你开关,支持在菜单保持展开时连续调整。
275
- - 折叠圆钮固定锚定在桌宠头部右上区域,展开和折叠时不再跳动。
276
- - Agent 连续 1 分钟没有新状态事件时,状态卡片和圆钮会自动隐藏。
277
- - Codex/Claude 包装器会在启动桌宠前写入 Provider 启动事件,避免共享事件流导致启动瞬间显示错误来源。
278
- - 工具或子 Agent 完成后,状态卡片会恢复为思考中;仅在当前回合真正结束时显示任务完成。
279
- - 新增统一 Provider 事件协议,第三方 CLI Agent 可接入桌宠状态和动画。
280
- - 新增默认关闭的本地额度历史,按 15 分钟采样并滚动保留 7 天趋势。
48
+ ### Speech
281
49
 
282
- ## [0.2.15] - 2026-07-24
50
+ - All pet speech comes from `~/.cc-pets/speech.txt`, can be edited in the built-in editor, and supports live data placeholders.
51
+ - Per-pet speech can be stored at `~/.cc-pets/speech/<pet-name>.txt` and replaces global speech by section.
52
+ - Includes four speech-frequency levels and stays silent while an agent is working.
283
53
 
284
- - 支持 Codex/PetDex `spriteVersionNumber: 2` 的 `8×11` 精灵图布局及十六向鼠标跟随。
285
- - 新增右键“检查更新…”,可在应用内确认并完成 npm 版本升级,无需手动打开终端。
286
- - 自动更新成功后由独立进程等待旧桌宠退出并启动新版,避免旧进程继续报告可更新。
54
+ ### Installation and integration
287
55
 
288
- ## [0.2.0] - 2026-07-22
56
+ - `npm install -g cc-pets` builds the native app, installs both hook integrations and shell integration, and installs `~/Applications/CC Pets.app`.
57
+ - Symlinks under `~/.cc-pets/shims` intercept `codex` and `claude`, including casing variants, to start the pet.
58
+ - `cc-pets install`, `uninstall`, and `uninstall-app` provide repeatable initialization and cleanup flows.
289
59
 
290
- - 项目和 npm 包更名为 CC Pets。
291
- - 新版安装器会自动清理旧版 `codex-pet` Hooks、Claude status line 包装和 shell aliases。
292
- - 旧版迁移只匹配 CC Pets 的完整命令签名,避免误删复用相似标记的其他工具配置。
293
- - 新增原创默认桌宠 ByteMochi,移除公开包中的第三方角色素材。
294
- - 新增 Codex CLI 与 Claude Code CLI 共存、Agent 动画和额度面板。
295
- - 新增 PetDex 外部素材动态扫描与桌宠切换。
296
- - 新增 `cc-pets uninstall`,可移除本项目 Hooks、恢复 Claude status line 并清理 shell aliases。
297
- - 构建支持 PNG、WebP 和空素材目录。
298
- - 补充隐私、安全、贡献和第三方素材说明。
60
+ ### Privacy
299
61
 
300
- ## [0.1.0] - 2026-07-21
301
-
302
- - 首个可用版本。
62
+ - Uploads no conversations, quotas, credentials, or usage statistics and contains no telemetry.
63
+ - Status cards and notifications show only the provider, state category, and redacted tool category.
@@ -0,0 +1,64 @@
1
+ # 更新记录
2
+
3
+ [English](./CHANGELOG.md) | 简体中文
4
+
5
+ 本项目遵循语义化版本号。版本号以 `package.json` 为唯一来源。
6
+
7
+ ## [2.0.1] - 2026-09-07
8
+
9
+ 额度显示与面板稳定性问题修复。
10
+
11
+ ### 额度与用量
12
+
13
+ - 从 Codex App Server 读取实时额度窗口,并叠加到本机聚合的 Token 用量上;后台保持长连接,处理刷新、通知、超时与降级回退。
14
+ - 修复额度重置后 Codex 额度不再显示的问题:过期的会话额度窗口现在会独立丢弃,耗尽状态在重置前后也能正确保留。
15
+ - 官方额度数据尚不可用时,显示“等待刷新”状态。
16
+
17
+ ### 桌宠与互动
18
+
19
+ - 修复面板偶尔无法显示的问题。
20
+ - 统一宠物台词视角为第一人称:由“宠物旁观 Agent”调整为“宠物即 Agent”。
21
+
22
+ ## [2.0.0] - 2026-08-23
23
+
24
+ 首个开源版本。
25
+
26
+ ### 桌宠与互动
27
+
28
+ - macOS 原生 AppKit 桌宠,运行时不依赖 Electron,也不需要 Codex/Claude 桌面端。
29
+ - 待机呼吸、随机小动作、拖动滞后与落脚回弹;头部、口袋、脚部和身体两侧的悬停与点击反馈。
30
+ - 右键菜单可切换桌宠、刷新用量、开关额度历史与系统通知、检查更新或退出。
31
+ - 支持内置素材与 `~/.cc-pets/pets/` 下的外部素材,兼容 `spriteVersionNumber` v1 / v2 网格。
32
+
33
+ ### 额度与用量
34
+
35
+ - 从本机 `~/.codex/sessions` 与 Claude Code 官方 status line 数据读取 5 小时额度、周额度和重置时间。
36
+ - 悬停口袋展开额度面板,用两张卡分别展示 Codex、Claude 的剩余百分比、本机 Token 与近 7 天趋势。
37
+ - 可选记录最近 7 天的本地额度历史;默认关闭,仅保存在本机。
38
+ - 支持「订阅额度 / API 用量」两种展示模式。
39
+
40
+ ### Agent 状态
41
+
42
+ - 由 Codex Hooks 与 Claude Code Hooks 驱动思考、工具调用、审批、子 Agent、完成与失败动画。
43
+ - 桌宠旁显示脱敏后的玻璃状态卡片,可折叠并显示活跃 CLI 会话数。
44
+ - 可分别启用任务完成、失败和等待审批的 macOS 系统通知。
45
+ - 第三方 CLI Agent 可通过统一 Provider 事件协议接入,详见
46
+ [`PROVIDER_PROTOCOL.zh-CN.md`](./PROVIDER_PROTOCOL.zh-CN.md)。
47
+
48
+ ### 台词
49
+
50
+ - 桌宠台词全部来自 `~/.cc-pets/speech.txt`,可在内置编辑器中修改,支持实时数据槽位。
51
+ - 可为单只宠物写专属台词(`~/.cc-pets/speech/<宠物名>.txt`),按小节整体覆盖通用台词。
52
+ - 四档碎碎念频率,Agent 工作期间不插嘴。
53
+
54
+ ### 安装与集成
55
+
56
+ - `npm install -g cc-pets` 自动构建原生应用、安装两套 Hooks 与 shell 集成,并安装
57
+ `~/Applications/CC Pets.app`。
58
+ - 通过 `~/.cc-pets/shims` 下的软链接管 `codex` / `claude`,任意大小写写法都能拉起桌宠。
59
+ - `cc-pets install` / `uninstall` / `uninstall-app` 提供可重复执行的初始化与清理流程。
60
+
61
+ ### 隐私
62
+
63
+ - 不上传会话内容、额度、凭据或使用统计,不包含遥测。
64
+ - 状态卡片与通知只显示 Provider、状态类别和脱敏后的工具类别。
package/CONTRIBUTING.md CHANGED
@@ -1,20 +1,23 @@
1
- # 参与贡献
1
+ # Contributing
2
2
 
3
- 感谢你参与 CC Pets。提交改动前,请先确认:
3
+ English | [简体中文](./CONTRIBUTING.zh-CN.md)
4
4
 
5
- 1. 改动聚焦于一个明确问题,并避免提交无关格式化。
6
- 2. 新素材必须是原创作品,或具有允许修改和再分发的明确许可证。
7
- 3. 不要提交 Codex/Claude 会话、额度缓存、API Key、Cookie、个人路径或其他敏感信息。
8
- 4. 运行 `npm test`,确保原生构建、Hooks、额度采集、卸载和包装器测试全部通过。
9
- 5. 对用户可见的行为变化同步更新 `README.md` 和 `CHANGELOG.md`。
5
+ Thank you for contributing to CC Pets. Before submitting a change:
10
6
 
11
- 建议先通过 Gitee Issue 描述较大的功能或兼容性改动,再提交 Pull Request。
7
+ 1. Keep the change focused on one clear problem and avoid unrelated formatting.
8
+ 2. Submit only original assets or assets with an explicit license that permits modification and redistribution.
9
+ 3. Never submit Codex or Claude sessions, quota caches, API keys, cookies, personal paths, or other sensitive information.
10
+ 4. Run `npm test` and confirm that the native build, hooks, quota collection, uninstall, and wrapper tests pass.
11
+ 5. Update `README.md` and `CHANGELOG.md` for user-visible behavior changes.
12
12
 
13
- ## 素材规范
13
+ For a substantial feature, open a GitHub Issue before sending a Pull Request so the
14
+ scope can be agreed on first.
14
15
 
15
- - 支持 PNG 或 WebP,背景必须透明。
16
- - 内置素材按 `8×9` 网格切分。外部 Codex/PetDex 素材支持
17
- `spriteVersionNumber` v1(`1536×1872`、`8×9`)和
18
- v2(`1536×2288`、`8×11`),每格均为 `192×208`。
19
- - 九行动画帧数依次为 `6/8/8/4/5/8/6/6/6`,未使用单元格必须保持透明。
20
- - 请在 Pull Request 中说明素材作者、来源和许可证。
16
+ ## Asset requirements
17
+
18
+ - Use PNG or WebP with a transparent background.
19
+ - Built-in assets use an `8×9` grid. External Codex/PetDex assets support
20
+ `spriteVersionNumber` v1 (`1536×1872`, `8×9`) and v2 (`1536×2288`, `8×11`),
21
+ with `192×208` cells.
22
+ - The nine animation rows contain `6/8/8/4/5/8/6/6/6` frames. Keep unused cells transparent.
23
+ - State the asset author, source, and license in the Pull Request.
@@ -0,0 +1,22 @@
1
+ # 参与贡献
2
+
3
+ [English](./CONTRIBUTING.md) | 简体中文
4
+
5
+ 感谢你参与 CC Pets。提交改动前,请先确认:
6
+
7
+ 1. 改动聚焦于一个明确问题,并避免提交无关格式化。
8
+ 2. 新素材必须是原创作品,或具有允许修改和再分发的明确许可证。
9
+ 3. 不要提交 Codex/Claude 会话、额度缓存、API Key、Cookie、个人路径或其他敏感信息。
10
+ 4. 运行 `npm test`,确保原生构建、Hooks、额度采集、卸载和包装器测试全部通过。
11
+ 5. 对用户可见的行为变化同步更新 `README.zh-CN.md` 和 `CHANGELOG.zh-CN.md`。
12
+
13
+ 建议先开一个 GitHub Issue 描述较大的功能改动,达成一致后再提交 Pull Request。
14
+
15
+ ## 素材规范
16
+
17
+ - 支持 PNG 或 WebP,背景必须透明。
18
+ - 内置素材按 `8×9` 网格切分。外部 Codex/PetDex 素材支持
19
+ `spriteVersionNumber` v1(`1536×1872`、`8×9`)和
20
+ v2(`1536×2288`、`8×11`),每格均为 `192×208`。
21
+ - 九行动画帧数依次为 `6/8/8/4/5/8/6/6/6`,未使用单元格必须保持透明。
22
+ - 请在 Pull Request 中说明素材作者、来源和许可证。
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 wangxinyusqn
3
+ Copyright (c) 2026 Sunnyshiny
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,10 +1,13 @@
1
- # CC Pets Provider 事件协议
1
+ # CC Pets Provider Event Protocol
2
2
 
3
- 第三方 CLI Agent 可以通过标准输入向 CC Pets 写入统一状态事件,从而复用状态气泡、
4
- 桌宠动画和可选的系统通知。协议只接收状态类别和工具类别,不接收提示词、命令正文、
5
- 文件内容或模型输出。
3
+ English | [简体中文](./PROVIDER_PROTOCOL.zh-CN.md)
6
4
 
7
- ## 发送事件
5
+ Third-party CLI agents can write normalized status events to CC Pets through
6
+ standard input and reuse its status card, animations, and optional system
7
+ notifications. The protocol accepts status and tool categories only. It does not
8
+ accept prompts, command text, file contents, or model output.
9
+
10
+ ## Sending an event
8
11
 
9
12
  ```bash
10
13
  printf '%s' '{
@@ -15,42 +18,48 @@ printf '%s' '{
15
18
  }' | cc-pets provider-event
16
19
  ```
17
20
 
18
- `provider` 必填,最长 32 个字符,仅保留字母、数字、空格、`.`、`_` 和 `-`。
19
- `tool` 可选,最长 64 个字符,仅用于选择脱敏后的状态文案和动画。
21
+ `provider` is required, has a maximum length of 32 characters, and may contain only
22
+ letters, digits, spaces, `.`, `_`, and `-`. `tool` is optional, has a maximum length
23
+ of 64 characters, and is used only to select redacted status text and animation.
20
24
 
21
- `state` 必须是下列值之一:
25
+ `state` must be one of these values:
22
26
 
23
- | state | 含义 |
27
+ | State | Meaning |
24
28
  | --- | --- |
25
- | `starting` | 会话开始 |
26
- | `thinking` | Agent 思考 |
27
- | `tool` | 工具开始执行 |
28
- | `approval` | 等待用户审批 |
29
- | `subagent` | 子 Agent 工作中 |
30
- | `tool_completed` | 单次工具执行完成 |
31
- | `tool_failed` | 单次工具执行失败 |
32
- | `completed` | 当前任务完成 |
33
- | `failed` | 当前任务失败 |
34
- | `notification` | 需要用户关注 |
35
-
36
- 建议工具类别使用 `shell`、`edit`、`write`、`read`、`search`、`web`、`mcp` 或
37
- `agent`。CC Pets 不会执行 `tool` 字段,也不会将其作为通知正文。
38
-
39
- ## 状态显示规则
40
-
41
- 事件到达顺序不一定等于语义顺序,气泡显示因此有两条额外规则:
42
-
43
- - **终态具有黏性。** 进入 `completed` 或 `failed` 后,紧随其后的 `tool_completed`
44
- (以及内部的 `SubagentStop`、`TaskCompleted`)不会改写气泡——这类尾巴事件常常在任务
45
- 真正结束之后才到达。要解除终态,请发送 `thinking`、`tool`、`approval` 或
46
- `notification` 等表示新一轮动作的状态。
47
- - **`starting` 是短时态。** 超过 8 秒没有后续事件,气泡会自动落到"待机中",表示会话
48
- 已就绪、正在等待输入。长时间的准备工作请显式发送 `thinking`,不要停留在 `starting`。
49
-
50
- ## 生命周期
51
-
52
- 事件写入当前用户的临时状态目录,已经运行的 CC Pets 会立即读取。Provider 集成需要自行
53
- 负责启动和关闭 CC Pets;事件协议不会创建后台守护进程,也不会改变现有 Codex/Claude CLI
54
- 的托管生命周期。
55
-
56
- 协议版本不兼容或字段无效时,命令返回退出码 `2`;写入失败时返回非零退出码。
29
+ | `starting` | Session started |
30
+ | `thinking` | Agent is thinking |
31
+ | `tool` | Tool execution started |
32
+ | `approval` | Waiting for user approval |
33
+ | `subagent` | Subagent is working |
34
+ | `tool_completed` | One tool execution completed |
35
+ | `tool_failed` | One tool execution failed |
36
+ | `completed` | Current task completed |
37
+ | `failed` | Current task failed |
38
+ | `notification` | User attention is required |
39
+
40
+ Recommended tool categories are `shell`, `edit`, `write`, `read`, `search`, `web`,
41
+ `mcp`, and `agent`. CC Pets never executes the `tool` value or uses it as notification
42
+ body text.
43
+
44
+ ## Display rules
45
+
46
+ Events may arrive in an order that differs from their semantic order, so the status
47
+ card applies two additional rules:
48
+
49
+ - **Terminal states are sticky.** After `completed` or `failed`, a following
50
+ `tool_completed` event (or internal `SubagentStop` / `TaskCompleted` event) does
51
+ not replace the terminal status. Send `thinking`, `tool`, `approval`,
52
+ `notification`, or another new-action state to clear it.
53
+ - **`starting` is temporary.** If no later event arrives within eight seconds, the
54
+ card changes to idle to show that the session is ready and waiting. Send
55
+ `thinking` explicitly for longer preparation work.
56
+
57
+ ## Lifecycle
58
+
59
+ Events are written to the current user's temporary state directory and are read
60
+ immediately by a running CC Pets process. A provider integration is responsible for
61
+ starting and stopping CC Pets. This protocol does not create a background daemon or
62
+ change the managed lifecycle of the Codex and Claude integrations.
63
+
64
+ An incompatible schema version or invalid field returns exit code `2`. A write
65
+ failure returns a non-zero exit code.