docs: add design spec, implementation plan, test plan; update gitignore
This commit is contained in:
neken
@@ -1,3 +1,5 @@
|
||||
node_modules/
|
||||
dist/
|
||||
.env
|
||||
.claude/
|
||||
*.log
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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 по завершении
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user