# @ghostpaw/telegram 中文文档

规范地址：https://npmcn.com/package/%40ghostpaw/telegram/

版本：0\.7\.9
npm 元数据更新时间：2026-11-10T11:48:20.450Z
中文译文更新时间：2026-11-16T08:03:08.323Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ghostpaw/telegram
原文对照：https://npmcn.com/package/%40ghostpaw/telegram/?lang=original
项目主页：https://telegram.ghostpaw.dev/
源码仓库：https://github.com/GhostPawJS/telegram

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：907 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-03-28T20:22:20.611Z
- 最新版本发布：2026-11-10T11:48:19.721Z
- 近 30 天下载量：4045（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Telegram bot 通道引擎——零运行时间依赖,Telegram运输,SQLite消息镜像,FTS5全文搜索,markdown渲染,以及结构化的LLM工具外观. 节点24+,内置节点:sqlite.

## 安装

```sh
npm install @ghostpaw/telegram
```

也可以使用：`pnpm add @ghostpaw/telegram`、`yarn add @ghostpaw/telegram`、`bun add @ghostpaw/telegram`

## README

[![GhostPaw telegram: Your bot remembers the chat, including what was edited.](https://raw.githubusercontent.com/GhostPawJS/telegram/main/.github/social-preview.png)](https://telegram.ghostpaw.dev/)

# @ghostpaw/ 电报

[![npm](https://img.shields.io/npm/v/@ghostpaw/telegram?style=flat-square&labelColor=0a1119&color=62e6f2&label=npm)](https://www.npmjs.com/package/@ghostpaw/telegram) [![CI](https://img.shields.io/github/actions/workflow/status/GhostPawJS/telegram/ci.yml?branch=main&style=flat-square&labelColor=0a1119&label=CI)](https://github.com/GhostPawJS/telegram/actions/workflows/ci.yml) [![site](https://img.shields.io/badge/site-telegram.ghostpaw.dev-62e6f2?style=flat-square&labelColor=0a1119)](https://telegram.ghostpaw.dev/) [![runtime deps](https://img.shields.io/badge/runtime_deps-0-7af0b4?style=flat-square&labelColor=0a1119)](https://npmcn.com/package/%40ghostpaw/telegram/package.json) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Ftelegram-b39dff?style=flat-square&labelColor=0a1119)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Ftelegram/versions/latest) [![node](https://img.shields.io/badge/node-%E2%89%A524-93a5b9?style=flat-square&labelColor=0a1119)](https://nodejs.org/) [![license](https://img.shields.io/npm/l/@ghostpaw/telegram?style=flat-square&labelColor=0a1119&color=93a5b9)](https://npmcn.com/package/%40ghostpaw/telegram/LICENSE)

**代理Telegram bots:在操作器运行前,每个更新镜都映入了SQLite.**

```bash
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>` 说不然.

**克劳德代码**

```bash
claude mcp add ghostpaw-telegram -- ghostpaw-telegram mcp
```

或作为插件,同时安装该技能:

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

**代码 CLI** (单位:千美元)`~/.telegram/config.toml`(中文(简体) )

```toml
[mcp_servers.ghostpaw-telegram]
command = "ghostpaw-telegram"
args = ["mcp"]
```

**光标** (单位:千美元)`.cursor/mcp.json`, (中文(简体) ), **克劳德桌面** (单位:千美元)`claude_desktop_config.json`(中文(简体) ) 或项目 `.mcp.json`数字 :

```json
{
  "mcpServers": {
    "ghostpaw-telegram": {
      "command": "ghostpaw-telegram",
      "args": ["mcp"]
    }
  }
}
```

Claude 桌面用户也可以安装 `server.mcpb` 从 [最新 GitHub 发布](https://github.com/GhostPawJS/telegram/releases/latest)。 。 。 . 容器主机包含一个 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>` 其绝对路径:

```sh
codex exec --sandbox workspace-write --add-dir <dir-with-db> "Run the GhostPaw CLI"
```

或者设置 `sandbox_workspace_write.writable_roots` 内 `~/.codex/config.toml` 在会议开始前:

```toml
[sandbox_workspace_write]
writable_roots = ["/absolute/dir-with-db"]
```

## 名词 CLI

27个指令路径来自4个工具策略:

```text
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` 二者皆能超越.

离线示例 :

```sh
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消息的描述符.

## 国 际

```bash
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: (英语)

```sh
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) (英语)

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"
```

达文 -阿尔马64:

```sh
curl -fsSL https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"
```

达文-x64:

```sh
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 中):

```powershell
irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex
```

跳过持久用户 PATH 编辑 :

```powershell
$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/telegram/main/install.ps1 | iex
```

绑入发布会 :

```sh
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, 所以使用该文件名 :

```sh
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"
```

```text
$ ghostpaw-telegram --version
telegram 0.7.8 (binary, linux-x64)
```

用于比较版本的脚本 `--version --short` 或者说 `--version --json`。 。 。 .

与 0. 7.1 linux- x64 二进制对接新数据库的会话, 没有设置符号, 因此出局命令只返回计划中的动作, 没有发送任何消息( 输出管道通过) `jq` 保持简短:

![ghostpaw-telegram 0.7.1 without a token: version, mirror chats, planned message send, typing and forward, account stats, account state and the tool list](https://raw.githubusercontent.com/GhostPawJS/telegram/main/docs/assets/cli.png)

同一届会议 [动画 GIF](https://raw.githubusercontent.com/GhostPawJS/telegram/main/docs/assets/cli.gif)。 。 。 .

其他放行安装器 :

```sh
mise use -g github:GhostPawJS/telegram
ubi --project GhostPawJS/telegram --exe ghostpaw-telegram --in ~/.local/bin
eget GhostPawJS/telegram
```

对于 [水量计](https://aquaproj.github.io/docs/reference/registry-config/),定义 a `github_release` 软件包在 `aqua.yaml`数字 :

```yaml
registries:
  - name: telegram
    type: local
    path: telegram-registry.yaml
packages:
  - name: GhostPawJS/telegram@v<VERSION>
    registry: telegram
```

`telegram-registry.yaml`数字 :

```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. 校验已下载的归档 [构建证明](https://cli.github.com/manual/gh_attestation_verify)数字 :

```sh
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. 见 [二进制构建工作流程](https://npmcn.com/package/%40ghostpaw/telegram/.github/workflows/release-binaries.yml)。 。 。 .

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 的环境)

```sh
npx @ghostpaw/telegram --help
npm install -g @ghostpaw/telegram
```

要求数 **节点24+** 用于内置 `node:sqlite` 模块。 npm包被取出816个KB.

### 库(用于将它嵌入代码)

```sh
npm install @ghostpaw/telegram
```

```ts
import { tools } from '@ghostpaw/telegram';
```

见 [图书馆使用量](https://npmcn.com/package/%40ghostpaw/telegram/#readme-quick-start)。 。 。 .

## 快速启动

```ts
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` 相反的配置 :

```ts
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
```

## 文档

阅读使用指南、食谱、结构和实体参考手册.

-   [概览](https://telegram.ghostpaw.dev/docs/): 手册涵盖的内容和起点
-   [人类使用](https://telegram.ghostpaw.dev/docs/human/): 在代码中直接使用库
-   [LLM 使用情况](https://telegram.ghostpaw.dev/docs/llm/): 工具、技能和激励代理人的灵魂
-   [食谱](https://telegram.ghostpaw.dev/docs/recipes/): 菜单、键盘和答复的图案
-   [建筑](https://telegram.ghostpaw.dev/docs/architecture/):如何制定守则
-   [聊天](https://telegram.ghostpaw.dev/docs/entities/chats/): 机器人看到的每一次谈话
-   [信件](https://telegram.ghostpaw.dev/docs/entities/messages/): 进出消息
-   [用户](https://telegram.ghostpaw.dev/docs/entities/users/): 机器人和人类账户
-   [成员](https://telegram.ghostpaw.dev/docs/entities/members/): 谁在哪个聊天, 具有地位
-   [回电](https://telegram.ghostpaw.dev/docs/entities/callbacks/): 内置键盘按钮
-   [文件](https://telegram.ghostpaw.dev/docs/entities/files/):相片、文件和语音注释
-   [反应](https://telegram.ghostpaw.dev/docs/entities/reactions/):emoji反应及其计数

## 存储什么

每次更新都会在操作器运行前被镜像到 SQLite 中 :

-   **信件** ——文本,媒体,编辑,回复边缘,相册,线程(FTS5全文索引有Unicodediacritic折叠)
-   **用户** ——取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名取名
-   **聊天** ——标题,类型,成员计数,论坛旗
-   **成员** – 状态,权限,每个聊天的管理员标题
-   **反应** ——每个用户每个消息的emoji,每个emoji计数和事件日志
-   **文件** ——元数据+原字节被存储为BLOB,SHA-256被去除;每个入库文件在背景中下载(`DEFAULTS.autoDownload` 已贬值和未使用;它不会改变这种行为)
-   **回电** — 内置按钮按下数据并回答状态
-   **Bot 状态** 任意的钥匙/价值储存和运行中的统计数据

所有8个表格都是在一个呼叫中创建的: `initTelegramTables(db)`。 。 。 .

## 两个观众

### 人类开发者

使用 `read`, (中文(简体) ), `write`,以及 `network` 每个域操作的直接代码访问的命名空间 :

```ts
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.');
```

见 [文件/人文资料](https://npmcn.com/package/%40ghostpaw/telegram/docs/HUMAN.md) 给全人类的指南 并有工作的例子.

### LLM 剂

使用 `tools`, (中文(简体) ), `skills`,以及 `soul` 结构化运行时表面的命名空间 :

```ts
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](https://npmcn.com/package/%40ghostpaw/telegram/docs/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` | 运行时间常数 |

## 工具

工具默认返回计划; 现有的同步处理器不执行输出动作 . 为了执行发送和节制行动,明确创建星相:

```ts
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` 超过大小和超时限制,例如:

```ts
const bot = createBot({ token, db, api: { mediaMaxBytes: 10 * 1024 * 1024, mediaTimeoutMs: 15_000 } });
```

## 发展

```bash
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** 通过沃尔塔。 使用您喜欢的版本管理器 .

### 支助

如果这个软件包有助于您的项目,请考虑赞助其维护:

[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-EA4AAA?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/Anonyfox)

* * *

**[无名狐狸](https://anonyfox.com/) 二. 支助 [MIT 许可证](https://npmcn.com/package/%40ghostpaw/telegram/LICENSE)**

## 常见问题

### @ghostpaw/telegram 是什么？

Telegram bot 通道引擎——零运行时间依赖,Telegram运输,SQLite消息镜像,FTS5全文搜索,markdown渲染,以及结构化的LLM工具外观\. 节点24\+,内置节点:sqlite\.

### 如何安装 @ghostpaw/telegram？

在项目目录运行 npm install @ghostpaw/telegram，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ghostpaw-telegram，可以用 npx ghostpaw-telegram 直接运行。

### @ghostpaw/telegram 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ghostpaw/telegram 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ghostpaw/telegram 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ghostpaw/telegram 可以商用吗？

@ghostpaw/telegram 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ghostpaw/telegram 的下载量有多少？

根据 npm 官方下载统计，@ghostpaw/telegram 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,045 次，日均约 135 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ghostpaw/telegram 还在维护吗？

最新版本 0\.7\.9 发布于 2026/11/10（5 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 20 个；首次发布于 2026/03/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

