复盘一个我自己踩的坑。第一次装「察元AI文档助手」那天我装完就兴冲冲打开 WPS 让 AI 批注错别字结果工具直接报错。当时心里咯噔一下又是装得上用不了的典型开源体验后来翻了文档才发现人家安装脚本最后一步跑了四级体检输出里其实早写了哪一层断了是我自己没看。这篇就把这套体检逻辑掰开讲清楚。先说背景察元是 WPS 加载项加本机 MCP 服务的组合AI 工具Claude Code、Cursor、Codex 都行不是直接操作 WPS而是通过http://127.0.0.1:62588/mcp这个本机 MCP 端点中转。链路一共四层任何一层断掉表现都不一样排查思路也不同。第一层加载项在不在最底下的一层是 WPS 加载项本体。安装脚本会把加载项文件写进 jsaddons 目录并注册 publish.xmlWPS 打开时自动加载。这一层断掉的症状是WPS 里根本看不到察元的功能区。检查办法最朴素——重启 WPS 看加载项有没有挂上。装的时候 WPS 开着是新手最常踩的坑重启一下就好。第二层服务活不活第二层是常驻本机的 chayuan-mcp 服务。这层挂掉时加载项还在但所有请求都超时。检查只要一条curlhttp://127.0.0.1:62588/healthz返回 online 就说明服务进程活着。MCP 生态今年爆发式增长但大量社区 MCP 服务是 npx 拉起的临时进程终端一关服务就没了排查半天发现是进程根本没在跑。healthz 这一条相当于整个链路的地基先看它能省掉一大半无效排查。察元这层是单文件二进制加开机自启正常情况重启电脑后它自己会回来4.1.2 版还修了「运行 Spike」掉线不能自愈的问题偶发断连现在能自己恢复。第三层握手成没成服务活着不代表协议通。第三层是 MCP 的 initialize 握手——客户端和服务端协商协议版本、交换能力清单。这层的标准验证工具是官方 Inspectornpx modelcontextprotocol/inspector打开后传输类型选 Streamable HTTP地址填http://127.0.0.1:62588/mcp点 Connect。能列出工具清单就是握手成功。将来你要接别的 MCP 服务这个排查手法也是通用的值得记住。第四层桥接工具通不通最后一层是 WPS 和 MCP 服务之间的桥。AI 工具调用wps_status它会返回 WPS 侧的分层健康状态如果 WPS 没开wps_launch可以冷启动 WPS 再接管。这一层的典型报错是WPS_AGENT_OFFLINE含义是 WPS 或加载项没连上服务端——回到第一二层找原因就行不用瞎猜。顺手记几个错误码用熟之后几个错误码比教程还好使DOCUMENT_TOO_LARGE是文档超长改用document_chunks分块读LOCATE_MISMATCH是锚点校验失败说明 AI 找的位置和原文对不上CONFIRMATION_REQUIRED是写操作没带确认标记属于安全机制而不是故障。看懂错误码排障基本不用求人。两个容易被误会的假故障一个是LICENSE_REQUIRED免费额度用尽时会返回这个码流程不会被打断更不会弹购买窗口按需处理即可别当成崩溃去反复重装。另一个是MODEL_NOT_CONFIGURED校对类功能依赖模型端点模型没配好时工具会直接说缺什么去设置里把 Ollama 或其他 OpenAI 兼容端点配好就能恢复。这两个码的共同点是报得明确照提示补配置就行不需要翻日志猜。长文档也顺带说一句document_meta会返回文档名称、字数、段数还有一条是否建议分块的提示正文超过约 80k 字符时document_get_text要显式 force 或改走document_chunks分页分块读。演示场合如果有人随手丢来一份几十万字的大部头先调 meta 看一眼再选读取策略就不会当场翻车。我的教训装完任何工具先跑一遍它自带的健康检查再开工这一条现在成了我的肌肉记忆。察元把四级体检直接做进安装脚本收尾输出能看就照着修不能看再逐层排查加载项、healthz、握手、桥接从下往上不过五分钟。工具链越长越要有一眼定位断点的能力。一条 healthz 返回 online比任何应该没问题吧都让人踏实。