agent hubПУТЕВОДИТЕЛЬ Начать

Документация

Agent Hub

Сайт и документация · Исходники · Релизы

Локальный основной источник навыков, MCP-инструментов и общего контекста для Claude Code, Codex и DeepSeek Harness.

Нужны Node.js 22.13 или новее и npm. Цели релиза — macOS/Linux; Windows экспериментальна. Кандидат 0.1.0-beta.1 распространяется как проверенные архивы исходников и пакета. Пакет npm остаётся закрытым для защиты от случайной публикации в реестре.

npm ci
npm run install:global
ahub quick

Установите из распакованных исходников, затем вызывайте ahub из любого проекта. Доступен равнозначный agent-hub. Публичной установки из реестра пока нет. Установщик создаёт самостоятельную копию с зафиксированными production-зависимостями; исходники после установки можно удалить. Каталог npm binaries должен быть в PATH.

Область беты описана в CHANGELOG.md, установка tarball, контрольные суммы и условия публикации — в RELEASE.md, приватные сообщения об уязвимостях — в SECURITY.md. Установка может скачивать зафиксированные зависимости из npm. Кандидат подготовлен локально; это не означает, что публичный релиз уже опубликован.

ahub quick показывает настройку общего Hub: создание или принятие Hub, сбор MCP и навыков, доставка глобальных запускателей, ссылок и существующих общих инструкций выбранным клиентам. Git-проект не нужен. В терминале подтвердите проверенный план; неинтерактивный preview выводит полную Apply this workflow. Значения Hub основные, конфликты требуют решения, затронутых клиентов нужно перезапустить.

Память проекта отдельна и необязательна. После подготовки Hub используйте ahub project connect /path/to/project для памяти, контекста и hooks Git-проекта. Этот путь выбирает проект; хранилище Hub остаётся ~/.agent-hub, пока AGENT_HUB_HOME не задаёт другое. Глобальные инструменты и навыки подключением проекта не синхронизируются.

Для графического начала выполните ahub ui и выберите Set up shared Hub. Connect project memory — отдельное действие после общей настройки. Области и восстановление описаны в быстром старте. Сценарии поэтапные с отдельными undo-снимками. ahub undo показывает откат последнего запуска, reset — первого baseline.

UI открывается по http://127.0.0.1:3082; Ctrl+C останавливает сервер. Другой порт задаётся --port 3083, ручное открытие — --no-open. Запуск из репозитория позволяет видеть его контекст.

UI сохраняет стиль исходных макетов, используя реальные данные:

Поиск фильтрует навыки, MCP и память; ⌘K / Ctrl+K переводит фокус. Тема следует системе до ручного выбора. Refresh перечитывает диск. Локальное приложение пока англоязычное.

Навыки, общий контекст и передача проекта

ahub import skills --dry-run
ahub skill add /path/to/local-skill --dry-run
ahub sync --area skills --dry-run
ahub sync --area context --dry-run
ahub init-repo --dry-run

Эти операции начинаются с preview и требуют точной --apply --expect своего плана. MCP import тоже по умолчанию не пишет и требует --apply --expect. Обычный sync — только MCP; навыки и контекст выбираются явно. Те же действия доступны в UI.

Навыки копируются со скриптами и assets, затем связываются с клиентскими папками. Общий контекст сохраняет личный текст, доставляя правила и индекс без переноса нативной памяти. Init-repo создаёт обычные файлы, не staging и не коммиты. Content-копии поддерживает restore; reset включает первые оригиналы управляемых файлов, папок и ссылок.

Контракты — в контенте, области и MCP — в памяти, нативный импорт и checkpoints — в автоматизации, первое рабочее испытание — в руководстве. mcp add/rm, обмен графовой памятью и индекс архивных сессий не реализованы.

Доставка MCP: dry run и точная команда

ahub sync --dry-run
ahub sync --client dsh --dry-run
ahub sync --json

По умолчанию dry run ничего не пишет. Он показывает цели, действия серверов и запускатель, затем команду с --expect <revision>. Копируйте её для применения именно проверенных входов. Для любой записи нужен --apply; сочетание с --dry-run запрещено.

Sync MCP only в UI открывает тот же план. Можно копировать dry run или применение либо нажать Apply with backup. После правки входа или истечения плана нужен новый preview. DSH, Codex и Claude выбираются раздельно.

Меняются только MCP-описания. Сохраняются клиентские записи, прочие JSON-значения, текст TOML/YAML и политики инструментов Codex. Отключённые клиенты и управляемые приложением серверы вроде node_repl пропускаются. Выбор источника при импорте разрешает замену именно рассмотренных вариантов; закрытые хеши происхождения не содержат секретов. Поздняя правка конфликтует. Inline/dotted-присваивания Codex требуют явных таблиц серверов; неподдерживаемый транспорт блокируется.

Для переноса конфликтующей записи с сохранением описания Hub выберите точные имена одного клиента:

ahub sync --client dsh --replace example-server --dry-run

План помечает замены. Выданное применение содержит --replace и ревизию --expect; без неё замена запрещена. Другие конфликты, неподдерживаемые поля, пропущенные переменные и записи приложения защищены. Реестр и секреты не переписываются. Имена wrappers или специальных скриптов не распознаются как автоматическое владение.

Перед записью создаются закрытые копии в hub/backups/<id>/, проверяются замены и хеши владения. Поздний сбой откатывает ранние изменения. Удаление из реестра убирает только неизменённое ранее управляемое описание.

ahub restore <backup-id> --dry-run

Restore тоже начинает с dry run и выводит точную команду. Файл клиента или владение, изменённые после копии, блокируют откат. После sync и restore перезапустите клиентов.

Возврат первого сохранённого состояния после нескольких операций:

ahub reset --dry-run

Оригиналы сохраняются до записи вне Hub в <AGENT_HUB_HOME>.recovery. Reset архивирует текущее и восстанавливает исходное; --apply требует проверенную --expect. Поздние правки клиента блокируются по умолчанию. Для старой установки без оригиналов следующая запись создаёт честно помеченный снимок существующего Hub; дорелизное состояние не выдумывается. Области, внешние правки, блокировки и ограничения — в восстановлении.

Сравнение показывает эффективный запуск, не здоровье сервера. Разные wrappers и ссылки на секреты могут быть эквивалентны. Status разрешает ссылки Hub и узнаёт свой запускатель, согласованно сравнивая прямые и созданные варианты. Для общего контекста — sync --area context, для репозитория — init-repo, с отдельными планами.

Проверки подключений MCP

ahub doctor
ahub doctor firecrawl --timeout 30
ahub doctor --client dsh --json

doctor запускает серверы через тот же Hub launcher, выполняет инициализацию и получает все страницы tools/list. Инструменты и API-провайдеров не вызываются. Успех доказывает соединение и discovery, не права всех внешних операций. Сервер только с ресурсами может успешно пройти без инструментов.

При явно заданном N8N_API_URL doctor независимо проверяет /healthz/readiness. GET без API-ключа удаляет query/fragment, не следует redirect и длится до трёх секунд. 5xx, DNS, отказ, TLS и timeout дают отдельное предупреждение, не провал и не отключение рабочего MCP. Защищённый, перенаправляющий или отсутствующий endpoint — неизвестность. После запуска сервиса повторите проверку. API-секреты не проверяются; для остальных провайдеров пока есть только MCP discovery.

Повреждённый кеш npx с ENOTEMPTY при rename отмечается отдельно от сети и временных 502/503/504. Doctor не исправляет кеш и не перезапускает deployments.

CLI показывает статус, число инструментов, время, фиксированную ошибку и следующий шаг. --timeout <seconds> задаёт общий бюджет сервера: по умолчанию 20 секунд, диапазон 0,1–120. Пробы выполняются по две. Записи приложения пропускаются; --client учитывает область и выключенные определения. Ctrl+C отменяет активные и ожидающие проверки.

В UI Check MCP открывает диалог с сервером, областью и timeout. Доступны прогресс, отмена и копирование. Таблица отделяет последнее соединение от конфигурации; карточка показывает число инструментов, длительность и время проверки. Refresh читает hub/state/doctor.json, новая ревизия реестра или секретов помечает кеш устаревшим. Закрытие текущей проверки отменяет её.

На macOS/Linux пробы изолированы по группам процессов. Timeout, отмена и завершение останавливают worker, launcher и потомков, при необходимости принудительно. На Windows завершение дерева потомков не проверено.

Отчёты не содержат исходные stdout/stderr, тела ответов и секреты. Локально проверяются права .env, собранный запускатель и сломанные ссылки навыков. Запись отчётов атомарна с правами 600. Используется официальный TypeScript SDK MCP.

CLI

ahub status
ahub status --json
ahub init
ahub import mcp --dry-run
ahub import mcp
ahub mcp ls
ahub mcp run <name>

AGENT_HUB_HOME выбирает Hub вместо ~/.agent-hub. Клиенты учитывают CLAUDE_CONFIG_DIR, CODEX_HOME, DSH_HOME; AGENT_HUB_CLAUDE_CONFIG и AGENT_HUB_SHARED_SKILLS переопределяют Claude JSON и общие навыки. AGENT_HUB_DSH_PROFILE переопределяет профиль DSH в hub.yaml. Архитектура и планы — в устройстве.

Разработка

npm run dev -- ui --no-open
npm run check
npm run test:coverage
npm run package:check

Frontend — обычные HTML/CSS/JS со стилями макетов, без сборщика и новых зависимостей. Сохраняйте ui/app рядом с dist для скомпилированного CLI. Allowlist пакета включает assets.

Сервер привязан только к 127.0.0.1, проверяет Host и Origin, требует токен записи и отдаёт фиксированный набор assets. Значения конфигурации и .env не выдаются файлами; планы MCP показывают ссылки и очищенные значения. Известный Markdown экранируется. UI вызывает общие сервисы импорта, а не shell-команды.

Тесты используют временные Hub, клиентов и репозитории. Покрыты полные наборы, метаданные, общие корни и затенение, владение блоками, шаблоны, скопированные команды, HTTP, восстановление артефактов, секреты, ревизии, области, идемпотентность, откат, ссылки и CLI defaults. Doctor использует независимые MCP-fixtures для handshake, pagination, ошибок, дедлайнов, очистки, отмены и редактирования отчётов. Настоящие файлы клиентов не меняются.

Для ручной проверки UI без своих конфигураций:

npm run qa:ui

Сервер http://127.0.0.1:3083 работает с временными JSON/TOML/YAML-клиентами, документами и локальными MCP. Путь выводится в консоль. Ctrl+C останавливает сервер; данные остаются для просмотра. Импорт, sync и doctor работают только с fixture. Скопированные команды — настоящий CLI: внедрённые пути трёх клиентов не являются defaults, поэтому ревизия не даст применить их вне этого контекста. Копируйте реальные команды из обычного UI/CLI. Проверенные случаи — в QA.

Любой сервис может объявить необязательный endpoint готовности без авторизации:

version: 1
servers:
  example:
    command: node
    args: [server.mjs]
    health:
      name: Example service
      url: ${EXAMPLE_URL}/ready

Health-метаданные не влияют на эквивалентность запуска и настройки клиентов. Пресет n8n — отдельная интеграция совместимости. Правила разработки — в CONTRIBUTING.md, находки и ограничения — в ревью.

Проверка самостоятельной глобальной установки — npm run install:check. Она использует временный prefix и fixture-пути, запускает ahub из другой папки и затем удаляет временную установку.

Явные области и восстановление

Выберите вход

ahub показывает quick, ui, status, doctor, project и undo. Начните с quick для терминала либо ui для пошагового управления. Специальные операции и технические параметры доступны через ahub --advanced --help и ahub --advanced quick --help. Старые вызовы, JSON и скрипты поддерживаются. Справочник объясняет пользователя и назначение каждой команды.