admin/claude-telegram-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add design spec, implementation plan, test plan; update gitignore

Browse Source
This commit is contained in:
neken
2026-04-10 17:55:43 +05:00
parent 8bccf6ce88
commit 6afb703a85
4 changed files with 1364 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2
View File
@@ -1,3 +1,5 @@
node_modules/ node_modules/
dist/ dist/
.env .env
.claude/
*.log
docs/superpowers/plans/2026-04-10-telegram-bot-plan.md
+1036
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/specs/2026-04-10-telegram-bot-design.md
+196
View File
@@ -0,0 +1,196 @@
# Telegram Bot для управления сессиями Claude Code
## Обзор
Персональный Telegram-бот для управления сессиями Claude Code, запущенными на локальном сервере. Позволяет создавать, останавливать, переключать сессии для разных проектов и вести полноценный диалог с Claude через Telegram.
## Решения
- **Подход:** Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) — программный контроль сессий из одного процесса
- **Пользователь:** один (персональный бот)
- **Взаимодействие:** полноценный чат — сообщения в Telegram отправляются как промпты в активную сессию
- **Управление проектами:** быстрый старт по пути + именованные закладки
- **Мультисессия:** одна активная сессия получает сообщения, переключение через `/switch` или inline-кнопки
- **Вывод:** только финальный результат (без стриминга промежуточных шагов)
## Архитектура
```
┌─────────────┐ Telegram Bot API ┌──────────────────────┐
│ Telegram │◄───────────────────────►│ Bot Server │
│ (владелец) │ │ (Bun + TypeScript) │
└─────────────┘ │ │
│ ┌────────────────┐ │
│ │ Session Manager │ │
│ │ - activeSession│ │
│ │ - sessions map │ │
│ │ - projects map │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Claude Agent SDK│ │
│ │ query({ │ │
│ │ prompt, │ │
│ │ cwd, │ │
│ │ resume, │ │
│ │ allowedTools │ │
│ │ }) │ │
│ └────────────────┘ │
└──────────────────────┘
│
┌──────────▼──────────┐
│ Файловая система │
│ сервера (проекты) │
└─────────────────────┘
```
**Три компонента:**
1. **Telegram Bot** (grammy) — принимает сообщения, отправляет ответы, inline-кнопки
2. **Session Manager** — CRUD сессий, переключение, закладки проектов, персистентность
3. **Claude Agent SDK** — выполнение запросов, управление session ID, resume
**Стек:** TypeScript, Bun, grammy, @anthropic-ai/claude-agent-sdk
## Команды бота
### Управление сессиями
| Команда | Описание |
|---------|----------|
| `/start <path или name>` | Создать новую сессию для проекта |
| `/stop` | Остановить текущую активную сессию |
| `/stop <name>` | Остановить конкретную сессию |
| `/stopall` | Остановить все сессии |
| `/switch <name>` | Переключиться на другую активную сессию |
| `/sessions` | Список активных сессий с inline-кнопками для переключения |
| `/status` | Статус текущей сессии (idle/busy, проект, cwd) |
### Управление проектами (закладки)
| Команда | Описание |
|---------|----------|
| `/save <name> <path>` | Сохранить закладку проекта |
| `/remove <name>` | Удалить закладку |
| `/projects` | Список закладок с inline-кнопками для запуска |
### Прочее
| Команда | Описание |
|---------|----------|
| `/help` | Справка по командам |
### Обычные сообщения
Текст без `/` отправляется как промпт в текущую активную сессию.
### Inline-кнопки
- `/sessions` — кнопки с именами сессий для быстрого переключения
- `/projects` — кнопки "Запустить <name>" для быстрого старта сессии
### Обработка ошибок
- Сообщение без активной сессии → "Нет активной сессии. Используй /start"
- Сообщение пока сессия busy → "Сессия занята, дождись ответа"
- `/start` с уже существующим именем → предложить `/switch`
## Модель данных
Состояние хранится в `~/.claude-telegram-bot/state.json`:
```typescript
interface AppState {
// Закладки проектов
projects: Record<string, string>; // name → absolute path
// Активные сессии
sessions: Record<string, { // name → session info
sessionId: string; // ID из Claude Agent SDK
cwd: string; // рабочая директория
status: "idle" | "busy";
}>;
// Какая сессия сейчас принимает сообщения
activeSession: string | null; // name из sessions
}
```
**Персистентность:**
- Записывается при каждом изменении
- При старте бота загружается из файла
- `sessions` при рестарте: sessionId сохраняются, при следующем сообщении пробуем resume — если не удаётся, сообщаем пользователю
- `projects` переживают перезапуск полностью
**Именование сессий:**
- `/start /d/my-project` → имя из последнего сегмента пути: `my-project`
- `/start mybot` (закладка) → имя = имя закладки
- Конфликт имён → суффикс: `my-project-2`
## Обработка сообщений
```
Telegram сообщение
│
├─ начинается с "/" → парсинг команды → выполнение
│
└─ обычный текст → отправка в активную сессию:
1. Проверить activeSession != null
2. Проверить session.status === "idle"
3. Поставить status = "busy"
4. Отправить typing индикатор
5. query({ prompt: text, resume: sessionId })
6. Собрать финальный ResultMessage
7. Отправить ответ (разбить на чанки если > 4096 символов)
8. Поставить status = "idle"
При ошибке → сообщение об ошибке, вернуть status = "idle"
```
**Разбивка длинных ответов:**
- Лимит Telegram — 4096 символов
- Разбиваем по границам `\n\n`, затем `\n`
- Markdown-форматирование в каждом чанке
## Безопасность
- **Allowlist по chat_id** — бот отвечает только владельцу (TELEGRAM_OWNER_ID), остальных игнорирует
- **Permissions для Claude Agent SDK** — `permissionMode: "bypassPermissions"` (персональный бот, интерактивный approval нецелесообразен)
- **Без валидации путей** — единственный пользователь, ограничение файловой системы не нужно
## Конфигурация
Файл `.env`:
```
TELEGRAM_BOT_TOKEN=<токен от BotFather>
TELEGRAM_OWNER_ID=<твой Telegram user ID>
ANTHROPIC_API_KEY=<API ключ Anthropic>
```
## Структура проекта
```
claude-telegram-bot/
├── src/
│ ├── index.ts # Точка входа
│ ├── bot.ts # grammy Bot, middleware owner check, хендлеры
│ ├── handlers/
│ │ ├── commands.ts # Хендлеры команд
│ │ └── message.ts # Текстовые сообщения → Claude
│ ├── services/
│ │ ├── session-manager.ts # CRUD сессий, переключение
│ │ └── claude.ts # Обёртка Claude Agent SDK
│ ├── state/
│ │ └── store.ts # Загрузка/сохранение state.json
│ └── utils/
│ └── telegram.ts # Разбивка сообщений, форматирование
├── .env
├── package.json
├── tsconfig.json
└── README.md
```
## Git
- Репозиторий: `http://localhost:3000/admin/claude-telegram-bot`
- Инициализация git при создании проекта, push в remote по завершении
docs/test-plan.md
+130
View File
@@ -0,0 +1,130 @@
# Master Test Plan — Claude Telegram Bot
Compiled from per-block test plans produced during implementation.
---
## Block 1: Project Scaffolding
- [ ] 1.1: `git log --oneline` shows initial commit
- [ ] 1.2: `bun run src/index.ts` starts without errors (with valid .env)
- [ ] 1.3: `.env` is NOT tracked by git
- [ ] 1.4: `git show --stat HEAD~8` shows exactly: .gitignore, bun.lock, package.json, src/index.ts, tsconfig.json
- [ ] 1.5: `node_modules/` exists with dependencies installed
## Block 2: State Store (`src/state/store.ts`)
- [ ] 2.1: `new Store()` returns default state `{ projects: {}, sessions: {}, activeSession: null }` when no state file exists
- [ ] 2.2: `store.save()` creates `~/.claude-telegram-bot/state.json` with valid JSON
- [ ] 2.3: Save then load round-trips correctly — write state, create new Store, verify data matches
- [ ] 2.4: `save()` auto-creates `~/.claude-telegram-bot/` directory if missing
- [ ] 2.5: TypeScript rejects invalid `SessionInfo.status` values (only "idle" | "busy")
## Block 3: Session Manager (`src/services/session-manager.ts`)
- [ ] 3.1: `activeSession` returns `null` when no session started
- [ ] 3.2: `createSession` sets session data, marks as active, and persists
- [ ] 3.3: `stopSession` removes session, reassigns active to remaining (or null)
- [ ] 3.4: `stopSession` returns `false` for unknown session name
- [ ] 3.5: `stopAll` clears all sessions, sets activeSession to null, returns count
- [ ] 3.6: `switchSession` updates activeSession and returns true for valid name
- [ ] 3.7: `switchSession` returns false for unknown name
- [ ] 3.8: `setStatus` updates only status field, no-ops for unknown session
- [ ] 3.9: `resolveProjectPath` returns bookmarked path when name matches a project
- [ ] 3.10: `resolveProjectPath` extracts basename from path for non-bookmarked input
- [ ] 3.11: `generateName` appends `-2`, `-3` on name conflicts
- [ ] 3.12: `saveProject` / `removeProject` CRUD works correctly
- [ ] 3.13: Every mutating method calls `store.save()` exactly once
## Block 4: Claude Service (`src/services/claude.ts`)
- [ ] 4.1: `createSession` returns non-empty `sessionId` with valid prompt and cwd
- [ ] 4.2: `createSession` returns non-empty `result` string
- [ ] 4.3: `sendMessage` with valid sessionId resumes context and returns result
- [ ] 4.4: Session context is preserved — sendMessage result reflects prior conversation
- [ ] 4.5: Invalid sessionId in `sendMessage` throws or returns empty string gracefully
- [ ] 4.6: `cwd` is respected — Claude tools resolve paths relative to it
- [ ] 4.7: Multi-message stream handled — only final result captured
## Block 5: Telegram Utilities (`src/utils/telegram.ts`)
- [ ] 5.1: Short message (<=4096 chars) returns single-element array
- [ ] 5.2: Exactly 4096 chars returns single-element array (boundary)
- [ ] 5.3: Long message with `\n\n` splits at paragraph boundary
- [ ] 5.4: Long message with only `\n` splits at line boundary
- [ ] 5.5: Long message with no whitespace hard-splits at 4096
- [ ] 5.6: All chunks are <= 4096 characters
- [ ] 5.7: No data loss — concatenated chunks reconstruct original content
- [ ] 5.8: `escapeMarkdown` returns input unchanged
## Block 6: Command Handlers (`src/handlers/commands.ts`)
- [ ] 6.1: `/start` without argument shows usage
- [ ] 6.2: `/start <path>` with existing session name suggests `/switch`
- [ ] 6.3: `/start <path>` creates Claude session, registers in manager, replies with result
- [ ] 6.4: `/stop` with no active session replies "Nothing to stop"
- [ ] 6.5: `/stop <name>` removes session, shows next active if any
- [ ] 6.6: `/stop <name>` for unknown session replies "not found"
- [ ] 6.7: `/stopall` stops all, reports count
- [ ] 6.8: `/switch` without argument shows usage
- [ ] 6.9: `/switch <name>` switches and confirms
- [ ] 6.10: `/switch <name>` for unknown session shows error + hint
- [ ] 6.11: `/sessions` with no sessions replies "No active sessions"
- [ ] 6.12: `/sessions` lists sessions with `►` marker and inline keyboard
- [ ] 6.13: `/status` with no session replies "No active session"
- [ ] 6.14: `/status` shows name, path, status
- [ ] 6.15: `/save` with <2 args shows usage
- [ ] 6.16: `/save <name> <path>` saves and confirms
- [ ] 6.17: `/remove <name>` removes or says "not found"
- [ ] 6.18: `/projects` shows list with inline "Start" buttons
- [ ] 6.19: `/help` shows full command reference
## Block 7: Message Handler (`src/handlers/message.ts`)
- [ ] 7.1: Non-text message ignored silently
- [ ] 7.2: Text with no active session shows "No active session" message
- [ ] 7.3: Text when session busy shows "Session is busy" message
- [ ] 7.4: Status set to "busy" before Claude call, "idle" after (including on error)
- [ ] 7.5: Typing indicator sent before Claude call
- [ ] 7.6: Response split into chunks and sent sequentially
- [ ] 7.7: Empty Claude response sends "(empty response)"
- [ ] 7.8: Claude error caught, error message sent, status reset to idle
## Block 8: Bot Setup (`src/bot.ts`)
- [ ] 8.1: `createBot` returns Bot instance without errors
- [ ] 8.2: Non-owner messages silently dropped by middleware
- [ ] 8.3: Owner messages reach handlers
- [ ] 8.4: `switch:` callback switches session and confirms
- [ ] 8.5: `start:` callback for unknown project answers "not found"
- [ ] 8.6: `start:` callback for existing session switches instead of creating
- [ ] 8.7: `start:` callback for new project creates session via Claude
- [ ] 8.8: Claude error in `start:` callback sends error message
- [ ] 8.9: All imports are static, `createBot` is synchronous
## Block 9: Entry Point (`src/index.ts`)
- [ ] 9.1: Missing TELEGRAM_BOT_TOKEN throws with clear message
- [ ] 9.2: Missing TELEGRAM_OWNER_ID throws with clear message
- [ ] 9.3: Missing ANTHROPIC_API_KEY throws with clear message
- [ ] 9.4: All vars present — bot starts, logs "Bot started successfully"
- [ ] 9.5: TELEGRAM_OWNER_ID converted to number
- [ ] 9.6: SIGINT triggers graceful shutdown with "Shutting down..." log
- [ ] 9.7: `.env` file loaded by dotenv/config
---
## Integration / Smoke Test
- [ ] E2E-1: `/help` — shows command list
- [ ] E2E-2: `/start /d/claude_telegram_bot` — creates session, Claude responds
- [ ] E2E-3: `What files are in this directory?` — Claude lists project files
- [ ] E2E-4: `/status` — shows session name, path, idle status
- [ ] E2E-5: `/sessions` — shows list with inline button
- [ ] E2E-6: Click inline button — switches session
- [ ] E2E-7: `/save mybot /d/claude_telegram_bot` — saves bookmark
- [ ] E2E-8: `/projects` — shows bookmark with "Start" button
- [ ] E2E-9: `/stop` — stops session
- [ ] E2E-10: `/sessions` — shows "No active sessions"
- [ ] E2E-11: Send text without session — shows "No active session" error
- [ ] E2E-12: Message from non-owner — silently ignored