agents-bridge 0.1.36 → 0.1.38

package/README.md

@@ -1,312 +1,312 @@
-# agents-bridge
-
-本地 Agent 网关，部署在客户本地机器上，通过长轮询连接 botlink 平台，把消息转发给本机运行的 Claude Code / Codex 等 Agent 运行时。
-
-核心特点：
-
-- 客户端主动外连，无需暴露入站端口
-- 支持 `claude-cli/...`、`codex-cli/...`、`qwen-cli/...`、`wukong-cli/...` 这类 CLI 模型引用
-- 支持多 agent 配置与按绑定规则路由
-- 提供 `onboard`、`add-agent`、`doctor`、`logs`、`config` 等运维命令
-- 支持前台运行和守护进程模式
-
-## 架构概览
-
-链路可以简化为：
-
-`botlink cloud -> 长轮询 -> agents-bridge -> 本地 CLI backend / Agent Runtime`
-
-其中：
-
-- botlink 负责云端消息入口
-- agents-bridge 负责轮询、路由、会话管理、日志和文件中转
-- 本地 Agent Runtime 负责实际执行 Claude Code、Codex 等 CLI
-
-## 快速开始
-
-### 方式 A：npm 全局安装
-
-```bash
-npm install -g agents-bridge@latest
-
-# 交互式初始化：输入 gateway URL、bot token、选择模型
-agents-bridge onboard
-
-# 前台启动
-agents-bridge start
-
-# 或后台启动
-agents-bridge start --daemon
-```
-
-### 方式 B：Docker Compose
-
-```bash
-cp .env.example .env
-# 编辑 .env，填写 GATEWAY_URL、BOT_TOKEN 等变量
-
-docker compose up -d
-```
-
-`docker-compose.yml` 默认会：
-
-- 挂载 `${WORKSPACE_DIR:-./workspace}` 到容器内 `/workspace`
-- 持久化 `/root/.agent-bridge`
-- 通过环境变量覆盖网关地址、Bot Token 和日志级别
-
-### 方式 C：源码运行
-
-```bash
-git clone <repo-url>
-cd agent-bridge
-pnpm install
-pnpm build
-cp config.example.json config.json
-# 编辑 config.json
-node dist/entry.js start
-```
-
-开发模式：
-
-```bash
-pnpm dev
-```
-
-## CLI 命令
-
-```bash
-agents-bridge start                  # 前台启动
-agents-bridge start --daemon         # 后台启动
-agents-bridge start -c ./config.json # 指定配置文件
-agents-bridge stop                   # 停止守护进程
-agents-bridge restart                # 重启
-agents-bridge reload                 # 热加载配置
-agents-bridge status                 # 查看运行状态
-agents-bridge onboard                # 交互式初始化
-agents-bridge add-agent              # 交互式追加一个 agent
-agents-bridge add-agent --account-id office-bot
-agents-bridge add-agent office-codex --model codex-cli/gpt-5.5 --workspace D:\workspace\office --account-id office-bot --no-interactive
-agents-bridge add-agent --create-account office-bot --account-gateway-url https://botlink.example.com --account-bot-token bot_xxx
-agents-bridge list-groups --account-id office-bot --json
-agents-bridge list-members --account-id office-bot --group-id conv_xxx
-agents-bridge list-members --account-id office-bot --chat-id -100123456789 --json
-agents-bridge send-message --account-id office-bot --group-id conv_xxx --text "hello"
-agents-bridge doctor                 # 检查环境、CLI、API Key 和配置
-agents-bridge logs                   # 查看最近日志
-agents-bridge config                 # 输出当前配置
-agents-bridge update                 # 更新已安装的 CLI
-agents-bridge version                # 查看版本
-agents-bridge help                   # 查看帮助
-```
-
-## 配置
-
-### 配置文件搜索顺序
-
-当前实现会按以下顺序读取第一个存在的配置文件：
-
-1. `agents-bridge start -c /path/to/config.json`
-2. 环境变量 `AGENT_BRIDGE_CONFIG`
-3. 当前目录 `./config.json`
-4. 用户目录 `~/.agent-bridge/config.json`
-
-### 最小配置示例
-
-```json
-{
-  "channels": {
-    "botlink": {
-      "accounts": {
-        "default": {
-          "gateway_url": "https://your-botlink.com",
-          "bot_token": "bot_xxx",
-          "poll_timeout": 30,
-          "retry_interval": 5,
-          "max_retry_interval": 60
-        }
-      }
-    }
-  },
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "claude-cli/opus-4.6"
-      }
-    },
-    "list": [
-      {
-        "id": "default",
-        "default": true
-      }
-    ]
-  },
-  "bindings": [
-    {
-      "agentId": "default",
-      "match": {
-        "channel": "*"
-      }
-    }
-  ]
-}
-```
-
-完整示例见：
-
-- [config.example.json](./config.example.json)
-- [config.multi-agent.example.json](./config.multi-agent.example.json)
-
-botlink 配置读取时兼容旧的顶层 `gateway_url` / `bot_token` 写法，但新的配置写入会统一落到 `channels.botlink.accounts`。
-
-兼容性说明：
-
-- 老配置仍可继续使用：顶层 `channels.botlink.gateway_url` / `bot_token` 仍然会被读取
-- 新示例配置统一使用 `channels.botlink.accounts` 格式
-- `add-agent` 会兼容读取老配置，并在保存时自动迁移成 `channels.botlink.accounts`
-- `onboard` 会先备份已有配置，再按新的 `channels.botlink.accounts` 格式重建配置
-
-### 关键配置项
-
-- `channels.botlink.accounts.<accountId>.gateway_url`：botlink 网关地址
-- `channels.botlink.accounts.<accountId>.bot_token`：bot token
-- `agents.defaults.model.primary`：主模型引用，例如 `claude-cli/opus-4.6`、`codex-cli/gpt-5.4`、`qwen-cli/qwen3-coder-plus` 或 `wukong-cli/wukong-coder`
-- `agents.defaults.model.fallbacks`：备用模型链
-- `agents.defaults.cliBackends`：CLI backend 启动参数与运行模式
-- `agents.list`：命名 agent 列表
-- `bindings`：消息路由规则，可按 `channel`、`accountId`、`peer.id` 等条件匹配
-- `files.temp_dir`：文件中转目录
-- `logging.level`：日志级别
-
-### 多 agent 配置
-
-多 agent 模式通过 `agents.list` 定义运行实例，通过 `bindings` 决定消息路由到哪个 agent。
-
-追加 agent 时，也可以直接运行：
-
-```bash
-agents-bridge add-agent
-```
-
-该命令会在现有配置上：
-
-- 追加一个 `agents.list[]` 项
-- 可选绑定已有 botlink `accountId`
-- 可选创建新的 botlink account 并立刻绑定
-- 兼容旧的顶层 botlink 配置写法，并在保存时自动迁移成 `channels.botlink.accounts.default`
-- 写入前自动备份原配置文件
-
-如果现有 account 已被其他 agent 占用，交互流程会提示该 account 当前绑定到哪个 agent，并允许直接创建新的 account 后继续绑定。
-
-也可以显式指定：
-
-```bash
-agents-bridge add-agent --account-id office-bot
-agents-bridge add-agent --create-account office-bot --account-gateway-url https://botlink.example.com --account-bot-token bot_xxx
-```
-
-例如：
-
-- 一个 bot 绑定到 Codex
-- 一个 bot 绑定到 Claude Code
-- 不同工作区使用不同 `workspace`
-- 通过预置 `cliSessionId` 复用既有 CLI 会话
-
-详见 [config.multi-agent.example.json](./config.multi-agent.example.json)。
-
-### 环境变量覆盖
-
-环境变量可覆盖配置文件中的对应值：
-
-| 环境变量 | 覆盖字段 | 说明 |
-|---|---|---|
-| `AGENT_BRIDGE_CONFIG` | 配置文件路径 | 指定要加载的 `config.json` |
-| `AGENT_BRIDGE_GATEWAY_URL` | `channels.botlink.accounts.default.gateway_url` 或旧格式 `channels.botlink.gateway_url` | 优先覆盖默认 botlink 账号；旧配置会覆盖顶层网关地址 |
-| `AGENT_BRIDGE_BOT_TOKEN` | `channels.botlink.accounts.default.bot_token` 或旧格式 `channels.botlink.bot_token` | 优先覆盖默认 botlink 账号；旧配置会覆盖顶层 Bot Token |
-| `AGENT_BRIDGE_LOG_LEVEL` | `logging.level` | 日志级别 |
-| `AGENT_BRIDGE_TEMP_DIR` | `files.temp_dir` | 临时文件目录 |
-| `ANTHROPIC_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
-| `OPENAI_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
-
-## 模型与运行模式
-
-当前消息执行链路仅支持 CLI 模式模型，也就是：
-
-- `claude-cli/...`
-- `codex-cli/...`
-- `qwen-cli/...`
-- `wukong-cli/...`
-
-配置层已经允许 `anthropic/...`、`openai/...` 这类 API provider 引用，但当前主运行时尚未实现 API 模式；若把它们设为主模型，程序会返回“当前仅支持 CLI 模式模型”。
-
-内置 `wukong-cli` 默认按通用 JSON exec 模式启动：
-
-```bash
-wukong-cli --output-format json --no-color --quiet --model <model> --prompt "<prompt>"
-```
-
-如果本地悟空 CLI 的可执行文件不在 `PATH`，可以把 `command` 覆盖为完整路径。若参数不同，可以在 `agents.defaults.cliBackends.wukong-cli` 或单个 agent 的 `cliBackends.wukong-cli` 中覆盖 `command`、`args`、`modelArg`、`promptArg` 等字段。
-
-## 数据目录
-
-运行时数据默认保存在 `~/.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 typecheck
-pnpm dev
-```
-
-环境要求：
-
-- Node.js >= 22.0.0
-- pnpm >= 9.0.0
-
-## 许可证
-
-[MIT](./LICENSE)
+# agents-bridge
+
+本地 Agent 网关，部署在客户本地机器上，通过长轮询连接 botlink 平台，把消息转发给本机运行的 Claude Code / Codex 等 Agent 运行时。
+
+核心特点：
+
+- 客户端主动外连，无需暴露入站端口
+- 支持 `claude-cli/...`、`codex-cli/...`、`qwen-cli/...`、`wukong-cli/...` 这类 CLI 模型引用
+- 支持多 agent 配置与按绑定规则路由
+- 提供 `onboard`、`add-agent`、`doctor`、`logs`、`config` 等运维命令
+- 支持前台运行和守护进程模式
+
+## 架构概览
+
+链路可以简化为：
+
+`botlink cloud -> 长轮询 -> agents-bridge -> 本地 CLI backend / Agent Runtime`
+
+其中：
+
+- botlink 负责云端消息入口
+- agents-bridge 负责轮询、路由、会话管理、日志和文件中转
+- 本地 Agent Runtime 负责实际执行 Claude Code、Codex 等 CLI
+
+## 快速开始
+
+### 方式 A：npm 全局安装
+
+```bash
+npm install -g agents-bridge@latest
+
+# 交互式初始化：输入 gateway URL、bot token、选择模型
+agents-bridge onboard
+
+# 前台启动
+agents-bridge start
+
+# 或后台启动
+agents-bridge start --daemon
+```
+
+### 方式 B：Docker Compose
+
+```bash
+cp .env.example .env
+# 编辑 .env，填写 GATEWAY_URL、BOT_TOKEN 等变量
+
+docker compose up -d
+```
+
+`docker-compose.yml` 默认会：
+
+- 挂载 `${WORKSPACE_DIR:-./workspace}` 到容器内 `/workspace`
+- 持久化 `/root/.agent-bridge`
+- 通过环境变量覆盖网关地址、Bot Token 和日志级别
+
+### 方式 C：源码运行
+
+```bash
+git clone <repo-url>
+cd agent-bridge
+pnpm install
+pnpm build
+cp config.example.json config.json
+# 编辑 config.json
+node dist/entry.js start
+```
+
+开发模式：
+
+```bash
+pnpm dev
+```
+
+## CLI 命令
+
+```bash
+agents-bridge start                  # 前台启动
+agents-bridge start --daemon         # 后台启动
+agents-bridge start -c ./config.json # 指定配置文件
+agents-bridge stop                   # 停止守护进程
+agents-bridge restart                # 重启
+agents-bridge reload                 # 热加载配置
+agents-bridge status                 # 查看运行状态
+agents-bridge onboard                # 交互式初始化
+agents-bridge add-agent              # 交互式追加一个 agent
+agents-bridge add-agent --account-id office-bot
+agents-bridge add-agent office-codex --model codex-cli/gpt-5.5 --workspace D:\workspace\office --account-id office-bot --no-interactive
+agents-bridge add-agent --create-account office-bot --account-gateway-url https://botlink.example.com --account-bot-token bot_xxx
+agents-bridge list-groups --account-id office-bot --json
+agents-bridge list-members --account-id office-bot --group-id conv_xxx
+agents-bridge list-members --account-id office-bot --chat-id -100123456789 --json
+agents-bridge send-message --account-id office-bot --group-id conv_xxx --text "hello"
+agents-bridge doctor                 # 检查环境、CLI、API Key 和配置
+agents-bridge logs                   # 查看最近日志
+agents-bridge config                 # 输出当前配置
+agents-bridge update                 # 更新已安装的 CLI
+agents-bridge version                # 查看版本
+agents-bridge help                   # 查看帮助
+```
+
+## 配置
+
+### 配置文件搜索顺序
+
+当前实现会按以下顺序读取第一个存在的配置文件：
+
+1. `agents-bridge start -c /path/to/config.json`
+2. 环境变量 `AGENT_BRIDGE_CONFIG`
+3. 当前目录 `./config.json`
+4. 用户目录 `~/.agent-bridge/config.json`
+
+### 最小配置示例
+
+```json
+{
+  "channels": {
+    "botlink": {
+      "accounts": {
+        "default": {
+          "gateway_url": "https://your-botlink.com",
+          "bot_token": "bot_xxx",
+          "poll_timeout": 30,
+          "retry_interval": 5,
+          "max_retry_interval": 60
+        }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "claude-cli/opus-4.6"
+      }
+    },
+    "list": [
+      {
+        "id": "default",
+        "default": true
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "default",
+      "match": {
+        "channel": "*"
+      }
+    }
+  ]
+}
+```
+
+完整示例见：
+
+- [config.example.json](./config.example.json)
+- [config.multi-agent.example.json](./config.multi-agent.example.json)
+
+botlink 配置读取时兼容旧的顶层 `gateway_url` / `bot_token` 写法，但新的配置写入会统一落到 `channels.botlink.accounts`。
+
+兼容性说明：
+
+- 老配置仍可继续使用：顶层 `channels.botlink.gateway_url` / `bot_token` 仍然会被读取
+- 新示例配置统一使用 `channels.botlink.accounts` 格式
+- `add-agent` 会兼容读取老配置，并在保存时自动迁移成 `channels.botlink.accounts`
+- `onboard` 会先备份已有配置，再按新的 `channels.botlink.accounts` 格式重建配置
+
+### 关键配置项
+
+- `channels.botlink.accounts.<accountId>.gateway_url`：botlink 网关地址
+- `channels.botlink.accounts.<accountId>.bot_token`：bot token
+- `agents.defaults.model.primary`：主模型引用，例如 `claude-cli/opus-4.6`、`codex-cli/gpt-5.4`、`qwen-cli/qwen3-coder-plus` 或 `wukong-cli/wukong-coder`
+- `agents.defaults.model.fallbacks`：备用模型链
+- `agents.defaults.cliBackends`：CLI backend 启动参数与运行模式
+- `agents.list`：命名 agent 列表
+- `bindings`：消息路由规则，可按 `channel`、`accountId`、`peer.id` 等条件匹配
+- `files.temp_dir`：文件中转目录
+- `logging.level`：日志级别
+
+### 多 agent 配置
+
+多 agent 模式通过 `agents.list` 定义运行实例，通过 `bindings` 决定消息路由到哪个 agent。
+
+追加 agent 时，也可以直接运行：
+
+```bash
+agents-bridge add-agent
+```
+
+该命令会在现有配置上：
+
+- 追加一个 `agents.list[]` 项
+- 可选绑定已有 botlink `accountId`
+- 可选创建新的 botlink account 并立刻绑定
+- 兼容旧的顶层 botlink 配置写法，并在保存时自动迁移成 `channels.botlink.accounts.default`
+- 写入前自动备份原配置文件
+
+如果现有 account 已被其他 agent 占用，交互流程会提示该 account 当前绑定到哪个 agent，并允许直接创建新的 account 后继续绑定。
+
+也可以显式指定：
+
+```bash
+agents-bridge add-agent --account-id office-bot
+agents-bridge add-agent --create-account office-bot --account-gateway-url https://botlink.example.com --account-bot-token bot_xxx
+```
+
+例如：
+
+- 一个 bot 绑定到 Codex
+- 一个 bot 绑定到 Claude Code
+- 不同工作区使用不同 `workspace`
+- 通过预置 `cliSessionId` 复用既有 CLI 会话
+
+详见 [config.multi-agent.example.json](./config.multi-agent.example.json)。
+
+### 环境变量覆盖
+
+环境变量可覆盖配置文件中的对应值：
+
+| 环境变量 | 覆盖字段 | 说明 |
+|---|---|---|
+| `AGENT_BRIDGE_CONFIG` | 配置文件路径 | 指定要加载的 `config.json` |
+| `AGENT_BRIDGE_GATEWAY_URL` | `channels.botlink.accounts.default.gateway_url` 或旧格式 `channels.botlink.gateway_url` | 优先覆盖默认 botlink 账号；旧配置会覆盖顶层网关地址 |
+| `AGENT_BRIDGE_BOT_TOKEN` | `channels.botlink.accounts.default.bot_token` 或旧格式 `channels.botlink.bot_token` | 优先覆盖默认 botlink 账号；旧配置会覆盖顶层 Bot Token |
+| `AGENT_BRIDGE_LOG_LEVEL` | `logging.level` | 日志级别 |
+| `AGENT_BRIDGE_TEMP_DIR` | `files.temp_dir` | 临时文件目录 |
+| `ANTHROPIC_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
+| `OPENAI_API_KEY` | 环境变量 | 供诊断或后续 API 模式使用 |
+
+## 模型与运行模式
+
+当前消息执行链路仅支持 CLI 模式模型，也就是：
+
+- `claude-cli/...`
+- `codex-cli/...`
+- `qwen-cli/...`
+- `wukong-cli/...`
+
+配置层已经允许 `anthropic/...`、`openai/...` 这类 API provider 引用，但当前主运行时尚未实现 API 模式；若把它们设为主模型，程序会返回“当前仅支持 CLI 模式模型”。
+
+内置 `wukong-cli` 默认按通用 JSON exec 模式启动：
+
+```bash
+wukong-cli --output-format json --no-color --quiet --model <model> --prompt "<prompt>"
+```
+
+如果本地悟空 CLI 的可执行文件不在 `PATH`，可以把 `command` 覆盖为完整路径。若参数不同，可以在 `agents.defaults.cliBackends.wukong-cli` 或单个 agent 的 `cliBackends.wukong-cli` 中覆盖 `command`、`args`、`modelArg`、`promptArg` 等字段。
+
+## 数据目录
+
+运行时数据默认保存在 `~/.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 typecheck
+pnpm dev
+```
+
+环境要求：
+
+- Node.js >= 22.0.0
+- pnpm >= 9.0.0
+
+## 许可证
+
+[MIT](./LICENSE)

package/bin/agent-bridge.mjs

@@ -1,13 +1,13 @@
-#!/usr/bin/env node
-
-// agents-bridge CLI entry point
-// Used by: npm install -g agents-bridge / npx agents-bridge
-
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-
-// Import the compiled entry point
-await import(pathToFileURL(resolve(__dirname, '..', 'dist', 'entry.js')).href)
+#!/usr/bin/env node
+
+// agents-bridge CLI entry point
+// Used by: npm install -g agents-bridge / npx agents-bridge
+
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// Import the compiled entry point
+await import(pathToFileURL(resolve(__dirname, '..', 'dist', 'entry.js')).href)