上个月帮法规科做内网部署，科长指着屏幕问我："你们这到底装了几个服务？为什么端口监听里 62581 和 62588 都有？"当时我一时没答利索，回家把拓扑画了一遍才算彻底讲清楚。这篇就把这两个端口的分工掰开说说，也当给准备部署察元AI文档助手的同学留个底。先交代科长为什么起疑：内网机器装完，任务管理器多了常驻进程，安全科例行来问端口用途，答不上来就得写书面说明。所以我干脆整理了一张对照卡贴在科室群里：谁在监听、干什么活、要不要联网，一目了然。

先分清：62581 是引擎，62588 是智能体

62581：知识库引擎。 这是察元桌面版/网络版（chayuan-desktop）的地盘，负责知识库 RAG 检索。单机版最省心，http://127.0.0.1:62581 免登录直接用；网络版带 JWT 登录，多人共享一套知识库；系统间对接走 HMAC 应用态鉴权。你在 WPS 里调 kb_retrieve 做 RAG 检索，背后干活的就是它。

62588：MCP 智能体服务。 这是 WPS 加载项带起来的 sidecar，对外说 Streamable HTTP 的 MCP 协议，挂了 46 个文档工具：读正文、写批注、批量替换、插表格行列、多文档交叉校对都在这儿。Claude Code、Codex CLI、Cursor 连的就是这个端口。

一句话记：**检索归 62581，改文档归 62588。**落到实际用法：让 agent 校对一份规程，先 kb_retrieve 查知识库里的术语规范，再 proofread_run 出问题清单，两边互相印证——术语口径以知识库为准，错字以校对为准，各管各的。这种"检索加校对"的组合拳，正是两个端口各司其职的价值。

为什么拆成两个端口

刚开始我也觉得两个服务麻烦，用久了才体会到解耦的好处。知识库引擎升级换版本，文档工具链照常干活；加载项更新，知识库的索引和权限体系原封不动。职能不同的东西分进程部署，本来就是运维常识，只是很多一体化产品为了"装完就能用"把所有东西糊在一个进程里，出问题时一倒全倒。还有一层实际好处：排查故障时责任边界清楚——校对有问题查 62588，检索不出结果查 62581，两边日志分开翻，不会搅成一锅粥。那天安全科来问，我拿分工卡对着端口监听记录讲了三分钟就过了关：两个端口都只监听本机回环地址，不对外发起连接，这正是他们最关心的点。

给科室落地的典型拓扑是这样：一台内网机器跑网络版当知识库底座，各人电脑上的 WPS 加载项通过 MCP 干文档活，需要查资料时走 62581 检索。检索、校对、写回全链路都在内网闭环，文档数据一个字节不出域——这正是数据安全不出域这个话题在 2026 年被反复强调之后，内网用户最在意的一点。

一套引擎，四档用法

察元的引擎是同一套，按规模分四档：

1. 文档助手：就是本项目这个 WPS 加载项，个人装机即用；
2. 桌面版：单机安装包，知识库落在本机；
3. 服务版：Docker 网络版，全科室共用一套知识库；
4. 至臻版：浏览器工作空间，覆盖数百到上万人。

科室场景一般停在第三档就够用了。第四档是给更大规模组织的，个人用户不用纠结。选型经验：从第一档用起，觉得知识库有用再上第二档，多人共享需求明确时直接第三档，一步到位比跳来跳去折腾少。

日常检查两件套

排查时两个端口各验各的。MCP 侧健康检查：

curl http://127.0.0.1:62588/healthz

返回 online 说明文档工具链在线。给 Claude Code 注册 MCP 也是一行：

claude mcp add --transport http chayuan-wps-mcp http://127.0.0.1:62588/mcp

知识库侧连不上时，先确认 62581 服务起没起、网络版的话登录态过没过期，再查 HMAC 对接参数。

边界与提醒

两个端口都只监听 127.0.0.1，本机即信任边界，所以日常不用配 Token；真要远程访问，走代理或者用 CHAYUAN_MCP_PORT 调整端口规划，别图省事直接把端口暴露出去。另外 RAG 检索结果是参考不是权威，涉及定密的材料，检索命中了也要按本单位流程人工核验。拓扑清楚了，出了问题才知道该去敲哪台机器的门。