🕉️ Проект 999: Армия Автономных НейроКодеров

🕉️ Архитектура Агентов и Правила Проекта

📍 Важно: Хранилище Правил

Все правила проекта и подробные инструкции для каждого агента хранятся исключительно в директории .cursor/rules/ в виде файлов .mdc. Эта директория – единственный источник истины для Дхармы проекта. README.mdc предоставляет высокоуровневый обзор и ссылки на эти файлы.

Этот документ описывает высокоуровневую архитектуру агентов, их роли, зоны ответственности и связь с основными правилами (Дхармой) проекта. Сами инструкции для каждого агента находятся в соответствующих AGENT_*.mdc файлах.

🎯 Текущая Задача

Для понимания текущей цели и этапа работ смотри: current_task.mdc.

📂 Документация скриптов

Подробная документация по скриптам проекта доступна в файле scripts/README.md.

🧘‍♂️ Основные Агенты

📜 Общие Правила и Принципы

Помимо специфичных инструкций для агентов, существуют общие правила, которым должны следовать все (включая Гуру и будущих наблюдателей):

TDD: Неукоснительное следование циклу "Красный -> Зеленый -> Рефакторинг".
Автономность: Агенты стремятся решать задачи самостоятельно, обращаясь к Гуру только при необходимости.
Стиль и Паттерны: Следование единому стилю кода и использование существующих паттернов.
Тестирование и Отладка: Используй команду bun test и следуй ритуалу, описанному в @testing-workflow.mdc.
Git Workflow: Работа через feature-ветки и Pull Request'ы.

Эти принципы были интегрированы в инструкции соответствующих агентов.

🕉️ Ритуал TDD с Помощником (`scripts/tdd-cycle.sh`)

Проблема: При ручном выполнении TDD-цикла легко пропустить важные шаги, такие как проверка типов (tsc) перед тестами или забыть запустить тесты после рефакторинга. Это приводит к накоплению ошибок, "сломанным" коммитам и болезненным регрессиям, когда новое изменение ломает старую функциональность. Время тратится на отладку проблем, которых можно было избежать.

Решение (Дхарма): Чтобы обеспечить чистоту кода, предотвратить регрессии и гарантировать последовательное выполнение всех шагов TDD, ОБЯЗАТЕЛЬНО использовать скрипт-помощник scripts/tdd-cycle.sh для КАЖДОГО цикла разработки, включающего изменение тестового файла.

Как Использовать:

Напишите падающий тест (🔴) в соответствующем файле (src/__tests__/...).

Запустите скрипт:

bash scripts/tdd-cycle.sh <путь_к_вашему_тестовому_файлу>

Следуйте инструкциям скрипта:
- Он проверит типы и убедится, что тест действительно падает (🔴).
- После написания кода реализации он будет проверять типы и запускать тест до тех пор, пока он не пройдет (🟢).
- После этапа рефакторинга он снова проверит типы и убедится, что тест все еще проходит (♻️).
Только после успешного завершения скрипта можно переходить к коммиту и обновлению документации (current_task.mdc, SUCCESS_HISTORY.md, REGRESSION_PATTERNS.md).

Улучшение Скрипта: Скрипт можно и нужно улучшать по мере выявления новых краевых случаев или потребностей в автоматизации.

Ом Шанти. Следуй ритуалу, и код твой будет чист и стабилен. 🙏

💾 Управление Состоянием (State Management)

📜 Общие Правила и Принципы

⚙️ Управление Окружением Разработки

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

Хранение типов

Все файлы с типами (*.d.ts, *type*.ts) должны находиться исключительно в директориях src/types или vendor-types. Это способствует:

Разделению собственных и вендорных типов
Единой точке истины для типов
Упрощению навигации
Предотвращению циклических зависимостей

Для проверки выполните: ./scripts/type-location-checker.sh

Запуск Окружения для Тестирования Агентов (Ручной режим)

Вместо использования PM2 или сложных скриптов, для стабильной работы во время совместной разработки с AI-ассистентом рекомендуется запускать необходимые фоновые сервисы вручную в отдельных окнах терминала с использованием bun:

Окно 1: Компиляция TypeScript (Watch Mode)
```
bun run build:watch
```
- Назначение: Запускает tsc --watch --preserveWatchOutput. Автоматически перекомпилирует .ts файлы в dist/ при их изменении.
Окно 2: Inngest Dev Server
```
bun run dev:serve
```
- Назначение: Запускает inngest-cli dev. Слушает события на http://localhost:8288, находит и запускает функции Inngest из работающего приложения (подключаясь к нему по URL, указанному в команде, обычно http://localhost:8484/api/inngest).
Окно 3: Сервер Приложения
```
bun run dev:start
```
- Назначение: Запускает основной сервер приложения, который обслуживает API для Inngest (/api/inngest) и выполняет код функций/агентов. Пытается использовать порт 8484.

Перед началом работы с AI: Убедитесь, что все три команды успешно запущены в отдельных окнах и работают без ошибок.

Использование PM2 (Альтернатива для долгосрочных процессов)

Если требуется более надежное управление фоновыми процессами, можно использовать pm2.

Установка (если не установлен):
```
npm install -g pm2
```

Первый Запуск / Перезапуск: Остановите все текущие процессы (pm2 delete all) и запустите необходимые с использованием bun:

# Компилятор TypeScript в режиме наблюдения
pm2 start bun --name tsc-watch -- run build:watch

# Inngest Dev Server (требуется для локальной разработки Inngest)
pm2 start bun --name inngest-dev -- run dev:serve

# Основное приложение (Сервер приложения)
pm2 start bun --name app-server -- run dev:start

Проверка Статуса:
```
pm2 list
```

Просмотр Логов:

pm2 logs <имя_процесса>
pm2 logs # Показать логи всех процессов

Сохранение/Восстановление:
```
pm2 save
pm2 resurrect
```
Полная Остановка:
```
pm2 delete all
```

🏺 Сохранение и Восстановление Конфигурации ("Игла Кощея")

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

Критически Важные Файлы Конфигурации

Следующие файлы считаются критически важными для консистентности окружения и включены в снимки:

package.json: Определяет зависимости проекта и скрипты.
bun.lockb: Фиксирует точные версии установленных зависимостей (аналог pnpm-lock.yaml).
tsconfig.json: Конфигурация компилятора TypeScript.
(vite.config.ts удален): Ранее использовался для Vite/Vitest, теперь конфигурация тестов управляется Bun.
.npmrc: Может содержать настройки для bun, хотя часто не требуется. Ранее использовался для pnpm с node-linker=hoisted.

Создание Снимка

Для сохранения текущей стабильной конфигурации используйте скрипт:

bash scripts/config/save-snapshot.sh

Это создаст директорию snapshots/snapshot-YYYY-MM-DD_HH-MM-SS, содержащую копии критически важных файлов.

Восстановление из Снимка

Если конфигурация была нарушена или вы настраиваете проект заново, вы можете восстановить последнюю известную стабильную конфигурацию:

Найдите нужный снимок: Посмотрите директории в snapshots/.

Запустите скрипт восстановления, указав путь к директории снимка:

# Замените <имя_директории_снимка> на актуальное
bash scripts/config/restore-snapshot.sh snapshots/<имя_директории_снимка>

Переустановите зависимости: После восстановления файлов обязательно выполните:
```
bun install
```

🛠️ Недавние Важные Исправления (Май 2024)

Для контекста и предотвращения повторения ошибок:

Проблема с zod: Ошибки TypeScript "Cannot find module 'zod'" были решены путем перехода на bun. Механизм установки зависимостей bun устранил эту проблему.
Ошибка Типов Агентов: Ошибка TS2352 в src/inngest/logic/dependencyUtils.ts была временно устранена явным приведением типов через as unknown as Agent<TddNetworkState>. Требует рефакторинга: функции create*Agent должны быть параметризованы типом состояния (TddNetworkState) для корректной типизации.
Переход на bun: Проект полностью переведен с pnpm и Vitest на bun для управления зависимостями, запуска скриптов и выполнения тестов (bun test). Файлы конфигурации vite.config.ts, vitest.config.ts, vitest.config.e2e.ts были удалены.

🚀 Восстановление Окружения с Нуля

Клонируйте репозиторий:

git clone https://github.com/gHashTag/999.git
cd 999

Установить зависимости:
```
bun install
```
Настроить окружение:
- Скопировать .env.example в .env.
- Заполнить .env необходимыми ключами API (DeepSeek, E2B, Inngest).

Запустить фоновые сервисы (в отдельных терминалах):

# Окно 1: Компиляция TypeScript
bun run build:watch
# Окно 2: Inngest Dev Server
bun run dev:serve
# Окно 3: Сервер Приложения
bun run dev:start

Отправить тестовое событие Inngest:

node scripts/send-test-event.mjs "Create a file hello.txt with content Hello World"
# Или:
# curl -X POST http://localhost:8288/e/<YOUR_INNGEST_EVENT_KEY> -d '{"name":"coding-agent/run", "data":{"input":"Your task here"}}'

Наблюдать за логами:

tail -f node-app.log | bun run scripts/pretty-logs.mjs
# Или
tail -f inngest-cli.log

✅ Статус и Текущие Задачи

Состояние проекта, текущие задачи и roadmap отслеживаются в файле: .cursor/rules/current_task.mdc

🛠️ Технологический Стек

Среда выполнения: Bun
Язык: TypeScript
Оркестрация задач: Inngest
Оркестрация агентов: AgentKit (@inngest/agent-kit)
Тестирование: Bun Test (bun test)
Качество кода: ESLint, Prettier
Форматирование логов: pino-pretty
Модель ИИ: DeepSeek Coder (или другая, настраивается через .env)
Песочница (опционально): E2B Sandbox (@e2b/sdk)

📁 Структура Проекта

├── .cursor/         # Конфигурация и правила для Cursor AI
│   └── rules/       # Правила и контекст для AI (Дхарма Проекта)
├── .husky/          # Git хуки (для pre-commit проверок)
├── artifacts/       # Артефакты выполнения (логи, файлы из песочницы)
├── coverage/        # Отчеты о покрытии кода тестами (удалено, Bun не генерирует html по умолчанию)
├── html/            # Отчеты Bun Test (если настроено)
├── node_modules/    # Зависимости
├── scripts/         # Вспомогательные скрипты (сборка, тесты, деплой...)
├── src/
│   ├── adapters/    # Адаптеры для внешних сервисов (MCP, ...)
│   ├── agents/      # Логика отдельных агентов (Coder, Critic, ...)
│   ├── cli/         # Компоненты для CLI (open-codex-cli)
│   ├── definitions/ # Определение агентов и инструментов для AgentKit
│   ├── inngest/     # Функции и логика Inngest
│   ├── mocks/       # Моки для MSW (тестирование API)
│   ├── network/     # Логика сети агентов AgentKit (роутер, состояние)
│   ├── server/      # Основной сервер приложения (Fastify)
│   ├── tools/       # Определения и логика инструментов для агентов
│   ├── types/       # Глобальные типы TypeScript
│   ├── utils/       # Общие утилиты (логгер, обработка ошибок)
│   └── vendor/      # Копии типов из vendor-библиотек (для стабильности)
├── vendor-types/    # Скопированные `.d.ts` файлы из `node_modules`
├── .env.example     # Пример файла переменных окружения
├── .env             # Переменные окружения (в .gitignore)
├── .eslintignore    # Файлы, игнорируемые ESLint (устарело)
├── .eslintrc.cjs    # Конфигурация ESLint
├── .gitignore       # Файлы, игнорируемые Git
├── .prettierrc.json # Конфигурация Prettier
├── bun.lockb        # Lock-файл Bun
├── eslint.config.js # Новая конфигурация ESLint (приоритет над .eslintrc.cjs)
├── package.json     # Зависимости и скрипты проекта
├── tsconfig.json    # Конфигурация TypeScript
└── README.md        # Этот файл

📜 Скрипты `package.json`

bun install: Установка зависимостей.
bun run build: Сборка проекта TypeScript (tsc).
bun run build:watch: Сборка в режиме наблюдения.
bun run dev:serve: Запуск Inngest Dev Server (inngest-cli dev).
bun run dev:start: Запуск основного сервера приложения (bun run src/server/index.ts).
bun run dev: Запуск dev:serve и dev:start параллельно с concurrently.
bun run lint: Проверка кода с помощью ESLint.
bun run lint:fix: Исправление ошибок ESLint.
bun run format: Форматирование кода с помощью Prettier.
bun run format:check: Проверка форматирования.
bun run typecheck: Проверка типов TypeScript (tsc --noEmit).
bun run check: Запуск lint, format и typecheck последовательно.
bun test: Запуск всех тестов с помощью Bun Test Runner.
bun test:watch: Запуск тестов в режиме наблюдения.
bun test:ui: Запуск тестов с UI (может не работать с Bun Test).
bun test:coverage: Запуск тестов с генерацией отчета о покрытии.
bun test:e2e: Запуск E2E тестов.
bun run open-codex: Запуск интерактивного CLI для общения с агентами.

🧪 Тестирование

Проект использует Bun Test Runner для всех видов тестов.

Unit-тесты: Проверяют отдельные модули/функции/агенты в изоляции. Находятся в src/__tests__/... (например, src/__tests__/agents/coder.test.ts).
Интеграционные тесты: Проверяют взаимодействие нескольких компонентов (например, адаптер + мок-инструмент). Находятся в src/__tests__/integration/, src/__tests__/adapters/.
E2E-тесты: Проверяют полный цикл работы системы, часто с использованием реальных или частично мокированных внешних зависимостей. Находятся в src/__tests__/e2e/.
Запуск:
- Все тесты: bun test
- Тесты в режиме наблюдения: bun test --watch
- Изолированный запуск файла: bun test <путь_к_файлу> --isolate
- Запуск с покрытием: bun test --coverage (отчет в консоли)

🪵 Логирование

Используется pino для структурированного логирования. Для удобного чтения логов в консоли используется pino-pretty через скрипт scripts/pretty-logs.mjs:

tail -f node-app.log | bun run scripts/pretty-logs.mjs

🤖 Архитектура Агентов

Высокоуровневое описание ролей агентов и принципов их взаимодействия находится в: .cursor/rules/README.mdc

Детальные инструкции для каждого агента находятся в соответствующих файлах AGENT_*.mdc в той же директории.

⚙️ Управление Окружением Разработки (Ручной Режим)

Для стабильной работы во время совместной разработки рекомендуется запускать необходимые фоновые сервисы вручную в отдельных окнах терминала:

Окно 1: Компиляция TypeScript (tsc --watch)
```
bun run build:watch
```
Окно 2: Inngest Dev Server (inngest-cli dev)
```
bun run dev:serve
```
Окно 3: Сервер Приложения (bun run ...)
```
bun run dev:start
```

Перед началом работы: Убедитесь, что все три команды успешно запущены.

🤝 Contributing

Пожалуйста, следуйте Руководству по Коммитам.

📄 Лицензия

MIT

gHashTag/999

🕉️ Проект 999: Армия Автономных НейроКодеров

🕉️ Архитектура Агентов и Правила Проекта

🎯 Текущая Задача

📂 Документация скриптов

🧘‍♂️ Основные Агенты

📜 Общие Правила и Принципы

🕉️ Ритуал TDD с Помощником (scripts/tdd-cycle.sh)

💾 Управление Состоянием (State Management)

📜 Общие Правила и Принципы

⚙️ Управление Окружением Разработки

Хранение типов

Запуск Окружения для Тестирования Агентов (Ручной режим)

Использование PM2 (Альтернатива для долгосрочных процессов)

🏺 Сохранение и Восстановление Конфигурации ("Игла Кощея")

Критически Важные Файлы Конфигурации

Создание Снимка

Восстановление из Снимка

🛠️ Недавние Важные Исправления (Май 2024)

🚀 Восстановление Окружения с Нуля

✅ Статус и Текущие Задачи

🛠️ Технологический Стек

📁 Структура Проекта

📜 Скрипты package.json

🧪 Тестирование

🪵 Логирование

🤖 Архитектура Агентов

⚙️ Управление Окружением Разработки (Ручной Режим)

🤝 Contributing

📄 Лицензия

🕉️ Ритуал TDD с Помощником (`scripts/tdd-cycle.sh`)

📜 Скрипты `package.json`