feat(matrix): land QA follow-ups and refresh docs
- 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
This commit is contained in:
parent
7fce4c9b3e
commit
6ced154124
35 changed files with 8380 additions and 67 deletions
174
docs/workflow-backup-2026-04-01.md
Normal file
174
docs/workflow-backup-2026-04-01.md
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
# 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, не после каждого коммита
|
||||
- Длинный контекст → дай агенту конкретный файл, не весь проект
|
||||
- Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее
|
||||
Loading…
Add table
Add a link
Reference in a new issue