Piagnet

多通道 AI 网关 - 让你的 AI 代理连接各种即时通讯平台

简介

Piagnet 是一个多通道 AI 网关，允许 AI 代理通过各种消息平台（Telegram、Discord、Slack 等）进行通信，并提供基于 Web 的管理界面。

功能特性

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

安装

# 使用 npm 全局安装
npm install -g piagnet

# 或使用 npx 直接运行
npx piagnet config init

快速开始

1. 初始化配置

piagnet config init

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

2. 配置 AI 代理

编辑配置文件 ~/.piagnet/config.yaml：

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

3. 添加通讯频道

Telegram 频道

piagnet channel add telegram my-bot --config.botToken=YOUR_BOT_TOKEN

Discord 频道

piagnet channel add discord my-discord --config.botToken=YOUR_BOT_TOKEN --config.applicationId=YOUR_APP_ID

Slack 频道

piagnet channel add slack my-slack --config.botToken=xoxb-YOUR-TOKEN --config.appToken=xapp-YOUR-APP-TOKEN

4. 绑定代理到频道

piagnet binding create my-assistant telegram:my-bot --type=default

5. 启动网关

piagnet gateway start

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

CLI 命令

网关管理

piagnet gateway start    # 启动网关服务器
piagnet gateway stop     # 停止网关服务器
piagnet gateway status   # 查看网关状态

配置管理

piagnet config init      # 初始化配置
piagnet config show      # 显示当前配置
piagnet config edit      # 编辑配置文件

代理管理

piagnet agent create <id>    # 创建新代理
piagnet agent list           # 列出所有代理
piagnet agent show <id>      # 显示代理详情
piagnet agent delete <id>    # 删除代理

频道管理

piagnet channel add <type> <name>    # 添加频道
piagnet channel list                 # 列出所有频道
piagnet channel remove <name>        # 移除频道

诊断工具

piagnet doctor           # 运行诊断检查

配置文件详解

完整的配置示例：

version: "1.0"

gateway:
  port: 18789                    # 网关端口
  wsPath: /ws                    # WebSocket 路径
  publicDir: ./public            # 静态文件目录
  sessionDir: ~/.piagnet/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-sonnet-20240229
    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             # 可选，自定义 intents
    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-sonnet-20240229

环境变量

Piagnet 支持以下环境变量：

| 变量名 | 说明 | |--------|------| | PIAGNET_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

作为库使用

import { Gateway, ConfigManager, SessionManager } from 'piagnet';

// 加载配置
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}`);

自定义频道适配器

import { BaseChannelAdapter, globalChannelRegistry } from 'piagnet';

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
2. 创建新应用
3. 在 Bot 页面添加 Bot 用户
4. 获取 Bot Token 和 Application ID
5. 启用必要的 Intents（Message Content Intent 等）

Slack

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

故障排除

检查配置

piagnet doctor

常见问题

Q: 无法启动网关

• 检查端口是否被占用
• 查看配置文件语法是否正确

Q: Telegram 收不到消息

• 确认 Bot Token 正确
• 检查是否已向 Bot 发送 /start

Q: Discord 消息无响应

• 确认 Intents 设置正确
• 检查 Bot 是否有频道权限

Q: Slack 连接失败

• 确认使用 Socket Mode
• 检查 App Token 格式（以 xapp- 开头）

开发

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

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

许可证

MIT License - 详见 LICENSE 文件

相关项目

• Pi AI - 统一的多提供商 LLM API
• Pi Agent - 代理运行时
• Pi Coding Agent - 交互式编码代理

作者

Mario Zechner

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