agents-bridge 0.1.4 → 0.1.5

package/README.md

@@ -1,290 +1,273 @@
-# agents-bridge
+# agents-bridge
 
-鏈湴 Agent 缃戝叧锛岄儴缃插湪瀹㈡埛鏈湴鏈哄櫒涓婏紝閫氳繃闀胯疆璇㈣繛鎺ヤ簯绔?botlink 骞冲彴锛岄┍鍔ㄦ湰鍦扮殑 Claude Code / Codex 绛?AI Agent銆?
+本地 Agent 网关，部署在客户本地机器上，通过长轮询连接 botlink 平台，把消息转发给本机运行的 Claude Code / Codex 等 Agent 运行时。
 
-## 鏋舵瀯姒傝
+核心特点：
 
-```
-botlink 浜戠                             瀹㈡埛鏈湴
-鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?       鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
-鈹? botlink-web         鈹?       鈹? agents-bridge           鈹?
-鈹? client-gateway      鈹?       鈹?                         鈹?
-鈹? bot-gateway 鈼勨攢鈹€鈹€鈹€鈹€鈹€鈹€鈹尖攢鈹€ HTTP 鈹? botlink channel         鈹?
-鈹? message-svc         鈹? 闀胯疆璇⑩攤    鈫?                    鈹?
-鈹? routing-svc         鈹?       鈹? Agent Runtime           鈹?
-鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?       鈹?   鈹溾攢 Claude Code (CLI)  鈹?
-                                鈹?   鈹溾攢 Codex (CLI)        鈹?
-                                鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
-```
+- 客户端主动外连，无需暴露入站端口
+- 支持 `claude-cli/...`、`codex-cli/...` 这类 CLI 模型引用
+- 支持多 agent 配置与按绑定规则路由
+- 提供 `onboard`、`add-agent`、`doctor`、`logs`、`config` 等运维命令
+- 支持前台运行和守护进程模式
+
+## 架构概览
+
+链路可以简化为：
 
-agents-bridge 濮嬬粓浣滀负瀹㈡埛绔富鍔ㄥ杩炰簯绔紝瀹㈡埛鏃犻渶鏆撮湶浠讳綍绔彛銆?
+`botlink cloud -> 长轮询 -> agents-bridge -> 本地 CLI backend / Agent Runtime`
 
-## 蹇€熷紑濮?
+其中：
 
-### 鏂瑰紡 A锛歯pm 鍏ㄥ眬瀹夎锛堟帹鑽愶級
+- botlink 负责云端消息入口
+- agents-bridge 负责轮询、路由、会话管理、日志和文件中转
+- 本地 Agent Runtime 负责实际执行 Claude Code、Codex 等 CLI
+
+## 快速开始
+
+### 方式 A：npm 全局安装
 
 ```bash
 npm install -g agents-bridge@latest
 
-# 浜や簰寮忓紩瀵硷細杈撳叆 gateway URL銆乥ot token銆侀€夋嫨妯″瀷锛岃嚜鍔ㄧ敓鎴愰厤缃?
+# 交互式初始化：输入 gateway URL、bot token、选择模型
 agents-bridge onboard
 
-# 鍚姩
+# 前台启动
 agents-bridge start
-```
 
-### 鏂瑰紡 B锛欴ocker
-
-```bash
-docker run -d --name agents-bridge \
-  -v /home/user/project:/workspace \
-  -v agents-bridge-data:/root/.agent-bridge \
-| `AGENT_BRIDGE_GATEWAY_URL` | `channels.botlink.gateway_url` 或 `channels.botlink.accounts.default.gateway_url` | botlink 网关地址 |
-| `AGENT_BRIDGE_BOT_TOKEN` | `channels.botlink.bot_token` 或 `channels.botlink.accounts.default.bot_token` | Bot Token |
-  -e ANTHROPIC_API_KEY=sk-ant-xxx \
-  agents-bridge:latest
+# 或后台启动
+agents-bridge start --daemon
 ```
 
-鎴栦娇鐢?docker-compose锛?
+### 方式 B：Docker Compose
 
 ```bash
 cp .env.example .env
-# 缂栬緫 .env 濉叆瀹為檯鍊?
+# 编辑 .env，填写 GATEWAY_URL、BOT_TOKEN 等变量
+
 docker compose up -d
 ```
 
-### 鏂瑰紡 C锛氭簮鐮佽繍琛岋紙寮€鍙戣€咃級
+`docker-compose.yml` 默认会：
+
+- 挂载 `${WORKSPACE_DIR:-./workspace}` 到容器内 `/workspace`
+- 持久化 `/root/.agent-bridge`
+- 通过环境变量覆盖网关地址、Bot Token 和日志级别
+
+### 方式 C：源码运行
 
 ```bash
 git clone <repo-url>
-cd <repo-dir>
+cd agent-bridge
 pnpm install
 pnpm build
-cp config.example.json config.json   # 缂栬緫閰嶇疆
+cp config.example.json config.json
+# 编辑 config.json
 node dist/entry.js start
 ```
 
-寮€鍙戞ā寮忥紙鑷姩閲嶈浇锛夛細
+开发模式：
 
 ```bash
 pnpm dev
 ```
 
-## CLI 鍛戒护
+## CLI 命令
 
 ```bash
-agents-bridge start                # 启动 gateway（前台）
-agents-bridge start --daemon       # 启动为后台守护进程
-agents-bridge start -c <path>      # 指定配置文件启动
-agents-bridge stop                 # 停止守护进程
-agents-bridge status               # 查看运行状态
-agents-bridge onboard              # 交互式初始化引导
-agents-bridge doctor               # 诊断环境、会话持久化、日志与 CLI 路径
-agents-bridge logs                 # 查看当天最新日志
-agents-bridge config               # 查看当前配置（脱敏显示）
-agents-bridge help                 # 帮助
+agents-bridge start                  # 前台启动
+agents-bridge start --daemon         # 后台启动
+agents-bridge start -c ./config.json # 指定配置文件
+agents-bridge stop                   # 停止守护进程
+agents-bridge restart                # 重启
+agents-bridge status                 # 查看运行状态
+agents-bridge onboard                # 交互式初始化
+agents-bridge add-agent              # 交互式追加一个 agent
+agents-bridge doctor                 # 检查环境、CLI、API Key 和配置
+agents-bridge logs                   # 查看最近日志
+agents-bridge config                 # 输出当前配置
+agents-bridge version                # 查看版本
+agents-bridge help                   # 查看帮助
 ```
 
-## 閰嶇疆
+## 配置
 
-### 閰嶇疆鏂囦欢
+### 配置文件搜索顺序
 
-涓婚厤缃枃浠朵负 JSON 鏍煎紡锛屾悳绱㈤『搴忥細
+当前实现会按以下顺序读取第一个存在的配置文件：
 
-1. CLI 鍙傛暟锛歚agents-bridge start -c /path/to/config.json`
-2. 鐜鍙橀噺锛歚AGENT_BRIDGE_CONFIG=/path/to/config.json`
-3. 鐢ㄦ埛鐩綍锛歚~/.agent-bridge/config.json`
-4. 褰撳墠鐩綍锛歚./config.json`
+1. `agents-bridge start -c /path/to/config.json`
+2. 环境变量 `AGENT_BRIDGE_CONFIG`
+3. 当前目录 `./config.json`
+4. 用户目录 `~/.agent-bridge/config.json`
 
-瀹屾暣绀轰緥瑙?[config.example.json](config.example.json)锛堝崟 agent锛夊拰 [config.multi-agent.example.json](config.multi-agent.example.json)锛堝 agent锛夈€傞厤缃瓧娈佃缁嗚鏄庤 [閰嶇疆鏂囨。](../agent-bridge-docs/docs/guides/configuration.md)銆?
-褰撳墠杩愯鏃朵粎鏀寔 CLI 妯″紡妯″瀷锛屽 `claude-cli/...`銆乣codex-cli/...`銆俙anthropic/...`銆乣openai/...` 杩欑被 API 鐩磋繛妯″瀷寮曠敤鏆傛湭瀹炵幇鎵ц閾捐矾銆?
-### 鏍稿績閰嶇疆椤癸紙鍗?agent锛?
+### 最小配置示例
 
 ```json
 {
   "channels": {
     "botlink": {
-      "gateway_url": "https://your-botlink-instance.com",
-      "bot_token": "bot_xxxxxxxxxxxxxxxxxx",
-      "poll_timeout": 30,
-      "retry_interval": 5,
-      "max_retry_interval": 60
+      "gateway_url": "https://your-botlink.com",
+      "bot_token": "bot_xxx"
     }
   },
   "agents": {
     "defaults": {
       "model": {
         "primary": "claude-cli/opus-4.6"
-      },
-      "cliBackends": {
-        "claude-cli": {
-          "command": "claude",
-          "args": ["-p", "--output-format", "json", "--dangerously-skip-permissions"],
-          "resumeArgs": ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"],
-          "output": "json",
-          "modelArg": "--model",
-          "sessionArg": "--session-id",
-          "sessionIdFields": ["session_id", "sessionId", "conversation_id", "conversationId"],
-          "sessionMode": "always",
-          "serialize": true
-        },
-        "codex-cli": {
-          "command": "codex",
-          "args": ["exec", "--json", "..."],
-          "resumeArgs": ["exec", "resume", "{sessionId}", "..."],
-          "sessionMode": "existing",
-          "output": "jsonl",
-          "resumeOutput": "text",
-          "modelArg": "--model",
-          "sessionIdFields": ["thread_id"],
-          "serialize": true
-        }
       }
-    }
-  },
-  "logging": {
-    "level": "info"
-  }
-}
-```
-
-### 澶?Agent 閰嶇疆
-
-鍦?`agents` 涓嬪姞 `list` 瀹氫箟澶氫釜鍛藉悕 agent锛岀敤椤跺眰 `bindings` 鎸変細璇?鐢ㄦ埛璺敱锛?
-
-```json
-{
-  "agents": {
-    "defaults": { "model": { "primary": "claude-cli/opus-4.6" } },
+    },
     "list": [
-      { "id": "coder", "default": true, "workspace": "/home/user/app" },
-      { "id": "ops", "model": "codex-cli/o3", "workspace": "/opt/infra" }
+      {
+        "id": "default",
+        "default": true
+      }
     ]
   },
   "bindings": [
-    { "agentId": "ops", "match": { "peer": { "id": "-300" } } },
-    { "agentId": "coder", "match": { "channel": "*" } }
+    {
+      "agentId": "default",
+      "match": {
+        "channel": "*"
+      }
+    }
   ]
 }
 ```
 
-姣忎釜 agent 缁ф壙 `defaults` 骞跺彲瑕嗙洊 model銆亀orkspace銆乪nv銆乧liBackends 绛夈€傝瑙?[閰嶇疆鏂囨。](../agent-bridge-docs/docs/guides/configuration.md)銆?
+完整示例见：
 
-### 鐜鍙橀噺瑕嗙洊
+- [config.example.json](./config.example.json)
+- [config.multi-agent.example.json](./config.multi-agent.example.json)
+- [配置文档](../agent-bridge-docs/docs/guides/configuration.md)
 
-鐜鍙橀噺鍙鐩栭厤缃枃浠朵腑鐨勫搴斿€硷細
+### 关键配置项
 
-| 鐜鍙橀噺 | 瑕嗙洊 | 璇存槑 |
-|---|---|---|
-| `AGENT_BRIDGE_CONFIG` | 鈥?| 閰嶇疆鏂囦欢璺緞 |
-| `AGENT_BRIDGE_GATEWAY_URL` | `channels.botlink.gateway_url` 或 `channels.botlink.accounts.default.gateway_url` | botlink 网关地址 |
-| `AGENT_BRIDGE_BOT_TOKEN` | `channels.botlink.bot_token` 或 `channels.botlink.accounts.default.bot_token` | Bot Token |
-| `AGENT_BRIDGE_LOG_LEVEL` | `logging.level` | 鏃ュ織绾у埆 |
-| `AGENT_BRIDGE_TEMP_DIR` | `files.temp_dir` | 涓存椂鏂囦欢鐩綍 |
+- `channels.botlink.gateway_url`：botlink 网关地址
+- `channels.botlink.bot_token`：bot token
+- `agents.defaults.model.primary`：主模型引用，例如 `claude-cli/opus-4.6` 或 `codex-cli/gpt-5.4`
+- `agents.defaults.model.fallbacks`：备用模型链
+- `agents.defaults.cliBackends`：CLI backend 启动参数与运行模式
+- `agents.list`：命名 agent 列表
+- `bindings`：消息路由规则，可按 `channel`、`accountId`、`peer.id` 等条件匹配
+- `files.temp_dir`：文件中转目录
+- `logging.level`：日志级别
 
-## 鏁版嵁鐩綍
+### 多 agent 配置
 
-```
-~/.agent-bridge/
-鈹溾攢鈹€ config.json                # 涓婚厤缃紙onboard 鐢熸垚锛?
-鈹溾攢鈹€ agent-bridge.pid           # PID 鏂囦欢锛坉aemon 妯″紡锛?
-鈹溾攢鈹€ agents/                    # per-agent 鐘舵€侊紙澶?agent 妯″紡锛?
-鈹?  鈹溾攢鈹€ coder/
-鈹?  鈹?  鈹斺攢鈹€ cli-sessions.json  # coder 鐨?session 鏄犲皠
-鈹?  鈹溾攢鈹€ reviewer/
-鈹?  鈹?  鈹斺攢鈹€ cli-sessions.json
-鈹?  鈹斺攢鈹€ default/               # 闅愬紡 agent锛堟湭閰?list 鏃讹級
-鈹?      鈹斺攢鈹€ cli-sessions.json
-鈹溾攢鈹€ data/
-鈹?  鈹溾攢鈹€ sessions/              # 鏃х増 session 瀛樺偍锛堝崌绾у悗鑷姩杩佺Щ锛?
-鈹?  鈹溾攢鈹€ files/                 # 鏂囦欢涓浆涓存椂鐩綍
-鈹?  鈹斺攢鈹€ logs/                  # 鏃ュ織鏂囦欢
-鈹斺攢鈹€ skills/                    # 鑷畾涔夋妧鑳?
-```
+多 agent 模式通过 `agents.list` 定义运行实例，通过 `bindings` 决定消息路由到哪个 agent。
 
-## 椤圭洰缁撴瀯
+追加 agent 时，也可以直接运行：
 
+```bash
+agents-bridge add-agent
 ```
-agents-bridge/
-鈹溾攢鈹€ bin/
-鈹?  鈹斺攢鈹€ agent-bridge.mjs       # CLI 鍏ュ彛锛坣pm 鍏ㄥ眬瀹夎锛?
-鈹溾攢鈹€ src/
-鈹?  鈹溾攢鈹€ entry.ts               # 涓诲叆鍙ｏ紝瀛愬懡浠よ矾鐢?
-鈹?  鈹溾攢鈹€ cli/                   # CLI 鍛戒护瀹炵幇
-鈹?  鈹?  鈹溾攢鈹€ run-main.ts        #   鍙傛暟瑙ｆ瀽
-鈹?  鈹?  鈹溾攢鈹€ cmd-start.ts       #   start 鍛戒护
-鈹?  鈹?  鈹溾攢鈹€ cmd-stop.ts        #   stop 鍛戒护
-鈹?  鈹?  鈹溾攢鈹€ cmd-status.ts      #   status 鍛戒护
-鈹?  鈹?  鈹溾攢鈹€ cmd-onboard.ts     #   onboard 浜や簰寮曞
-鈹?  鈹?  鈹溾攢鈹€ cmd-doctor.ts      #   doctor 鐜璇婃柇
-鈹?  鈹?  鈹溾攢鈹€ cmd-logs.ts        #   logs 鏌ョ湅
-鈹?  鈹?  鈹斺攢鈹€ cmd-config.ts      #   config 鏌ョ湅
-鈹?  鈹溾攢鈹€ config/                # 閰嶇疆鍔犺浇涓庢牎楠?
-鈹?  鈹?  鈹溾攢鈹€ config.ts          #   涓诲姞杞藉櫒
-鈹?  鈹?  鈹溾攢鈹€ zod-schema.ts      #   Zod schema
-鈹?  鈹?  鈹溾攢鈹€ paths.ts           #   鏁版嵁鐩綍璺緞甯搁噺
-鈹?  鈹?  鈹溾攢鈹€ env-vars.ts        #   鐜鍙橀噺璇诲彇
-鈹?  鈹?  鈹溾攢鈹€ merge-config.ts    #   閰嶇疆鍚堝苟
-鈹?  鈹?  鈹斺攢鈹€ agent-dirs.ts      #   鐩綍鍒濆鍖?
-鈹?  鈹溾攢鈹€ channels/              # Channel 鎻掍欢妗嗘灦
-鈹?  鈹?  鈹溾攢鈹€ registry.ts        #   鎻掍欢娉ㄥ唽琛?
-鈹?  鈹?  鈹溾攢鈹€ session.ts         #   浼氳瘽绠＄悊
-鈹?  鈹?  鈹斺攢鈹€ ...
-鈹?  鈹溾攢鈹€ agents/                # Agent 杩愯鏃?
-鈹?  鈹?  鈹溾攢鈹€ agent-resolver.ts  #   澶?agent 閰嶇疆瑙ｆ瀽锛坉efaults + list 鍚堝苟锛?
-鈹?  鈹?  鈹溾攢鈹€ agent-router.ts    #   娑堟伅璺敱锛坆indings 鍖归厤锛?
-鈹?  鈹?  鈹溾攢鈹€ cli-backends.ts    #   CLI backend provider id / 榛樿閰嶇疆瑁呴厤
-鈹?  鈹?  鈹溾攢鈹€ cli-session-store.ts # CLI session 鏄犲皠鎸佷箙鍖栵紙per-agent锛?
-鈹?  鈹?  鈹溾攢鈹€ cli-runner.ts      #   Claude/Codex CLI 鎵ц鍣?
-鈹?  鈹?  鈹斺攢鈹€ ...
-鈹?  鈹溾攢鈹€ types/                 # 绫诲瀷瀹氫箟
-鈹?  鈹斺攢鈹€ logger.ts              # Pino 鏃ュ織
-鈹溾攢鈹€ extensions/                # Channel 鎻掍欢锛坆otlink锛?
-鈹溾攢鈹€ skills/                    # 鎶€鑳藉畾涔?
-鈹溾攢鈹€ config.example.json        # 閰嶇疆绀轰緥
-鈹溾攢鈹€ .env.example               # 鐜鍙橀噺绀轰緥
-鈹溾攢鈹€ Dockerfile
-鈹溾攢鈹€ docker-compose.yml
-鈹溾攢鈹€ package.json
-鈹斺攢鈹€ tsconfig.json
-```
 
-## 褰撳墠鏀寔鐨?Agent 妯″紡
+该命令会在现有配置上：
+
+- 追加一个 `agents.list[]` 项
+- 可选绑定已有 botlink `accountId`
+- 可选创建新的 botlink account 并立刻绑定
+- 写入前自动备份原配置文件
 
-| 妯″紡 | 妯″瀷寮曠敤绀轰緥 | 璇存槑 |
+例如：
+
+- 一个 bot 绑定到 Codex
+- 一个 bot 绑定到 Claude Code
+- 不同工作区使用不同 `workspace`
+- 通过预置 `cliSessionId` 复用既有 CLI 会话
+
+详见 [config.multi-agent.example.json](./config.multi-agent.example.json)。
+
+### 环境变量覆盖
+
+环境变量可覆盖配置文件中的对应值：
+
+| 环境变量 | 覆盖字段 | 说明 |
 |---|---|---|
-| Claude Code | `claude-cli/opus-4.6` | 通过 CLI backend 启动本地 `claude` 命令 |
-| Codex | `codex-cli/gpt-5.4` | 通过 CLI backend 启动本地 `codex` 命令 |
-| Pi Agent | `anthropic/claude-sonnet-4-6` | 通过 LLM API 直连，内置工具执行 |
+| `AGENT_BRIDGE_CONFIG` | 配置文件路径 | 指定要加载的 `config.json` |
+| `AGENT_BRIDGE_GATEWAY_URL` | `channels.botlink.gateway_url` | botlink 网关地址 |
+| `AGENT_BRIDGE_BOT_TOKEN` | `channels.botlink.bot_token` | Bot Token |
+| `AGENT_BRIDGE_LOG_LEVEL` | `logging.level` | 日志级别 |
+| `AGENT_BRIDGE_TEMP_DIR` | `files.temp_dir` | 临时文件目录 |
+| `ANTHROPIC_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
+| `OPENAI_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
 
-鍦?`config.json` 鐨?`agents.defaults.model.primary` 涓€夋嫨銆?
+## 模型与运行模式
 
-## CLI Backend 绾﹀畾
+当前消息执行链路仅支持 CLI 模式模型，也就是：
 
-- 内置 provider id 固定为 `claude-cli`、`codex-cli`。
-- `agents.defaults.cliBackends` 会覆盖内置默认值，不需要重复写全量字段。
-- `SessionEnvelope.sessionId` 是 botlink 稳定会话键，不等于 Claude/Codex 自己的 session id。
-- CLI backend session id 会持久化到 `~/.agent-bridge/data/sessions/cli-sessions.json` 的 `cliSessionIds[providerId]`。
-- `serialize: true` 的语义是“同一 botlink session 串行、跨 session 可并发”。
-- Claude CLI 走 JSON 输出；Codex CLI 首次运行走 JSONL，resume 走 text。
-- agents-bridge 会把运行日志同时写到 stdout 和 `~/.agent-bridge/data/logs/agent-bridge-YYYY-MM-DD.log`。
-- `agents-bridge doctor` 会检查 Codex 会话是否缺失 `thread_id` 持久化，便于定位“每次都 fresh”的问题。
+- `claude-cli/...`
+- `codex-cli/...`
 
-## 鎶€鏈爤
+配置层已经允许 `anthropic/...`、`openai/...` 这类 API provider 引用，但当前主运行时尚未实现 API 模式；若把它们设为主模型，程序会返回“当前仅支持 CLI 模式模型”。
 
-- TypeScript + Node.js (>= 22.0.0)
-- pnpm (>= 9.0.0)
-- Pino锛堟棩蹇楋級
-- Zod锛堥厤缃牎楠岋級
-- JSON锛堥厤缃牸寮忥級
+## 数据目录
 
-## 寮€鍙?
+运行时数据默认保存在 `~/.agent-bridge/`：
+
+```text
+~/.agent-bridge/
+├── config.json
+├── agent-bridge.pid
+├── agents/
+│   └── <agentId>/
+│       └── cli-sessions.json
+├── data/
+│   ├── files/
+│   ├── logs/
+│   └── sessions/
+└── skills/
+```
+
+其中：
+
+- `config.json`：全局配置文件
+- `agent-bridge.pid`：守护进程 PID 文件
+- `agents/<agentId>/cli-sessions.json`：每个 agent 的 CLI 会话映射
+- `data/logs/`：按天滚动的日志文件
+- `skills/`：自定义技能目录
+
+## 项目结构
+
+```text
+agent-bridge/
+├── bin/                    # CLI 入口
+├── src/
+│   ├── cli/                # start / stop / onboard / doctor 等命令
+│   ├── agents/             # Agent 解析、路由、CLI 执行
+│   ├── channels/           # Channel 插件（如 botlink）
+│   ├── config/             # 配置加载、校验、默认值
+│   ├── types/              # 类型定义
+│   └── logger.ts           # 日志
+├── extensions/             # 扩展点
+├── skills/                 # 本地技能目录
+├── config.example.json
+├── config.multi-agent.example.json
+├── docker-compose.yml
+├── Dockerfile
+└── package.json
+```
+
+## 开发
 
 ```bash
-pnpm install          # 瀹夎渚濊禆
-pnpm build            # 缂栬瘧
-pnpm dev              # 寮€鍙戞ā寮忥紙鑷姩閲嶈浇锛?
-pnpm typecheck        # 绫诲瀷妫€鏌?
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm dev
 ```
 
+环境要求：
+
+- Node.js >= 22.0.0
+- pnpm >= 9.0.0
+
+## 相关文档
+
+- [文档索引](../agent-bridge-docs/INDEX.md)
+- [配置文档](../agent-bridge-docs/docs/guides/configuration.md)
+
+## 许可证
 
+[MIT](./LICENSE)

package/config.example.json

@@ -8,11 +8,11 @@
       "max_retry_interval": 60
     }
   },
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "claude-cli/opus-4.6",
-        "fallbacks": [
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "claude-cli/opus-4.6",
+        "fallbacks": [
           "codex-cli/gpt-5.4"
         ]
       },
@@ -77,22 +77,22 @@
           "args": [
             "exec",
             "--json",
-            "--color",
-            "never",
-            "--sandbox",
-            "workspace-write",
-            "--skip-git-repo-check"
-          ],
+            "--color",
+            "never",
+            "--sandbox",
+            "workspace-write",
+            "--skip-git-repo-check"
+          ],
           "resumeArgs": [
             "exec",
             "resume",
             "{sessionId}",
-            "--color",
-            "never",
-            "--sandbox",
-            "workspace-write",
-            "--skip-git-repo-check"
-          ],
+            "--color",
+            "never",
+            "--sandbox",
+            "workspace-write",
+            "--skip-git-repo-check"
+          ],
           "output": "jsonl",
           "resumeOutput": "text",
           "input": "arg",
@@ -102,13 +102,13 @@
             "sessionSource": "agent-bridge",
             "startupTimeoutMs": 15000,
             "requestTimeoutMs": 30000,
-            "serviceName": "agent-bridge",
-            "experimentalApi": false,
-            "approvalPolicy": "never",
-            "sandbox": "workspace-write",
-            "persistExtendedHistory": false,
-            "experimentalRawEvents": false
-          },
+            "serviceName": "agent-bridge",
+            "experimentalApi": false,
+            "approvalPolicy": "never",
+            "sandbox": "workspace-write",
+            "persistExtendedHistory": false,
+            "experimentalRawEvents": false
+          },
           "sessionIdFields": [
             "thread_id"
           ],
@@ -129,28 +129,28 @@
                 "maxMs": 180000
               }
             }
-          }
-        }
-      }
-    },
-    "list": [
-      {
-        "id": "default",
-        "default": true
-      }
-    ]
-  },
-  "bindings": [
-    {
-      "agentId": "default",
-      "match": {
-        "channel": "*"
-      }
-    }
-  },
-  "skills": {
-    "dirs": [
-      "./skills"
+          }
+        }
+      }
+    },
+    "list": [
+      {
+        "id": "default",
+        "default": true
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "default",
+      "match": {
+        "channel": "*"
+      }
+    }
+  },
+  "skills": {
+    "dirs": [
+      "./skills"
     ]
   },
   "files": {

package/dist/agents/cli-runner.d.ts

@@ -4,7 +4,8 @@ import { type CodexTurnRuntime } from './codex-app-server-runtime.js';
 import { CliSessionStore } from './cli-session-store.js';
 export declare class LocalCliTurnExecutor implements CliTurnExecutor {
     private readonly options;
-    private codexRuntime;
+    private activeCodexRuntime;
+    private readonly drainingCodexRuntimes;
     constructor(options: {
         config: Pick<AppConfig, 'agents'>;
         logger: Logger;
@@ -16,7 +17,9 @@ export declare class LocalCliTurnExecutor implements CliTurnExecutor {
     private emitProcessing;
     private executeTurn;
     teardown(): Promise<void>;
-    private getCodexRuntime;
+    rotateCodexRuntime(): Promise<void>;
+    private acquireCodexRuntime;
+    private releaseCodexRuntime;
     private executeCodexAppServerTurn;
     private executeCliExecTurn;
 }

package/dist/agents/cli-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-runner.d.ts","sourceRoot":"","sources":["../../src/agents/cli-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EACV,gBAAgB,EAGhB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,MAAM,EAEP,MAAM,mBAAmB,CAAA;AAc1B,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,eAAe,EAAwB,MAAM,wBAAwB,CAAA;AAkB9E,qBAAa,oBAAqB,YAAW,eAAe;IAIxD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,YAAY,CAAgC;gBAGjC,OAAO,EAAE;QACxB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;QACjC,MAAM,EAAE,MAAM,CAAA;QACd,YAAY,CAAC,EAAE,eAAe,CAAA;QAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAA;KACrE;IAGG,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;YAyHxC,cAAc;YAId,WAAW;IAqBnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,OAAO,CAAC,eAAe;YAUT,yBAAyB;YA+DzB,kBAAkB;CAwIjC"}
+{"version":3,"file":"cli-runner.d.ts","sourceRoot":"","sources":["../../src/agents/cli-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EACV,gBAAgB,EAGhB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,MAAM,EAEP,MAAM,mBAAmB,CAAA;AAc1B,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,eAAe,EAAwB,MAAM,wBAAwB,CAAA;AAuB9E,qBAAa,oBAAqB,YAAW,eAAe;IAKxD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,kBAAkB,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA8B;gBAGjD,OAAO,EAAE;QACxB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;QACjC,MAAM,EAAE,MAAM,CAAA;QACd,YAAY,CAAC,EAAE,eAAe,CAAA;QAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAA;QACzB,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAA;KACrE;IAGG,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;YAyHxC,cAAc;YAId,WAAW;IAqBnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAYzB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAezC,OAAO,CAAC,mBAAmB;YAab,mBAAmB;YAUnB,yBAAyB;YAqEzB,kBAAkB;CAwIjC"}