企业官网建设流程全解析

复盘一个我自己踩的坑。第一次装「察元AI文档助手」那天，我装完就兴冲冲打开 WPS 让 AI 批注错别字，结果工具直接报错。当时心里咯噔一下：又是"装得上用不了"的典型开源体验？后来翻了文档才发现，人家安装脚本最后一步跑了四级体检，输出里其实早写了哪一层断了，是我自己没看。

这篇就把这套体检逻辑掰开讲清楚。先说背景：察元是 WPS 加载项加本机 MCP 服务的组合，AI 工具（Claude Code、Cursor、Codex 都行）不是直接操作 WPS，而是通过http://127.0.0.1:62588/mcp这个本机 MCP 端点中转。链路一共四层，任何一层断掉，表现都不一样，排查思路也不同。

第一层：加载项在不在

最底下的一层是 WPS 加载项本体。安装脚本会把加载项文件写进 jsaddons 目录并注册 publish.xml，WPS 打开时自动加载。这一层断掉的症状是：WPS 里根本看不到察元的功能区。检查办法最朴素——重启 WPS 看加载项有没有挂上。装的时候 WPS 开着是新手最常踩的坑，重启一下就好。

第二层：服务活不活

第二层是常驻本机的 chayuan-mcp 服务。这层挂掉时加载项还在，但所有请求都超时。检查只要一条：

curlhttp://127.0.0.1:62588/healthz

返回 online 就说明服务进程活着。MCP 生态今年爆发式增长，但大量社区 MCP 服务是 npx 拉起的临时进程，终端一关服务就没了，排查半天发现是进程根本没在跑。healthz 这一条相当于整个链路的地基，先看它，能省掉一大半无效排查。察元这层是单文件二进制加开机自启，正常情况重启电脑后它自己会回来；4.1.2 版还修了「运行 Spike」掉线不能自愈的问题，偶发断连现在能自己恢复。

第三层：握手成没成

服务活着不代表协议通。第三层是 MCP 的 initialize 握手——客户端和服务端协商协议版本、交换能力清单。这层的标准验证工具是官方 Inspector：

npx @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，比任何"应该没问题吧"都让人踏实。