# Piagent

轻量级多通道 AI 智能体网关 - OpenClaw 的简洁替代方案

[![npm version](https://img.shields.io/npm/v/piagent.svg)](https://www.npmjs.com/package/piagent)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 简介

**Piagent** 是一个轻量级多通道 AI 智能体网关，功能类似于 [OpenClaw](https://github.com/openclaw-ai/openclaw)，但设计更简洁、部署更轻量。它让你的 AI 代理能够无缝连接各种即时通讯平台（Telegram、Discord、Slack 等），并提供统一的 Web 管理界面。

### 与 OpenClaw 对比

| 特性 | Piagent | OpenClaw |
|------|---------|----------|
| 架构复杂度 | 极简，单进程运行 | 微服务架构，多组件 |
| 资源占用 | 轻量，适合边缘部署 | 需要更多服务器资源 |
| 配置方式 | 单文件 YAML 配置 | 多配置文件，环境变量 |
| 部署难度 | 一行命令启动 | 需要 Docker/K8s 编排 |
| 扩展方式 | 插件式频道适配器 | 完整的插件系统 |
| 核心功能 | 多平台接入、智能路由、会话管理 | 相同 |

**选择 Piagent，如果你需要：**
- 快速部署一个 AI 网关，无需复杂的基础设施
- 在资源受限的环境（如 VPS、边缘设备）运行
- 简单的配置文件管理，不牺牲核心功能
- 轻量级但功能完整的多通道 AI 代理方案

## 功能特性

- 🤖 **多代理管理** - 配置和管理多个 AI 代理，每个代理可独立配置模型、技能和工具
- 📱 **多平台支持** - 同时连接 Telegram、Discord、Slack 等即时通讯平台
- 🔒 **访问控制** - 灵活的访问控制策略（配对模式、白名单、开放访问）
- 🌐 **Web 管理界面** - 内置 Web UI 用于管理和监控网关状态
- 🔌 **WebSocket 实时通信** - 支持实时双向通信
- 💾 **会话管理** - 自动会话历史管理和压缩
- 🛠️ **工具调用** - 支持 AI 代理执行各种工具任务
- 📦 **可选沙箱** - 按需启用代码执行沙箱环境
- ⚡ **一键启动** - 无需依赖外部服务，单命令启动完整网关

## 快速开始

### 安装

```bash
# 使用 npm 全局安装
npm install -g piagent

# 或使用 npx 直接运行
npx piagent config init
```

### 1. 初始化配置

```bash
piagent config init
```

这将在 `~/.piagent/piagent.yaml` 创建默认配置文件。

### 2. 配置 AI 代理

编辑配置文件 `~/.piagent/piagent.yaml`：

```yaml
agents:
  - id: my-assistant
    name: 智能助手
    model:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
    systemPrompt: 你是一个 helpful 的 AI 助手
    skills:
      - coding
      - file-management
```

### 3. 添加通讯频道

#### Telegram 频道

```bash
piagent channel add telegram
```

然后在配置文件中添加 Bot Token。

#### Discord 频道

```bash
piagent channel add discord
```

#### Slack 频道

```bash
piagent channel add slack
```

### 4. 启动网关

```bash
piagent gateway start
```

网关将在 http://localhost:18789 启动，WebSocket 路径为 `/ws`。

## CLI 命令

### 网关管理

```bash
piagent gateway start    # 启动网关服务器
piagent gateway status   # 查看网关状态
```

### 配置管理

```bash
piagent config init      # 初始化配置
piagent config show      # 显示当前配置
piagent config validate  # 验证配置
piagent config path      # 显示配置文件路径
```

### 代理管理

```bash
piagent agent create <id>    # 创建新代理
piagent agent list           # 列出所有代理
piagent agent delete <id>    # 删除代理
```

### 频道管理

```bash
piagent channel add <type>     # 添加频道 (telegram/discord/slack)
piagent channel list           # 列出所有频道
piagent channel remove <type>  # 移除频道
```

### 诊断工具

```bash
piagent doctor           # 运行诊断检查
```

## 配置文件详解

完整的配置示例：

```yaml
version: "1.0"

gateway:
  port: 18789                    # 网关端口
  wsPath: /ws                    # WebSocket 路径
  publicDir: ./public            # 静态文件目录
  sessionDir: ~/.piagent/sessions  # 会话存储目录
  debug: false                   # 调试模式
  corsOrigins: ["*"]             # CORS 允许的来源

# 节点发现配置（可选）
node:
  enabled: false
  discovery:
    mdns: true                   # mDNS 发现
    tailnet: false               # Tailscale 发现

# 代理定义
agents:
  - id: assistant
    name: AI 助手
    description: 通用 AI 助手
    model:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
    systemPrompt: 你是一个 helpful 的 AI 助手
    skills:
      - coding
      - web-search
    tools:
      allow: ["read_file", "write_file", "execute_command"]
    sandbox:
      enabled: true
      workspace: ./workspace
    session:
      historyLimit: 100          # 历史消息限制
      idleMinutes: 60            # 空闲超时（分钟）
      compression: summary       # 历史压缩模式
      queuing: sequential        # 消息队列模式

# 频道配置
channels:
  - type: telegram
    name: tg-bot
    enabled: true
    config:
      botToken: "${TELEGRAM_BOT_TOKEN}"
    access:
      dmPolicy: pairing          # 私信策略: pairing/allowlist/open
      groupPolicy: mention       # 群组策略: mention/allowlist/open

  - type: discord
    name: dc-bot
    enabled: true
    config:
      botToken: "${DISCORD_BOT_TOKEN}"
      applicationId: "${DISCORD_APP_ID}"
      intents: 33281
    access:
      dmPolicy: pairing
      groupPolicy: mention

  - type: slack
    name: slack-bot
    enabled: true
    config:
      botToken: "${SLACK_BOT_TOKEN}"
      appToken: "${SLACK_APP_TOKEN}"
      socketMode: true
    access:
      dmPolicy: pairing
      groupPolicy: mention

# 频道绑定
bindings:
  - agentId: assistant
    channel: tg-bot
    bindType: default            # default/peer/guild/team/account/channel
    bindValue: "*"
    access:
      dmPolicy: pairing
      groupPolicy: mention

# 默认配置
defaults:
  agent: assistant
  model:
    provider: anthropic
    model: claude-3-5-sonnet-20241022
```

## 环境变量

Piagent 支持以下环境变量：

| 变量名 | 说明 |
|--------|------|
| `PIAGENT_CONFIG` | 配置文件路径 |
| `TELEGRAM_BOT_TOKEN` | Telegram Bot Token |
| `DISCORD_BOT_TOKEN` | Discord Bot Token |
| `DISCORD_APP_ID` | Discord Application ID |
| `SLACK_BOT_TOKEN` | Slack Bot Token (xoxb-) |
| `SLACK_APP_TOKEN` | Slack App Token (xapp-) |
| `ANTHROPIC_API_KEY` | Anthropic API Key |
| `OPENAI_API_KEY` | OpenAI API Key |

## 编程 API

### 作为库使用

```typescript
import { Gateway, ConfigManager, SessionManager } from 'piagent';

// 加载配置
const configManager = await ConfigManager.create();
await configManager.load();

// 创建会话管理器
const sessionManager = new SessionManager({
  sessionDir: configManager.getGatewayConfig().sessionDir,
});
await sessionManager.initialize();

// 创建并启动网关
const gateway = new Gateway({ configManager, sessionManager });
await gateway.start();

console.log(`Gateway started on port ${configManager.getGatewayConfig().port}`);
```

### 自定义频道适配器

```typescript
import { BaseChannelAdapter, globalChannelRegistry } from 'piagent';

class MyCustomAdapter extends BaseChannelAdapter {
  readonly channelType = 'custom';

  async initialize(): Promise<void> {
    // 初始化逻辑
  }

  async shutdown(): Promise<void> {
    // 清理逻辑
  }

  async send(message: OutboundMessage): Promise<void> {
    // 发送消息逻辑
  }

  async getProfile(): Promise<ChannelProfile> {
    // 返回频道信息
  }
}

// 注册适配器
globalChannelRegistry.register('custom', MyCustomAdapter);
```

## 系统要求

- Node.js >= 20.0.0
- npm >= 10.0.0

## 平台特定配置

### Telegram

1. 在 Telegram 中搜索 @BotFather
2. 发送 `/newbot` 创建新机器人
3. 按照提示设置名称和用户名
4. 保存获取到的 Bot Token

### Discord

1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
2. 创建新应用
3. 在 Bot 页面添加 Bot 用户
4. 获取 Bot Token 和 Application ID
5. 启用必要的 Intents（Message Content Intent 等）

### Slack

1. 访问 [Slack API](https://api.slack.com/apps)
2. 创建新应用
3. 启用 Socket Mode
4. 添加 Bot Token Scopes: `chat:write`, `app_mentions:read`, `im:history` 等
5. 获取 Bot Token (xoxb-) 和 App Token (xapp-)

## 故障排除

### 检查配置

```bash
piagent doctor
```

### 常见问题

**Q: 无法启动网关**
- 检查端口是否被占用
- 查看配置文件语法是否正确
- 运行 `piagent doctor` 诊断问题

**Q: Telegram 收不到消息**
- 确认 Bot Token 正确
- 检查是否已向 Bot 发送 `/start`

**Q: Discord 消息无响应**
- 确认 Intents 设置正确
- 检查 Bot 是否有频道权限

**Q: Slack 连接失败**
- 确认使用 Socket Mode
- 检查 App Token 格式（以 xapp- 开头）

## 开发

```bash
# 克隆仓库
git clone https://github.com/badlogic/pi-mono.git
cd pi-mono/packages/piagent

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test
```

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 相关项目

- [Pi AI](https://github.com/badlogic/pi-mono/tree/main/packages/ai) - 统一的多提供商 LLM API
- [Pi Agent Core](https://github.com/badlogic/pi-mono/tree/main/packages/agent) - 代理运行时
- [Pi Coding Agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) - 交互式编码代理

## 作者

Mario Zechner

---

如有问题或建议，欢迎提交 Issue 或 PR！