docs: 补充完整的项目 README 文档
This commit is contained in:
228
README.md
228
README.md
@@ -1,32 +1,222 @@
|
|||||||
# PIT_Channel
|
# PIT Channel
|
||||||
|
|
||||||
OpenClaw Channel plugin for connecting to PIT Router, enabling multi-Agent collaboration.
|
<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>
|
||||||
|
|
||||||
## Features
|
> OpenClaw Channel 插件，连接 PIT Router 实现多 Agent 协作
|
||||||
|
|
||||||
- Connect to PIT Router service
|
## 📖 简介
|
||||||
- Multi-Agent message routing
|
|
||||||
- Inter-Agent communication support
|
|
||||||
|
|
||||||
## Install
|
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
|
```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 install
|
||||||
|
|
||||||
|
# 类型检查
|
||||||
|
npm run typecheck
|
||||||
|
|
||||||
|
# 构建
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# 运行测试
|
||||||
|
npm test
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
### 项目结构
|
||||||
|
|
||||||
```typescript
|
```
|
||||||
import { PITChannel } from './src/index';
|
PIT_Channel/
|
||||||
|
├── src/
|
||||||
const channel = new PITChannel({
|
│ ├── index.ts # 插件入口
|
||||||
routerUrl: 'http://pit-router.example.com',
|
│ ├── channel.ts # Channel 主文件
|
||||||
agentId: 'my-agent'
|
│ ├── config.ts # 配置处理
|
||||||
});
|
│ ├── gateway.ts # WebSocket 连接 + 队列
|
||||||
|
│ ├── outbound.ts # 消息发送
|
||||||
await channel.connect();
|
│ ├── 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
|
||||||
```
|
```
|
||||||
|
|
||||||
## License
|
## 🌐 Web UI
|
||||||
|
|
||||||
MIT
|
插件提供 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>
|
||||||
|
|||||||
Reference in New Issue
Block a user