From 3f39b7002aabfd317c24b56deee5479cc523e57e Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Thu, 16 Apr 2026 12:01:26 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20create=20thread=20=E2=80=94=20matrix=20?= =?UTF-8?q?dev=20prototype=20agent=20platform=20state?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...trix-dev-prototype-agent-platform-state.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 .planning/threads/matrix-dev-prototype-agent-platform-state.md diff --git a/.planning/threads/matrix-dev-prototype-agent-platform-state.md b/.planning/threads/matrix-dev-prototype-agent-platform-state.md new file mode 100644 index 0000000..c485ab0 --- /dev/null +++ b/.planning/threads/matrix-dev-prototype-agent-platform-state.md @@ -0,0 +1,133 @@ +# Thread: Matrix dev prototype — состояние агента и платформы + +## Status: OPEN + +## Goal + +Зафиксировать текущее состояние платформы для последующей разработки Matrix dev прототипа, +в котором команды разработки скиллов смогут быстро добавлять и обкатывать скиллы. + +## Context + +*Исследование проведено 2026-04-14. Репозитории: `external/platform-agent`, `external/platform-agent_api`, `external/platform-master`.* + +### Решение по деплою: локальный контейнер у каждого разработчика + +`platform-master` не готов для общего деплоя: +- lifecycle management контейнеров (TTL, cleanup, переиспользование сессий) — в ветке `feat/storage`, не смержено в main +- без него при общем деплое контейнеры висят вечно, ресурсы не освобождаются + +Локальный вариант: `make up-dev` — полностью рабочий, volume mount `./workspace:/workspace/`, hot reload src. + +### Архитектура изоляции контекстов + +`AgentService` — singleton с `thread_id = "default"` — это **намеренно**. Архитектура Master предполагает один контейнер `platform-agent` на один чат. Изоляция на уровне контейнеров, не thread_id. Фиксить не нужно. + +### Система скиллов (deepagents) + +`SkillsMiddleware` в `deepagents` полностью готов: +- скилл = директория с `SKILL.md` (YAML frontmatter + markdown инструкции) +- progressive disclosure: агент видит имя+описание в system prompt, читает полный файл по требованию +- загружается один раз при старте сессии, кэшируется в LangGraph state + +**НЕ подключено** в `platform-agent/src/agent/base.py` — отсутствует одна строка: +```python +skills=["/workspace/skills/"] +``` +Это задача для команды платформы. + +### Workflow разработчика скилла + +``` +workspace/ + skills/ + my-skill/ + SKILL.md ← редактируешь здесь (live через volume mount) + helper.py ← вспомогательные файлы + config/ + my-skill.json ← токены и настройки (пишет агент при первом запуске) +``` + +1. Редактируешь `SKILL.md` +2. `!new` в Matrix (новая сессия = скиллы перечитываются) +3. Проверяешь поведение +4. Повторяешь + +Агент может **сам установить скилл** из GitHub: +- `execute` → git clone +- `write_file` → положить в `/workspace/skills/` +- после `!new` скилл активен + +### Конфигурация скиллов (токены, API ключи) + +Агент управляет конфигом сам: +- первый запуск: спрашивает пользователя → пишет в `/workspace/config/skill-name.json` +- последующие запуски: читает из файла +- файл персистентен между сессиями (volume mount) + +### Входящий протокол (что принимает агент) + +`ClientMessage` — только `text: str`. Файлы и изображения не поддерживаются. +Задача для платформы — расширить протокол. + +### Исходящий протокол (что шлёт агент) + +Новые события с `origin/main` (апрель 2026): +- `AGENT_EVENT_TOOL_CALL_CHUNK` — агент вызывает инструмент +- `AGENT_EVENT_TOOL_RESULT` — результат инструмента +- `AGENT_EVENT_CUSTOM_UPDATE` — произвольный прогресс + +**Наш `sdk/agent_session.py` падает на этих событиях** (`raise PlatformError("Unexpected agent message")`). +Нужно починить — это наша задача, ~10 строк. + +### AgentApi из lambda_agent_api + +Готовый production-клиент с правильным lifecycle (`connect()`, `close()`, `send_message()` как `AsyncIterator`). +Наш `sdk/agent_session.py` дублирует его функциональность. Стоит заменить. + +### Инструменты агента из коробки + +- `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` — файловые операции в workspace +- `execute` — shell под изолированным OS-пользователем `agent` +- `write_todos` — список задач +- `task` — вызов субагентов + +### Запуск локально + +```bash +# .env минимально необходимый: +PROVIDER_URL=https://openrouter.ai/api/v1 +PROVIDER_API_KEY=<ключ> +PROVIDER_MODEL=anthropic/claude-sonnet-4-6 + +# Dev контейнер: +make up-dev # требует AGENT_API_PATH=../platform-agent_api в env +``` + +Dev Dockerfile монтирует `./workspace:/workspace/` и `./src:/app/src` (hot reload). + +## Что нужно от платформы + +1. Добавить `skills=["/workspace/skills/"]` в `platform-agent/src/agent/base.py` +2. Поддержка файлов/изображений в `ClientMessage` (не срочно для MVP) +3. Lifecycle management контейнеров в Master (для общего деплоя, не срочно) + +## Что делаем мы + +1. Починить `sdk/agent_session.py` — обработка tool-событий вместо исключения +2. (опционально) Заменить `AgentSessionClient` на `AgentApi` из `lambda_agent_api` + +## References + +- `external/platform-agent` — локальный клон, наш патч `1dca2c1` (thread_id) поверх `1e9fa1f` +- `external/platform-agent_api` — локальный клон, актуальный (origin/master = `bb20a84`) +- `external/platform-master` — локальный клон, активная разработка в `feat/storage-s02` +- `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md` +- `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md` + +## Next Steps + +1. Запросить у команды платформы: подключение `SkillsMiddleware` в `base.py` +2. Починить `sdk/agent_session.py` — обработать tool-события +3. Написать первый тестовый скилл (`workspace/skills/hello/SKILL.md`) и проверить end-to-end +4. Документировать workflow для разработчиков скиллов