Pi Bot

Pi Bot 是一个与聊天平台无关的持久化 Agent 核心。它只处理对话语义、模型调用、记忆、多模态引用和可靠出站队列，不包含任何具体 IM SDK、登录协议或消息网关实现。

IM SDK / Gateway
       ↕
ChannelAdapter + ChannelPlugin v1
       ↕
ChannelRuntime
       ↕
GroupAgentCore → Pi Agent → durable outbox

具体平台通过仓库外的适配包接入。适配器负责原生事件转换和消息发送；核心只接收标准事件、输出标准动作，并按适配器声明的能力做运行时校验。

特性

• 完整保存未触发机器人的群聊消息，后续回复仍能理解真实上下文。
• transcript、长期 memory、behavior 三层状态相互独立且可审计。
• 入站事件幂等、同会话串行、回复与 outbox 原子提交。
• 支持文本、图片、音频、语音、视频、文件、链接、引用和成员提及。
• 媒体只保存 AssetRef，二进制内容位于独立的 AssetStore。
• 适配器用版本化 feature 声明收发能力，用强类型 capability 暴露可选操作。
• capability 不会自动成为模型工具；只有显式配置的 toolProviders 能进入 Pi。
• 支持按需图片理解、附件检查、知识检索、MCP 工具和语音生成。
• 群聊触发支持点名、唤醒词、引用、自然续聊、always-on 和关闭模式。
• 模型可选择沉默，不会向群聊发送内部占位符。

环境

• Node.js >= 22.13
• 一个 Pi 支持的模型 API key

npm ci
npm run check

最小用法

import { getModel } from "@earendil-works/pi-ai";
import {
  CHANNEL_PLUGIN_API_VERSION,
  ChannelRuntime,
  GroupAgentCore,
  PiAgentRunner,
  defineChannelPlugin,
} from "pi-bot";

const core = new GroupAgentCore({
  bot: {
    id: "bot-1",
    displayName: "小派",
    wakeWords: ["派派", "小派"],
  },
  runner: new PiAgentRunner({
    model: getModel("anthropic", "claude-sonnet-4-6"),
    apiKey: () => process.env.ANTHROPIC_API_KEY,
    thinkingLevel: "low",
  }),
  databasePath: "./data/agent.sqlite",
  defaultGroupActivation: "mention",
  operatorIds: ["operator-1"],
});

const plugin = defineChannelPlugin({
  apiVersion: CHANNEL_PLUGIN_API_VERSION,
  id: "example-adapter-instance",

  async start(context) {
    sdk.onMessage(async (raw) => {
      await context.ingest({
        type: "message",
        id: raw.eventId,
        transportMessageId: raw.messageId,
        conversation: {
          id: raw.conversationId,
          kind: raw.isGroup ? "group" : "direct",
          title: raw.conversationTitle,
        },
        sender: {
          id: raw.senderId,
          displayName: raw.senderName,
        },
        text: raw.text,
        timestamp: raw.timestamp,
        mentions: raw.mentionedBot ? [{ id: "bot-1" }] : [],
      });
    });
  },

  async send(action) {
    await sdk.send({
      conversationId: action.conversationId,
      text: action.text,
      parts: action.parts,
      replyTo: action.replyToMessageId,
      idempotencyKey: action.id,
    });
  },

  async stop() {
    await sdk.close();
  },
});

const runtime = new ChannelRunti