Autonomous code orchestration

Ergodeon - автономный AI-агент на Python для разработки программного обеспечения. Использует LLM через API OpenRouter для понимания инструкций пользователя и взаимодействия с операционной системой.

Ключевая особенность - способность планировать, выполнять инструменты (чтение/запись файлов, запуск команд) и поддерживать контекст диалога. При работе над проектом агент автоматически создаёт документацию (чеклист, walkthrough, план) в формате YAML + Markdown.

Требуется Python 3.10+, uv, Node.js 18+ (для веб-режима).

pip install uv
cp .env.example .env
# вставьте OPENROUTER_API_KEY в .env

При обновлении библиотек

uv sync --reinstall

Два независимых режима. CLI использует Rich в терминале, веб-режим поднимает Litestar-сервер и Svelte-клиент в браузере. Функциональность одинакова в обоих.

./run_demo.sh                                  # обычный запуск
./run_demo.sh --project ./projects/my-project  # открыть существующий проект
./run_demo.sh --resume  ./projects/my-project  # сразу возобновить пайплайн

./run_demo_web.sh         # dev: сервер :8000 + Svelte dev :5173
./run_demo_web.sh --prod  # prod: собрать Svelte, раздавать из питона

В dev режиме открыть http://localhost:5173. В prod - http://localhost:8000.

Работают одинаково в CLI и веб-интерфейсе.

Если путь не указан - используется текущий активный проект.

Описываете задачу. Агент определяет что это пайплайн, создаёт папку в projects/, проходит 7 этапов.

User: Launchpad-контракт на Solidity для Polygon с вайтлистом...
→ Агент предлагает запустить пайплайн
→ Создаёт projects/polygon-launchpad_1234567890/
→ Проходит этапы 1-7
→ При прерывании: статус сохранён в execution_log.yaml

Прогресс сохраняется после каждого шага. Продолжить можно тремя способами:

# CLI при запуске
./run_demo.sh --resume ./projects/polygon-launchpad_1234567890

# Команда в чате (CLI или веб)
resume ./projects/polygon-launchpad_1234567890

# Естественным языком
продолжи выполнение ./projects/polygon-launchpad_1234567890

# CLI при запуске
./run_demo.sh --project ./my-existing-app

# Команда в чате (CLI или веб)
adopt ./my-existing-app

# Естественным языком
возьми проект ./my-existing-app
вот проект /home/user/my-app - поработай с ним

После adopt агент предлагает: проанализировать / запустить пайплайн / просто работать.

Глубокий анализ кодовой базы с сохранением в analysis.md внутри папки проекта.

analyze ./my-app

# Или естественным языком
проанализируй проект ./my-app и сохрани результат

Анализ включает стек, архитектуру, точки входа, технический долг, рекомендации.

После любого из флоу 1-4 агент знает активный проект и все операции выполняет внутри него.

что здесь не так с архитектурой?
добавь логирование в модуль payments
напиши тесты для функции calculate_fee

Сервер - Litestar + python-socketio (ASGI). Клиент - Svelte + socket.io-client. Один WebSocket коннект = одна сессия агента.

Все события агента стримятся в браузер в реальном времени. Опасные операции показывают диалог подтверждения с блокировкой интерфейса до ответа пользователя.

StatusBar - текущий стейдж, прогресс-бар шагов, финальный статус пайплайна.

Chat - лента сообщений с типами: user, assistant, system, error, review. Поддерживает **bold** и `code` без внешних зависимостей.

Input - поле ввода с автодополнением команд (начните вводить adopt, resume, analyze, reset). Enter отправляет, Shift+Enter - перенос строки.

LogStream - сворачиваемая панель с логами агента и tool_call/tool_result событиями. Ограничена 500 строками.

ConfirmDialog - всплывающий диалог при опасных операциях. Блокирует интерфейс до явного Выполнить/Отклонить.

./run_demo_web.sh --prod

Собирает Svelte в web/dist/, Litestar раздаёт статику через StaticFilesConfig. Одна команда, один процесс.

Ergodeon/
  src/openrouter_agent/
    agent/
      core.py          ядро агента, ReAct цикл, run_pipeline, resume_pipeline
      intent.py        классификация намерений
      memory.py        эпизодическая память (Jaccard similarity)
      planner.py       планировщик, валидация, авто-исправление
      sandbox.py       снимки рабочей директории
      prompts.py       промты для LLM (7 шт)
      config.py        конфигурация пайплайна
      scanner.py       сканнер проекта
      doc_generator.py генератор документов (YAML + MD)
    tools/
      base.py          BaseTool (msgspec)
      registry.py      реестр инструментов
      filesystem.py    файловая система (10 инструментов)
      system.py        системные команды (2 инструмента)
      web.py           веб (2 инструмента)
      code.py          анализ кода (1 инструмент)
      reasoning.py     мета-рассуждение (1 инструмент)
      json_edit.py     JSONPath редактор (1 инструмент)
    server/
      app.py           Litestar + socketio, монтирование статики
      agent_session.py сессия агента на коннект, log bridge, confirm bridge
      events.py        константы имён socketio событий
    utils.py           load/save json/yaml, find_balanced_json, compute_diff
  demo/
    cli.py             интерактивный CLI (Rich)
  web/
    src/
      lib/
        socket.js      singleton socketio клиент, все stores
      components/
        Chat.svelte         лента сообщений
        Input.svelte        поле ввода с автодополнением команд
        StatusBar.svelte    прогресс пайплайна
        LogStream.svelte    лог агента (сворачиваемый)
        ConfirmDialog.svelte диалог подтверждения опасных операций
      App.svelte
    package.json
    vite.config.js
  memory/
    episodes.json      персистентная память эпизодов
  projects/            созданные агентом проекты
  pyproject.toml
  run_demo.sh
  run_demo_web.sh
  .env.example

AUTO_CONFIRM=true - агент не спрашивает подтверждение при write_file, edit_file, execute_command и других опасных операциях. В веб-режиме при AUTO_CONFIRM=false вместо CLI-запроса показывается ConfirmDialog. Ревью документов всегда требует явного ответа.

Документы хранятся в флоу-разработки/стейдж-N/версия-N/ внутри папки проекта.

Запрос преобразуется в структуру: goal, actions, constraints, implicit_requirements, priority, scope. При размытом запросе агент задаёт уточняющие вопросы.

ProjectScanner рекурсивно обходит проект (игнорирует .git, node_modules, .venv). LLM генерирует Project Digest: стек, архитектура, зависимости, риски.

Три документа генерируются последовательно. checklist.yaml - атомарные задачи. walkthrough.yaml - изменения по блокам. implementation_plan.yaml - шаги выполнения. Каждый документ имеет параллельный .md для чтения и комментирования.

Ожидает обратную связь. Комментарии через <!-- COMMENT: текст --> в .md файлах или в чате. Изменение чеклиста каскадно перегенерирует walkthrough и план.

Последовательное выполнение шагов. Прогресс сохраняется в execution_log.yaml после каждого шага. При ошибке до 3 повторных попыток.

Итоговая статистика. При >30% провалов - critical_failure. При partial_success - подсказка команды для resume.

флоу-разработки/стейдж-1/версия-1/
  parsed_request.yaml
  project_digest.yaml
  checklist.yaml / checklist.md
  walkthrough.yaml / walkthrough.md
  implementation_plan.yaml / implementation_plan.md
  execution_log.yaml       основа для resume (статус после каждого шага)
  execution_log.md         human-readable лог
  review_comments.md       для inline комментариев

Все файловые операции ограничены директорией project_dir через _resolve_and_guard. Попытка записи за пределы блокируется до передачи инструменту.

При AUTO_CONFIRM=false каждая опасная операция требует явного подтверждения. В CLI - через Confirm.ask в терминале с остановкой спиннера. В веб-режиме - через ConfirmDialog с блокировкой интерфейса и таймаутом 5 минут.