xiaojiu-agent-bridge

在 Xiaojiu 里发一句私聊或群内 @ 消息，让本机的 Claude Code、Codex CLI、Pi、OpenCode 或 OMP 在指定工作目录执行；Markdown 或卡片结果回到同一个会话。

本地优先的消息桥：不自建后端，把 Xiaojiu 的聊天入口接到你已经安装好的 coding-agent CLI。

你会得到什么

• 从聊天开始：接收 message_receive 与 card_action_trigger Webhook，快速确认后异步处理。
• 会话不丢上下文：按聊天 / 话题 scope 保存 Agent 会话、工作目录与运行状态。
• 一套入口，多种 Agent：统一适配 Claude Code、Codex CLI、Pi、OpenCode 和 OMP。
• 可控地运行：合并连续输入，执行访问控制、超时、中断、恢复和附件缓存。
• 结果回到原处：以 Markdown 或消息卡片回复；流式输出通过更新消息模拟。
• 团队可管理：用 profile、后台服务和本机 Web 控制台管理多套 Bot 配置。

先看一条消息的完整路径

下面是项目机制示意，不是生产环境截图：

Xiaojiu Webhook
    │  message_receive / card_action_trigger
    ▼
HTTP 校验 · header.id 去重 · 立即 200
    ▼
消息合并 · scope · 运行策略 · 工作目录
    ▼
RunExecutor → AgentAdapter → 本机 CLI 子进程
    ▼
RunState → Markdown / 卡片 → Xiaojiu 会话

每个 scope 同时最多运行一个任务；全局子进程池默认最多 10 个运行，范围为 1–50。共享服务器可托管多个 profile，并按 App ID 分发事件。

快速开始

环境要求

• Node.js >= 20.12.0
• pnpm 10（源码开发）
• 已安装并登录至少一个本地 Agent：claude、codex、pi、opencode 或 omp
• 一个 Xiaojiu Bot，以及 Xiaojiu 能访问的 HTTP/HTTPS 回调地址

安装与构建

从 npm 安装稳定版：

npm install -g @saltpub/xiaojiu-agent-bridge

源码开发：

pnpm install
pnpm typecheck
pnpm build
npm install -g .

启动第一个 profile

把占位符换成你的 Bot 凭据与 Bot Owner 工号：

xiaojiu-agent-bridge run \
  --app-id <app-id> \
  --app-secret <app-secret> \
  --owner <staff-no>

启动后在 Xiaojiu 私聊 Bot 发送 /status，即可确认 profile、Agent、工作目录和运行状态。平台地址、凭据、事件订阅与回调安全见 docs/xiaojiu.md。

多 profile 与服务

需要在同一台机器上管理多个 Agent 时，先创建 profile：

xiaojiu-agent-bridge profile create claude --agent claude --owner <staff-no>
xiaojiu-agent-bridge profile create codex --agent codex --owner <staff-no>
xiaojiu-agent-bridge profile list
xiaojiu-agent-bridge profile use claude

一次 start / run 只上线一个 bot。默认共用 9699 时，第二个 start --profile 会加入已有监听，而不是再起一套服务。用 ps 查看各进程的端口和在线 bot。

xiaojiu-agent-bridge start
xiaojiu-agent-bridge start --profile codex
xiaojiu-agent-bridge ps
xiaojiu-agent-bridge status
xiaojiu-agent-bridge stop

需要本机网页时加 --web-ui。start 会按操作系统注册服务：macOS 使用 launchd，Linux 使用 systemd，Windows 使用任务计划程序。也可以用 kill <id|pid|#> 停止指定进程。

Xiaojiu 内命令

| 命令 | 作用 | | --- | --- | | /new、/reset | 清空当前会话 | | /status | 查看 profile、Agent、工作目录和运行状态 | | /agent <claude\|codex\|pi\|opencode\|omp> | 空闲时切换当前 profile 的 Agent | | /cd <path> | 切换工作目录并重置会话 | | /ws list、/ws save <name>、/ws use <name> | 管理命名工作空间 | | /resume | 恢复兼容的历史会话 | | /invite user @某人 | 允许用户私聊使用 | | /invite admin @某人 | 添加管理员 | | /invite group | 允许当前群或频道使用 | | /remove user @某人、/remove admin @某人、/remove group | 移除访问资格 | | /stop | 停止当前任务 | | /timeout [N\|off\|default] | 调整当前会话超时 | | /doctor [描述] | 执行低敏诊断 | | /help | 显示帮助 |

配置与安全

默认配置目录为 ~/.xiaojiu-agent-bridge，可通过 XIAOJIU_BRIDGE_HOME 修改。Webhook 默认监听 0.0.0.0:9699，默认 profile 回调路径为 /webhook/<profile>。

生产部署请使用 HTTPS、不可猜测的回调路径、header.appId 校验和反向代理访问控制。不要把 App Secret、回调密钥、访问令牌或原始 prompt 写进配置、日志或聊天。

密钥由 bridge 加密存储；如需迁移 profile，可使用 profile export，并谨慎处理包含 secrets 的导出内容。

版本更新

CLI 在交互式终端中每 24 小时检查一次 npm Registry，不阻塞命令启动。为避免干扰首次配置或交互式界面，提示只会在支持的终端会话中显示，并可随时手动检查和查看随包发布的更新记录：

xiaojiu-agent-bridge update
xiaojiu-agent-bridge changelog
npm install -g @saltpub/xiaojiu-agent-bridge@latest

设置 XIAOJIU_BRIDGE_NO_UPDATE_CHECK=1 可以关闭自动检查。CI、非交互终端和管道输出不会显示更新提示。

开发验证

pnpm vitest run tests/unit/channel tests/integration/channel
pnpm typecheck
pnpm test
pnpm build

没有真实 Xiaojiu 凭据时，只能验证本地契约和模拟 HTTP 流程。发布包只包含 dist、bin、README.md、CHANGELOG.md 与 LICENSE；平台级接入资料保留在 docs/xiaojiu.md。

边界

会议智能体、云文档评论、账号切换和 WebSocket 重连等上游能力已从本项目移除，不支持对应命令或流程。本项目不包含独立后端、数据库或面向 Xiaojiu 用户的前端；web/ 只构建本机管理控制台。

License

MIT。原项目许可证保留在 LICENSE。