coze-bridge 0.2.4-alpha.102 → 0.2.4-alpha.11

package/README.md

@@ -5,7 +5,7 @@
 ## 前置依赖
 
 - **Node ≥ 20**
-- 本机至少装好 `claude` / `codex` / `openclaw` 中的一个
+- 仅在运行本地 Agent 时，需要安装 `claude` / `codex` / `openclaw` 中至少一个；仅建立设备连接不需要 framework、Agent 或 Project
 
 ## 用法
 
@@ -13,6 +13,12 @@
 # 启动 / 复用 daemon, 投递 pair (云端 UI 复制粘贴一行, 唯一保留无 verb 的入口)
 npx -y coze-bridge@latest --pat-token=<sat_xxx> --pair-code=<xxx>
 
+# 已成功 pair 后，使用落盘 PAT 重建生产环境连接（不重新消费 pair-code）
+coze-bridge connect
+
+# 切换并持久化 PPE 环境；daemon 被 supervisor 重启后仍恢复该环境
+coze-bridge connect --env=ppe_coze_drive
+
 # 查 daemon 状态
 coze-bridge status
 
@@ -44,9 +50,12 @@ coze-bridge service uninstall
 |---|---|
 | `--pat-token <sat_xxx>` | coze PAT token, 从 coze 平台拿 |
 | `--pair-code <xxx>` | 配对码, 从云端 UI 拿 |
+| `--device-id <id>` | 云端 Device / Project / Agent 定向重连命令提供的稳定硬件 ID；Bridge 会校验本机 ID，不应手工修改 |
 
 支持 `--name VALUE` 与 `--name=VALUE` 两种写法。
 
+通用首次配对命令可以在没有 Agent、Project 或 framework 时直接执行。云端已有设备或本地项目需要重连时，平台返回的命令会追加 `--device-id`；Bridge 只把它用于本机身份校验，不会改变 `_agent/pair` 协议。
+
 ### 自动 connect 某个 agent(可选)
 
 | Flag | 说明 |
@@ -62,17 +71,21 @@ npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --agent-id=<your-agent-id
 | Flag | 说明 |
 |---|---|
 | `--env <value>` | `ppe_*` 走 `x-use-ppe: 1` + `x-tt-env`; `boe_*` 仅 `x-tt-env` |
-| `--handshake-url <url>` | 覆盖 HTTP base, 默认 `https://www.coze.cn` |
-| `--frontier-url <url>` | 覆盖 Frontier WS URL, 默认 `wss://frontier.coze.cn` |
+| `--handshake-url <url>` | 覆盖 HTTP base, 默认 `https://www.coze.cn`；仅当前 daemon 进程生效 |
+| `--frontier-url <url>` | 覆盖 Frontier WS URL, 默认 `wss://frontier.coze.cn`；仅当前 daemon 进程生效 |
 
 ```bash
 npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
 ```
 
+成功 pair/connect 后，Bridge 会将 PAT 和 `--env` 写入 `~/.coze/bridge/connection.json`。daemon 被 supervisor 重启时会自动恢复该环境；不带 `--env` 的 pair/connect 明确切回 production，并清除已保存的 PPE/BOE 环境。`--handshake-url`、`--frontier-url` 和 `--mock-scenario` 不持久化。
+
+默认 HTTP/Frontier URL 只表示接入地址，不代表最终一定路由到生产环境；PPE/BOE 由 `x-tt-env`（PPE 同时使用 `x-use-ppe: 1`）决定。
+
 ## 行为说明
 
 - **daemon 启动自动复活 agents**: `~/.coze/agents/` 里所有未被云端主动 disconnect 的 agent, daemon 启动后会自动 spawn 子进程 + 加入路由, 不需要你一个个 reconnect
-- **device 级 10s 批量心跳**: pair 成功后每 10s 上行 1 帧 `_agent/health`, 装该 device 下所有 eligible agent (`agents:[{agentId,status},...]`), 新 agent 上线毫秒级出首帧
+- **device 级 10s 批量心跳**: pair 成功后每 10s 上行 1 帧 `_agent/health`；没有 eligible agent 时仍发送 `agents:[]` 维持设备在线，新 Agent 注册后自动切换为正常列表
 - **deviceId 不持久化**: 每次 pair 由云端 handshake 接口分配, 切环境 / 重启 daemon 都用新值
 - **cloud agent 跟本机 framework 解耦**: `_agent/create` 带 `_meta.cozeDeployType=cloud` 时 Bridge 直接 ack 不 spawn — agent 在云端跑, 本机没装对应 framework 也行
 
@@ -85,6 +98,8 @@ npx -y coze-bridge --pat-token=sat_xxx --pair-code=xxx --env=ppe_xxx
 │   ├── bridge.pid          # PID
 │   ├── bridge.port         # IPC HTTP 端口
 │   ├── bridge.token        # IPC token (mode 0600)
+│   ├── connection.json     # 最近成功连接的 PAT + env (mode 0600)
+│   ├── pat-token           # 旧版 PAT 文件，仅用于兼容 fallback
 │   ├── bridge.log
 │   └── config.json         # frameworks_cache + libVersion (不存 deviceId, 每次 pair 拿)
 └── agents/<agentId>/       # 每个 agent 一个目录, daemon 重启自动复活

package/bin/coze-bridge.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ENTRY = fileURLToPath(new URL('../dist/index.js', import.meta.url));
+const MARKER = 'COZE_BRIDGE_WARNINGS_FILTERED';
+
+if (process.env.COZE_BRIDGE_NODE_WARNINGS || process.env[MARKER] === '1') {
+  await import('../dist/index.js');
+} else {
+  const major = Number(process.versions.node.split('.')[0] ?? '0');
+  const warningFlag = major >= 20 ? '--disable-warning=DEP0151' : '--no-warnings';
+  const child = spawn(process.execPath, [warningFlag, ENTRY, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      [MARKER]: '1',
+    },
+  });
+
+  child.once('error', (err) => {
+    process.stderr.write(`fatal: failed to launch coze-bridge: ${String(err)}\n`);
+    process.exit(1);
+  });
+
+  child.once('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}