agent-telegram-free

Agent Telegram LITE

Agent Telegram 通信规范免费版。定义 3 类基础 Agent 角色的账号映射与消息发送格式，Agent 向用户发送 Telegram 消息时遵循此规范.

输入规范

主要能力

• 3 类基础角色账号映射：为每个 Agent 分配独立的 accountId 与 emoji 标识
  • main（9527）→ default → 🤖 主控 Agent
  • backend（老崔）→ backend → 🔧 后端工程师
  • frontend（小白）→ frontend → 🎨 前端工程师
• 统一消息格式：所有消息通过 message 工具发送，必填字段 action: "send"、channel: "telegram"、accountId、target: "5440561025"、message
• 两类汇报时机：收到任务立即汇报、完成子任务汇报
• 基础消息模板：任务开始、任务完成两类模板

部署说明

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

不适用于：多角色协作、问题上报决策、架构师/产品/内容/爬虫/QA 角色通信等高级场景.

消息格式规范

标准发送格式

message({
  action: "send",
  channel: "telegram",
  accountId: "<你的accountId>",
  target: "5440561025",
  message: "<你的emoji> <内容>"
})

消息模板

任务开始模板：

 收到任务：<任务名>
📝 开始执行...

任务完成模板：

 <任务名> 完成
✅ 已完成: <子任务>
📁 输出: <文件路径>

账号映射表

用户 Telegram ID：5440561025（固定值）

案例展示

案例 1：后端工程师汇报 API 开发完成

触发：backend 完成 API 接口开发

发送内容：

message({
  action: "send",
  channel: "telegram",
  accountId: "backend",
  target: "5440561025",
  message: "🔧 API 接口开发完成，接口文档：~/Desktop/project/docs/backend/api.md"
})

用户收到：Telegram 收到 🔧 API 接口开发完成，接口文档：~/Desktop/project/docs/backend/api.md

案例 2：前端工程师汇报页面开发完成

触发：frontend 完成登录页面开发

发送内容：

message({
  action: "send",
  channel: "telegram",
  accountId: "frontend",
  target: "5440561025",
  message: "🎨 登录页面开发完成\n✅ 已完成: 登录表单与校验逻辑\n📁 输出: ~/Desktop/project/src/pages/login.vue"
})

用户收到：Telegram 收到带子任务与输出文件路径的完成消息

异常恢复方案

常见疑问

Q1：可以用 sessions_send 工具发 Telegram 消息吗？

A：不可以。sessions_send 是 Agent 会话内部通信工具，不会将消息路由到 Telegram。必须使用 message 工具并指定 channel: "telegram".

Q2：target 字段可以改成其他用户 ID 吗？

A：不可以。本规范约定所有 Agent 消息统一发送给用户 5440561025.

Q3：免费版支持哪些角色？

A：免费版仅支持 main、backend、frontend 三类基础角色。如需 architect、product、content、crawler、qa 等角色，请升级付费版.

Q4：如何配置 Telegram Bot？

A：在 ~/.json 的 channels.telegram.accounts 节点下配置 Bot Token。Bot Token 通过 @BotFather 创建获取.

限制条件

• 仅支持 main、backend、frontend 三类角色，不支持 architect/product/content/crawler/qa
• target 固定为 5440561025，不支持向其他用户发送消息
• 消息内容上限 4096 字符，超长需拆分多条
• 不支持"遇到问题"模板与问题上报决策流程
• 不支持多角色协作与 main 汇总流程
• 依赖 Agent 平台已配置 message 工具与 Telegram Bot Token

运行环境

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 网络：需可访问 Telegram Bot API（https://api.telegram.org）

依赖项

API Key 配置

• Telegram Bot Token 配置在 ~/.json 的 channels.telegram.accounts..token 字段

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，消息发送需要 exec 调用 message 工具）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务

---

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

升级提示

当前为免费版，仅支持 3 类基础角色与两类汇报时机。如需以下完整功能，请升级付费版：

• 8 类角色账号映射：新增 architect（🏗️）、product（🟡）、content（✍️）、crawler（🕷️）、qa（🧪）角色
• 四类汇报时机：新增"遇到问题"汇报时机与问题上报决策流程
• "遇到问题"消息模板：含问题描述与建议方案的标准化模板
• 多角色协作流程：main 分发任务 → 各角色执行并汇报 → main 汇总结果
• product 角色 sproduct 约定：避免 JavaScript 保留字冲突的特殊 accountId 处理
• 文件附件发送：支持通过 attachment 字段直接发送文件
• 多 Bot 独立路由：每个角色使用独立 Bot Token，消息互不干扰

升级至付费版：https://SkillHub.ai/skill/agent-telegram

响应格式

{
  "success": true,
  "data": {
    "result": "Agent TG LITE处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "agent-telegram"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

创新特色

效率提升量化分析

差异化对比

核心痛点解决

安全规范

1. [与「智能体Telegram免费版」相关的安全注意事项]
   1. 确保所有通信数据通过安全的通道传输，避免数据泄露。
   2. 定期更新账号密码，防止密码被破解。
   3. 对外发送的消息内容应进行审查，避免包含敏感信息。
   4. 确保技能使用的环境安全，避免遭受恶意攻击。
   5. 定期备份重要数据，防止数据丢失。

安全风险防范

核心属性

• 自动化执行: Agent Teleg
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

异常处理指南

针对智能体Telegram免费版使用中可能遇到的常见问题,提供以下排查方案:

智能体Telegram免费版通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

指南中心

问题解答汇总

核心功能特性

• 自动化执行: Agent Teleg
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果