企业官网建设流程全解析

1. ZCode 里接 WPS 文档智能体，到底解决什么问题

ZCode 是智谱推出的智能体开发环境，桌面端形态，既能跑自研 Agent，也能挂 Claude Code、Codex 这类命令行智能体统一管理。很多人第一次用它，是拿 GLM 模型干点杂活：写脚本、改配置、整理资料。但真正让文档工作者上头的是另一件事——把 WPS 文档能力接进来，让智能体直接读写你正在编辑的那份文档。

这就是 WPS 文档智能体（察元技能包）的价值。它不是一个独立 App，而是一套跑在本机的 MCP 服务加 WPS 加载项：加载项负责在 WPS 里暴露文档结构，MCP 服务负责把「读取标题」「插入表格列」「按批注写回」这些动作标准化成工具调用。智能体通过 MCP 协议连上它，就能像操作变量一样操作文档。

适合谁？三类人最明显。第一类是天天跟长文档打交道的：标书、合同、技术方案，几十页起步，格式检查、错别字校对、中英对照，人工过一遍要半天。第二类是做数据整理的：报价表、汇总表要批量加列、改表头、拆合单元格。第三类是已经在 ZCode 里跑 Agent 的开发者，想让 Agent 的输出直接落到文档里，而不是复制粘贴。

在 ZCode 里接它有两条路：一条是走内置的 Claude Code 会话，安装脚本自动注册 MCP 和技能文件，开箱即用；另一条是走 ZCode 自研 Agent 或其它智能体，手动配 MCP 服务，再把通用提示词贴进人设。两条路底层是同一个 MCP 服务，区别只在「谁去调它」和「技能纪律从哪来」。

而不管走哪条路，只要涉及模型调用，就会碰到 Key 管理的问题。ZCode 侧的对话模型、察元侧的内容模型，如果各配各的 Key，切换和排障都很烦。TaoToken 的统一 Key 和 API 通道就是来解决这个的：一个 Key 覆盖多个模型入口，Base URL 指向同一网关，配置片段可以复制到不同客户端。下面按两条路分别给可复制的配置和验证动作。

2. 前置底座：WPS 加载项与本机 MCP 服务怎么装

不管走哪条路，底座都得先有：WPS 加载项 + 本机 MCP 服务。这一步不做，后面 ZCode 里配什么都是空的。

Windows 下用 PowerShell 跑安装脚本，一行搞定：

& {[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12;$w=New-Object Net.WebClient;$w.Encoding=[Text.Encoding]::UTF8;$s=$w.DownloadString('https://gitee.com/cloudshd/chayuan-wps-releases/raw/master/scripts/install-wps-skill-chayuan.ps1');if($s.Length -and $s[0]-eq[char]0xFEFF){$s=$s.Substring(1)};& ([scriptblock]::Create($s)) -Fetch}

Linux 和 macOS 用对应的 curl 那行，脚本逻辑一样：下载安装包、投放加载项、注册 MCP 服务、设置开机自启。

跑完之后检查三件事。第一，WPS 的 jsaddons 目录里有了加载项，打开 WPS 能在加载项面板看到。第二，62588 端口的 MCP 服务起来了，浏览器访问：

http://127.0.0.1:62588/healthz

返回里ok为true就绪。第三，如果本机装了 Claude Code，脚本第四步会探测到并自动执行claude mcp add，同时把技能文件投放到~/.claude/skills/。这一步是第一条路能「开箱即用」的关键。

这里有个容易踩的坑：MCP 服务只监听回环地址（127.0.0.1），意味着 ZCode 和 WPS 必须在同一台机器上。如果你的 ZCode 跑在容器或远程主机里，是连不进来的。我试过在 WSL 里跑 ZCode、Windows 里开 WPS，结果 healthz 能通但工具列表刷不出来，就是因为网络命名空间隔离。解决办法是把 ZCode 也装在 Windows 侧，或者用端口转发把 62588 映射过去——但后者会破坏「只监听回环」的安全假设，不建议。

另一个坑是 TLS 版本。老版本 PowerShell 默认用 TLS 1.0，下载脚本会失败。上面那行开头强制设成 TLS 1.2 就是防这个。如果还是报「基础连接已关闭」，检查系统代理设置，或者手动下载脚本再执行。

底座就绪后，先别急着配 ZCode，用浏览器或 curl 直接打一下 MCP 端点，确认服务本身是活的：

curl -s http://127.0.0.1:62588/healthz

返回{"ok":true}之类的结构就对了。这一步能通，后面 ZCode 里连不上就基本是配置问题，不是服务问题。

3. 两条路的可复制配置：Claude Code 会话与自研 Agent 的 MCP 接入

先说第一条路，ZCode 里的 Claude Code 会话。这是最省事的：安装脚本已经帮你把 MCP 注册进 Claude Code 的用户配置，技能文件也投放好了。ZCode 管理的 Claude Code 智能体用的就是这套用户目录配置，所以你在 ZCode 里开一个 Claude Code 会话，察元的技能已经在了，不用再配。

验证方式很直接：ZCode 里开 Claude Code 会话，WPS 打开一份文档，输入：

读取当前文档标题和前两段，只读冒烟。

能念回来就是通了。之后的用法跟原生 Claude Code 完全一样，校对、批注、翻译插段、表格插列，技能文件里的纪律它自己遵守。

第二条路，ZCode 自研 Agent 或里面挂的其它智能体，得手动配 MCP。ZCode 界面跟着版本迭代比较快，我不写死菜单路径，说思路：在设置里找到 MCP 服务或工具集成的入口，新建一个服务，协议类型选 HTTP（Streamable HTTP），名称填chayuan-wps-mcp，地址填：

http://127.0.0.1:62588/mcp

鉴权字段留空，这个服务只在回环地址上监听，不设 token。保存后看工具列表能不能刷出四十多个文档工具，能刷出来就是连上了。

如果你的 ZCode 版本支持按 JSON 配置 MCP，那就是一个mcpServers节点下一条 url 记录的事，跟其它客户端写法一致。可复制的 JSON 片段：

{ "mcpServers": { "chayuan-wps-mcp": { "type": "http", "url": "http://127.0.0.1:62588/mcp" } } }

注意type字段：有的客户端写streamable-http，有的写http，以你 ZCode 版本的文档为准。写错了会报「unknown transport」或直接静默不加载。

自研 Agent 没有 Claude Code 那种技能文件机制，建议把察元技能包里那份通用提示词（generic.prompt.md）贴到 Agent 的指令或人设里。里面是几条硬规矩：动手前先只读确认文档没拿错；写回前先出预览；默认批注不改正文；表格这类结构性写入必须等确认。贴了之后 Agent 干文档活会稳很多，GLM 的中文语感做校对清单质量也够用。

现在说 TaoToken 统一 Key 怎么接。核心思路：把模型调用的 Base URL 指向 TaoToken 网关，Key 用 TaoToken 生成的统一 Key，Model ID 按需选。这样 ZCode 侧的对话模型和察元侧的内容模型可以共用一套凭证，切换模型只改 Model ID。

TaoToken 的 API 入口是：

https://taotoken.net/api

在 ZCode 或察元的模型设置里，填三件套：

Base URL: https://taotoken.net/api API Key: <你的 TaoToken Key> Model ID: glm-4-plus # 或其它你需要的模型

如果你用的是 Claude Code 会话，配置在~/.claude/settings.json或环境变量里：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "<你的 TaoToken Key>" } }

Codex 的话，~/.codex/auth.json里填对应的 Base URL 和 Key。Cline MCP 场景则在 MCP 配置里把模型 provider 指向 TaoToken。三件套（Base URL + Key + Model ID）缺一不可，少一个就会报 401 或 model not found。

这里要强调：TaoToken 是统一的 API 通道，不是替代编辑器或 WPS 的东西。它解决的是「多个客户端、多个模型入口，Key 和地址散落各处」的问题。文档智能体的工具调用走 ZCode 侧的模型，校对翻译这类内容活走察元配置的模型，两头都指向 TaoToken，管理成本就降下来了。

4. 验证请求与成功结果检查点：一次文档生成请求的完整动作

配置完不验证，等于没配。这一节给一次完整的文档生成请求，从发起到检查返回结果。

先确认 MCP 工具列表能刷出来。在 ZCode 自研 Agent 的工具面板里，应该能看到四十多个以文档操作为主的工具，名字类似read_document、insert_table_column、add_comment、translate_paragraph等。刷不出来就回到第 3 节检查 JSON 配置和 healthz。

然后做只读冒烟。WPS 打开一份文档，在 Agent 里输入：

读取当前文档标题和前两段，只读冒烟。

成功结果的检查点有三个：第一，返回内容里的标题和你 WPS 里看到的一致；第二，前两段文字没有乱码或截断；第三，Agent 没有尝试写入或修改文档。第三点很重要——只读请求如果触发了写操作，说明技能纪律没生效，通用提示词没贴对。

只读通了之后，做一次带预览的写入请求。比如给表格加一列：

读取当前文档第一个表格的表头，告诉我产品名称是第几列，然后在它后面插入一列，列名单位。

成功结果的检查点：第一，Agent 先回报定位，比如「产品名称在第 2 列，将在第 3 列插入『单位』」；第二，等你确认后才执行插入；第三，插入后 WPS 里表格确实多了一列，列名正确，原有数据没串位。

再做一个内容活，验证 TaoToken 通道。比如中英对照：

把当前文档逐段翻译成英文，译文插到各段后面，从最后一段往前处理，先预览前两段。

成功结果的检查点：第一，预览的两段译文质量正常，没有机翻腔或漏译；第二，处理顺序是从后往前（避免段落索引错乱）；第三，确认后写回，WPS 里每段后面多了英文段落，格式没乱。

如果这一步翻译质量差或报模型错误，问题多半在 TaoToken 的 Model ID 或 Key 上。检查ANTHROPIC_BASE_URL或察元里的 Base URL 是不是https://taotoken.net/api，Key 有没有多余空格，Model ID 是不是当前账号可用的。

最后做一个端到端的终检场景，把工具调用和模型能力串起来：

对当前文档做终检：标题层级是否连续、段落编号是否跳号、正文里有没有错别字，按问题类型分组出清单，先预览。

成功结果的检查点：第一，清单按「标题层级」「编号」「错别字」分组；第二，每条问题有定位（第几段、原文是什么）；第三，确认后按批注写回，WPS 里能看到批注，正文没被改动。

这一套跑下来，两条路都验证了：Claude Code 会话走技能文件，自研 Agent 走 MCP + 通用提示词，模型调用走 TaoToken 统一通道。任何一环断了，都能定位到具体步骤。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

配置过程中最常见的报错就那几个，逐个说清楚。

401 Unauthorized。这个基本是 Key 问题。检查三处：TaoToken Key 有没有复制完整（有时候复制会带上换行或空格）；Base URL 是不是https://taotoken.net/api，有没有多写或少写/api；请求头里的认证字段名对不对（Anthropic 系是x-api-key或Authorization: Bearer，看客户端要求）。如果 Key 是对的还报 401，去 TaoToken 控制台看这个 Key 有没有绑定正确的模型权限。

local proxy failed。这个报错通常出现在客户端试图走本地代理但代理没起来。如果你在 ZCode 或 Claude Code 里配了HTTP_PROXY/HTTPS_PROXY环境变量，但代理进程没跑，就会报这个。解决办法：要么把代理环境变量清掉，直连 TaoToken；要么确认代理进程在跑。注意，这里说的是正常的网络代理配置，不是任何绕过网络管理的手段。企业内网环境下，按 IT 给的代理地址填就行。

reading choices 相关报错。这个多出现在模型返回结构不符合预期时，比如客户端期望choices[0].message.content，但实际返回的是流式 chunk 或错误结构。检查 Model ID 是不是写成了不存在的名字，或者 TaoToken 通道返回的格式和客户端解析逻辑不匹配。换一个确认可用的 Model ID 试，比如glm-4-plus，能通就说明是模型名的问题。

OAuth 相关报错。Claude Code 或某些客户端默认走 OAuth 登录流程，如果你已经配了 API Key，要把 OAuth 关掉或跳过。在~/.claude/settings.json里确认没有残留的 OAuth token 配置，环境变量里ANTHROPIC_API_KEY优先级要高于 OAuth。Codex 的auth.json同理，填了 Key 就不要留 OAuth 字段。

MCP 工具列表刷不出来。先 curl healthz 确认服务活着；再确认 ZCode 和 WPS 在同一台机器；然后检查 JSON 配置里type字段和 url 路径（/mcp不能少）；最后看 ZCode 日志里有没有「connection refused」或「unknown transport」。

技能文件没生效。Claude Code 会话里如果 Agent 不遵守「先预览再写回」的纪律，检查~/.claude/skills/下有没有察元的技能文件。没有的话重新跑安装脚本，或者手动把技能包里的文件复制过去。自研 Agent 则检查通用提示词有没有贴进人设。

翻译或校对质量差。先确认走的是哪个模型。察元侧的内容活走察元自己配置的模型，跟 ZCode 侧的模型是两回事。如果察元侧没配好，可能 fallback 到默认模型，质量就不稳定。在察元设置里把模型指向 TaoToken 通道，Model ID 选中文能力强的，比如 GLM 系列。

端口冲突。62588 被占用的话，MCP 服务起不来。检查有没有其它进程占这个端口，或者改安装脚本里的端口配置。改完记得同步改 ZCode 里的 MCP url。

这些错排查完，基本能覆盖 90% 的配置问题。剩下的看日志，ZCode 和察元都有日志输出，报错信息通常能直接定位。

6. 把 Key 和通道收拢到一处，文档活才跑得稳

两条路走下来，我的体会是：Claude Code 会话适合快速验证和日常轻量使用，开箱即用，技能纪律现成；自研 Agent 适合深度定制，能把通用提示词改成自己团队的规矩，配合 ZCode 的 Agent 编排做更复杂的文档流水线。

但不管走哪条，模型调用的 Key 和 Base URL 如果散落在 ZCode、察元、Claude Code、Codex 各处，排障就是噩梦。TaoToken 统一 Key 的价值在这里：一个 Key、一个 Base URL，配到不同客户端，切换模型只改 Model ID。401 的时候只需要检查一处，不用满世界找哪个配置文件写错了。

如果你还没开始配，建议顺序是：先装底座，curl healthz 确认服务活；再走 Claude Code 会话做只读冒烟，确认技能文件生效；然后配 TaoToken 三件套，做一次翻译请求验证模型通道；最后切到自研 Agent，贴通用提示词，跑终检场景。每一步都有明确的成功检查点，断了就回到对应章节排查。

文档智能体这东西，配好之后是真的省时间。标书终检从半天缩到十几分钟，中英对照材料不用来回复制粘贴，表格整理说一句话就加好列。但前提是配置要对，Key 要通，纪律要生效。把这几件事做扎实，剩下的就是让它干活了。