123 lines
7.6 KiB
Markdown
123 lines
7.6 KiB
Markdown
# Phase 1: Matrix QA & Polish — Context
|
||
|
||
**Gathered:** 2026-04-02
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
Переработать и довести Matrix адаптер до уровня "приемлемо работает" как Telegram:
|
||
- Переход с DM-first на Space+rooms архитектуру
|
||
- Убрать реакции как механизм подтверждения — заменить текстовыми командами
|
||
- Реализовать все команды управления (`!new`, `!chats`, `!rename`, `!archive`, `!skills`, `!soul`, `!safety`, `!settings`)
|
||
- Подтвердить работу ручным тестированием (бот уже запускался)
|
||
|
||
Новые возможности (коннекторы, E2EE, Space discovery) — вне scope.
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Архитектура: Space + rooms
|
||
|
||
- **D-01:** Space+rooms — единственная поддерживаемая модель. DM-first убрать.
|
||
- **D-02:** При первом invite бот создаёт Space `Lambda — {display_name}`, внутри — первую комнату `Чат 1`. Приглашает пользователя.
|
||
- **D-03:** `!new [name]` создаёт новую комнату внутри Space пользователя, приглашает его туда.
|
||
- **D-04:** `!archive` выводит комнату из Space (не удаляет).
|
||
- **D-05:** Маппинг `room_id → space_id` + `room_id → chat_id` хранится в SQLite через `adapter/matrix/store.py`.
|
||
|
||
### Подтверждение действий
|
||
|
||
- **D-06:** Реакции (`👍`/`❌`) — убрать полностью. `OutgoingUI` с кнопками рендерится как текст + `!yes` / `!no`.
|
||
- **D-07:** Когда агент запрашивает подтверждение, бот пишет текстовое сообщение с описанием и подсказкой: `Ответьте !yes для подтверждения или !no для отмены.`
|
||
- **D-08:** `!yes` / `!no` работают в текущей комнате. Состояние ожидания подтверждения хранится per (user_id, room_id).
|
||
|
||
### Команды
|
||
|
||
- **D-09:** Все команды работают из любой комнаты Space — нет выделенной комнаты «Настройки».
|
||
- **D-10:** Команды: `!new [name]`, `!chats`, `!rename <name>`, `!archive`, `!skills`, `!soul`, `!safety`, `!settings`, `!yes`, `!no`.
|
||
- **D-11:** `!start` — не нужен, онбординг через invite flow.
|
||
|
||
### Настройки (Вариант D)
|
||
|
||
- **D-12:** `!settings` — read-only дашборд: одно сообщение со статусом всего (скиллы, soul, safety, активные чаты). Ничего не меняет.
|
||
- **D-13:** Изменения через субкоманды:
|
||
- `!skills` — показать список; `!skill on/off <name>` — переключить
|
||
- `!soul` — показать профиль; `!soul name/style/priority/reset <value>` — изменить
|
||
- `!safety` — показать статус; `!safety on/off <action>` — переключить
|
||
- **D-14:** Каждая команда без аргументов (`!skills`, `!soul`, `!safety`) выводит текущее состояние + подсказку как менять.
|
||
|
||
### Claude's Discretion
|
||
|
||
- Формат текста в Matrix (plain text vs markdown) — на усмотрение, Matrix клиенты рендерят markdown
|
||
- Структура invite-сообщения в новом Space — на усмотрение, главное: приветствие + список команд
|
||
- Обработка ошибок matrix-nio (room_create fail, join fail) — логировать + ответить пользователю
|
||
|
||
</decisions>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Архитектурные документы
|
||
- `docs/matrix-prototype.md` — описание Space+rooms структуры, FSM состояний, команд (ВНИМАНИЕ: секция "Реакции как действия" устарела — заменена D-06..D-08)
|
||
- `bot-examples/matrix_bot_rooms.py` — reference реализация Space+rooms на matrix-nio (другая архитектура поверх, но паттерны работы с Space/rooms актуальны)
|
||
|
||
### Текущая реализация (требует переработки)
|
||
- `adapter/matrix/bot.py` — точка входа, `send_outgoing` (реакции убрать), `MatrixBot`, `MatrixRuntime`
|
||
- `adapter/matrix/handlers/auth.py` — `handle_invite` (сейчас создаёт DM без Space — переписать)
|
||
- `adapter/matrix/handlers/chat.py` — `make_handle_new_chat` (сейчас не добавляет комнату в Space — переписать)
|
||
- `adapter/matrix/store.py` — хранилище метаданных комнат (расширить для space_id)
|
||
- `adapter/matrix/room_router.py` — маршрутизация room_id → chat_id
|
||
|
||
### Протокол
|
||
- `core/protocol.py` — `IncomingCommand`, `OutgoingUI`, `OutgoingMessage` — типы не менять
|
||
- `adapter/matrix/converter.py` — маппинг nio events → IncomingEvent
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `adapter/matrix/store.py`: `get_room_meta` / `set_room_meta` — переиспользовать, добавить поля `space_id`
|
||
- `adapter/matrix/room_router.py`: `resolve_chat_id` — переиспользовать, возможно расширить
|
||
- `core/handlers/`: все обработчики команд уже зарегистрированы через `register_all`
|
||
- `adapter/matrix/handlers/settings.py`, `confirm.py` — проверить, возможно переиспользовать/обновить
|
||
|
||
### Known Bugs (из анализа кода)
|
||
- `auth.py:27`: `"chat_id": "C1"` захардкожен — у каждого нового пользователя будет коллизия
|
||
- `bot.py:167`: `_button_action_to_reaction` — убрать целиком
|
||
- `handlers/chat.py:50`: `room_create` не добавляет комнату в Space (`space_id` не указан)
|
||
|
||
### Integration Points
|
||
- `AsyncClient.room_create(space=True)` — создание Space через matrix-nio
|
||
- `AsyncClient.room_put_state(room_id, "m.space.child", ...)` — добавление комнаты в Space
|
||
- Оба метода есть в `bot-examples/matrix_bot_rooms.py`
|
||
|
||
</code_context>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- Подтверждение: бот пишет `Ответьте !yes для подтверждения или !no для отмены.` — явно, без двусмысленности
|
||
- `!settings` — один дашборд-блок, не несколько сообщений
|
||
|
||
</specifics>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
- Комната «Настройки» как отдельная закреплённая комната — решили не делать в Phase 1
|
||
- E2EE / python-olm — инфраструктурный трек, вне scope
|
||
- Space discovery (бот находит существующий Space при повторном invite) — Phase 2+
|
||
- Attachment handling (m.file, m.image, m.audio) — Phase 2+
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 01-matrix-qa-polish*
|
||
*Context gathered: 2026-04-02*
|