Подключение RAGRAF к DeepSeek Harness

Как это устроено

Что было доработано в RAGRAF

Дефект был не «неудобно», а «не работает вовсе»: первый же ответ с русским текстом убивал сервер. Измерено запуском — три причины, каждая подтверждена замером.

UnicodeEncodeError: 'charmap' codec can't encode characters in position 97-105
  File "src/ragraf/mcp_server.py", line 551, in send
    sys.stdout.write(json.dumps(message, ensure_ascii=False) + "\n")

1. 1Кодировка потокаMCP SDK передаёт дочернему процессу лишь 12 переменных (APPDATA, PATH, TEMP, USERPROFILE и др. — DEFAULT_INHERITED_ENV_VARS), а HARNESS дополнительно вычищает имена с PASSWORD|SECRET|TOKEN|KEY и все DSH_*. Ни PYTHONUTF8, ни PYTHONIOENCODING в набор не входят — локаль процесса остаётся cp1252. Правка: force_utf8_stdio() перенастраивает stdin, stdout, stderr на UTF-8, не полагаясь на окружение.
2. 2Зависимостиfastembed, PyYAML, sqlite_vec, tree_sitter, ijson были достижимы интерпретатору из PATH только через переменную PYTHONUSERBASE — HARNESS её вычищает, и сервер рапортует «не установлен PyYAML». Решение: сервер запускается интерпретатором из .venv самого проекта — замерено, что при полностью снятых PYTHON*-переменных он импортирует все пакеты.
3. 3Обязательный --projectКлиент, запускающий сервер без аргументов, не мог стартовать вообще. Правка: --project больше не обязателен — корпус определяется по рабочему каталогу через реестр (_resolve_default_project()), для ручного переключения добавлен инструмент ragraf_use_project, а --agent берётся ещё и из переменной RAGRAF_AGENT.

Совместимость с прежними клиентами сохранена: AutoClaw и SagaAI передают --project явно и выставляют PYTHONIOENCODING — для них ничего не изменилось.

Установка — три шага

Все три шага кладут файлы в домашний каталог HARNESS (%USERPROFILE%\.dsh или $DSH_HOME); готовые блоки лежат в каталоге harness/ репозитория RAGRAF. В командах ниже $repo — путь к локальному клону RAGRAF, $dsh — поставляемый CLI приложения.

1. 1Подключите MCP-серверГотовый блок harness/ragraf-mcp.patch.yml дописывается в конец слоя патчей профиля cordis.patch.yml. Приложение хранит патчи массивом, поэтому блок вставляется отдельной строкой «- insert:». Сначала бэкап — файл принадлежит пользователю.
   Дописывание патч-блока (PowerShell)Копировать

   $repo = 'C:\AutoClaw\RAGRAF'   # путь к локальному клону RAGRAF
   $src  = Join-Path $repo 'harness\ragraf-mcp.patch.yml'
   $dst  = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.dsh\profiles\desktop\cordis.patch.yml'
   
   # 1. бэкап (обязательно: файл принадлежит пользователю)
   Copy-Item $dst "$dst.bak-$(Get-Date -Format yyyyMMdd-HHmmss)"
   
   # 2. проверить, что блока ещё нет
   Select-String -LiteralPath $dst -Pattern 'mcp-ragraf'
   
   # 3. дописать блок (слой патчей — массив; блок вставляется отдельной строкой "- insert:")
   Add-Content -LiteralPath $dst -Value (Get-Content -LiteralPath $src -Raw) -Encoding utf8NoBOM

   Проверить, что патч применяется — без запуска приложения:

   Проверка через dsh --dump-configКопировать

   $dsh = Join-Path $env:LOCALAPPDATA 'Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd'
   & $dsh --profile headless --patch $src --dump-config | Select-String 'serverName: ragraf' -Context 1,3

   Профиль desktop — рабочий профиль приложения; headless — одноразовые задачи из командной строки. Для профиля, отличного от desktop, блок кладётся в его cordis.patch.yml тем же способом.

2. 2Установите навыкКорень навыков %USERPROFILE%\.dsh\skills читает провайдер @deepseek-ai/dsh-skill-filesystem: на верхнем уровне он ищет <имя>/SKILL.md. Навык в этом каталоге обнаруживается без перезапуска — провайдер следит за корнем.
   Установка навыка ragraf-coreКопировать

   $skills = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.dsh\skills\ragraf-core'
   New-Item -ItemType Directory -Path $skills -Force | Out-Null
   Copy-Item (Join-Path $repo 'harness\skills\ragraf-core\SKILL.md') "$skills\SKILL.md" -Force

3. 3Добавьте правило в глобальные инструкцииHARNESS читает %USERPROFILE%\.dsh\AGENTS.md (модуль dsh-agent-instructions; dshHome = $DSH_HOME или ~/.dsh). Раздел для вставки — harness/agents-section.md; ставится перед разделом «Журнал изменений», иначе правило окажется после истории (в проверенной установке это раздел 6). Ожидаемое поведение: на вопрос «с чего начинается задача о коде» агент отвечает mcp__ragraf__ensure и ссылается на этот раздел.

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

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

cd $repo
Remove-Item Env:\PYTHONUTF8, Env:\PYTHONIOENCODING -ErrorAction SilentlyContinue
python tests\test_mcp_compat.py

ИТОГ: пройдено 13, провалено 0

& $dsh --profile headless --patch $src --json `
  "Вызови mcp__ragraf__index_status и приведи первую строку ответа"

{"type":"tool_call","tool":"mcp__ragraf__ragraf_index_status","input":{}}
{"type":"tool_result","status":"completed","result":"op=index_status rev=rev-0043 capability=full ..."}

& $dsh --profile headless --patch $src "Загрузи навык ragraf-core и назови первый шаг"

{"type":"tool_call","tool":"skill","input":{"name":"ragraf-core"}}

pwsh -NoLogo -NoProfile -NonInteractive -File tools\Invoke-ProjectDoctrine.ps1

checks: 16, errors: 0, warnings: 0, Result: PASS
[PASS] MCP server survives a scrubbed client environment
[PASS] operations outside the facade are recorded

Три ограничения, которые надо знать

Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
  Select-Object ProcessId, @{n='MB';e={[int]($_.WorkingSetSize/1MB)}}
Get-NetTCPConnection -LocalPort 9500 -ErrorAction SilentlyContinue

# висящий сервер снимается вместе с родительским процессом:
taskkill /PID <PID родительского cmd.exe> /T /F

Откат

HARNESS: вернуть слой патчей и AGENTS.md из бэкапов (их имена печатала установка), удалить каталог навыка ragraf-core.

$home2 = [Environment]::GetFolderPath('UserProfile')
# 1. вернуть слой патчей из бэкапа (имя печатала установка)
Copy-Item "$home2\.dsh\profiles\desktop\cordis.patch.yml.bak-<метка>" `
          "$home2\.dsh\profiles\desktop\cordis.patch.yml" -Force
# 2. вернуть глобальные правила
Copy-Item "$home2\.dsh\AGENTS.md.bak-<метка>" "$home2\.dsh\AGENTS.md" -Force
# 3. убрать навык
Remove-Item "$home2\.dsh\skills\ragraf-core" -Recurse -Force

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

Поведение HARNESS: где лежит что

Домашним каталогом управляют переменные DSH_HOME (явный путь важнее) и DSH_AGENTS_HOME (общий каталог навыков агентов, по умолчанию ~/.agents). Из окружения дочерних процессов HARNESS вычищает обе — на запуск MCP-сервера это не влияет: он читает только --project и рабочий каталог.

Порядок разрешения корней навыков (rank): <проект>/.dsh/skills (100), <проект>/.agents/skills (200), пользовательские customSkillDirs (300), ~/.dsh/skills (400), ~/.agents/skills (500). Проектный корень — ближайший каталог с .git.

HARNESS разрабатывается в приватном репозитории (github.com/deepseek-ai/deepseek-harness); публичной проверки API не делалось. Контракт выше описан по фактам текущей установки — lib/index.js и README пакетов внутри app.asar, — а не по документации.