--- hash: 914e96dcdb181c08 url: "https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk/index.html" final_url: "https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk/index.html" family: own title: "heteronimos-semi-asistidos-sdk" method: direct fetched_at: "2026-09-18T08:44:07Z" sha256_md: 8763de8c1e53b0d1639457d7d06af39dc808409ae0112b80e306b325ab86355c cited_by: - "2040039649607852520" --- 0.0.0Version 165Tests 14Suites 0Failures ⚠Pre-kick-off ★ 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 # install Bun first if needed → bun.sh 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. Dos arquetipos: **headless** (examples/console-app/) e **interactive** (examples/dashboard/ — [TUI admin panel](https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk/dashboard-guide.html)). Detalles completos en la [guía de Quick Start](https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk/quick-start.html). 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. # BotPlugin interface { name: string; pluginCode: string; # prefix for all commands commands(): CommandDefinition[]; menus?(): MenuDefinition[]; # optional inline keyboards onMessage?(ctx): string; # optional fallback handler } 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}!`, }]; } } # examples/console-app/main.ts import { registerPlugins } from "heteronimos-semi-asistidos-sdk"; const plugins = [new MyBot()]; registerPlugins(bot, plugins, tracker); ### Core Modules command-handler CommandDefinition · handleCommand() generic sequence · registerCommands() · toBotFatherFormat() · syncCommandsWithTelegram() with diff (+/~/-) menu-handler MenuDefinition · NavButton / UrlButton · registerMenu() auto-wires /command + callback queries · inline keyboard pages chat-tracker Persists chat IDs to .chats.json · middleware auto-tracking · broadcast(bot, msg) to all known chats logger LOG_LEVEL env (debug|info|warn|error) · scoped [timestamp] [LEVEL] [scope] · child() sub-loggers · colored output ### Quick Reference | Script | What | | --- | --- | | bun run dev | watch mode | | bun run dev:verbose | + LOG_LEVEL=debug | | bun run start | single run | | bun run build | bundle → dist/ | | bun run lint | tsc --noEmit | | bun run bot-father-settings | generate docs | | bun run test | 165 tests across 14 suites | | bun run test:report | JUnit XML | | bun run test:coverage | coverage report | | bun run release | version tag | Sin .env la app arranca en modo mock — ver [Quick Start](https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk/quick-start.html). ### Stack Bun TypeScript grammY Telegram Bot API **License:** AIPL — Animus Iocandi Public License **Org:** [Escrivivir.co](https://escrivivir.co) --- 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. ### Contributing **1.** Check [BACKLOG.md](https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk/blob/main/BACKLOG.md) for open tasks (🗒) **2.** Fork → branch from main → `feat/` `fix/` `docs/` **3.** Implement → `bun run lint` → `bun run test` **4.** Update docs + backlog when a contributor-facing phase closes **5.** Open a PR against main — reference the backlog item # **Session handoff:** finish with `bun run lint` and `bun run test`, update `BACKLOG.md` if a phase is done, and keep GH Pages aligned with `README.md` and related specs/docs. | Resource | Link | | --- | --- | | Source | [github.com/escrivivir-co/heteronimos-semi-asistidos-sdk](https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk) | | Docs | [escrivivir-co.github.io/heteronimos-semi-asistidos-sdk](https://escrivivir-co.github.io/heteronimos-semi-asistidos-sdk) | | Backlog | [BACKLOG.md](https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk/blob/main/BACKLOG.md) | | Guide | [CONTRIBUTING.md](https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk/blob/main/CONTRIBUTING.md) | | Specs | [specs/](https://github.com/escrivivir-co/heteronimos-semi-asistidos-sdk/tree/main/specs) | | License | AIPL — Animus Iocandi Public License | heteronimos-semi-asistidos-sdk · v0.0.0 · 165 tests passing · Escrivivir.co · AIPL