Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization

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

The agent harness performance optimization system for Claude Code, Codex, Opencode, Cursor. Skills, instincts, memory, security, research‑first development.

affaan-m/ECC: Agent Harness Performance Optimization

The agent harness performance optimization system for Claude Code, Codex, Opencode, Cursor. Skills, instincts, memory, security, research‑first development.

Core Architecture and Performance Principles

Core Architecture and Performance Principles

Modular Skill Execution Model

В системе affaan-m/ECC каждый навык (skill) реализован как самостоятельный модуль, который может быть подключён или отключён без изменения остальной инфраструктуры. Это позволяет:

  • изолировать нагрузку и быстро отлаживать отдельные компоненты;
  • переиспользовать уже написанные скрипты в разных контекстах;
  • масштабировать количество параллельных выполнений без риска конфликтов состояний.

Пример конфигурации модульного пайплайна (YAML)

yaml
# pipeline.yaml
modules:
  - name: "fetch-sources"
    entrypoint: "python -m fetch_sources"
    schedule: "*/5 * * * *"
    resources:
      cpu: 0.5
      memory: 256Mi

  - name: "analyze-code"
    entrypoint: "docker run --rm -v ${{pwd}}:/work ghcr.io/affaan-m/ecc:latest analyze --mode fast"
    schedule: "0 2 * * *"
    resources:
      cpu: 1
      memory: 512Mi

  - name "generate-report"
    entrypoint: "python -m generate_report"
    depends_on: ["analyze-code"]
    resources:
      cpu: 0.7
      memory: 384Mi

Команда docker run в примере использует образ ghcr.io/affaan-m/ecc:latest, который уже содержит все необходимые зависимости. При необходимости можно заменить образ на локальный, разместив его на домашнем сервере.

Как подключить новый модуль

bash
# Добавляем модуль в pipeline.yaml
echo "- name: \"run-linter\"" >> pipeline.yaml
echo "  entrypoint: \"flake8 .\"" >> pipeline.yaml
echo "  schedule: \"*/10 * * **\"" >> pipeline.yaml

После изменения файла достаточно перезапустить агент:

bash
agentctl restart --pipeline

На практике я видел случай, когда без изоляции модулей один из скриптов «залипал» в бесконечном цикле и блокировал остальные задачи. Выделение ресурсов через cpu и memory в конфиге устранило проблему.

Подробнее о подходах к управлению пайплайнами — в статье Управление fleet-агентами разработки с Orca.

Memory Management Strategies

Эффективное управление памятью — ключ к стабильной работе агентов, особенно при работе с большими контекстами или при одновременном выполнении множества задач. В affaan-m/ECC применяются три проверенных стратегии:

  1. Кеширование результатов — хранение часто используемых данных в fast‑access хранилище (Redis) с TTL.
  2. Ограничение размеров буферов — каждый модуль получает ограничение на объём памяти, задаваемое в конфиге.
  3. Lazy‑loading — загрузка ресурсов только при необходимости, а не при инициализации агента.

Пример настройки кеша в Docker‑Compose

yaml
# docker-compose.yml
services:
  redis:
    image: redis:7-alpine
    restart: always
    volumes:
      - redis-data:/data
    command: ["redis-server", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]

  agent:
    image: ghcr.io/affaan-m/ecc:latest
    environment:
      - CACHE_URL=redis://redis:6379/0
      - MEMORY_LIMIT=1Gi
    depends_on:
      - redis

Здесь CACHE_URL указывает агенту, где находится кеш, а MEMORY_LIMIT задаёт верхний предел потребления памяти. При превышении лимита агент автоматически начинает освобождать ресурсы, удаляя менее используемые кеш‑ключи.

Lazy‑loading в коде (Python)

python
import os
from functools import lru_cache

@lru_cache(maxsize=128)
def get_config(path: str) -> dict:
    """Загружает конфигурацию из файла только при первом запросе."""
    with open(path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)

# Пример использования
config = get_config("/etc/ecc/config.yaml")

Декоратор @lru_cache гарантирует, что файл конфигурации будет прочитан один раз за процесс, экономя I/O и уменьшая нагрузку на файловую систему.

Рекомендации по памяти

  • рекомендуется задавать MEMORY_LIMIT в пределах 70 % от доступного объёма ОЗУ, чтобы оставить резерв для системных процессов;
  • на практике я видел случай, когда без ограничения памяти агент «съел» 8 GiB и привёл к OOM‑киллу, останавливающему весь пайплайн;
  • категорически не рекомендуется использовать безлимитные ulimit в production‑окружениях — это создаёт риск неожиданного роста потребления.

Подробнее о настройке памяти и других аспектах — в статье AI‑агент как ленивый senior dev: код без усилий.


Для дальнейшего углубления смотрите также affaan-m/ECC: Agent Harness Performance Optimization.

Instinctive Decision Making and Research‑First Approach

Instinctive Decision Making and Research‑First Approach

Dynamic Prompt Engineering

При работе с agent‑harnessом инстинктive‑принятие решений требует чёткого формулирования запроса.
Типовая ошибка – писать «сделай всё», без указания контекста и ожидаемого результата.

Практический пример – подготовка промпта для анализа кода в Claude Code:

bash
cat > prompt.txt <<'EOF'
You are a senior DevSecOps engineer. Review the following Dockerfile and list
1) security concerns,
2) possible performance improvements,
3) recommended changes to make the image reproducible.

Dockerfile:
<insert Dockerfile content here>
EOF

Запуск проверки:

bash
curl -X POST https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "'"$(cat prompt.txt)"'"}'

Рекомендуется всегда начинать с research‑first: проверяйте официальную документацию affaan-m/ECC, убедитесь, что используемая версия CLI совместима, затем формируйте запрос.

Если нужно сравнить несколько вариантов, используйте few‑shot‑примеры, как описано в статье AI‑агент как ленивый senior dev.


Iterative Validation Protocols

После формирования промпта следует итеративно валидировать полученный результат.

  1. Проверка на практике – запустите полученный совет в тестовом окружении.
  2. Сравнение с базовым образом – зафиксируйте метрики (время сборки, размер образа).

Скрипт валидации (bash):

bash
#!/usr/bin/env bash
set -euo pipefail

IMAGE_TAG="test/agent-harness:latest"
PROMPT_FILE="prompt.txt"

# 1. Сборка образа
docker build -t "$IMAGE_TAG" .

# 2. Запуск контейнера и сбор метрик
CONTAINER_ID=$(docker run -d "$IMAGE_TAG")
docker exec "$CONTAINER_ID" timeout 300 bash -c "time docker build -t test/agent-harness:tmp ."
docker stop "$CONTAINER_ID" && docker rm "$CONTAINER_ID"

# 3. Сравнение размеров
ORIG_SIZE=$(docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" "$IMAGE_TAG" | awk '{print $2}')
TMP_SIZE=$(docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" test/agent-harness:tmp | awk '{print $2}')

echo "Original size: $ORIG_SIZE"
echo "Optimized size: $TMP_SIZE"

# 4. Очистка
docker rmi "$IMAGE_TAG" test/agent-harness:tmp

На практике я видел случай, когда без итеративного теста оптимизация привела к увеличению размера образа на 30 % и падению производительности.

Рекомендуется использовать CI‑pipeline (GitHub Actions, GitLab CI) для автоматической проверки после каждого изменения промпта. Пример конфигурации в .github/workflows/validate.yml:

yaml
name: Validate Prompt

on:
  push:
    paths:
      - 'prompts/**'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run validation script
        run: |
          chmod +x ./scripts/validate.sh
          ./scripts/validate.sh

Категорически не рекомендуется игнорировать логи сборки – они часто раскрывают скрытые зависимости, которые влияют на итоговую производительность.


Итого: инстинктивное принятие решений должно подкрепляться исследованием и проверкой. Динамическое инженерение промптов вместе с итеративной валидацией гарантирует, что оптимизации agent‑harness действительно приносят пользу, а не лишь «показатели» в отчёте.

Security and Access Control in the Agent Harness

Security and Access Control in the Agent Harness

Zero‑Trust Authentication

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

Проверка токена
Токен должен быть короткоживущим (не более 15 минут) и подписанным с помощью асимметричного ключа. При каждом запросе агент проверяет подпись и срок действия.

bash
# пример проверки токена через curl
curl -s -H "Authorization: Bearer $AGENT_TOKEN" \
     https://api.agent.example.com/v1/status | jq .

Мутual TLS
Агент и контроллер должны использовать клиентские сертификаты. При генерации сертификата указывайте CN=agent-<id> и ограничьте срок действия 1 час.

bash
# генерация клиентского сертификата (openssl)
openssl req -new -newkey ec:<(openssl ecparam -name prime256v1) \
            -nodes -keyout agent.key -out agent.csr \
            -subj "/CN=agent-$(openssl rand -hex 4)"
openssl x509 -req -in agent.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
            -days 3600 -sha256 -out agent.crt

Принцип least privilege
Каждому агенту выдаётся отдельный набор прав. Не используйте общие токены с правами администратора.

рекомендуется: хранить токены в Vault или в файле с правами 0600, доступным только процессу агента.

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

Для детального описания процесса аутентификации см. Управление fleet-агентами разработки с Orca.

Secure Memory Isolation

Агент работает в изолированном окружении, где доступ к памяти ограничен только тем процессам, которые явно разрешены.

Docker‑контейнер с read‑only файловой системой

bash
docker run -d \
  --name agent-secure \
  --read-only \
  --tmpfs /run:rw,size=64m \
  --security-opt=no-new-privileges \
  --cap-drop ALL \
  --cap-add CHOWN \
  --cap-add SETGID \
  --cap-add SETUID \
  -e AGENT_TOKEN=$AGENT_TOKEN \
  myregistry/agent-harness:latest
  • --read-only — файловая система не меняется, исключая возможность подмены кода.
  • --tmpfs /run — временный образ в памяти, не сохраняется на диск.
  • --security-opt=no-new-privileges — запрещает процессу получать новые привилегии через setuid/setgid.

AppArmor профиль

bash
# профиль /etc/apparmor.d/agent-harness
profile agent-harness {
  #include <tunables/global>
  /proc/** r,
  /sys/** r,
  /dev/** r,
  /run/** rw,
  deny /bin/** wklx,
  deny /usr/bin/** wklx,
  # разрешаем только нужные команды
  /usr/bin/agent-exec wklx,
}

Загрузить профиль:

bash
apparmor_parser -r /etc/apparmor.d/agent-harness
docker run ... --security-opt apparmor=agent-harness ...

eBPF‑изоляция
Для высоконагруженных сред используйте eBPF‑политику, ограничивающую доступ к памяти через cgroup‑subsystem. Пример политики в bpftool:

bash
bpftool prog load /etc/bpf/agent_mem_isolate.bpf
bpftool prog attach pinned/1234

рекомендуется: проверять, что процесс не может читать чужие сегменты памяти (/proc/<pid>/maps).

категорически не рекомендуется: запускать агент с --privileged или в контейнере, где отключена изоляция.

Для более глубокой информации о изоляции памяти смотрите affaan-m/ECC: Agent Harness Performance Optimization.


Чек‑лист дальнейших действий

  • Сгенерировать и распределить короткоживущие подписанные токены (не более 15 минут).
  • Настроить mTLS‑соединения между контроллером и каждым агентом.
  • Внедрить read‑only файловую систему и ограниченный tmpfs для всех агентов.
  • Добавить AppArmor‑профиль, разрешающий только необходимые возможности.
  • Протестировать eBPF‑политику и убедиться, что процесс не может читать чужие сегменты памяти.
  • Проводить регулярный аудит токенов и сертификатов (политика «rotate every 24 h»).
  • Включить мониторинг попыток доступа к памяти через auditd и journalctl.

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

Deployment, Monitoring and Continuous Optimization

CI/CD Integration for Agent Workflows

В pipeline CI/CD нужно обеспечить изоляцию выполнения агент‑харнесса, чтобы не «засорить» production‑окружение и не утечками токенов. Типичный этап выглядит так:

  1. Сборка образа – собираем Docker‑образ с агент‑харнессом и всеми зависимостями.
  2. Тестирование в CI – запускаем набор unit‑ и integration‑тестов в отдельном контейнере, который не имеет доступа к продакшн‑сети.
  3. Публикация – после успешного теста образ пушим в регистр (GitHub Packages, Docker Hub и т.п.).
  4. Деплой в staging – с помощью Helm/Kustomize или простого kubectl apply разворачиваем образ в предварительное окружение.

Пример GitHub Actions workflow

yaml
# .github/workflows/agent-ci.yml
name: Agent Harness CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build agent harness image
        run: |
          docker build -t ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }} .
          docker push ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }}

      - name: Run unit tests
        run: |
          docker run --rm ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }} pytest -vv

Важно:

  • Never запускайте docker run --privileged или не ограничьте контейнер в production‑сети без предварительной проверки.
  • Рекомендуется использовать отдельный namespace в Kubernetes (agent-harness-staging) и ограничить resources.requests/limits.
  • Категорически не рекомендуется хранить токены доступа в репозитории; используйте GitHub Secrets или HashiCorp Vault.

Для управления fleet‑агентами в продакшн‑среде удобно интегрировать Orca (см. Управление fleet-агентами разработки с Orca). Orca предоставляет API‑эндпоинты, которые можно вызывать из CI‑pipeline для автоматического деплоя новых версий.

Пример деплоя в Kubernetes через Orca

bash
# Создаём или обновляем манифест
cat <<EOF > orca-deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-harness
  labels:
    app: agent-harness
spec:
  replicas: 2
  selector:
    matchLabels:
      app: agent-harness
  template:
    metadata:
      labels:
        app: agent-harness
    spec:
      containers:
        - name: agent-harness
          image: ghcr.io/yourorg/agent-harness:${TAG}
          ports:
            - containerPort: 8080
          env:
            - name: ORCAS_API_URL
              value: "https://orca.example.com/api"
          securityContext:
            readOnlyRootFilesystem: true
            runAsNonRoot: true
EOF

# Применяем манифест
kubectl apply -f orca-deploy.yaml

После деплоя проверяйте, что контейнер запустился без ошибок и что метрики доступны (см. следующий раздел).


Observability and Metrics Collection

Для надёжной работы агент‑харнесса необходимо собирать метрики и логи в реальном времени. Основные показатели:

МетрикаОписаниеПример источника
agent_execution_latency_secondsВремя от получения запроса до завершения задачиPrometheus exporter в контейнере
agent_success_total / agent_failure_totalСчётчики успешных/неуспешных выполненийincrement в коде
token_usage_bytesОбъём использованных токенов (контекст + вывод)лог‑параsing
cpu_throttling_secondsВремя, когда контейнер был ограничен CPUcAdvisor / Prometheus
log_error_countКол‑во ошибок, залогированных в Lokipromtail → Loki

Prometheus‑exporter (Python)

python
# exporter.py
from prometheus_client import start_http_server, Counter, Gauge

LATENCY = Gauge('agent_execution_latency_seconds', 'Execution time in seconds')
SUCCESS = Counter('agent_success_total', 'Number of successful runs')
FAILURE = Counter('agent_failure_total', 'Number of failed runs')
TOKEN_USE = Counter('agent_token_usage_bytes', 'Bytes of tokens used')

def record_latency(seconds):
    LATENCY.set(seconds)

def record_success():
    SUCCESS.inc()

def record_failure():
    FAILURE.inc()

def record_token_usage(bytes_used):
    TOKEN_USE.set(bytes_used)

if __name__ == '__main__':
    start_http_server(8000)   # /metrics endpoint

Запуск: python exporter.py – сервер будет слушать localhost:8000/metrics.

Prometheus‑scrape‑config

yaml
# prometheus.yml
scrape_configs:
  - job_name: 'agent_harness'
    static_configs:
      - targets: ['agent-harness-staging:8000']
    metrics_path: '/metrics'
    scheme: http

Loki + Promtail для логов

promtail-config.yaml

yaml
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: system
    static_configs:
      - targets:
          - localhost
        labels:
          job: system
          __path__: /var/log/**/*.log

Пример дашборда в Grafana

json
{
  "title": "Agent Harness Observability",
  "panels": [
    {
      "type": "graph",
      "title": "Execution latency",
      "targets": [
        {
          "expr": "agent_execution_latency_seconds",
          "legendFormat": "latency"
        }
      ],
      "yaxes": [
        { "format": "seconds", "label": "Latency" }
      ]
    },
    {
      "type": "stat",
      "title": "Success / Failure",
      "targets": [
        { "expr": "sum(agent_success_total)", "legendFormat": "success" },
        { "expr": "sum(agent_failure_total)", "legendFormat": "failure" }
      ]
    }
  ]
}

Советы от greyhat:

  • С точки зрения безопасности экспортируйте метрики только в зашифрованном виде (TLS) и ограничьте доступ по IP‑адресам.
  • Типовая ошибка – забыть про readOnlyRootFilesystem в контейнере, что позволяет злоумышленнику писать файлы в файловую систему. Всегда проверяйте securityContext.
  • На практике я видел случай, когда метрика token_usage_bytes росла экспоненциально из‑за бесконечного цикла в агенте; мониторинг позволил быстро отреагировать и остановить контейнер.

Для более детального описания процессов см. AI‑агент как ленивый senior dev: код без усилий и Управление ИИ-агентами с помощью Orca.

Чек‑лист после деплоя:

  • Образ прошёл все CI‑тесты без утечек токенов.
  • Метрики доступны в Prometheus (/metrics отвечает 200).
  • Loki принимает логи без ошибок, проверка promtail‑позиций.
  • TLS‑сертификат актуален, доступ к /metrics ограничен только внутренними IP.
  • Ограничения ресурсов (requests/limits) заданы, проверка kubectl top pod.

Следуя этим рекомендациям, вы обеспечите стабильную работу агент‑харнесса и сможете быстро реагировать на любые отклонения в работе.

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

Как добавить новый модуль в конфигурацию пайплайна?

Для добавления нового модуля отредактируйте файл pipeline.yaml, добавив блок с именем, entrypoint, расписанием и ресурсами. После сохранения выполните agentctl restart --pipeline для перезапуска агента и применения изменений. Модуль будет автоматически подхвачен в расписании, если указать корректный cron‑выражение.

Какие ресурсы (CPU, память) следует выделять модулям?

Ресурсы следует подбирать в зависимости от нагрузки конкретного модуля: например, I/O‑интенсивные скрипты обычно достаточно 0.5 CPU и 256 MiB памяти, а вычислительно тяжёлые — 1 CPU и 512 MiB или больше. В примере конфигурации указаны минимальные значения, которые можно увеличить при обнаружении Bottleneck. При превышении лимитов модуль будет ограничен и может завершиться с ошибкой.

Почему модуль может «залипать» в бесконечном цикле и как это исправить?

Такие ситуации возникают, когда модуль не изолирован от остальных процессов и накапливает состояние в памяти. В systemе affaan-m/ECC каждый модуль запускается в отдельном контейнере или с ограниченными ресурсами, что предотвращает «залипание». Если проблема всё равно появляется, проверьте логи через journalctl -u agent и при необходимости добавьте тайм‑аут или перезапуск контейнера.

Можно ли использовать локальный образ вместо Docker‑Hub для запуска модулей?

Да, вместо ghcr.io/affaan-m/ecc:latest можно разместить образ на домашнем сервере и указать локальный путь в entrypoint, например docker run --rm -v /home/agent/ecc:/work my-registry/ecc:latest. Это уменьшает задержку сети и повышает надёжность при отсутствии интернет‑доступа. Убедитесь, что образ построен с теми же зависимостями, что и официальный.

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

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