cc-pets 2.0.0 → 2.0.3

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 (37) hide show
  1. package/CHANGELOG.md +73 -30
  2. package/CHANGELOG.zh-CN.md +90 -0
  3. package/CONTRIBUTING.md +18 -15
  4. package/CONTRIBUTING.zh-CN.md +22 -0
  5. package/LICENSE +1 -1
  6. package/PROVIDER_PROTOCOL.md +50 -41
  7. package/PROVIDER_PROTOCOL.zh-CN.md +58 -0
  8. package/README.md +240 -502
  9. package/README.zh-CN.md +617 -0
  10. package/Resources/Info.plist +2 -0
  11. package/Resources/phrases.default.txt +48 -49
  12. package/SECURITY.md +13 -10
  13. package/SECURITY.zh-CN.md +18 -0
  14. package/Sources/CCPets/CCPetsAppDelegate.h +12 -0
  15. package/Sources/CCPets/CCPetsAppDelegate.m +400 -37
  16. package/Sources/CCPets/CCPetsCodexRateLimits.h +13 -0
  17. package/Sources/CCPets/CCPetsCodexRateLimits.m +383 -0
  18. package/Sources/CCPets/CCPetsEvents.m +7 -2
  19. package/Sources/CCPets/CCPetsPaths.h +4 -0
  20. package/Sources/CCPets/CCPetsPaths.m +6 -0
  21. package/Sources/CCPets/CCPetsPhrases.h +1 -24
  22. package/Sources/CCPets/CCPetsPhrases.m +1 -82
  23. package/Sources/CCPets/CCPetsPhrasesEditor.m +0 -28
  24. package/Sources/CCPets/CCPetsQuotaHistory.m +12 -5
  25. package/Sources/CCPets/CCPetsTerminalFocus.h +11 -0
  26. package/Sources/CCPets/CCPetsTerminalFocus.m +150 -0
  27. package/Sources/CCPets/CCPetsUsage.m +135 -14
  28. package/Sources/CCPets/CCPetsUsageMonitor.m +41 -3
  29. package/Sources/CCPets/PetView.m +19 -11
  30. package/Sources/CCPets/QuotaDashboardView.m +38 -16
  31. package/Sources/CCPets/main.m +5 -0
  32. package/THIRD_PARTY_NOTICES.md +13 -7
  33. package/THIRD_PARTY_NOTICES.zh-CN.md +12 -0
  34. package/bin/claude-with-pet +8 -2
  35. package/bin/codex-with-pet +8 -3
  36. package/package.json +14 -5
  37. package/scripts/pet-store.mjs +1 -1
package/CHANGELOG.md CHANGED
@@ -1,46 +1,89 @@
1
- # 更新记录
1
+ # Changelog
2
2
 
3
- 本项目遵循语义化版本号。版本号以 `package.json` 为唯一来源。
3
+ English | [简体中文](./CHANGELOG.zh-CN.md)
4
+
5
+ This project follows Semantic Versioning. `package.json` is the single source of
6
+ truth for the version.
7
+
8
+ ## [2.0.3] - 2026-09-17
9
+
10
+ Terminal jump-back and session-liveness fixes for agents started outside the wrapper scripts.
11
+
12
+ ### Agent status
13
+
14
+ - Fall back to the kernel when `CC_PETS_TERMINAL_*` is missing: read the controlling terminal through `sysctl(KERN_PROC_PID)` and resolve the host terminal application by walking up the parent process chain, so `claude` / `codex` launched directly can still be jumped back to.
15
+ - Fix sessions without a pid file being declared dead immediately: liveness now prefers the pid file, and falls back to the activity grace window for providers that never wrote one.
16
+
17
+ ## [2.0.2] - 2026-09-11
18
+
19
+ Multi-session agent list, plus session-liveness and Codex usage-trend fixes.
20
+
21
+ ### Agent status
22
+
23
+ - Every hook status card is clickable and returns to the terminal that triggered the event; Terminal.app and iTerm2 are selected precisely by TTY, other terminals fall back to activating the owning application.
24
+ - The circular status icon lists up to eight recent online agent terminal sessions, badges the number of sessions waiting for approval, and pins those sessions to the top of the list.
25
+ - Notify once and pull the card back to the front when an agent sits in approval for 2 minutes or in thinking for 5 minutes; the session re-arms after its next event.
26
+ - The card no longer clears after 60 idle seconds while an approval is outstanding.
27
+ - Fix stale online sessions: a session is online only when its controlling terminal still matches the TTY recorded in the pid file, so orphaned Node processes no longer keep a closed window listed.
28
+
29
+ ### Quota and usage
30
+
31
+ - Fix the usage-trend column being overridden by the pending refresh state while a 7-day percentage is available, and give the rate-limited footnote its own color.
32
+ - Keep official window percentages in quota history while rate limited, so a long-limited provider still has samples to draw a trend curve from.
33
+
34
+ ## [2.0.1] - 2026-09-07
35
+
36
+ Bug fixes for quota display and panel stability.
37
+
38
+ ### Quota and usage
39
+
40
+ - 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.
41
+ - 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.
42
+ - Show a pending refresh state when official quota data is not yet available.
43
+
44
+ ### Pet and interaction
45
+
46
+ - Fix the panel occasionally failing to show.
47
+ - Unify pet speech to first person: the pet now speaks as the agent instead of narrating it from the outside.
4
48
 
5
49
  ## [2.0.0] - 2026-08-23
6
50
 
7
- 首个开源版本。
51
+ First open-source release.
8
52
 
9
- ### 桌宠与互动
53
+ ### Pet and interaction
10
54
 
11
- - macOS 原生 AppKit 桌宠,运行时不依赖 Electron,也不需要 Codex/Claude 桌面端。
12
- - 待机呼吸、随机小动作、拖动滞后与落脚回弹;头部、口袋、脚部和身体两侧的悬停与点击反馈。
13
- - 右键菜单可切换桌宠、刷新用量、开关额度历史与系统通知、检查更新或退出。
14
- - 支持内置素材与 `~/.cc-pets/pets/` 下的外部素材,兼容 `spriteVersionNumber` v1 / v2 网格。
55
+ - Native macOS AppKit desktop pet with no Electron runtime and no dependency on the Codex or Claude desktop apps.
56
+ - Idle breathing, random movements, drag lag and landing bounce, plus hover and click feedback for the head, pocket, feet, and both body sides.
57
+ - The right-click menu can switch pets, refresh usage, toggle quota history and system notifications, check for updates, or exit.
58
+ - Supports built-in assets and external assets under `~/.cc-pets/pets/`, with `spriteVersionNumber` v1 and v2 grids.
15
59
 
16
- ### 额度与用量
60
+ ### Quota and usage
17
61
 
18
- - 从本机 `~/.codex/sessions` 与 Claude Code 官方 status line 数据读取 5 小时额度、周额度和重置时间。
19
- - 悬停口袋展开额度面板,用两张卡分别展示 Codex、Claude 的剩余百分比、本机 Token 与近 7 天趋势。
20
- - 可选记录最近 7 天的本地额度历史;默认关闭,仅保存在本机。
21
- - 支持「订阅额度 / API 用量」两种展示模式。
62
+ - Reads five-hour quota, weekly quota, and reset times from local `~/.codex/sessions` data and Claude Code's official status line input.
63
+ - Hovering over the pocket opens a panel with separate Codex and Claude cards for remaining percentage, local tokens, and seven-day trends.
64
+ - Optionally records seven days of local quota history; disabled by default and stored only on the local machine.
65
+ - Supports Subscription quota and API usage display modes.
22
66
 
23
- ### Agent 状态
67
+ ### Agent status
24
68
 
25
- - 由 Codex Hooks 与 Claude Code Hooks 驱动思考、工具调用、审批、子 Agent、完成与失败动画。
26
- - 桌宠旁显示脱敏后的玻璃状态卡片,可折叠并显示活跃 CLI 会话数。
27
- - 可分别启用任务完成、失败和等待审批的 macOS 系统通知。
28
- - 第三方 CLI Agent 可通过统一 Provider 事件协议接入,详见 `PROVIDER_PROTOCOL.md`。
69
+ - Codex Hooks and Claude Code Hooks drive animations for thinking, tool calls, approvals, subagents, completion, and failure.
70
+ - Displays a redacted glass status card beside the pet, which can be collapsed and shows the active CLI session count.
71
+ - macOS notifications can be enabled separately for completion, failure, and approval requests.
72
+ - Third-party CLI agents can integrate through the unified Provider event protocol; see [`PROVIDER_PROTOCOL.md`](./PROVIDER_PROTOCOL.md).
29
73
 
30
- ### 台词
74
+ ### Speech
31
75
 
32
- - 桌宠台词全部来自 `~/.cc-pets/speech.txt`,可在内置编辑器中修改,支持实时数据槽位。
33
- - 可为单只宠物写专属台词(`~/.cc-pets/speech/<宠物名>.txt`),按小节整体覆盖通用台词。
34
- - 四档碎碎念频率,Agent 工作期间不插嘴。
76
+ - All pet speech comes from `~/.cc-pets/speech.txt`, can be edited in the built-in editor, and supports live data placeholders.
77
+ - Per-pet speech can be stored at `~/.cc-pets/speech/<pet-name>.txt` and replaces global speech by section.
78
+ - Includes four speech-frequency levels and stays silent while an agent is working.
35
79
 
36
- ### 安装与集成
80
+ ### Installation and integration
37
81
 
38
- - `npm install -g cc-pets` 自动构建原生应用、安装两套 Hooks 与 shell 集成,并安装
39
- `~/Applications/CC Pets.app`。
40
- - 通过 `~/.cc-pets/shims` 下的软链接管 `codex` / `claude`,任意大小写写法都能拉起桌宠。
41
- - `cc-pets install` / `uninstall` / `uninstall-app` 提供可重复执行的初始化与清理流程。
82
+ - `npm install -g cc-pets` builds the native app, installs both hook integrations and shell integration, and installs `~/Applications/CC Pets.app`.
83
+ - Symlinks under `~/.cc-pets/shims` intercept `codex` and `claude`, including casing variants, to start the pet.
84
+ - `cc-pets install`, `uninstall`, and `uninstall-app` provide repeatable initialization and cleanup flows.
42
85
 
43
- ### 隐私
86
+ ### Privacy
44
87
 
45
- - 不上传会话内容、额度、凭据或使用统计,不包含遥测。
46
- - 状态卡片与通知只显示 Provider、状态类别和脱敏后的工具类别。
88
+ - Uploads no conversations, quotas, credentials, or usage statistics and contains no telemetry.
89
+ - Status cards and notifications show only the provider, state category, and redacted tool category.
@@ -0,0 +1,90 @@
1
+ # 更新记录
2
+
3
+ [English](./CHANGELOG.md) | 简体中文
4
+
5
+ 本项目遵循语义化版本号。版本号以 `package.json` 为唯一来源。
6
+
7
+ ## [2.0.3] - 2026-09-17
8
+
9
+ 修复未经包装脚本启动的 Agent 的终端回跳与会话存活判定。
10
+
11
+ ### Agent 状态
12
+
13
+ - 缺少 `CC_PETS_TERMINAL_*` 时回退到内核信息:通过 `sysctl(KERN_PROC_PID)` 读取控制终端,并沿父进程链向上找到宿主终端应用,直接启动的 `claude` / `codex` 也能回跳。
14
+ - 修复没有 pid 文件的会话被立即判定为离线的问题:存活判定优先使用 pid 文件,从未写过 pid 文件的 provider 回退到活动宽限窗口。
15
+
16
+ ## [2.0.2] - 2026-09-11
17
+
18
+ 多会话 Agent 列表,以及会话存活判定与 Codex 用量趋势修复。
19
+
20
+ ### Agent 状态
21
+
22
+ - 所有 Hook 状态卡都可点击并返回触发事件的终端;Terminal 和 iTerm2 按 TTY 精确选中,其他终端回退为激活所属应用。
23
+ - 圆形状态图标可展开最近 8 个在线 Agent 终端会话,并以角标显示等待审批的会话数,这些会话在列表中置顶。
24
+ - Agent 停在等待审批超过 2 分钟、或停在思考态超过 5 分钟时提醒一次,并把状态卡重新推到眼前;该会话有新事件后重新武装。
25
+ - 存在未处理的审批时,状态卡不再在闲置 60 秒后清空。
26
+ - 修复在线会话残留:只有控制终端仍与 pid 文件中记录的 TTY 一致时才算在线,关闭窗口后残留的 Node 孤儿进程不再让会话一直挂在列表里。
27
+
28
+ ### 额度与用量
29
+
30
+ - 修复 7 天百分比可用时,用量趋势列仍被「等待刷新」覆盖的问题;限流脚注使用独立配色。
31
+ - 限流期间保留官方窗口百分比写入额度历史,长期限流的 provider 仍有样本可以绘制趋势曲线。
32
+
33
+ ## [2.0.1] - 2026-09-07
34
+
35
+ 额度显示与面板稳定性问题修复。
36
+
37
+ ### 额度与用量
38
+
39
+ - 从 Codex App Server 读取实时额度窗口,并叠加到本机聚合的 Token 用量上;后台保持长连接,处理刷新、通知、超时与降级回退。
40
+ - 修复额度重置后 Codex 额度不再显示的问题:过期的会话额度窗口现在会独立丢弃,耗尽状态在重置前后也能正确保留。
41
+ - 官方额度数据尚不可用时,显示“等待刷新”状态。
42
+
43
+ ### 桌宠与互动
44
+
45
+ - 修复面板偶尔无法显示的问题。
46
+ - 统一宠物台词视角为第一人称:由“宠物旁观 Agent”调整为“宠物即 Agent”。
47
+
48
+ ## [2.0.0] - 2026-08-23
49
+
50
+ 首个开源版本。
51
+
52
+ ### 桌宠与互动
53
+
54
+ - macOS 原生 AppKit 桌宠,运行时不依赖 Electron,也不需要 Codex/Claude 桌面端。
55
+ - 待机呼吸、随机小动作、拖动滞后与落脚回弹;头部、口袋、脚部和身体两侧的悬停与点击反馈。
56
+ - 右键菜单可切换桌宠、刷新用量、开关额度历史与系统通知、检查更新或退出。
57
+ - 支持内置素材与 `~/.cc-pets/pets/` 下的外部素材,兼容 `spriteVersionNumber` v1 / v2 网格。
58
+
59
+ ### 额度与用量
60
+
61
+ - 从本机 `~/.codex/sessions` 与 Claude Code 官方 status line 数据读取 5 小时额度、周额度和重置时间。
62
+ - 悬停口袋展开额度面板,用两张卡分别展示 Codex、Claude 的剩余百分比、本机 Token 与近 7 天趋势。
63
+ - 可选记录最近 7 天的本地额度历史;默认关闭,仅保存在本机。
64
+ - 支持「订阅额度 / API 用量」两种展示模式。
65
+
66
+ ### Agent 状态
67
+
68
+ - 由 Codex Hooks 与 Claude Code Hooks 驱动思考、工具调用、审批、子 Agent、完成与失败动画。
69
+ - 桌宠旁显示脱敏后的玻璃状态卡片,可折叠并显示活跃 CLI 会话数。
70
+ - 可分别启用任务完成、失败和等待审批的 macOS 系统通知。
71
+ - 第三方 CLI Agent 可通过统一 Provider 事件协议接入,详见
72
+ [`PROVIDER_PROTOCOL.zh-CN.md`](./PROVIDER_PROTOCOL.zh-CN.md)。
73
+
74
+ ### 台词
75
+
76
+ - 桌宠台词全部来自 `~/.cc-pets/speech.txt`,可在内置编辑器中修改,支持实时数据槽位。
77
+ - 可为单只宠物写专属台词(`~/.cc-pets/speech/<宠物名>.txt`),按小节整体覆盖通用台词。
78
+ - 四档碎碎念频率,Agent 工作期间不插嘴。
79
+
80
+ ### 安装与集成
81
+
82
+ - `npm install -g cc-pets` 自动构建原生应用、安装两套 Hooks 与 shell 集成,并安装
83
+ `~/Applications/CC Pets.app`。
84
+ - 通过 `~/.cc-pets/shims` 下的软链接管 `codex` / `claude`,任意大小写写法都能拉起桌宠。
85
+ - `cc-pets install` / `uninstall` / `uninstall-app` 提供可重复执行的初始化与清理流程。
86
+
87
+ ### 隐私
88
+
89
+ - 不上传会话内容、额度、凭据或使用统计,不包含遥测。
90
+ - 状态卡片与通知只显示 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
- 建议先开一个 GitHub 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 UniverseWang
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.
@@ -0,0 +1,58 @@
1
+ # CC Pets Provider 事件协议
2
+
3
+ [English](./PROVIDER_PROTOCOL.md) | 简体中文
4
+
5
+ 第三方 CLI Agent 可以通过标准输入向 CC Pets 写入统一状态事件,从而复用状态气泡、
6
+ 桌宠动画和可选的系统通知。协议只接收状态类别和工具类别,不接收提示词、命令正文、
7
+ 文件内容或模型输出。
8
+
9
+ ## 发送事件
10
+
11
+ ```bash
12
+ printf '%s' '{
13
+ "schemaVersion": 1,
14
+ "provider": "MyAgent",
15
+ "state": "tool",
16
+ "tool": "shell"
17
+ }' | cc-pets provider-event
18
+ ```
19
+
20
+ `provider` 必填,最长 32 个字符,仅保留字母、数字、空格、`.`、`_` 和 `-`。
21
+ `tool` 可选,最长 64 个字符,仅用于选择脱敏后的状态文案和动画。
22
+
23
+ `state` 必须是下列值之一:
24
+
25
+ | state | 含义 |
26
+ | --- | --- |
27
+ | `starting` | 会话开始 |
28
+ | `thinking` | Agent 思考 |
29
+ | `tool` | 工具开始执行 |
30
+ | `approval` | 等待用户审批 |
31
+ | `subagent` | 子 Agent 工作中 |
32
+ | `tool_completed` | 单次工具执行完成 |
33
+ | `tool_failed` | 单次工具执行失败 |
34
+ | `completed` | 当前任务完成 |
35
+ | `failed` | 当前任务失败 |
36
+ | `notification` | 需要用户关注 |
37
+
38
+ 建议工具类别使用 `shell`、`edit`、`write`、`read`、`search`、`web`、`mcp` 或
39
+ `agent`。CC Pets 不会执行 `tool` 字段,也不会将其作为通知正文。
40
+
41
+ ## 状态显示规则
42
+
43
+ 事件到达顺序不一定等于语义顺序,气泡显示因此有两条额外规则:
44
+
45
+ - **终态具有黏性。** 进入 `completed` 或 `failed` 后,紧随其后的 `tool_completed`
46
+ (以及内部的 `SubagentStop`、`TaskCompleted`)不会改写气泡——这类尾巴事件常常在任务
47
+ 真正结束之后才到达。要解除终态,请发送 `thinking`、`tool`、`approval` 或
48
+ `notification` 等表示新一轮动作的状态。
49
+ - **`starting` 是短时态。** 超过 8 秒没有后续事件,气泡会自动落到"待机中",表示会话
50
+ 已就绪、正在等待输入。长时间的准备工作请显式发送 `thinking`,不要停留在 `starting`。
51
+
52
+ ## 生命周期
53
+
54
+ 事件写入当前用户的临时状态目录,已经运行的 CC Pets 会立即读取。Provider 集成需要自行
55
+ 负责启动和关闭 CC Pets;事件协议不会创建后台守护进程,也不会改变现有 Codex/Claude CLI
56
+ 的托管生命周期。
57
+
58
+ 协议版本不兼容或字段无效时,命令返回退出码 `2`;写入失败时返回非零退出码。