cc-pets 2.3.0 → 2.5.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.
Files changed (101) hide show
  1. package/CC_BRIDGE.md +63 -7
  2. package/CC_BRIDGE.zh-CN.md +43 -5
  3. package/CHANGELOG.md +106 -0
  4. package/CHANGELOG.zh-CN.md +106 -0
  5. package/CONTRIBUTING.md +23 -1
  6. package/CONTRIBUTING.zh-CN.md +18 -1
  7. package/PROVIDER_PROTOCOL.md +5 -1
  8. package/PROVIDER_PROTOCOL.zh-CN.md +4 -1
  9. package/README.md +177 -33
  10. package/README.zh-CN.md +137 -32
  11. package/Resources/AgentIcons/claude.png +0 -0
  12. package/Resources/AgentIcons/codex.icns +0 -0
  13. package/Resources/IDEPlugins/cc-pets-terminal.vsix +0 -0
  14. package/Resources/IDEPlugins/cc-pets-terminal.zip +0 -0
  15. package/Resources/zh-Hans.lproj/Localizable.strings +187 -35
  16. package/Sources/CCPets/App/CCPetsAppDelegate+AgentEvents.m +47 -4
  17. package/Sources/CCPets/App/CCPetsAppDelegate+AgentStatus.m +121 -20
  18. package/Sources/CCPets/App/CCPetsAppDelegate+Bridge.m +8 -6
  19. package/Sources/CCPets/App/CCPetsAppDelegate+MenuBar.m +86 -0
  20. package/Sources/CCPets/App/CCPetsAppDelegate+Private.h +14 -1
  21. package/Sources/CCPets/App/CCPetsAppDelegate+Quota.m +6 -1
  22. package/Sources/CCPets/App/CCPetsAppDelegate+Settings.m +3 -6
  23. package/Sources/CCPets/App/CCPetsAppDelegate+Speech.m +118 -50
  24. package/Sources/CCPets/App/CCPetsAppDelegate+Update.m +4 -1
  25. package/Sources/CCPets/App/CCPetsAppDelegate+Workbench.m +4 -0
  26. package/Sources/CCPets/App/CCPetsAppDelegate.h +12 -2
  27. package/Sources/CCPets/App/CCPetsAppDelegate.m +4 -2
  28. package/Sources/CCPets/App/main.m +6 -0
  29. package/Sources/CCPets/Bridge/CCPetsBridge.m +45 -18
  30. package/Sources/CCPets/Bridge/CCPetsBridgeCLI.m +175 -68
  31. package/Sources/CCPets/Bridge/CCPetsBridgeCore.h +14 -6
  32. package/Sources/CCPets/Bridge/CCPetsBridgeCore.m +356 -110
  33. package/Sources/CCPets/Bridge/CCPetsBridgeSetup.h +0 -2
  34. package/Sources/CCPets/Bridge/CCPetsBridgeSetup.m +247 -126
  35. package/Sources/CCPets/Bridge/CCPetsBridgeStore.h +37 -9
  36. package/Sources/CCPets/Bridge/CCPetsBridgeStore.m +385 -80
  37. package/Sources/CCPets/Integrations/CCPetsEvents.h +5 -0
  38. package/Sources/CCPets/Integrations/CCPetsEvents.m +68 -12
  39. package/Sources/CCPets/Integrations/CCPetsIDEIntegration.h +21 -0
  40. package/Sources/CCPets/Integrations/CCPetsIDEIntegration.m +503 -0
  41. package/Sources/CCPets/Integrations/CCPetsIntegrations.m +1 -1
  42. package/Sources/CCPets/Integrations/CCPetsLaunchPreflight.h +5 -0
  43. package/Sources/CCPets/Integrations/CCPetsLaunchPreflight.m +367 -0
  44. package/Sources/CCPets/Integrations/CCPetsTerminalFocus.h +8 -1
  45. package/Sources/CCPets/Integrations/CCPetsTerminalFocus.m +156 -25
  46. package/Sources/CCPets/Integrations/CCPetsTerminalIntegration.h +17 -0
  47. package/Sources/CCPets/Integrations/CCPetsTerminalIntegration.m +64 -0
  48. package/Sources/CCPets/Integrations/CCPetsVSCodeIntegration.h +23 -0
  49. package/Sources/CCPets/Integrations/CCPetsVSCodeIntegration.m +475 -0
  50. package/Sources/CCPets/Pet/CCPetsPhrasesEditor.m +7 -0
  51. package/Sources/CCPets/Pet/PetView+Menu.m +11 -3
  52. package/Sources/CCPets/Pet/PetView.h +7 -0
  53. package/Sources/CCPets/Pet/PetView.m +12 -1
  54. package/Sources/CCPets/Support/CCPetsDoctor.m +26 -12
  55. package/Sources/CCPets/Support/CCPetsPreferences.h +12 -0
  56. package/Sources/CCPets/Support/CCPetsPreferences.m +52 -2
  57. package/Sources/CCPets/UI/CCPetsFormBuilder.h +2 -0
  58. package/Sources/CCPets/UI/CCPetsFormBuilder.m +18 -7
  59. package/Sources/CCPets/UI/CCPetsGlassView.h +26 -4
  60. package/Sources/CCPets/UI/CCPetsGlassView.m +40 -9
  61. package/Sources/CCPets/UI/CCPetsMenuBarIcon.h +16 -0
  62. package/Sources/CCPets/UI/CCPetsMenuBarIcon.m +70 -0
  63. package/Sources/CCPets/UI/CCPetsMenuBarPanel.h +18 -0
  64. package/Sources/CCPets/UI/CCPetsMenuBarPanel.m +528 -0
  65. package/Sources/CCPets/UI/CCPetsMenuBarSummary.h +51 -0
  66. package/Sources/CCPets/UI/CCPetsMenuBarSummary.m +95 -0
  67. package/Sources/CCPets/UI/CCPetsSettingsPage.h +6 -1
  68. package/Sources/CCPets/UI/CCPetsSettingsPage.m +577 -66
  69. package/Sources/CCPets/UI/CCPetsStatusItem.h +28 -0
  70. package/Sources/CCPets/UI/CCPetsStatusItem.m +147 -0
  71. package/Sources/CCPets/UI/CCPetsUIStyle.h +5 -2
  72. package/Sources/CCPets/UI/CCPetsUIStyle.m +57 -8
  73. package/Sources/CCPets/UI/CCPetsUsageChartView.m +4 -0
  74. package/Sources/CCPets/UI/CCPetsUsagePage.m +23 -28
  75. package/Sources/CCPets/UI/CCPetsUsageStore.m +2 -2
  76. package/Sources/CCPets/UI/CCPetsWorkbenchPages.m +5 -3
  77. package/Sources/CCPets/Usage/CCPetsUsage+CodexBackground.m +193 -0
  78. package/Sources/CCPets/Usage/CCPetsUsage+Internal.h +1 -0
  79. package/Sources/CCPets/Usage/CCPetsUsage+Models.m +49 -11
  80. package/Sources/CCPets/Usage/CCPetsUsage.h +3 -2
  81. package/Sources/CCPets/Usage/CCPetsUsageMonitor.m +15 -17
  82. package/Sources/CCPets/Usage/QuotaDashboardView+Rendering.m +11 -29
  83. package/Sources/CCPets/Usage/QuotaDashboardView.m +128 -2
  84. package/THIRD_PARTY_NOTICES.md +7 -3
  85. package/THIRD_PARTY_NOTICES.zh-CN.md +5 -1
  86. package/bin/claude-with-pet +2 -0
  87. package/bin/codex-with-pet +2 -0
  88. package/package.json +5 -1
  89. package/plugins/jetbrains/README.md +62 -0
  90. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalBridge.java +379 -0
  91. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalIdentity.java +24 -0
  92. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalStartup.java +12 -0
  93. package/plugins/jetbrains/src/main/resources/META-INF/plugin.xml +23 -0
  94. package/plugins/jetbrains/src/main/resources/META-INF/pluginIcon.svg +380 -0
  95. package/plugins/vscode/README.md +63 -0
  96. package/plugins/vscode/extension.js +210 -0
  97. package/plugins/vscode/package.json +18 -0
  98. package/scripts/build-idea-plugin.sh +101 -0
  99. package/scripts/build-vscode-extension.sh +112 -0
  100. package/scripts/build.sh +24 -2
  101. package/scripts/compile-cached.zsh +133 -0
package/README.zh-CN.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="docs/images/cover.png" alt="CC Pets v2.3.0:主菜单、多账号与按模型统计 Token 用量">
2
+ <img src="docs/images/cover.png" alt="CC Pets v2.5.0:菜单栏模式、会话展示与 CC Bridge 可靠性改进">
3
3
  </p>
4
4
 
5
5
  # CC Pets
@@ -9,22 +9,21 @@
9
9
  一个不依赖 Codex/Claude 桌面端的 macOS 原生桌宠。直接启动桌面端,或启动 Codex CLI / Claude Code CLI 时自动出现,
10
10
  并通过 Codex App Server 官方接口与 Claude Code 官方 status line 数据读取 5 小时额度、周额度和周重置时间。
11
11
 
12
- ## v2.3.0 新功能
12
+ ## v2.5.0 新功能
13
13
 
14
- - **主菜单**:从菜单或 `cc-pets open` 打开概览、会话、用量、宠物、多账号、提醒、设置和诊断,
15
- 集中查看在线会话、跳转终端和管理桌宠设置。
16
- - **多账号与模型用量**:在「多账号」页管理 Claude / Codex Home,按账号隔离额度、历史和在线状态;
17
- 查看最近 7、30、90 天的 Token 图表,按账号和模型筛选,独立设置订阅额度或 API 用量展示。
18
- - **原生运行时与诊断修复**:Hooks、CC Bridge 和 CLI 工具运行时无需 Node.js;
19
- 诊断页可修复已登记账号的 Hooks 和 Claude status line,修改前自动备份配置。
14
+ - **菜单栏模式**:保留桌宠、同时显示菜单栏或仅用菜单栏;查看会话与额度,
15
+ 有待审批会话时可直接跳到对应终端。
16
+ - **会话更清楚**:状态卡按会话区分,跟踪 Codex 桌面端的持久化聊天,
17
+ 会话结束时清理状态,不误播完成动画。
18
+ - **CC Bridge 可靠性**:逐次识别共享宿主上的调用者,改进并发文件预留和消息清理,
19
+ 保留配置中不属于 Bridge 的内容。
20
20
 
21
- 完整改动见 [更新记录](./CHANGELOG.zh-CN.md) 和 [Release Note](./docs/release-notes-v2.3.0.md)。
21
+ 完整改动见 [更新记录](./CHANGELOG.zh-CN.md) 和 [Release Note](./docs/release-notes-v2.5.0.md)。
22
22
 
23
23
  ## 界面预览
24
24
 
25
25
  <p align="center">
26
- <img src="docs/images/liquid-glass-panel.png" width="45%" alt="Liquid Glass 主题下的中文额度面板">
27
- <img src="docs/images/liquid-glass-menu.png" width="45%" alt="中文右键菜单与面板主题子菜单">
26
+ <img src="docs/images/liquid-glass-panel.png" width="48%" alt="Liquid Glass 主题下的中文额度面板"> <img src="docs/images/liquid-glass-menu.png" width="48%" alt="中文右键菜单与面板主题子菜单">
28
27
  </p>
29
28
 
30
29
  ## 功能
@@ -32,7 +31,7 @@
32
31
  - App 与 CLI 支持英语和简体中文,界面语言可即时切换
33
32
  - macOS 26 及以上可在经典与原生 Liquid Glass 两种面板主题之间切换
34
33
  - 随 Codex CLI 或 Claude Code CLI 自动启动,无需打开对应桌面版
35
- - 多个 Codex/Claude CLI 共用一个桌宠,最后一个 CLI 退出后桌宠自动关闭
34
+ - 多个 Codex/Claude CLI 共用一个桌宠,最后一个托管 CLI 退出且 Codex 桌面端未运行时,桌宠自动关闭
36
35
  - 鼠标悬停口袋时展开额度详情面板,用两张卡分别显示 Codex、Claude 的剩余 5 小时额度、周额度和精确到秒的周重置时间
37
36
  - reset 时间自动转换为 Mac 当前系统时区,例如 `Jul 22 3pm America/Los_Angeles` 在上海时区显示为 `7/23 06:00:00`
38
37
  - 支持待机、左右拖动、身体两侧感应、头部/脚部悬停和点击反馈动画
@@ -51,6 +50,7 @@
51
50
  - 可分别启用任务完成、失败、等待审批和响应超时的 macOS 系统通知
52
51
  - 内置一个原创素材,更多桌宠可从兼容 PetDex 的素材源按需下载到本机
53
52
  - 提供普通的主菜单:概览、会话与 CC Bridge 消息、按模型的 Token 用量、全部设置和内置诊断(见[主菜单](#主菜单))
53
+ - 可以常驻菜单栏:一键查看会话、各账号额度和今日用量,也可以完全隐藏桌宠(见[菜单栏](#菜单栏))
54
54
  - 使用原生 AppKit,运行时不依赖 Electron
55
55
 
56
56
  ## 主菜单
@@ -68,8 +68,8 @@ cc-pets open general # 还有 pet、accounts、alerts、diagnostics
68
68
  ```
69
69
 
70
70
  <p align="center">
71
- <img src="docs/images/main-menu-overview.png" width="45%" alt="主菜单概览页:宠物、今日 Token 用量和各账号额度卡片">
72
- <img src="docs/images/main-menu-usage.png" width="45%" alt="主菜单用量页:按模型堆叠的近 30 天每日用量图和模型明细表">
71
+ <img src="docs/images/main-menu-overview.png" width="48%" alt="主菜单概览页:宠物、今日 Token 用量和各账号额度卡片">
72
+ <img src="docs/images/main-menu-usage.png" width="48%" alt="主菜单用量页:按模型堆叠的近 30 天每日用量图和模型明细表">
73
73
  </p>
74
74
 
75
75
  - **侧边栏**:顶部是会动的当前宠物和它的状态,下面分两组:**工作台**(概览、会话、用量、宠物、多账号)
@@ -79,29 +79,71 @@ cc-pets open general # 还有 pet、accounts、alerts、diagnostics
79
79
  - **会话**:此刻在线的 Agent 会话(等审批的置顶,每行可「跳到终端」),以及 CC Bridge 的
80
80
  消息往来:卡在信箱里待投递的、最近送达的。仅显示消息交互,无消息正文。
81
81
  - **用量**:本机 Claude Code / Codex 最近 7、30、90 天的 Token 用量。顶部和概览同一套五格:总用量
82
- (输入 + 缓存写 + 输出 + 缓存输入)、输入、输出、缓存输入(附命中率)、请求数。每日柱状图按模型分色堆叠,
82
+ (输入 + 缓存写 + 输出 + 缓存输入 + 后台用量)、输入、输出、缓存输入(附命中率)、请求数。本机 Codex SQLite 日志补充的后台用量仅计入总量,不推算 Token 明细。每日柱状图按模型分色堆叠,
83
83
  颜色固定跟着模型走,可以在这五项之间切换;点图例或表格里的模型只看它,鼠标移到柱子上看当天各模型的数值。
84
84
  数据全部来自本机会话日志,不会发送到任何地方;按日归档让 Claude Code 清理旧转录之后,历史仍然留得住。
85
85
  - **多账号**:添加 Claude / Codex Home,查看账号的目录与集成状态,并通过“管理”菜单修复、重命名、重新定位或移除自定义 Home 的集成。
86
- - **宠物 / 提醒 / 设置**:桌宠的全部设置拆成三页(宠物:选宠物、大小、碎碎念、点击互动、导入 Codex 素材;提醒:系统通知、桌面状态卡和系统状态;
87
- 设置:语言、面板外观和素材目录),另有更细的项(比如连击阈值、可以连续调节的玻璃压暗,菜单里仍是四档)。
86
+ - **宠物 / 提醒 / 设置**:桌宠的全部设置拆成三页(宠物:选宠物、确认删除未选中的自定义宠物、大小、碎碎念、点击互动、导入 Codex 素材;提醒:系统通知、桌面状态卡和系统状态;
87
+ 设置:语言、显示位置、面板外观和素材目录),另有更细的项(比如连击阈值、可以连续调节的玻璃压暗,菜单里仍是四档)。
88
88
  右键菜单只留最常用的几项:管理桌宠、宠物大小、显示消息气泡、用量展示模式、面板主题和 CC Bridge,其余都到这里改。改动会立刻作用到桌面上的宠物,在菜单里改的也会同步显示在这里。
89
89
  会改写 Claude Code / Codex 配置的选项(启用 CC Bridge、免审批)仍只在右键菜单里。
90
90
  - **诊断**:和 `cc-pets doctor` 同一套检查,要处理的问题置顶,每条带所属模块、修复命令和「复制命令」;
91
91
  正常项折叠成一行。还有「重新检查」和「复制报告」(路径显示为 `~`,可以直接贴进 issue)。
92
92
  已登记账号的 Hooks 和 Claude status line 问题可点「自动修复」或「全部修复」,修复前备份配置及相关脚本,完成后自动重新检查。备份路径显示在页面上,其中 `manifest.json` 记录原文件路径、权限及备份文件;修复失败时显示原因,其他问题仍需复制命令执行。普通 `cc-pets doctor` 仍然只读。PATH 顺序那一项在这里只提示去终端运行 `cc-pets doctor`:
93
- 桌宠进程自己的 PATH 不是你终端的 PATH。
94
-
95
- 窗口在打开时才创建,关闭即释放,关着的时候没有任何后台任务。Dock 图标和菜单栏只在窗口打开期间出现,
96
- 窗口最小化后点 Dock 图标可以恢复。
93
+ 桌宠进程自己的 PATH 不是你终端的 PATH。版本检查比较本地包、当前运行的原生程序与已安装 App;
94
+ 源码 checkout/worktree 显示「本地源码包」,npm 安装显示「本地 npm 包」,无法确认来源时显示「本地包」。
95
+ 这些标签不表示 npm 已发布该版本;线上版本由更新检查单独查询。
96
+
97
+ 主菜单窗口在打开时才创建,关闭即释放,其页面关闭后不运行后台任务。Dock 图标和应用菜单只在窗口打开期间出现,
98
+ 窗口最小化后点 Dock 图标可以恢复。可选的菜单栏状态图标由「设置 → 显示位置」独立控制,不受主菜单窗口开关影响。
99
+
100
+ ### 菜单栏
101
+
102
+ 在 **主菜单 → 设置 → 显示位置** 选择 CC Pets 出现在哪里:**仅桌宠**(默认)、**桌宠 + 菜单栏**
103
+ 或 **仅菜单栏**。有菜单栏图标时:
104
+
105
+ - **左键**打开精简的玻璃面板,风格与悬停面板一致:宠物和它此刻在做什么;最多 5 个在线会话
106
+ (等待审批的置顶,点一行跳到对应终端);每个账号一行,显示 5 小时额度环、本周剩余和下次重置时间
107
+ (API 账号显示本月 Token 和调用次数;订阅账号排在前面);今日总用量;**显示桌宠**和**主菜单**。有新版本时这里也会
108
+ 出现「更新到 x.y.z…」。趋势、Token 明细和系统状态仍在悬停面板和主菜单里。点面板外或按 Esc 关闭。
109
+ - **有会话等待审批时**,左键改为直接跳到那个会话的终端(会话列表里排第一的那个,处理完再点就是下一个)。
110
+ 按住 ⌥ 点击仍然打开面板;取不到该会话的终端时也照常打开面板。
111
+ - **右键**(或按住 Control 点击)打开和右键桌宠相同的菜单,CC Bridge 开关和**退出**都在里面。
112
+ - 图标是一个带 `>_` 提示符的描边终端窗口,颜色与状态卡同步:待机为菜单栏原色,Agent 工作中为蓝色,
113
+ 任务完成为绿色,失败为红色。等待审批是唯一需要你动手的状态,显示为橙色 `•••`。
114
+ 状态卡回落待机(约 1 分钟没有新事件)时恢复菜单栏原色,因此隐藏桌宠时也能看到 Hook 动态。
115
+ - 图标旁用红色数字显示等待审批的会话数。打开 **菜单栏显示额度** 后会附上订阅账号中最低的
116
+ 5 小时剩余额度,20% 及以下为橙色,10% 及以下为红色;关掉开关后不显示数字,额度低时也一样。
117
+
118
+ **仅菜单栏** 会隐藏桌宠、状态卡、说话气泡、更新气泡和悬停面板。碎碎念直接跳过、不占每小时预算,
119
+ 因此低额度提醒只剩菜单栏数字变色。Agent 状态跟踪、额度采集和系统通知照常运行。
120
+ 最后一个托管 CLI 退出且 Codex 桌面端未运行时,菜单栏图标随桌宠一起消失;独立启动时会保持运行,直到手动退出。
97
121
 
98
122
  ## 互动方式
99
123
 
124
+ ### JetBrains IDE 终端跳转
125
+
126
+ 基于 IntelliJ 平台的 JetBrains IDE(IDEA、PyCharm、WebStorm、GoLand、CLion、PhpStorm、RubyMine、Rider 等)
127
+ 2026.2 / 2026.3 的本地 Reworked 终端可通过 **CC Pets Terminal** 插件精确跳转。
128
+ 在桌宠「设置 → 通用 → 终端跳转」中,每个检测到的 IDE 一行,点「安装」确认后插件会写入该 IDE 的插件目录;
129
+ IDE 正在运行时重启即可加载,打开项目后自动连接,无需配置端口。随 CC Pets 带来新版插件时,该行会显示「更新」。
130
+ 自定义了插件目录(`idea.plugins.path`)的 IDE 退回手动安装:Settings → Plugins → ⚙ → Install Plugin from Disk。
131
+ 每个 IDE 以及稳定版与 EAP 的插件相互独立;Classic 和远程终端暂不支持。
132
+ 详细安装、构建和本机通信说明见 [插件说明](plugins/jetbrains/README.md)。
133
+
134
+ ### VS Code 终端跳转
135
+
136
+ VS Code 1.80+ 及其分支(Cursor、Windsurf、VSCodium、Insiders 等)可通过 **CC Pets Terminal** 扩展
137
+ 精确跳到集成终端,面板、分屏和编辑器区里的终端都支持。在「设置 → 通用 → 终端跳转」中每个检测到的应用一行,
138
+ 点「安装」确认后用该应用自带的命令行工具安装随包 VSIX;已打开的窗口通常自动连接,否则执行「Developer: Reload Window」。
139
+ 没有命令行工具的应用退回手动安装:扩展视图 → ⋯ → 从 VSIX 安装…。未安装扩展时点击卡片只会激活应用;
140
+ 远程窗口(SSH、WSL、容器)暂不支持。详见 [扩展说明](plugins/vscode/README.md)。
141
+
100
142
  ### Agent 工作状态
101
143
 
102
144
  | Agent 事件 | 桌宠反馈 |
103
145
  | --- | --- |
104
- | 新会话启动 | 挥手唤醒 |
146
+ | CLI 新会话启动 | 挥手唤醒 |
105
147
  | 提交用户提示、Agent 思考 | 思考动画 |
106
148
  | 执行 Shell 命令 | 跑动动画 |
107
149
  | 编辑或写入文件 | 工作动画 |
@@ -111,6 +153,7 @@ cc-pets open general # 还有 pet、accounts、alerts、diagnostics
111
153
  | 工具执行成功 | 完成动画 |
112
154
  | 工具执行失败 | 失败动画 |
113
155
  | 当前回合或子 Agent 结束 | 告别后恢复待机 |
156
+ | 当前会话退出 | 切换到其他在线会话或恢复待机,不播放完成动画 |
114
157
 
115
158
  Agent 动画分别由 Codex Hooks 和 Claude Code Hooks 驱动。首次安装或 Codex Hook 内容更新后,启动 Codex 并执行
116
159
  `/hooks`,检查并信任 CC Pets Hook;未经信任的用户级 Hook 会被 Codex 安全机制跳过。
@@ -126,11 +169,15 @@ Claude Code Hook 会合并到 `~/.claude/settings.json`,现有的 `env`、`mod
126
169
  会回退到内核信息:从进程树解析控制终端和承载终端的应用,这些会话的状态卡同样可以点击回跳。
127
170
  这类会话没有 pid 文件,只要 Hook 还在持续发事件就会留在最近会话列表里,闲置 60 秒后移出列表。
128
171
 
172
+ Codex 桌面端的持久化聊天也会出现在会话列表并计入在线数量,按当前应用实例判断存活;后台临时任务不计入。
173
+ 重启桌宠可恢复近期桌面会话记录,不重播动画或通知,未完成的状态恢复为待机。收到会话结束事件后移除该聊天,
174
+ 并切换到其他在线会话或恢复待机;未收到结束事件时,聊天可能保留到桌面应用退出。桌面会话启动不播放 CLI 的启动动画。
175
+
129
176
  所有 Hook 状态卡都可以点击;右侧圆形状态图标会展开最近 8 个在线 Agent 终端会话。
130
- macOS Terminal 和 iTerm2 会按 TTY 精确选中对应标签页或 Session。VS Code、
131
- JetBrains IDE、Warp、WezTerm、Ghostty 等在不安装扩展的模式下仅激活对应应用;应用
132
- 内部标签页是否恢复由应用自身决定。首次回跳 Terminal 或 iTerm2 时,macOS 可能要求
133
- 允许 CC Pets 控制该终端应用。
177
+ macOS Terminal 和 iTerm2 会按 TTY 精确选中对应标签页或 Session,Ghostty 1.4+ 还支持精确选择分屏。
178
+ VS Code 和 JetBrains IDE 通过随包扩展精确选择终端;未安装扩展时,以及 Warp、WezTerm 和旧版 Ghostty,
179
+ 仅前置对应应用。跳转 Terminal、iTerm2 或 Ghostty 时,macOS 可能要求 Automation 权限,
180
+ 可在「设置 → 终端跳转」管理权限与扩展。
134
181
 
135
182
  ### 鼠标互动
136
183
 
@@ -155,9 +202,38 @@ Hook 状态卡和消息气泡在宠物小于 100% 时同比例缩小,文字、
155
202
  右键菜单「面板主题」提供「经典」和「Liquid Glass」,默认使用经典样式。
156
203
  选择后立即应用于额度面板、状态条和说话气泡,并在重启后保留。Liquid Glass 使用系统原生玻璃,
157
204
  仅在 macOS 26 及以上可选;构建原生玻璃支持需要 macOS 26 或更新的 SDK。同一子菜单里的「玻璃压暗」
158
- 可在通透(0%)、轻度(15%)、标准(25%,默认)、清晰(45%)之间切换,作用于额度面板、状态卡和
205
+ 可在通透(0%)、轻度(25%)、标准(50%)、清晰(100%)之间切换,作用于额度面板、状态卡和
159
206
  说话气泡:档位越低越通透,档位越高在浅色背景上越容易看清。
160
207
 
208
+ ### 启动前检查 Shadowrocket
209
+
210
+ 在 **主菜单 → 设置 → 启动保护** 打开「Shadowrocket」开关(默认关闭)。
211
+ 启动保护按软件分别配置,当前提供 Shadowrocket,后续软件可在同一分组增加独立开关。
212
+ 通过 CC Pets 包装器启动 `claude` / `codex` 时,会先确认 Shadowrocket 的系统 VPN
213
+ 状态为已连接,再向对应服务的 `/cdn-cgi/trace` 发起 HTTPS GET,检查出口 IP 和地区;失败会在终端提示原因并返回非零退出码,
214
+ 不会启动 CLI,也不会登记会话或发送启动事件。关闭开关后不进行网络检查。
215
+
216
+ 仅识别 Shadowrocket 的 VPN 配置,不把「应用进程正在运行」当成代理已连接。
217
+ Claude 默认检查 `api.anthropic.com`;Codex 根据当前 Home 的 `auth.json` 选择:ChatGPT 登录检查
218
+ `chatgpt.com`,API Key 登录检查 `api.openai.com`。模式未知(例如凭据仅在 Keychain 中)时,两者都必须通过。
219
+ 返回的 `ip`、`loc`、`h` 必须有效且匹配目标域名;`loc=CN` 或 `HK` 会阻止启动。
220
+ 请求失败、非 HTTP 200、无效响应、未知地区、TLS 错误或超时也会阻止启动;成功时在终端显示域名、出口 IP 和地区。
221
+ 每次尝试连接最多等待 8 秒,请求总计最多 15 秒,外层进程保护时限为 16 秒。
222
+ 临时传输故障或 HTTP 502 / 503 / 504 会间隔 1 秒重试一次,重试前再次确认 VPN 连接状态。
223
+ 两次请求均超时时,每个域名约等待 31 秒,另加 VPN 检查及进程开销。
224
+ 被拦截地区、无效 trace 和证书错误不重试。失败提示区分连接、响应及进程超时,
225
+ 显示尝试次数和 DNS / TCP / TLS / 响应的累计耗时。不再额外做系统 DNS 或首页 HEAD 探测。
226
+ 请求不带账号凭据,正常校验证书,忽略 `~/.curlrc`,不跟随重定向。
227
+
228
+ Claude 支持当前 `CLAUDE_CONFIG_DIR` 下 `settings.json` 中的网络环境变量及终端代理变量,
229
+ 优先使用其中的 `ANTHROPIC_BASE_URL`。Codex 支持 `CODEX_HOME/config.toml` 中常见的单行字符串
230
+ 路由配置(`model_provider`、`profile`、`model_providers.<id>.base_url`、`chatgpt_base_url`)、
231
+ `--profile` / `-p`、`OPENAI_BASE_URL` 和终端代理变量。自定义地址检查同一源站的 `/cdn-cgi/trace`,
232
+ 不回退到其他域名;网关必须提供有效 trace,且结果只代表到网关的出口,不代表网关到上游的出口。
233
+ 复杂路由 TOML、未支持的云服务商、命令行配置覆盖及项目网络覆盖会拒绝检查并提示原因。
234
+ 企业托管网络配置不在支持范围内。此检查不验证账号、密钥或服务支持地区,也不能保证探测后出口不变。
235
+ 直接启动原始 CLI 二进制或桌面客户端不会经过此保护。
236
+
161
237
  ### 界面语言
162
238
 
163
239
  主菜单「设置」页的「语言」提供「跟随系统」和所有已打包的语言,目前是「English」「简体中文」。
@@ -208,12 +284,20 @@ Agent 状态动画会优先播放。
208
284
 
209
285
  Agent 状态卡片会根据屏幕剩余空间自动显示在桌宠上方或下方。点击桌宠旁的圆形箭头可以
210
286
  折叠卡片;折叠后圆钮会显示当前活跃的 Codex/Claude CLI 会话数,点击后重新展开。卡片只展示
211
- Provider、脱敏状态和通用说明,不提供消息输入,也不会显示提示词、命令正文或模型输出。
287
+ 会话标签、脱敏状态和通用说明,不提供消息输入,也不会显示提示词、命令正文或模型输出。
288
+ 标题优先使用 CC Bridge 会话名:自动名称缩写为「目录名.动物」,自定义名称保持原样;
289
+ 没有 Bridge 名称时使用工作目录名,再回退到智能体名称。长标签保留末尾动物后缀,悬停可查看完整会话名和工作目录。
212
290
  连续 1 分钟没有收到新的 Agent 状态事件时,卡片和圆钮会一起自动隐藏;下一次收到事件时
213
291
  会重新显示并重新计时。
214
292
 
293
+ API 用量模式下,月度 Token 趋势将今日用量和记录天数分行显示;悬停可查看当前所选账号的峰值。
294
+ Codex 耗尽标记从采样时起五分钟后失效,从缓存恢复也不会延长有效期。
295
+
215
296
  ## 碎碎念
216
297
 
298
+ 低额度提醒按订阅账号分别跟踪剩余 20%、10%、5% 阈值,注明触发账号,冷却期间排队播报。
299
+ 首次采样、过期额度和 API 用量账号不触发提醒;普通额度台词的槽位使用剩余额度最低的订阅账号。
300
+
217
301
  桌宠会以自己的口吻讲话:Agent 干活时讲的话直接写在状态卡副行上,闲着的时候单独冒气泡。
218
302
  主菜单「宠物」页的「碎碎念」里可以整体开关、调频率、选择台词来源、改台词。
219
303
 
@@ -360,6 +444,22 @@ defaults delete com.universewang.cc-pets CCPetsSpeechCooldown # 交
360
444
  - zsh
361
445
  - Xcode Command Line Tools,可通过 `xcode-select --install` 安装
362
446
 
447
+ ## CC Bridge
448
+
449
+ [CC Bridge](./CC_BRIDGE.zh-CN.md) 是默认关闭的可选功能,让本机 Claude Code / Codex 会话互发消息并预留文件。
450
+ 身份识别优先验证会话 ID;按 PID 回退时只接受唯一在线会话,共享宿主下身份不明确会拒绝操作。
451
+ Codex 消息使用接收方的 Home 投递。
452
+ 多个 Codex 会话共用 app-server PID 时,Agent 在每次 MCP 调用中传入 Bridge hook 提供的当前 `session_id`。
453
+ 更新后需重新连接 MCP,以加载新的工具定义。
454
+
455
+ 中文显示会为自动生成的会话名附加动物别名,发送消息仍使用原始名称或 ref。
456
+ 没有持久化转录的 Codex 临时任务不注册为收件人,但仍执行文件预留检查。
457
+
458
+ 未确认的信箱消息可在异常退出后恢复。输出和确认之间崩溃时可能重复投递同一消息 ID;送达不代表已读或同意。
459
+ 关闭自动唤醒后,已运行的 watcher 也会停止主动取信;关闭 Bridge 后 CLI 拒绝发送、改名和收件。
460
+ 集成未能完整移除时会报错,可排除原因后重试。详细配置与投递边界见使用指南,修复列表见
461
+ [未发布更新记录](./CHANGELOG.zh-CN.md#unreleased)。
462
+
363
463
  ## 安装
364
464
 
365
465
  ### npm 安装
@@ -591,7 +691,7 @@ API 用量模式只替换对应
591
691
  “调用次数”来自本机会话记录:Claude 按请求标识去重,Codex 按去重后的累计 Token 快照计数。
592
692
  某个窗口
593
693
  当前没有额度数据时该列标注"当前无活跃窗口"。卡片上的在线徽章表示该 Provider 是否还有
594
- 运行中的客户端(包装脚本写出的 pid 文件,或该 Provider 最近 60 秒内仍在发事件),与是否
694
+ 运行中的客户端(包装脚本写出的 pid 文件、当前 Codex 桌面应用实例中的持久化聊天,或该 Provider 最近 60 秒内仍在发事件),与是否
595
695
  已采集到额度数据无关;客户端退出后显示"离线",从未采集到数据时显示"等待数据"。经
596
696
  `codex-with-pet` / `claude-with-pet` 启动的会话退出后 3 秒内转为离线;直接运行 `codex` /
597
697
  `claude` 时没有可靠的退出信号,最多需要 60 秒静默才会转为离线。服务端的 Unix 时间戳会使用 Mac 当前系统时区
@@ -711,13 +811,16 @@ PetDex 官方 CLI(`npx petdex install <slug>`)会把素材放在 `~/.petdex/
711
811
 
712
812
  ## 隐私
713
813
 
714
- - Codex 额度通过本机 Codex CLI 启动的官方 App Server 读取,沿用 Codex CLI 自身的登录状态;Codex Token 只从本机 `~/.codex/sessions` 读取(可用 `CC_PETS_CODEX_HOME` 覆盖)。
814
+ - 可选 Shadowrocket 启动保护默认关闭;启用后检查本机 VPN 状态,并向配置的服务 `/cdn-cgi/trace` 端点发起 HTTPS 请求。端点可见连接的出口 IP;请求不携带账号凭据、校验 TLS 且不跟随重定向。路由与支持限制见启动保护章节。
815
+ - Token 统计还会读取本机 Codex SQLite 日志和线程元数据,并在本机缓存派生用量与增量读取游标,不上传这些日志。
816
+ - 已安装的终端扩展仅监听 `127.0.0.1`,并验证本地请求身份;实例元数据与本地访问令牌保存在 `~/Library/Application Support/CC Pets/ide-instances/`,权限仅限本人。扩展安装经确认后写入所选 IDE 的插件或扩展目录;通过脚本跳转终端需要 macOS Automation 权限。
817
+ - Codex 额度通过本机 Codex CLI 启动的官方 App Server 读取,沿用 Codex CLI 自身的登录状态;Codex Token 从本机已登记 Home 的会话记录及 SQLite 数据读取(默认 Home 可用 `CC_PETS_CODEX_HOME` 覆盖)。
715
818
  - Claude 额度只从 Claude Code 传给本机 status line 的 `rate_limits` 字段读取。
716
819
  - 为区分 API 账号和订阅账号,CC Pets 会读取各已登记 Home 中的认证配置(Claude 的 `settings.json`;Codex 的 `auth.json` 和 `config.toml`),并可能在本机运行该 Home 的 `claude auth status` / `codex login status`。只在内存中保留识别出的模式,不保存密钥、邮箱或命令输出。
717
820
  - 诊断页修复前,会把受影响的配置文件和脚本备份到 `~/Library/Application Support/CC Pets/diagnostic-backups/`(仅本人可读),备份只保存在本机。
718
- - Agent Hooks 只向当前用户的临时目录写入桌宠事件和额度缓存。
821
+ - Agent Hooks 向当前用户的临时目录写入脱敏状态事件和额度缓存;事件可包含工作目录、Home 和转录路径,用于会话标签与生命周期跟踪,不包含转录正文。
719
822
  - 额度历史默认关闭;启用后只在本机保留最近 7 天的剩余比例快照。
720
- - 状态气泡和通知只显示 Provider、状态及脱敏工具类别,不显示会话正文。
823
+ - 状态卡显示会话标签、状态及脱敏工具类别,悬停提示可显示完整会话名和工作目录;Agent 通知显示 Provider 和脱敏状态,不显示会话正文。
721
824
  - 项目不上传会话内容、额度、凭据或使用统计,也不包含遥测服务。
722
825
  - 桌宠启动时及 CLI 再次唤起桌宠时会向 npm Registry 查询最新版本号(同一次运行内最多每 10 分钟一次);仅在有新版本时再读取该版本 tag 中已提交的 Release Note,依次尝试 raw.githubusercontent.com、jsDelivr,最后回退到 GitHub Release API。请求不携带任何账号或使用数据。
723
826
  - 右键“退出桌宠”或执行 `cc-pets uninstall` 后,不会继续运行后台守护进程。
@@ -742,6 +845,8 @@ CC Pets 建立的软链,并恢复安装前的 Claude status line;其他用
742
845
 
743
846
  CC Pets 是社区开源项目,与 OpenAI、Anthropic、PetDex 及任何角色版权方不存在隶属、授权
744
847
  或官方合作关系。Codex、ChatGPT、Claude 及相关图标和商标归各自权利人所有。
848
+ 未能读取已安装应用的图标时,会使用随包提供、统一视觉尺寸的 Claude 和 Codex 备用图标。
849
+ 来源及版权归属见[第三方声明](./THIRD_PARTY_NOTICES.zh-CN.md),这些图标不适用本项目的 MIT License。
745
850
 
746
851
  ## License
747
852
 
Binary file
Binary file