@saltpub/xiaojiu-agent-bridge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# xiaojiu-agent-bridge
+
+## 0.1.0
+
+### Highlights
+
+- Add npm Registry update checks with a 24-hour local cache.
+- Add `update` and `changelog` CLI commands for version visibility.
+- Publish the package under the public `@saltpub` organization scope.
+- Verify the npm tarball contains no private repository metadata or source files.
+
+### Added
+
+- npm-based update notices for interactive terminal sessions.
+- Structured update metadata in the published package manifest.
+- Local release notes available through `xiaojiu-agent-bridge changelog`.
+
+### Changed
+
+- Use the package manifest version for Agent protocol client information.
+- Keep update state separate from profile and runtime state.
+
+### Fixed
+
+- Prevent private repository URLs, credentials, and source artifacts from entering the npm package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xiaojiu Agent Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+<p align="center">
+  <img src="./assets/readme/hero.gif" width="100%" alt="Xiaojiu Agent Bridge routes a Xiaojiu message through the local bridge runtime to one of five local coding-agent CLIs and returns the reply to the same Xiaojiu session">
+</p>
+
+<p align="center">
+  <sub>静态 SVG 回退：Xiaojiu 消息 → 本机 CLI Agent → 回到同一会话 · <a href="./assets/readme/hero.svg">查看完整路由图</a></sub>
+</p>
+
+# 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 配置。
+
+## 先看一条消息的完整路径
+
+下面是项目机制示意，不是生产环境截图：
+
+```text
+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 安装稳定版：
+
+```bash
+npm install -g @saltpub/xiaojiu-agent-bridge
+```
+
+源码开发：
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm build
+npm install -g .
+```
+
+### 启动第一个 profile
+
+把占位符换成你的 Bot 凭据与 Bot Owner 工号：
+
+```bash
+xiaojiu-agent-bridge run \
+  --app-id <app-id> \
+  --app-secret <app-secret> \
+  --owner <staff-no>
+```
+
+启动后在 Xiaojiu 私聊 Bot 发送 `/status`，即可确认 profile、Agent、工作目录和运行状态。平台地址、凭据、事件订阅与回调安全见 [`docs/xiaojiu.md`](./docs/xiaojiu.md)。
+
+## 多 profile 与服务
+
+需要在同一台机器上管理多个 Agent 时，先创建 profile：
+
+```bash
+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。
+
+```bash
+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，不阻塞当前命令。也可以手动检查和查看随包发布的更新记录：
+
+```bash
+xiaojiu-agent-bridge update --check
+xiaojiu-agent-bridge changelog
+npm install -g @saltpub/xiaojiu-agent-bridge@latest
+```
+
+设置 `XIAOJIU_BRIDGE_NO_UPDATE_CHECK=1` 可以关闭自动检查。CI、非交互终端和管道输出不会显示更新提示。
+
+## 开发验证
+
+```bash
+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`](./docs/xiaojiu.md)。
+
+## 边界
+
+会议智能体、云文档评论、账号切换和 WebSocket 重连等上游能力已从本项目移除，不支持对应命令或流程。本项目不包含独立后端、数据库或面向 Xiaojiu 用户的前端；`web/` 只构建本机管理控制台。
+
+## License
+
+MIT。原项目许可证保留在 [`LICENSE`](./LICENSE)。

package/bin/xiaojiu-agent-bridge.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';