PIT_Channel/README.md

# 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>