将 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 响应需要按模式解释。此外 CLI 既不依赖应用重启、也不依赖服务器注册 — 不会「悄然掉线」。靶场实测：14 次工具调用对无索引的 28 次；首次请求命中目标文件 — 92%。

MCP 通道：机制与接入

AutoClaw 的 MCP 接入机制与常见客户端（Claude Desktop、Codex、DeepSeek Harness）不同，这一点很关键。会话中实测的四个事实：

1. 1配置文件中没有 MCP 配置在 ~/.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验证，而不是假设接入前以 ragraf 为查询调用 tool_search — 预期为 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_* 表）。

四个兼容性缺陷

接入第二个客户端（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. 3reindex 命令不把运行写入登记簿在自身语料上实测：索引中 rev-0046，登记簿中 rev-0045 且校验和过期；因此 check 每次都重新索引语料，而 catalog 与面板显示的是过去状态。修复：src/ragraf/cli.py — reindex 经与 index 相同的公共入口 watch.record_index_run 写入运行记录。
4. 4ensure 与 use_project 未进入统计遥测以包装器挂在门面的 op_* 方法上，而这两个操作位于 MCP 服务器中。usage 汇总里没有它们 — 也就无法回答智能体是否遵守第一步规则。修复：Facade.record_external_call（src/ragraf/facade.py）加服务器侧记录。修复后实测：按智能体汇总中 ensure 1、use_project 1。

依赖：为什么用 .venv 解释器

在作者机器上，PATH 解释器只能经 PYTHONUSERBASE（%APPDATA%\AutoClaw-oversea-official\toolchain\python\Python313\site-packages）触达 RAGRAF 依赖。外部客户端会清掉它 — PATH 中的 python 便报「未安装 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 KiB，编码为无 BOM 的 UTF-8，换行为 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() 调用、把 --project 的 required=True 改回、从 TOOLS 与 _handlers 删除 ragraf_use_project。它们都不触及索引、存储模式、修订编号或登记簿 — 回滚无需重建索引。

账户中的技能副本从项目恢复：

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