@ghostpaw/ 电报
代理Telegram bots:在操作器运行前,每个更新镜都映入了SQLite.
ghostpaw-telegram --help # after installing the release binary
Telegram bot 通道引擎——以零运行时间依赖性获取传输,以FTS5全文搜索的SQLite消息镜像,急切地将文件BLOB存储,markdown渲染,以及结构化的LLM工具外观.
每一个收到的更新在您处理器运行前都会被镜像到一个本地的SQLite数据库中,给您一个持续,可查询的机器人所看到的一切记录——包括每张照片的原始字节,文档,语音信息,和视频,这些在更新被存储后在背景中下载,并保存一次按 SHA-256 hash. 下载失败会离开文件行而不检查和, 这样您就可以用它重试 write.downloadFile它作为单一的被捆绑的blob同时为两个受众设计:人类开发者在代码中构建bot后端,LLM代理通过结构化的工具外观运行.
MCP 服务器
下面每个客户端都会启动相同的 stdio 服务器 : ghostpaw-telegram mcp。 。 。 .
对于 npm 环境, 使用 npx -y @ghostpaw/telegram mcp。 。 。 .
信件存在于 ~/.ghostpaw/telegram.db 除非 GHOSTPAW_TELEGRAM_DB
环境变量(绝对路径)或 --db <path> 说不然.
克劳德代码
claude mcp add ghostpaw-telegram -- ghostpaw-telegram mcp
或作为插件,同时安装该技能:
/plugin marketplace add GhostPawJS/telegram
/plugin install ghostpaw-telegram@ghostpaw-telegram
代码 CLI (单位:千美元)~/.telegram/config.toml(中文(简体) )
[mcp_servers.ghostpaw-telegram]
command = "ghostpaw-telegram"
args = ["mcp"]
光标 (单位:千美元).cursor/mcp.json, (中文(简体) ), 克劳德桌面 (单位:千美元)claude_desktop_config.json(中文(简体) )
或项目 .mcp.json数字 :
{
"mcpServers": {
"ghostpaw-telegram": {
"command": "ghostpaw-telegram",
"args": ["mcp"]
}
}
}
Claude 桌面用户也可以安装 server.mcpb 从
最新 GitHub 发布。 。 。 .
容器主机包含一个 Docker 文件 :
docker build -t ghostpaw-telegram . && docker run -i --rm -v telegram:/data ghostpaw-telegram。 。 。 .
服务器会说MCP 2026-07-28(无状态, server/discover)和
以2025-11-25,2025-06-18,2025-03-26和2024-11-05为基础初始化修订.
设定 TELEGRAM_BOT_TOKEN 在服务器环境中执行发送和节制动作.
没有符号,这些工具返回计划;本地读取和工具发现工作下线.
这个 .mcp.json 符号占位符必须由客户端环境提供.
服务器会读取您库中包含的镜像; 它不会对更新进行民调 .
在沙盒内跑动
密码CLI内部 --sandbox workspace-write 届会、数据库及其
父目录必须在可写入的根内, 包括 SQLite 的 -wal 财务报告和审定财务报表
-shm 边文件。 默认 DB 下方 ~/.ghostpaw 这些根的外边可能失败
与 SQLITE_CANTOPEN 或者说 EPERM (通常退出 70; 目录创建失败)
可能退出 2),即使正常的 shell 权限允许访问. 将 DB 放在工作空间内 --db ./state/telegram.db, (中文(简体) ),
或设置 GHOSTPAW_TELEGRAM_DB="$PWD/state/telegram.db" 用于CLI/MCP.
要使用外部 DB 目录, 请在启动 OpenAI Codex CLI 时添加
(替换) <dir-with-db> 其绝对路径:
codex exec --sandbox workspace-write --add-dir <dir-with-db> "Run the GhostPaw CLI"
或者设置 sandbox_workspace_write.writable_roots 内
~/.codex/config.toml 在会议开始前:
[sandbox_workspace_write]
writable_roots = ["/absolute/dir-with-db"]
名词 CLI
27个指令路径来自4个工具策略:
bot stats | state <key> | chats
mirror message <chatId> <messageId>
mirror messages <chatId> | search <chatId> <query>
mirror chat <chatId> | chats | user <userId> | users
mirror reactions <chatId> <messageId>
mirror replies <chatId> <messageId> | edits <chatId> <messageId>
message send <chatId> <text> | edit <chatId> <messageId> <text>
message delete <chatId> <messageId> | pin <chatId> <messageId> | unpin <chatId> <messageId>
message typing <chatId> | forward <fromChatId> <messageId> <toChatId>
member ban <chatId> <userId> | unban <chatId> <userId> | restrict <chatId> <userId>
member promote <chatId> <userId> | kick <chatId> <userId> | show <chatId> <userId>
member list <chatId>
使用 help <noun> 或者说 <noun> <verb> --help 为图谋旗帜。 接受字段数
kebab- case 旗帜, 如 --can-send-messages true 财务报告和审定财务报表 --is-admin false。 。 。 .
对象接受JSON;阵列接受重复的旗帜或JSON. 价值是字面的,
包括领导 @; 没有旗读取文件 .
单人 - 读取 stdin JSON; 清晰的旗帜覆盖 stdin 字段.
-- 结束选项解析.
全球旗帜 : --db <path>, (中文(简体) ), --json, (中文(简体) ), -q, --quiet, (中文(简体) ), --compact, (中文(简体) ), --help编号 :-h, (中文(简体) ),
--version编号 :-V编号 :-v, (中文(简体) ), --no-color. 管道输出默认为 JSON;
-q, --quiet 压制斯通. completions bash|zsh|fish 打印补全
设置和 version 打印软件包版本和安装变体.
| 新建命令退出代码 | 含义 |
|---|---|
| 0 个 | 成功与否 |
| 1个 | 工具错误 |
| 2个 | 用法或计划错误 |
| 3个 | 需要澄清或未查明 |
| 页:1 | 冲突或版本不匹配 |
| 70个 | 意外的内部错误 |
现有 tools [--json], (中文(简体) ), describe <tool>, (中文(简体) ), call <tool> [JSON|-]平顶
tg_<tool> --parameter value, (中文(简体) ), mcp 财务报告和审定财务报表 skill 表格保持他们的行为.
名词动词发送和节制命令总是返回计划,包括:
何时 TELEGRAM_BOT_TOKEN 已经设定。 处决仍可通过
createTelegramToolFacade({ client, execute: true }); 现有工具级别
CLI 和 MCP 表格执行时 TELEGRAM_BOT_TOKEN 已经设定.
本地镜像读取,计划下线工作,无从考证.
GHOSTPAW_TELEGRAM_DB 设置默认数据库, 否则
~/.ghostpaw/telegram.db 用于; --db 二者皆能超越.
离线示例 :
ghostpaw-telegram mirror chats --db /tmp/telegram-port-example.db --json
ghostpaw-telegram message send 123 'Offline plan' --db /tmp/telegram-port-example.db --json
ghostpaw-telegram mirror messages 123 --db /tmp/telegram-port-example.db --json
空镜像不返回聊天或信件 。 发送返回动作 不发送Telegram消息的描述符.
国 际
ghostpaw-telegram tools
ghostpaw-telegram call tg_read '{"subcommand":"list_chats"}'
ghostpaw-telegram --db :memory: call tg_send '{"subcommand":"send_message","chatId":123,"text":"Hello"}'
发送示例返回一个计划,除非 TELEGRAM_BOT_TOKEN 已经设定.
使用 ghostpaw-telegram skill --short 对于紧凑的CLI作弊表,
ghostpaw-telegram skill --list 列出向导,以及
ghostpaw-telegram skill <guide> 读一个.
在 POSIX 上, CLI 和 MCP 镜像数据库以模式创建 0600,包括:
新建 SQLite WAL/SHM 文件. 为数据库使用模式创建的目录 0700。 。 。 .
保存现有的数据库和目录权限. 镜子可能包含
私人聊天内容和文件blobs.
特工技能
SKILL.md 财务报告和审定财务报表 skills/telegram/ 包裹里有船 打印技能
ghostpaw-telegram skill 或副本 skills/telegram/ 输入您的技能文件夹.
安装
释放二进制( 默认)
每行下载最新发行资产,对照发行的SHA256SUMS进行检查,并安装在PATH上(~/.local/bin on Linux/macOS;Windows脚本将其文件夹添加到用户PATH上).
这些行从不编辑 ~/. profile 或其他 shell 启动文件 : export PATH 仅适用于当前外壳。 为了保持它的新壳,使用 ~/.profile 线条下方.
linux-x64: (英语)
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"
linux- arm64 : (原始内容存档于2017-09-31) (英语)
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"
达文 -阿尔马64:
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"
达文-x64:
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"
窗口- x64 (PowerShell; 坚持将安装文件夹添加到用户 PATH 中):
irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex
跳过持久用户 PATH 编辑 :
$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex
绑入发布会 :
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 --version 0.7.8 && export PATH="$HOME/.local/bin:$PATH"
并添加~/. local/ bin 到~. profile( 编辑~. profile一次; 如果它已经提及~/. local/ bin; zsh 登录 shells 读作~. zprofile, 所以使用该文件名 :
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"
$ ghostpaw-telegram --version
telegram 0.7.8 (binary, linux-x64)
用于比较版本的脚本 --version --short 或者说 --version --json。 。 。 .
与 0. 7.1 linux- x64 二进制对接新数据库的会话, 没有设置符号, 因此出局命令只返回计划中的动作, 没有发送任何消息( 输出管道通过) jq 保持简短:

同一届会议 动画 GIF。 。 。 .
其他放行安装器 :
mise use -g github:GhostPawJS/telegram
ubi --project GhostPawJS/telegram --exe ghostpaw-telegram --in ~/.local/bin
eget GhostPawJS/telegram
对于 水量计,定义 a
github_release 软件包在 aqua.yaml数字 :
registries:
- name: telegram
type: local
path: telegram-registry.yaml
packages:
- name: GhostPawJS/telegram@v<VERSION>
registry: telegram
telegram-registry.yaml数字 :
packages:
- type: github_release
repo_owner: GhostPawJS
repo_name: telegram
asset: ghostpaw-telegram-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz
format: tar.gz
replacements: { amd64: x64 }
overrides:
- goos: windows
asset: ghostpaw-telegram-{{trimV .Version}}-windows-{{.Arch}}.zip
format: zip
files:
- name: ghostpaw-telegram
安装脚本验证 SHA256SUMS. 校验已下载的归档 构建证明数字 :
gh attestation verify <archive> -R GhostPawJS/telegram
设定 GHOSTPAW_VERIFY=attestation 用于验证 install.sh。 。 。 .
二进制是无签名的;macOS 二进制是带有临时签名的. 对于浏览器
在 macOS 上下载,删除隔离
xattr -d com.apple.quarantine /path/to/ghostpaw-telegram。 。 。 .
Linux 二进制需要 glibc 2.28+;在高山上使用npx.
见 二进制构建工作流程。 。 。 .
0.7.1的大小(每个二进制中的26.12.1号):
| 目标 | 存档 | 二进制 |
|---|---|---|
| linux-x64 | 41.6 MB tar.gz | 117.4甲基溴 |
| linux- arm64 (英语) | 41.1 甲基溴 tar.gz | 115.1甲基溴 |
| darwin-arm64 (英语) | 44.8 MB tar.gz | 146.6甲基溴 |
| 达尔文-x64 | 46.3 MB tar.gz | 149.5甲基溴 |
| 窗口-x64 | 38.4 MB 拉链 | 105.6甲基溴 |
在ubuntu-24.04、macos-15和窗口-2025上检查了释放装置.
npx / npm (针对基于 npm 的环境)
npx @ghostpaw/telegram --help
npm install -g @ghostpaw/telegram
要求数 节点24+ 用于内置 node:sqlite 模块。 npm包被取出816个KB.
库(用于将它嵌入代码)
npm install @ghostpaw/telegram
import { tools } from '@ghostpaw/telegram';
见 图书馆使用量。 。 。 .
快速启动
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 模式——通过 a 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
文档
阅读使用指南、食谱、结构和实体参考手册.
- 概览: 手册涵盖的内容和起点
- 人类使用: 在代码中直接使用库
- LLM 使用情况: 工具、技能和激励代理人的灵魂
- 食谱: 菜单、键盘和答复的图案
- 建筑:如何制定守则
- 聊天: 机器人看到的每一次谈话
- 信件: 进出消息
- 用户: 机器人和人类账户
- 成员: 谁在哪个聊天, 具有地位
- 回电: 内置键盘按钮
- 文件:相片、文件和语音注释
- 反应:emoji反应及其计数
存储什么
每次更新都会在操作器运行前被镜像到 SQLite 中 :
- 信件 ——文本,媒体,编辑,回复边缘,相册,线程(FTS5全文索引有Unicodediacritic折叠)
- 用户 ——取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名
- 聊天 ——标题,类型,成员计数,论坛旗
- 成员 – 状态,权限,每个聊天的管理员标题
- 反应 ——每个用户每个消息的emoji,每个emoji计数和事件日志
- 文件 ——元数据+原字节被存储为BLOB,SHA-256被去除;每个入库文件在背景中下载(
DEFAULTS.autoDownload已贬值和未使用;它不会改变这种行为) - 回电 — 内置按钮按下数据并回答状态
- Bot 状态 任意的钥匙/价值储存和运行中的统计数据
所有8个表格都是在一个呼叫中创建的: 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.');
见 文件/人文资料 给全人类的指南 并有工作的例子.
LLM 剂
使用 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',结构数据,以及下一步提示。 没有任何例外.
见 文件/LLM.md 包括灵魂、工具和技能.
软件包表面
| 导出 | 作用 |
|---|---|
initTelegramTables(db) | 一发DDL——启动时拨打一次 |
createBot(config) | 装有内置交通工具的完整瓶装; 投票或网钩 |
adaptBot(grammy) | 搭桥一个生格莱美 Bot 页:1 MockBot 执行器接口 |
read | 查询本地 SQLite 镜像( 无网络) |
write | 发送消息、媒体和动作; 管理文件 BLOBs |
keyboards | 构建内置键盘和回调按钮 |
network | 管理投票和更新发送 |
render | 纯标记和文本转换 |
tools | 4个LLM代理的JSON-schema工具 |
skills | 6个LLM代理工作流程游戏本 |
soul | 系统提示的先驱人物a |
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 消息
酌情提供身份证明,并用错误的口罩表示瓶形标志。 一号能力桶
限制每次聊天和全球每次API呼叫; Telegram 429 retry_after 答复
暂停重试, 默认情况下重复两次 。 限制适用于每个表面实例;
重复使用一个假面 供呼叫者分享一个机器人。 部分执行可能发生在
多呼吁行动失败(例如,踢出禁令然后取消禁令).
围绕操作者意图塑造的四个工具:
| 工具 | 它会做什么 |
|---|---|
tg_read | 查询消息、聊天、用户、反应、编辑历史、回复链 |
tg_send | 发送、编辑、删除、转发、发接; 设定反应; 广播 |
tg_manage | 禁止、取消、限制、推广、踢出用户;查询成员状况 |
tg_connect | 获取 bot 数据, 读取 bot 状态, 列出活动聊天 |
每个工具导出运行时元数据——名称,描述,JSON Schema,副作用级别, readOnly 旗帜 —— 这样,代理吊带就可以在不读出文件的情况下进行接线.
技能
6个工作流程游戏本作为下限字符串:
| 技能 | 工作流程 |
|---|---|
manage-telegram-conversations | 读取上下文、 回复、 指针、 音轨线程和相册 |
moderate-chat-effectively | 发现违规情况、警告、限制和有审计线索的禁令 |
handle-group-administration | 推广、降级、迁移、配置权限 |
broadcast-to-audience | 编写、发送、处理错误、重试失败的聊天 |
search-and-retrieve-messages | 全文搜索、 回复链条、 编辑历史 |
stream-progressive-responses | 流出后溢出并恢复出错 |
该软件包具有零运行时间依赖性. 它使用节点 24 全局获取 Bot API 请求和一个内重同步 Markdown 解析器. 格莱美和标记 是用于兼容性测试的开发依赖性.
createBot 接受可选 api: { fetch, apiRoot } 插入的设置
获取执行或自定义的 Bot API 端点 。 默认终点是
https://api.telegram.org。 。 。 .
adaptBot 继续接受格莱美瓶子 不上传的呼叫
api.raw; 文件上传使用内置客户端, 因此 grammy API 变压器是
不适用于上传。 它的可选第二个参数接受 { fetch, apiRoot }。 。 。 .
远程媒体 URL
媒体发送接受 { url: 'https://example.com/image.jpg' }。下载使用
节点 HTTP/ HTTPS 直接, 独立于 Bot API fetch 选项。 仅
支持HTTP和HTTPS. 检查每个DNS结果和重定向目标;
私人、地方、链接-地方、多播和保留的目标被封锁。 连接
使用经过验证的地址防止 DNS 重新绑定.
下载默认为 50 MiB, 整个超时30秒(包括 DNS 和
最多5个方向。 体型过大,非-2xx 最终
回复失败 TELEGRAM_FILE 错误.
设定 api: { allowPrivateMediaUrls: true } 内 createBot,或设置
GHOSTPAW_TELEGRAM_ALLOW_PRIVATE_URLS=1,允许私人目标。 无论是
允许选择使用本地服务和元数据端点;仅使用
包含可信任的媒体 URL。 客户选项 mediaMaxBytes 财务报告和审定财务报表 mediaTimeoutMs
超过大小和超时限制,例如:
const bot = createBot({ token, db, api: { mediaMaxBytes: 10 * 1024 * 1024, mediaTimeoutMs: 15_000 } });
发展
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
重罚被锁定 节点 24.14.0 通过沃尔塔。 使用您喜欢的版本管理器 .
支助
如果这个软件包有助于您的项目,请考虑赞助其维护:
