Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ghashtag/999


https://github.com/ghashtag/999

Last synced: 14 days ago
JSON representation

Awesome Lists containing this project

README 

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



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



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



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



---



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



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



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



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



Подробная документация по скриптам проекта доступна в файле [`scripts/README.md`](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` для **КАЖДОГО** цикла разработки, включающего изменение тестового файла.



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



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

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

    ```bash

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

    ```

3.  Следуйте инструкциям скрипта:

    *   Он проверит типы и убедится, что тест действительно падает (🔴).

    *   После написания кода реализации он будет проверять типы и запускать тест до тех пор, пока он не пройдет (🟢).

    *   После этапа рефакторинга он снова проверит типы и убедится, что тест все еще проходит (♻️).

4.  **Только после** успешного завершения скрипта можно переходить к коммиту и обновлению документации (`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.  **Окно 1: Компиляция TypeScript (Watch Mode)**



    ```bash

    bun run build:watch

    ```



    - **Назначение:** Запускает `tsc --watch --preserveWatchOutput`. Автоматически перекомпилирует `.ts` файлы в `dist/` при их изменении.



2.  **Окно 2: Inngest Dev Server**



    ```bash

    bun run dev:serve

    ```



    - **Назначение:** Запускает `inngest-cli dev`. Слушает события на `http://localhost:8288`, находит и запускает функции Inngest из работающего приложения (подключаясь к нему по URL, указанному в команде, обычно `http://localhost:8484/api/inngest`).



3.  **Окно 3: Сервер Приложения**

    ```bash

    bun run dev:start

    ```

    - **Назначение:** Запускает основной сервер приложения, который обслуживает API для Inngest (`/api/inngest`) и выполняет код функций/агентов. Пытается использовать порт 8484.



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



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



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



1.  **Установка (если не установлен):**

    ```bash

    npm install -g pm2

    ```

2.  **Первый Запуск / Перезапуск:**

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



    ```bash

    # Компилятор 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

    ```



3.  **Проверка Статуса:**

    ```bash

    pm2 list

    ```

4.  **Просмотр Логов:**

    ```bash

    pm2 logs <имя_процесса>

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

    ```

5.  **Сохранение/Восстановление:**

    ```bash

    pm2 save

    pm2 resurrect

    ```

6.  **Полная Остановка:**

    ```bash

    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

bash scripts/config/save-snapshot.sh

```



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



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



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



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

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



    ```bash

    # Замените <имя_директории_снимка> на актуальное

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

    ```



3.  **Переустановите зависимости:** После восстановления файлов **обязательно** выполните:

    ```bash

    bun install

    ```



---



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



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



- **Проблема с `zod`:** Ошибки TypeScript "Cannot find module 'zod'" были решены путем перехода на `bun`. Механизм установки зависимостей `bun` устранил эту проблему.

- **Ошибка Типов Агентов:** Ошибка `TS2352` в `src/inngest/logic/dependencyUtils.ts` была временно устранена явным приведением типов через `as unknown as Agent`. **Требует рефакторинга:** функции `create*Agent` должны быть параметризованы типом состояния (`TddNetworkState`) для корректной типизации.

- **Переход на `bun`:** Проект полностью переведен с `pnpm` и `Vitest` на `bun` для управления зависимостями, запуска скриптов и выполнения тестов (`bun test`). Файлы конфигурации `vite.config.ts`, `vitest.config.ts`, `vitest.config.e2e.ts` были удалены.



---



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



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

    ```bash

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

    cd 999

    ```

2.  **Установить зависимости:**

    ```bash

    bun install

    ```

3.  **Настроить окружение:**

    *   Скопировать `.env.example` в `.env`.

    *   Заполнить `.env` необходимыми ключами API (DeepSeek, E2B, Inngest).

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

    ```bash

    # Окно 1: Компиляция TypeScript

    bun run build:watch

    # Окно 2: Inngest Dev Server

    bun run dev:serve

    # Окно 3: Сервер Приложения

    bun run dev:start

    ```

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

    ```bash

    node scripts/send-test-event.mjs "Create a file hello.txt with content Hello World"

    # Или:

    # curl -X POST http://localhost:8288/e/ -d '{"name":"coding-agent/run", "data":{"input":"Your task here"}}'

    ```

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

    ```bash

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

    # Или

    tail -f inngest-cli.log

    ```



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



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

[`.cursor/rules/current_task.mdc`](./.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`:



```bash

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

```



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



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

[`.cursor/rules/README.mdc`](./.cursor/rules/README.mdc)



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



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



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



1.  **Окно 1: Компиляция TypeScript (`tsc --watch`)**

    ```bash

    bun run build:watch

    ```

2.  **Окно 2: Inngest Dev Server (`inngest-cli dev`)**

    ```bash

    bun run dev:serve

    ```

3.  **Окно 3: Сервер Приложения (`bun run ...`)**

    ```bash

    bun run dev:start

    ```



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



## 🤝 Contributing



Пожалуйста, следуйте [Руководству по Коммитам](COMMIT_GUIDE.md).



## 📄 Лицензия



[MIT](./LICENSE)