设置指南

将 RAGRAF 接入 DeepSeek Harness

--agent-kind external MCP · stdio · JSON-RPC mcp__ragraf__ragraf_* 经实测确认 · dsh 0.2.0-rc.2

Electron 应用 DeepSeek Harness 0.2.0-rc.2，内置 MCP 客户端（插件 @deepseek-ai/dsh-mcp-client）。RAGRAF 以 stdio MCP 服务器接入；工具以 mcp__ragraf__ragraf_* 的名称呈现。该集成已完整调试并经实际会话测量确认：以下内容均为可复现的命令、路径与实测输出。

dsh 0.2.0-rc.2 · Electron
24 个 ragraf_* 工具
3 处 RAGRAF 修复
4 个验证层级

命令中的记号：$repo — 本地 RAGRAF 克隆路径（片段在第一行设置），$dsh — 应用自带的 CLI。命令与输出按实测引用 — 包括产品打印的俄文字符串。

来源：集成会话文档《RAGRAF × DeepSeek Harness》 — 真实会话（dsh 0.2.0-rc.2）的可复现命令、路径与实测输出。

工作原理

为什么用 stdio 而不是 streamable-http

HARNESS 的 MCP 客户端声明 capabilities: {}——服务器拿不到 roots。若把 RAGRAF 作为单一 HTTP 服务提供，就无法判断「当前是哪个项目」：客户端的当前目录不会传到服务器。stdio 服务器的工作目录是已知的，语料通过开发登记表解析。

为什么所有项目共用一个服务器

HARNESS 客户端不允许 RAGRAF 工具重启自身，而每个项目一个服务器意味着每个项目都要在内存中保留一份索引副本。因此改由 mcp__ragraf__use_project 操作切换语料，默认语料按工作目录经登记表解析。找不到语料时服务器仍会启动，如实响应 catalog 与 use_project，其余操作则说明原因并拒绝。

内容	位置
服务器入口	tools/ragraf-mcp.py · репозиторий RAGRAF
24 个内置工具	src/ragraf/mcp_server.py
操作门面（22）	src/ragraf/facade.py
语料登记表	catalog/catalog.json
配置档补丁层	%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml
技能	%USERPROFILE%\.dsh\skills\ragraf-core\SKILL.md
全局规则	%USERPROFILE%\.dsh\AGENTS.md · раздел 6

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")

流编码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。
依赖fastembed、PyYAML、sqlite_vec、tree_sitter、ijson 对 PATH 解释器只有经 PYTHONUSERBASE 才可达——HARNESS 会清除它，服务器便报告「PyYAML 未安装」。解决：服务器改由项目自带 .venv 的解释器启动——实测在完全移除 PYTHON* 变量时也能导入全部包。
强制的 --project不带参数启动服务器的客户端根本无法启动。修复：--project 不再必需——语料按工作目录经登记表解析（_resolve_default_project()），新增 ragraf_use_project 工具用于手动切换，--agent 还可取自 RAGRAF_AGENT 变量。

文件	所做修改
src/ragraf/mcp_server.py	force_utf8_stdio()；--project 不再必需；_resolve_default_project()；ragraf_use_project 工具；--agent 亦可取自 RAGRAF_AGENT；未选定语料时的拒绝——可读文本而非 ConfigError
src/ragraf/cli.py	reindex 命令现在像 index 一样把运行记录写入登记表
tests/test_mcp_compat.py	新文件：针对精简环境、语料自动识别与切换的检查
tools/Invoke-ProjectDoctrine.ps1	Test-McpClientCompatibility 与 Test-ExternalOpsAreRecorded 检查；登记表规则现在检查每个启动索引器的函数而非整个文件（16 项检查，原为 14）
README.md · INTEGRATION.md · AGENTS.md	数字与代码对齐：24 个工具；「三个陷阱」连同实测数据写入文档

与既有客户端的兼容性保持不变：AutoClaw 和 SagaAI 显式传 --project 并设置 PYTHONIOENCODING——对它们毫无影响。

安装——三步

三步都是把文件放入 HARNESS 主目录（%USERPROFILE%\.dsh 或 $DSH_HOME）；现成块位于 RAGRAF 仓库的 harness/ 目录。下列命令中 $repo 是本地 RAGRAF 克隆路径，$dsh 是应用自带 CLI。

接入 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 用于命令行一次性任务。其他配置档同理，把块放入其 cordis.patch.yml 即可。

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
```
把规则加入全局指令HARNESS 读取 %USERPROFILE%\.dsh\AGENTS.md（模块 dsh-agent-instructions；dshHome = $DSH_HOME 或 ~/.dsh）。待插入章节为 harness/agents-section.md；须放在「变更日志」章节之前，否则规则会落在历史记录之后（在已验证的安装中是第 6 节）。预期行为：被问「代码任务从哪里开始」时，智能体回答 mcp__ragraf__ensure 并引用该节。

验证——四个层级

由窄到宽：服务器单独验证 → 应用内实际运行 → 技能 → 项目检查器。每一级都是一条命令和实际会话中测得的预期输出。

针对上述缺陷的检查：运行前移除 PYTHONUTF8 与 PYTHONIOENCODING——正如 HARNESS 所做。测试为 tests/test_mcp_compat.py：精简环境、语料自动识别、切换。

兼容性测试（PowerShell）

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

预期输出

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

headless 配置档下的任务，智能体必须调用工具。事件流中出现带完整信封的 tool_call 与 tool_result：op、rev、capability。

经 dsh CLI 启动（PowerShell）

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

预期输出

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

提供器无需重启即可发现 ragraf-core；此检查确认智能体确实加载了该技能并依据其内容行事。

技能检查

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

预期输出

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

项目准则检查器中的兼容性属性规则——让环境回归在应用启动前被捕获，而不是在会话中。

运行检查器

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

预期输出

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

需要知道的三个限制

必须重启应用

配置档设置在启动时读取。插入的 mcp-ragraf 块在重启 DeepSeek Harness 后才生效；在此之前界面中不会出现 mcp__ragraf__* 工具。这是正常行为，不是故障。

索引时悬挂的 Joern 服务器

完整索引会在 9500 端口启动 Joern（JVM）。实测：首次重建索引后残留一个占用 3 GB、持有该端口的 java.exe 进程；随父进程 cmd.exe 一并终止（taskkill /PID <cmd> /T /F）。长时间作业前后请检查进程与端口：

检查悬挂的 Joern（PowerShell）

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

reindex 曾丢失登记表中的运行记录

在处理同一任务时发现并已修复：index 会把结果写入登记表，reindex 不会。在 RAGRAF 自身语料上实测：索引中是 rev-0046，登记表中是 rev-0045——因此 check 每次验证都重新索引语料，表现为「RAGRAF 很慢」。征兆：catalog 显示的修订与 index_status 不一致。检查器规则现在会检查每个启动索引器的函数。

回滚

HARNESS：从备份恢复补丁层与 AGENTS.md（备份文件名由安装过程打印），删除 ragraf-core 技能目录。

回滚——HARNESS 设置（PowerShell）

$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() 调用、恢复 --project 的 required=True、从 TOOLS 与 _handlers 中删除 ragraf_use_project 工具。

HARNESS 行为：各项位置

内容	位置
应用安装	%LOCALAPPDATA%\Programs\DeepSeek Harness
HARNESS 插件	resources\app.asar · дерево dsh/node_modules
HARNESS 主目录	%USERPROFILE%\.dsh
配置档设置	%USERPROFILE%\.dsh\profiles\<имя>
Electron 数据	%APPDATA%\@deepseek-ai\dsh-desktop
插件注册表	https://registry.npmjs.org/
CLI	resources\runtime\cli\bin\dsh.cmd

主目录由变量控制：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 与 app.asar 内各包的 README——而非文档。

代理规范

规程以两层交付：ragraf-core 技能（提供器无需重启即可加载）与全局规则 %USERPROFILE%\.dsh\AGENTS.md 的章节 — 「代码任务从 mcp__ragraf__ensure 开始」。通用规程片段（「集成」页）是技能的基础，也可独立生效。

遥测

遥测与其他 external 智能体一致：kind=external、以参数哈希代替完整查询文本、usage_call 中的 token 估算（字符/4）——足以对比该组合与 grep 方式的经济性。智能体名称来自补丁块中的 --agent 或 RAGRAF_AGENT 变量：自 HARNESS 修复后服务器即读取该变量。

其他设置指南

将 RAGRAF 接入 AutoClaw 两条独立通道（CLI 与 MCP）、通过产品界面注册服务器、技能装入两个账户、四个已关闭的兼容性缺陷、验证与回滚。打开指南将 RAGRAF 接入 SagaAI 技能库与经由 run_code 的 CLI：如何把 RAGRAF 接入代码中没有 MCP 客户端的平台。事实已对照 v1.13.1 仓库核实。打开指南

全部集成