GhostPaw Telegram

@ghostpaw/telegram

Agent Telegram 机器人：每条更新都会在处理程序运行前镜像到 SQLite。

npm install @ghostpaw/telegram

Telegram 机器人通道引擎——使用零运行时依赖的 fetch 传输、支持 FTS5 全文搜索的 SQLite 消息镜像、主动存储文件 BLOB、Markdown 渲染，以及结构化的大模型工具接口。

每条收到的更新都会在处理程序运行前镜像到本地 SQLite 数据库，为你提供机器人所见一切内容的持久化、可查询记录——包括每张照片、每份文档、每条语音消息和每段视频的原始字节。这些文件会在更新存储后于后台下载，并按 SHA-256 哈希值去重保存。如果下载失败，文件行会保留但没有校验和，因此你可以使用 write.downloadFile 重试。它以单个预打包文件的形式发布，同时面向两类用户：用代码构建机器人后端的人类开发者，以及通过结构化工具接口运行操作的 LLM Agent。

MCP 服务

以下每个客户端都会启动同一个 stdio 服务：npx -y @ghostpaw/telegram mcp。 除非设置 GHOSTPAW_TELEGRAM_DB 环境变量（绝对路径）或通过 --db <path> 指定其他位置，否则消息会存储在 ~/.ghostpaw/telegram.db 中。

Claude Code

claude mcp add ghostpaw-telegram -- npx -y @ghostpaw/telegram mcp

也可以将其作为插件安装，它还会安装技能：

/plugin marketplace add GhostPawJS/telegram
/plugin install ghostpaw-telegram@ghostpaw-telegram

Codex CLI（~/.telegram/config.toml）

[mcp_servers.ghostpaw-telegram]
command = "npx"
args = ["-y", "@ghostpaw/telegram", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json） 或项目级 .mcp.json：

{
  "mcpServers": {
    "ghostpaw-telegram": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/telegram", "mcp"]
    }
  }
}

Claude Desktop 用户也可以从最新的 GitHub 发布版本安装 server.mcpb。 项目包含供容器主机使用的 Dockerfile： docker build -t ghostpaw-telegram . && docker run -i --rm -v telegram:/data ghostpaw-telegram。

该服务支持 MCP 2026-07-28（无状态，server/discover）以及基于 initialize 的 2025-11-25、2025-06-18、2025-03-26 和 2024-11-05 版本。

在服务环境中设置 TELEGRAM_BOT_TOKEN，以执行发送和管理操作。 未设置令牌时，这些工具会返回操作计划；本地读取和工具发现可离线使用。 .mcp.json 中的令牌占位符必须由客户端环境提供。 该服务会读取由你的库传输填充的镜像；它不会轮询更新。

CLI

npx -y @ghostpaw/telegram tools
npx -y @ghostpaw/telegram call tg_read '{"subcommand":"list_chats"}'
npx -y @ghostpaw/telegram --db :memory: call tg_send '{"subcommand":"send_message","chatId":123,"text":"Hello"}'

除非设置了 TELEGRAM_BOT_TOKEN，否则发送示例会返回操作计划。

Agent 技能

软件包中包含 SKILL.md 和 skills/telegram/。使用 npx -y @ghostpaw/telegram skill 输出技能内容，或将 skills/telegram/ 复制到你的技能文件夹中。

安装

npm install @ghostpaw/telegram

需要 Node.js 24+（使用内置的 node:sqlite 模块）。

快速入门

import { DatabaseSync } from 'node:sqlite';
import { createBot, initTelegramTables } from '@ghostpaw/telegram';

const db = new DatabaseSync('bot.db');
initTelegramTables(db);

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  onMessage: async ({ message, user }) => {
    console.log(user?.firstName, message.text);
  },
});

await bot.start(); // long-polling

Webhook 模式——改为传入 webhook 配置：

const bot = createBot({
  token: process.env.TELEGRAM_TOKEN!,
  db,
  webhook: { path: '/webhook', port: 8443, secretToken: process.env.TG_SECRET },
  onMessage: async ({ message, user }) => { /* ... */ },
});

await bot.start(); // listens on port 8443

存储内容

每次更新都会先写入 SQLite 镜像，然后才运行你的处理器：

• 消息——文本、媒体、编辑记录、回复关系、相册、主题（带 Unicode 变音符折叠的 FTS5 全文索引）
• 用户——名字、姓氏、用户名、语言代码
• 聊天——标题、类型、成员数量、论坛标记
• 成员——每个聊天中的状态、权限、管理员头衔
• 回应——每位用户对每条消息使用的表情符号，以及按表情符号统计的数量和事件日志
• 文件——元数据和以 BLOB 形式存储的原始字节，使用 SHA-256 去重；每个收到的文件都会在后台下载（DEFAULTS.autoDownload 已弃用且不再使用；它不会改变此行为）
• 回调——内联按钮的点击记录，包含数据和已回复状态
• 机器人状态——任意键值存储和运行统计信息

调用一次 initTelegramTables(db) 即可创建全部八张表。

两类受众

人类开发者

使用 read、write 和 network 命名空间，直接通过代码访问各领域的所有操作：

import { read, write, network } from '@ghostpaw/telegram';

// query the local mirror — no network calls
const chat = read.getChat(db, chatId);
const messages = read.listMessages(db, { chatId, limit: 50 });
const results = read.searchMessages(db, chatId, 'invoice');
const chain = read.replyChain(db, chatId, messageId);

// retrieve a stored file blob
const bytes = write.getFileBlob(db, fileId); // Buffer | null

// send text and media
await write.sendMessage(bot.client, chatId, 'Hello');
await write.sendPhoto(bot.client, chatId, fileId);
await write.sendDocument(bot.client, chatId, buffer, { caption: 'Report' });
await write.broadcast(bot.client, chatIds, 'Announcement');

// streaming — progressive in-place edits
const stream = write.createStream(bot.client, { chatId });
await stream.append('Thinking...');
await stream.replace('Done.');

完整的人类开发者指南及示例请参阅 docs/HUMAN.md。

LLM Agent

使用 tools、skills 和 soul 命名空间，访问结构化的运行时接口：

import { tools, skills, soul } from '@ghostpaw/telegram';

// 4 JSON-schema tools with structured ToolResult responses
const allTools = tools.telegramTools;
const readTool = tools.getTelegramToolByName('tg_read');
const result = readTool?.handler(db, { subcommand: 'search_messages', chatId, query: 'invoice' });

// 6 workflow playbooks for common multi-step scenarios
const allSkills = skills.telegramSkills;

// Herald persona for system prompts
const prompt = soul.renderTelegramSoulPromptFoundation();

每个工具都会返回一个可区分的结果，其中包含 outcome: 'success' | 'no_op' | 'error'、结构化数据和后续步骤提示。无需解析抛出的异常。

涵盖 soul、tools 和 skills 的完整 AI 指南请参阅 docs/LLM.md。

Package 接口

导出项	用途
initTelegramTables(db)	一次性 DDL——在启动时调用一次
createBot(config)	完整的机器人组合，内置 fetch 传输；支持轮询或 webhook
adaptBot(grammy)	将原始 grammy Bot 桥接到 MockBot 执行器接口
read	查询本地 SQLite 镜像（不使用网络）
write	发送消息、媒体和操作；管理文件 BLOB
keyboards	构建内联键盘和回调按钮
network	管理轮询和更新分发
render	纯 Markdown 和文本转换
tools	为 LLM Agent 提供的 4 个 JSON Schema 工具
skills	为 LLM Agent 提供的 6 个工作流操作手册
soul	用于系统提示词的 Herald 人设
DEFAULTS	可调节的运行时常量

工具

默认情况下，工具只返回计划；现有的同步处理器不会执行任何出站操作。 若要执行发送和管理操作，请显式创建异步门面：

const facade = tools.createTelegramToolFacade({
  client: bot.client,
  execute: true,
  perChatPerSecond: 1,
  globalPerSecond: 30,
  maxRetries: 2,
});
const result = await facade.handler(db, 'tg_send', {
  subcommand: 'send_message', chatId: 123, text: 'Hello',
});

省略 execute 即可保留仅生成计划的行为。执行会复用出站执行器，返回包含操作数据的通用结果结构；在适用情况下，还会返回 sent 消息 ID，并在错误信息中隐藏机器人令牌。容量为 1 的令牌桶会限制每次 API 调用的频率（按聊天和全局范围分别限制）；遇到 Telegram 429 retry_after 响应时会暂停重试，默认重试两次。限制按门面实例计算；共享同一机器人的调用方应复用一个门面。多次调用的操作在失败时可能只执行一部分（例如踢出操作会先封禁再解除封禁）。

四种围绕操作人员意图设计的工具：

工具	功能
tg_read	查询消息、聊天、用户、回应、编辑历史记录和回复链
tg_send	发送、编辑、删除、转发和置顶消息；设置回应；广播
tg_manage	封禁、解除封禁、限制、提升权限和踢出用户；查询成员状态
tg_connect	获取机器人统计信息、读取机器人状态、列出活跃聊天

每个工具都会导出运行时元数据——名称、描述、JSON Schema、副作用级别和 readOnly 标记——因此 Agent 框架无需阅读文档即可接入这些工具。

技能

六个以 Markdown 字符串编写的工作流手册：

技能	工作流
manage-telegram-conversations	阅读上下文、回复、置顶、跟踪话题和相册
moderate-chat-effectively	检测违规、警告、限制、封禁并保留审计记录
handle-group-administration	提升权限、降级权限、迁移、配置权限
broadcast-to-audience	撰写、发送、处理错误、重试发送失败的聊天
search-and-retrieve-messages	全文搜索、回复链、编辑历史
stream-progressive-responses	使用防抖流式传输，并处理溢出和错误恢复

文档

文档	面向对象
docs/HUMAN.md	使用 read/write/network API 的开发者
docs/LLM.md	连接工具、技能和 soul 的 Agent 构建者
docs/RECIPES.md	高级 UI/UX 模式：流式传输、审批流程、分页
docs/README.md	架构概览：存储模型、界面、不变量
docs/entities/	各实体手册，包含精确的公开 API 列表

该软件包没有运行时依赖。它使用 Node 24 全局 fetch 发送 Bot API 请求，并使用仓库内的同步 Markdown 解析器。grammy 和 marked 是用于兼容性测试的开发依赖。

createBot 接受可选的 api: { fetch, apiRoot } 设置，以注入 fetch 实现或自定义 Bot API 端点。默认端点为 https://api.telegram.org。

adaptBot 仍接受 grammy Bot 实例。不含上传的调用使用 api.raw；文件上传使用内置客户端，因此 grammy API 转换器不适用于上传。其可选的第二个参数接受 { fetch, apiRoot }。

开发

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup
npm run test:dist   # built artifact checks (after build)
npm run check:deps  # verify zero runtime dependencies

此仓库通过 Volta 固定使用 Node 24.14.0。可使用你偏好的版本管理器。

支持

如果这个软件包对你的项目有所帮助，请考虑赞助其维护工作：

---

Anonyfox • MIT License