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/CC_BRIDGE.md CHANGED
@@ -66,13 +66,33 @@ The agent uses these MCP tools:
66
66
  | Tool | Description |
67
67
  | --- | --- |
68
68
  | `list_agents` | Lists online sessions: name [ref], CLI, busy/idle, terminal (tty), start time, directory. The name is the address; add ` [ref]` only when names collide. |
69
- | `send_message` | Sends a message. With `notify_when_idle: true`, you get a one-shot notice when the recipient next finishes a turn. |
69
+ | `send_message` | Sends a message. With `notify_when_idle: true`, you get a one-shot notice when the recipient next finishes a turn. That doesn't mean it has handled this message. |
70
70
  | `set_name` | Renames the current session. |
71
71
  | `reserve_files` | Reserves files or directories you are about to edit (globs supported); returns conflicts when they overlap with other reservations. |
72
72
  | `release_files` | Releases this session's reservations. |
73
73
  | `list_reservations` | Lists reservations in the current repository, or who reserved a given file. |
74
74
  | `check_inbox` | Reads the inbox manually. Messages are normally delivered automatically. |
75
75
 
76
+ ### Current session identity
77
+
78
+ Every MCP tool accepts an optional `session_id` identifying the caller. Bridge supplies the current ID
79
+ in `SessionStart` and `UserPromptSubmit` hook context; agents should pass that exact value on each call.
80
+ For an existing session without this context, read `CODEX_THREAD_ID` (Codex) or
81
+ `CLAUDE_CODE_SESSION_ID` (Claude) from that session's own shell. Do not use a recipient's ID, guess
82
+ from the online list, or hard-code one session's ID in shared MCP configuration.
83
+
84
+ Multiple Codex sessions can share an app-server PID. When MCP does not inherit a session ID, the
85
+ argument distinguishes the caller. Each call independently validates the registration, live status,
86
+ provider and host PID; the MCP process never caches the selected identity. An invalid explicit ID,
87
+ one belonging to another host, or one that can't be checked because the MCP host process can't be
88
+ identified is rejected with the reason and without falling back to another identity. Calls without
89
+ the argument retain environment-based identification and unique PID matching for existing single-session
90
+ clients. Anonymous session listing remains available when identity cannot be resolved, but `list_reservations`
91
+ returns an error because the repository to check is unknown.
92
+
93
+ After updating, reconnect the CC Bridge MCP server (or restart its client) to load the new binary
94
+ and tool definitions with `session_id`.
95
+
76
96
  ### Session names
77
97
 
78
98
  Default names look like `<account>.<project-directory>.<animal>`, for example `claude.my-app.otter` or
@@ -119,12 +139,14 @@ Claude / Codex sessions for wording changes to take effect (MCP instructions loa
119
139
  | Notify a session | Use cc-bridge to tell api the login endpoint is now POST /api/login and returns a token; update the frontend call |
120
140
  | Hand off a task | Ask web to write unit tests for src/api/login.ts and report back |
121
141
  | Get an answer back | Ask api how far the database migration has gone, and have it reply through cc-bridge |
122
- | Wait until it's done | Tell api to run the test suite, and notify you when it goes idle |
142
+ | Wait for a result | Tell api to run the test suite and send you the result through cc-bridge |
143
+ | See when it's idle | Message api and have it notify you when it goes idle |
123
144
  | Target by terminal | Send this to the Claude session in ttys003: … |
124
145
 
125
146
  Replies arrive as new messages in your session. "Notify you when it goes idle" sends a one-shot
126
- notice once the recipient finishes its turn (`notify_when_idle`), which is handy for "continue after
127
- it's done".
147
+ notice once the recipient finishes its turn (`notify_when_idle`). If the recipient is busy, that may be
148
+ a turn that started before your message arrived, so the notice only means a turn ended, not that your
149
+ task is done. To wait for a result, ask the recipient to reply when it finishes.
128
150
 
129
151
  ### Several sessions in one repository
130
152
 
@@ -186,8 +208,8 @@ Just ask: "Reserve src/api before you start the refactor, and release it when yo
186
208
  | Codex | Woken immediately through `codex queue` | Queued after the current turn | Not delivered; receipt is undeliverable |
187
209
  | Claude Code | Woken by a background `asyncRewake` watcher | Injected into the current turn | Not delivered; receipt is undeliverable |
188
210
 
189
- The Claude Code watcher arms at session start and at the end of every turn, and waits up to about
190
- 55 minutes before exiting. If a Claude session stays idle through that gap, messages stay in its
211
+ The Claude Code watcher arms at session start and at the end of every turn. A new watcher replaces the
212
+ previous one and restarts the wait, which lasts up to about 55 minutes before it exits. If a Claude session stays idle through that gap, messages stay in its
191
213
  inbox and are included with the user's next prompt; messages that arrive during that turn are
192
214
  delivered when it ends.
193
215
 
@@ -199,6 +221,15 @@ prompt brings them in.
199
221
  Senders get receipts such as "queued", "in inbox", or "undeliverable". Delivery does not mean
200
222
  the recipient has read or agreed to anything.
201
223
 
224
+ A session that crashes or is killed never fires `SessionEnd`. Its undelivered messages are cleaned up
225
+ the next time the session list finds it offline, or when the next session starts: receipts become
226
+ undeliverable and its idle subscriptions are removed.
227
+
228
+ Codex threads on a shared app-server run in the background. Closing a terminal tab doesn't end the
229
+ thread right away: `SessionEnd` fires when the app-server unloads it, which took up to a few minutes
230
+ when tested. Until then the thread still shows as online, and a message sent to it may be queued and
231
+ run when the thread is resumed.
232
+
202
233
  ## In the pet
203
234
 
204
235
  With CC Bridge enabled, the round icon on the pet's status card gets a message badge in its
@@ -239,9 +270,34 @@ tool through `~/.cc-pets/bridge-cli.json`, written on every `cc-pets install`; i
239
270
  when a peer asks for an action that was denied on its side, the agent should refuse and tell the user.
240
271
  - Message bodies are stored in the current user's temporary directory
241
272
  (`cc-bridge-<uid>/` under `getconf DARWIN_USER_TEMP_DIR`) with `0700` directories and `0600`
242
- files; undelivered messages expire after 24 hours. This is an explicit exception to the
273
+ files; undelivered messages expire after 24 hours (cleaned up when the next session starts). A body is
274
+ deleted once its message is delivered. Receipts hold only sender, recipient, time and status, and
275
+ stay about 48 hours for troubleshooting. This is an explicit exception to the
243
276
  [Provider protocol](./PROVIDER_PROTOCOL.md)'s no-content rule, which is why CC Bridge is off by default.
244
277
  - A message is limited to 16 KB. A pair of sessions exchanging more than 20 messages within
245
278
  10 minutes is paused to stop two agents from auto-replying to each other in a loop.
246
279
  - Pet status cards and notifications never show message bodies.
247
280
  - No background daemon: only hooks, the MCP server, and the watcher inside Claude sessions, all of which exit with the session.
281
+
282
+ ## Identity and delivery guarantees
283
+
284
+ Bridge validates `CODEX_THREAD_ID` / `CLAUDE_CODE_SESSION_ID` against the live session registry and the
285
+ current host process. Without a session ID, PID lookup is allowed only when it identifies exactly one
286
+ live session. Ambiguous shared hosts and stale explicit IDs fail closed for sending, renaming, reading
287
+ inboxes and managing reservations. CLI diagnostics can select a session explicitly with
288
+ `--from <session-name-or-full-session-id>`; with `send`, put it before the message.
289
+
290
+ Claimed inbox messages remain on disk until the complete output has been flushed successfully.
291
+ A later hook, watcher or `check_inbox` recovers unconfirmed messages after a crash. A crash between
292
+ output and confirmation may deliver the same message ID again; the host provides no acknowledgement
293
+ protocol, so exactly-once delivery is not guaranteed. When `codex queue` times out, Bridge can't tell
294
+ whether the message was queued, so it also goes to the inbox and the sender is told it may arrive
295
+ twice with the same ID. Codex queue delivery uses the recipient's Home.
296
+ Legacy records with an unknown Home fall back to the inbox until registration is refreshed by input
297
+ in that session.
298
+
299
+ Existing watchers recheck the enabled and auto-wake switches while polling. Disabling Bridge also
300
+ blocks CLI send, rename and inbox operations. Integration removal failures return a nonzero exit code;
301
+ the runtime remains disabled, and `disable` can be retried after resolving the reported errors.
302
+ `disable` deletes all undelivered messages and marks their receipts undeliverable. Delivered receipts
303
+ contain no message body and stay for their normal retention period.
@@ -48,6 +48,10 @@ cc-pets bridge configure --edit-guard=off # 关闭编辑前预留拦截
48
48
  | `--wake=on\|off` | 自动唤醒空闲会话,默认开。关闭后消息只进信箱,等对方下次收到你的输入时带入,可省 token |
49
49
  | `--edit-guard=on\|off` | 编辑他人预留的文件时暂停一次,默认开 |
50
50
 
51
+ 运行中的 watcher 会在轮询时检查关闭状态;关闭自动唤醒后不再主动取信,关闭 Bridge 后 CLI 也拒绝发送、改名和收件。
52
+ 卸载集成失败会返回非零退出码,运行时开关仍保持关闭,可排除错误后再次执行 `disable`。
53
+ `disable` 会删除所有未投递的消息,回执标记为 undeliverable;已送达的回执不含正文,按保留期留作记录。
54
+
51
55
  Claude 侧的改动会被热加载;Codex 侧(审批、hooks)需要重启 Codex 会话,hooks 变化后还要在 `/hooks` 中重新信任。
52
56
 
53
57
  ## 使用
@@ -61,13 +65,27 @@ Agent 会调用这些 MCP 工具:
61
65
  | 工具 | 说明 |
62
66
  | --- | --- |
63
67
  | `list_agents` | 列出在线会话:名字 [ref]、CLI、忙闲、所在终端(tty)、启动时间、目录。名字就是地址;只有重名时才需要写成 `名字 [ref]`。 |
64
- | `send_message` | 发消息;`notify_when_idle: true` 时,对方下次完成回合后你会收到一条一次性空闲通知。 |
68
+ | `send_message` | 发消息;`notify_when_idle: true` 时,对方下次完成回合后你会收到一条一次性空闲通知。这不代表对方已处理这条消息。 |
65
69
  | `set_name` | 修改当前会话的名字。 |
66
70
  | `reserve_files` | 预留即将修改的文件或目录(支持 glob),与他人预留重叠时返回冲突列表。 |
67
71
  | `release_files` | 释放本会话的预留。 |
68
72
  | `list_reservations` | 查看当前仓库的所有预留,或某个文件被谁预留。 |
69
73
  | `check_inbox` | 手动读取信箱。正常情况下消息会自动送达,一般不需要调用。 |
70
74
 
75
+ ### 当前会话身份
76
+
77
+ 所有 MCP 工具都支持可选的 `session_id` 参数,用来标识调用者。Bridge 在 `SessionStart` 和
78
+ `UserPromptSubmit` hook 的上下文中提供当前 ID,Agent 应在每次调用中原样传入;旧会话缺少该上下文时,
79
+ 可从当前会话 shell 的 `CODEX_THREAD_ID`(Codex)或 `CLAUDE_CODE_SESSION_ID`(Claude)读取。
80
+ 不要使用收件人的 ID、从在线列表猜测,或把某个会话的 ID 固定写进共享 MCP 配置。
81
+
82
+ Codex 的多个会话可以共用一个 app-server PID;MCP 未继承会话 ID 时,必须通过参数区分调用者。
83
+ 每次调用独立校验注册记录、在线状态、provider 和宿主 PID,不在 MCP 进程中缓存会话身份。
84
+ 显式 ID 无效或不属于当前宿主时直接报错,错误信息会说明原因;识别不出 MCP 的宿主进程时同样拒绝。这些情况都不回退到其他身份。未传参数时保留环境变量及 PID 唯一匹配,
85
+ 兼容原来的单会话模式;无法识别时仍允许匿名查看会话列表,但 `list_reservations` 会报错,因为无从确定该查哪个仓库。
86
+
87
+ 更新后需要重新连接 CC Bridge MCP(或重启使用它的客户端),才能加载新程序和带 `session_id` 的工具定义。
88
+
71
89
  ### 会话名
72
90
 
73
91
  默认名字是 `<账号名>.<项目目录名>.<动物>`,例如 `claude.my-app.otter`、`claude-x.my-app.panda`。账号名取多账号页里的名称
@@ -110,11 +128,13 @@ CC_BRIDGE_NAME=api codex
110
128
  | 通知对方 | 用 cc-bridge 告诉 api:登录接口改成了 POST /api/login,返回字段加了 token,你那边同步改一下前端调用 |
111
129
  | 分派任务 | 让 web 帮忙写 src/api/login.ts 的单元测试,写完告诉我结果 |
112
130
  | 要对方回复 | 问一下 api 数据库迁移做到哪一步了,让它用 cc-bridge 回复你 |
113
- | 等对方做完 | 给 api 发消息让它跑一遍测试,并在它空闲时通知你 |
131
+ | 等对方回复 | 给 api 发消息让它跑一遍测试,跑完用 cc-bridge 把结果发给你 |
132
+ | 看对方何时空闲 | 给 api 发消息,并在它空闲时通知你 |
114
133
  | 按终端指定 | 发给 ttys003 那个 Claude 会话:…… |
115
134
 
116
135
  对方的回复会作为一条新消息出现在当前会话里。"在它空闲时通知你"会让对方这一轮做完后,
117
- 当前会话收到一条一次性的空闲通知(`notify_when_idle`),适合"等它做完我再继续"。
136
+ 当前会话收到一条一次性的空闲通知(`notify_when_idle`)。对方忙碌时,这一轮可能是收到消息前就在进行的回合,
137
+ 所以通知只表示对方结束了一个回合,不代表你的任务已完成。要等结果,请让对方做完后回复你。
118
138
 
119
139
  ### 多个会话改同一个仓库
120
140
 
@@ -143,6 +163,13 @@ CC_BRIDGE_NAME=api codex
143
163
  - 开启 CC Bridge 之前就在运行的 Claude 会话能收消息,但没有这些工具,只能在 shell 里用 `cc-pets bridge send` 回复;重启一下最省事。
144
164
  - 留意桌宠:状态图标右下角出现蓝色数字,说明会话之间有往来;点开能看到谁发给了谁,点一下即跳到对应终端(见下文)。
145
165
 
166
+ ### 身份识别与共享宿主
167
+
168
+ Bridge 优先验证当前进程提供的 `CODEX_THREAD_ID` / `CLAUDE_CODE_SESSION_ID`,包括注册记录、
169
+ 在线状态和宿主是否一致。没有会话 ID 时,仅允许宿主 PID 唯一匹配一个在线会话。
170
+ 多个会话共享 PID 且缺少可靠 ID,或显式 ID 已失效时,会明确拒绝发送、改名、收件和文件预留等操作,
171
+ 不会按最近活跃时间猜测。CLI 排查时可用 `--from <会话名或完整会话 ID>` 显式指定身份;`send` 的 `--from` 要写在正文之前。
172
+
146
173
  ## 文件预留
147
174
 
148
175
  多个 Agent 在同一个仓库里工作时,最怕两个会话同时改同一个文件。文件预留让 Agent 在开始较大的修改前
@@ -165,7 +192,7 @@ CC_BRIDGE_NAME=api codex
165
192
  | Codex | 通过 `codex queue` 立即唤醒 | 排在当前回合之后处理 | 不投递,回执为 undeliverable |
166
193
  | Claude Code | 后台 watcher 通过 `asyncRewake` 唤醒 | 注入当前回合 | 不投递,回执为 undeliverable |
167
194
 
168
- Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多等待约 55 分钟后自动退出。
195
+ Claude Code 的 watcher 在会话启动和每轮结束时挂上,新挂上的会取代旧的并重新计时,最多等待约 55 分钟后自动退出。
169
196
  如果 Claude 会话在这段空窗期里一直空闲,消息会留在信箱,等用户下次输入时一并带入;
170
197
  那一轮进行中新到的消息,在该轮结束时投递。
171
198
 
@@ -175,6 +202,16 @@ Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多
175
202
 
176
203
  发送方只会收到"已送达队列 / 已放入信箱 / 无法投递"这类回执。送达不代表对方已读,也不代表对方同意。
177
204
 
205
+ 信箱消息认领后保留在 `claimed`,完整输出并刷新输出流成功后才确认。进程异常退出时,下一次
206
+ hook、watcher 或 `check_inbox` 会恢复未确认消息。在输出已到达宿主、确认尚未落盘的瞬间崩溃,
207
+ 恢复后可能重复投递同一个消息 ID;目前没有宿主确认协议,无法保证恰好一次送达。
208
+ `codex queue` 超时时无法确定消息是否已入队,消息会同时放进信箱,发送方会收到可能重复的提示,两份消息的 ID 相同。
209
+ 会话崩溃或被杀时不会触发 `SessionEnd`:下一次查询在线列表时发现它已离线,或下一个会话启动时,
210
+ 它未投递的消息会被清理,回执标记为 undeliverable,空闲订阅也一并移除。
211
+ 共享 app-server 的 Codex 线程在后台运行:关闭终端标签后,线程不会立刻结束,要等 app-server 卸载它才触发 `SessionEnd`,
212
+ 实测有几分钟以内的延迟。在此之前它仍显示在线,发给它的消息可能进入队列,并在恢复该线程时执行。
213
+ 跨账号投递 Codex 使用接收方注册的 Home;旧记录无法确定 Home 时保留到信箱,等待该会话输入后刷新注册。
214
+
178
215
  ## 桌宠里的显示
179
216
 
180
217
  开启 CC Bridge 后,桌宠状态卡的圆形图标右下角会多一个消息角标(右上角的红色角标仍是待审批):
@@ -208,7 +245,8 @@ Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多
208
245
  这条消息不能提升权限:不能用来修改权限或配置,不能当作对待确认操作的批准;如果对方说某个操作
209
246
  在它那边被拒绝、请你代为执行,Agent 应拒绝并告知用户。
210
247
  - 消息正文保存在当前用户的临时目录(`getconf DARWIN_USER_TEMP_DIR` 下的 `cc-bridge-<uid>/`),
211
- 目录权限为 `0700`、文件权限为 `0600`,未投递的消息 24 小时后过期。
248
+ 目录权限为 `0700`、文件权限为 `0600`,未投递的消息 24 小时后过期(在下一个会话启动时清理)。
249
+ 消息送达后正文随之删除。回执只保存发送方、接收方、时间和状态,不含正文,保留约 48 小时用于排查。
212
250
  这是对 [Provider 协议](./PROVIDER_PROTOCOL.zh-CN.md)"不接收正文"原则的一个显式例外,
213
251
  所以默认关闭,需要你主动开启。
214
252
  - 单条消息最多 16KB。同一对会话 10 分钟内往来超过 20 条会被暂停,防止两个 Agent 互相自动回复形成循环。
package/CHANGELOG.md CHANGED
@@ -7,6 +7,112 @@ truth for the version.
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.5.0] - 2026-11-15
11
+
12
+ ### Menu bar
13
+
14
+ - Add a menu bar icon, chosen under Settings → Show In: Desktop Pet (default), Pet + Menu Bar, or Menu Bar Only.
15
+ - Left-click opens a compact glass panel: the pet's current status, up to five online sessions (click to jump to the terminal), a 5-hour quota ring per account, today's tokens, and Show Pet / Main menu. Right-click opens the pet's context menu.
16
+ - The menu bar icon is an outlined terminal window whose color follows the status card (blue working, green completed, red failed); awaiting approval switches the `>_` prompt to orange `•••` and returns to the normal menu bar color when the card goes back to idle. Plan accounts are listed before API accounts in the panel.
17
+ - While a session awaits approval, left-clicking the icon jumps straight to its terminal; ⌥-click opens the panel.
18
+ - The icon shows the number of sessions awaiting approval and, optionally, the lowest 5-hour quota left (orange at 20% or below, red at 10%). The number follows the switch only.
19
+ - Menu Bar Only hides the pet and its status card, bubbles and hover panel. Chatter is skipped without using its budget; tracking and notifications continue.
20
+ - The phrases editor's Try a Line explains that the pet is hidden in Menu Bar Only.
21
+
22
+ ### Status card
23
+
24
+ - Show the session instead of the agent in the title ("session · status"), so concurrent sessions can be told apart at a glance. With CC Bridge enabled the label is `directory.animal` (for example `cc-pets.crab`); otherwise it is the working directory name, falling back to the agent name when neither is known. Long labels are truncated in the middle and keep the trailing animal suffix.
25
+ - Hovering the status card shows the full session name and working directory.
26
+ - Accept optional working-directory metadata in provider events for session labels and tooltips, falling back to the event command's current directory.
27
+
28
+ ### CC Bridge
29
+
30
+ - Show Chinese animal aliases alongside automatically generated session names in Chinese UI, CLI output, messages and notifications. Keep original names and refs as message addresses; custom names remain unchanged.
31
+ - Exclude transient Codex tasks without persisted transcripts from message-recipient registration while retaining their pre-edit file reservation checks.
32
+ - Accept a per-call `session_id` in MCP tools, supplied through session-start and user-prompt hook context, so Codex sessions sharing an app-server PID can identify themselves when MCP does not inherit a session ID. Explicit identities must pass live-registration and host checks; retain single-session auto-detection, reject invalid IDs and never cache caller identity.
33
+ - Keep `config.toml` byte-for-byte outside CC Bridge's own managed block, including blank lines inside multi-line strings and marker-like text.
34
+ - Recognize CLI hosts from structured argv so paths containing spaces work. Rejected `session_id` values now report why, and an unverifiable host is still rejected.
35
+ - Serialize reservation creation, renewal, acknowledgement, release and expiry so concurrent sessions can't miss conflicts or lose updates.
36
+ - Detect overlaps between directories and globs, such as `src/api` and `src/**/*.ts`, by checking whether a common path exists.
37
+ - Clean up after sessions that exit without `SessionEnd`: mark undelivered messages undeliverable, expire old messages and receipts, and remove idle subscriptions.
38
+ - Reject invalid `paths` in `release_files` without changing any reservation.
39
+ - Make send limits atomic so concurrent sessions can't exceed them.
40
+ - Resolve symlinks in repository roots and reserved paths, including new files and globs, so reservations match however a session reached the directory.
41
+ - Keep the newest deliveries in the pet's badge and notifications when receipts exceed the scan limit.
42
+ - Use the same online check in the pet as in the CLI.
43
+ - Report the right count in the "and N more" delivery notification.
44
+ - Recognize only real `mcp_servers` declarations when uninstalling, so matching text in project paths no longer causes false removal errors.
45
+ - Treat `--from` after the first two `send` arguments as message text, and reject unknown options and flags missing a value.
46
+ - Stop treating patch-like text in written content as edited files, and skip `git` when no reservations exist.
47
+ - Answer MCP requests with invalid UTF-8 with a parse error instead of no response.
48
+ - Return an error from `list_reservations` when the caller is unknown instead of checking the MCP process directory.
49
+ - Stop storing message bodies in receipts, so a body is deleted once its message is delivered.
50
+ - Delete undelivered messages on `disable` and mark their receipts undeliverable.
51
+ - When `codex queue` times out, keep the inbox fallback and warn the sender that the message may arrive twice.
52
+ - `release_files` with an empty `paths` array now releases nothing; omit `paths` to release everything.
53
+ - Skip inbox locking while the watcher's inbox is empty, and clarify what `notify_when_idle` guarantees.
54
+ - Let each new watcher replace the previous one and restart the wait, so active sessions stay wakeable for about 55 minutes after every turn.
55
+ - Enqueue under the inbox lock and recheck that Bridge is on and the recipient is online, so a slow send can't leave a body behind after `disable` or a session exit.
56
+ - Follow symlinks before resolving `..` in reserved paths, and recognize quoted `mcp_servers` keys at every level when uninstalling.
57
+
58
+ ### Session lifecycle
59
+
60
+ - Match shared-host Codex terminal launches against unique TUI readiness records within one second before or after session creation, covering initial frames logged just after creation without guessing between concurrent clients.
61
+ - Track persistent Codex desktop chats against the current app instance, include them in online counts, and keep the pet running while Codex desktop is open after the last managed CLI exits. Ignore transient background tasks and restore recent desktop records without replaying animations or notifications.
62
+ - Record Codex session-end hooks, remove ended sessions and pending approvals, and switch the displayed session or return to idle without a completion animation. Ignore trailing events after a turn completes.
63
+ - Preserve profile-ID separators and normalize legacy IDs so account matching stays consistent. Track managed CLI exits per session instead of excluding other sessions from the same provider.
64
+
65
+ ## [2.4.0] - 2026-11-03
66
+
67
+ ### Diagnostics
68
+
69
+ - Distinguish local source packages, local npm packages and unknown local package locations in Diagnostics, copied reports and `cc-pets paths`. Local version mismatch warnings no longer imply that a version has been published on npm; published updates are checked separately.
70
+
71
+ ### Terminal jump and settings
72
+
73
+ - Add exact terminal selection for JetBrains 2026.2 / 2026.3 Reworked terminals through the bundled plugin, including terminals moved into editor tabs. Classic terminals, remote development and split subterminals are outside the supported scope. Ghostty 1.4+ selects tabs and splits by TTY; iTerm2 selects sessions by TTY. Automation permission is required for script-based terminal jumps.
74
+ - Put Panel Appearance first in Settings, with compact theme tiles and a live Liquid Glass dimming preview. Dimming is displayed as 0–100 while retaining the existing internal range; menu presets are 0/25/50/100. Combine terminal integration states in one card, group versions of the same JetBrains product and collapse lists longer than five rows.
75
+
76
+ ### Pet management
77
+
78
+ - Delete pets from the user's own folder directly on the Main menu's Pet page, using a hover button or context menu and a confirmation dialog. Built-in pets and the currently selected pet are protected. Refresh the picker when pets are added or removed through the CLI, Finder or the pet menu.
79
+
80
+ ### Token accounting
81
+
82
+ - Correct Codex cache-write double counting and migrate existing daily archives. Incrementally include background usage from local Codex SQLite logs, excluding sessions already represented by persisted transcripts. Background totals do not invent an input/output/cache breakdown.
83
+ - Keep individual chart series and colors for every model instead of folding models after the eighth into Other. Restore native tooltips for usage metrics.
84
+
85
+ ### VS Code terminal jump
86
+
87
+ - Add the CC Pets Terminal extension for VS Code 1.80+ and its forks (Cursor, Windsurf, VSCodium, …). Clicking an agent card selects the exact integrated terminal by TTY — in the panel, a split or the editor area — and brings its window forward by reopening that window's workspace, switching Spaces when needed. Forks are recognised by `product.json`, not a bundle ID list. Remote windows are not supported; without the extension the app is only brought forward, as before.
88
+ - Settings → Terminal Jump lists each VS Code family app with install, update, reload-needed and disabled states. Install runs the app's own command line tool on the bundled VSIX after confirmation, with a manual "Install from VSIX…" fallback. The VSIX is built reproducibly with macOS tools only (`scripts/build-vscode-extension.sh`).
89
+
90
+ ### Build reliability
91
+
92
+ - Replace cached and uncached executables atomically after signing and verification, including the App's executable. This fixes macOS signature-related termination after in-place overwrites that could break Hooks, CLI launch and tests. Builds now check CLI execution before reporting success; early test failures report their phase, location and exit status.
93
+
94
+ ### CC Bridge
95
+
96
+ - Validate explicit session IDs before PID lookup and reject ambiguous shared-host identities instead of selecting the most recently active session. This protects messaging, renaming, inbox access and file reservations.
97
+ - Retain claimed inbox messages until output is flushed successfully, recover unconfirmed messages after crashes, and prevent delivered receipts from reverting to pending. Recovery can repeat a message ID if a crash occurs between output and confirmation; exactly-once delivery is not guaranteed.
98
+ - Serialize session updates and renaming, use kernel-backed watcher locks, and preserve numeric suffixes when allocating duplicate 40-character session names.
99
+ - Recheck enabled and auto-wake settings in running watchers, reject CLI mutations while disabled, and report integration removal failures with a nonzero exit code while keeping the runtime disabled.
100
+ - Use the recipient's Codex Home for queue delivery, recognize literal bracketed file paths such as `[id]` in reservation checks, and preserve account and sender IDs for Bridge activity display.
101
+ - Shorten the cross-session message envelope to a source line, a one-line permission notice and a reply address that includes the sender's ref. MCP instructions now ask the receiving session to reply to the originating session with `send_message` when it needs clarification or finishes the request.
102
+
103
+ ### Launch protection
104
+
105
+ - Added an optional Shadowrocket launch check under **Main menu → Settings → Launch Protection** (off by default). Before registering a session or sending a starting event, wrappers verify the VPN connection and request each service's `/cdn-cgi/trace`. Mainland China (CN), Hong Kong (HK), unknown exits and failed requests block launch; successful checks show the exit IP and region.
106
+ - Claude defaults to `api.anthropic.com`; Codex selects `chatgpt.com` or `api.openai.com` from its `auth.json` login mode, checking both when unknown. Common user-level endpoint settings are supported; custom endpoints must return valid trace data, with no unrelated-domain fallback. Removed separate DNS / homepage HEAD probes. Requests send no account credentials, verify TLS, ignore `~/.curlrc` and do not follow redirects. See README for complex configuration, project override and cloud-provider limitations. Launches bypassing wrappers are not checked.
107
+ - Exit checks allow 8 seconds to connect and 15 seconds per request, with a 16-second process watchdog. Temporary transport failures and HTTP 502 / 503 / 504 retry once after 1 second. Failures report the timeout phase, attempt count and cumulative connection timings. Wrapper tests use a fresh preferences domain per run, keeping real VPN settings and network probes out of ordinary tests while preserving compile caching and phase timing.
108
+
109
+ ### Quota and interface
110
+
111
+ - Track low-quota speech independently for each subscription account at the 20%, 10% and 5% thresholds. Queue reminders during cooldown, identify the triggering account, skip the first sample and expired windows, and exclude API-usage accounts. General quota placeholders use the account with the least remaining quota.
112
+ - Apply the same Codex live-usage merge to default and custom Homes. Expire exhaustion markers from their original sampling time so repeated cache reads cannot extend their five-minute lifetime.
113
+ - Simplify the monthly token trend layout: show today's usage and recorded days on separate lines, with peak usage in a tooltip for the selected account.
114
+ - Normalize provider icon sizing and bundle fallback Claude and Codex icons for CLI-only installations. Include them in native builds and npm packages, and document their sources and separate ownership in the third-party notices.
115
+
10
116
  ## [2.3.0] - 2026-10-21
11
117
 
12
118
  ### Installation
@@ -6,6 +6,112 @@
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [2.5.0] - 2026-11-15
10
+
11
+ ### 菜单栏
12
+
13
+ - 新增菜单栏图标,在「设置 → 显示位置」选择:仅桌宠(默认)、桌宠 + 菜单栏、仅菜单栏。
14
+ - 左键打开精简的玻璃面板:宠物当前状态、最多 5 个在线会话(点击跳到终端)、每个账号一个 5 小时额度环、今日用量,以及显示桌宠、主菜单。右键打开与桌宠相同的右键菜单。
15
+ - 菜单栏图标是带 `>_` 的描边终端窗口,颜色与状态卡同步(工作中蓝、完成绿、失败红),等待审批时 `>_` 换成橙色 `•••`,状态卡回落待机时恢复原色。面板中订阅账号排在 API 账号之前。
16
+ - 有会话等待审批时,左键点图标直接跳到该会话的终端;按住 ⌥ 点击打开面板。
17
+ - 图标旁显示等待审批的会话数,可选显示最低的 5 小时剩余额度(20% 及以下橙色,10% 及以下红色),是否显示只看开关。
18
+ - 仅菜单栏时隐藏桌宠及其状态卡、气泡和悬停面板。碎碎念直接跳过、不占预算;状态跟踪和系统通知照常。
19
+ - 仅菜单栏时,台词编辑器的「试说一句」会提示桌宠已隐藏。
20
+
21
+ ### 状态卡
22
+
23
+ - 标题由「智能体 · 状态」改为「会话 · 状态」,多个会话同时运行时能直接看出是哪一个。开启 CC Bridge 时显示「目录名.动物」(如 `cc-pets.crab`),否则显示工作目录名;取不到时仍显示智能体名称。过长的标签截掉中间、保留末尾的动物后缀。
24
+ - 悬停状态卡显示完整会话名和工作目录。
25
+ - Provider 事件支持可选的工作目录信息,用于会话标签与悬停提示;未提供或无效时回退到事件命令的当前目录。
26
+
27
+ ### CC Bridge
28
+
29
+ - 中文界面、CLI 输出、消息与通知为自动生成的会话名附加中文动物别名;消息寻址仍使用原始名称和 ref,自定义名称保持不变。
30
+ - 没有持久化转录的 Codex 临时任务不再注册为消息收件人,但仍执行编辑前的文件预留检查。
31
+ - MCP 工具支持逐次传入 `session_id`,由会话启动及用户输入 hook 提供当前身份,修复多个 Codex 会话共用 app-server PID 且 MCP 未继承会话 ID 时无法识别调用者的问题。显式身份须通过在线注册及宿主校验;保留单会话自动识别,拒绝无效 ID 且不缓存调用者身份。
32
+ - `config.toml` 只改 CC Bridge 自身的管理块,其余内容逐字保留,包括多行字符串里的空行和形似标记的文本。
33
+ - 通过结构化 argv 识别 CLI 宿主,修复路径含空格时识别失败的问题。`session_id` 被拒绝时会说明原因,无法验证宿主时仍然拒绝。
34
+ - 文件预留的创建、续期、确认、释放和过期删除改为串行执行,避免并发会话漏检冲突或丢失更新。
35
+ - 通过判断是否存在共同路径来检测目录与 glob 的重叠,例如 `src/api` 与 `src/**/*.ts`。
36
+ - 补全未触发 `SessionEnd` 就退出的会话的清理:未投递消息标记为 undeliverable,过期消息和回执收尾,并移除空闲订阅。
37
+ - `release_files` 收到非法 `paths` 时报错,且不改动任何预留。
38
+ - 发送限额改为原子操作,并发会话不会越过上限。
39
+ - 解析仓库根和预留路径中的软链,包括新文件和 glob,无论会话从哪条路径进入目录,预留都能对上。
40
+ - 回执数超过扫描上限时,桌宠的角标和通知仍保留最新送达的消息。
41
+ - 桌宠与 CLI 使用同一套在线判断规则。
42
+ - 修正送达通知里“另外 N 条”的数量。
43
+ - 卸载时只识别真正的 `mcp_servers` 声明,项目路径中的相同文字不再导致误报移除失败。
44
+ - `send` 前两个参数之后的 `--from` 视为消息正文;未知选项和缺值的参数会报错。
45
+ - 写入内容里形似补丁的文本不再算作被编辑的文件;没有预留时跳过 `git` 调用。
46
+ - 含非法 UTF-8 的 MCP 请求返回解析错误,不再没有响应。
47
+ - 调用者身份未知时,`list_reservations` 返回错误,不再查询 MCP 进程所在目录。
48
+ - 回执不再保存消息正文,消息送达后正文即被删除。
49
+ - `disable` 时删除未投递的消息,回执标记为 undeliverable。
50
+ - `codex queue` 超时时仍回退到信箱,并提示发送方消息可能到达两次。
51
+ - `release_files` 传空数组时不再释放任何预留;不传 `paths` 才会全部释放。
52
+ - watcher 在信箱为空时不再加锁,并明确 `notify_when_idle` 的保证范围。
53
+ - 新 watcher 取代旧的并重新计时,活跃会话在每轮结束后约 55 分钟内都能被唤醒。
54
+ - 入信箱时持有信箱锁,并复查 Bridge 开关和收件方在线状态,发送缓慢时不会在 `disable` 或会话退出后留下正文。
55
+ - 预留路径先解析软链再处理 `..`;卸载时识别每一级都带引号的 `mcp_servers` 键。
56
+
57
+ ### 会话生命周期
58
+
59
+ - 共享宿主下的 Codex 终端匹配改为查询会话创建前后一秒内唯一的 TUI 就绪记录,兼容首帧稍晚于会话创建才记录的情况,多个客户端并发时仍不猜测归属。
60
+ - 按当前应用实例跟踪 Codex 桌面端的持久化聊天,将其计入在线数量;最后一个托管 CLI 退出后,Codex 桌面端仍运行时保留桌宠。过滤后台临时任务,恢复近期桌面会话记录时不重播动画或通知。
61
+ - 记录 Codex 会话结束 Hook,清理已结束会话和待审批记录,并切换展示会话或直接恢复待机,不误播完成动画;回合完成后的尾随事件不再覆盖终态。
62
+ - 保留账号 ID 的分隔符并兼容旧格式,修复账号匹配;按具体会话跟踪托管 CLI 退出,避免误排除同一 Provider 的其他会话。
63
+
64
+ ## [2.4.0] - 2026-11-03
65
+
66
+ ### 诊断
67
+
68
+ - 诊断页、复制报告与 `cc-pets paths` 区分本地源码包、本地 npm 包及无法确认来源的本地包。版本不一致提示明确比较本地安装,不再让人误以为对应版本已在 npm 发布;线上版本仍由更新检查单独查询。
69
+
70
+ ### 终端跳转与设置
71
+
72
+ - 通过随包插件精确选择 JetBrains 2026.2 / 2026.3 Reworked 终端,支持移入编辑器标签页的终端;Classic 终端、远程开发及分屏内子终端不在支持范围内。Ghostty 1.4+ 按 TTY 选择标签页和分屏,iTerm2 按 TTY 选择会话;通过脚本跳转的终端需要 Automation 权限。
73
+ - 设置页将面板外观置顶,缩小主题卡片,并提供 Liquid Glass 压暗实时预览。压暗显示为 0–100,内部范围保持不变,菜单预设调整为 0/25/50/100。终端集成状态合并到一张卡片,同一 JetBrains 产品的多个版本合并展示,超过五行时折叠。
74
+
75
+ ### 宠物管理
76
+
77
+ - 主菜单「宠物」页可通过悬停按钮或右键菜单删除用户素材目录内的宠物,删除前弹窗确认;内置宠物与当前选中的宠物受保护。通过 CLI、Finder 或桌宠菜单增删素材后,列表会刷新。
78
+
79
+ ### Token 统计
80
+
81
+ - 修复 Codex cache write 重复计数并迁移已有按日归档;从本机 Codex SQLite 日志增量补充后台用量,排除已由持久化会话记录覆盖的部分。后台用量仅计入总量,不推算 input/output/cache 明细。
82
+ - 每个模型保留独立图表序列与颜色,第八个之后不再合并为 Other;用量指标恢复原生 tooltip。
83
+
84
+ ### VS Code 终端跳转
85
+
86
+ - 新增 VS Code 1.80+ 及其分支(Cursor、Windsurf、VSCodium 等)的 CC Pets Terminal 扩展。点击 Agent 卡片时按 TTY 精确选中集成终端,面板、分屏和编辑器区均支持;通过重新打开该窗口的工作区把对应窗口前置,必要时切换桌面。分支按 `product.json` 识别,不维护 bundle ID 名单。远程窗口不支持;未安装扩展时仍只激活应用。
87
+ - 「设置 → 终端跳转」按应用列出 VS Code 家族,显示安装、更新、需要重新加载和已禁用等状态。确认后调用应用自带的命令行工具安装随包 VSIX,失败时可手动「从 VSIX 安装…」。VSIX 仅用 macOS 自带工具可复现构建(`scripts/build-vscode-extension.sh`)。
88
+
89
+ ### 构建可靠性
90
+
91
+ - 缓存与无缓存构建均在签名校验后原子替换可执行文件,覆盖裸 CLI 和 App 内的程序,修复原地覆盖导致 macOS 因签名问题终止进程、连带 Hook、CLI 启动和测试失败的问题。构建报告成功前检查 CLI 能否执行;测试提前失败时显示阶段、位置与退出码。
92
+
93
+ ### CC Bridge
94
+
95
+ - 优先验证显式会话 ID;按 PID 回退时遇到共享宿主的多个会话会拒绝操作,不再按最近活跃时间猜测身份,覆盖发消息、改名、收件和文件预留。
96
+ - 信箱消息在完整输出并刷新输出流成功前保留,异常退出后恢复未确认消息;已送达回执不会被迟到的更新覆盖为待投递。输出与确认之间崩溃时可能重复投递同一消息 ID,不保证恰好一次送达。
97
+ - 会话更新和改名串行化,watcher 改用内核锁;为重名的 40 字符会话名分配新名字时保留数字后缀,避免死循环。
98
+ - 运行中的 watcher 持续检查启用和自动唤醒开关;关闭后 CLI 拒绝修改操作;集成卸载失败返回非零退出码,运行时仍保持关闭。
99
+ - Codex 队列投递使用接收方的 Home;文件预留检查正确处理 `[id]` 等带方括号的真实路径;Bridge 活动展示保留账号和发送方会话 ID。
100
+ - 精简跨会话消息封装:只保留来源行、一行降权说明和带 ref 的回复地址;MCP 说明要求接收方在需要补充信息或任务完成时,用 `send_message` 回复来源会话。
101
+
102
+ ### 启动保护
103
+
104
+ - 新增可选的 Shadowrocket 启动检查,位于「主菜单 → 设置 → 启动保护」,默认关闭。包装器在登记会话、发送 starting 事件之前检查 VPN 连接状态,并分别请求服务的 `/cdn-cgi/trace`。中国大陆(CN)、香港(HK)、未知出口及请求失败均阻止启动;成功显示出口 IP 和地区。
105
+ - Claude 默认检查 `api.anthropic.com`;Codex 按 `auth.json` 的登录模式检查 `chatgpt.com` 或 `api.openai.com`,模式未知时检查两者。支持用户级常见端点配置;自定义地址必须返回有效 trace,不回退到无关域名。移除独立 DNS / 首页 HEAD 探测,不携带账号凭据、校验 TLS 证书、忽略 `~/.curlrc`、不跟随重定向。复杂配置、项目网络覆盖及云服务商的支持边界见 README;绕过包装器的启动不受保护。
106
+ - 出口检测调整为连接时限 8 秒、单次请求时限 15 秒、进程保护时限 16 秒;临时传输故障和 HTTP 502 / 503 / 504 间隔 1 秒重试一次。失败时显示超时阶段、尝试次数及连接累计耗时。包装器测试每轮使用独立偏好域,避免读取真实 VPN 设置并发起网络探测,保留编译缓存和阶段计时。
107
+
108
+ ### 额度与界面
109
+
110
+ - 低额度台词按订阅账号分别记录 20%、10%、5% 阈值,冷却时排队,播报注明触发账号;首次采样、过期额度和 API 用量账号不触发提醒。普通额度槽位使用剩余额度最低的账号。
111
+ - 默认和自定义 Home 统一合并 Codex 实时额度;耗尽标记按原始采样时间计算五分钟有效期,重复读取缓存不再延长有效期。
112
+ - 简化月度 Token 趋势排版,今日用量和记录天数分行显示,峰值移入当前所选账号的悬浮提示。
113
+ - 统一服务商图标的视觉尺寸;为仅安装 CLI 的环境随原生构建和 npm 包提供 Claude、Codex 备用图标,并在第三方声明中说明来源及独立版权归属。
114
+
9
115
  ## [2.3.0] - 2026-10-21
10
116
 
11
117
  ### 安装
package/CONTRIBUTING.md CHANGED
@@ -13,6 +13,28 @@ Thank you for contributing to CC Pets. Before submitting a change:
13
13
  For a substantial feature, open a GitHub Issue before sending a Pull Request so the
14
14
  scope can be agreed on first.
15
15
 
16
+ ## Build and test cache
17
+
18
+ `npm run build` and `npm test` share object files and linked binaries under
19
+ `.build/clang-cache/cc-pets`. Changes to sources, project headers, compiler flags,
20
+ the toolchain, or SDK invalidate the cache; temporary output paths do not.
21
+ Empty-resource builds, normal builds, and installation checks still refresh resources
22
+ and signatures. Every test runs each time; passing results are never cached.
23
+ Logs show compilation progress, compiled/reused counts, test phases, and elapsed time.
24
+ Executables are staged on the destination filesystem, ad-hoc signed and verified, then
25
+ atomically renamed into place. This also applies when the cache is disabled; executable
26
+ files must not be overwritten in place on macOS. Builds check that the resulting CLI can
27
+ run `--version`, and early test failures report their phase, location, and exit status.
28
+
29
+ The test runner assigns a fresh `CC_PETS_PREFERENCES_DOMAIN` on every run. Changing
30
+ `HOME` alone does not isolate macOS `CFPreferences`. Launch protection defaults to off
31
+ in this domain, so wrapper and shim tests do not depend on your VPN or live exit probes.
32
+
33
+ Use `CC_PETS_NO_BUILD_CACHE=1 npm run build` or `CC_PETS_NO_BUILD_CACHE=1 npm test`
34
+ to bypass the cache and compile with the original clang command. This does not read
35
+ or write this cache. The existing `cc-pets clean` command removes these artifacts
36
+ along with the application's other caches.
37
+
16
38
  ## Branch and release policy
17
39
 
18
40
  Develop, test, and prepare preview releases on `publish`. Preview releases must be
@@ -21,7 +43,7 @@ Install preview builds explicitly; the automatic updater accepts stable versions
21
43
  `main` is reserved for stable releases, including the stable GitHub Release and tag.
22
44
  Complete implementation, documentation, screenshots, and validation on `publish`
23
45
  before submitting to `main`; repeat integration checks there before a stable release.
24
- The latest stable GitHub release is **v2.3.0**, covering the Main menu, multiple accounts, token usage by model, and the native runtime.
46
+ The latest stable GitHub release is **v2.4.0**, covering exact terminal jumps, optional launch protection, CC Bridge reliability, token accounting, and clearer local version diagnostics.
25
47
  See [release status](docs/release-status.md) for validation and handoff details.
26
48
 
27
49
  ## Localization
@@ -12,6 +12,23 @@
12
12
 
13
13
  建议先开一个 GitHub Issue 描述较大的功能改动,达成一致后再提交 Pull Request。
14
14
 
15
+ ## 构建与测试缓存
16
+
17
+ `npm run build` 与 `npm test` 共用 `.build/clang-cache/cc-pets` 下的目标文件和链接产物。
18
+ 源码、项目头文件、编译参数、工具链或 SDK 变化时自动失效;临时输出目录的变化不影响复用。
19
+ 空素材构建、正常构建和安装测试仍会更新资源与签名,所有测试每次都执行,不缓存通过结果。
20
+ 日志显示当前编译文件、编译/复用数量、测试阶段及耗时。
21
+ 可执行文件先在目标文件系统中暂存,完成临时签名与校验后再原子替换;关闭缓存时也使用此流程,
22
+ 避免在 macOS 上原地覆盖可执行文件。构建完成前确认 CLI 可以执行 `--version`,
23
+ 测试提前失败时输出所属阶段、代码位置与退出码。
24
+
25
+ 测试入口每轮设置全新的 `CC_PETS_PREFERENCES_DOMAIN`。仅修改 `HOME` 无法隔离 macOS
26
+ `CFPreferences`;独立偏好域中的启动保护默认关闭,包装器和 shim 测试不依赖本机 VPN 或真实出口探测。
27
+
28
+ 需要绕过缓存完整重编译时,使用 `CC_PETS_NO_BUILD_CACHE=1 npm run build`,
29
+ 或 `CC_PETS_NO_BUILD_CACHE=1 npm test`。该开关直接使用原始 clang 命令,不读写这份缓存。
30
+ 缓存位于现有构建缓存目录内,`cc-pets clean` 清理应用缓存时也会一并清理它。
31
+
15
32
  ## 分支与发布规则
16
33
 
17
34
  在 `publish` 完成开发、修改、测试和测试版本准备。测试版本必须在 GitHub 标记为
@@ -19,7 +36,7 @@ prerelease,并使用如 `2.2.1-rc.1` 的预发布版本号。`main` 仅负责
19
36
  GitHub Release 和 tag。提交到 `main` 前,代码、文档、截图与验证必须全部完成;
20
37
  在 `main` 完成集成验证后才能发布正式版本。
21
38
  测试版本需显式安装,自动更新器只接受正式版本号。
22
- 当前 GitHub 正式版本为 **v2.3.0**,包含主菜单、多账号、按模型统计 Token 用量与原生运行时。
39
+ 当前 GitHub 正式版本为 **v2.4.0**,包含终端精准跳转、可选启动保护、CC Bridge 可靠性改进、Token 统计修正及更清晰的本地版本诊断。
23
40
  验证和交接状态见[发布状态](docs/release-status.md)。
24
41
 
25
42
  ## 多语言
@@ -4,7 +4,7 @@ English | [简体中文](./PROVIDER_PROTOCOL.zh-CN.md)
4
4
 
5
5
  Third-party CLI agents can write normalized status events to CC Pets through
6
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
7
+ notifications. The protocol accepts status, tool categories, and working-directory metadata. It does not
8
8
  accept prompts, command text, file contents, or model output.
9
9
 
10
10
  ## Sending an event
@@ -22,6 +22,10 @@ printf '%s' '{
22
22
  letters, digits, spaces, `.`, `_`, and `-`. `tool` is optional, has a maximum length
23
23
  of 64 characters, and is used only to select redacted status text and animation.
24
24
 
25
+ `cwd` is optional and supplies the working directory for the session label and tooltip.
26
+ It must be an absolute path of at most 1,024 UTF-16 code units without control characters.
27
+ If omitted or invalid, CC Pets uses the event command's current working directory.
28
+
25
29
  `state` must be one of these values:
26
30
 
27
31
  | State | Meaning |
@@ -3,7 +3,7 @@
3
3
  [English](./PROVIDER_PROTOCOL.md) | 简体中文
4
4
 
5
5
  第三方 CLI Agent 可以通过标准输入向 CC Pets 写入统一状态事件,从而复用状态气泡、
6
- 桌宠动画和可选的系统通知。协议只接收状态类别和工具类别,不接收提示词、命令正文、
6
+ 桌宠动画和可选的系统通知。协议接收状态类别、工具类别和工作目录信息,不接收提示词、命令正文、
7
7
  文件内容或模型输出。
8
8
 
9
9
  ## 发送事件
@@ -20,6 +20,9 @@ printf '%s' '{
20
20
  `provider` 必填,最长 32 个字符,仅保留字母、数字、空格、`.`、`_` 和 `-`。
21
21
  `tool` 可选,最长 64 个字符,仅用于选择脱敏后的状态文案和动画。
22
22
 
23
+ `cwd` 可选,用于会话标签和悬停提示。必须是绝对路径,最长 1,024 个 UTF-16 码元,
24
+ 且不能含控制字符。未提供或无效时,使用事件命令的当前工作目录。
25
+
23
26
  `state` 必须是下列值之一:
24
27
 
25
28
  | state | 含义 |