coze-bridge 0.4.1 → 0.4.2-beta.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.
Files changed (3) hide show
  1. package/README.md +45 -27
  2. package/dist/index.js +656 -676
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,48 +1,58 @@
1
1
  # coze-bridge
2
2
 
3
- 本机后台 daemon, 把云端 Agent Service 跟本地 AI agent (Claude Code / Codex / OpenClaw) 通过扩展 ACP 协议桥接起来。
3
+ 本机后台 daemon，把云端 Agent Service 与 Claude Code、Codex、OpenClaw、Hermes 等 AI agent 通过扩展 ACP 协议桥接起来。
4
4
 
5
5
  ## 前置依赖
6
6
 
7
7
  - **Node ≥ 22**
8
- - 仅在运行本地 Agent 时，需要安装 `claude` / `codex` / `openclaw` 中至少一个；仅建立设备连接不需要 framework、Agent 或 Project
8
+ - 仅建立设备连接不需要安装 framework，也不要求已有 Agent 或 Project
9
+ - 真正执行本地 Agent 时需要对应运行时：本地 Claude Code、OpenClaw、Hermes 分别依赖可用的 `claude`、`openclaw`、`hermes-acp`；Codex 使用 Bridge 固化的私有运行时
9
10
 
10
11
  ## 用法
11
12
 
13
+ 以下示例统一使用 `npx -y coze-bridge@latest`，不会假设用户已全局安装 CLI；如果已经全局安装，可自行省略此前缀。
14
+
12
15
  ```bash
13
- # 启动 / 复用 daemon, 投递 pair (云端 UI 复制粘贴一行, 唯一保留无 verb 的入口)
16
+ # 启动 / 复用当前 daemon, 投递 pair（默认不注册 OS 保活服务）
14
17
  npx -y coze-bridge@latest --pat-token=<sat_xxx> --pair-code=<xxx>
15
18
 
16
- # 已成功 pair 后，使用落盘 PAT 重建生产环境连接（不重新消费 pair-code）
17
- coze-bridge connect
19
+ # 已成功 pair 后，使用落盘 PAT 重建生产环境连接（默认不注册 OS 保活服务）
20
+ npx -y coze-bridge@latest connect
18
21
 
19
22
  # 切换并持久化 PPE 环境；daemon 被 supervisor 重启后仍恢复该环境
20
- coze-bridge connect --env=ppe_coze_drive
23
+ npx -y coze-bridge@latest connect --env=ppe_coze_drive
21
24
 
22
25
  # 查 daemon 状态
23
- coze-bridge status
26
+ npx -y coze-bridge@latest status
27
+
28
+ # 回收所有 agent 子进程；下次 prompt 按最新环境重新拉起
29
+ npx -y coze-bridge@latest reload
24
30
 
25
- # 停 daemon
26
- coze-bridge stop
31
+ # 保留连接环境，升级到 npm latest，并保持当前手动 / supervisor 托管形态
32
+ npx -y coze-bridge@latest update
27
33
 
28
- # 重新探测本地 agent 路径 / 版本
29
- coze-bridge refresh
34
+ # 注销 OS 保活服务并停止 daemon
35
+ npx -y coze-bridge@latest stop
30
36
 
31
37
  # 清理: 停 daemon + 卸自启 + 删 ~/.coze/bridge (保留 ~/.coze/agents 工作区)
32
- coze-bridge purge
38
+ npx -y coze-bridge@latest purge
33
39
 
34
- # 装 / 卸 OS supervisor 自启 (login 时自动拉起 daemon)
35
- coze-bridge service install
36
- coze-bridge service uninstall
40
+ # 显式注册 OS 保活服务并按平台能力接管 / 注销 supervisor 配置
41
+ npx -y coze-bridge@latest service install
42
+ npx -y coze-bridge@latest service uninstall
37
43
  ```
38
44
 
39
- > 老 flag (`--status` / `--stop` / `--refresh` / `--install-service` / `--uninstall`) 仍能用, 但 stderr 会打 deprecation warn, 后续 major bump 会删。建议切到新子命令形态。
45
+ > 老 flag（`--status` / `--stop` / `--install-service` / `--uninstall`）仍能用，但 stderr 会打印 deprecation warning，后续 major bump 会删除。建议切到新子命令形态。
40
46
  >
41
47
  > 注意 `--uninstall` 在 0.1.67 起映射到新 `purge`: 删除范围从 `~/.coze` 收窄到 `~/.coze/bridge`, 不再误删 `~/.coze/agents/<id>/workspace` 里用户写过的 CLAUDE.md / SOUL.md。完全重置仍可手动 `rm -rf ~/.coze`。
42
48
 
43
- > **保活能力按平台不同**:
44
- > - **macOS / Linux**: 配对成功即由 launchd / systemd 接管 daemon —— 开机自启 + **进程崩溃/被杀也会自动拉起**(KeepAlive / `Restart=always`)。
45
- > - **Windows**: Task Scheduler 仅 **登录时自启**(ONLOGON), **不含崩溃自动重启**(daemon 崩了需重新登录或重新跑一次配对命令恢复)。崩溃自启是已知待办(需 PowerShell 改 Task XML 加 `RestartOnFailure`)。
49
+ > `pair` / `connect` 只启动或复用当前 daemon，不会首次创建 launchd、systemd 或 Task Scheduler 配置。`service install` 是唯一显式注册入口；普通的 `pair`、`connect`、`update` 不会迁移或删除旧版本及此前显式注册的服务。
50
+ >
51
+ > **显式注册后的平台能力**:
52
+ > - **macOS / Linux**: `service install` 会关闭当前手动 daemon，等待单实例锁释放，再由 launchd / systemd 接管；支持开机自启和崩溃拉起（KeepAlive / `Restart=always`）。接管失败会清理本次半成品，并尽量恢复原手动 daemon，但命令仍返回失败。
53
+ > - **Windows**: `service install` 只登记 Task Scheduler 的 **登录时自启**（ONLOGON），不会停止或立即启动 daemon，任务从下次登录起生效；不支持崩溃自动重启。
54
+ >
55
+ > `stop` 会先注销保活服务，再通过 IPC 和进程清理停止 daemon。`service uninstall` 不发送 IPC shutdown，也不扫杀手动 daemon；但 macOS 的 `launchctl unload` 和 Linux 的 `systemctl disable --now` 会停止原本由 supervisor 托管的 daemon。Windows 删除计划任务不会停止当前手动 daemon。
46
56
 
47
57
  ### 配对参数
48
58
 
@@ -60,10 +70,10 @@ coze-bridge service uninstall
60
70
 
61
71
  | Flag | 说明 |
62
72
  |---|---|
63
- | `--agent-id <id>` | pair 成功后自动 connect 该 agent: 本地已有走 reconnect/revive, 没有 (需云端协议升级) 拉详情新建 |
73
+ | `--agent-id <id>` | pair 成功后自动 connect 该 agent：本地已有配置时 reconnect/revive，否则通过 `_agent/detail` 拉取云端详情并在本机注册 |
64
74
 
65
75
  ```bash
66
- npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id>
76
+ npx -y coze-bridge@latest --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id>
67
77
  ```
68
78
 
69
79
  ### 环境路由(可选, 联调时用)
@@ -75,7 +85,7 @@ npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id
75
85
  | `--frontier-url <url>` | 覆盖 Frontier WS URL, 默认 `wss://frontier.coze.cn`；仅当前 daemon 进程生效 |
76
86
 
77
87
  ```bash
78
- npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
88
+ npx -y coze-bridge@latest --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
79
89
  ```
80
90
 
81
91
  成功 pair/connect 后，Bridge 会将 PAT 和 `--env` 写入 `~/.coze/bridge/connection.json`。daemon 被 supervisor 重启时会自动恢复该环境；不带 `--env` 的 pair/connect 明确切回 production，并清除已保存的 PPE/BOE 环境。`--handshake-url`、`--frontier-url` 和 `--mock-scenario` 不持久化。
@@ -84,24 +94,32 @@ npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
84
94
 
85
95
  ## 行为说明
86
96
 
87
- - **daemon 启动自动复活 agents**: `~/.coze/agents/` 里所有未被云端主动 disconnect 的 agent, daemon 启动后会自动 spawn 子进程 + 加入路由, 不需要你一个个 reconnect
97
+ - **daemon 启动恢复 agent 路由**: `~/.coze/agents/` 中未被 disconnect / delete 的 agent 会重新注册到内存；ACP 子进程按需启动，直到收到下一条 prompt 才 lazy spawn，不需要逐个 reconnect
88
98
  - **device 级 10s 批量心跳**: pair 成功后每 10s 上行 1 帧 `_agent/health`；没有 eligible agent 时仍发送 `agents:[]` 维持设备在线，新 Agent 注册后自动切换为正常列表
89
- - **deviceId 不持久化**: 每次 pair 由云端 handshake 接口分配, 切环境 / 重启 daemon 都用新值
90
- - **cloud agent 跟本机 framework 解耦**: `_agent/create` 带 `_meta.cozeDeployType=cloud` 时 Bridge 直接 ack 不 spawn — agent 在云端跑, 本机没装对应 framework 也行
99
+ - **两类 device ID 分开管理**: handshake 返回的连接 `deviceId` 只保存在当前 daemon 内存中，切环境或重启后重新获取；本机稳定硬件 ID 由 Bridge 与桌面端共享在 `~/.coze/desktop/device.json`，`--device-id` 校验的是这份硬件 ID
100
+ - **cloud deploy 仍是本机执行**: `_meta.cozeDeployType=cloud` 表示模型凭证和网关配置由云端下发，不代表 Agent 进程运行在云端；Bridge 仍会在收到 prompt 时 lazy spawn 对应 ACP 进程。cloud Claude Code / Codex 可使用 Bridge 固化的 wrapper，OpenClaw / Hermes 仍需要本机对应运行时
91
101
 
92
102
  ## 工作目录
93
103
 
94
104
  ```
95
105
  ~/.coze/
106
+ ├── desktop/
107
+ │ └── device.json # Bridge 与桌面端共享的稳定硬件设备 ID
96
108
  ├── bridge/ # daemon 文件
97
109
  │ ├── lib/index.js # 固化的 dist (npx 首次执行复制过来)
110
+ │ ├── bin/ # 注入 Agent 子进程 PATH 的同版本 coze-bridge shim
98
111
  │ ├── bridge.pid # PID
99
112
  │ ├── bridge.port # IPC HTTP 端口
100
113
  │ ├── bridge.token # IPC token (mode 0600)
101
114
  │ ├── connection.json # 最近成功连接的 PAT + env (mode 0600)
102
115
  │ ├── pat-token # 旧版 PAT 文件，仅用于兼容 fallback
103
- │ ├── bridge.log
104
- │ └── config.json # frameworks_cache + libVersion (不存 deviceId, 每次 pair 拿)
116
+ │ ├── agent-env.json # pair/connect 捕获的 shell 环境快照 (mode 0600)
117
+ │ ├── config.json # framework 探测缓存 + libVersion；不存 handshake deviceId
118
+ │ ├── model-cache.json # per-framework 模型列表缓存
119
+ │ ├── bridge.log # dated 日志迁移提示；legacy/supervisor 裸输出兜底
120
+ │ └── logs/
121
+ │ ├── bridge-YYYY-MM-DD.log
122
+ │ └── daemon-stdio.log
105
123
  └── agents/<agentId>/ # 每个 agent 一个目录, daemon 重启自动复活
106
124
  ├── config.json # mode 0600 (含 cozeIdentity / model / modelToken / sessions / ...)
107
125
  ├── workspace/ # 子进程 cwd, CLAUDE.md / AGENTS.md / SOUL.md 在这