affaan-m/ECC: Оптимизация производительности агента
Agent harness от affaan-m ускоряет Claude Code, Codex, Opencode, Cursor, сочетая навыки, инстинкты, память и безопасность.
Архитектура и компоненты ECC
Архитектура и компоненты ECC
Когда мы говорим об оптимизации работы ИИ-агентов, основная проблема заключается в «раздувании» контекста. Чем больше данных вы скармливаете модели, тем выше задержка (latency) и стоимость токенов. ECC (Engineered Context Control) решает это не за счёт уменьшения объёма данных, а за счёт их грамотной фильтрации и структурирования перед отправкой в LLM.
С точки зрения безопасности, такая архитектура также позволяет внедрить слой валидации: мы не просто передаём файлы в Claude Code, а пропускаем их через фильтры, которые отсекают чувствительные данные (secrets, ключи, конфиги с паролями) ещё до того, как они покинут ваш контур.
Модульная структура и распределение задач
ECC не является монолитным приложением. Это прослойка (harness), которая работает по принципу конвейера. Вместо того чтобы заставлять агента самостоятельно искать информацию по всему репозиторию, ECC разбивает процесс на три независимых модуля:
- Memory & Instinct Module: отвечает за хранение краткосрочного контекста сессии и долгосрочных паттернов разработки. Это позволяет избежать ситуации, когда агент забывает инструкции, данные три шага назад.
- Skill Orchestrator: распределяет задачи между специализированными под-агентами. Если задача требует работы с системными вызовами, оркестратор подготавливает окружение, минимизируя риск выполнения невалидных команд.
- Security & Context Filter: критически важный компонент. Он выполняет пре-процессинг контекста.
На практике это выглядит как разделение потоков данных. Если вы используете Ponytail для управления контекстом, то ECC дополняет этот подход, добавляя слой «инстинктов» — предугадывания того, какие именно файлы понадобятся агенту в следующей итерации.
Типовая ошибка при настройке подобных систем — предоставление агенту прямого доступа к корневой директории проекта без ограничений. В ECC это решается через создание изолированного рабочего пространства.
bash# Пример создания ограниченного окружения для работы агента
mkdir -p ./agent_workspace/sandbox
# Рекомендуется запускать агент в контейнере с ограниченными правами
docker run --rm -v $(pwd)/agent_workspace:/app:ro \
--security-opt no-new-privileges \
python:3.11-slim /bin/bash
Здесь флаг :ro (read-only) крайне важен: агент может читать код для анализа, но не может случайно или намеренно изменить системные файлы в вашей основной среде.
Интеграция с Claude Code и другими инструментами
ECC спроектирован как middleware. Он не заменяет Claude Code или Cursor, а встраивается в их цикл работы. Основной механизм интеграции — перехват запросов на чтение файлов и подмена их на оптимизированные «снимки» (snapshots) контекста.
При интеграции с Claude Code, ECC анализирует дерево проекта и формирует компактный context_map. Вместо того чтобы отправлять содержимое пятидесяти файлов, ECC передаёт только сигнатуры функций и ключевые комментарии, которые необходимы для решения текущей задачи.
Для разработчиков, которые рассматривают OpenComputer как альтернативу проприетарным решениям, ECC становится модулем, который можно подключить к любому open-source агенту для повышения его «интеллектуальной плотности».
Пример конфигурации интеграции ECC с локальным агентом через JSON-конфиг:
json{
"integration": {
"target": "claude-code",
"mode": "intercept",
"optimization_level": "aggressive"
},
"security": {
"mask_secrets": true,
"allowed_extensions": [".py", ".js", ".go", ".md"],
"forbidden_paths": ["**/config/*.env", "**/certs/*"]
},
"memory": {
"provider": "local-vector-db",
"retrieval_limit": 5
}
}
Настоятельно рекомендую всегда проверять секцию forbidden_paths. С точки зрения безопасности, если вы не ограничите доступ к .env файлам на уровне архитектуры агента, вы рискуете утечкой credentials в облако провайдера LLM.
Если ваша задача — масштабирование подобных решений на целую команду, стоит изучить подходы к управлению флотом ИИ-агентов с помощью Orca, так как ECC лучше всего работает в связке с централизованной системой управления.
Оптимизация навыков и инстинктов
Анализ паттернов поведения агента
Когда мы говорим об оптимизации таких инструментов, как Claude Code или Cursor, основная проблема заключается не в вычислительной мощности модели, а в неэффективном цикле «действие — реакция». Типовая ошибка при работе с AI-агентами — позволить им бесконечно перебирать варианты в попытке решить задачу, что приводит к раздуванию контекста и резкому росту стоимости запросов.
С точки зрения безопасности и производительности, ECC (Agent harness от affaan-m) внедряет слой, который анализирует паттерны поведения агента до того, как запрос уйдет на API. Вместо того чтобы просто транслировать ввод пользователя, система оценивает, является ли текущее действие агента повторяющимся или деструктивным.
На практике я видел случай, когда агент в цикле пытался исправить одну и ту же ошибку синтаксиса, каждый раз переписывая весь файл целиком. Без контроля паттернов это превращается в бесконечную трату токенов. ECC позволяет ограничить такие циклы на уровне инстинктов агента.
Для настройки ограничений на частоту определенных действий в конфигурации ECC рекомендуется использовать параметры контроля интентов. Пример упрощенного конфига для ограничения цикличных попыток правки кода:
yaml# ECC Agent Behavior Policy
behavior_control:
max_loop_iterations: 3 # Пресекаем бесконечные циклы самоисправления
pattern_recognition:
enabled: true
sensitivity: high # Высокая чувствительность к повторам команд
safety_check:
allow_destructive_commands: false # Запрет на выполнение rm -rf или подобных через агент
Если вы хотите глубже разобраться в том, как структурировать работу агентов, чтобы они не уходили в бесконечные циклы, рекомендую изучить материал про Ponytail: оптимизация работы AI-агентов.
Управление контекстом и памятью
Контекстное окно — это самый дорогой и ограниченный ресурс при работе с LLM. Чем больше «мусора» попадает в текущую сессию, тем выше вероятность галлюцинаций и тем медленнее работает агент. В ECC оптимизация памяти строится на разделении данных на краткосрочные (текущая задача) и долгосрочные (инстинкты и знания о проекте).
Вместо того чтобы скармливать агенту весь репозиторий, ECC использует механизм селективной памяти. Это позволяет держать в активном контексте только те фрагменты кода, которые непосредственно относятся к текущему паттерну задачи. Это концептуально близко к тому, как работают профессиональные инструменты вроде OpenComputer.
При настройке локального окружения для работы с ECC крайне важно контролировать, какие именно данные попадают в индекс памяти. Категорически не рекомендуется индексировать директории с бинарными файлами, логами или чувствительными данными (например, .env файлами).
Перед запуском агента убедитесь, что ваш .gitignore или специальный конфиг исключений ECC настроен корректно. С точки зрения безопасности, это критический шаг: агент не должен иметь возможности «прочитать» ваши секреты и отправить их в контекст запроса к Anthropic.
Пример настройки исключений для индексации памяти:
bash# Проверка содержимого директории перед индексацией (пример для проверки чистоты)
find . -maxdepth 2 -not -path '*/.*'
# В конфиге ECC указываем пути, которые должны быть полностью изолированы
memory_management:
indexing:
exclude_patterns:
- "**/*.log"
- "**/.env"
- "**/node_modules/**"
- "**/dist/**"
compression_level: high # Сжатие контекста для экономии токенов
Эффективное управление памятью — это не только экономия денег, но и стабильность системы. Если вы планируете масштабировать этот подход на несколько машин, стоит обратить внимание на Управление флотом ИИ-агентов с помощью Orca.
Для более детального понимания того, как ECC вписывается в общую архитектуру оптимизации, ознакомьтесь с Обзором системы ECC.
Безопасность и контроль доступа
### Изоляция процессов и ограничение привилегий
Для защиты агента от несанкционированного доступа используйте несколько слоёв изоляции.
1. Пользовательские namespace и cgroups
Запуск агента в отдельном пользовательском namespace гарантирует, что он не сможет влиять на хост‑систему, даже если работает от root внутри контейнера.
bashdocker run --rm \
--user 1001:1001 \
--read-only \
--security-opt=no-new-privileges \
--cap-drop=ALL \
--pids-limit=64 \
--name ecc-agent \
myimage:latest
2. AppArmor профиль
AppArmor ограничивает набор разрешённых системных вызовов. Пример профиля ecc-agent.profile:
apparmor#include <tunables/global> profile ecc-agent { #include <abstractions/base> /usr/local/bin/ecc-agent mr, /usr/share/ecc/** mrw, /etc/ecc/** r, deny /etc/** w, deny /tmp/** w, deny /var/log/** w, }
Запуск с профилем:
bashapparmor_parser -r /etc/apparmor.d/ecc-agent.profile docker run --security-opt apparmor_profile=ecc-agent /path/to/ecc-agent
3. firejail – лёгкий инструмент для ограничения сетевого доступа и доступа к файловой системе.
bashfirejail --net=none --private=~/ecc --netfilter --quiet /usr/local/bin/ecc-agent
4. Ограничение ресурсов
ulimit и параметры cgroup позволяют задать максимальное количество открытых файлов, процессов и объём памяти.
bashulimit -n 1024 # максимум открытых дескрипторов
systemd-run --scope -p MemoryLimit=200M /usr/local/bin/ecc-agent
5. Практика
На практике я видел случай, когда агент, запущенный без ограничения привилегий, получил доступ к /etc/passwd и смог выполнить скрипт с правами root. После применения вышеуказанных мер такой сценарий стал невозможен.
Подобный подход описан в OpenComputer: open source alternative to Devin for teams.
### Автоматический аудит и мониторинг
Необходимо обеспечить непрерывный аудит действий агента и быстрый отклик на подозрительные события.
1. auditd – базовый механизм аудита ядра Linux.
bash# Записывать все попытки исполнения бинарника агента
auditctl -w /usr/local/bin/ecc-agent -p x -k ecc_agent_exec
# Мониторить изменения конфигурационных файлов
auditctl -w /etc/ecc/ -p wa -k ecc_config_change
2. journalctl – централизованный журнал системных событий.
bash# Следить за событиями агента в реальном времени
journalctl -u ecc-agent -f
# Фильтровать по метке, установленной auditd
journalctl _COMM=ecc-agent _AUDIT=ecc_agent_exec
3. fail2ban / crowdsec – автоматические блокировки по паттернам в логах.
ini# fail2ban filter (ecc-agent.conf)
[Definition]
failregex = ^.*\[ecc-agent\] .*Failed to authenticate.*$
ignoreregex =
4. Wazuh – open‑source SIEM, поддерживает аудит, мониторинг файлов и интеграцию с Prometheus.
yaml# wazuh-agent.yaml
log_path = /var/log/ecc/agent.log
alert_status = enabled
5. Prometheus + Grafana – метрики производительности и health‑checks.
yaml# prometheus.yml
scrape_configs:
- job_name: 'ecc-agent'
static_configs:
- targets: ['localhost:9100']
6. Loki – агрегация логов, удобна для поиска по запросу.
logql{job="ecc-agent"} |~ "ERROR"
7. Системный watchdog – автоматический перезапуск при зависании.
ini# systemd unit fragment
[Service]
WatchdogSec=30
Restart=on-failure
RestartSec=5
8. Оповещения
При превышении порога (например, более 5 ошибок за минуту) генерируется событие, которое может быть отправлено в webhook‑службу (Slack, Telegram‑бот и т.п.).
Для управления несколькими агентами в кластере рекомендуется посмотреть Оптимизация AI-агентов с помощью системы ECC и Управление флотом ИИ-агентов с помощью Orca.
Подробный обзор методов изоляции и аудита можно найти в Обзор OpenComputer: open source агент для разработки.
Исследовательский подход и постоянное улучшение
Исследовательский подход и постоянное улучшение
В работе с ECC я опираюсь на проверенные практики изоляции и автоматизацию. На практике я видел случай, когда агент, запущенный без ограничений, начал использовать сетевые порты, которых не было в политике iptables, что привело к непредвиденному сканированию внешних ресурсов. Поэтому каждый запуск проходит в песочной среде, а результаты тестов фиксируются в CI/CD‑pipeline.
Тестирование в изоляции (sandbox)
Для изоляции использую Docker контейнер с полным запретом сетевого доступа и ограничениями в капсулах. Пример запуска тестового режима агента:
bashdocker run --rm \
--network=none \
--security-opt=no-new-privileges \
--cpu-quota=50000 \
-v "$(pwd)/sandbox:/work" \
affaan-m/ecc-agent:latest \
--mode test
--network=none— полностью отключает сетевой стек, только если агент требует сетевого доступа, добавляем отдельный network‑namespace.--security-opt=no-new-privileges— запрещает получение новых привилегий внутри контейнера.--cpu-quota=50000— ограничивает использование CPU, что предотвращает DoS‑атаки внутри sandbox.
Для дополнительной защиты применяю firejail и seccomp‑профиль:
bashfirejail --net=none --caps.drop=all --quiet docker run \
--security-opt=no-new-privileges \
-v "$(pwd)/sandbox:/work" \
affaan-m/ecc-agent:latest \
--mode test
seccomp‑файл (seccomp.json) ограничивает набор системных вызовов:
json{
"defaultAction": "SCMP_ACT_ERRNO",
"syscalls": [
{"name": "execve", "action": "SCMP_ACT_ALLOW"},
{"name": "openat", "action": "SCMP_ACT_ALLOW"},
{"name": "read", "action": "SCMP_ACT_ALLOW"},
{"name": "write", "action": "SCMP_ACT_ALLOW"},
{"name": "exit", "action": "SCMP_ACT_ALLOW"}
]
}
Запуск с seccomp:
bashdocker run --rm \
--network=none \
--security-opt seccomp=seccomp.json \
-v "$(pwd)/sandbox:/work" \
affaan-m/ecc-agent:latest \
--mode test
Тесты в sandbox позволяют убедиться, что агент не выходит за пределы своей задачи и не использует запрещённые операции. Результаты (stdout/stderr) сохраняются в лог‑файле, который затем анализируется в CI.
CI/CD пайплайны для ECC
Автоматизация построения и тестирования выглядит так (GitHub Actions):
yamlname: ECC CI
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: Build image
run: |
docker build -t affaan-m/ecc-agent:${{ github.sha }} .
- name: Run sandbox tests
run: |
docker run --rm \
--network=none \
--security-opt=no-new-privileges \
-v "${{ github.workspace }}/sandbox:/work" \
affaan-m/ecc-agent:${{ github.sha }} --mode test \
> sandbox.log 2>&1
- name: Verify test results
run: |
grep -q "PASS" sandbox.log || (echo "Tests failed" && exit 1)
- name: Push image (main only)
if: github.ref == 'refs/heads/main'
run: |
echo "${{ secrets.GITHUB_TOKEN }}" | docker login -u "${{ secrets.GITHUB_USER }}" --password-stdin
docker push affaan-m/ecc-agent:${{ github.sha }}
- build – собирает Docker‑образ с тегом, содержащим SHA‑хеш коммита.
- sandbox tests – запускает агент в изолированном контейнере, как описано выше, и сохраняет вывод в
sandbox.log. - Verify test results – проверяет, что в логе есть строка
PASS; при неудаче пайплайн останавливается. - Push image – публикует образ только из главной ветки, используя токен доступа.
Для более масштабного управления flotaми агентов применяю Orca (см. Управление флотом ИИ-агентов с помощью Orca). Orca позволяет задавать шаблоны запуска, мониторить статус и автоматически перезапускать контейнеры при провале тестов.
В каждом этапе pipeline я следую принципу «проверка → действие»: перед деплоем в продакшн запускаю отдельный набор интеграционных тестов в среде, имитирующей реальное окружение (например, с подключённым SSH‑доступом через bastion‑host). Это гарантирует, что оптимизации, внесённые в коде, не ломают совместимость с реальными рабочими сценариями.
Оптимизация AI-агентов с помощью системы ECC — подробный разбор подхода, который я применяю в данных пайплайнах.
Часто задаваемые вопросы
Как ECC снижает latency и стоимость токенов, не уменьшая объём данных?
ECC не просто обрезает контекст, а фильтрует и структурирует информацию, удаляя нерелевантные файлы, группируя похожие данные и применяя приоритетные инстинкты. Это позволяет передавать в LLM только те фрагменты, которые действительно влияют на решение задачи, тем самым уменьшая количество токенов и задержку. В результате агент работает быстрее и дешевле, а качество ответа не страдает.
Что делает модуль Security & Context Filter и как он защищает конфиденциальные данные?
Модуль Security & Context Filter выполняет пре‑процессинг контекста, сканируя все файлы и строки на наличие чувствительных данных (secrets, ключи, пароли). Он отсекает такие элементы до их отправки в Claude Code или другие LLM, используя правила валидации, прописанные в настройках. Это предотвращает утечку конфиденциальной информации и снижает риск эксплуатации уязвимостей.
Нужно ли дополнительно настраивать Ponytail, если уже используется ECC?
ECC дополняет подход Ponytail, добавляя слой «инстинктов», который предугадывает нужные файлы и оптимизирует их загрузку. Ponytail остаётся полезным для общей управляемости контекста, но его настройка не обязательна – ECC уже интегрирован в конвейер и может работать автономно. При наличии Ponytail рекомендуется убедиться, что его правила совместимы с фильтрацией ECC, чтобы избежать дублирования или конфликтов.
Как Memory & Instinct Module влияет на надёжность работы агента в длительных сессиях?
Memory & Instinct Module сохраняет краткосрочный и долгосрочный контекст, а также паттерны разработки, что предотвращает «забывание» инструкций и данных через несколько шагов. Это особенно важно в длительных сессиях, когда агент может потерять связность без постоянного хранения ключевых сведений. За счёт этого снижается вероятность ошибок выполнения команд и повышается стабильность работы агента.