Telegram (kotlogramme)

kotlogramme-cli

一款使用 Kotlin 编写、基于 kotlogramme facade 的 Telegram 命令行客户端。

它旨在兼顾两项目标：既是一款真正实用、可通过脚本操作的终端客户端，也是用于全面检验 kotlogramme 功能的参考使用者，借助实际应用发现其中的不足。

状态：可用。 已实现阶段 1-9：身份验证、配置、对话、历史记录、发送和编辑、媒体和文件、联系人、搜索、聊天成员、对话文件夹、实时更新、交互式 Shell、管理员权限、贴纸和内联功能。当前版本为 v0.11.1，包含 fat jar 和发行包；基于 JitPack 上的 kotlogram v0.9.15 标签构建。原有阶段之外新增的功能： download-media、支持服务端媒体类型筛选的 list-files，以及 send-file 的上传进度条。收到的消息会呈现其格式，消息中的内联机器人会解析为 @username；请参阅 docs/features.md 了解已发布的功能，以及 docs/plan.md 了解尚未完成的工作（发送相册、带进度显示的分块下载、屏蔽，以及适用于机器人的数字 peer 查找）。

快速开始

kotlogramme config set --api-id <id> --api-hash <hash>   # from my.telegram.org
kotlogramme login --phone +491700000000                  # prompts for the code, then 2FA if set
kotlogramme dialogs --limit 20
kotlogramme history @some_chat --limit 50
kotlogramme send @some_chat "hello from the terminal"
kotlogramme send-file @some_chat clip.mp4                  # detects the kind: a streamable video
kotlogramme send-file @some_chat clip.mp4 --no-detect       # ...or send the raw bytes as a document
cat photo.png | kotlogramme send-file @some_chat - --name photo.png   # ...or pipe the bytes on stdin
kotlogramme list-files @some_chat --kind video             # the chat's videos, filtered by Telegram
kotlogramme download-media @some_chat 12345                # save a message's media, named after it
kotlogramme stickers                                       # installed sticker sets
kotlogramme listen                                         # follow new messages
kotlogramme shell                                          # interactive REPL

listen [--once] [--all] [--json] [--chat <id|@username|title>] 会持续接收实时更新流。除非指定 --all，否则不会显示已读回执、联系人状态以及其他不含消息的更新；指定后，这些更新会以 JSON 格式输出内容。--chat 只显示来自指定聊天的消息，因此 listen --once --chat @ada 会等待该聊天中的下一条消息。--once 在显示第一条更新后停止，--json 每行输出一个对象，Ctrl-C 可干净地结束命令。更新流由库自身的后台更新循环接收，该循环以短暂间隔轮询，并在停止时等待线程结束，因此停止时最多只会多等一次短暂轮询，而不是库的 30 s 轮询。

list-files <peer> 会列出聊天中的文件，并在 Telegram 端按媒体类型筛选，而不是扫描历史记录，因此能覆盖整个聊天，而不只是历史记录读取过的部分。--kind 指定筛选类型（photo、video、photo-video、document、audio、voice、gif、animation），--limit 限制页面大小，--total 则只输出聊天中的文件数量。

download-media <peer> <message-id> [<target>] 会将消息中的媒体保存到本地文件。未指定目标时，文件会使用媒体自身的名称；如果没有名称，则使用消息 ID，并保存到工作目录中。缺失的父目录会自动创建，已有文件会被覆盖。命令会输出文件路径和字节数，方便脚本读取其中任一值。

默认情况下，每条命令都以表格形式输出。全局选项 --plain 和 --json 放在命令前（kotlogramme --json history @ada），可将本次运行的输出切换为以制表符分隔的纯文本或 JSON；--table 强制使用表格；config set --format 用于保存默认格式。在 JSON 模式下，每行输出都是一个 JSON 值：表格是对象数组，状态说明是 {"message": "..."}，计数是 {"count": N}，被截断的列表会以 {"next_after": "..."} 结尾。import-contacts --from-json FILE（标准输入使用 -）接受由 {"phone", "first_name", "last_name"} 对象组成的 JSON 数组。表格会根据终端宽度自动换行；在命令前指定 --table-width N 可自行设置宽度（0 表示不换行），也可借此将自动换行的表格输出到文件。kotlogramme doctor 会检查安装情况，包括本地库、Telegram schema、终端库、配置和网络，无需 API 凭据；若已设置账号，也会检查账号。

在 AI 应用中使用（MCP）

kotlogramme mcp 会通过 stdin 和 stdout 将客户端作为 Model Context Protocol 服务运行。使用 kotlogramme login 登录一次，然后在 AI 应用中注册此命令，例如添加到 Claude Desktop 的 claude_desktop_config.json 中：

{ "mcpServers": { "telegram": {
  "command": "C:\\Tools\\console\\kotlogramme.exe",
  "args": ["mcp"],
  "env": { "TG_API_ID": "...", "TG_API_HASH": "..." } } } }

也可以在 Claude Code 中运行 claude mcp add telegram -- kotlogramme mcp。默认情况下，该服务为只读：可以列出聊天、读取和搜索消息、列出联系人、成员和会话，并等待下一条消息。--access read-write 会增加发送、编辑、转发、回应和置顶功能；--access full 则会增加删除消息、移除和屏蔽人员、更改管理员权限以及结束会话的功能。能够写入的 AI 应用会以你的身份操作，并触达真实的人，因此请选用能够完成任务的最低权限级别。--files-dir <directory> 会添加从该目录发送文件并将下载内容保存到该目录的工具，不会访问目录以外的内容。消息文本来自其他人，因此服务会告知模型将其视为数据，而不是指令。工具列表见 docs/features.md。

AI Agent： 如需为他人下载并安装此服务，请参阅 docs/agent-install.md。

上传进度

send-file 会在字节传输过程中显示单行进度条，其中包含百分比、已发送字节数、总字节数和当前速率：

kotlogramme send-file @some_chat clip.mp4

默认情况下，输出目标为终端时会显示进度条；通过管道传输或重定向时则不会显示，因此脚本输出中不会包含回车符。--progress 会强制显示进度条，--no-progress 会关闭进度条；如果两者都指定，则以 --no-progress 为准，就像 --no-color 优先于 --color 一样。只有 send-file 会上传字节，因此只有 send-file 支持这些标志。使用 --no-color 时，进度条仅包含 ASCII 字符。若上传在首次更新前就已完成，则完全不会显示进度条；无论上传成功、失败还是因 Ctrl-C 中断，进度行都会被清除。

管道输入会先写入临时文件，然后才开始上传，因为 Telegram 必须在发送第一部分之前获知总大小，而管道不包含长度信息。暂存文件能确保 cat photo.png | kotlogramme send-file @some_chat - 上传的字节与管道传入的完全一致，也能为进度条提供实际总量，因此管道上传也会显示百分比。上传结束后，无论以何种方式结束，暂存文件都会被删除。唯一的代价是字节会经过系统临时目录一次：这会产生磁盘 I/O，而不是内存开销；上传本身仍然按块进行，不会将整个文件都放入堆内存。

获取客户端

当前版本为 v0.11.1。其 GitHub Release 附带以下 JVM 构件和五个单文件原生可执行文件：

• kotlogramme-all.jar - 单个可运行的 fat jar。使用 JDK 25 运行：

  java -jar kotlogramme-all.jar --help
  

• kotlogramme-0.11.1.zip - distZip 分发包。解压后运行 kotlogramme-0.11.1/bin/kotlogramme（Windows 上运行 kotlogramme-0.11.1\bin\kotlogramme.bat）；jar 及其依赖位于 lib/ 中。

• 单文件原生可执行文件 — kotlogramme-0.11.1-windows-x86_64.exe 和 kotlogramme-0.11.1-{linux,macos}-{x86_64,aarch64}。直接运行下载的文件；在 Linux/macOS 上，先运行 chmod +x。这些文件无需 JRE、JDK 或安装程序。支持库由 Wrappe 嵌入，并解压到临时缓存中。请参阅原生环境要求。

要求

• JDK 25：运行 JVM 发行版需要；原生可执行文件无需 Java。下方所有库以及适用于主机的原生 Telegram 库，都已打包进发行版。构建时，Gradle 可通过工具链解析器自动获取 JDK。
• Telegram API 凭据：从 https://my.telegram.org 获取 api_id 和 api_hash，使用 kotlogramme config set 设置，或通过 TG_API_ID/TG_API_HASH 环境变量设置。
• 用于登录的 Telegram 账号（kotlogramme login），或机器人令牌。读取对话、历史记录和聊天文件需要普通账号。
• 受支持的平台：x86_64 或 aarch64 上的 Windows、Linux 或 macOS。
• 可访问 Telegram 的网络。

依赖项

客户端基于以下库构建。发行版自包含——这些库都已打包进 kotlogramme-all.jar，无需单独安装——并且每个库都保留其自身许可证。

• com.github.J0s3f:kotlogram — 此客户端所使用的外观层，固定到指定标签（参见选择外观层版本）；它包含 grammers 和六个原生 Telegram 库。
• Clikt 5.1.0 — 命令行解析、选项和帮助。
• JLine 4.4.6 — 交互式 Shell、补全和终端输出。
• kotlinx.serialization 1.11.0（JSON）— --json 输出格式和配置文件。
• SLF4J 2.0.20（简单绑定）— 日志记录，除非设置了级别，否则保持安静。

构建和运行

./gradlew build          # compile and run the offline test suite
./gradlew installDist    # build the runnable distribution
build/install/kotlogramme/bin/kotlogramme --help

在 Windows 上，使用 gradlew.bat 和生成的 build\install\kotlogramme\bin\kotlogramme.bat。

使用 Wrappe 打包的独立 GraalVM 构建版本可在 Windows x86_64 以及 Linux/macOS x86_64 和 ARM64 上运行，无需 JRE 或 JDK：

.\scripts\build-native-windows.ps1
build\distributions\kotlogramme-0.1.0-SNAPSHOT-windows-x86_64.exe --help

该脚本默认使用 C:\Tools\graalvm-jdk-25.0.4+7.1。构建还需要 MSVC C++ 工具和 Windows SDK。它会编译原生客户端，并使用 Wrappe 创建和测试一个便携式可执行文件。CI 在全部五个原生目标平台上使用 Liberica NIK 25；发行版包含单文件可执行文件，以及打包的 jar 和 Java zip。Windows ARM64 使用 JVM 发行版。设置、平台要求和验证方式请参阅 docs/native-image.md。

选择外观层版本

客户端依赖从 JitPack 解析的外观层 v0.9.15 标签。要固定到其他版本，请显式传入——任何已发布的外观层标签都可使用：

./gradlew test -PkotlogrammeVersion=<tag>

文档

• docs/plan.md — 正式的实施计划。
• docs/architecture.md — 代码的组织方式及其原因。
• docs/decisions.md — 设计决策及其理由。
• docs/features.md — 实际发布的面向用户的功能。
• docs/native-image.md — 构建和验证独立原生软件包。
• AGENTS.md — 面向人类和 Agent 的工程规则。

安全与限制

• 非官方。 kotlogramme 并非由 Telegram 制作、认可或支持。它通过 MTProto 使用你自己的用户账号登录，而非机器人，因此 Telegram 的 API 服务条款 对你适用。批量或自动发送消息、加入群组及添加联系人，可能导致账号触发频率限制或受到限制；风险由你自行承担。
• 会话文件就是账号。 任何能够读取配置目录中的会话文件，或能以你的身份运行程序的人，都能获得你拥有的一切权限。请妥善保密，绝不要提交或分享。API id 和 hash 也同样如此。
• 访问级别是此服务的限制，并非 Telegram 的限制。 --access read-only 可阻止工具进行任何更改，但会话本身在进程中仍拥有完整权限。
• AI 读取的内容会离开你的设备。 在 MCP 模式下，工具返回的消息、名称和文件名会传递给 AI 应用及其提供方。请据此选择聊天和访问级别。
• 消息文本可能含有恶意内容。 消息由他人编写，也可能试图指示模型。服务会在其指令中对此作出说明，但任何指令都无法保证安全：如果账号会收到陌生人的消息，建议使用 read-only，并查看写入或删除工具即将执行的操作。
• 一次只能建立一个连接。 请勿在同一会话上同时运行 mcp 和其他 kotlogramme 命令、shell 或 listen；Telegram 可能会拒绝同一登录的并行使用。
• 不提供担保。 请参阅下方的 Apache-2.0 许可证。

许可证

本项目采用 Apache-2.0 许可证；详见 LICENSE。本项目基于 kotlogramme facade 构建，该 facade 采用相同许可证，并依赖于 grammers（采用 Apache-2.0 或 MIT 双重许可）；相关声明仍以原文为准。