{"id":28045615,"url":"https://github.com/ghashtag/999","last_synced_at":"2025-08-03T13:06:05.195Z","repository":{"id":289835208,"uuid":"972111949","full_name":"gHashTag/999","owner":"gHashTag","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-10T11:09:56.000Z","size":2562,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-11T18:26:04.651Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gHashTag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T14:53:21.000Z","updated_at":"2025-05-03T15:06:51.000Z","dependencies_parsed_at":"2025-05-11T18:22:09.368Z","dependency_job_id":"7e9b68ab-29f1-411f-8984-59d54f8e5eac","html_url":"https://github.com/gHashTag/999","commit_stats":null,"previous_names":["ghashtag/999"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gHashTag/999","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gHashTag%2F999","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gHashTag%2F999/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gHashTag%2F999/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gHashTag%2F999/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gHashTag","download_url":"https://codeload.github.com/gHashTag/999/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gHashTag%2F999/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268548154,"owners_count":24267806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-11T18:19:13.828Z","updated_at":"2025-08-03T13:06:05.135Z","avatar_url":"https://github.com/gHashTag.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🕉️ Проект 999: Армия Автономных НейроКодеров\n\n# 🕉️ Архитектура Агентов и Правила Проекта\n\n**📍 Важно: Хранилище Правил**\n\n\u003e **Все правила проекта и подробные инструкции для каждого агента хранятся исключительно в директории `.cursor/rules/` в виде файлов `.mdc`. Эта директория – единственный источник истины для Дхармы проекта. `README.mdc` предоставляет высокоуровневый обзор и ссылки на эти файлы.**\n\n---\n\nЭтот документ описывает высокоуровневую архитектуру агентов, их роли, зоны ответственности и связь с основными правилами (Дхармой) проекта. Сами инструкции для каждого агента находятся в соответствующих `AGENT_*.mdc` файлах.\n\n## 🎯 Текущая Задача\n\nДля понимания текущей цели и этапа работ смотри: [`current_task.mdc`](mdc:current_task.mdc).\n\n## 📂 Документация скриптов\n\nПодробная документация по скриптам проекта доступна в файле [`scripts/README.md`](scripts/README.md).\n\n## 🧘‍♂️ Основные Агенты\n\n## 📜 Общие Правила и Принципы\n\nПомимо специфичных инструкций для агентов, существуют общие правила, которым должны следовать все (включая Гуру и будущих наблюдателей):\n\n- **TDD:** Неукоснительное следование циклу \"Красный -\u003e Зеленый -\u003e Рефакторинг\".\n- **Автономность:** Агенты стремятся решать задачи самостоятельно, обращаясь к Гуру только при необходимости.\n- **Стиль и Паттерны:** Следование единому стилю кода и использование существующих паттернов.\n- **Тестирование и Отладка:** Используй команду `bun test` и следуй ритуалу, описанному в @`testing-workflow.mdc`.\n- **Git Workflow:** Работа через feature-ветки и Pull Request'ы.\n\nЭти принципы были интегрированы в инструкции соответствующих агентов.\n\n## 🕉️ Ритуал TDD с Помощником (`scripts/tdd-cycle.sh`)\n\n**Проблема:** При ручном выполнении TDD-цикла легко пропустить важные шаги, такие как проверка типов (`tsc`) перед тестами или забыть запустить тесты после рефакторинга. Это приводит к накоплению ошибок, \"сломанным\" коммитам и болезненным регрессиям, когда новое изменение ломает старую функциональность. Время тратится на отладку проблем, которых можно было избежать.\n\n**Решение (Дхарма):** Чтобы обеспечить чистоту кода, предотвратить регрессии и гарантировать последовательное выполнение всех шагов TDD, **ОБЯЗАТЕЛЬНО** использовать скрипт-помощник `scripts/tdd-cycle.sh` для **КАЖДОГО** цикла разработки, включающего изменение тестового файла.\n\n**Как Использовать:**\n\n1.  Напишите падающий тест (🔴) в соответствующем файле (`src/__tests__/...`).\n2.  Запустите скрипт:\n    ```bash\n    bash scripts/tdd-cycle.sh \u003cпуть_к_вашему_тестовому_файлу\u003e\n    ```\n3.  Следуйте инструкциям скрипта:\n    *   Он проверит типы и убедится, что тест действительно падает (🔴).\n    *   После написания кода реализации он будет проверять типы и запускать тест до тех пор, пока он не пройдет (🟢).\n    *   После этапа рефакторинга он снова проверит типы и убедится, что тест все еще проходит (♻️).\n4.  **Только после** успешного завершения скрипта можно переходить к коммиту и обновлению документации (`current_task.mdc`, `SUCCESS_HISTORY.md`, `REGRESSION_PATTERNS.md`).\n\n**Улучшение Скрипта:** Скрипт можно и нужно улучшать по мере выявления новых краевых случаев или потребностей в автоматизации.\n\n*Ом Шанти. Следуй ритуалу, и код твой будет чист и стабилен.* 🙏\n\n## 💾 Управление Состоянием (State Management)\n\n## 📜 Общие Правила и Принципы\n\n## ⚙️ Управление Окружением Разработки\n\nДля стабильной работы агентов в режиме разработки необходимо запустить несколько фоновых сервисов.\n\n### Хранение типов\n\nВсе файлы с типами (*.d.ts, *type\\*.ts) должны находиться исключительно в директориях `src/types` или `vendor-types`. Это способствует:\n\n- Разделению собственных и вендорных типов\n- Единой точке истины для типов\n- Упрощению навигации\n- Предотвращению циклических зависимостей\n\nДля проверки выполните: `./scripts/type-location-checker.sh`\n\n### Запуск Окружения для Тестирования Агентов (Ручной режим)\n\nВместо использования PM2 или сложных скриптов, для стабильной работы во время совместной разработки с AI-ассистентом рекомендуется запускать необходимые фоновые сервисы вручную в отдельных окнах терминала **с использованием `bun`**:\n\n1.  **Окно 1: Компиляция TypeScript (Watch Mode)**\n\n    ```bash\n    bun run build:watch\n    ```\n\n    - **Назначение:** Запускает `tsc --watch --preserveWatchOutput`. Автоматически перекомпилирует `.ts` файлы в `dist/` при их изменении.\n\n2.  **Окно 2: Inngest Dev Server**\n\n    ```bash\n    bun run dev:serve\n    ```\n\n    - **Назначение:** Запускает `inngest-cli dev`. Слушает события на `http://localhost:8288`, находит и запускает функции Inngest из работающего приложения (подключаясь к нему по URL, указанному в команде, обычно `http://localhost:8484/api/inngest`).\n\n3.  **Окно 3: Сервер Приложения**\n    ```bash\n    bun run dev:start\n    ```\n    - **Назначение:** Запускает основной сервер приложения, который обслуживает API для Inngest (`/api/inngest`) и выполняет код функций/агентов. Пытается использовать порт 8484.\n\n**Перед началом работы с AI:** Убедитесь, что все три команды успешно запущены в отдельных окнах и работают без ошибок.\n\n### Использование PM2 (Альтернатива для долгосрочных процессов)\n\nЕсли требуется более надежное управление фоновыми процессами, можно использовать `pm2`.\n\n1.  **Установка (если не установлен):**\n    ```bash\n    npm install -g pm2\n    ```\n2.  **Первый Запуск / Перезапуск:**\n    Остановите все текущие процессы (`pm2 delete all`) и запустите необходимые **с использованием `bun`**:\n\n    ```bash\n    # Компилятор TypeScript в режиме наблюдения\n    pm2 start bun --name tsc-watch -- run build:watch\n\n    # Inngest Dev Server (требуется для локальной разработки Inngest)\n    pm2 start bun --name inngest-dev -- run dev:serve\n\n    # Основное приложение (Сервер приложения)\n    pm2 start bun --name app-server -- run dev:start\n    ```\n\n3.  **Проверка Статуса:**\n    ```bash\n    pm2 list\n    ```\n4.  **Просмотр Логов:**\n    ```bash\n    pm2 logs \u003cимя_процесса\u003e\n    pm2 logs # Показать логи всех процессов\n    ```\n5.  **Сохранение/Восстановление:**\n    ```bash\n    pm2 save\n    pm2 resurrect\n    ```\n6.  **Полная Остановка:**\n    ```bash\n    pm2 delete all\n    ```\n\n---\n\n## 🏺 Сохранение и Восстановление Конфигурации (\"Игла Кощея\")\n\nЧтобы избежать повторения долгих отладок, связанных с конфигурацией среды, мы используем систему снимков ключевых файлов.\n\n### Критически Важные Файлы Конфигурации\n\nСледующие файлы считаются критически важными для консистентности окружения и включены в снимки:\n\n- `package.json`: Определяет зависимости проекта и скрипты.\n- `bun.lockb`: Фиксирует точные версии установленных зависимостей (аналог `pnpm-lock.yaml`).\n- `tsconfig.json`: Конфигурация компилятора TypeScript.\n- `(vite.config.ts удален)`: Ранее использовался для Vite/Vitest, теперь конфигурация тестов управляется Bun.\n- `.npmrc`: Может содержать настройки для `bun`, хотя часто не требуется. Ранее использовался для `pnpm` с `node-linker=hoisted`.\n\n### Создание Снимка\n\nДля сохранения текущей стабильной конфигурации используйте скрипт:\n\n```bash\nbash scripts/config/save-snapshot.sh\n```\n\nЭто создаст директорию `snapshots/snapshot-YYYY-MM-DD_HH-MM-SS`, содержащую копии критически важных файлов.\n\n### Восстановление из Снимка\n\nЕсли конфигурация была нарушена или вы настраиваете проект заново, вы можете восстановить последнюю известную стабильную конфигурацию:\n\n1.  **Найдите нужный снимок:** Посмотрите директории в `snapshots/`.\n2.  **Запустите скрипт восстановления**, указав путь к директории снимка:\n\n    ```bash\n    # Замените \u003cимя_директории_снимка\u003e на актуальное\n    bash scripts/config/restore-snapshot.sh snapshots/\u003cимя_директории_снимка\u003e\n    ```\n\n3.  **Переустановите зависимости:** После восстановления файлов **обязательно** выполните:\n    ```bash\n    bun install\n    ```\n\n---\n\n## 🛠️ Недавние Важные Исправления (Май 2024)\n\nДля контекста и предотвращения повторения ошибок:\n\n- **Проблема с `zod`:** Ошибки TypeScript \"Cannot find module 'zod'\" были решены путем перехода на `bun`. Механизм установки зависимостей `bun` устранил эту проблему.\n- **Ошибка Типов Агентов:** Ошибка `TS2352` в `src/inngest/logic/dependencyUtils.ts` была временно устранена явным приведением типов через `as unknown as Agent\u003cTddNetworkState\u003e`. **Требует рефакторинга:** функции `create*Agent` должны быть параметризованы типом состояния (`TddNetworkState`) для корректной типизации.\n- **Переход на `bun`:** Проект полностью переведен с `pnpm` и `Vitest` на `bun` для управления зависимостями, запуска скриптов и выполнения тестов (`bun test`). Файлы конфигурации `vite.config.ts`, `vitest.config.ts`, `vitest.config.e2e.ts` были удалены.\n\n---\n\n## 🚀 Восстановление Окружения с Нуля\n\n1.  **Клонируйте репозиторий:**\n    ```bash\n    git clone https://github.com/gHashTag/999.git\n    cd 999\n    ```\n2.  **Установить зависимости:**\n    ```bash\n    bun install\n    ```\n3.  **Настроить окружение:**\n    *   Скопировать `.env.example` в `.env`.\n    *   Заполнить `.env` необходимыми ключами API (DeepSeek, E2B, Inngest).\n4.  **Запустить фоновые сервисы (в отдельных терминалах):**\n    ```bash\n    # Окно 1: Компиляция TypeScript\n    bun run build:watch\n    # Окно 2: Inngest Dev Server\n    bun run dev:serve\n    # Окно 3: Сервер Приложения\n    bun run dev:start\n    ```\n5.  **Отправить тестовое событие Inngest:**\n    ```bash\n    node scripts/send-test-event.mjs \"Create a file hello.txt with content Hello World\"\n    # Или:\n    # curl -X POST http://localhost:8288/e/\u003cYOUR_INNGEST_EVENT_KEY\u003e -d '{\"name\":\"coding-agent/run\", \"data\":{\"input\":\"Your task here\"}}'\n    ```\n6.  **Наблюдать за логами:**\n    ```bash\n    tail -f node-app.log | bun run scripts/pretty-logs.mjs\n    # Или\n    tail -f inngest-cli.log\n    ```\n\n## ✅ Статус и Текущие Задачи\n\nСостояние проекта, текущие задачи и roadmap отслеживаются в файле:\n[`.cursor/rules/current_task.mdc`](./.cursor/rules/current_task.mdc)\n\n## 🛠️ Технологический Стек\n\n*   **Среда выполнения:** Bun\n*   **Язык:** TypeScript\n*   **Оркестрация задач:** Inngest\n*   **Оркестрация агентов:** AgentKit (`@inngest/agent-kit`)\n*   **Тестирование:** Bun Test (`bun test`)\n*   **Качество кода:** ESLint, Prettier\n*   **Форматирование логов:** `pino-pretty`\n*   **Модель ИИ:** DeepSeek Coder (или другая, настраивается через `.env`)\n*   **Песочница (опционально):** E2B Sandbox (`@e2b/sdk`)\n\n## 📁 Структура Проекта\n\n```\n├── .cursor/         # Конфигурация и правила для Cursor AI\n│   └── rules/       # Правила и контекст для AI (Дхарма Проекта)\n├── .husky/          # Git хуки (для pre-commit проверок)\n├── artifacts/       # Артефакты выполнения (логи, файлы из песочницы)\n├── coverage/        # Отчеты о покрытии кода тестами (удалено, Bun не генерирует html по умолчанию)\n├── html/            # Отчеты Bun Test (если настроено)\n├── node_modules/    # Зависимости\n├── scripts/         # Вспомогательные скрипты (сборка, тесты, деплой...)\n├── src/\n│   ├── adapters/    # Адаптеры для внешних сервисов (MCP, ...)\n│   ├── agents/      # Логика отдельных агентов (Coder, Critic, ...)\n│   ├── cli/         # Компоненты для CLI (open-codex-cli)\n│   ├── definitions/ # Определение агентов и инструментов для AgentKit\n│   ├── inngest/     # Функции и логика Inngest\n│   ├── mocks/       # Моки для MSW (тестирование API)\n│   ├── network/     # Логика сети агентов AgentKit (роутер, состояние)\n│   ├── server/      # Основной сервер приложения (Fastify)\n│   ├── tools/       # Определения и логика инструментов для агентов\n│   ├── types/       # Глобальные типы TypeScript\n│   ├── utils/       # Общие утилиты (логгер, обработка ошибок)\n│   └── vendor/      # Копии типов из vendor-библиотек (для стабильности)\n├── vendor-types/    # Скопированные `.d.ts` файлы из `node_modules`\n├── .env.example     # Пример файла переменных окружения\n├── .env             # Переменные окружения (в .gitignore)\n├── .eslintignore    # Файлы, игнорируемые ESLint (устарело)\n├── .eslintrc.cjs    # Конфигурация ESLint\n├── .gitignore       # Файлы, игнорируемые Git\n├── .prettierrc.json # Конфигурация Prettier\n├── bun.lockb        # Lock-файл Bun\n├── eslint.config.js # Новая конфигурация ESLint (приоритет над .eslintrc.cjs)\n├── package.json     # Зависимости и скрипты проекта\n├── tsconfig.json    # Конфигурация TypeScript\n└── README.md        # Этот файл\n```\n\n## 📜 Скрипты `package.json`\n\n*   `bun install`: Установка зависимостей.\n*   `bun run build`: Сборка проекта TypeScript (`tsc`).\n*   `bun run build:watch`: Сборка в режиме наблюдения.\n*   `bun run dev:serve`: Запуск Inngest Dev Server (`inngest-cli dev`).\n*   `bun run dev:start`: Запуск основного сервера приложения (`bun run src/server/index.ts`).\n*   `bun run dev`: Запуск `dev:serve` и `dev:start` параллельно с `concurrently`.\n*   `bun run lint`: Проверка кода с помощью ESLint.\n*   `bun run lint:fix`: Исправление ошибок ESLint.\n*   `bun run format`: Форматирование кода с помощью Prettier.\n*   `bun run format:check`: Проверка форматирования.\n*   `bun run typecheck`: Проверка типов TypeScript (`tsc --noEmit`).\n*   `bun run check`: Запуск `lint`, `format` и `typecheck` последовательно.\n*   `bun test`: Запуск всех тестов с помощью Bun Test Runner.\n*   `bun test:watch`: Запуск тестов в режиме наблюдения.\n*   `bun test:ui`: Запуск тестов с UI (может не работать с Bun Test).\n*   `bun test:coverage`: Запуск тестов с генерацией отчета о покрытии.\n*   `bun test:e2e`: Запуск E2E тестов.\n*   `bun run open-codex`: Запуск интерактивного CLI для общения с агентами.\n\n## 🧪 Тестирование\n\nПроект использует **Bun Test Runner** для всех видов тестов.\n\n*   **Unit-тесты:** Проверяют отдельные модули/функции/агенты в изоляции. Находятся в `src/__tests__/...` (например, `src/__tests__/agents/coder.test.ts`).\n*   **Интеграционные тесты:** Проверяют взаимодействие нескольких компонентов (например, адаптер + мок-инструмент). Находятся в `src/__tests__/integration/`, `src/__tests__/adapters/`.\n*   **E2E-тесты:** Проверяют полный цикл работы системы, часто с использованием реальных или частично мокированных внешних зависимостей. Находятся в `src/__tests__/e2e/`.\n*   **Запуск:**\n    *   Все тесты: `bun test`\n    *   Тесты в режиме наблюдения: `bun test --watch`\n    *   Изолированный запуск файла: `bun test \u003cпуть_к_файлу\u003e --isolate`\n    *   Запуск с покрытием: `bun test --coverage` (отчет в консоли)\n\n## 🪵 Логирование\n\nИспользуется `pino` для структурированного логирования. Для удобного чтения логов в консоли используется `pino-pretty` через скрипт `scripts/pretty-logs.mjs`:\n\n```bash\ntail -f node-app.log | bun run scripts/pretty-logs.mjs\n```\n\n## 🤖 Архитектура Агентов\n\nВысокоуровневое описание ролей агентов и принципов их взаимодействия находится в:\n[`.cursor/rules/README.mdc`](./.cursor/rules/README.mdc)\n\nДетальные инструкции для каждого агента находятся в соответствующих файлах `AGENT_*.mdc` в той же директории.\n\n## ⚙️ Управление Окружением Разработки (Ручной Режим)\n\nДля стабильной работы во время совместной разработки рекомендуется запускать необходимые фоновые сервисы вручную в отдельных окнах терминала:\n\n1.  **Окно 1: Компиляция TypeScript (`tsc --watch`)**\n    ```bash\n    bun run build:watch\n    ```\n2.  **Окно 2: Inngest Dev Server (`inngest-cli dev`)**\n    ```bash\n    bun run dev:serve\n    ```\n3.  **Окно 3: Сервер Приложения (`bun run ...`)**\n    ```bash\n    bun run dev:start\n    ```\n\n**Перед началом работы:** Убедитесь, что все три команды успешно запущены.\n\n## 🤝 Contributing\n\nПожалуйста, следуйте [Руководству по Коммитам](COMMIT_GUIDE.md).\n\n## 📄 Лицензия\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghashtag%2F999","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghashtag%2F999","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghashtag%2F999/lists"}