Skip to content

developer-guide.md

Latest commit

 

History

History
117 lines (96 loc) · 4.83 KB

developer-guide.md

File metadata and controls

117 lines (96 loc) · 4.83 KB

Web2Comic Bot Developer Guide

Cross references:

Scope note:

  • Developer docs describe architecture, prompts, storage, and testing.
  • Admin-only bot commands are intentionally excluded from published command references.

Public Command Catalog (Implementation Scope)

  • Onboarding/info: /start, /welcome, /help, /about, /version, /user, /config, /explain, /debug
  • Generation inputs: text, web link, PDF, image, or voice/audio, /invent <story>, /random
  • Replay: /peek, /peek <n>, /peek<n>
  • Providers/models: /vendors, /vendor <role> <name>, /vendor <name>, /models [role] [model], /test
  • Output controls: /panels, /objective, /objectives, objective shortcuts, /style, style shortcuts, /new_style, /language, /mode, /consistency, /detail, /crazyness, /concurrency, /retries
  • Prompt/options: /prompts, /set_prompt, /list_options, /options
  • Credentials/state: /keys, /setkey, /unsetkey, /reset_config, /restart

Architecture

  • Entry point: telegram/src/webhook-bot.js
  • Generator bridge: telegram/src/generate.js
  • Shared engine: engine/src/*
  • Bot data modules: telegram/src/data/* (messages, providers, styles/objectives, options, thresholds)
  • Engine prompt templates: engine/src/data/prompt-templates.js
  • Runtime state/config: telegram/src/config-store.js
  • Persistence adapters: telegram/src/persistence.js + request/crash log stores

Processing model:

  • Webhook handler ACKs immediately
  • Update is enqueued per chat id
  • One active job per chat queue preserves per-user order

Input Classification

Input from message.text, media attachments, or message.caption is classified as:

  • command
  • url
  • pdf
  • image
  • voice
  • text
  • empty/unsupported

Source-specific flows extract structured text before generation:

  • URL flow snapshots rendered page HTML before generation
  • PDF flow extracts document text from a link or uploaded file
  • Image flow extracts scene/story context from a link or uploaded file
  • Voice/audio flow transcribes the clip before story generation

Generation Pipeline

  1. Resolve effective per-user config
  2. Apply secrets (runtime/shared/env)
  3. Build storyboard with text provider
  4. Optional consistency flow (if enabled and supported): generate one summary reference image
  5. Generate panel images (each prompt includes Background + Image description; Story title line removed; references summary style when available)
  6. Stream panel sends to Telegram as each panel becomes ready
  7. Send final completion summary

Important behavior:

  • Panel captions in chat use X(Y) prefix
  • Image prompt explicitly forbids rendering text inside artwork (rule repeated in English/Hebrew/Russian)
  • Watermark is configurable (generation.panel_watermark, default true)
  • Consistency mode is configurable (generation.consistency, default true)
  • Telegram sends use protect_content=false to keep forwarding enabled

Command System

Primary command handling is in handleCommand.

Notable UX behavior:

  • /objective without args lists all objectives
  • /crazyness <0..2> controls story invention temperature
  • /options without args explains valid paths/options; apply via dedicated commands (/objective, /panels, /mode, /vendor, /models, etc.)
  • /keys shows runtime key status
  • /vendors [role] prints available provider roles and options
  • URL flow sends Detected link, parsing page: <url> with the exact parsed URL

Blacklist Model

Blacklist is persistent in config state:

  • ids list
  • usernames list (normalized)

Ban checks run before allowlist checks during message processing.

Security

  • Secrets are redacted from user-visible output
  • BOT_SECRETS_ENV_ONLY=true disables YAML fallback for deployment/CI
  • Provider switching checks required keys and blocks missing-key changes

Storage

  • R2 state object: user runtime config/secrets/profile + history
  • R2: env-scoped images, request logs, crash logs, runtime logs, and status markers
  • Capacity/retention cleanup is enforced by runtime/storage managers

Testing

Primary suites:

  • npm run test:telegram:local
  • npm run test:telegram
  • npm run test:telegram:r2-real
  • npm run test:telegram:full-stack
  • npx vitest run -c telegram/vitest.config.js telegram/tests/webhook-url-real.e2e.test.js (opt-in with RUN_WEBHOOK_URL_REAL=true)

Secret checks before deploy/tests:

  • npm run secrets:validate:deploy:ci
  • npm run secrets:validate:tests:ci

Deployment

Use:

npm run bot:deploy:auto -- --target render --env staging --branch stage1 --env-only

See:

  • telegram/docs/deployment-runbook.md
  • telegram/docs/testing.md