SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场telegram

telegram

办公与效率

查看项目

更新于 10-16 08:22

技能介绍

Telegram 技能是 Claudicle 框架中面向 Claude 的轻量层，封装了位于 ~/.claudicle/adapters/telegram/ 的 python-telegram-bot v22 轮询适配器，用于通过 @claudicle_bot 机器人发送、读取和响应 Telegram 消息。发送脚本直接使用 REST（requests）而非 asyncio，因此可在任意子进程或技能调用中可靠运行。

【用途】 该技能用于在 Claude Code 会话中操作 Telegram：发送消息、构建带内联键盘按钮的审批门控、检查共享收件箱中的未处理消息、读取并应答按钮回调、检查机器人与监听器健康状态、加载记忆上下文，以及通过 /telegram-respond 运行完整认知流水线。

【主要能力】

  • telegram_send.py：基于 REST 的发送器，支持 parse_mode、回复线程、stdin、静默模式和内联键盘。长消息按换行自动拆分，键盘附加到最后一段。按钮格式为行列表，每行是 "Label|callback_data" 字符串；使用 "Label|url:https://..." 可生成 URL 按钮。成功时每行输出一个 message_id。若 Telegram 拒绝格式，脚本会以纯文本重试一次并在 stderr 打印警告。
  • telegram_check.py：读取 ~/.claudicle/daemon/inbox.jsonl 中 telegram:* 频道的条目，支持 --all、--limit、--mark-read、--mark-all-read。
  • telegram_callback.py：读取 entry_type 为 telegram_callback 的条目，支持前缀过滤、标记已处理和应答回调以清除加载动画。Telegram 要求约 30 秒内调用 answerCallbackQuery，否则查询过期、加载动画卡住。
  • telegram_status.py：一次运行检查三项——通过 getMe 检查机器人可达性、监听器进程是否存活（PID 文件 + kill -0）、收件箱是否在写入。退出码 0 表示全部正常，1 表示机器人正常但监听器停止，2 表示机器人不可达。
  • telegram_memory.py：对 ~/.claudicle/adapters/shared/claudicle_memory.py 的薄封装，提供工作记忆、用户模型和灵魂状态访问。
  • /telegram-respond：通过 Claudicle 认知流水线处理未处理消息，包括内部独白、用户模型检查/更新、灵魂状态检查/更新、外部响应。

【使用方式】 前置条件：在 ~/.config/env/secrets.env 中设置 TELEGRAM_BOT_TOKEN；安装 requests（发送/状态/回调脚本）和 python-telegram-bot（仅监听器）；监听器需 Python 3.10+，macOS 上须使用 /opt/homebrew/bin/python3 而非 /usr/bin/python3（系统 3.9 存在 asyncio 事件循环 bug，会破坏 CallbackQueryHandler）。需通过 @BotFather 创建机器人，并获取自己的 Telegram 用户 ID 或群组/频道 chat ID。

快速开始示例： python3 ~/.claude/skills/telegram/scripts/telegram_send.py <CHAT_ID> "Hello from Claudicle!" python3 ~/.claude/skills/telegram/scripts/telegram_send.py <CHAT_ID> "bold italic" --parse-mode Markdown python3 ~/.claude/skills/telegram/scripts/telegram_send.py <CHAT_ID> "Approve dispatch?" --buttons '[["Approve|approve_day42","Reject|reject_day42"]]' python3 ~/.claude/skills/telegram/scripts/telegram_check.py python3 ~/.claude/skills/telegram/scripts/telegram_callback.py --prefix approve: python3 ~/.claude/skills/telegram/scripts/telegram_status.py /telegram-respond

监听器管理： python3 ~/.claudicle/adapters/telegram/telegram_listen.py --bg python3 ~/.claudicle/adapters/telegram/telegram_listen.py --status python3 ~/.claudicle/adapters/telegram/telegram_listen.py --stop

【适用场景】

  • 发送 Telegram 消息（文本、Markdown、HTML、回复线程）
  • 构建带内联键盘按钮的审批门控（点击批准/拒绝流程）
  • 检查共享收件箱中的未处理 Telegram 消息
  • 读取待处理的按钮回调查询
  • 应答回调查询（清除加载动画、显示提示）
  • 调试发送失败前检查机器人身份与监听器健康
  • 加载 Telegram 记忆上下文
  • 通过 /telegram-respond 对未处理消息启动完整认知流水线

【限制与注意事项】

  • 该技能与机器无关，仅依赖适配器目录、secrets.env 中的机器人令牌和 Python 版本；所有路径从 Path.home() 解析。
  • 监听器需 Python 3.10+；发送/状态/回调脚本可在 Python 3.9+ 运行。
  • 回调数据须保持在 64 字节以内（Telegram 硬限制）；消息上限 4096 字符。
  • 环境变量命名漂移：当前监听器读取 CLAUDICLE_TELEGRAM_ALLOWED_CHATS 进行访问控制，而非 CLAUDICLE_TELEGRAM_ALLOWED_USERS。
  • 安全：切勿将 TELEGRAM_BOT_TOKEN 提交到 git；用户提供的文本在进入认知流水线前会清理 XML 标签；回调数据是不可信输入，须先按预期命名空间验证再操作。
  • 常见问题：按钮不出现检查 --buttons JSON 解析及每个按钮恰好一个 | 分隔符；点击未落入 inbox.jsonl 检查监听器运行状态及 CallbackQueryHandler 注册；"Task attached to different loop" 错误说明监听器运行在 Python 3.9；"Query is too old" 说明应答超过约 30 秒。
  • 文档中提到的 Mazkir 集成与 launchd 部署仅为某位操作者的具体示例，描述一种模式而非要求，技能在没有这些的情况下完全可用。