From f3aad7b14da798a55e0b4f3e760d0d879beb835a Mon Sep 17 00:00:00 2001 From: Vladyslav Tezyk Date: Wed, 12 Aug 2026 09:58:21 +0200 Subject: [PATCH] docs(uk-UA): sync translation with current v2.2.0 README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rebase Ukrainian README structure onto the current English source (previously based on v2.0.0/v2.1) - Preserve existing translated prose for unchanged sections - Translate newly added sections: Plan Canvas, self-host Kimi with Itô compute, expanded security/hooks guidance, and the upcoming 2.2 guided setup notice --- docs/uk-UA/README.md | 2760 +++++++++++++++++++++++++----------------- 1 file changed, 1665 insertions(+), 1095 deletions(-) diff --git a/docs/uk-UA/README.md b/docs/uk-UA/README.md index 73fdc1e8a..49987f863 100644 --- a/docs/uk-UA/README.md +++ b/docs/uk-UA/README.md @@ -1,113 +1,112 @@ -**Мова:** [English](../../README.md) | [Português (Brasil)](../pt-BR/README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](../ko-KR/README.md) | [Türkçe](../tr/README.md) | [Русский](../ru/README.md) | [Tiếng Việt](../vi-VN/README.md) | [ไทย](../th/README.md) | [Deutsch](../de-DE/README.md) | [Español](../es/README.md) | [**Українська**](../uk-UA/README.md) +

+ ECC - операційна система для агентних оболонок +

-![ECC — операційна система для агентних оболонок](../../assets/hero.png) +

+ Мова: + English | + Português (Brasil) | + 简体中文 | + 繁體中文 | + 日本語 | + 한국어 | + Türkçe | + Русский | + Tiếng Việt | + ไทย | + Deutsch | + Español | + Українська +

-[![Discord](https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Join%20the%20Discord&color=5865F2)](https://discord.gg/36yGMHGFbR) -[![Website](https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white)](https://ecc.tools) -[![GitHub App](https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white)](https://github.com/apps/ecc-tools) -[![Guides](https://img.shields.io/badge/Guides-Start%20here-1f6feb?logo=readme&logoColor=white)](#посібники) +

+ Discord + Website + GitHub App + MIT license +

-[![Stars](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fstars&style=flat)](https://github.com/affaan-m/ECC/stargazers) -[![Forks](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fforks&style=flat)](https://github.com/affaan-m/ECC/network/members) -[![Contributors](https://img.shields.io/github/contributors/affaan-m/ECC?style=flat)](https://github.com/affaan-m/ECC/graphs/contributors) -[![npm ecc-universal](https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-universal) -[![npm ecc-agentshield](https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-agentshield) -[![GitHub App Install](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github)](https://github.com/marketplace/ecc-tools) -[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE) -![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white) -![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white) -![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white) -![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white) -![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white) -![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white) -![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white) +

+ Stars + Forks + Contributors + GitHub App installs +

+ +

+ ecc-universal npm downloads + ecc-agentshield npm downloads +

+ +

+ Shell + TypeScript + Python + Go + Java + Perl + Markdown +

> [!WARNING] > **Лише офіційні джерела.** Встановлюйте ECC виключно з перевірених каналів: репозиторій GitHub [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC), пакети npm [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) та [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield), [GitHub App](https://github.com/apps/ecc-tools), ідентифікатор плагіна `ecc@ecc`, та вебсайт проєкту [ecc.tools](https://ecc.tools). Сторонні перезавантаження та неофіційні дзеркала не підтримуються і не перевіряються проєктом та можуть містити шкідливе програмне забезпечення. -**211,9K+ зірок** | **32,5K+ форків** | **230+ учасників** | **12+ мовних екосистем** | **Крос-агентні робочі процеси** +## Встановлення через Claude Code ---- +Виконайте ці команди всередині Claude Code: + +```text +/plugin marketplace add https://github.com/affaan-m/ECC +/plugin install ecc@ecc +``` + +Це встановлює навички, агенти, команди та керовані плагіном хуки ECC. Якщо ви обираєте цей шлях, зупиніться на цьому. Не запускайте також повне ручне встановлення в Claude Code. + +> Керований майстер налаштування пакета з'явиться в `ecc-universal` 2.2.0. Поки npm залишається на 2.1.0, використовуйте нативні команди плагіна Claude вище.
-**Мова / Language / 语言 / 語言 / Dil / Язык / Ngôn ngữ / Idioma** - -[English](../../README.md) | [Português (Brasil)](../pt-BR/README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](../ko-KR/README.md) - | [Türkçe](../tr/README.md) | [Русский](../ru/README.md) | [Tiếng Việt](../vi-VN/README.md) | [ไทย](../th/README.md) | [Deutsch](../de-DE/README.md) | [Español](../es/README.md) | [**Українська**](../uk-UA/README.md) + + + + + + +
+ + ECC Tools
+ ECC Pro + GitHub App +
+ Безкоштовне встановлення · Приватні репозиторії від $19/місце/міс +		 + +
+ Підтримати ECC +
+ Фінансувати open-source проєкт +		 + + Discord
+ Спільнота +
+ Discord · Питання та відповіді · Show and Tell +
---- - -**Нативна оболонка операційної системи для агентної роботи. Побудована на основі реальних мультиоболонкових інженерних процесів.** - -Не просто конфігурації. Повна система: навички, інстинкти, оптимізація пам'яті, безперервне навчання, сканування безпеки та розробка з пріоритетом досліджень. Готові до продакшну агенти, навички, хуки, правила, конфігурації MCP та застарілі командні шими, що розвивалися протягом 10+ місяців інтенсивного щоденного використання при створенні реальних продуктів. - -Працює на **Codex**, **Claude Code**, **Cursor**, **OpenCode**, **Gemini**, **Zed**, **GitHub Copilot** та інших оболонках агентів ШІ. - -ECC v2.0.0 додає публічну історію оператора Hermes поверх повторно використовуваного шару: почніть з [посібника з налаштування Hermes](../../docs/HERMES-SETUP.md), потім перегляньте [примітки до версії 2.0.0](../../docs/releases/2.0.0/release-notes.md) та [крос-агентну архітектуру](../../docs/architecture/cross-harness.md). - ---- - - - - - - - - -
- - ⚡ ECC Pro
- Приватні репо · GitHub App · $19/місць/міс - -		 - - ❤️ Спонсор
- Підтримати OSS · Від $5/міс - -		 - - 💬 Спільнота -
- Обговорення · Питання та відповіді · Демонстрація - -		 - - 🤖 GitHub App
- Встановлення · Аудит PR · Безкоштовний рівень - -
- -**OSS залишається безкоштовним.** Цей репозиторій ліцензований за MIT назавжди. ECC Pro — розміщений GitHub App для приватних репозиторіїв. Спонсори та Pro-підписники фінансують роботу — саме тому один розробник щотижня випускає оновлення для 7 оболонок. +**OSS залишається безкоштовним.** Цей репозиторій ліцензований за MIT назавжди. ECC Pro — розміщений GitHub App для приватних репозиторіїв. Спонсори та Pro-підписники фінансують роботу. Саме тому один розробник щотижня випускає оновлення для 7 оболонок.
-Бізнес-спонсори +Партнери та спонсори - - - - - - -
- - CodeRabbit logo
- CodeRabbit - -		 - - Greptile logo
- Greptile - -		 - - Atlas Cloud logo
- Atlas Cloud - -
+

+ CodeRabbit    + Greptile    + Atlas Cloud    + Moonshot AI - Kimi    + Itô Markets +

Спонсори спільноти: Mike Morgan · @jasonwu513 · @1anter · @massimotodaro · @meadmccabe @@ -115,649 +114,77 @@ ECC v2.0.0 додає публічну історію оператора Hermes
---- +

Перейти до встановлення ↓

-## Посібники +# ECC -Цей репозиторій містить лише вихідний код. Посібники пояснюють усе. +Ваш агент може писати код, але ECC надає йому скоординовану інженерну систему та набір інструментів: він планує перед тим, як будувати, перевіряє зміни тестами, переглядає власну роботу зі свіжого контексту, запам'ятовує важливе та перетворює повторювані перемоги на навички та процеси для повторного використання. - - - - - -
- -Короткий посібник з ECC
-Короткий посібник - -
Налаштування, основи, філософія. Читайте спочатку. (нитка) -		 - -Розширений посібник з ECC
-Розширений посібник - -
Оптимізація токенів, збереження пам'яті, оцінки, паралелізація. (нитка) -
- -
- -Короткий посібник з усього, що стосується безпеки агентів
-Посібник з безпеки - -
Вектори атак, пісочниця, санітизація, CVE, AgentShield. (нитка) -
- -| Тема | Що ви дізнаєтесь | -|-------|-------------------| -| Оптимізація токенів | Вибір моделі, скорочення системного промпту, фонові процеси | -| Збереження пам'яті | Хуки, що автоматично зберігають/завантажують контекст між сесіями | -| Безперервне навчання | Автовитягування патернів із сесій у навички для повторного використання | -| Петлі верифікації | Контрольні точки проти безперервних оцінок, типи оцінювачів, метрики pass@k | -| Паралелізація | Git worktrees, каскадний метод, коли масштабувати інстанції | -| Оркестрація підагентів | Проблема контексту, патерн ітеративного отримання | - ---- - -## Що нового - -### v2.0.0 — Операційна система агентних оболонок (черв. 2026) - -Стабільний випуск лінійки 2.0: 261 навичка, субстрат площини управління (адаптери сесій + інвентаризація MCP), служба життєвого циклу worktree, родина оркестраторів `orch-*`, та запуск [спільноти ECC Discord](https://discord.gg/36yGMHGFbR). Повні примітки: [docs/releases/2.0.0/release-notes.md](../../docs/releases/2.0.0/release-notes.md). - -### v2.0.0-rc.1 — Оновлення поверхні, оператори та ECC 2.0 Alpha (квіт. 2026) - -- **GUI панелі керування** — Нова настільна програма на основі Tkinter (`ecc_dashboard.py` або `npm run dashboard`) з перемикачем темної/світлої теми, налаштуванням шрифту та логотипом проєкту у заголовку та панелі задач. -- **Публічна поверхня синхронізована з живим репозиторієм** — метадані, кількість у каталозі, маніфести плагінів та документація зі встановлення тепер відповідають фактичній OSS-поверхні: 66 агентів, 268 навичок та 84 застарілих командних шими. -- **Розширення операторних і вихідних процесів** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops` та `workspace-surface-audit` доповнюють операторну гілку. -- **Медіа та інструменти запуску** — `manim-video`, `remotion-video-creation` та вдосконалені поверхні публікації в соцмережах роблять технічні роз'яснення та контент для запуску частиною тієї ж системи. -- **Зростання фреймворків і продуктових поверхонь** — `nestjs-patterns`, більш насичені поверхні встановлення Codex/OpenCode та розширена крос-оболонкова упаковка роблять репозиторій придатним для використання не лише в Claude Code. -- **Пакет навичок Itô для ринків прогнозів** — `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner`, `ito-data-atlas-agent`, `prediction-market-oracle-research` та `prediction-market-risk-review` додають публічні, неконсультативні ринкові процеси, залишаючи живий доступ до API Itô окремим від білінгу ECC Tools. -- **Пакет навичок оптимізації** — `parallel-execution-optimizer`, `benchmark-optimization-loop`, `data-throughput-accelerator`, `latency-critical-systems` та `recursive-decision-ledger` перетворюють повторювані запити про швидкість/рекурсію на обмежені процеси тестування продуктивності, пропускної здатності та журналу рішень. -- **ECC 2.0 alpha у дереві** — прототип на Rust у `ecc2/` тепер збирається локально та надає команди `dashboard`, `start`, `sessions`, `status`, `stop`, `resume` та `daemon`. Використовується як альфа-версія, але ще не є загальним випуском. -- **Знімки статусу оператора** — `ecc status --markdown --write status.md` перетворює локальне сховище стану на портативне передавання, яке охоплює готовність, активні сесії, стан виконання навичок, стан встановлення, очікувані події управління та пов'язані робочі елементи з Linear/GitHub. Використовуйте `ecc work-items upsert ...` для ручних записів та `ecc status --exit-code` для автоматичного завершення з помилкою. -- **Зміцнення екосистеми** — AgentShield, контроль витрат ECC Tools, робота з білінг-порталом та оновлення вебсайту продовжують поставлятись разом з основним плагіном. - -### v1.9.0 — Вибіркове встановлення та розширення мовної підтримки (бер. 2026) - -- **Архітектура вибіркового встановлення** — Конвеєр встановлення на основі маніфестів з `install-plan.js` та `install-apply.js` для цільового встановлення компонентів. Сховище стану відстежує встановлене та підтримує інкрементальні оновлення. -- **6 нових агентів** — `typescript-reviewer`, `pytorch-build-resolver`, `java-build-resolver`, `java-reviewer`, `kotlin-reviewer`, `kotlin-build-resolver` розширюють мовне покриття до 10 мов. -- **Нові навички** — `pytorch-patterns` для процесів глибокого навчання, `documentation-lookup` для дослідження API-документації, `bun-runtime` та `nextjs-turbopack` для сучасних JS-інструментальних ланцюжків, плюс 8 навичок для операційних доменів та `mcp-server-patterns`. -- **Інфраструктура сесій та стану** — Сховище стану SQLite з CLI запитів, адаптери сесій для структурованого запису, фундамент для саморозвиваючих навичок. -- **Переробка оркестрації** — Оцінка аудиту оболонок зроблена детермінованою, статус оркестрації та сумісність запускачів вдосконалені, захист від циклів спостерігача з 5-шаровою охороною. -- **Надійність спостерігача** — Виправлення вибуху пам'яті з обмеженням та вибіркою хвоста, виправлення доступу до пісочниці, логіка відкладеного запуску та захист від повторного входу. -- **12 мовних екосистем** — Нові правила для Java, PHP, Perl, Kotlin/Android/KMP, C++ та Rust доповнюють існуючі TypeScript, Python, Go та загальні правила. -- **Внески спільноти** — Переклади корейською та китайською, оптимізація biome hook, навички відеообробки, операційні навички, PowerShell-інсталятор, підтримка Antigravity IDE. -- **Зміцнення CI** — 19 виправлень помилок тестів, примусовий підрахунок каталогу, валідація маніфесту встановлення та повний набір тестів зелений. - -### v1.8.0 — Система продуктивності агентних оболонок (бер. 2026) - -- **Першочерговий випуск для оболонок** — ECC тепер явно позиціонується як система підвищення продуктивності агентних оболонок, а не просто пакет конфігурацій. -- **Переробка надійності хуків** — Резервний шлях SessionStart, підсумки сесій на фазі Stop та хуки на основі скриптів замість ненадійних однолінійників. -- **Елементи управління виконанням хуків** — `ECC_HOOK_PROFILE=minimal|standard|strict` та `ECC_DISABLED_HOOKS=...` для управління під час виконання без редагування файлів хуків. -- **Нові команди оболонки** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`. -- **NanoClaw v2** — маршрутизація моделей, гаряче завантаження навичок, розгалуження/пошук/експорт/компакшн/метрики сесій. -- **Крос-оболонковий паритет** — Поведінка вирівняна між Claude Code, Cursor, OpenCode та Codex. -- **997 внутрішніх тестів пройдено** — повний набір тестів зелений після рефакторингу хуків/виконання та оновлень сумісності. - -### v1.7.0 — Кросплатформне розширення та конструктор презентацій (лют. 2026) - -- **Підтримка Codex app + CLI** — Пряма підтримка Codex на основі `AGENTS.md`, цільове встановлення та документація Codex. -- **Навичка `frontend-slides`** — Конструктор HTML-презентацій без залежностей з керівництвом щодо конвертації PPTX та строгими правилами відповідності вьюпорту. -- **5 нових загальних бізнес/контент-навичок** — `article-writing`, `content-engine`, `market-research`, `investor-materials`, `investor-outreach`. -- **Ширше охоплення інструментів** — Підтримка Cursor, Codex та OpenCode вдосконалена для чистого постачання з одного репозиторію через всі основні оболонки. -- **992 внутрішні тести** — Розширена валідація та регресійне покриття для плагіна, хуків, навичок та упаковки. - -### v1.6.0 — Codex CLI, AgentShield та Marketplace (лют. 2026) - -- **Підтримка Codex CLI** — Нова команда `/codex-setup` генерує `codex.md` для сумісності з OpenAI Codex CLI. -- **7 нових навичок** — `search-first`, `swift-actor-persistence`, `swift-protocol-di-testing`, `regex-vs-llm-structured-text`, `content-hash-cache-pattern`, `cost-aware-llm-pipeline`, `skill-stocktake`. -- **Інтеграція AgentShield** — Навичка `/security-scan` запускає AgentShield безпосередньо з Claude Code; 1282 тести, 102 правила. -- **GitHub Marketplace** — ECC Tools GitHub App доступний на [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) з безкоштовним/pro/enterprise рівнями. -- **30+ злитих PR від спільноти** — Внески від 30 учасників на 6 мовах. -- **978 внутрішніх тестів** — Розширений набір валідації для агентів, навичок, команд, хуків та правил. - -### v1.4.1 — Виправлення помилок (лют. 2026) - -- **Виправлено втрату вмісту при імпорті інстинктів** — `parse_instinct_file()` мовчки відкидав увесь вміст після frontmatter (розділи Action, Evidence, Examples) під час `/instinct-import`. ([#148](https://github.com/affaan-m/ECC/issues/148), [#161](https://github.com/affaan-m/ECC/pull/161)) - -### v1.4.0 — Мультимовні правила, майстер встановлення та PM2 (лют. 2026) - -- **Інтерактивний майстер встановлення** — Нова навичка `configure-ecc` забезпечує покрокове налаштування з виявленням злиття/перезапису. -- **PM2 та мультиагентна оркестрація** — 6 нових команд (`/pm2`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/multi-workflow`) для управління складними мультисервісними процесами. -- **Архітектура мультимовних правил** — Правила реструктуровані з плоских файлів у директорії `common/` + `typescript/` + `python/` + `golang/`. Встановлюйте лише потрібні мови. -- **Переклад китайською (zh-CN)** — Повний переклад всіх агентів, команд, навичок та правил (80+ файлів). -- **Підтримка GitHub Sponsors** — Спонсоруйте проєкт через GitHub Sponsors. -- **Покращений CONTRIBUTING.md** — Детальні шаблони PR для кожного типу внеску. - -### v1.3.0 — Підтримка плагінів OpenCode (лют. 2026) - -- **Повна інтеграція OpenCode** — 12 агентів, 24 команди, 16 навичок з підтримкою хуків через систему плагінів OpenCode (20+ типів подій). -- **3 нативних власних інструменти** — run-tests, check-coverage, security-audit. -- **LLM-документація** — `llms.txt` для повної документації OpenCode для LLM. - -### v1.2.0 — Уніфіковані команди та навички (лют. 2026) - -- **Підтримка Python/Django** — Навички Django patterns, security, TDD та verification. -- **Навички Java Spring Boot** — Patterns, security, TDD та verification для Spring Boot. -- **Управління сесіями** — Команда `/sessions` для історії сесій. -- **Безперервне навчання v2** — Навчання на основі інстинктів з оцінюванням довіри, імпортом/експортом, еволюцією. - -Повний журнал змін у [Releases](https://github.com/affaan-m/ECC/releases). - ---- - -## Швидкий старт - -Почніть за менш ніж 2 хвилини: - -### Виберіть один шлях - -Більшість користувачів Claude Code повинні використовувати рівно один шлях встановлення: - -- **Рекомендований стандарт:** встановіть плагін Claude Code, потім скопіюйте лише ті папки з правилами, які вам справді потрібні. -- **Використовуйте ручний інсталятор лише якщо** ви хочете більш тонкого контролю, хочете уникнути шляху плагіна, або ваша збірка Claude Code має труднощі з вирішенням запису самостійного marketplace. -- **Не комбінуйте методи встановлення.** Найпоширеніша зламана конфігурація: спочатку `/plugin install`, потім `install.sh --profile full` або `npx ecc-install --profile full`. - -Якщо ви вже застосували кілька методів і виникло дублювання, перейдіть одразу до [Скидання/Видалення ECC](#скидання--видалення-ecc). - -### Шлях з низьким контекстом / без хуків - -Якщо хуки здаються надто глобальними або вам потрібні лише правила, агенти, команди та основні навички ECC, пропустіть плагін та використовуйте мінімальний ручний профіль: - -```bash -./install.sh --profile minimal --target claude +```text +план -> тест -> реалізація -> перегляд -> перевірка -> запам'ятовування -> покращення ``` -```powershell -.\install.ps1 --profile minimal --target claude -# або -npx ecc-install --profile minimal --target claude -``` +Замість того, щоб відтворювати цей процес у кожному промпті, ви встановлюєте його один раз і робите частиною того, як працює ваш агент. -Цей профіль навмисно виключає `hooks-runtime`. +> Оптимізуйте контекстне вікно. Зберігайте все інше. -Якщо вам потрібен звичайний основний профіль, але з вимкненими хуками: +ECC — це MIT-ліцензований open source. Найкраще працює з Claude Code сьогодні, має підтримуваний шлях синхронізації з Codex та надає адаптери з обмеженими можливостями для Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen та інших оболонок. Перегляньте [матрицю статусу підтримки](#підтримка-платформ), перш ніж припускати повний паритет функцій. + +Доступ до 68 агентів, 287 навичок та 94 застарілих командних шимів, а також хуки, правила, пам'ять, безперервне навчання та сканування безпеки AgentShield. Агенти спеціалізовані на плануванні, перегляді, виправленні збірки, безпеці, архітектурі та доменній роботі. + +| Що включено | Кількість | Що це дає | +| ---------------- | ----------: | ------------------------------------------------------------------------------------ | +| Агенти | 68 агентів | Планування, перегляд, виправлення збірки, безпека, архітектура та доменна робота | +| Навички | 287 навичок | TDD, дослідження, безпека, документація, фронтенд, дані, ML, операції та інше | +| Команди | 94 команди | Зручні точки входу, поки ECC переходить на поверхню, орієнтовану на навички | +| Хуки та пам'ять | Час виконання | Примусове виконання, підсумки сесій, безперервне навчання, інстинкти та контроль контексту | +| Правила | Вибірково | Завжди завантажувані стандарти, які ви обираєте за мовою чи проєктом | +| AgentShield | Включено | Сканування промптів, хуків, конфігурації MCP, дозволів, секретів і файлів агентів | + +## Встановлення ECC + +> [!IMPORTANT] +> Керований майстер налаштування пакета з'явиться в `ecc-universal` 2.2.0. Поточний реліз npm, 2.1.0, ще не містить команд керованого налаштування. Використовуйте нативні команди плагіна Claude на початку цього README до публікації 2.2.0. + +### Обирайте лише один шлях (на кожну оболонку) + +Ви можете використовувати ECC з Claude Code, Codex та іншими оболонками одночасно. Для кожної оболонки обирайте один метод встановлення: + +- **Рекомендовано сьогодні для Claude Code:** використовуйте [нативні команди плагіна вище](#встановлення-через-claude-code) +- **З'явиться у релізі 2.2:** кероване налаштування пакета для Claude Code, Codex та Kimi Code; перегляньте попередній перегляд внизу цього розділу встановлення +- **Працює:** плагін Claude Code + нативний плагін Codex +- **Працює:** плагін Claude Code + застарілий потік синхронізації Codex +- **Уникайте:** плагін Claude Code + повне ручне встановлення Claude +- **Уникайте:** синхронізація Codex + плагін маркетплейсу Codex + +**Не накопичуйте методи встановлення.** Встановлення ECC двічі в одну оболонку може продублювати навички, команди, хуки чи конфігурацію; встановлення один раз у кілька оболонок — ні. + +Якщо ви вже наклали кілька встановлень і щось виглядає продубльованим, перейдіть одразу до [Скидання / видалення ECC](#скидання--видалення-ecc). + +**Проблеми зі встановленням?** Відкрийте коротку [форму проблеми встановлення чи виконання](https://github.com/affaan-m/ECC/issues/new?template=install-problem.yml) або запустіть `ecc feedback`. ECC ніколи автоматично не завантажує діагностику. + +### Деталі для Claude Code + +Claude Code володіє цими вбудованими командами, включно з їхніми помилками, коли маркетплейс, плагін чи конфліктуючий рівень уже існує. ECC не може перехопити цей парсер. Якщо будь-яка нативна команда повідомляє про наявне встановлення чи конфлікт рівнів, дочекайтеся керованого налаштування 2.2.0 або вирішіть конфліктуючий рівень плагіна Claude перед повторною спробою; не накладайте ручне встановлення поверх. + +Після встановлення ECC `/ecc:configure-ecc` — це навичка переналаштування в Claude з простором імен. Вона делегує до того ж безпечного потоку налаштування, але доступна лише після встановлення плагіна і не може замінити вбудовану команду `/plugin` Claude Code під час першого встановлення. + +Плагіни Claude Code не можуть розповсюджувати `rules`, тому додавайте лише ті пакети правил, які вам справді потрібні: ```bash -./install.sh --profile core --without baseline:hooks --target claude -``` - -Додайте хуки пізніше лише за потреби примусового виконання під час роботи: - -```bash -./install.sh --target claude --modules hooks-runtime -``` - -### Спочатку знайдіть потрібні компоненти - -Якщо ви не впевнені, який профіль або компонент ECC встановити, запитайте вбудованого консультанта з будь-якого проєкту: - -```bash -npx ecc consult "security reviews" --target claude -``` - -Він повертає відповідні компоненти, пов'язані профілі та команди попереднього перегляду/встановлення. Використовуйте команду попереднього перегляду перед встановленням, якщо хочете перевірити точний план файлів. - -### Крок 1: Встановлення плагіна (рекомендовано) - -> ПРИМІТКА: Плагін зручний, але OSS-інсталятор нижче все ще є найнадійнішим шляхом, якщо ваша збірка Claude Code має труднощі з вирішенням записів самостійного marketplace. - -```bash -# Додати marketplace -/plugin marketplace add https://github.com/affaan-m/ECC - -# Встановити плагін -/plugin install ecc@ecc -``` - -### Примітка щодо іменування та міграції - -ECC має три публічних ідентифікатори, і вони не є взаємозамінними: - -- Вихідний репозиторій GitHub: `affaan-m/ECC` -- Ідентифікатор marketplace/плагіна Claude: `ecc@ecc` -- Пакет npm: `ecc-universal` - -Це навмисно. Встановлення через marketplace/плагін Anthropic прив'язані до канонічного ідентифікатора плагіна, тому ECC використовує `ecc@ecc` для збереження коротких назв інструментів і просторів імен для команд зі слешем. Старі публікації можуть показувати попередній довгий ідентифікатор marketplace — вважайте це лише застарілим псевдонімом. Пакет npm залишився на `ecc-universal`, тому встановлення через npm та marketplace навмисно використовують різні назви. - -### Крок 2: Встановлення правил лише за потреби - -> УВАГА: **Важливо:** Плагіни Claude Code не можуть автоматично розповсюджувати `rules`. -> -> Якщо ви вже встановили ECC через `/plugin install`, **не запускайте `./install.sh --profile full`, `.\install.ps1 --profile full` або `npx ecc-install --profile full` після цього**. Плагін вже завантажує навички, команди та хуки ECC. Запуск повного інсталятора після встановлення плагіна копіює ті ж поверхні в директорії користувача і може створити дублювання навичок та дублювання поведінки під час виконання. -> -> Для встановлення через плагін вручну скопіюйте лише директорії `rules/`, які вам потрібні, до `~/.claude/rules/ecc/`. Почніть з `rules/common` плюс один мовний або фреймворковий пакет, який ви фактично використовуєте. Не копіюйте всі директорії правил, якщо ви явно не хочете весь цей контекст у Claude. -> -> Використовуйте повний інсталятор лише при повністю ручному встановленні ECC замість шляху плагіна. - -```bash -# Спочатку клонуйте репозиторій git clone https://github.com/affaan-m/ECC.git cd ECC - -# Встановіть залежності (виберіть менеджер пакетів) -npm install # або: pnpm install | yarn install | bun install - -# Шлях встановлення через плагін: копіюйте лише правила ECC у просторі імен ECC mkdir -p ~/.claude/rules/ecc cp -R rules/common ~/.claude/rules/ecc/ -cp -R rules/typescript ~/.claude/rules/ecc/ - -# Шлях повного ручного встановлення ECC (використовуйте замість /plugin install) -# ./install.sh --profile full +cp -R rules/typescript ~/.claude/rules/ecc/ # замініть на ваш стек ``` -```powershell -# Windows PowerShell +Почніть з `rules/common` плюс один мовний чи фреймворковий пакет, який ви фактично використовуєте. Якщо ви встановили плагін, не запускайте після цього `./install.sh --profile full`. -# Шлях встановлення через плагін: копіюйте лише правила ECC у просторі імен ECC -New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules/ecc" | Out-Null -Copy-Item -Recurse rules/common "$HOME/.claude/rules/ecc/" -Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/ecc/" +
+Надаєте перевагу settings.json? Додайте маркетплейс декларативно -# Шлях повного ручного встановлення ECC (використовуйте замість /plugin install) -# .\install.ps1 --profile full -# npx ecc-install --profile full -``` - -Для інструкцій з ручного встановлення дивіться README у папці `rules/`. При ручному копіюванні правил копіюйте цілу директорію мови (наприклад `rules/common` або `rules/golang`), а не файли всередині неї, щоб відносні посилання продовжували працювати. - -### Повне ручне встановлення (запасний варіант) - -Використовуйте це лише якщо ви навмисно пропускаєте шлях плагіна: - -```bash -./install.sh --profile full -``` - -```powershell -.\install.ps1 --profile full -# або -npx ecc-install --profile full -``` - -Якщо ви вибрали цей шлях, зупиніться. Не запускайте також `/plugin install`. - -### Скидання / Видалення ECC - -Якщо ECC здається продубльованим, надто нав'язливим або зламаним, не продовжуйте перевстановлювати поверх себе. - -- **Шлях плагіна:** видаліть плагін з Claude Code, потім видаліть конкретні папки правил, які ви вручну скопіювали до `~/.claude/rules/ecc/`. -- **Шлях ручного інсталятора / CLI:** з кореня репозиторію спочатку перегляньте видалення: - -```bash -node scripts/uninstall.js --dry-run -``` - -Потім видаліть файли, керовані ECC: - -```bash -node scripts/uninstall.js -``` - -Також можна використати обгортку lifecycle: - -```bash -node scripts/ecc.js list-installed -node scripts/ecc.js doctor -node scripts/ecc.js repair -node scripts/ecc.js uninstall --dry-run -``` - -ECC видаляє лише файли, записані в його стані встановлення. Він не видалятиме неспоріднені файли, які він не встановлював. - -Якщо ви комбінували методи, очищуйте в такому порядку: - -1. Видаліть встановлення плагіна Claude Code. -2. Запустіть команду видалення ECC з кореня репозиторію для видалення файлів, керованих станом встановлення. -3. Видаліть будь-які додаткові папки правил, скопійовані вручну, які вам більше не потрібні. -4. Перевстановіть один раз, використовуючи єдиний шлях. - -### Крок 3: Почніть використовувати - -```bash -# Навички є основною поверхнею процесів. -# Існуючі назви команд зі слешем продовжують працювати під час міграції з commands/. - -# Встановлення через плагін використовує канонічну форму з простором імен -/ecc:plan "Додати автентифікацію користувача" - -# Ручне встановлення зберігає коротку форму зі слешем: -# /plan "Додати автентифікацію користувача" - -# Перевірте доступні команди -/plugin list ecc@ecc -``` - -**Ось і все!** Тепер у вас є доступ до 67 агентів, 271 навички та 92 застарілих командних шими. - -### Панель керування GUI - -Запустіть настільну панель керування для візуального дослідження компонентів ECC: - -```bash -npm run dashboard -# або -python3 ./ecc_dashboard.py -``` - -**Функції:** -- Вкладки: Агенти, Навички, Команди, Правила, Налаштування -- Перемикач темної/світлої теми -- Налаштування шрифту (сімейство та розмір) -- Логотип проєкту у заголовку та панелі задач -- Пошук і фільтрація по всіх компонентах - -### Мультимодельні команди вимагають додаткового налаштування - -> УВАГА: Команди `multi-*` **не** входять до базового встановлення плагіна/правил. -> -> Для використання `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend` та `/multi-workflow` необхідно також встановити `ccg-workflow`. -> -> Ініціалізуйте його командою `npx ccg-workflow`. -> -> Цей runtime надає зовнішні залежності, яких очікують ці команди, зокрема: -> - `~/.claude/bin/codeagent-wrapper` -> - `~/.claude/.ccg/prompts/*` -> -> Без `ccg-workflow` ці команди `multi-*` не працюватимуть коректно. - ---- - -## Кросплатформна підтримка - -Цей плагін тепер повністю підтримує **Windows, macOS та Linux**, а також тісну інтеграцію з основними IDE (Cursor, Zed, OpenCode, Antigravity) та оболонками CLI. Усі хуки та скрипти переписані на Node.js для максимальної сумісності. - -### Виявлення менеджера пакетів - -Плагін автоматично виявляє ваш бажаний менеджер пакетів (npm, pnpm, yarn або bun) з таким пріоритетом: - -1. **Змінна середовища**: `CLAUDE_PACKAGE_MANAGER` -2. **Конфіг проєкту**: `.claude/package-manager.json` -3. **package.json**: поле `packageManager` -4. **Lock-файл**: Виявлення з package-lock.json, yarn.lock, pnpm-lock.yaml або bun.lockb -5. **Глобальний конфіг**: `~/.claude/package-manager.json` -6. **Запасний варіант**: Перший доступний менеджер пакетів - -Щоб встановити бажаний менеджер пакетів: - -```bash -# Через змінну середовища -export CLAUDE_PACKAGE_MANAGER=pnpm - -# Через глобальний конфіг -node scripts/setup-package-manager.js --global pnpm - -# Через конфіг проєкту -node scripts/setup-package-manager.js --project bun - -# Виявити поточне налаштування -node scripts/setup-package-manager.js --detect -``` - -Або використовуйте команду `/setup-pm` у Claude Code. - -### Елементи управління виконанням хуків - -Використовуйте прапорці виконання для налаштування суворості або тимчасового вимкнення конкретних хуків: - -```bash -# Профіль суворості хуків (стандарт за замовчуванням) -export ECC_HOOK_PROFILE=standard - -# Через кому ідентифікатори хуків для вимкнення -export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" - -# Обмежити додатковий контекст SessionStart (за замовчуванням: 8000 символів) -export ECC_SESSION_START_MAX_CHARS=4000 - -# Повністю вимкнути додатковий контекст SessionStart для конфігурацій з низьким контекстом -export ECC_SESSION_START_CONTEXT=off - -# Вікно збереження session-tmp у днях (за замовчуванням: 30) -export ECC_SESSION_RETENTION_DAYS=14 - -# Зберегти попередження щодо контексту/обсягу/циклів, але пригнічити оцінки витрат API -export ECC_CONTEXT_MONITOR_COST_WARNINGS=off -``` - -Windows PowerShell: - -```powershell -[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User') -[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User') -``` - -### Домашня директорія даних агента (мультиоболонкова ізоляція) - -Хуки збереження пам'яті (підсумки сесій, вивчені навички, псевдоніми сесій, метрики) зберігають дані під єдиним кореневим каталогом даних агента. За замовчуванням це `~/.claude`. При використанні ECC у Claude Code та Cursor на одному комп'ютері, встановіть окремий корінь для Cursor, щоб два середовища не перезаписували файли сесій одне одного: - -```bash -# Кордон лише для Cursor (Claude Code зберігає стандартний ~/.claude) -export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" -``` - -Шляхи, що вирішуються під цим коренем: - -- `$ECC_AGENT_DATA_HOME/session-data/` — підсумки сесій -- `$ECC_AGENT_DATA_HOME/skills/learned/` — вивчені навички з evaluate-session -- `$ECC_AGENT_DATA_HOME/session-aliases.json` — псевдоніми сесій -- `$ECC_AGENT_DATA_HOME/metrics/` — метрики витрат та активності - -Дивіться [affaan-m/ECC#2065](https://github.com/affaan-m/ECC/issues/2065). - ---- - -## Що всередині - -Цей репозиторій є **плагіном Claude Code** — встановіть його безпосередньо або скопіюйте компоненти вручну. - -``` -ECC/ -|-- .claude-plugin/ # Маніфести плагіна та marketplace -| |-- plugin.json # Метадані плагіна та шляхи компонентів -| |-- marketplace.json # Каталог marketplace для /plugin marketplace add -| -|-- agents/ # 67 спеціалізованих підагентів для делегування -| |-- planner.md # Планування реалізації функцій -| |-- architect.md # Рішення щодо системного дизайну -| |-- tdd-guide.md # Розробка через тестування -| |-- code-reviewer.md # Перевірка якості та безпеки -| |-- security-reviewer.md # Аналіз вразливостей -| |-- build-error-resolver.md -| |-- e2e-runner.md # E2E тестування Playwright -| |-- refactor-cleaner.md # Очищення мертвого коду -| |-- doc-updater.md # Синхронізація документації -| |-- docs-lookup.md # Пошук документації/API -| |-- chief-of-staff.md # Триаж комунікацій та чернетки -| |-- loop-operator.md # Виконання автономних циклів -| |-- harness-optimizer.md # Налаштування конфігурації оболонки -| |-- cpp-reviewer.md # Перегляд коду C++ -| |-- cpp-build-resolver.md # Вирішення помилок збирання C++ -| |-- fsharp-reviewer.md # Перегляд функціонального коду F# -| |-- go-reviewer.md # Перегляд коду Go -| |-- go-build-resolver.md # Вирішення помилок збирання Go -| |-- python-reviewer.md # Перегляд коду Python -| |-- database-reviewer.md # Перегляд бази даних/Supabase -| |-- typescript-reviewer.md # Перегляд коду TypeScript/JavaScript -| |-- java-reviewer.md # Перегляд коду Java/Spring Boot -| |-- java-build-resolver.md # Помилки збирання Java/Maven/Gradle -| |-- kotlin-reviewer.md # Перегляд коду Kotlin/Android/KMP -| |-- kotlin-build-resolver.md # Помилки збирання Kotlin/Gradle -| |-- harmonyos-app-resolver.md # Розробка додатків HarmonyOS/ArkTS -| |-- rust-reviewer.md # Перегляд коду Rust -| |-- rust-build-resolver.md # Вирішення помилок збирання Rust -| |-- pytorch-build-resolver.md # Помилки навчання PyTorch/CUDA -| |-- mle-reviewer.md # Перегляд конвеєра ML, оцінок, обслуговування та моніторингу -| -|-- skills/ # Визначення процесів та доменні знання -| |-- coding-standards/ # Найкращі практики мов -| |-- clickhouse-io/ # Аналітика ClickHouse, запити, інженерія даних -| |-- backend-patterns/ # Шаблони API, баз даних, кешування -| |-- frontend-patterns/ # Шаблони React, Next.js -| |-- frontend-slides/ # HTML-слайди та процеси PPTX (НОВИЙ) -| |-- article-writing/ # Довгоформне письмо без загального тону ШІ (НОВИЙ) -| |-- content-engine/ # Мультиплатформний соціальний контент (НОВИЙ) -| |-- market-research/ # Ринкові та конкурентні дослідження (НОВИЙ) -| |-- investor-materials/ # Питч-деки, меморандуми та фінансові моделі (НОВИЙ) -| |-- investor-outreach/ # Персоналізований фандрейзинговий аутріч (НОВИЙ) -| |-- continuous-learning/ # Застарілий патерн v1 для Stop-hook -| |-- continuous-learning-v2/ # Навчання на основі інстинктів з оцінюванням довіри -| |-- iterative-retrieval/ # Прогресивне уточнення контексту для підагентів -| |-- strategic-compact/ # Ручні пропозиції компакшну (Розширений посібник) -| |-- tdd-workflow/ # Методологія TDD -| |-- security-review/ # Контрольний список безпеки -| |-- eval-harness/ # Оцінка петлі верифікації (Розширений посібник) -| |-- verification-loop/ # Безперервна верифікація (Розширений посібник) -| ... (та багато інших) -| -|-- commands/ # Підтримувана сумісність зі слеш-записами; надавайте перевагу skills/ -|-- legacy-command-shims/ # Архів для вилучених шимів -|-- rules/ # Завжди дотримувані правила (копіюйте до ~/.claude/rules/ecc/) -| |-- common/ # Незалежні від мови принципи -| |-- typescript/ # Специфіка TypeScript/JavaScript -| |-- python/ # Специфіка Python -| |-- golang/ # Специфіка Go -| |-- swift/ # Специфіка Swift -| |-- php/ # Специфіка PHP (НОВИЙ) -| |-- arkts/ # Специфіка HarmonyOS / ArkTS -| -|-- hooks/ # Автоматизації на основі тригерів -|-- scripts/ # Кросплатформні скрипти Node.js -|-- tests/ # Набір тестів -|-- contexts/ # Динамічні контексти ін'єкції системного промпту -|-- examples/ # Приклади конфігурацій та сесій -|-- mcp-configs/ # Конфігурації MCP-серверів -|-- ecc_dashboard.py # Настільна GUI-панель (Tkinter) -|-- marketplace.json # Конфігурація самостійного marketplace -``` - ---- - -## Інструменти екосистеми - -### Конструктор навичок - -Два способи генерації навичок Claude Code з вашого репозиторію: - -#### Варіант A: Локальний аналіз (вбудований) - -Використовуйте команду `/skill-create` для локального аналізу без зовнішніх сервісів: - -```bash -/skill-create # Аналізувати поточний репозиторій -/skill-create --instincts # Також генерувати інстинкти для continuous-learning-v2 -``` - -Це аналізує вашу git-історію локально та генерує файли SKILL.md. - -#### Варіант B: GitHub App (розширений) - -Для розширених функцій (10k+ комітів, автоматичні PR, спільний доступ у команді): - -[Встановити ECC Tools GitHub App](https://github.com/apps/ecc-tools) | [ecc.tools](https://ecc.tools) - -```bash -# Коментуйте у будь-якому issue: -/ecc-tools analyze - -# Або запускайте проти репозиторію з розміщеного додатка -``` - -Обидва варіанти створюють: -- **Файли SKILL.md** — Готові до використання навички для активної оболонки -- **Колекції інстинктів** — Для continuous-learning-v2 -- **Витягування патернів** — Навчається з вашої git-історії - -### AgentShield — Аудитор безпеки - -> Створений на Claude Code Hackathon (Cerebral Valley x Anthropic, лют. 2026). 1282 тести, 98% покриття, 102 правила статичного аналізу. - -Скануйте вашу конфігурацію Claude Code на вразливості, помилкові конфігурації та ризики ін'єкцій. - -```bash -# Швидке сканування (без встановлення) -npx ecc-agentshield scan - -# Автовиправлення безпечних проблем -npx ecc-agentshield scan --fix - -# Глибокий аналіз з трьома агентами Opus 4.6 -npx ecc-agentshield scan --opus --stream - -# Генерація безпечної конфігурації з нуля -npx ecc-agentshield init -``` - -**Що сканується:** CLAUDE.md, settings.json, конфіги MCP, хуки, визначення агентів та навички по 5 категоріях — виявлення секретів (14 патернів), аудит дозволів, аналіз ін'єкцій хуків, профілювання ризиків MCP-серверів та перевірка конфігурації агентів. - -**Прапорець `--opus`** запускає три агенти Claude Opus 4.6 у конвеєрі атакуючий/захисник/аудитор. Атакуючий знаходить ланцюжки вразливостей, захисник оцінює захисти, а аудитор синтезує обох у пріоритизовану оцінку ризиків. Адверсарне міркування, а не просто зіставлення патернів. - -**Формати виводу:** Термінал (кольорова градація A-F), JSON (CI-конвеєри), Markdown, HTML. Код виходу 2 при критичних знахідках для воріт збирання. - -Використовуйте `/security-scan` у Claude Code для запуску, або додайте до CI через [GitHub Action](https://github.com/affaan-m/agentshield). - -[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield) - -### Безперервне навчання v2 - -Система навчання на основі інстинктів автоматично вивчає ваші патерни: - -```bash -/instinct-status # Показати вивчені інстинкти з довірою -/instinct-import # Імпортувати інстинкти від інших -/instinct-export # Експортувати ваші інстинкти для поширення -/evolve # Кластеризувати пов'язані інстинкти в навички -``` - -Дивіться `skills/continuous-learning-v2/` для повної документації. -Зберігайте `continuous-learning/` лише якщо вам явно потрібен застарілий потік v1 Stop-hook з вивченими навичками. - ---- - -## Вимоги - -### Версія Claude Code CLI - -**Мінімальна версія: v2.1.0 або новіша** - -Цей плагін вимагає Claude Code CLI v2.1.0+ через зміни в тому, як система плагінів обробляє хуки. - -Перевірте свою версію: -```bash -claude --version -``` - -### Важливо: Поведінка автозавантаження хуків - -> УВАГА: **Для учасників:** НЕ додавайте поле `"hooks"` до `.claude-plugin/plugin.json`. Це забезпечується регресійним тестом. - -Claude Code v2.1+ **автоматично завантажує** `hooks/hooks.json` з будь-якого встановленого плагіна за угодою. Явне оголошення його в `plugin.json` спричиняє помилку виявлення дублікатів: - -``` -Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file -``` - -**Передісторія:** Це спричинило повторювані цикли виправлення/відкату в цьому репозиторії ([#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103)). Поведінка змінювалася між версіями Claude Code, що призводило до плутанини. Тепер у нас є регресійний тест для запобігання повторного введення цього. - ---- - -## Встановлення - -### Варіант 1: Встановлення як плагін (рекомендовано) - -Найпростіший спосіб використання цього репозиторію — встановлення як плагін Claude Code: - -```bash -# Додати цей репозиторій як marketplace -/plugin marketplace add https://github.com/affaan-m/ECC - -# Встановити плагін -/plugin install ecc@ecc -``` - -Або додайте безпосередньо до вашого `~/.claude/settings.json`: +Додайте безпосередньо до вашого `~/.claude/settings.json`: ```json { @@ -775,80 +202,915 @@ Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded fil } ``` -Це надає миттєвий доступ до всіх команд, агентів, навичок та хуків. +Це дає той самий результат, що й дві команди `/plugin` вище. +
-> **Примітка:** Система плагінів Claude Code не підтримує розповсюдження `rules` через плагіни. Вам потрібно встановити правила вручну: -> -> ```bash -> # Спочатку клонуйте репозиторій -> git clone https://github.com/affaan-m/ECC.git -> cd ECC -> -> # Варіант A: Правила рівня користувача (застосовуються до всіх проєктів) -> mkdir -p ~/.claude/rules/ecc -> cp -r rules/common ~/.claude/rules/ecc/ -> cp -r rules/typescript ~/.claude/rules/ecc/ # оберіть свій стек -> cp -r rules/python ~/.claude/rules/ecc/ -> cp -r rules/golang ~/.claude/rules/ecc/ -> cp -r rules/php ~/.claude/rules/ecc/ -> -> # Варіант B: Правила рівня проєкту (застосовуються лише до поточного проєкту) -> mkdir -p .claude/rules/ecc -> cp -r rules/common .claude/rules/ecc/ -> cp -r rules/typescript .claude/rules/ecc/ # оберіть свій стек -> ``` +
+Примітка щодо іменування та міграції (ecc@ecc, affaan-m/ECC, ecc-universal) ---- +ECC має три публічних ідентифікатори, і вони не є взаємозамінними: -### Варіант 2: Ручне встановлення +- Вихідний репозиторій GitHub: `affaan-m/ECC` +- Ідентифікатор marketplace/плагіна Claude: `ecc@ecc` +- Пакет npm: `ecc-universal` -Якщо ви надаєте перевагу ручному контролю над тим, що встановлено: +Це навмисно. Встановлення через marketplace/плагін Anthropic прив'язані до канонічного ідентифікатора плагіна, тому ECC використовує `ecc@ecc`, щоб зберегти назви інструментів і простори імен команд зі слешем достатньо короткими для строгих валідаторів Desktop/API. Старі публікації можуть показувати попередній довгий ідентифікатор marketplace; вважайте це лише застарілим псевдонімом. Окремо, пакет npm навмисно залишився на `ecc-universal`, тому встановлення через npm та marketplace навмисно використовують різні назви. + +Релізи npm вирізаються за тегом версії, а не за кожним комітом, тому `ecc-universal` відстежує релізи (2.1, 2.2, ...), а не кожен push у `main`. Встановлюйте з git, якщо хочете найсвіжішу версію. + +Якщо ваше локальне налаштування Claude було стерто чи скинуто, це не означає, що вам потрібно щось перекуповувати. Почніть з `node scripts/ecc.js list-installed`, потім запустіть `node scripts/ecc.js doctor` та `node scripts/ecc.js repair` перед перевстановленням. Зазвичай це відновлює керовані ECC файли без перебудови всього налаштування. +
+ +### Codex App і CLI + +Поточні релізи Codex можуть встановлювати ECC як нативний плагін репо-маркетплейсу. Запис маркетплейсу використовує корінь репозиторію, тому кеш Codex отримує маніфест разом з усіма навичками, конфігурацією MCP, середовищем виконання хуків, скриптами та ресурсами, на які є посилання: + +```bash +codex plugin marketplace add affaan-m/ECC +codex plugin add ecc@ecc +codex plugin list --json +node scripts/codex/check-plugin-cache.js +``` + +Обидві команди додавання ідемпотентні. Щоб оновити пізніше, запустіть `codex plugin marketplace upgrade ecc`, а потім `codex plugin add ecc@ecc`. Codex зберігає стан одного увімкненого плагіна в активному `CODEX_HOME`; він не пропонує рівні `user`, `project` та `local` Claude. Його нативні хуки вимагають явного рішення про довіру і не використовують чотири профілі хуків ECC для Claude. Всередині Codex викликайте `$configure-ecc` для керованого потоку, що враховує провайдера. + +Старіший шлях `scripts/sync-ecc-to-codex.sh` залишається окремим варіантом сумісності для користувачів, які навмисно хочуть скопійовану та злиту конфігурацію в `~/.codex`; він не потрібен для нативного плагіна. Спочатку запустіть Codex один раз, щоб `~/.codex/config.toml` існував, потім: ```bash -# Клонуйте репозиторій git clone https://github.com/affaan-m/ECC.git cd ECC +npm install +bash scripts/sync-ecc-to-codex.sh +``` -# Скопіюйте агентів до вашої конфігурації Claude +Ви також можете відкрити репозиторій ECC безпосередньо в Codex для локального налаштування проєкту. Codex читає кореневий `AGENTS.md` та довірену конфігурацію проєкту в `.codex/` без глобальної синхронізації. Не додавайте нативний плагін маркетплейсу поверх потоку синхронізації. + +Для навігації по репозиторію, володіння поверхнями та настанов щодо пакетів diff для PR читайте [карту навігації Codex ECC](../../docs/CODEX-NAVIGATION-GUIDE.md). Дивіться [примітки плагіна .codex](../../.codex-plugin/README.md) для деталей нативного життєвого циклу. + +### Інші агенти та редактори + +
+Cursor, OpenCode, Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode, Copilot + +Клонуйте ECC один раз, потім оберіть ціль, що відповідає вашій оболонці: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +``` + +| Оболонка | Встановлення чи налаштування | Примітки | +|---|---|---| +| Cursor | `./install.sh --profile minimal --target cursor` | Локальний для проєкту адаптер `.cursor/` | +| OpenCode | `npm install && npm run build:opencode && ./install.sh --profile full --target opencode` | Збирає пейлоад плагіна перед повним встановленням | +| Gemini CLI | `./install.sh --profile minimal --target gemini` | Локальна для проєкту конфігурація `.gemini/` | +| Zed | `./install.sh --profile minimal --target zed` | Локальний для проєкту адаптер `.zed/` | +| Antigravity | `./install.sh --profile minimal --target antigravity` | Дивіться [посібник з Antigravity](../../docs/ANTIGRAVITY-GUIDE.md) | +| Qwen CLI | `./install.sh --profile minimal --target qwen` | Дивіться [посібник з Qwen](../../docs/QWEN-GUIDE.md) | +| Hermes | `./install.sh --profile minimal --target hermes` | Дивіться [посібник з налаштування Hermes](../../docs/HERMES-SETUP.md) | +| OpenClaw | `./install.sh --profile minimal --target openclaw` | Кероване встановлення в домашню директорію | +| Kimi Code CLI | `./install.sh --profile minimal --target kimi` | Локальне для проєкту встановлення `.kimi-code/` | +| CodeBuddy | `./install.sh --profile minimal --target codebuddy` | Локальне для проєкту встановлення `.codebuddy/` | +| JoyCode | `./install.sh --profile minimal --target joycode` | Локальне для проєкту встановлення `.joycode/` | + +Підтримка GitHub Copilot вже включена в цей репозиторій. `.github/copilot-instructions.md` надає шар інструкцій, `.github/prompts/` містить повторно використовувані промпти `/plan`, `/tdd`, `/security-review`, `/build-fix` та `/refactor`, а `.vscode/settings.json` вмикає `chat.promptFiles`. + +Для оболонки без нативної цілі ECC використовуйте [посібник з ручної адаптації](../../docs/MANUAL-ADAPTATION-GUIDE.md). Він пояснює, як перенести невеликий набір навичок і робочих інструкцій ECC у чат-подібні інструменти, не вдаючи, що хуки чи нативне виявлення навичок доступні. + +Cursor встановлює визначення агентів під `.cursor/agents/ecc-*.md`. Нативна поведінка завантаження Cursor може відрізнятися залежно від збірки Cursor. ECC не встановлює кореневий `AGENTS.md` в `.cursor/`. Адаптер тримає контекст Cursor обмеженим його нативними правилами та поверхнями агентів. + +Детальні примітки по кожній оболонці (паритет функцій, адаптери хуків, обмеження) знаходяться в [Підтримці платформ](#підтримка-платформ) нижче. +
+ +## Розширені опції встановлення + +Опції залишаються тут, безпосередньо під основними шляхами встановлення, щоб вам не довелося шукати по всьому README, коли стандартне налаштування не підходить. + +
+Встановлення з низьким контекстом без середовища виконання хуків + +### Шлях з низьким контекстом / без хуків + +Використовуйте це, коли хочете правила, агентів, команди, конфігурацію платформи та основні процеси ECC без хуків часу виконання: + +```bash +./install.sh --profile minimal --target claude +``` + +Windows: + +```powershell +.\install.ps1 --profile minimal --target claude +``` + +Цей профіль навмисно виключає `hooks-runtime`. + +Ручні встановлення Claude розміщують кожну навичку безпосередньо в `~/.claude/skills/<назва-навички>/` (або `.claude/skills/<назва-навички>/` для `claude-project`), щоб Claude Code міг її виявити. При оновленні старішого ручного встановлення ECC інсталятор мігрує лише вкладені файли `skills/ecc/`, записані в стані встановлення ECC. Якщо плоска директорія навички належить користувачу, ECC зберігає її, друкує попередження про конфлікт і відстежує будь-яку старішу керовану копію для безпечного видалення замість перезапису файлів користувача. + +Для звичайного основного профілю з вимкненими хуками: + +```bash +./install.sh --profile core --without baseline:hooks --target claude +``` + +Додайте середовище виконання хуків пізніше, лише якщо хочете його: + +```bash +./install.sh --target claude --modules hooks-runtime +``` +
+ +
+Обирайте лише потрібні вам компоненти + +### Спочатку знайдіть потрібні компоненти + +Запитайте вбудованого консультанта, які компоненти відповідають вашій роботі: + +```bash +node scripts/ecc.js consult "security reviews" --target claude +``` + +Він повертає відповідні компоненти, пов'язані профілі та команди попереднього перегляду/встановлення. Використовуйте команду попереднього перегляду перед встановленням, якщо хочете перевірити точний план файлів. + +Ви також можете встановити явні навички чи можливості: + +```bash +./install.sh --target claude --skills tdd-workflow,security-review +node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning +``` + +Ручне копіювання компонент за компонентом також працює. Кожен компонент повністю незалежний: + +```bash +# Лише агенти cp agents/*.md ~/.claude/agents/ -# Скопіюйте директорії правил (common + мовноспецифічні) +# Директорії правил (загальні + мовноспецифічні) mkdir -p ~/.claude/rules/ecc cp -r rules/common ~/.claude/rules/ecc/ cp -r rules/typescript ~/.claude/rules/ecc/ # оберіть свій стек -# Спочатку скопіюйте навички (основна поверхня процесів) +# Лише основні/загальні навички (Claude Code завантажує навички з прямих +# нащадків ~/.claude/skills; не вкладайте ручні встановлення під ~/.claude/skills/ecc/) mkdir -p ~/.claude/skills cp -r .agents/skills/* ~/.claude/skills/ cp -r skills/search-first ~/.claude/skills/ -# Необов'язково: збережіть сумісність зі слеш-командами +# Опційно: підтримувана сумісність зі слеш-командами під час міграції mkdir -p ~/.claude/commands cp commands/*.md ~/.claude/commands/ ``` -#### Встановлення хуків +Застарілі шими живуть у `legacy-command-shims/`. Копіюйте окремі файли звідти, лише якщо вам все ще потрібні старі назви на кшталт `/tdd`. +
-Не копіюйте `hooks/hooks.json` безпосередньо. Використовуйте інсталятор: +
+Локальні для проєкту правила замість глобальних + +Використовуйте локальні для проєкту правила, коли стандарти ECC мають застосовуватись до одного репозиторію, а не до кожної сесії Claude Code: + +```bash +cd your-project +mkdir -p .claude/rules/ecc +cp -R /path/to/ECC/rules/common .claude/rules/ecc/ +cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/ +``` + +Правила — це завжди завантажуваний контекст, тому починайте з `common` та одного пакета для стеку, який ви фактично використовуєте. При ручному копіюванні правил копіюйте цілу мовну директорію (наприклад `rules/common` чи `rules/golang`), а не файли всередині неї, щоб відносні посилання продовжували працювати, а назви файлів не конфліктували. +
+ +
+Повністю ручне встановлення Claude + +Використовуйте це лише коли ви навмисно пропускаєте шлях плагіна: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +./install.sh --profile full +``` + +Windows: + +```powershell +git clone https://github.com/affaan-m/ECC.git +cd ECC +.\install.ps1 --profile full +``` + +Якщо ви обираєте цей шлях, зупиніться на цьому. Не запускайте також `/plugin install`. + +Для вибіркових ручних встановлень Claude виявляє навички як прямих нащадків `~/.claude/skills/`; не вкладайте їх під `~/.claude/skills/ecc/`. + +#### Встановлення хуків + +Не копіюйте необроблений `hooks/hooks.json` з репозиторію безпосередньо в `~/.claude/settings.json` чи `~/.claude/hooks/hooks.json`. Цей файл орієнтований на плагін/репозиторій; використовуйте інсталятор, щоб шляхи команд хуків були правильно переписані: ```bash -# macOS / Linux bash ./install.sh --target claude --modules hooks-runtime ``` +Це записує вирішені хуки в `~/.claude/hooks/hooks.json` і залишає будь-який наявний `~/.claude/settings.json` недоторканим. + +Якщо ви встановили ECC через `/plugin install`, не копіюйте ці хуки в `settings.json`. Claude Code v2.1+ вже автоматично завантажує `hooks/hooks.json` плагіна, і дублювання їх у `settings.json` спричиняє подвійне виконання та крос-платформні конфлікти хуків. + +На Windows кореневий каталог конфігурації Claude — `%USERPROFILE%\\.claude`; встановіть середовище виконання хуків командою: + ```powershell -# Windows PowerShell pwsh -File .\install.ps1 --target claude --modules hooks-runtime ``` #### Налаштування MCP -Встановлення плагінів Claude навмисно не вмикають автоматично визначення вбудованих MCP-серверів ECC. Використовуйте команду `/mcp` Claude Code або налаштування MCP через CLI. +Встановлення плагіна Claude навмисно не вмикають автоматично вбудовані визначення MCP-серверів ECC. Це уникає надто довгих назв MCP-інструментів плагіна на строгих сторонніх шлюзах, зберігаючи ручне налаштування MCP доступним. ---- +Використовуйте команду `/mcp` Claude Code чи керовану CLI конфігурацію MCP для живих змін MCP-серверів у Claude Code; Claude Code зберігає ці вибори в `~/.claude.json`. Для локального для репозиторію доступу до MCP скопіюйте потрібні визначення MCP-серверів з `mcp-configs/mcp-servers.json` у `.mcp.json` в межах проєкту. + +ECC поставляється рівно з одним конектором за замовчуванням (`chrome-devtools`); все інше — це навичка, що обгортає CLI/REST API, або опційний запис каталогу. Правило та аудит червня 2026 року, який вивів з експлуатації попередні шість конекторів за замовчуванням, знаходяться в [docs/MCP-CONNECTOR-POLICY.md](../../docs/MCP-CONNECTOR-POLICY.md). + +Якщо ви вже запускаєте власні копії вбудованих MCP ECC, встановіть: + +```bash +export ECC_DISABLED_MCPS="chrome-devtools" +``` + +Керовані ECC потоки встановлення та синхронізації Codex пропустять чи видалять ці вбудовані сервери замість повторного додавання дублікатів. `ECC_DISABLED_MCPS` — це фільтр встановлення/синхронізації ECC, а не живий перемикач Claude Code. + +**Важливо:** Замініть заповнювачі `YOUR_*_HERE` вашими фактичними API-ключами. +
+ +
+Мультимодельні команди вимагають додаткового налаштування + +Команди `multi-*` **не** входять до базового встановлення плагіна/правил. + +Для використання `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend` та `/multi-workflow` необхідно також встановити середовище виконання `ccg-workflow`. Ініціалізуйте його командою `npx ccg-workflow`. + +Це середовище виконання надає зовнішні залежності, яких очікують ці команди, зокрема: + +- `~/.claude/bin/codeagent-wrapper` +- `~/.claude/.ccg/prompts/*` + +Без `ccg-workflow` ці команди `multi-*` не працюватимуть коректно. +
+ +
+Власні API-ендпоінти, шлюзи моделей і моделі на власному хостингу + +ECC працює через звичайну конфігурацію кожної оболонки, тому ви можете використовувати офіційного провайдера, сумісний власний API-ендпоінт чи шлюз моделей, або модель на власному хостингу без зміни робочих процесів ECC. + +Для Claude Code ECC не жорстко прив'язує налаштування транспорту, розміщеного Anthropic. Мінімальний приклад шлюзу: + +```bash +export ANTHROPIC_BASE_URL=https://your-gateway.example.com +export ANTHROPIC_AUTH_TOKEN=your-token +claude +``` + +Якщо ваш шлюз перевизначає назви моделей, налаштуйте це в Claude Code, а не в ECC. Хуки, навички, команди та правила ECC не залежать від провайдера моделі, коли CLI `claude` вже працює. Дивіться [документацію Anthropic про LLM-шлюзи](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) та [документацію про конфігурацію моделі](https://docs.anthropic.com/en/docs/claude-code/model-config). + +Запускайте чи розміщуйте будь-яку модель з відкритим вихідним кодом за цим шлюзом, використовуючи окремі обчислювальні ресурси та налаштування обслуговування. Якщо вам потрібна GPU-потужність, [Itô](https://compute.itomarkets.com) — бажаний обчислювальний спонсор ECC; підходить будь-який GPU-провайдер. Посилання на спонсорство пасивне: воно не викликає RFQ, не резервує потужність, не надає обчислювальні ресурси та не налаштовує обслуговування. Окремо, `ecc ito find` викликає явно налаштований канонічний CLI Itô та подає живий автентифікований RFQ; він не резервує потужність. Кероване виведення через Itô ще не працює наживо. + +### Самостійний хостинг Kimi з ECC + обчислювальними ресурсами Itô + +Оболонка Kimi Code та шар обслуговування моделі — окремі речі. ECC налаштовує оболонку агента; ви приносите API-ендпоінт чи розміщуєте самостійно модель Kimi з відкритими вагами на власній GPU-потужності. Цей адаптер перевірений проти Kimi Code 0.31.x (`@moonshot-ai/kimi-code`): + + + + + + + +
+ + Itô Markets
+ 1. Отримайте GPU-потужність +
+ Використовуйте Itô чи будь-якого GPU-провайдера. +		 + + Moonshot AI - Kimi
+ 2. Обслуговуйте Kimi +
+ Відкрийте обраний чекпоінт через сумісний ендпоінт. +		 + + ECC Tools
+ 3. Запустіть Kimi Code з ECC +
+ Встановіть інструкції та навички проєкту, потім запустіть Kimi Code. +
+ +Налаштуйте ендпоінт за [офіційним посібником провайдера](https://moonshotai.github.io/kimi-cli/en/configuration/providers.html) Kimi Code, потім встановіть ECC: + +```bash +bash ./install.sh --target kimi --profile minimal +node scripts/ecc.js doctor --target kimi +kimi +``` + +Kimi Code нативно виявляє встановлені інструкції `.kimi-code/AGENTS.md` та процеси `.kimi-code/skills/`; для проєкту `.agents/skills/` — також офіційне місце виявлення. ECC безпечно зливає записи MCP проєкту в `.kimi-code/mcp.json` і не змінює `~/.kimi-code/config.toml` рівня користувача. Kimi Code підтримує нативні хуки, але поточний керований адаптер проєкту ECC їх не налаштовує, тому цей інсталятор не пропонує профілі хуків Kimi. Пробний запуск інсталятора та набір регресійних тестів перевіряють, що кожен керований запис Kimi залишається в межах локального для проєкту кореня `.kimi-code/`. + +### Міст CLI обчислень Itô + +`ecc ito` делегує до окремо встановленого канонічного клієнта Itô; ECC не підтримує другий API-клієнт. `ecc ito login [--no-browser]` виконує авторизацію пристрою, відкриває сторінку верифікації Itô за замовчуванням та зберігає токен пристрою в macOS Keychain; `--no-browser` пригнічує передачу сторінки. ECC сам не виконує автоматизацію браузера. `ecc ito auth` лише перевіряє і відхиляє `--no-browser`. Доступні операції: `ecc ito login`, `ecc ito auth`, `ecc ito find`, `ecc ito status` та окремо захищений `ecc ito evals`. Відповідні MCP-інструменти залишаються `ito_auth`, `ito_find` та `ito_status`; `ito_auth` перевіряє наявні облікові дані, а кваліфікація вузла доступна лише через CLI. + +Пакет `ito-compute-cli` наразі не опубліковано. Зберіть його локально з репозиторію середовища виконання Itô (приватний, поки стіл зміцнюється; партнери з дизайну отримують доступ) під `cli/ito-compute-cli`, запустіть `npm ci` та `npm run check`, потім встановіть `ECC_ITO_CLI_EXECUTABLE` на абсолютний шлях `dist/bin/ito.js` цієї збірки. Вхід ніколи не успадковує `ITO_API_KEY`; auth, find та status передають `ITO_API_KEY` напряму, коли налаштовано, і `ITO_AUTH_MODE=legacy` не потрібен. `ecc ito logout` відкликає поточні облікові дані пристрою і зберігає їхню локальну копію, якщо віддалене відкликання не може бути підтверджене. Токени пристрою за замовчуванням використовують macOS Keychain; явний резервний файл повинен зберігати дозволи директорії/файлу лише для власника. ECC не виявляє цей клієнт, що містить облікові дані, через `PATH`. Дивіться [навичку `ito-compute`](../../skills/ito-compute/SKILL.md) для повного контракту повноважень RFQ та налаштування MCP. + +`find` подає живий автентифікований RFQ. Він не резервує потужність. `evals` вимагає одночасно `ITO_ENABLE_SIXTYTWO_LIVE=1` та `--live-sixtytwo`, окремо встановлений `sixtytwo-cli==0.3.33`, явний список вузлів та наявну абсолютну директорію конфігурації. Він не може орендувати, запускати, відновлювати, ремонтувати чи купувати. ECC не надає шлях блокування котирування, покупки, робочого навантаження чи виведення, і ніколи не замінює відсутнього клієнта чи невдалого живого виклику локальним результатом. +
+ +
+Скидання, ремонт чи видалення + +### Скидання / видалення ECC + +Якщо ECC здається продубльованим, нав'язливим чи зламаним, перевірте керований стан перед перевстановленням: + +```bash +node scripts/ecc.js list-installed +node scripts/ecc.js doctor +node scripts/ecc.js repair +node scripts/ecc.js uninstall --dry-run +``` + +Для прямого видалення: + +```bash +node scripts/uninstall.js --dry-run +node scripts/uninstall.js +``` + +Якщо ви йдете, команда видалення друкує опційну [20-секундну форму зворотного зв'язку](https://github.com/affaan-m/ECC/issues/new?template=quick-feedback.yml). Це публічний issue на GitHub, вона ніколи не блокує видалення, і ECC не завантажує діагностику. Ви також можете в будь-який час запустити `ecc feedback`, щоб побачити маршрути для проблем, зворотного зв'язку та пропозицій функцій. + +Користувачі плагіна повинні видалити плагін з Claude Code, а потім видалити лише ті папки правил, які вони скопіювали вручну і більше не хочуть мати. ECC видаляє лише файли, записані в його стані встановлення. Він не претендує на непов'язані файли у ваших директоріях оболонки. + +Якщо ви наклали кілька методів, очищуйте в такому порядку: + +1. Видаліть встановлення плагіна Claude Code. +2. Запустіть команду видалення ECC з кореня репозиторію, щоб видалити файли, керовані станом встановлення. +3. Видаліть будь-які додаткові папки правил, які ви скопіювали вручну і більше не хочете мати. +4. Перевстановіть один раз, використовуючи єдиний шлях. +
+ +## Скоро: кероване налаштування в релізі 2.2 + +> [!WARNING] +> Ці команди пакетного бігуна ECC недоступні в поточному релізі npm, 2.1.0. Не запускайте їх, поки не буде опубліковано `ecc-universal` 2.2.0. + +Попередній опис README — **Рекомендований стандарт:** запустіть керований майстер налаштування плагіна Claude — був опублікований завчасно. Ця рекомендація відкликана до релізу 2.2. + +Для налаштування плагіна Claude Code, оновлень, зміни рівня та зміни профілю хуків: + +```bash +npx ecc-universal setup +``` + +Реліз 2.2 підтримуватиме те саме кероване налаштування через сучасні пакетні бігуни: + +| Пакетний бігун | Команда керованого налаштування | +|---|---| +| npm / npx | `npx ecc-universal setup` | +| pnpm | `pnpm dlx ecc-universal setup` | +| Yarn 2+ | `yarn dlx ecc-universal setup` | +| Bun | `bunx ecc-universal setup` | + +Yarn Classic 1 не надає `yarn dlx`; використовуйте `npx`, встановіть пакет глобально, або оновіть Yarn для тимчасового одноразового запуску після публікації 2.2. + +Майстер інвентаризує офіційний маркетплейс і кожен нативний рівень встановлення Claude перед внесенням змін, потім встановлює, оновлює чи безпечно переміщує `ecc@ecc` до обраного вами рівня. Повторно запускайте ту саму команду, коли хочете оновити ECC, змінити рівень чи змінити профіль хуків. Цей майстер налаштування наразі налаштовує плагін Claude Code; використовуйте мультиоболонковий майстер нижче для Codex чи Kimi Code. + +Щоб налаштувати більше одного кодового агента в одному переглянутому потоці, використовуйте мультиоболонковий майстер: + +```bash +npx ecc-universal install --guided +``` + +Він дозволяє обрати будь-яку комбінацію Claude Code, Codex та Kimi Code, показує кожен канал встановлення та призначення, попередньо перевіряє кожен вибір перед першим записом та запитує одне фінальне підтвердження. + +| Оболонка | Поведінка керованого встановлення | +|---|---| +| Claude Code | Нативний плагін `ecc@ecc` з одним рівнем `user`, `project` чи `local` та профілем хуків ECC | +| Codex | Нативний життєвий цикл маркетплейсу/плагіна Codex; перегляд і довіра хуків залишаються за Codex | +| Kimi Code | Керовані файли проєкту під `./.kimi-code`; хуки ECC, налаштування моделі/провайдера та автентифікація не налаштовуються | + +Для автоматизації зробіть кожен вибір, специфічний для провайдера, явним: + +```bash +npx ecc-universal install --guided \ + --harness claude --harness codex --harness kimi \ + --claude-scope local --claude-hooks standard \ + --profile core --yes +``` + +Перевірте нативний керований шлях Codex та керований шлях Kimi без запису: + +```bash +npx ecc-universal install --guided --harness codex --dry-run +npx ecc-universal install --profile core --target kimi --dry-run +``` + +Додаткові команди з назвою пакета також стануть доступні через псевдонім 2.2: + +```bash +npx ecc-universal consult "security reviews" --target claude +npx ecc-universal install --profile minimal --target claude --with capability:machine-learning +npx ecc-universal doctor --target kimi +``` + +Не використовуйте `npx ecc-install --profile minimal --target claude`: `ecc-install` — це назва бінарного файлу всередині `ecc-universal`, а не окремо опублікований пакет npm. + +ECC також постачає розширені керовані адаптери для `cursor`, `antigravity`, `gemini`, `opencode`, `codebuddy`, `joycode`, `qwen`, `zed`, `hermes` та `openclaw`. Ці цілі досі використовують свої задокументовані шляхи `ecc install --target ...`, поки кожен адаптер не пройде керовану матрицю життєвого циклу конфліктів, оновлень, ремонту та видалення. Жоден майстер не встановлює мовчки в кожну виявлену оболонку. + +## Почніть використовувати ECC + +Почніть з процесу, який вам потрібен, а не з повного каталогу. + +| Що ви робите | Почніть тут | +|---|---| +| Створюєте функцію | `/ecc:plan "опишіть функцію"`, потім `tdd-workflow` | +| Виправляєте помилку | Відтворіть її непрохідним тестом, потім використовуйте `tdd-workflow` | +| Переглядаєте новий код | `/code-review` для перегляду зі свіжого контексту | +| Ремонтуєте збірку | `/build-fix` | +| Очищуєте кодову базу | `/refactor-clean` | +| Перевіряєте тиск контексту | `/context-budget` | +| Завершуєте довгу сесію | `/save-session` чи `/learn-eval` | +| Відновлюєте пізніше | `/resume-session` | +| Аудитуєте конфігурацію агента | `/security-scan` чи `npx -y ecc-agentshield scan --path .` | + +
+Команди плагіна та ручні команди + +Команди плагіна Claude Code використовують форму з простором імен: + +```text +/ecc:plan "Додати автентифікацію" +``` + +Ручні встановлення можуть надавати коротшу форму сумісності: + +```text +/plan "Додати автентифікацію" +``` + +Навички — це основна поверхня процесів. Команди залишаються зручними точками входу та шимами сумісності. Перевірте, що встановлено: + +```bash +/plugin list ecc@ecc +``` +
+ +
+Який агент використовувати? + +Навички є канонічною поверхнею процесів; підтримувані слеш-записи залишаються доступними для процесів, орієнтованих на команди. + +| Я хочу... | Використовуйте цю поверхню | Використаний агент | +|--------------|-----------------|------------| +| Спланувати нову функцію | `/ecc:plan "Додати автентифікацію"` | planner | +| Спроєктувати архітектуру системи | `/ecc:plan` + агент architect | architect | +| Писати код з попереднім тестуванням | навичка `tdd-workflow` | tdd-guide | +| Переглянути щойно написаний код | `/code-review` | code-reviewer | +| Виправити помилки збірки | `/build-fix` | build-error-resolver | +| Запустити наскрізні тести | навичка `e2e-testing` | e2e-runner | +| Знайти вразливості безпеки | `/security-scan` | security-reviewer | +| Видалити мертвий код | `/refactor-clean` | refactor-cleaner | +| Оновити документацію | `/update-docs` | doc-updater | +| Переглянути код Go | `/go-review` | go-reviewer | +| Переглянути код Python | `/python-review` | python-reviewer | +| Переглянути код F# | *(викликайте `fsharp-reviewer` напряму)* | fsharp-reviewer | +| Переглянути код TypeScript/JavaScript | *(викликайте `typescript-reviewer` напряму)* | typescript-reviewer | +| Розробляти додатки HarmonyOS | *(викликайте `harmonyos-app-resolver` напряму)* | harmonyos-app-resolver | +| Аудитувати запити до бази даних | *(автоделегування)* | database-reviewer | +| Переглянути продакшн-зміни ML | навичка `mle-workflow` + агент `mle-reviewer` | mle-reviewer | + +
+ +
+Типові процеси + +Слеш-форми нижче показані там, де вони залишаються частиною підтримуваної поверхні команд. Застарілі шими коротких назв, такі як `/tdd` та `/eval`, живуть у `legacy-command-shims/` лише для явного опційного підключення. + +**Початок нової функції:** +``` +/ecc:plan "Додати автентифікацію користувача з OAuth" + -> planner створює план реалізації +навичка tdd-workflow -> tdd-guide забезпечує написання тестів спочатку +/code-review -> code-reviewer перевіряє вашу роботу +``` + +**Виправлення помилки:** +``` +навичка tdd-workflow -> tdd-guide: напишіть непрохідний тест, що відтворює її + -> реалізуйте виправлення, перевірте, що тест проходить +/code-review -> code-reviewer: перехопіть регресії +``` + +**Підготовка до продакшну:** +``` +/security-scan -> security-reviewer: аудит OWASP Top 10 +навичка e2e-testing -> e2e-runner: тести критичних потоків користувача +/test-coverage -> перевірте покриття 80%+ +``` +
+ +## Що нового: ECC 2.1 + +> [!IMPORTANT] +> **НОВЕ В ECC 2.1: Plan Canvas · оболонка Kimi · самостійне обслуговування на GPU Itô.** +> [Дивіться повні примітки до релізу →](https://github.com/affaan-m/ECC/blob/main/docs/releases/2.1.0/release-notes.md) + +### Plan Canvas: переглядайте плани, вказуючи, а не передруковуючи + +Ваш агент пише план, потім відкриває його в браузерному канвасі, доступному лише локально. Клацніть частину, яку маєте на увазі, додайте пронумеровані анотації, спілкуйтесь з бічної панелі та натисніть **Схвалити план** чи **Запросити зміни**. Вердикт відображається безпосередньо на воротах CONFIRM команди `/plan`. Діаграми Mermaid відображаються наживо, а зміни в файлі плану перезавантажують сторінку. + +![Plan Canvas demo: reviewing an ECC plan in the browser, scrolling diagrams, attaching an anchored annotation, chatting with the agent, and approving the plan](https://raw.githubusercontent.com/affaan-m/ECC/main/docs/releases/2.1.0/assets/ecc-plan-canvas-demo.gif) + +Це агностично до оболонки та моделі: простий CLI (`ecc-plan-canvas`), що говорить JSON, тому будь-який агент може ним керувати. Спробуйте: попросіть вашого агента виконати `/ecc:plan` щось, а потім переглядайте зі сторінки замість терміналу. + +[Відкрити план, використаний у цьому демо →](https://github.com/affaan-m/ECC/blob/main/docs/releases/2.1.0/plan-canvas-demo.plan.md) + +### Також у 2.1 + +- **Ціль встановлення Kimi Code** (`--target kimi`): ECC встановлюється нативно в Kimi Code CLI від [Moonshot AI](https://www.moonshot.ai) +- **Самостійний хостинг на GPU**: перевірений шлях з [Itô](https://compute.itomarkets.com), бажаним обчислювальним спонсором ECC, включно з опційним мостом RFQ `ecc ito find` (деталі та розкриття вище в опціях встановлення) +- **Moonshot AI (Kimi), Itô та Atlas Cloud** тепер публічні спонсори +- **Цілі встановлення Hermes + OpenClaw**, посібник з навігації Codex, консолідовані хуки PostToolUse та зміцнення ланцюжка поставок + +### Поточна розробка: Уніфікованe сховище пам'яті + +`ecc memory` надає Claude, Codex, Hermes, OpenClaw, Kimi та іншим оболонкам єдиний локальний, доступний для перегляду формат Markdown для тривалого контексту та передавання. Опційний stdio-сервер `ecc-memory-mcp` надає ту саму обмежену поверхню збереження/пошуку/читання/діагностики, не вмикаючи себе за замовчуванням. Повні деталі в розділі [Ділитеся контекстом між оболонками](#ділитеся-контекстом-між-оболонками) нижче. + +
+Попередні релізи + +| Версія | Основне | +|---|---| +| [v2.0.0](https://github.com/affaan-m/ECC/releases/tag/v2.0.0) | Операційна система агентних оболонок: крос-оболонкова градація, субстрат площини управління, оркестратори `orch-*`, Discord + бот ECC, політика єдиного конектора MCP | +| [v1.10.0](https://github.com/affaan-m/ECC/releases/tag/v1.10.0) | Оновлення поверхні, оператори процеси, альфа-версія ECC 2.0 | +| [v1.9.0](https://github.com/affaan-m/ECC/releases/tag/v1.9.0) | Вибіркове встановлення, ECC Tools Pro, 12 мовних екосистем | +| [v1.8.0](https://github.com/affaan-m/ECC/releases/tag/v1.8.0) | Продуктивність оболонок та крос-платформна надійність | +| [v1.7.0](https://github.com/affaan-m/ECC/releases/tag/v1.7.0) | Крос-платформне розширення та конструктор презентацій | +| [v1.6.0](https://github.com/affaan-m/ECC/releases/tag/v1.6.0) | Codex Edition та ECC Tools GitHub App | +| [v1.5.0](https://github.com/affaan-m/ECC/releases/tag/v1.5.0) | Universal Edition | +| [v1.4.0](https://github.com/affaan-m/ECC/releases/tag/v1.4.0) | Мультимовні правила, майстер встановлення, оркестрація PM2 | +| [v1.3.0](https://github.com/affaan-m/ECC/releases/tag/v1.3.0) | Повна підтримка плагіна OpenCode | +| [v1.2.0](https://github.com/affaan-m/ECC/releases/tag/v1.2.0) | Уніфіковані команди та навички | +| [v1.1.0](https://github.com/affaan-m/ECC/releases/tag/v1.1.0) | Крос-платформна підтримка та виправлення від спільноти | +| [v1.0.0](https://github.com/affaan-m/ECC/releases/tag/v1.0.0) | Офіційний реліз плагіна | + +
+ +
+Історія релізів детально + +### v2.0.0: Операційна система агентних оболонок (черв. 2026) + +Стабільна градація лінійки 2.0: субстрат площини управління (адаптери сесій + інвентаризація MCP), служба життєвого циклу worktree, родина оркестраторів `orch-*` та запуск [спільноти ECC Discord](https://discord.gg/36yGMHGFbR). Повні примітки: [docs/releases/2.0.0/release-notes.md](../../docs/releases/2.0.0/release-notes.md). + +### v2.0.0-rc.1: Оновлення поверхні, оператори процеси та альфа ECC 2.0 (квіт. 2026) + +- **GUI панель керування**: нова настільна програма на основі Tkinter (`ecc_dashboard.py` чи `npm run dashboard`) з перемикачем темної/світлої теми, налаштуванням шрифту та логотипом проєкту в заголовку та панелі задач. +- **Публічна поверхня синхронізована з живим репозиторієм**: метадані, кількість у каталозі, маніфести плагінів і документація зі встановлення тепер відповідають фактичній OSS-поверхні. +- **Розширення операторних і вихідних процесів**: `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops` та `workspace-surface-audit` доповнюють операторну гілку. +- **Медіа та інструменти запуску**: `manim-video`, `remotion-video-creation` та вдосконалені поверхні публікації в соцмережах роблять технічні роз'яснення та контент для запуску частиною тієї ж системи. +- **Зростання фреймворків і продуктових поверхонь**: `nestjs-patterns`, більш насичені поверхні встановлення Codex/OpenCode та розширена крос-оболонкова упаковка роблять репозиторій придатним для використання поза межами однієї оболонки. +- **Пакет навичок Itô для ринків прогнозів**: `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner`, `ito-data-atlas-agent`, `prediction-market-oracle-research` та `prediction-market-risk-review` додають публічні, неконсультативні ринкові/кошикові процеси, зберігаючи живий доступ до API Itô окремим від білінгу ECC Tools. +- **Пакет навичок оптимізації**: `parallel-execution-optimizer`, `benchmark-optimization-loop`, `data-throughput-accelerator`, `latency-critical-systems` та `recursive-decision-ledger` перетворюють повторювані запити про швидкість/рекурсію на обмежені процеси тестування продуктивності, пропускної здатності та журналу рішень. +- **ECC 2.0 alpha у дереві**: прототип площини управління на Rust у `ecc2/` збирається локально та надає команди `dashboard`, `start`, `sessions`, `status`, `stop`, `resume` та `daemon`. +- **Знімки статусу оператора**: `ecc status --markdown --write status.md` перетворює локальне сховище стану на портативне передавання, яке охоплює готовність, активні сесії, стан виконання навичок, стан встановлення, очікувані події управління та пов'язані робочі елементи з Linear/GitHub/handoffs. +- **Зміцнення екосистеми**: AgentShield, контроль витрат ECC Tools, робота з білінг-порталом та оновлення вебсайту продовжують поставлятись навколо основного плагіна замість того, щоб дрейфувати в окремі силоси. + +### v1.9.0: Вибіркове встановлення та розширення мовної підтримки (бер. 2026) + +- **Архітектура вибіркового встановлення**: конвеєр встановлення на основі маніфестів з `install-plan.js` та `install-apply.js` для цільового встановлення компонентів. Сховище стану відстежує встановлене та підтримує інкрементальні оновлення. +- **6 нових агентів**: `typescript-reviewer`, `pytorch-build-resolver`, `java-build-resolver`, `java-reviewer`, `kotlin-reviewer`, `kotlin-build-resolver` розширюють мовне покриття до 10 мов. +- **Нові навички**: `pytorch-patterns`, `documentation-lookup`, `bun-runtime`, `nextjs-turbopack`, 8 навичок для операційних доменів та `mcp-server-patterns`. +- **Інфраструктура сесій та стану**: сховище стану SQLite з CLI запитів, адаптери сесій для структурованого запису, фундамент для саморозвиваючих навичок. +- **Переробка оркестрації**: детермінована оцінка аудиту оболонок, зміцнений статус оркестрації та сумісність запускачів, захист від циклів спостерігача з 5-шаровою охороною. +- **Надійність спостерігача**: виправлення вибуху пам'яті з обмеженням та вибіркою хвоста, виправлення доступу до пісочниці, логіка відкладеного запуску та захист від повторного входу. +- **12 мовних екосистем**: нові правила для Java, PHP, Perl, Kotlin/Android/KMP, C++ та Rust доповнюють існуючі TypeScript, Python, Go та загальні правила. +- **Внески спільноти**: переклади корейською та китайською, оптимізація biome hook, навички відеообробки, операційні навички, PowerShell-інсталятор, підтримка Antigravity IDE. +- **Зміцнення CI**: 19 виправлень помилок тестів, примусовий підрахунок каталогу, валідація маніфесту встановлення та повний набір тестів зелений. + +### v1.8.0: Система продуктивності оболонок (бер. 2026) + +- **Першочерговий випуск для оболонок**: ECC явно позиціонується як система продуктивності агентних оболонок, а не просто пакет конфігурацій. +- **Переробка надійності хуків**: резервний шлях SessionStart, підсумки сесій на фазі Stop та хуки на основі скриптів замість ненадійних однорядкових. +- **Елементи управління виконанням хуків**: `ECC_HOOK_PROFILE=minimal|standard|strict` та `ECC_DISABLED_HOOKS=...` для управління під час виконання без редагування файлів хуків. +- **Нові команди оболонки**: `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`. +- **NanoClaw v2**: маршрутизація моделей, гаряче завантаження навичок, розгалуження/пошук/експорт/компакшн/метрики сесій. +- **Крос-оболонковий паритет**: поведінка вирівняна між Claude Code, Cursor, OpenCode та Codex app/CLI. +- **997 внутрішніх тестів пройдено**: повний набір тестів зелений після рефакторингу хуків/виконання та оновлень сумісності. + +### v1.7.0: Крос-платформне розширення та конструктор презентацій (лют. 2026) + +- **Підтримка Codex app + CLI**: пряма підтримка Codex на основі `AGENTS.md`, цільове встановлення та документація Codex. +- **Навичка `frontend-slides`**: конструктор HTML-презентацій без залежностей з керівництвом щодо конвертації PPTX та строгими правилами відповідності вьюпорту. +- **5 нових загальних бізнес/контент-навичок**: `article-writing`, `content-engine`, `market-research`, `investor-materials`, `investor-outreach`. +- **Ширше охоплення інструментів**: підтримка Cursor, Codex та OpenCode вдосконалена, щоб той самий репозиторій постачався чисто через усі основні оболонки. +- **992 внутрішні тести**: розширена валідація та регресійне покриття для плагіна, хуків, навичок та упаковки. + +### v1.6.0: Codex CLI, AgentShield та Marketplace (лют. 2026) + +- **Підтримка Codex CLI**: нова команда `/codex-setup` генерує `codex.md` для сумісності з OpenAI Codex CLI. +- **7 нових навичок**: `search-first`, `swift-actor-persistence`, `swift-protocol-di-testing`, `regex-vs-llm-structured-text`, `content-hash-cache-pattern`, `cost-aware-llm-pipeline`, `skill-stocktake`. +- **Інтеграція AgentShield**: `/security-scan` запускає AgentShield безпосередньо з Claude Code; 1282 тести, 102 правила. +- **GitHub Marketplace**: ECC Tools GitHub App доступний на [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) з безкоштовним/pro/enterprise рівнями. +- **30+ злитих PR від спільноти**: внески від 30 учасників на 6 мовах. +- **978 внутрішніх тестів**: розширений набір валідації для агентів, навичок, команд, хуків та правил. + +### v1.4.1: Виправлення помилки (лют. 2026) + +- **Виправлено втрату вмісту при імпорті інстинктів**: `parse_instinct_file()` мовчки відкидав увесь вміст після frontmatter (розділи Action, Evidence, Examples) під час `/instinct-import`. ([#148](https://github.com/affaan-m/ECC/issues/148), [#161](https://github.com/affaan-m/ECC/pull/161)) + +### v1.4.0: Мультимовні правила, майстер встановлення та PM2 (лют. 2026) + +- **Інтерактивний майстер встановлення**: нова навичка `configure-ecc` забезпечує кероване налаштування з виявленням злиття/перезапису. +- **PM2 та мультиагентна оркестрація**: 6 нових команд (`/pm2`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/multi-workflow`) для управління складними мультисервісними процесами. +- **Архітектура мультимовних правил**: правила реструктуровані з плоских файлів у директорії `common/` + `typescript/` + `python/` + `golang/`. Встановлюйте лише потрібні мови. +- **Переклад китайською (zh-CN)**: повний переклад усіх агентів, команд, навичок та правил (80+ файлів). +- **Підтримка GitHub Sponsors**: спонсоруйте проєкт через GitHub Sponsors. +- **Покращений CONTRIBUTING.md**: детальні шаблони PR для кожного типу внеску. + +### v1.3.0: Підтримка плагіна OpenCode (лют. 2026) + +- **Повна інтеграція OpenCode**: 12 агентів, 24 команди, 16 навичок з підтримкою хуків через систему плагінів OpenCode (20+ типів подій). +- **3 нативних власних інструменти**: run-tests, check-coverage, security-audit. +- **LLM-документація**: `llms.txt` для повної документації OpenCode для LLM. + +### v1.2.0: Уніфіковані команди та навички (лют. 2026) + +- **Підтримка Python/Django**: навички Django patterns, security, TDD та verification. +- **Навички Java Spring Boot**: patterns, security, TDD та verification для Spring Boot. +- **Управління сесіями**: команда `/sessions` для історії сесій. +- **Безперервне навчання v2**: навчання на основі інстинктів з оцінюванням довіри, імпортом/експортом, еволюцією. + +Повний журнал змін у [Releases](https://github.com/affaan-m/ECC/releases). +
+ +## Чому обрати ECC? + +| Без системи | З ECC | +| ------------------------------------------------------- | --------------------------------------------------------------------- | +| Плани зникають в історії чату | Плани стають редагованими артефактами перед початком реалізації | +| "Будь ласка, використовуй TDD" — це інструкція, яку модель може забути | TDD стає воротовим процесом ЧЕРВОНИЙ -> ЗЕЛЕНИЙ -> РЕФАКТОРИНГ з доказами | +| Той самий контекст пише й переглядає код | Рецензент зі свіжим контекстом шукає регресії та сліпі зони | +| Пам'ять означає збереження величезної стенограми | Сесії дистилюються в підсумки, інстинкти та навички для повторного використання | +| Перевірки якості залежать від нагадувань | Хуки можуть примусово виконувати детерміновані перевірки поза промптом | +| Конфігурація агента довіряється за замовчуванням | AgentShield сканує саму оболонку як поверхню атаки | + +### TDD: розробка через тестування + +```text +/ecc:plan "Додати сповіщення про білінг на основі використання" + -> підтвердіть чи відредагуйте план + -> активуйте tdd-workflow + -> зафіксуйте докази ЧЕРВОНИЙ перед реалізацією + -> реалізуйте до ЗЕЛЕНОГО + -> перегляньте зі свіжого контексту + -> виправте знахідки з регресійними тестами + -> перевірте збірку, лінт, типи та тести +``` + +Результат — це не просто код. Це слід доказів: план, непрохідний тест, прохідний тест, знахідки перегляду та фінальна перевірка. + +### Навички тримають контекст сфокусованим + +Правила, навички, агенти та хуки вирішують різні проблеми. Тримати ці завдання окремо — ось як ECC додає можливості, не скидаючи весь репозиторій у кожну сесію. + +| Концепція | Що це робить | Поведінка контексту | +|---|---|---| +| Навички | Повторно використовувані процеси, такі як TDD, перегляд безпеки чи глибоке дослідження | Завантажуються, коли завдання їх потребує | +| Агенти | Обмежені за обсягом працівники з власним контекстом і дозволами на інструменти | Ізолюють планування, реалізацію та перегляд | +| Правила | Тривалі стандарти проєкту чи мови | Завжди завантажені, тому встановлюйте їх вибірково | +| Хуки | Скрипти, викликані подіями оболонки | Виконуються поза контекстом моделі | +| Інстинкти | Патерни, вивчені з реальних сесій з оцінкою довіри | Пригадуються, коли релевантні | + +### Ділитеся контекстом між оболонками + +Сховище пам'яті ECC надає Claude, Codex, Hermes, OpenClaw, Kimi та іншим оболонкам єдиний локальний, доступний для перегляду формат Markdown для тривалого контексту та передавання. Пам'ять проєкту та команди живе під `.ecc/memory/`; пам'ять користувача живе під `~/.ecc/memory/`. + +```bash +npm install -g ecc-universal +ecc memory init --scope project +ecc memory search "authentication migration" --target-harness codex +ecc memory doctor +``` + +Пам'ять — це неперевірений контекст, а не виконувана політика. Перевіряйте важливі твердження за авторитетними джерелами та переносьте прийняті знання в керовану документацію проєкту. Опційний сервер `ecc-memory-mcp` надає ту саму обмежену поверхню збереження, пошуку, читання та діагностики, не вмикаючи себе за замовчуванням. + +[Відкрити процес Уніфікованої пам'яті →](../../skills/unified-memory/SKILL.md) + +
+Сховище пам'яті детально: обсяги, передавання та межі довіри + +Сховище пам'яті зберігає портативні документи Markdown `ecc.memory.v1` замість копіювання транскриптів постачальника чи надсилання контексту між агентами електронною поштою. Пам'ять проєкту захищена fail-closed `.gitignore`; використовуйте обсяг команди лише для перевіреного людиною, версіонованого поширення. Пам'ять команди залишається неперевіреним контекстом навіть після коміту. + +Встановлення лише навичок, мінімальні, ручні та встановлення через плагін Claude не розміщують середовище виконання Сховища пам'яті на `PATH`. Встановіть середовище виконання npm окремо перед використанням CLI чи опційного MCP-сервера: + +```bash +npm install -g ecc-universal +ecc memory --help +command -v ecc-memory-mcp +``` + +```bash +# Ініціалізуйте сховище проєкту. +ecc memory init --scope project + +# Запишіть тіло передавання у звичайний файл, потім націльтеся на наступну оболонку. +ecc memory handoff \ + --from hermes \ + --target codex \ + --title "Continue authentication migration" \ + --body-file ./handoff.md + +# Пригадайте його з іншої оболонки. +ecc memory search "authentication migration" --target-harness codex +ecc memory read + +# Перевірте сховище перед поширенням пам'яті команди. +ecc memory doctor +``` + +Тіла пам'яті приймаються лише через `--stdin` чи `--body-file`, а не як значення командного рядка. Перший реліз тримає кожен запис сховища неперевіреним і лише для створення; людський перегляд переносить прийняті знання в керовану документацію проєкту, а не змінює довіру до пам'яті. Звичайний пошук пригадування повертає активну пам'ять проєкту та команди. Пряме читання за ID може перевірити неактивний запис. Пригадування на рівні користувача повинно бути запитане явно. Агенти повинні перевіряти важливі твердження за авторитетними джерелами і ніколи не повинні розглядати пригадані тіла як виконувані інструкції чи політику. + +Для опційного доступу через MCP додайте запис `ecc-memory-vault` з [`mcp-configs/mcp-servers.json`](../../mcp-configs/mcp-servers.json) до кожної оболонки, якій він потрібен, потім запустіть `ecc-memory-mcp`. Сервер надає лише `memory_save`, `memory_search`, `memory_read` та `memory_doctor`. Кожен сервер повинен запускатися з ідентичністю `ECC_MEMORY_HARNESS` у нижньому регістрі; ідентичність прив'язана до сервера і не може надаватися викликачем інструменту. Обсяг користувача додатково вимагає опційне підключення `ECC_MEMORY_ALLOW_USER_SCOPE=1`, кероване оператором. Дивіться [`skills/unified-memory/SKILL.md`](../../skills/unified-memory/SKILL.md) для процесу та меж довіри, і [`docs/design/ecc-memory-vault.md`](../../docs/design/ecc-memory-vault.md) для контракту можливостей. +
+ +## Посібники + +Цей репозиторій — сирий код. Посібники пояснюють усе. + + + + + + + +
+ +Короткий посібник з ECC
+Короткий посібник + +
Налаштування, основи та використання з першого дня. Читайте спочатку. (нитка) +		 + +Розширений посібник з ECC
+Розширений посібник + +
Економіка контексту, пам'ять, оцінки та паралельні агенти. (нитка) +		 + +Посібник з безпеки ECC
+Посібник з безпеки + +
Ін'єкція промптів, хуки, MCP та AgentShield. (нитка) +
+ +| Тема | Що ви дізнаєтесь | +|-------|-------------------| +| Оптимізація токенів | Вибір моделі, скорочення системного промпту, фонові процеси | +| Збереження пам'яті | Хуки, що автоматично зберігають/завантажують контекст між сесіями | +| Безперервне навчання | Автовитягування патернів із сесій у навички для повторного використання | +| Петлі верифікації | Контрольні точки проти безперервних оцінок, типи оцінювачів, метрики pass@k | +| Паралелізація | Git worktrees, каскадний метод, коли масштабувати інстанції | +| Оркестрація підагентів | Проблема контексту, патерн ітеративного отримання | + +[Швидкий довідник команд](../../COMMANDS-QUICK-REF.md) | [Посібник з ручної адаптації](../../docs/MANUAL-ADAPTATION-GUIDE.md) + +## Що всередині + +```text +ECC/ +|-- agents/ # 68 спеціалізованих підагентів для делегування +|-- skills/ # 287 навичок для повторного використання, що завантажуються на вимогу +|-- commands/ # 94 підтримувані слеш-командні шими +|-- rules/ # опційні загальні та мовноспецифічні стандарти +|-- hooks/ # автоматизація та примусове виконання під час виконання +|-- scripts/ # встановлення, ремонт, синхронізація, оркестрація та перевірки +|-- .claude-plugin/ # маніфест маркетплейсу Claude Code +|-- .codex/ # довідкова конфігурація Codex та ролі агентів +|-- .opencode/ # плагін, команди та інструкції OpenCode +|-- .cursor/ # правила та адаптер хуків Cursor +|-- docs/ # публічні посібники зі встановлення, архітектури та експлуатації +``` + +Корінь — джерело істини. Адаптери платформ пакують чи відображають ці ж процеси замість підтримки окремих копій. + +
+Анотований каталог компонентів + +Повний анотований каталог (агенти, навички, команди, правила, хуки, скрипти) синхронізований з англомовним README — дивіться [оригінальний README](../../README.md#annotated-component-catalog) для найсвіжішого детального списку кожного файлу, оскільки він оновлюється при кожному релізі. +
+ +
+GUI панель керування + +Запустіть настільну панель керування для візуального дослідження компонентів ECC: + +```bash +npm run dashboard +# або +python3 ./ecc_dashboard.py +``` + +**Функції:** +- Вкладковий інтерфейс: Агенти, Навички, Команди, Правила, Налаштування +- Перемикач темної/світлої теми +- Налаштування шрифту (сімейство та розмір) +- Логотип проєкту в заголовку та панелі задач +- Пошук та фільтрація по всіх компонентах +
+ +## Інструменти екосистеми + +
+Конструктор навичок: генеруйте навички з вашої git-історії + +Два способи генерації навичок з вашого репозиторію: + +### Варіант A: Локальний аналіз (вбудований) + +Використовуйте команду `/skill-create` для локального аналізу без зовнішніх сервісів: + +```bash +/skill-create # Аналізувати поточний репозиторій +/skill-create --instincts # Також генерувати інстинкти для continuous-learning-v2 +``` + +Це аналізує вашу git-історію локально та генерує файли SKILL.md. + +### Варіант B: GitHub App (розширений) + +Для розширених функцій (10k+ комітів, автоматичні PR, спільний доступ у команді): + +[Встановити ECC Tools GitHub App](https://github.com/apps/ecc-tools) | [ecc.tools](https://ecc.tools) + +```bash +# Коментуйте у будь-якому issue: +/ecc-tools analyze +``` + +Обидва варіанти створюють: +- **Файли SKILL.md**: готові до використання навички для активної оболонки +- **Колекції інстинктів**: для continuous-learning-v2 +- **Витягування патернів**: навчається з вашої git-історії +
+ +
+AgentShield: аудитор безпеки для конфігурацій агентів + +> Створений на Claude Code Hackathon (Cerebral Valley x Anthropic, лют. 2026). 1282 тести, 98% покриття, 102 правила статичного аналізу. + +Скануйте вашу конфігурацію агента на вразливості, помилкові конфігурації та ризики ін'єкцій. + +```bash +# Швидке сканування (без встановлення) +npx ecc-agentshield scan + +# Автовиправлення безпечних проблем +npx ecc-agentshield scan --fix + +# Глибокий аналіз з трьома агентами Opus 4.6 +npx ecc-agentshield scan --opus --stream + +# Генерація безпечної конфігурації з нуля +npx ecc-agentshield init +``` + +**Що сканується:** CLAUDE.md, settings.json, конфіги MCP, хуки, визначення агентів та навички по 5 категоріях: виявлення секретів (14 патернів), аудит дозволів, аналіз ін'єкцій хуків, профілювання ризиків MCP-серверів та перевірка конфігурації агентів. + +**Прапорець `--opus`** запускає три агенти Claude Opus 4.6 у конвеєрі атакуючий/захисник/аудитор. Атакуючий знаходить ланцюжки вразливостей, захисник оцінює захисти, а аудитор синтезує обох у пріоритизовану оцінку ризиків. Адверсарне міркування, а не просто зіставлення патернів. + +**Формати виводу:** термінал (кольорова градація A-F), JSON (CI-конвеєри), Markdown, HTML. Код виходу 2 при критичних знахідках для воріт збирання. + +Використовуйте `/security-scan` у Claude Code для запуску, або додайте до CI через [GitHub Action](https://github.com/affaan-m/agentshield). + +[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield) +
+ +
+Безперервне навчання v2: інстинкти + +Система навчання на основі інстинктів автоматично вивчає ваші патерни: + +```bash +/instinct-status # Показати вивчені інстинкти з довірою +/instinct-import # Імпортувати інстинкти від інших +/instinct-export # Експортувати ваші інстинкти для поширення +/evolve # Кластеризувати пов'язані інстинкти в навички +``` + +Дивіться `skills/continuous-learning-v2/` для повної документації. Зберігайте `continuous-learning/` лише якщо вам явно потрібен застарілий потік v1 Stop-hook з вивченими навичками. +
## Ключові концепції +
+Агенти, навички, хуки та правила пояснено + ### Агенти Підагенти виконують делеговані завдання з обмеженим обсягом. Приклад: @@ -857,7 +1119,7 @@ pwsh -File .\install.ps1 --target claude --modules hooks-runtime --- name: code-reviewer description: Переглядає код на якість, безпеку та підтримуваність -tools: ["Read", "Grep", "Glob", "Bash"] +tools: Read, Grep, Glob, Bash model: opus --- @@ -866,7 +1128,7 @@ model: opus ### Навички -Навички є основною поверхнею процесів. Вони можуть викликатися безпосередньо, пропонуватися автоматично та повторно використовуватися агентами. +Навички є основною поверхнею процесів. Вони можуть викликатися безпосередньо, пропонуватися автоматично та повторно використовуватися агентами. ECC все ще постачає підтримувані `commands/` під час міграції, тоді як застарілі шими коротких назв живуть під `legacy-command-shims/` лише для явного опційного підключення. Нова розробка процесів має відбуватися в `skills/` насамперед. ```markdown # Процес TDD @@ -907,121 +1169,650 @@ rules/ arkts/ # Патерни та обмеження HarmonyOS / ArkTS ``` ---- +Дивіться [`rules/README.md`](../../rules/README.md) для деталей встановлення та структури. +
-## Який агент використовувати? +## Крос-платформна підтримка -Не знаєте, з чого почати? Використовуйте цей довідник. +Основний Node.js CLI ECC та керовані інсталятори працюють на **Windows, macOS та Linux**, але опційні можливості не мають повного паритету. Деякі шляхи безперервного навчання, GAN та оркестрації досі вимагають Bash чи Python; оболонки також надають різні API хуків, агентів та навичок. -| Я хочу... | Поверхня | Агент | -|--------------|-----------------|------------| -| Спланувати нову функцію | `/ecc:plan "Додати автентифікацію"` | planner | -| Спроєктувати архітектуру системи | `/ecc:plan` + агент architect | architect | -| Писати код з попереднім тестуванням | Навичка `tdd-workflow` | tdd-guide | -| Переглянути щойно написаний код | `/code-review` | code-reviewer | -| Виправити помилки збирання | `/build-fix` | build-error-resolver | -| Запустити наскрізні тести | Навичка `e2e-testing` | e2e-runner | -| Знайти вразливості безпеки | `/security-scan` | security-reviewer | -| Видалити мертвий код | `/refactor-clean` | refactor-cleaner | -| Оновити документацію | `/update-docs` | doc-updater | -| Переглянути код Go | `/go-review` | go-reviewer | -| Переглянути код Python | `/python-review` | python-reviewer | -| Переглянути ML-зміни для продакшну | Навичка `mle-workflow` + агент `mle-reviewer` | mle-reviewer | +| Платформа | Статус | Поточне обмеження | +|---|---|---| +| Linux | Підтримується основний | Опційні функції можуть вимагати Bash, Python чи інструменти конкретного провайдера. | +| macOS | Підтримується основний | Автономний шлях GAN shell не сумісний із системним Bash 3.2 і наразі має дефект розбору оцінок ([#2674](https://github.com/affaan-m/ECC/issues/2674)). | +| Windows + WSL | Підтримується основний | WSL слідує шляхам Linux; інтеграції з хостом Windows все ще відрізняються залежно від оболонки. | +| Windows нативний | Підтримується з обмеженнями | Демон спостерігача та записи сховища пам'яті continuous-learning v2 мають відкриті дефекти на нативному Windows ([#2489](https://github.com/affaan-m/ECC/issues/2489), [#2626](https://github.com/affaan-m/ECC/issues/2626)). Опційні функції на основі shell вимагають Git Bash/WSL чи недоступні. | -### Типові процеси - -**Початок нової функції:** -``` -/ecc:plan "Додати автентифікацію користувача з OAuth" - → planner створює план реалізації -Навичка tdd-workflow → tdd-guide забезпечує написання тестів спочатку -/code-review → code-reviewer перевіряє вашу роботу -``` - -**Виправлення помилки:** -``` -Навичка tdd-workflow → tdd-guide: написати непрохідний тест, що відтворює її - → реалізувати виправлення, перевірити що тест проходить -/code-review → code-reviewer: перевірити регресії -``` - -**Підготовка до продакшну:** -``` -/security-scan → security-reviewer: аудит OWASP Top 10 -Навичка e2e-testing → e2e-runner: тести критичних процесів -/test-coverage → перевірити покриття 80%+ -``` - ---- - -## Поширені запитання +Розглядайте `stable`, `beta`, `experimental` та `instruction-only` нижче як твердження про можливості, а не маркетингові рівні.
-Як перевірити, які агенти/команди встановлено? +Виявлення менеджера пакетів + +Плагін автоматично виявляє ваш бажаний менеджер пакетів (npm, pnpm, yarn чи bun) з таким пріоритетом: + +1. **Змінна середовища**: `CLAUDE_PACKAGE_MANAGER` +2. **Конфіг проєкту**: `.claude/package-manager.json` +3. **package.json**: поле `packageManager` +4. **Lock-файл**: виявлення з package-lock.json, yarn.lock, pnpm-lock.yaml чи bun.lockb +5. **Глобальний конфіг**: `~/.claude/package-manager.json` +6. **Запасний варіант**: перший доступний менеджер пакетів + +Щоб встановити бажаний менеджер пакетів: ```bash -/plugin list ecc@ecc +# Через змінну середовища +export CLAUDE_PACKAGE_MANAGER=pnpm + +# Через глобальний конфіг +node scripts/setup-package-manager.js --global pnpm + +# Через конфіг проєкту +node scripts/setup-package-manager.js --project bun + +# Виявити поточне налаштування +node scripts/setup-package-manager.js --detect ``` -Це показує всі доступні агенти, команди та навички з плагіна. +Або використовуйте команду `/setup-pm`.
-Мої хуки не працюють / я бачу помилки "Duplicate hooks file" +Елементи управління виконанням хуків (змінні середовища) -Це найпоширеніша проблема. **НЕ додавайте поле `"hooks"` до `.claude-plugin/plugin.json`.** Claude Code v2.1+ автоматично завантажує `hooks/hooks.json` з встановлених плагінів. Явне оголошення спричиняє помилки виявлення дублікатів. Дивіться [#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103). -
- -
-Чи можна використовувати ECC з Claude Code на власному API-ендпоінті або шлюзі моделей? - -Так. ECC не прив'язує налаштування транспорту Anthropic жорстко. Він працює локально через звичайну CLI/плагін-поверхню Claude Code, тому працює з: - -- Розміщеним Anthropic Claude Code -- Офіційними налаштуваннями шлюзу Claude Code через `ANTHROPIC_BASE_URL` та `ANTHROPIC_AUTH_TOKEN` -- Сумісними власними ендпоінтами, що розуміють Anthropic API - -Мінімальний приклад: +Використовуйте прапорці виконання для налаштування суворості чи тимчасового вимкнення конкретних хуків: ```bash -export ANTHROPIC_BASE_URL=https://your-gateway.example.com -export ANTHROPIC_AUTH_TOKEN=your-token -claude +# Профіль суворості хуків (стандарт за замовчуванням) +export ECC_HOOK_PROFILE=standard + +# Через кому ідентифікатори хуків для вимкнення +export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" + +# Обмежити додатковий контекст SessionStart (за замовчуванням: 8000 символів) +export ECC_SESSION_START_MAX_CHARS=4000 + +# Повністю вимкнути додатковий контекст SessionStart для конфігурацій з низьким контекстом/локальними моделями +export ECC_SESSION_START_CONTEXT=off + +# Вікно збереження session-tmp у днях (за замовчуванням: 30). +# Встановіть 0, off, false, disabled, never чи none, щоб зберігати всі сесії (вимкнути очищення). +export ECC_SESSION_RETENTION_DAYS=14 + +# Обмежити кількість вивчених інстинктів, які SessionStart вводить у контекст (за замовчуванням: 6) +export ECC_MAX_INJECTED_INSTINCTS=6 + +# Мінімальна довіра, необхідна інстинкту для введення, 0-1 (за замовчуванням: 0.7) +export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7 + +# SessionStart ранжує введені інстинкти за довірою + релевантністю проєкту/стеку +# (за замовчуванням: увімкнено). Встановіть off/false/0/no для ранжування лише за довірою. +export ECC_INSTINCT_RELEVANCE_RANKING=on + +# Зберегти попередження щодо контексту/обсягу/циклів, але пригнічити оцінки витрат API +export ECC_CONTEXT_MONITOR_COST_WARNINGS=off ``` +Windows PowerShell: + +```powershell +[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User') +[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User') +```
-Моє контекстне вікно скорочується / Claude вичерпує контекст +Домашня директорія даних агента (мультиоболонкова ізоляція) -Забагато MCP-серверів поглинає ваш контекст. Кожен опис інструменту MCP витрачає токени з вашого вікна 200k, потенційно скорочуючи його до ~70k. Контекст SessionStart обмежений 8000 символами за замовчуванням; знизьте це за допомогою `ECC_SESSION_START_MAX_CHARS=4000` або вимкніть за допомогою `ECC_SESSION_START_CONTEXT=off` для конфігурацій з локальними моделями або низьким контекстом. +Хуки збереження пам'яті (підсумки сесій, вивчені навички, псевдоніми сесій, метрики) зберігають дані під єдиним кореневим каталогом даних агента. За замовчуванням це `~/.claude`. При використанні ECC у Claude Code та Cursor на одному комп'ютері встановіть окремий корінь для Cursor, щоб два середовища не перезаписували файли сесій одне одного: -**Виправлення:** Вимкніть невикористовувані MCP у Claude Code за допомогою `/mcp`. Тримайте менше 10 активних MCP та менше 80 активних інструментів. +```bash +# Кордон лише для Cursor (Claude Code зберігає стандартний ~/.claude) +export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" +``` + +Шляхи, що вирішуються під цим коренем: + +- `$ECC_AGENT_DATA_HOME/session-data/`: підсумки сесій +- `$ECC_AGENT_DATA_HOME/skills/learned/`: вивчені навички з evaluate-session +- `$ECC_AGENT_DATA_HOME/session-aliases.json`: псевдоніми сесій +- `$ECC_AGENT_DATA_HOME/metrics/`: метрики витрат та активності + +Дивіться [affaan-m/ECC#2065](https://github.com/affaan-m/ECC/issues/2065).
+## Підтримка платформ + +| Оболонка | Статус | Рекомендований дистрибутив | Важливе обмеження | +|---|---|---|---| +| Claude Code | Стабільна основна | Плагін чи вибірковий інсталятор | Плагін рекламує встановлений каталог моделі; використовуйте вибірковий/ручний профіль, коли важливий обсяг контексту. Опційні навички на основі shell не портативні на кожну ОС. | +| Codex | Підтримувана синхронізація; маркетплейс експериментальний | Конфігурація репозиторію чи `sync-ecc-to-codex.sh` | Немає середовища виконання хуків ECC. Пакет маркетплейсу може пропускати спільний вміст репозиторію з кешу Codex; використовуйте синхронізацію для надійного шляху. | +| Cursor | Бета-адаптер проєкту | Вибірковий інсталятор у `.cursor/` | Виявлення агентів залежить від збірки Cursor, а шляхи інсталятора ECC ще не показують ідентичні набори хуків ([#2419](https://github.com/affaan-m/ECC/issues/2419)). | +| OpenCode | Бета зібраний плагін | Зберіть плагін, потім вибірковий інсталятор | ECC постачає підмножину каталогу, а еталонна конфігурація прив'язує моделі Anthropic; оберіть моделі, доступні вашому провайдеру ([#2617](https://github.com/affaan-m/ECC/issues/2617)). | +| GitHub Copilot | Лише інструкції | Закомічені інструкції та файли промптів | Немає хуків ECC, агентів часу виконання, делегування чи нативного виявлення навичок. | +| Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode | Експериментальні/мінімальні адаптери | Ціль вибіркова для оболонки | Розміщення файлів та портативність інструкцій перевірені; повний паритет функцій Claude не заявляється. | + +### Карта крос-інструментальних можливостей + +| Можливість | Claude Code | Codex | Cursor | OpenCode | GitHub Copilot | +|---|---|---|---|---|---| +| Інструкції | Нативно | Нативний `AGENTS.md` | Правила проєкту | Інструкції плагіна | Нативний файл інструкцій | +| Навички | Нативний встановлений набір | Нативний синхронізований набір | Набір проєкту залежно від збірки | Вбудована підмножина | Лише посилання на промпти/інструкції | +| Агенти/делегування | Нативні агенти | Мультиагентні ролі Codex | Агенти проєкту залежно від збірки | Агенти плагіна | Не підтримується | +| Хуки ECC | Нативні хуки плагіна | Не підтримується | Адаптер хуків Cursor; відмінності шляхів встановлення залишаються | Події плагіна | Не підтримується | +| Конфігурація MCP | Доступна, явна активація | Злиття TOML через синхронізацію | Явна конфігурація проєкту/користувача | Конфігурація провайдера/плагіна | Не надається ECC | +| Паритет з Claude Code | Основний еталон | Частковий | Частковий | Частковий | Не є ціллю паритету | + +**Ключові архітектурні рішення:** +- **AGENTS.md** у корені — універсальний крос-інструментальний файл (читається Claude Code, Cursor, Codex та OpenCode; GitHub Copilot використовує `.github/copilot-instructions.md` замість нього) +- **Патерн DRY-адаптера** дозволяє Cursor повторно використовувати скрипти хуків Claude Code без дублювання +- **Формат навичок** (SKILL.md з YAML frontmatter) працює у Claude Code, Codex та OpenCode +- Відсутність хуків у Codex компенсується `AGENTS.md`, опційними перевизначеннями `model_instructions_file` та дозволами пісочниці +
-Чи можу я використовувати лише деякі компоненти (наприклад, лише агентів)? +Детальна підтримка Cursor IDE -Так. Використовуйте Варіант 2 (ручне встановлення) та скопіюйте лише те, що вам потрібно. Кожен компонент повністю незалежний. -
+ECC надає підтримку Cursor IDE з хуками, правилами, агентами, навичками, командами та конфігами MCP, адаптованими для макету проєктів Cursor. -
-Чи це працює з Cursor / OpenCode / Codex / Antigravity / GitHub Copilot? +```bash +# macOS/Linux +./install.sh --target cursor typescript +./install.sh --target cursor python golang swift php +``` -Так. ECC є кросплатформним. Дивіться відповідні розділи нижче для деталей кожної оболонки. -
+```powershell +# Windows PowerShell +.\install.ps1 --target cursor typescript +.\install.ps1 --target cursor python golang swift php +``` -
-Як зробити внесок новою навичкою або агентом? +#### Що включено для Cursor -Дивіться [CONTRIBUTING.md](../../CONTRIBUTING.md). Коротко: -1. Зробіть форк репозиторію -2. Створіть навичку в `skills/your-skill-name/SKILL.md` (з YAML frontmatter) -3. Або створіть агента в `agents/your-agent.md` -4. Надішліть PR з чітким описом того, що він робить і коли використовувати -
+| Компонент | Кількість | Деталі | +|-----------|-------|---------| +| Події хуків | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt та ще 10 | +| Скрипти хуків | 16 | Тонкі Node.js-скрипти, що делегують до `scripts/hooks/` через спільний адаптер | +| Правила | 34 | 9 загальних (alwaysApply) + 25 мовноспецифічних (TypeScript, Python, Go, Swift, PHP) | +| Агенти | 48 | `.cursor/agents/ecc-*.md` при встановленні; з префіксом для уникнення конфліктів з агентами користувача чи маркетплейсу | +| Навички | Спільні + вбудовані | `.cursor/skills/` для перекладених доповнень | +| Команди | Спільні | `.cursor/commands/` якщо встановлено | +| Конфіг MCP | Спільний | `.cursor/mcp.json` якщо встановлено | +#### Примітки завантаження Cursor + +ECC не встановлює кореневий `AGENTS.md` в `.cursor/`. Cursor трактує вкладені файли `AGENTS.md` як контекст директорії, тому копіювання ідентичності репозиторію ECC в проєкт-хост забруднило б цей проєкт. + +Нативна поведінка завантаження Cursor може відрізнятися залежно від збірки Cursor. ECC встановлює агентів як `.cursor/agents/ecc-*.md`; якщо ваша збірка Cursor не показує агентів проєкту, ці файли все одно працюють як явні довідкові визначення замість прихованого глобального контексту промпту. + +#### Ізоляція пам'яті та даних (Cursor + Claude Code) + +Хуки пам'яті ECC повторно використовують ті самі `scripts/hooks/*.js`, що й Claude Code. Для Cursor ECC намагається автоматично тримати пам'ять **поза `~/.claude`**: + +1. **Хук `sessionStart` Cursor** (встановлюється в `.cursor/hooks.json` при `--target cursor`) вводить `ECC_AGENT_DATA_HOME` для всієї сесії composer. +2. **Стандарт середовища виконання хуків**: коли присутні `CURSOR_VERSION` чи `CURSOR_PROJECT_DIR`, хуки за замовчуванням використовують `~/.cursor/ecc`, якщо змінна середовища не встановлена. +3. **Конфіг проєкту**: `.cursor/ecc-agent-data.json` документує та перевизначає шлях (`agentDataHome`). +4. **Завжди-увімкнене правило**: `.cursor/rules/ecc-agent-data-home.mdc` нагадує агенту, де живе пам'ять. + +Ви все ще можете явно перевизначити: + +```bash +export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" +``` + +Щоб **поділитися** пам'яттю з Claude Code навмисно, встановіть `ECC_AGENT_DATA_HOME=~/.claude` у shell чи в `.cursor/ecc-agent-data.json`. + +Інстинкти continuous learning v2 залишаються окремо під `CLV2_HOMUNCULUS_DIR` (за замовчуванням `~/.local/share/ecc-homunculus`). + +#### Архітектура хуків (DRY-патерн адаптера) + +Cursor має **більше подій хуків, ніж Claude Code** (20 проти 8). Модуль `.cursor/hooks/adapter.js` перетворює вхідний JSON Cursor у формат Claude Code, дозволяючи повторно використовувати існуючі `scripts/hooks/*.js` без дублювання. + +``` +Вхідний JSON Cursor -> adapter.js -> перетворює -> scripts/hooks/*.js + (спільний з Claude Code) +``` + +Ключові хуки: +- **beforeShellExecution**: блокує dev-сервери поза tmux (код виходу 2), перегляд git push +- **afterFileEdit**: автоформатування + перевірка TypeScript + попередження про console.log +- **beforeSubmitPrompt**: виявляє секрети (патерни sk-, ghp_, AKIA) у промптах +- **beforeTabFileRead**: блокує читання Tab з .env, .key, .pem файлів (код виходу 2) +- **beforeMCPExecution / afterMCPExecution**: аудит-логування MCP + +#### Формат правил + +Правила Cursor використовують YAML frontmatter з `description`, `globs` та `alwaysApply`: + +```yaml --- +description: "TypeScript coding style extending common rules" +globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"] +alwaysApply: false +--- +``` + + +
+Детальна підтримка Codex macOS app + CLI + +ECC надає підтримуваний шлях репо/синхронізації Codex для macOS-додатка та CLI, з еталонною конфігурацією, Codex-специфічним доповненням AGENTS.md та спільними навичками. Маршрут маркетплейсу ECC залишається експериментальним. Для навігації по репозиторію, володіння поверхнями та настанов щодо пакетів diff для PR почніть з [`docs/CODEX-NAVIGATION-GUIDE.md`](../../docs/CODEX-NAVIGATION-GUIDE.md). + +```bash +# Запустіть Codex CLI в репозиторії: AGENTS.md та .codex/ виявляються автоматично +codex + +# Автоматичне налаштування: синхронізуйте активи ECC (AGENTS.md, навички, MCP-сервери) у ~/.codex +npm install && bash scripts/sync-ecc-to-codex.sh + +# Або вручну: скопіюйте еталонну конфігурацію у вашу домашню директорію +cp .codex/config.toml ~/.codex/config.toml +``` + +Скрипт синхронізації безпечно зливає MCP-сервери ECC в наявний `~/.codex/config.toml`, використовуючи стратегію **лише додавання**: він ніколи не видаляє й не змінює ваші наявні сервери. Запустіть з `--dry-run` для попереднього перегляду змін, чи `--update-mcp`, щоб примусово оновити сервери ECC до останньої рекомендованої конфігурації. + +Для Context7 ECC використовує канонічну назву розділу Codex `[mcp_servers.context7]`, все ще запускаючи пакет `@upstash/context7-mcp`. Якщо у вас вже є застарілий запис `[mcp_servers.context7-mcp]`, `--update-mcp` мігрує його до канонічної назви розділу. + +Codex macOS app: +- Відкрийте цей репозиторій як робочу область. +- Кореневий `AGENTS.md` виявляється автоматично. +- `.codex/config.toml` та `.codex/agents/*.toml` працюють найкраще, коли залишаються локальними для проєкту. +- Еталонний `.codex/config.toml` навмисно не прив'язує `model` чи `model_provider`, тому Codex використовує свій поточний стандарт, якщо ви не перевизначите його. +- Опційно: скопіюйте `.codex/config.toml` в `~/.codex/config.toml` для глобальних стандартів; тримайте файли ролей мультиагента локальними для проєкту, якщо ви також не копіюєте `.codex/agents/`. + +#### Що включено для Codex + +| Компонент | Кількість | Деталі | +|-----------|-------|---------| +| Конфіг | 1 | `.codex/config.toml`: approvals/sandbox/web_search верхнього рівня, MCP-сервери, сповіщення, профілі | +| AGENTS.md | 2 | Кореневий (універсальний) + `.codex/AGENTS.md` (Codex-специфічне доповнення) | +| Навички | 32 | `.agents/skills/`: SKILL.md + agents/openai.yaml на навичку | +| MCP-сервери | 6 | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 з Supabase через синхронізацію `--update-mcp`) | +| Профілі | 2 | `strict` (пісочниця лише для читання) та `yolo` (повне автозатвердження) | +| Ролі агентів | 3 | `.codex/agents/`: explorer, reviewer, docs-researcher | + +Навички в `.agents/skills/` автоматично завантажуються Codex. Канонічні навички Anthropic, такі як `claude-api`, `frontend-design` та `skill-creator`, навмисно не перевбудовані тут. Встановлюйте їх з [`anthropics/skills`](https://github.com/anthropics/skills), коли хочете офіційні версії. + +#### Ключове обмеження + +Codex **ще не забезпечує паритет виконання хуків у стилі Claude**. Примусове виконання ECC там базується на інструкціях через `AGENTS.md`, опційні перевизначення `model_instructions_file` та налаштування пісочниці/затвердження. + +#### Підтримка мультиагентності + +Поточні збірки Codex підтримують стабільні мультиагентні процеси. + +- Увімкніть `features.multi_agent = true` в `.codex/config.toml` +- Визначте ролі під `[agents.]` +- Вкажіть кожну роль на файл під `.codex/agents/` +- Використовуйте `/agent` в CLI для перевірки чи керування дочірніми агентами + +ECC постачає три приклади конфігурацій ролей: + +| Роль | Призначення | +|------|---------| +| `explorer` | Збір доказів кодової бази лише для читання перед редагуванням | +| `reviewer` | Перегляд правильності, безпеки та відсутніх тестів | +| `docs_researcher` | Перевірка документації та API перед релізом/змінами документації | + +
+ +
+Підтримка Zed + +ECC надає підтримку проєктів Zed через консервативний адаптер `.zed` для локальних для проєкту налаштувань, вирівняних правил, агентів, команд та навичок. + +```bash +./install.sh --profile minimal --target zed +``` + +```powershell +.\install.ps1 --profile minimal --target zed +``` + +Адаптер записує керовані ECC файли під `.zed/` і тримає облікові дані BYOK/OpenRouter поза репозиторієм. Налаштуйте обліковий запис Zed чи API-ключі через власний UI налаштувань Zed чи ваші локальні налаштування користувача. +
+ +
+Детальна підтримка OpenCode + +ECC надає бета-інтеграцію плагіна OpenCode з інструкціями, підмножиною каталогу, командами, власними інструментами та подіями хуків. Він не надає паритет функцій з Claude Code, а еталонні ID моделей повинні існувати у налаштованого провайдера користувача. + +```bash +# Встановіть OpenCode +npm install -g opencode + +# Запустіть у корені репозиторію +opencode +``` + +Конфігурація виявляється автоматично з `.opencode/opencode.json`. + +#### Підтримка хуків через плагіни + +Система плагінів OpenCode має 20+ типів подій: + +| Хук Claude Code | Подія плагіна OpenCode | +|-----------------|----------------------| +| PreToolUse | `tool.execute.before` | +| PostToolUse | `tool.execute.after` | +| Stop | `session.idle` | +| SessionStart | `session.created` | +| SessionEnd | `session.deleted` | + +**Додаткові події OpenCode**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show` та інші. + +#### Встановлення плагіна + +**Варіант 1: Використовувати напряму** +```bash +cd ECC +opencode +``` + +**Варіант 2: Встановити як npm-пакет** +```bash +npm install ecc-universal +``` + +Потім додайте до вашого `opencode.json`: +```json +{ + "plugin": ["ecc-universal"] +} +``` + +Цей запис npm-плагіна вмикає опублікований плагін-модуль OpenCode від ECC (хуки/події та інструменти плагіна). Він **не** автоматично додає повний каталог команд/агентів/інструкцій ECC до конфігурації вашого проєкту. + +Для повного налаштування ECC OpenCode або: +- запустіть OpenCode всередині цього репозиторію, або +- скопіюйте вбудовані ресурси конфігурації `.opencode/` у ваш проєкт і підключіть записи `instructions`, `agent` та `command` в `opencode.json` + +#### Документація + +- **Посібник з міграції**: `.opencode/MIGRATION.md` +- **README плагіна OpenCode**: `.opencode/README.md` +- **Консолідовані правила**: `.opencode/instructions/INSTRUCTIONS.md` +- **LLM-документація**: `llms.txt` (повна документація OpenCode для LLM) +
+ +
+Детальна підтримка GitHub Copilot + +ECC надає **підтримку GitHub Copilot** для VS Code через нативну систему інструкційних та промпт-файлів Copilot Chat. Додаткові інструменти не потрібні. + +#### Що включено для GitHub Copilot + +| Компонент | Файл | Призначення | +|-----------|------|---------| +| Основні інструкції | `.github/copilot-instructions.md` | Завжди завантажувані правила: стиль коду, безпека, тестування, git-процес | +| Налаштування VS Code | `.vscode/settings.json` | Файли інструкцій для конкретних завдань: генерація коду, генерація тестів, повідомлення комітів | +| Промпт plan | `.github/prompts/plan.prompt.md` | Поетапне планування реалізації | +| Промпт TDD | `.github/prompts/tdd.prompt.md` | Цикл Червоний-Зелений-Покращення | +| Промпт перевірки безпеки | `.github/prompts/security-review.prompt.md` | Глибокий аналіз безпеки за OWASP | +| Промпт виправлення збирання | `.github/prompts/build-fix.prompt.md` | Систематичне вирішення помилок збирання та CI | +| Промпт рефакторингу | `.github/prompts/refactor.prompt.md` | Очищення мертвого коду та спрощення | + +Файли вже на місці: відкрийте будь-який репозиторій, що містить цей проєкт, і GitHub Copilot Chat автоматично підхопить `.github/copilot-instructions.md`. Закомічений `.vscode/settings.json` вмикає `chat.promptFiles`, щоб VS Code міг завантажувати повторно використовувані промпти з `.github/prompts/`. + +Щоб використовувати промпти процесів у Copilot Chat: +1. Відкрийте панель Copilot Chat у VS Code. +2. Клацніть іконку **скріпки / прикріпити** та оберіть **Prompt...**, або введіть `/` та оберіть промпт. +3. Оберіть промпт (наприклад, `plan`, `tdd`, `security-review`). + +#### Покриття функцій + +| Функція ECC | Еквівалент Copilot | +|-------------|-------------------| +| Стандарти кодування | Завжди увімкнено через `copilot-instructions.md` | +| Контрольний список безпеки | Завжди увімкнено + промпт `security-review` | +| Тестування / TDD | Завжди увімкнено + промпт `tdd` | +| Планування реалізації | Промпт `plan` | +| Перегляд коду | Зовнішній перегляд PR через CodeRabbit + Greptile | +| Вирішення помилок збірки | Промпт `build-fix` | +| Рефакторинг | Промпт `refactor` | +| Формат повідомлень комітів | Інструкція для конкретного завдання в `settings.json` | +| Хуки / автоматизація | Не підтримується (Copilot не має системи хуків) | +| Агенти / делегування | Не підтримується (Copilot не має API підагентів) | + +#### Обмеження + +GitHub Copilot не має системи хуків чи API підагентів, тому автоматизації хуків ECC (автоформат, перевірка TypeScript, збереження сесій, захист dev-сервера) та делегування агентів недоступні. Шар інструкцій та промптів все ж привносить повну філософію кодування ECC (стандарти, безпеку, TDD та процес) у кожну сесію Copilot Chat. +
+ +
+Що змінилося у v2.0.0 + +ECC v2.0.0 стабілізує лінійку 2.0 з публічною історією оператора Hermes, 281 навичкою, 67 агентами, 94 командними шимами, адаптерами сесій, інвентаризацією MCP, службами життєвого циклу worktree, процесами оркестраторів та спільнотою ECC Discord. + +- [Примітки до релізу v2.0.0](../../docs/releases/2.0.0/release-notes.md) +- [Еталонна архітектура ECC 2.0](../../docs/ECC-2.0-REFERENCE-ARCHITECTURE.md) +- [Посібник з налаштування Hermes](../../docs/HERMES-SETUP.md) +- [Посібник з міграції з 1.x](../../docs/MIGRATION-1X-TO-2.0.md) +
+ +## Оптимізація токенів + +Використання агента може бути дорогим, якщо не керувати споживанням токенів. Ці налаштування значно знижують витрати без шкоди для якості. Повний посібник: [docs/token-optimization.md](../../docs/token-optimization.md). + +
+Рекомендовані налаштування + +Додайте до `~/.claude/settings.json`: + +```json +{ + "model": "sonnet", + "env": { + "MAX_THINKING_TOKENS": "10000", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", + "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" + } +} +``` + +| Налаштування | Стандарт | Рекомендовано | Ефект | +|---------|---------|-------------|--------| +| `model` | opus | **sonnet** | ~60% скорочення витрат; справляється з 80%+ завдань кодування | +| `MAX_THINKING_TOKENS` | 31 999 | **10 000** | ~70% скорочення прихованих витрат на міркування за запит | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Компакшн раніше, краща якість у довгих сесіях | +| `ECC_CONTEXT_MONITOR_COST_WARNINGS` | увімк | **вимк для підписників підписки** | Пригнічує попередження оцінок API-рейту для агента, зберігаючи попередження контексту/обсягу/циклів | + +Переходьте на Opus лише коли потрібне глибоке архітектурне міркування: +``` +/model opus +``` +
+ +
+Команди щоденного процесу + +| Команда | Коли використовувати | +|---------|-------------| +| `/model sonnet` | Стандарт для більшості завдань | +| `/model opus` | Складна архітектура, налагодження, глибоке міркування | +| `/clear` | Між непов'язаними завданнями (безкоштовно, миттєве скидання) | +| `/compact` | У логічних точках зупинки завдань (дослідження завершено, milestone досягнуто) | +| `/cost` | Моніторинг витрат токенів під час сесії | + +Якщо ви використовуєте підписку і оцінки API-рейту монітора контексту не корисні, встановіть `ECC_CONTEXT_MONITOR_COST_WARNINGS=off`. Це лише пригнічує попередження витрат для агента; воно не вимикає попередження про вичерпання контексту, обсяг чи цикли. +
+ +
+Стратегічний компакшн + +Навичка `strategic-compact` пропонує `/compact` у логічних точках зупинки замість покладання на автокомпакшн при 95% контексту. Дивіться `skills/strategic-compact/SKILL.md` для повного посібника з рішень. + +**Коли компактувати:** +- Після дослідження/вивчення, перед реалізацією +- Після завершення milestone, перед початком наступного +- Після налагодження, перед продовженням роботи з функцією +- Після невдалого підходу, перед спробою нового + +**Коли НЕ компактувати:** +- В середині реалізації (ви втратите назви змінних, шляхи до файлів, частковий стан) +
+ +
+Управління контекстним вікном + +**Критично:** Не вмикайте всі MCP одразу. Кожен опис MCP-інструменту витрачає токени з вашого вікна 200k, потенційно скорочуючи його до ~70k. + +- Тримайте менше 10 MCP увімкненими на проєкт +- Тримайте менше 80 активних інструментів +- Використовуйте `/mcp` для вимкнення невикористовуваних MCP-серверів Claude Code; ці вибори часу виконання зберігаються в `~/.claude.json` +- Використовуйте `ECC_DISABLED_MCPS` лише для фільтрації конфігів MCP, згенерованих ECC, під час потоків встановлення/синхронізації +- Якщо контекст стає важким, запустіть `/context-budget` та видаліть непотрібні правила + +**Попередження про вартість команд агентів:** Agent Teams породжує кілька контекстних вікон. Кожен товариш по команді споживає токени незалежно. Використовуйте лише для завдань, де паралелізм дає чітку цінність (мультимодульна робота, паралельні перегляди). Для простих послідовних завдань підагенти ефективніші за токенами. +
+ +## Вимоги + +
+Версія Claude Code CLI + поведінка автозавантаження хуків + +### Версія Claude Code CLI + +**Мінімальна версія: v2.1.0 чи новіша.** Плагін вимагає Claude Code CLI v2.1.0+ через зміни в тому, як система плагінів обробляє хуки. + +Перевірте свою версію: +```bash +claude --version +``` + +### Важливо: поведінка автозавантаження хуків + +> УВАГА: **Для учасників:** НЕ додавайте поле `"hooks"` до `.claude-plugin/plugin.json`. Це забезпечується регресійним тестом. + +Claude Code v2.1+ **автоматично завантажує** `hooks/hooks.json` з будь-якого встановленого плагіна за угодою. Явне оголошення його в `plugin.json` спричиняє помилку виявлення дублікатів: + +``` +Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file +``` + +**Передісторія:** Це спричинило повторювані цикли виправлення/відкату в цьому репозиторії ([#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103)). Поведінка змінювалася між версіями Claude Code, що призводило до плутанини. Тепер є регресійний тест для запобігання повторного введення цього. +
+ +## Безпека + +Встановлюйте ECC лише з офіційних джерел: + +- Репозиторій GitHub: +- Плагін Claude Code: `ecc@ecc` +- Пакети npm: [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) та [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield) +- GitHub App: +- Вебсайт: + +Скануйте проєкт з AgentShield: + +```bash +npx -y ecc-agentshield scan --path . +``` + +- **Повідомте про вразливість.** Використовуйте приватний процес у [SECURITY.md](../../SECURITY.md) (приватне звітування про вразливість GitHub). Будь ласка, не відкривайте публічні issues для звітів про безпеку. +- **Вбудовані захисні механізми.** GateGuard блокує деструктивні команди оболонки (включно з `rm`, force/path `git checkout` та деструктивним `find -exec`) перед їхнім виконанням; сканер IOC ланцюжка поставок запускається в CI; а AgentShield аудитує ваші власні поверхні агента, хуків, MCP, дозволів та секретів (`/security-scan`). + +
+Хуки, MCP-сервери та контроль контексту + +Хуки можуть виконувати команди оболонки, MCP-сервери можуть тримати облікові дані, а інструкції проєкту можуть потрапляти в контекст агента. Розглядайте всі три як виконувану конфігурацію. + +Не копіюйте необроблений `hooks/hooks.json` в `~/.claude/settings.json` після встановлення плагіна. Сучасні версії Claude Code автоматично завантажують хуки плагіна, і друга копія може змусити їх спрацьовувати двічі. + +Використовуйте `/mcp` для вимкнень часу виконання Claude Code; Claude Code зберігає ці вибори в `~/.claude.json`. + +`ECC_DISABLED_MCPS` — це фільтр встановлення/синхронізації ECC, а не живий перемикач Claude Code. + +Якщо контекст стає важким, запустіть `/context-budget`, видаліть непотрібні правила та вимкніть невикористовувані MCP-сервери. Дивіться [посібник з оптимізації токенів](../../docs/token-optimization.md). +
+ +Посилання з безпеки: + +- [Політика безпеки](../../SECURITY.md) +- [Посібник з безпеки](../../the-security-guide.md) +- [Політика конекторів MCP](../../docs/MCP-CONNECTOR-POLICY.md) +- [Реагування на інциденти ланцюжка поставок](../../docs/security/supply-chain-incident-response.md) + +## Усунення несправностей + +
+ECC з'являється двічі чи хуки спрацьовують двічі + +Звичайна причина — встановлення плагіна Claude, а потім запуск `./install.sh --profile full` поверх нього. + +1. Видаліть встановлення плагіна Claude Code. +2. Запустіть `node scripts/ecc.js uninstall --dry-run` з чекауту ECC. +3. Видаліть додаткові папки правил, скопійовані вручну, які більше не потрібні. +4. Перевстановіть один раз, використовуючи один шлях. + +Для перевірок, специфічних для хуків, дивіться [README хуків](../../hooks/README.md). +
+ +
+Мої хуки не працюють / помилки "Duplicate hooks file" + +**НЕ додавайте поле `"hooks"` до `.claude-plugin/plugin.json`.** Claude Code v2.1+ автоматично завантажує `hooks/hooks.json` зі встановлених плагінів. Явне оголошення спричиняє помилки виявлення дублікатів. Дивіться [#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103). +
+ +
+Маркетплейс Codex встановлюється, але навички не завантажуються + +Запустіть перевірку кешу з чекауту ECC: + +```bash +node scripts/codex/check-plugin-cache.js +``` + +Якщо повідомляється про невирішені батьківські посилання, використовуйте `bash scripts/sync-ecc-to-codex.sh`. Реєстрація в `codex plugin list` підтверджує запис маркетплейсу, а не те, що кожен файл, на який є посилання, досягнув кешу плагіна. Завантаження навичок під час виконання з локальних/репо-маркетплейсів все ще ненадійне вище за течією ([openai/codex#26037](https://github.com/openai/codex/issues/26037)); дивіться [#2128](https://github.com/affaan-m/ECC/issues/2128) для повного дослідження. +
+ +
+Моє контекстне вікно скорочується + +Забагато MCP-серверів поглинає ваш контекст. Кожен опис MCP-інструменту витрачає токени з вашого вікна 200k, потенційно скорочуючи його до ~70k. Контекст SessionStart обмежений 8000 символами за замовчуванням; знизьте це за допомогою `ECC_SESSION_START_MAX_CHARS=4000` чи вимкніть за допомогою `ECC_SESSION_START_CONTEXT=off` для локальних моделей чи налаштувань з низьким контекстом. + +**Виправлення:** вимкніть невикористовувані MCP з Claude Code за допомогою `/mcp`. Claude Code записує ці вибори часу виконання в `~/.claude.json`; `.claude/settings.json` та `.claude/settings.local.json` не є надійними перемикачами для вже завантажених MCP-серверів. + +Тримайте менше 10 увімкнених MCP та менше 80 активних інструментів. +
+ +
+Чи можу я використовувати лише деякі компоненти (наприклад, лише агентів)? + +Так. Використовуйте ручні копії компонентів у [Розширених опціях встановлення](#розширені-опції-встановлення) та копіюйте лише те, що вам потрібно: + +```bash +# Лише агенти +cp agents/*.md ~/.claude/agents/ + +# Лише правила +mkdir -p ~/.claude/rules/ecc/ +cp -r rules/common ~/.claude/rules/ecc/ +``` + +Кожен компонент повністю незалежний. +
+ +
+Чи це працює з Cursor / OpenCode / Codex / Antigravity / GitHub Copilot? + +Так. ECC є крос-платформним: +- **Cursor**: попередньо перекладені конфіги в `.cursor/`. Дивіться [Підтримку платформ](#підтримка-платформ). +- **Gemini CLI**: експериментальна локальна для проєкту підтримка через `.gemini/GEMINI.md` та спільну сантехніку інсталятора. +- **OpenCode**: бета-інтеграція плагіна в `.opencode/`; вибір моделі провайдера та паритет каталогу залишаються обмеженими. +- **Codex**: підтримуваний шлях репо/синхронізації для macOS-додатка та CLI; пакет маркетплейсу ECC залишається експериментальним. +- **GitHub Copilot (VS Code)**: шар інструкцій та промптів через `.github/copilot-instructions.md`, `.vscode/settings.json` та `.github/prompts/`. +- **Antigravity**: щільно інтегроване налаштування для процесів, навичок та вирівняних правил в `.agent/`. Дивіться [Посібник з Antigravity](../../docs/ANTIGRAVITY-GUIDE.md). +- **JoyCode / CodeBuddy**: локальні для проєкту вибіркові адаптери встановлення для команд, агентів, навичок та вирівняних правил. Дивіться [Посібник з адаптера JoyCode](../../docs/JOYCODE-GUIDE.md). +- **Qwen CLI**: домашній вибірковий адаптер встановлення для команд, агентів, навичок, правил та конфігурації Qwen. Дивіться [Посібник з адаптера Qwen CLI](../../docs/QWEN-GUIDE.md). +- **Zed**: локальний для проєкту вибірковий адаптер встановлення для `.zed/settings.json`, вирівняних правил, команд, агентів та навичок. +- **Не-нативні оболонки**: ручний резервний шлях для чат-подібних інтерфейсів. Дивіться [Посібник з ручної адаптації](../../docs/MANUAL-ADAPTATION-GUIDE.md). +- **Claude Code**: нативно. Це основна ціль. +
+ +
+Моєї платформи немає в списку + +Використовуйте [посібник з ручної адаптації](../../docs/MANUAL-ADAPTATION-GUIDE.md), чи відкрийте [обговорення GitHub](https://github.com/affaan-m/ECC/discussions) з назвою оболонки та форматами файлів, навичок, команд і хуків, які вона підтримує. +
## Запуск тестів @@ -1037,274 +1828,57 @@ node tests/lib/package-manager.test.js node tests/hooks/hooks.test.js ``` ---- - -## Участь у розробці - -**Внески вітаються та заохочуються.** - -Цей репозиторій призначений бути ресурсом спільноти. Якщо у вас є: -- Корисні агенти або навички -- Розумні хуки -- Кращі конфігурації MCP -- Покращені правила - -Будь ласка, зробіть внесок! Дивіться [CONTRIBUTING.md](../../CONTRIBUTING.md) для настанов. - -### Ідеї для внесків - -- Мовноспецифічні навички (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, TypeScript та HarmonyOS/ArkTS вже включені -- Конфіги для фреймворків (Rails, FastAPI) — Django, NestJS, Spring Boot та Laravel вже включені -- DevOps-агенти (Kubernetes, Terraform, AWS, Docker) -- Стратегії тестування (різні фреймворки, візуальна регресія) -- Доменні знання (ML, інженерія даних, мобільна розробка) - ---- - -## Підтримка Cursor IDE - -ECC надає підтримку Cursor IDE з хуками, правилами, агентами, навичками, командами та конфігами MCP, адаптованими для макету проєктів Cursor. - -### Швидкий старт (Cursor) - -```bash -# macOS/Linux -./install.sh --target cursor typescript -./install.sh --target cursor python golang swift php -``` - -```powershell -# Windows PowerShell -.\install.ps1 --target cursor typescript -.\install.ps1 --target cursor python golang swift php -``` - -### Що включено - -| Компонент | Кількість | Деталі | -|-----------|-------|---------| -| Події хуків | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt та ще 10 | -| Скрипти хуків | 16 | Тонкі Node.js-скрипти, що делегують до `scripts/hooks/` через спільний адаптер | -| Правила | 34 | 9 загальних (alwaysApply) + 25 мовноспецифічних (TypeScript, Python, Go, Swift, PHP) | -| Агенти | 48 | `.cursor/agents/ecc-*.md` при встановленні; з префіксом для уникнення конфліктів | -| Навички | Спільні + вбудовані | `.cursor/skills/` для перекладених доповнень | -| Команди | Спільні | `.cursor/commands/` якщо встановлено | -| Конфіг MCP | Спільний | `.cursor/mcp.json` якщо встановлено | - -### Архітектура хуків (DRY-патерн адаптера) - -Cursor має **більше подій хуків, ніж Claude Code** (20 проти 8). Модуль `.cursor/hooks/adapter.js` перетворює вхідний JSON Cursor у формат Claude Code, дозволяючи повторно використовувати існуючі `scripts/hooks/*.js` без дублювання. - -``` -Вхідний JSON Cursor → adapter.js → перетворює → scripts/hooks/*.js - (спільний з Claude Code) -``` - ---- - -## Підтримка Codex macOS App + CLI - -ECC надає **першокласну підтримку Codex** як для macOS-додатка, так і для CLI, з еталонною конфігурацією, Codex-специфічним доповненням AGENTS.md та спільними навичками. - -### Швидкий старт (Codex App + CLI) - -```bash -# Запустіть Codex CLI в репозиторії — AGENTS.md та .codex/ виявляються автоматично -codex - -# Автоматичне налаштування: синхронізація активів ECC у ~/.codex -npm install && bash scripts/sync-ecc-to-codex.sh -``` - -### Ключове обмеження - -Codex **поки не забезпечує паритет виконання хуків у стилі Claude**. Виконання ECC там базується на інструкціях через `AGENTS.md`, необов'язкові перевизначення `model_instructions_file` та налаштування пісочниці/затвердження. - ---- - -## Підтримка Zed - -ECC надає підтримку проєктів Zed через консервативний адаптер `.zed` для локальних налаштувань проєкту, вирівняних правил, агентів, команд та навичок. - -```bash -./install.sh --profile minimal --target zed -``` - ---- - -## Підтримка OpenCode - -ECC надає **повну підтримку OpenCode**, включаючи плагіни та хуки. - -### Паритет функцій - -| Функція | Claude Code | OpenCode | Статус | -|---------|---------------------|----------|--------| -| Агенти | 67 агентів | 12 агентів | **Claude Code лідирує** | -| Команди | 92 команди | 35 команд | **Claude Code лідирує** | -| Навички | 271 навичка | 37 навичок | **Claude Code лідирує** | -| Хуки | 8 типів подій | 11 подій | **OpenCode більше!** | -| Правила | 29 правил | 13 інструкцій | **Claude Code лідирує** | -| MCP-сервери | 14 серверів | Повний | **Повний паритет** | -| Власні інструменти | Через хуки | 6 нативних інструментів | **OpenCode краще** | - ---- - -## Підтримка GitHub Copilot - -ECC надає **підтримку GitHub Copilot** для VS Code через нативну систему інструкційних та промпт-файлів Copilot Chat — без додаткових інструментів. - -### Що включено - -| Компонент | Файл | Призначення | -|-----------|------|---------| -| Основні інструкції | `.github/copilot-instructions.md` | Завжди завантажувані правила: стиль коду, безпека, тестування, git-процес | -| Налаштування VS Code | `.vscode/settings.json` | Файли інструкцій для конкретних завдань | -| Промпт plan | `.github/prompts/plan.prompt.md` | Поетапне планування реалізації | -| Промпт TDD | `.github/prompts/tdd.prompt.md` | Цикл Червоний-Зелений-Покращення | -| Промпт перевірки безпеки | `.github/prompts/security-review.prompt.md` | Глибокий аналіз безпеки за OWASP | -| Промпт виправлення збирання | `.github/prompts/build-fix.prompt.md` | Систематичне вирішення помилок збирання | -| Промпт рефакторингу | `.github/prompts/refactor.prompt.md` | Очищення мертвого коду | - -### Обмеження - -GitHub Copilot не має системи хуків або API підагентів, тому автоматизації хуків ECC (автоформат, перевірка TypeScript, збереження сесій, захист від dev-сервера) та делегування агентів недоступні. Шар інструкцій та промптів все ж привносить повну філософію кодування ECC — стандарти, безпеку, TDD та процес — у кожну сесію Copilot Chat. - ---- - -## Паритет функцій між інструментами - -ECC — **перший плагін, що максимізує можливості кожного основного інструменту ШІ-кодування**. Порівняння оболонок: - -| Функція | Claude Code | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot | -|---------|-----------------------|------------|-----------|----------|----------------| -| **Агенти** | 67 | Спільні (AGENTS.md) | Спільні (AGENTS.md) | 12 | Немає | -| **Команди** | 92 | Спільні | На основі інструкцій | 35 | 5 промптів | -| **Навички** | 271 | Спільні | 10 (нативний формат) | 37 | Через інструкції | -| **Події хуків** | 8 типів | 15 типів | Немає | 11 типів | Немає | -| **Правила** | 34 (common + lang) | 34 (YAML frontmatter) | На основі інструкцій | 13 інструкцій | 1 завжди-увімкнений файл | -| **Власні інструменти** | Через хуки | Через хуки | Немає | 6 нативних інструментів | Немає | -| **MCP-сервери** | 14 | Спільні (mcp.json) | 7 | Повний | Немає | -| **Конфіг** | settings.json | hooks.json + rules/ | config.toml | opencode.json | copilot-instructions.md + settings.json | -| **Файл контексту** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md | copilot-instructions.md | - -**Ключові архітектурні рішення:** -- **AGENTS.md** у корені є універсальним крос-інструментальним файлом (читається Claude Code, Cursor, Codex та OpenCode — GitHub Copilot використовує `.github/copilot-instructions.md`) -- **Патерн DRY-адаптера** дозволяє Cursor повторно використовувати скрипти хуків Claude Code без дублювання -- **Формат навичок** (SKILL.md з YAML frontmatter) працює у Claude Code, Codex та OpenCode -- Відсутність хуків у Codex компенсується `AGENTS.md`, необов'язковими перевизначеннями `model_instructions_file` та дозволами пісочниці - ---- - ## Передісторія -Я використовую Claude Code з моменту експериментального впровадження. Виграв хакатон Anthropic x Forum Ventures у вер. 2025 разом з [@DRodriguezFX](https://x.com/DRodriguezFX) — побудував [zenith.chat](https://zenith.chat) повністю за допомогою Claude Code. +Я використовую Claude Code з моменту експериментального впровадження. Виграв хакатон Anthropic x Forum Ventures у вер. 2025 разом з [@DRodriguezFX](https://x.com/DRodriguezFX) — побудував [zenith.chat](https://zenith.chat) повністю за допомогою агентних процесів. Ці конфіги перевірені в кількох продакшн-додатках. ---- +## Спільнота та проєкт -## Оптимізація токенів +
+Спонсори та ECC Pro -Використання Claude Code може бути дорогим, якщо не керувати споживанням токенів. Ці налаштування значно знижують витрати без шкоди для якості. +ECC залишається безкоштовним, тому що спонсори та Pro-користувачі фінансують роботу. Логотипи спонсорів вгорі цього README; повний список та рівні в [SPONSORS.md](../../SPONSORS.md). -### Рекомендовані налаштування +ECC Pro додає аналіз приватних репозиторіїв, аудити, викликані PR, сканування на основі AgentShield, автоматичні перевірки push та PR, об'єднане командне використання та пріоритетну підтримку через розміщений GitHub App. -Додайте до `~/.claude/settings.json`: + + + + + + + +
ECC Pro
Розміщений GitHub App для приватних репозиторіїв		Спонсорувати ECC
Фінансувати OSS-роботу		Спільнота
Питання, ідеї та Show and Tell		GitHub App
Аудити PR та розміщені процеси
-```json -{ - "model": "sonnet", - "env": { - "MAX_THINKING_TOKENS": "10000", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" - } -} -``` +[Стати спонсором](https://github.com/sponsors/affaan-m) | [Рівні спонсорства](../../SPONSORS.md) | [Програма спонсорства](../../SPONSORING.md) +
-| Налаштування | Стандарт | Рекомендовано | Ефект | -|---------|---------|-------------|--------| -| `model` | opus | **sonnet** | ~60% скорочення витрат; справляється з 80%+ завдань кодування | -| `MAX_THINKING_TOKENS` | 31 999 | **10 000** | ~70% скорочення прихованих витрат на міркування за запит | -| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Компакшн раніше — краща якість у довгих сесіях | -| `ECC_CONTEXT_MONITOR_COST_WARNINGS` | увімк | **вимк для підписників** | Пригнічує попередження оцінок API-рейту, зберігаючи попередження контексту/обсягу/циклів | +
+Участь у розробці -Переходьте на Opus лише для глибокого архітектурного міркування: -``` -/model opus -``` +Внески вітаються в навичках, агентах, правилах, хуках, документації, тестах, адаптерах та покращеннях безпеки. -### Команди щоденного процесу +- [Посібник з внесків](../../CONTRIBUTING.md) +- [Посібник з розробки навичок](../../docs/SKILL-DEVELOPMENT-GUIDE.md) +- [Політика розміщення навичок](../../docs/SKILL-PLACEMENT-POLICY.md) +- [Швидкий довідник команд](../../COMMANDS-QUICK-REF.md) -| Команда | Коли використовувати | -|---------|-------------| -| `/model sonnet` | Стандарт для більшості завдань | -| `/model opus` | Складна архітектура, налагодження, глибоке міркування | -| `/clear` | Між непов'язаними завданнями (безкоштовно, миттєве скидання) | -| `/compact` | У логічних точках зупинки завдань | -| `/cost` | Моніторинг витрат токенів під час сесії | +Коротка версія: +1. Зробіть форк репозиторію +2. Створіть навичку в `skills/your-skill-name/SKILL.md` (з YAML frontmatter) +3. Або створіть агента в `agents/your-agent.md` +4. Надішліть PR з чітким описом того, що він робить і коли використовувати -### Стратегічний компакшн +**Ідеї для внесків:** -Навичка `strategic-compact` пропонує `/compact` у логічних точках зупинки замість покладання на автокомпакшн при 95% контексту. - -**Коли компактувати:** -- Після дослідження/вивчення, перед реалізацією -- Після завершення milestone, перед початком наступного -- Після налагодження, перед продовженням роботи з функцією -- Після невдалого підходу, перед спробою нового - -**Коли НЕ компактувати:** -- В середині реалізації (ви втратите назви змінних, шляхи до файлів, частковий стан) - ---- - -## ПОПЕРЕДЖЕННЯ: Важливі примітки - -### Оптимізація токенів - -Досягаєте щоденних лімітів? Дивіться **[Посібник з оптимізації токенів](../../docs/token-optimization.md)**. - -Швидкі виграші: - -```json -// ~/.claude/settings.json -{ - "model": "sonnet", - "env": { - "MAX_THINKING_TOKENS": "10000", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", - "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" - } -} -``` - -### Налаштування - -Ці конфіги підходять для мого процесу. Вам слід: -1. Почати з того, що резонує -2. Змінити для вашого стеку -3. Видалити те, що ви не використовуєте -4. Додати власні патерни - ---- - -## Безпека - -ECC серйозно ставиться до безпеки ланцюжка поставок та агентної безпеки. - -- **Лише офіційні джерела.** Встановлюйте ECC лише з перевірених каналів, перелічених у банері вгорі цього README. -- **Повідомте про вразливість.** Використовуйте приватний процес у [SECURITY.md](../../SECURITY.md) (приватне звітування про вразливість GitHub). Будь ласка, не відкривайте публічні issues для звітів про безпеку. -- **Вбудовані захисні механізми.** GateGuard захищає деструктивні команди оболонки перед їх виконанням; сканер IOC ланцюжка поставок запускається в CI; [AgentShield](#agentshield--аудитор-безпеки) перевіряє ваш агент, хуки, MCP, дозволи та секретні поверхні (`/security-scan`). -- **Детальна інформація.** Дивіться [Посібник з безпеки](../../the-security-guide.md). - ---- - -## Спонсори - -Основні спонсори вказані вгорі цього README — повний список та рівні в [SPONSORS.md](../../SPONSORS.md). [Стати спонсором](https://github.com/sponsors/affaan-m). - ---- +- Мовноспецифічні навички (Rust, C#, Kotlin, Java): Go, Python, Perl, Swift, TypeScript та HarmonyOS/ArkTS вже включені +- Конфіги для фреймворків (Rails, FastAPI): Django, NestJS, Spring Boot та Laravel вже включені +- DevOps-агенти (Kubernetes, Terraform, AWS, Docker) +- Стратегії тестування (різні фреймворки, візуальна регресія) +- Доменні знання (ML, інженерія даних, мобільна розробка) +
## Посилання @@ -1313,12 +1887,8 @@ ECC серйозно ставиться до безпеки ланцюжка п - **Посібник з безпеки:** [Посібник з безпеки](../../the-security-guide.md) | [Нитка](https://x.com/affaan/status/2033263813387223421) - **Підписатись:** [@affaan](https://x.com/affaan) ---- - ## Ліцензія -MIT — Використовуйте вільно, змінюйте за потреби, робіть внески якщо можете. +MIT. Використовуйте вільно, адаптуйте під свій процес та робіть внески, коли можете. ---- - -**Поставте зірку цьому репозиторію, якщо він допоміг вам. Читайте обидва посібники. Будуйте щось чудове.** +**Поставте зірку цьому репозиторію, якщо він допоміг. Читайте посібники. Будуйте щось чудове.** \ No newline at end of file