★ START HERE
Quick Start
Clone → install → run · si falta .env la app te guía (mock o Telegram)
☞ GUÍA COMPLETA
☞ GITHUB REPO
☞ TUI DASHBOARD GUIDE
☞ PROMPTS & AGENTES
git clone https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk.git
cd heteronimos-semi-asistidos-sdk && bun install
bun run lint && bun run test
bun run dev
No necesitas configurar .env antes de arrancar: la consola te pregunta si quieres crearlo y te ofrece modo mock; el dashboard entra en mock automáticamente y te deja configurar desde el Config Panel.
En modo mock, el panel [5] Commands permite ejecutar comandos directamente desde la UI y ver las respuestas del bot en tiempo real.
CORE
Architecture — Bot-of-Bots
Each bot is a BotPlugin. The public entrypoint is src/index.ts; the core wires, prefixes, syncs, and broadcasts.
┌──────────────────────────────────────────────┐
│ main.ts │
│ │
│ plugins[] ──→ registerPlugins(bot, plugins) │
│ │ │
│ ┌──────────┼──────────┐ │
│ ▼ ▼ ▼ │
│ commands menus onMessage │
│ (prefixed) (inline) (fallback) │
│ │ │ │ │
│ └──────────┼──────────┘ │
│ ▼ │
│ syncCommands() │
│ ┌─ diff local vs Telegram │
│ ├─ prompt on changes │
│ └─ broadcast update │
└──────────────────────────────────────────────┘
bot-handler
command-handler
menu-handler
chat-tracker
logger
INTERFACE
BotPlugin — Create Your Own Bot
Implement BotPlugin, register in main.ts, done.
{
name: string;
pluginCode: string;
commands(): CommandDefinition[];
menus?(): MenuDefinition[];
onMessage?(ctx): string;
}
Commands are auto-prefixed: pluginCode_command
e.g. pluginCode "rb" → /rb_aleph, /rb_menu, /rb_join
Example — minimal plugin
import type { BotPlugin } from "heteronimos-semi-asistidos-sdk";
export class MyBot implements BotPlugin {
name = "my-bot";
pluginCode = "mb";
commands() {
return [{
command: "hello",
description: "Say hello",
buildText: (ctx) =>
`Hello, ${ctx.from?.first_name}!`,
}];
}
}
import { registerPlugins } from "heteronimos-semi-asistidos-sdk";
const plugins = [new MyBot()];
registerPlugins(bot, plugins, tracker);
DEMO
RabbitBot — Example Plugin
pluginCode = "rb" · 4 commands · 1 menu (2 pages) · onMessage handler
☞ TRY THE BOT
/rb_aleph next Fibonacci-date event ·
/rb_join join link ·
/rb_quit quit ·
/rb_alephs all events ·
/rb_menu inline keyboard
Channel: A cyborg-driven chat room
GROUPS
Groups & Privacy Mode
Para que el bot reciba todos los mensajes en grupos, desactiva Privacy Mode en BotFather
Por defecto, Telegram bots tienen Privacy Mode activado — en grupos solo reciben:
- Mensajes que empiezan con
/ (comandos)
- Respuestas a mensajes del propio bot
- Mensajes que @mencionan al bot por su username
Si necesitas que el bot reciba todos los mensajes del grupo (para handlers onMessage):
@BotFather → /setprivacy → selecciona tu bot → Disable
Importante: Después de cambiar este ajuste, elimina y vuelve a añadir el bot a cada grupo para que el cambio surta efecto.
Menú / en grupos: El SDK registra los comandos con scopes default y all_group_chats automáticamente, para que el menú de comandos aparezca tanto en chats privados como en grupos y supergrupos.
Webhooks residuales: Al arrancar, el SDK verifica si hay un webhook activo y lo elimina automáticamente para garantizar que el long-polling funcione correctamente.
AI
Prompts & Agentes Expertos
Sesiones guiadas con IA · El agente se caracteriza según el lore que le proporcionas
☞ VER TODOS LOS PROMPTS
hacker-devops — Un hacker DevOps experimentado analiza la codebase en 5 fases: revisión inquisitiva → adaptación por rol → plan de ataque → offboarding → cierre. Invócalo con @workspace /hacker-devops y añade lore al final para especializar al agente.
Tip: los prompts viven en .github/prompts/ — puedes copiarlos y pegarlos en cualquier agente de IA, no solo Copilot.