tg

核心用法

该 Skill 是 Telegram CLI 工具 @cyberdrk/tg 的使用说明文档，为 AI Agent 提供与 Telegram 交互的标准化指令集。用户需先通过 npm 全局安装 CLI 工具并完成 Telegram API 认证，即可通过命令行实现：消息收发（tg send、、tg read）、收件箱管理（tg inbox）、聊天记录搜索（tg search）、联系人及群组信息查询（tg contact、、tg members、、tg admins）等操作。所有命令均支持 --json` 输出格式，便于程序化处理。

显著优点

1. 纯文档零风险：Skill 本身不含任何可执行代码，仅为 Markdown 使用指南，安全透明可审计
2. 功能覆盖全面：涵盖消息读写、搜索、联系人管理、群组权限查询等核心 Telegram 操作
3. 结构化输出友好：内置 JSON 输出支持，方便 AI Agent 解析和后续自动化处理
4. 参数设计灵活：支持时间范围过滤（--since）、消息数量限制（-n）、模糊匹配聊天名称等实用特性
5. 轻量无依赖：Skill 不捆绑任何运行时，CLI 工具由用户按需自主安装

潜在缺点与局限性

1. 来源可信度有限：底层 CLI 工具来自个人开发者账号（T3 来源），非 Telegram 官方出品，长期维护存在不确定性
2. 功能边界受限：不支持媒体文件上传下载、语音通话、复杂群组管理等高级功能
3. 认证门槛较高：首次使用需手动从 my.telegram.org 申请 API ID 和 Hash，对普通用户不够友好
4. 无图形界面：纯命令行交互，不适合需要可视化操作的场景
5. 依赖外部工具：Skill 仅为文档，实际功能完全依赖用户自行安装的第三方 npm 包，版本兼容性需自行保障

适合的目标群体

• 开发者及技术型用户，需要通过脚本自动化 Telegram 消息处理
• AI Agent 构建者，希望为 Agent 赋予 Telegram 读写能力
• 需要批量查询聊天记录、监控群组动态的运营人员
• 偏好命令行效率、追求工作流集成的极客用户

使用风险

1. API 凭证泄露风险：Telegram API ID 和 Hash 具有长期有效性，若保管不当可能导致账号被盗用
2. 会话数据本地存储：CLI 工具将加密会话保存在 ~/.config/tg/，多用户环境需注意目录权限隔离
3. 第三方工具信任问题：@cyberdrk/tg 非官方工具，其代码安全性、隐私政策需用户自行评估
4. 误操作风险：命令行发送消息无二次确认，批量操作可能导致消息误发
5. Rate Limit 限制：高频调用 Telegram API 可能触发平台限流，影响正常使用

核心用法

tg Skill 是一个面向 Claude Code 的 Telegram CLI 工具集成文档，提供完整的命令参考。核心功能分为四大模块：

消息读取：tg inbox 查看未读摘要，tg read "ChatName" -n 50 读取最近消息，tg search "query" --all 全局搜索，支持 --since 时间筛选和 --json 结构化输出。

消息发送：tg send @username "message" 发送私信，tg send "GroupName" "message" 群发消息，tg reply "ChatName" 12345 "response" 指定消息 ID 回复。

联系人与群组管理：tg contact @username 查询信息，tg members/admins "GroupName" 列出成员/管理员，tg groups --admin 筛选管理群组。

会话状态：tg auth 初始化认证（需 my.telegram.org 获取 API 凭证），tg whoami/check 验证登录状态。

显著优点

• 纯文档零风险：无可执行代码，仅 Markdown 指令参考，通过 S 级安全认证
• 命令覆盖全面：涵盖读、写、搜索、管理、认证完整 CLI 工作流
• 输出灵活：原生支持 --json 结构化数据，便于自动化处理
• 智能匹配：聊天名称支持部分匹配，降低精确输入负担
• 时效筛选：内置 --since 语法（1h/30m/7d），快速定位近期消息

局限性与风险

• 外部依赖风险：Skill 本身安全，但实际运行依赖 npm 包 @cyberdrk/tg，该包由个人开发者维护（T3 来源），需用户自行审计
• 认证门槛：首次使用需手动申请 Telegram API ID/Hash，流程较繁琐
• 无实时同步：文档未提消息推送或 WebSocket 实时通知能力
• 平台局限：仅支持 Telegram，无多 IM 适配

适合人群

Telegram 重度用户、社群管理员、需批量消息处理或自动化工作流的开发者，以及偏好 CLI 操作的技术用户。不适合无 Telegram 账号或对第三方 npm 包安全敏感的用户。

常规风险

• npm 供应链攻击风险（建议安装前验证包哈希）
• API 凭证本地存储安全（tg auth 生成的会话文件权限）
• 消息误发风险（群聊名称匹配模糊可能导致发送到错误群组）