Подключение к агентным средам

Agent-среда автора RAGRAF (zwork 2.0.2, Electron): именно на ней продукт проектировался и на ней измерены опубликованные результаты. Подключение идёт двумя независимыми каналами — CLI без настройки и MCP через интерфейс продукта; --agent-kind autoclaw — реальный кодовый путь (атрибуция телеметрии, расширенный режим журнала). Всё в гайде — замеры интеграционной сессии и факты из кода приложения.

1. 1Начните с канала CLI — он работает без настройкиПервый шаг задачи — python <repo>\tools\ragraf.py ensure <каталог>, дальше — операции индекса вместо чтения файлов. CLI не зависит ни от настроек приложения, ни от перезапуска и не может «тихо отвалиться». Если инструментов ragraf_* в списке агента нет — это не поломка: индекс, поиск, схема и графы остаются полностью рабочими через CLI (замер сессии: tool_search → 0).
2. 2MCP регистрируется через интерфейс продуктаИзмерено: файлового способа регистрации нет — ни mcp.json, ни mcpServers в профиле, ни таблицы серверов в runtime.sqlite (проверены все 106 таблиц). Сервер указывается в настройках проекта/приложения: интерпретатор .venv, ragraf-mcp.py --agent AutoClaw --agent-kind autoclaw, рабочий каталог <repo>. --project не нужен: корпус определится по рабочему каталогу, переключение — ragraf_use_project.
3. 3Навык — в оба аккаунта, правила — в ~/.pi/agent/AGENTS.mdragraf-core раскладывается в дерево навыков каждого аккаунта (источник — docs/skills проекта; свежесть копий контролируется по SHA-256). Раздел 8 пользовательских правил предписывает начинать задачу с ensure и исполним в обеих конфигурациях — с MCP и без.
4. 4Проверяйте замерами, а не предположениемtool_search по ragraf: 0 до регистрации и 59 после перезапуска — эта разница и есть доказательство. Через CLI: catalog (реестр), ensure (status: actual), check (совпадение сумм). usage --agent AutoClaw покажет ensure в разбивке — значит правило первого шага соблюдается.

команда:            <repo>\.venv\Scripts\python.exe
аргументы:          <repo>\tools\ragraf-mcp.py
                    --agent AutoClaw --agent-kind autoclaw
рабочий каталог:    <repo>

Открытая платформа команды ИИ-сотрудников (Streamlit, MIT, v1.13.1): ассистенты, автономные оркестраторы, встроенный агент-разработчик DevAgent, базы знаний и библиотека навыков. MCP-клиента в коде платформы нет — проверено поиском по репозиторию, — поэтому RAGRAF подключается через её собственные механизмы: навык ragraf-core и CLI-вызовы инструментом run_code.

1. 1Постройте корпус один раз — он общий для всех сотрудниковИндекс read-only для агентов: несколько оркестраторов и диалогов работают с одним корпусом одновременно. Первый шаг — ensure <каталог проекта>.
2. 2Установите навык ragraf-core в библиотекуУстановка из GitHub-URL, ZIP или папки (реестр skills/skills.json; лимиты: 200 МБ, 5000 файлов, 50 МБ на файл). Сторонний навык не попадает в системный промпт, пока DevAgent (Skill Developer) не завершит адаптацию — mark_skill_adapted.
3. 3Внесите регламент в инструкции оркестратораПять правил универсального фрагмента — минимальный достаточный набор; добавьте их в инструкцию сотрудника (сохраняется между перезапусками) или в AGENT.md проекта. Без регламента агенты возвращаются к search_in_files — это сразу видно в статистике вызовов.
4. 4CLI-вызовы — через run_coderun_code выполняет команды в изолированном subprocess (таймаут 300 с; опасные паттерны — только с подтверждением в UI): catalog, ensure, query symbol, check, usage --agent saga-worker. Текст ответа агент читает сам — интерпретация схемы не нужна.

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "<repo>/tools/ragraf-mcp.py",
        "--agent", "saga-worker",
        "--agent-kind", "external"
      ]
    }
  }
}

Electron-приложение DeepSeek Harness 0.2.0-rc.2 со встроенным MCP-клиентом (плагин @deepseek-ai/dsh-mcp-client). RAGRAF подключается к нему как MCP-сервер по stdio; инструменты становятся видны под именами mcp__ragraf__ragraf_*. Связка отлажена до конца и подтверждена замерами живой сессии: всё ниже — повторяемые команды, пути и измеренные выводы.

Полный гайд по настройке Harness

Среды нет в списке? Если клиент умеет запускать stdio-процесс и говорить JSON-RPC — этого достаточно. Три шага: конфиг сервера, регламент в системный промпт, проверка capabilities первым вызовом.

# Регламент работы с RAGRAF (фрагмент AGENTS.md)
1. Навигация — только через ragraf_symbol / ragraf_search.
   Полный файл — только ragraf_live_read и только по факту из индекса.
2. Проверяй конверт: stale_warnings → перечитай затронутое (live_read);
   capability=degraded → не планируй задачи со slice.
3. Перед любой записью в БД — ragraf_write_check (всегда).
4. Перед правкой символа — ragraf_impact --depth 3.
5. «Не найдено» — валидный ответ: сообщай limits из конверта, не додумывай.

# сервер отвечает на инициализацию MCP и раскрывает режим корпуса
python tools/ragraf-mcp.py --project corpus.yaml --agent probe --agent-kind external
# → JSON-RPC: 59 инструментов ragraf_*; list_capabilities:
#   {"capability":"full","operations":[...22...]}   (или degraded + reason)

# телеметрия после пробных вызовов
ragraf -p corpus.yaml query usage_stats
# → usage_call содержит записи agent=probe, kind=external