223 lines
6.0 KiB
Markdown
223 lines
6.0 KiB
Markdown
# PIT Channel
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/Version-1.0.0-blue.svg" alt="Version">
|
||
<img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
|
||
<img src="https://img.shields.io/badge/OpenClaw-2026.3+-orange.svg" alt="OpenClaw Version">
|
||
</p>
|
||
|
||
> OpenClaw Channel 插件，连接 PIT Router 实现多 Agent 协作
|
||
|
||
## 📖 简介
|
||
|
||
PIT Channel 是 OpenClaw 的 Channel 插件，用于连接 **PIT Router（个人智能体团队路由服务）**，实现多 Agent 之间的消息路由和协作通信。
|
||
|
||
### 什么是 PIT Router？
|
||
|
||
PIT Router 是一个消息路由服务，负责：
|
||
- 管理多个用户连接
|
||
- 将用户消息路由到正确的 Agent
|
||
- 支持 Agent 之间的协作通信
|
||
- 提供消息确认和离线消息队列
|
||
|
||
## ✨ 功能特性
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 🔌 WebSocket 连接 | 实时双向通信，支持长连接 |
|
||
| 📬 消息收发 | 支持文本、媒体消息 |
|
||
| 🔄 自动重连 | 指数退避策略，网络断开自动重连 |
|
||
| 💾 离线队列 | 消息本地缓存，连接恢复后自动发送 |
|
||
| ❤️ 心跳检测 | 连接保活，超时自动断开 |
|
||
| ✅ 消息确认 | 发送确认机制，确保消息可靠 |
|
||
| 📦 消息分块 | 智能 Markdown 分块，超长消息自动拆分 |
|
||
| 📊 指标监控 | 连接状态、消息计数、延迟统计 |
|
||
| 🎨 Web UI | 配置管理界面，实时状态展示 |
|
||
| 🔧 版本管理 | 配置迁移、自动更新检查 |
|
||
|
||
## 🏗️ 架构
|
||
|
||
```
|
||
┌──────────────┐ WebSocket ┌──────────────┐
|
||
│ PIT Router │ ←─────────────→ │ PIT Channel │
|
||
│ (服务端) │ │ (OpenClaw) │
|
||
└──────────────┘ └──────────────┘
|
||
↑ ↓
|
||
│ ┌──────────────┐
|
||
│ │ Agent │
|
||
└─────────────────────────┤ (OpenClaw) │
|
||
└──────────────┘
|
||
```
|
||
|
||
## 📦 安装
|
||
|
||
### 前置要求
|
||
|
||
- Node.js >= 20.0.0
|
||
- OpenClaw >= 2026.3.0
|
||
- PIT Router 服务端
|
||
|
||
### 安装插件
|
||
|
||
```bash
|
||
# 方式1: 从本地安装
|
||
openclaw plugins install ./PIT_Channel
|
||
|
||
# 方式2: 从 npm 安装（未来支持）
|
||
openclaw plugins install @openclaw/pit-channel
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
### 基本配置
|
||
|
||
在 `openclaw.json` 中添加：
|
||
|
||
```json
|
||
{
|
||
"plugins": {
|
||
"entries": {
|
||
"pit-bot": {
|
||
"enabled": true,
|
||
"config": {
|
||
"routerUrl": "ws://your-pit-router:9000/ws",
|
||
"authToken": "${PIT_ROUTER_TOKEN}",
|
||
"heartbeatInterval": 30000,
|
||
"heartbeatTimeout": 10000,
|
||
"ackTimeout": 30000,
|
||
"maxQueueSize": 100
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置参数说明
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `routerUrl` | string | - | **必填** PIT Router WebSocket 地址 |
|
||
| `authToken` | string | - | 认证 Token，支持 `${ENV_VAR}` 引用环境变量 |
|
||
| `enabled` | boolean | true | 是否启用 |
|
||
| `reconnectInterval` | number | 5000 | 重连间隔（毫秒） |
|
||
| `heartbeatInterval` | number | 30000 | 心跳间隔（毫秒） |
|
||
| `heartbeatTimeout` | number | 10000 | 心跳超时（毫秒） |
|
||
| `ackTimeout` | number | 30000 | 消息确认超时（毫秒） |
|
||
| `maxQueueSize` | number | 100 | 离线消息队列最大长度 |
|
||
|
||
### 多账户配置
|
||
|
||
```json
|
||
{
|
||
"plugins": {
|
||
"entries": {
|
||
"pit-bot": {
|
||
"enabled": true,
|
||
"config": {
|
||
"routerUrl": "ws://localhost:9000/ws",
|
||
"accounts": {
|
||
"work": {
|
||
"enabled": true,
|
||
"name": "工作 Agent",
|
||
"routerUrl": "ws://work.example.com:9000/ws",
|
||
"authToken": "${PIT_WORK_TOKEN}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 开发
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 类型检查
|
||
npm run typecheck
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 运行测试
|
||
npm test
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
PIT_Channel/
|
||
├── src/
|
||
│ ├── index.ts # 插件入口
|
||
│ ├── channel.ts # Channel 主文件
|
||
│ ├── config.ts # 配置处理
|
||
│ ├── gateway.ts # WebSocket 连接 + 队列
|
||
│ ├── outbound.ts # 消息发送
|
||
│ ├── types.ts # 类型定义
|
||
│ ├── webui/ # Web UI 模块
|
||
│ │ ├── routes.ts # HTTP 路由
|
||
│ │ ├── api.ts # REST API
|
||
│ │ └── static.ts # 静态页面
|
||
│ ├── update/ # 更新模块
|
||
│ │ ├── version.ts # 版本检查
|
||
│ │ ├── migrate.ts # 配置迁移
|
||
│ │ └── rollback.ts # 回滚机制
|
||
│ └── utils/ # 工具模块
|
||
│ ├── logger.ts # 日志
|
||
│ ├── metrics.ts # 指标监控
|
||
│ ├── queue.ts # 消息队列
|
||
│ ├── chunker.ts # 智能分块
|
||
│ └── payload.ts # 消息负载
|
||
├── docs/
|
||
│ └── PIT_Channel_Technical_Spec.md # 技术文档
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── openclaw.plugin.json
|
||
```
|
||
|
||
## 🌐 Web UI
|
||
|
||
插件提供 Web 配置界面，访问地址：
|
||
|
||
```
|
||
http://<gateway>:18888/plugins/pit-bot
|
||
```
|
||
|
||
功能：
|
||
- 📊 连接状态实时显示
|
||
- ⚙️ 配置参数修改
|
||
- 🔌 连接/断开控制
|
||
- 📈 指标监控展示
|
||
|
||
## 📖 文档
|
||
|
||
- [技术规格文档](./docs/PIT_Channel_Technical_Spec.md) - 详细的架构和实现说明
|
||
- [OpenClaw 插件文档](https://docs.openclaw.ai) - OpenClaw 官方文档
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License - see [LICENSE](LICENSE) for details.
|
||
|
||
## 👤 作者
|
||
|
||
- 作者：小白 🐶
|
||
- 联系：云下飞（主人）
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
Made with ❤️ by [OpenClaw](https://github.com/openclaw/openclaw)
|
||
|
||
</div>
|