Mikhail Putilovskij
6ced154124
- harden Matrix onboarding/chat lifecycle after manual QA - refresh README and Matrix docs to match current behavior - add local ignores for runtime artifacts and include current planning/report docs Closes #7 Closes #9 Closes #14
174 lines
6.6 KiB
Markdown
174 lines
6.6 KiB
Markdown
# Surfaces team — Lambda Lab 3.0
|
||
|
||
Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.
|
||
|
||
## Правило №1: не быть ждуном
|
||
|
||
Платформа (SDK от Азамата) ещё не готова. Это **не блокер**.
|
||
|
||
- Все вызовы платформы — через `platform/interface.py` (Protocol)
|
||
- Реализация сейчас — `platform/mock.py` (MockPlatformClient)
|
||
- При подключении реального SDK — меняем только `platform/mock.py`
|
||
- Архитектурные решения принимаем сами, фиксируем в `docs/api-contract.md`
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
surfaces-bot/
|
||
core/
|
||
protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
|
||
handler.py — EventDispatcher: IncomingEvent → OutgoingEvent (общее для всех ботов)
|
||
handlers/ — обработчики по типам событий (start, message, chat, settings, callback)
|
||
store.py — StateStore Protocol + InMemoryStore + SQLiteStore
|
||
chat.py — ChatManager: метаданные чатов C1/C2/C3
|
||
auth.py — AuthManager: AuthFlow
|
||
settings.py — SettingsManager: SettingsAction
|
||
|
||
adapter/
|
||
telegram/ — aiogram адаптер
|
||
converter.py — aiogram Event → IncomingEvent и обратно
|
||
bot.py — точка входа
|
||
handlers/ — aiogram роутеры
|
||
keyboards/ — инлайн-клавиатуры
|
||
states.py — FSM состояния
|
||
matrix/ — matrix-nio адаптер
|
||
converter.py — matrix-nio Event → IncomingEvent и обратно
|
||
bot.py — точка входа
|
||
handlers/ — обработчики событий
|
||
|
||
platform/
|
||
interface.py — Protocol: PlatformClient (контракт к SDK)
|
||
mock.py — MockPlatformClient (заглушка)
|
||
|
||
docs/ — вся документация
|
||
tests/ — pytest тесты
|
||
.claude/agents/ — конфиги агентов
|
||
```
|
||
|
||
Подробно об унификации: `docs/surface-protocol.md`
|
||
Telegram функционал: `docs/telegram-prototype.md`
|
||
Matrix функционал: `docs/matrix-prototype.md`
|
||
|
||
---
|
||
|
||
## Агенты
|
||
|
||
| Агент | Когда запускать | Модель | Токены |
|
||
|-------|----------------|--------|--------|
|
||
| `@researcher` | Изучить API, найти примеры | Haiku | ~дёшево |
|
||
| `@architect` | Спроектировать решение | Sonnet | ~средне |
|
||
| `@tg-developer` | Писать код Telegram-адаптера | Sonnet | ~средне |
|
||
| `@matrix-developer` | Писать код Matrix-адаптера | Sonnet | ~средне |
|
||
| `@core-developer` | Писать core/ и platform/ | Sonnet | ~средне |
|
||
| `@reviewer` | Проверить код перед PR | Sonnet | ~средне |
|
||
|
||
**Важно (Pro-лимиты):** не запускай больше двух Sonnet-агентов одновременно.
|
||
Haiku можно запускать параллельно сколько угодно.
|
||
|
||
---
|
||
|
||
## Стратегия параллельной разработки
|
||
|
||
Два бота разрабатываются параллельно, но через общее ядро.
|
||
|
||
### Порядок работы
|
||
|
||
```
|
||
1. core/ — сначала (однократно, все ждут)
|
||
@core-developer пишет protocol.py, handler.py, session.py, auth.py, settings.py
|
||
|
||
2. platform/ — сразу после core/
|
||
@core-developer пишет interface.py и mock.py
|
||
|
||
3. adapter/telegram/ и adapter/matrix/ — параллельно
|
||
@tg-developer → adapter/telegram/
|
||
@matrix-developer → adapter/matrix/
|
||
Не пересекаются по файлам — можно одновременно в разных терминалах.
|
||
```
|
||
|
||
### Что можно делать одновременно (разные терминалы)
|
||
|
||
```bash
|
||
# Терминал 1 — Telegram адаптер
|
||
claude "Use @tg-developer to implement adapter/telegram/handlers/start.py"
|
||
|
||
# Терминал 2 — Matrix адаптер (параллельно)
|
||
claude "Use @matrix-developer to implement adapter/matrix/handlers/start.py"
|
||
```
|
||
|
||
### Что нельзя делать одновременно
|
||
|
||
- Два агента в одном файле
|
||
- @core-developer параллельно с @tg-developer или @matrix-developer
|
||
(core/ должен быть готов до адаптеров)
|
||
- Больше двух Sonnet-агентов одновременно (Pro-лимит)
|
||
|
||
---
|
||
|
||
## Git worktree workflow
|
||
|
||
Каждая фича в отдельном worktree — адаптеры не мешают друг другу:
|
||
|
||
```bash
|
||
# Создать worktrees для параллельной работы
|
||
git worktree add .worktrees/telegram -b feat/telegram-adapter
|
||
git worktree add .worktrees/matrix -b feat/matrix-adapter
|
||
|
||
# Работать в каждом независимо
|
||
cd .worktrees/telegram && claude "Use @tg-developer to ..."
|
||
cd .worktrees/matrix && claude "Use @matrix-developer to ..."
|
||
|
||
# Смержить когда готово
|
||
git checkout main
|
||
git merge feat/telegram-adapter
|
||
git merge feat/matrix-adapter
|
||
```
|
||
|
||
---
|
||
|
||
## Команды запуска
|
||
|
||
```bash
|
||
# Установить зависимости
|
||
uv sync
|
||
|
||
# Запустить тесты
|
||
pytest tests/ -v
|
||
|
||
# Запустить только тесты Telegram
|
||
pytest tests/adapter/telegram/ -v
|
||
|
||
# Запустить только тесты Matrix
|
||
pytest tests/adapter/matrix/ -v
|
||
|
||
# Запустить только тесты ядра
|
||
pytest tests/core/ -v
|
||
|
||
# Запустить Telegram бота
|
||
python -m adapter.telegram.bot
|
||
|
||
# Запустить Matrix бота
|
||
python -m adapter.matrix.bot
|
||
```
|
||
|
||
---
|
||
|
||
## Переменные окружения
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Никогда не коммить `.env`.
|
||
|
||
---
|
||
|
||
## Экономия токенов (Pro-лимиты)
|
||
|
||
- Исследования → всегда `@researcher` (Haiku), не Sonnet
|
||
- Точечные правки в одном файле → напрямую без агента
|
||
- Ревью → только перед PR, не после каждого коммита
|
||
- Длинный контекст → дай агенту конкретный файл, не весь проект
|
||
- Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее
|