cc-pets 0.1.0

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 ADDED
@@ -0,0 +1,18 @@
1
+ # 更新记录
2
+
3
+ 本项目遵循语义化版本号。
4
+
5
+ ## [Unreleased]
6
+
7
+ - 项目和 npm 包更名为 CC Pets。
8
+ - 新增原创默认桌宠 ByteMochi,移除公开包中的第三方角色素材。
9
+ - 新增 Codex CLI 与 Claude Code CLI 共存、Agent 动画和额度面板。
10
+ - 新增 PetDex 外部素材动态扫描与桌宠切换。
11
+ - 新增 `codex-pet uninstall`,可移除本项目 Hooks、恢复 Claude status line 并清理 shell aliases。
12
+ - 构建支持 PNG、WebP 和空素材目录。
13
+ - 补充隐私、安全、贡献和第三方素材说明。
14
+
15
+ ## [0.1.0] - 2026-07-21
16
+
17
+ - 首个可用版本。
18
+
@@ -0,0 +1,19 @@
1
+ # 参与贡献
2
+
3
+ 感谢你参与 CC Pets。提交改动前,请先确认:
4
+
5
+ 1. 改动聚焦于一个明确问题,并避免提交无关格式化。
6
+ 2. 新素材必须是原创作品,或具有允许修改和再分发的明确许可证。
7
+ 3. 不要提交 Codex/Claude 会话、额度缓存、API Key、Cookie、个人路径或其他敏感信息。
8
+ 4. 运行 `npm test`,确保原生构建、Hooks、额度采集、卸载和包装器测试全部通过。
9
+ 5. 对用户可见的行为变化同步更新 `README.md` 和 `CHANGELOG.md`。
10
+
11
+ 建议先通过 Gitee Issue 描述较大的功能或兼容性改动,再提交 Pull Request。
12
+
13
+ ## 素材规范
14
+
15
+ - 支持 PNG 或 WebP,背景必须透明。
16
+ - 画布为 `1536×1872`,按 `8×9` 网格切分,每格 `192×208`。
17
+ - 九行动画帧数依次为 `6/8/8/4/5/8/6/6/6`,未使用单元格必须保持透明。
18
+ - 请在 Pull Request 中说明素材作者、来源和许可证。
19
+
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wangxinyusqn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,237 @@
1
+ # CC Pets
2
+
3
+ 一个不依赖 Codex/Claude 桌面端的 macOS 原生桌宠。启动 Codex CLI 或 Claude Code CLI 时自动出现,
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
+ - 支持拖动桌宠位置,右键刷新用量或退出
14
+ - 响应 Codex 与 Claude Code Agent 的思考、工具调用、审批、子 Agent、完成和失败状态
15
+ - 使用原生 AppKit,运行时不依赖 Electron
16
+
17
+ ## 互动方式
18
+
19
+ ### Agent 工作状态
20
+
21
+ | Agent 事件 | 桌宠反馈 |
22
+ | --- | --- |
23
+ | 新会话启动 | 挥手唤醒 |
24
+ | 提交用户提示、Agent 思考 | 思考动画 |
25
+ | 执行 Shell 命令 | 跑动动画 |
26
+ | 编辑或写入文件 | 工作动画 |
27
+ | 读取、搜索或调用 MCP | 观察动画 |
28
+ | 等待审批 | 提醒动画 |
29
+ | 启动子 Agent | 子 Agent 动画 |
30
+ | 工具执行成功 | 完成动画 |
31
+ | 工具执行失败 | 失败动画 |
32
+ | 当前回合或子 Agent 结束 | 告别后恢复待机 |
33
+
34
+ Agent 动画分别由 Codex Hooks 和 Claude Code Hooks 驱动。首次安装或 Codex Hook 内容更新后,启动 Codex 并执行
35
+ `/hooks`,检查并信任 CC Pets Hook;未经信任的用户级 Hook 会被 Codex 安全机制跳过。
36
+ Claude Code Hook 会合并到 `~/.claude/settings.json`,现有的 `env`、`model`、`statusLine`
37
+ 以及其他 Hooks 都会保留。Claude status line 会通过透明转发器继续执行原命令,同时将官方
38
+ `rate_limits` 字段提供给桌宠。
39
+ 执行 `codex-pet install` 会重新构建应用、安装或更新两套 Hooks,并配置 shell alias;如果旧版桌宠正在运行,
40
+ 安装器会自动重启桌宠,使新版本生效。
41
+
42
+ ### 鼠标互动
43
+
44
+ | 操作 | 桌宠反馈 |
45
+ |--------------------|----------------------------------------------------------|
46
+ | 鼠标移动到头部 | 播放头部互动动画 |
47
+ | 鼠标移动到口袋 | 播放口袋互动动画,并从桌宠左侧展开 Codex/Claude 额度面板 |
48
+ | 鼠标移动到脚部 | 播放脚部互动动画 |
49
+ | 鼠标移动到身体右侧 | 播放右侧感应动画 |
50
+ | 鼠标移动到身体左侧 | 播放左侧感应动画 |
51
+ | 单击桌宠 | 播放一次俏皮反馈动画 |
52
+ | 按住并向右拖动 | 播放向右拖行动画,同时移动桌宠 |
53
+ | 按住并向左拖动 | 播放向左拖行动画,同时移动桌宠 |
54
+ | 鼠标移开或拖动结束 | 恢复默认待机动画 |
55
+ | 右键桌宠 | 切换已有桌宠、刷新用量或退出 |
56
+
57
+ 右键菜单中的“切换桌宠”会动态扫描 `~/.petdex/pets/`、`~/.codex/pets/` 以及包内素材。
58
+ 外部桌宠使用目录名作为菜单名称,内置桌宠使用素材文件名(不显示扩展名)。选择后立即
59
+ 切换并持久保存;下次启动会继续使用上次选择的桌宠。该菜单只负责切换已有素材,不提供
60
+ 添加或删除功能。每次打开菜单都会重新扫描,因此通过 PetDex 安装新素材后无需重新编译。
61
+
62
+ 当 `~/.petdex/pets/<name>/` 只有 `pet.json` 时,程序会自动到
63
+ `~/.codex/pets/<name>/` 查找同名桌宠的 `spritesheet.webp` 或 `spritesheet.png`。
64
+
65
+ 交互区域存在重叠时,按“口袋、头部、脚部、身体左右侧”的优先级识别。拖动超过
66
+ 3 像素后才进入拖动状态,避免普通点击被误判为拖动。
67
+
68
+ 素材行与行为的对应关系:
69
+
70
+ 1. 默认待机(6 帧)
71
+ 2. 向右拖动(8 帧)
72
+ 3. 向左拖动(8 帧)
73
+ 4. 身体右侧感应(4 帧)
74
+ 5. 头部悬停(5 帧)
75
+ 6. 口袋悬停与额度展示(8 帧)
76
+ 7. 脚部悬停(6 帧)
77
+ 8. 点击反馈(6 帧)
78
+ 9. 身体左侧感应(6 帧)
79
+
80
+ ## 系统要求
81
+
82
+ - macOS 13 或更高版本
83
+ - Node.js 18 或更高版本
84
+ - 已安装并登录 Codex CLI 和/或 Claude Code CLI
85
+ - zsh
86
+ - Xcode Command Line Tools,可通过 `xcode-select --install` 安装
87
+
88
+ ## 安装
89
+
90
+ ### npm 安装
91
+
92
+ ```bash
93
+ npm install -g cc-pets
94
+ codex-pet install
95
+ source ~/.zshrc
96
+ codex
97
+ # 或
98
+ claude
99
+ ```
100
+
101
+ ### 本地源码安装
102
+
103
+ ```bash
104
+ git clone https://gitee.com/wangxinyusqn/cc-pets.git
105
+ cd cc-pets
106
+ npm install -g .
107
+ codex-pet install
108
+ source ~/.zshrc
109
+ codex
110
+ # 或
111
+ claude
112
+ ```
113
+
114
+ 两种方式都会安装 `codex-pet`、`codex-with-pet` 和 `claude-with-pet`。
115
+ `codex-pet install` 是桌宠初始化命令:它会构建原生应用、安装两套 Agent Hooks,并向 `~/.zshrc` 追加带明确标记的
116
+ `codex` 与 `claude` alias,不会覆盖真实的 CLI 二进制。
117
+
118
+ 如果真实 Codex CLI 不在当前 `PATH`,可以显式指定:
119
+
120
+ ```bash
121
+ export CODEX_REAL_BIN=/absolute/path/to/codex
122
+ ```
123
+
124
+ 包装器不会读取或执行 `.env`,只会把当前终端环境原样传给真实 Codex。Codex CLI 会按自身规则
125
+ 读取 `${CODEX_HOME:-~/.codex}/.env`,因此代理和其他 Codex 配置不需要由桌宠重复加载。
126
+
127
+ 如果真实 Claude Code CLI 不在当前 `PATH`,可以显式指定:
128
+
129
+ ```bash
130
+ export CLAUDE_REAL_BIN=/absolute/path/to/claude
131
+ ```
132
+
133
+ ## 命令说明
134
+
135
+ ```bash
136
+ # 构建原生程序
137
+ codex-pet build
138
+
139
+ # 独立启动桌宠;独立启动时不会随 CLI 自动退出
140
+ codex-pet
141
+
142
+ # 前台运行,便于调试
143
+ codex-pet --foreground
144
+
145
+ # 查看当前解析到的 Codex 额度
146
+ codex-pet --status
147
+
148
+ # 安装/更新 Hooks、shell alias,并让已运行桌宠加载新版本
149
+ codex-pet install
150
+
151
+ # 安全移除 Hooks、恢复 Claude status line,并清理 shell alias
152
+ codex-pet uninstall
153
+
154
+ # 启动桌宠后进入 Codex CLI
155
+ codex-with-pet
156
+
157
+ # 启动桌宠后进入 Claude Code CLI
158
+ claude-with-pet
159
+ ```
160
+
161
+ ## 用量数据
162
+
163
+ Codex 用量来自 `~/.codex/sessions` 的本地 `token_count` 事件:
164
+
165
+ - `window_minutes = 300` 对应 5 小时额度
166
+ - `window_minutes = 10080` 对应周额度
167
+ - 桌宠将 `used_percent` 换算为剩余百分比后显示
168
+ - Codex 当前事件未提供某个额度窗口时显示 `--`,不会使用已过期的历史额度冒充当前值
169
+
170
+ Claude 用量来自官方 status line 输入中的 `rate_limits.five_hour` 与
171
+ `rate_limits.seven_day`。其中的 `used_percentage` 会换算为剩余百分比。该字段仅面向
172
+ Claude.ai Pro/Max 订阅账号,并在会话完成首次 API 响应后出现;字段尚不可用时显示 `--`。
173
+
174
+ 额度详情面板使用青色区分 Codex、紫色区分 Claude。5 小时剩余额度使用进度条,周剩余
175
+ 额度使用环形进度,右侧展示对应的周重置时间。服务端的 Unix 时间戳会使用 Mac 当前系统时区格式化为
176
+ `M/d HH:mm:ss`;因此它与 CLI 中标注其他时区的同一时刻可能日期和小时不同,但代表同一个真实时间。
177
+ 应用每 5 秒自动重新读取一次额度,右上角刷新按钮也可立即读取本地数据;Codex 数据随本地 session 更新,Claude 数据则要等 Claude Code
178
+ 下一次把 `rate_limits` 传给 status line 后才会变化,按钮不会主动请求 Claude 服务端。
179
+ 面板使用原生 AppKit 毛玻璃材质,以紧凑悬浮卡片形式显示在桌宠左上方,并优先使用本机官方 Codex、Claude 应用
180
+ 图标。鼠标从口袋移动到面板后可继续停留查看,移出两者后面板会延迟收起;拖动桌宠时
181
+ 面板会保持显示并实时跟随位置。
182
+
183
+ 可以独立验证解析结果:
184
+
185
+ ```bash
186
+ ./scripts/build.sh
187
+ ./.build/release/codex-pet --status
188
+ ```
189
+
190
+ ## 素材与版权
191
+
192
+ 桌宠素材统一放在 `Sources/CodexPet/Resources/`,程序会自动收集其中的 `.webp` 和 `.png` 文件。
193
+ 素材需要使用 `1536×1872` 画布,按 `8×9` 网格切分为 `192×208` 单元格,并遵循相同的帧数和动作行协议。
194
+ 角色可能属于受版权保护的作品;公开
195
+ 发布本项目或 npm 包前,请确认已经获得素材的使用和分发授权,或替换为原创、可公开分发的素材。
196
+
197
+ 也可以直接使用 PetDex 安装素材,无需放入项目目录:
198
+
199
+ ```bash
200
+ npx petdex install <slug>
201
+ ```
202
+
203
+ 安装完成后,打开桌宠右键菜单即可看到对应目录名。
204
+
205
+ 项目允许在没有内置素材时构建。若启动时内置目录和两个外部目录都没有可用素材,应用会显示
206
+ 提示窗口,可打开 `~/.petdex/pets/`、安装素材后重新扫描,或安全退出。
207
+
208
+ ## 隐私
209
+
210
+ - Codex 额度只从本机 `${CODEX_HOME:-~/.codex}/sessions` 读取。
211
+ - Claude 额度只从 Claude Code 传给本机 status line 的 `rate_limits` 字段读取。
212
+ - Agent Hooks 只向当前用户的临时目录写入桌宠事件和额度缓存。
213
+ - 项目不上传会话内容、额度、凭据或使用统计,也不包含遥测服务。
214
+ - 右键“退出桌宠”或执行 `codex-pet uninstall` 后,不会继续运行后台守护进程。
215
+
216
+ ## 卸载
217
+
218
+ 先在 npm 包仍然存在时移除集成:
219
+
220
+ ```bash
221
+ codex-pet uninstall
222
+ source ~/.zshrc
223
+ npm uninstall -g cc-pets
224
+ ```
225
+
226
+ 卸载器只删除带 CC Pets 标记的 Codex/Claude Hooks 和 shell alias,并恢复安装前的 Claude
227
+ status line;其他用户配置和 Hooks 会保留。
228
+
229
+ ## 项目声明
230
+
231
+ CC Pets 是社区开源项目,与 OpenAI、Anthropic、PetDex 及任何角色版权方不存在隶属、授权
232
+ 或官方合作关系。Codex、ChatGPT、Claude 及相关图标和商标归各自权利人所有。
233
+
234
+ ## License
235
+
236
+ 项目代码和原创默认素材 ByteMochi 采用 [MIT License](./LICENSE)。外部素材不因本项目许可证而自动获得授权,
237
+ 详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。
@@ -0,0 +1,28 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3
+ <plist version="1.0">
4
+ <dict>
5
+ <key>CFBundleDisplayName</key>
6
+ <string>CC Pets</string>
7
+ <key>CFBundleExecutable</key>
8
+ <string>codex-pet</string>
9
+ <key>CFBundleIdentifier</key>
10
+ <string>com.universewang.codex-pet</string>
11
+ <key>CFBundleInfoDictionaryVersion</key>
12
+ <string>6.0</string>
13
+ <key>CFBundleName</key>
14
+ <string>CodexPet</string>
15
+ <key>CFBundlePackageType</key>
16
+ <string>APPL</string>
17
+ <key>CFBundleShortVersionString</key>
18
+ <string>0.1.0</string>
19
+ <key>CFBundleVersion</key>
20
+ <string>1</string>
21
+ <key>LSMinimumSystemVersion</key>
22
+ <string>13.0</string>
23
+ <key>LSUIElement</key>
24
+ <true/>
25
+ <key>NSHighResolutionCapable</key>
26
+ <true/>
27
+ </dict>
28
+ </plist>
package/SECURITY.md ADDED
@@ -0,0 +1,17 @@
1
+ # 安全策略
2
+
3
+ ## 支持范围
4
+
5
+ 安全修复优先应用于最新发布版本和 `main` 分支。
6
+
7
+ ## 报告安全问题
8
+
9
+ 请不要在公开 Issue 中披露尚未修复的漏洞、凭据或私人会话数据。请通过
10
+ [Gitee 维护者主页](https://gitee.com/wangxinyusqn) 私下联系,并提供:
11
+
12
+ - 受影响版本与 macOS 版本
13
+ - 可复现步骤和影响范围
14
+ - 必要的最小日志;提交前请移除 Token、Cookie、用户名和本机路径
15
+
16
+ 维护者确认问题并准备修复后,再协调公开披露时间。
17
+