Подключение RAGRAF к AutoClaw

Два канала: CLI и MCP

Смешивать каналы нельзя — от этого зависит, что именно проверять. CLI работает всегда и не зависит от настроек приложения; MCP даёт те же операции как инструменты агента, но требует регистрации сервера.

Что уже настроено

Срез машины автора по замерам интеграционной сессии — ориентир «как должно выглядеть» после настройки.

Аккаунты AutoClaw на машине (у каждого своё дерево навыков и свой runtime)

%APPDATA%\AutoClaw-oversea-official\accounts\<account-1>\   (основной)
%APPDATA%\AutoClaw-oversea-official\accounts\<account-2>\

Навык разложен в оба аккаунта — тогда при смене учётной записи он остаётся виден. Свежесть копий подтверждена замером: SKILL.md, reference/operations.md и reference/repair.md совпадают с проектной редакцией по SHA-256 в обоих аккаунтах.

Канал CLI: работает без настройки

Основной путь, пока MCP не зарегистрирован. Три правила.

1. 1Первым шагом — актуализировать корпусОтвет несёт status: actual — индекс актуален, reindexed — пересобран только что, created — корпуса не было и он создан, not_a_project — каталог не похож на проект, error — причина в поле reason.
   Первый шаг задачи (PowerShell)Копировать

   python <repo>\tools\ragraf.py ensure <каталог проекта>

2. 2Дальше — операция, а не чтение файловПризнак stale: true означает, что фактам верить нельзя до переиндексации: код ушёл вперёд. Это не «предупреждение на всякий случай».
   Операции индекса (PowerShell)Копировать

   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml query symbol --name corpus_hash
   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

3. 3Список корпусов — командой без конфигурацииРеестр разработок виден без -p: catalog печатает все заведённые корпусы с ревизиями и суммами.
   Реестр корпусов (PowerShell)Копировать

   python <repo>\tools\ragraf.py catalog

Почему CLI здесь предпочтительнее MCP

Не из-за удобства. Каждая команда печатает текст, который агент читает сам, а MCP-ответ надо интерпретировать по схеме. Плюс CLI не зависит ни от перезапуска приложения, ни от регистрации сервера — то есть не может «тихо отвалиться». Замер по полигону: 14 вызовов инструментов против 28 без индекса, попадание в файл-цель с первого запроса — 92%.

Канал MCP: устройство и подключение

Устройство подключения MCP в AutoClaw не совпадает с привычными клиентами (Claude Desktop, Codex, DeepSeek Harness), и это существенно. Четыре факта, измеренные в сессии:

1. 1MCP-конфига в профиле нетПоиск по ~/.pi, <account>\runtime и <account>\projects не нашёл ни mcp.json, ни mcpServers в настройках. Регистрация живёт не в файле профиля.
2. 2ragraf не регистрируется ни одним пакетом приложенияПроверены все таблицы runtime.sqlite (106 штук) — таблицы MCP-серверов нет; упоминания ragraf-mcp в базе оказались историей прошлых сессий, а не регистрацией.
3. 3Вертикальный пакет объявляет MCP-серверы декларациейПоле mcpServers есть в схеме пакета: dist\resources\vertical-packs\code\zwork-pack.json. У официальных пакетов оно пустое ("mcpServers": []), а пользовательских пакетов на диске нет вовсе (поиск zwork-pack.json вне установки — 0 файлов).
4. 4Встроенный агент MCP не обслуживает@earendil-works/pi-coding-agent не содержит ни строки про MCP (проверены dist и docs); все найденные в бандле упоминания mcpServers принадлежат встроенным SDK вендоров (Google/Gemini) и к AutoClaw отношения не имеют.

Как подключать и что проверять

1. 1Найдите раздел MCP в настройках продуктаОткройте настройки проекта (или приложения) в AutoClaw и найдите раздел про MCP / внешние инструменты — сервер регистрируется там.
2. 2Укажите запуск (значения проверены запуском)--project указывать не нужно: сервер сам определит корпус по рабочему каталогу через реестр разработок, а для чужого проекта корпус выбирается инструментом ragraf_use_project (список даёт ragraf_catalog).
3. 3Проверьте, а не предположитеДо подключения вызовите tool_search с запросом ragraf — ожидается 0. После регистрации и перезапуска — 24 инструмента. Эта разница и есть доказательство, что подключение сработало.

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

Если интерфейсного раздела нет

Тогда честный ответ такой: MCP-канал в этой сборке недоступен, а RAGRAF работает через CLI (раздел выше). Ничего не теряется, кроме того, что каждый вызов идёт командой, а не инструментом. Придумывать регистрацию правкой базы или подменой файла нельзя: runtime.sqlite — состояние приложения, и правка его в обход продукта ломает учёт прав и артефактов (таблицы governed_tool_*).

4 дефекта совместимости

Подключение ко второму клиенту (DeepSeek Harness) вскрыло дефекты, которые касались и AutoClaw. Все четыре закрыты, каждый — с регрессионной защитой.

1. 1Сервер падал на первом русском ответе при урезанном окруженииMCP-клиент передаёт дочернему процессу только 12 переменных (APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, USERPROFILE, PROGRAMFILES). Ни PYTHONUTF8, ни PYTHONIOENCODING туда не попадают, локаль процесса остаётся cp1252 — и send() падал с UnicodeEncodeError: charmap codec (src/ragraf/mcp_server.py). Оболочка AutoClaw ставит обе переменные, поэтому для AutoClaw дефект был невидим — он проявился только на втором клиенте. Правка: force_utf8_stdio() — потоки приводятся к UTF-8 в самом сервере, а не берутся из окружения.
2. 2Обязательный --project не давал работать с несколькими проектамиПравка: --project необязателен, корпус ищется по рабочему каталогу (реестр разработок), добавлен инструмент ragraf_use_project. Один сервер обслуживает все 18 корпусов машины автора.
3. 3Команда reindex не записывала прогон в реестрИзмерено на собственном корпусе: в индексе rev-0046, в реестре rev-0045 со старой суммой; check из-за этого переиндексировал корпус заново, а catalog и панель показывали прошедшее состояние. Правка: src/ragraf/cli.py — reindex пишет прогон той же общей точкой watch.record_index_run, что и index.
4. 4ensure и use_project не попадали в статистикуТелеметрия навешивается обёрткой на методы op_* фасада, а эти две операции живут в MCP-сервере. В сводке usage их не было — то есть нельзя было ответить, соблюдают ли агенты правило первого шага. Правка: Facade.record_external_call (src/ragraf/facade.py) + запись со стороны сервера. Замер после правки: ensure 1, use_project 1 в сводке по агенту.

Зависимости: почему интерпретатор из .venv

На машине автора зависимости RAGRAF достижимы интерпретатору из PATH только через переменную PYTHONUSERBASE (%APPDATA%\AutoClaw-oversea-official\toolchain\python\Python313\site-packages). Внешний клиент её вычищает — и python из PATH падает на «не установлен PyYAML». Замерено: .venv проекта самодостаточен — при полностью снятых PYTHON*-переменных он импортирует yaml, fastembed, sqlite_vec, tree_sitter, ijson, tiktoken. Для AutoClaw это тоже полезно: CLI в оболочке агента работает и так, но .venv перестаёт зависеть от настроек окружения.

Навык и правила

Навык ragraf-core

Навык лежит в дереве каждого аккаунта:

%APPDATA%\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core\
    SKILL.md                 (вход: когда применять, порядок работы)
    reference/operations.md  (выбор операции и границы)
    reference/repair.md      (что делать, когда индекс сломан)

Источник — каталог проекта: <repo>\docs\skills\ragraf-core. Правка идёт в проект, затем копируется в служебный каталог аккаунта. Иначе при следующем развёртывании копия в аккаунте «отстанет» от проекта и агент будет работать по старой редакции. Копий ровно две — по числу аккаунтов; в обоих навык есть.

Проверено замером свежести (сессия): в обоих аккаунтах лежат три файла — SKILL.md 9811 байт, reference/operations.md 7546, reference/repair.md 11271, — и SHA-256 каждого совпадает с проектной редакцией. То есть копия в аккаунте не отстала от источника.

$src = '<repo>\docs\skills\ragraf-core'
Get-ChildItem "$env:APPDATA\AutoClaw-oversea-official\accounts" -Directory | ForEach-Object {
    $dst = Join-Path $_.FullName 'runtime\zwork-agent\skills\ragraf-core'
    if (Test-Path -LiteralPath $dst) {
        Copy-Item -Recurse -Force "$src\*" $dst
        Write-Host "обновлено: $dst"
    }
}

Проверка навыка: файл начинается с ---, поля name и description разбираются построчно, размер меньше 256 КиБ, кодировка UTF-8 без BOM, переводы строк LF, а копия в аккаунте совпадает с проектной побайтово.

Правила: ~/.pi/agent/AGENTS.md

Это пользовательский файл правил AutoClaw — он подхватывается в любом проекте, где нет своего AGENTS.md, и наоборот: проектный AGENTS.md строже. Подхватывается также AGENTS.md из родительских каталогов до границы .git.

Раздел, который заставляет работать через индекс, — раздел 8 «Обязательное использование RAGRAF при разработке кода». Три места, которые надо знать:

Проверка — четыре уровня

От узкого к широкому: CLI и реестр → свежесть корпуса → MCP-канал → телеметрия. Каждый уровень — команда и ожидаемый результат из сессии.

python <repo>\tools\ragraf.py catalog
python <repo>\tools\ragraf.py ensure <repo>

18 разработок в реестре; status: actual и совпадение сумм.

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

«сумма корпуса сейчас» = «сумма при индексации», «изменилось после индексации: нет».

tool_search("ragraf")                    → до подключения: 0 инструментов
                                           после регистрации и перезапуска: 24
ragraf_ensure()                          → status = actual | reindexed | created
ragraf_index_status()                    → index_rev, capability
ragraf_use_project(project="<имя>")      → ревизия ДРУГОГО корпуса

cd <repo>
Remove-Item Env:\PYTHONUTF8, Env:\PYTHONIOENCODING -ErrorAction SilentlyContinue
python tests\test_mcp_compat.py        # 15 проверок

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml usage --agent AutoClaw

Строка по агенту с числом вызовов и операциями, включая ensure. Если ensure в разбивке нет — значит клиент его не вызывал, а не «телеметрия потеряла».

Откат

Регистрация MCP — единственное обратимое действие в интерфейсе: снять сервер в том же разделе настроек и перезапустить приложение. Индекс, реестр и корпуса от этого не меняются.

Правки самого RAGRAF аддитивные; чтобы вернуть прежнее поведение, достаточно трёх изменений: убрать вызов force_utf8_stdio(), вернуть required=True у --project, удалить ragraf_use_project из TOOLS и _handlers. Ни одно из них не затрагивает индекс, схему хранилища, нумерацию ревизий или реестр — переиндексация при откате не требуется.

Копии навыка в аккаунтах восстанавливаются из проекта:

Copy-Item -Recurse -Force <repo>\docs\skills\ragraf-core `
    "$env:APPDATA\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core"

Где что лежит в AutoClaw

Особенность установки: код приложения лежит распакованным (resources\app\dist), а не в app.asar. Это удобно для разведки: файлы читаются обычными средствами, и main.cjs можно искать по строкам.

Приглашение в AutoClaw