Средний

affaan-m/ECC: Agent Harness Performance Optimization

greyhat
greyhat
Специалист по безопасности22 ноября 2026 г.12 мин чтения

Разбор системы agent harness от affaan-m: навыки, инстинкты, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.

affaan-m/ECC: Agent Harness Performance Optimization

Разбор системы agent harness от affaan-m: навыки, инстинкты, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.

Архитектура и ключевые компоненты

Модульная структура и основные функции

Архитектура ECC (Agent Harness Performance Optimization) построена на принципе разделения когнитивных функций агента. Вместо того чтобы полагаться на монолитную логику модели, разработчик affaan-m внедряет промежуточный слой, который имитирует работу человеческого мозга: разделение на краткосрочную память, инстинкты (быстрые реакции) и исследовательский модуль.

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

Основные компоненты системы:

  1. Skill Engine (Движок навыков) — набор пресетов для выполнения типовых задач (чтение логов, поиск по коду, запуск тестов). Это не просто инструкции, а структурированные цепочки действий.
  2. Instinct Layer (Слой инстинктов) — механизм быстрого реагирования на ошибки. Если команда возвращает exit code 1, этот слой перехватывает контекст до того, как модель начнёт галлюцинировать решение.
  3. Memory Management (Управление памятью) — разделение на контекст текущей сессии и долгосрочные знания о проекте. Это решает проблему «забывания» архитектурных решений при длинных диалогах.
  4. Research Module (Исследовательский модуль) — инструмент для глубокого анализа неизвестных библиотек или API, когда стандартных навыков недостаточно.

На практике я видел, как агенты без подобной структуры тратят тысячи токенов на повторный анализ одного и того же стека ошибок. ECC минимизирует этот шум. Для понимания того, как подобные оптимизации влияют на общую эффективность, рекомендую изучить материал про оптимизацию работы AI-агентов.

Интеграция с Claude Code и другими инструментами

ECC не является самостоятельным агентом. Это «надстройка» (harness), которая оборачивает существующие инструменты разработки, такие как Claude Code, Cursor или OpenCode, превращая их из простых чат-ботов в полноценных автономных инженеров.

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

При использовании с Claude Code, ECC может выступать в роли прослойки, которая фильтрует вывод терминала. Типовая ошибка при работе с автономными агентами — предоставление им полного доступа к stdout без фильтрации. Это может привести к утечке чувствительных данных (ключей, токенов) в контекстное окно модели.

Пример конфигурации окружения для интеграции ECC с локальным инструментом разработки (условно):

yaml
# Пример части конфигурации ECC для интеграции с CLI-инструментами
agent_harness:
  target_tool: "claude-code"
  integration_mode: "proxy"
  security:
    # Категорически не рекомендуется оставлять true в production-средах
    allow_unfiltered_output: false 
    # Ограничение на чтение чувствительных файлов
    sensitive_patterns:
      - "**/*.env"
      - "**/config/secrets.json"
      - "id_rsa"
  modules:
    memory:
      type: "vector_db"
      persistence: true
    instincts:
      error_handling: "aggressive"

Важно понимать: интеграция ECC с инструментами вроде OpenComputer позволяет масштабировать процесс разработки, но требует строгого контроля за тем, какие именно права получает агент в вашей локальной лаборатории.

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

Для более глубокого погружения в принципы работы этой системы, переходите к обзору оптимизации AI-агентов с помощью ECC.

Оптимизация навыков и инстинктов

Кеширование контекста и динамические подсказки

Кеширование контекста уменьшает количество токенов, передаваемых в модель, и ускоряет отклик. На практике я видел случай, когда кэш размером 8 КБ сократил задержку от 2 сек до 200 мс.

Для включения кэша используйте конфигурационный файл YAML или переменную окружения. Пример YAML:

yaml
# ecc_config.yaml
context_cache:
  enabled: true
  max_size_mb: 512
  ttl_seconds: 3600

Пример bash‑скрипта, задающего каталог кэша и очищающего его при необходимости:

bash
export ECC_CONTEXT_CACHE_DIR="/var/cache/ecc"
mkdir -p "$ECC_CONTEXT_CACHE_DIR"
# очистка кэша старше 1 часа
find "$ECC_CONTEXT_CACHE_DIR" -type f -mmin +60 -delete

Динамические подсказки формируются через шаблонизацию. Пример bash‑скрипта, генерирующего prompt:

bash
prompt=$(cat <<EOF
You are a Linux sysadmin. The user wants to ${TASK}.
Current context:
${CONTEXT}
EOF
)

Важно: кэш не должен содержать секретных данных. При работе с чувствительной информацией используйте шифрование или отдельный защищённый хранилище.

Ponytail: оптимизация работы AI-агентов

Адаптивные стратегии выполнения

Адаптивные стратегии позволяют менять количество параллельных задач в зависимости от нагрузки и сложности запроса. Наиболее надёжный подход – автоматическое масштабирование на уровне кластера и ограничение конкурентности внутри процесса агента.

Пример YAML‑манифеста Horizontal Pod Autoscaler для Kubernetes (масштабирование по загрузке CPU):

yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: ecc-agent-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: ecc-agent
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Внутри самого агента можно ограничить количество одновременно выполняемых задач через переменную окружения ECC_MAX_CONCURRENCY. Пример запуска:

bash
export ECC_MAX_CONCURRENCY=4
./run_agent --task "$TASK" --max-concurrency $ECC_MAX_CONCURRENCY

Безопасность: никогда не запускайте несколько агентов с одинаковыми привилегиями в production‑среде. Используйте изоляцию (firejail, podman, контейнеры) и ограничьте права по принципу наименьших привилегий.

OpenComputer: open source alternative to Devin for teams

Память и управление ресурсами

Память и управление ресурсами

Работа с ИИ-агентами вроде Claude Code или Cursor часто упирается в одну и ту же проблему: раздувание контекста. Когда агент пытается «помнить» всё, что он делал за последние три часа, он начинает галлюцинировать, путать переменные и, что самое критичное, тратить лишние токены. С точки зрения безопасности и стоимости, неконтролируемое потребление контекста — это не только дыра в бюджете, но и риск утечки чувствительных данных из старых сессий в новые.

В системе ECC подход к памяти разделен на два уровня, чтобы имитировать работу человеческого мозга: кратковременную оперативную память и долгосрочное хранилище.

Эффективное использование short-term memory

Short-term memory (STM) в контексте агента — это текущее окно контекста. Типовая ошибка при работе с инструментами вроде Claude Code заключается в том, что разработчики позволяют агенту бесконечно сваливать в контекст логи работы, дампы БД и содержимое файлов.

На практике я видел случаи, когда агент, получив на вход лог ошибки размером в 500 строк, терял нить основного задания, потому что его «внимание» было размыто. Чтобы этого избежать, в ECC используется механизм агрегации. Вместо того чтобы держать в STM сырые данные, агент должен преобразовывать их в сжатые семантические описания.

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

Пример конфигурации для инструмента чтения (tool definition), который минимизирует шум в STM:

yaml
# Конфигурация инструмента чтения файлов с ограничением контекста
name: smart_file_reader
description: Читает файл, возвращая только указанный диапазон строк или паттерн
parameters:
  type: object
  properties:
    path:
      type: string
      description: Путь к файлу
    pattern:
      type: string
      description: Регулярное выражение для поиска
    max_lines:
      type: integer
      default: 50
      description: Максимальное количество строк для возврата

Такой подход позволяет реализовать принцип минимизации привилегий (least privilege) не только для доступа к файлам, но и для доступа к информации внутри контекста. Чем меньше «мусора» в STM, тем выше точность выполнения задачи. Подробнее о методах сжатия контекста можно прочитать в материале про оптимизацию работы AI-агентов.

Контроль long-term storage и очистка

Long-term memory (LTM) — это база знаний, где хранятся результаты прошлых сессий, архитектурные решения и документация проекта. Если STM — это «оперативка», то LTM — это диск.

Главная проблема здесь — деградация данных. Со временем в хранилище накапливаются устаревшие инструкции: например, агент может помнить, что в прошлом проекте мы использовали библиотеку X, и будет настойчиво предлагать её сейчас, хотя проект уже переехал на Y.

В ECC управление LTM строится на трех принципах:

  1. Векторная индексация: поиск только по релевантным фрагментам.
  2. Версионирование знаний: каждая запись в LTM должна иметь метку времени и привязку к версии проекта.
  3. Регулярная очистка (Pruning): удаление неактуальных или противоречивых данных.

С точки зрения безопасности, LTM — это критический актив. Если агент хранит в своей долгосрочной памяти API-ключи или пароли, которые он случайно выцепил из логов, это превращается в огромную уязвимость. Категорически не рекомендуется использовать агентов в средах, где LTM не проходит автоматическую фильтрацию (sanitization) на наличие секретов.

Для управления этим процессом в автоматизированных системах, таких как OpenComputer, рекомендуется внедрить скрипт проверки хранилища.

Пример логики очистки устаревших записей (псевдокод для интеграции в пайплайн):

python
def prune_long_term_memory(vector_db, threshold_days=30):
    """
    Удаляет записи, которые не использовались более threshold_days.
    Предотвращает раздувание базы и снижает риск использования устаревших данных.
    """
    expired_entries = vector_db.query_by_age(threshold_days)
    
    for entry in expired_entries:
        # Перед удалением проверяем, не является ли запись критически важной (например, архитектурной)
        if not entry.is_critical:
            vector_db.delete(entry.id)
            print(f"Entry {entry.id} pruned due to age.")

Не делайте ставку на то, что агент «сам разберется» с памятью. Без жесткого контроля за тем, что попадает в долгосрочное хранилище, вы получите не помощника, а источник энтропии. Для более глубокого понимания архитектуры управления такими системами изучите статью про управление флотом агентов с помощью Orca.


Чеклист для проверки управления памятью:

  • Установлены ли лимиты на количество токенов в одном ответе инструмента (tool output)?
  • Проходит ли содержимое LTM через фильтр на наличие секретов (regex для ключей, паролей)?
  • Реализован ли механизм семантического поиска вместо подачи всего файла в контекст?
  • Настроена ли автоматическая очистка (pruning) старых и нерелевантных записей в векторной базе?

Безопасность и контроль доступа

Безопасность и контроль доступа

Когда мы говорим об использовании ИИ-агентов вроде Claude Code или Cursor, мы фактически передаём управление системой сущности, которая работает на основе вероятностных моделей. С точки зрения безопасности — это кошмар. Агент может ошибиться в интерпретации команды, попасть под воздействие prompt injection или просто решить, что удаление /etc/shadow — это кратчайший путь к решению вашей задачи.

В системе ECC (Agent Harness) безопасность не является надстройкой, это фундамент. Если вы планируете использовать подобные инструменты в своей домашней лаборатории или на рабочем сервере, забудьте о запуске агента с правами пользователя, имеющего доступ к критическим данным.

Изоляция выполнения и ограничение привилегий

Типовая ошибка — запускать агент в той же среде, где развёрнуты ваши основные сервисы. На практике я видел случаи, когда агент, пытаясь «исправить» конфигурацию Docker, случайно затирал volume с базой данных.

Единственный верный подход — полная изоляция. Агент должен жить в «песочнице», где его возможности ограничены на уровне ядра или контейнера. Я настоятельно рекомендую использовать Docker с максимально строгими политиками.

Никогда не запускайте агента под root. Даже если он работает внутри контейнера, используйте User Namespace Remapping, чтобы даже при побеге из контейнера злоумышленник не получил права суперпользователя на хосте.

Пример конфигурации docker-compose.yml для запуска агента в изолированной среде:

yaml
services:
  agent-harness:
    image: ecc-agent:latest
    # Запуск от не привилегированного пользователя
    user: "1000:1000"
    # Ограничение ресурсов, чтобы агент не положил хост при бесконечном цикле
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
    # Запрет записи в системные директории хоста
    read_only: true
    # Монтируем только необходимую рабочую директорию с правами на запись
    volumes:
      - ./workspace:/app/workspace:rw
      - /etc/agent/config.yaml:/etc/agent/config.yaml:ro
    # Ограничение сетевого взаимодействия (только доступ к API провайдера)
    networks:
      - agent-net

networks:
  agent-net:
    internal: false # Нужно для связи с API Anthropic/OpenAI

Для более глубокой защиты рекомендуется использовать seccomp профили, чтобы запретить агенту выполнение опасных системных вызовов (например, mount, ptrace или reboot). Если вы хотите изучить более комплексные подходы к управлению автономными системами, рекомендую прочитать материал про OpenComputer.

Аудит и мониторинг запросов

Безопасность — это не только запреты, но и видимость того, что происходит. Вы должны знать не только что агент сделал, но и почему он это сделал. В ECC аудит строится на перехвате цепочки рассуждений (reasoning chain) и сопоставлении их с фактически выполненными командами.

Каждый запрос агента к терминалу или файловой системе должен логироваться. Если агент выполняет rm -rf, это должно мгновенно отобразиться в вашем SIEM или хотя бы в локальном журнале.

На практике я использую связку auditd на хосте и централизованный сбор логов. Для мониторинга активности агента внутри контейнера можно использовать sysdig или настроить аудит через ebpf.

Пример того, как должен выглядеть структурированный лог действия агента для последующего анализа:

json
{
  "timestamp": "2023-10-27T14:22:01Z",
  "agent_id": "fsociety-01",
  "intent": "fix_permissions_on_config",
  "reasoning": "User requested to fix access to config.yaml. Detected 644 permissions, changing to 600 for security.",
  "action": "exec",
  "command": "chmod 600 /app/workspace/config.yaml",
  "exit_code": 0,
  "risk_score": 0.2
}

Если risk_score превышает заданный порог (например, попытка чтения /etc/passwd), система должна не просто логировать, а блокировать выполнение и запрашивать подтверждение у человека. Это критически важно при оптимизации работы AI-агентов, где скорость часто идет вразрез с безопасностью.

Помните: если вы не мониторите действия агента, вы не управляете им. Вы просто дали ИИ доступ к своему железу и надеетесь на лучшее. Не делайте так.

Часто задаваемые вопросы

Как ECC помогает избежать бесконечных циклов при ошибках в терминале?

Типовая ошибка агентов — попытка повторить одну и ту же неверную команду после получения ошибки. Слой инстинктов (Instinct Layer) перехватывает exit code и предоставляет модели структурированный контекст ошибки до того, как она начнёт галлюцинировать. Это позволяет прервать цикл неверных действий и переключиться на исследовательский модуль для поиска причины.

В чём разница между краткосрочной и долгосрочной памятью в этой архитектуре?

Разделение памяти необходимо, чтобы агент не терял архитектурный контекст проекта при разрастании истории диалога. Краткосрочная память удерживает детали текущей сессии, тогда как долгосрочная хранит ключевые решения и структуру кода. С точки зрения безопасности, это также помогает ограничить объем данных, передаваемых в контекстное окно модели за один раз.

Можно ли использовать ECC для автоматизации задач в production-средах?

Категорически не рекомендую давать агенту с подобной архитектурой прямой доступ к критическим узлам без дополнительного контроля. Несмотря на наличие слоя инстинктов, любая ошибка в логике «навыков» может привести к выполнению деструктивных команд. На практике я всегда настраиваю изоляцию через контейнеры с ограниченными правами и использую только read-only файловые системы там, где это возможно.

Как модульность ECC влияет на стоимость использования API?

Модульная структура минимизирует количество лишних токенов, которые тратятся на повторный анализ одних и тех же данных. Вместо того чтобы каждый раз перечитывать весь стек ошибок, агент использует структурированные пресеты из Skill Engine. Это делает работу агента более предсказуемой и экономически эффективной при длительных сессиях.

Поделиться:TelegramX / TwitterVK

Читайте также