cc-pets 1.4.8 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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`;写入失败时返回非零退出码。