察元AI文档助手是一款基于JavaScript和Vue 3构建的WPS加载项，它利用WPS JSAPI实现文档读写、任务窗格与功能区交互。本文从源码构建到各平台安装，深入解析其技术架构与部署流程，帮助开发者快速上手并优化工作流。

技术架构与产物形态

察元AI助手本质上是一个WPS文字的JavaScript加载项，前端采用Vue 3与Vite组织界面和打包，通过WPS JSAPI桥接文档操作。模型侧基于HTTP，使用axios发送请求，兼容OpenAI格式的对话与多模态接口，后端可对接Ollama、Xinference、OneAPI网关或云厂商端点。

仓库脚本将Vite构建结果整理为WPS可识别的目录结构，并生成带enable标记的publish.xml，确保在麒麟、UOS等环境下正常加载。在线包与离线包通过npm脚本分流，离线包通常采用7z归档，符合WPS插件生态习惯。

关键点：Vite构建产物需转化为WPS加载项规范，publish.xml的enable标记是解决环境兼容性的核心。

️ 开发环境搭建与联调

首先准备一台安装WPS文字的开发机，并安装Node.js与npm（建议使用LTS版）。克隆仓库后执行npm install安装依赖。日常开发中，npm run dev会启动Vite开发服务器（默认端口3889），可在浏览器中单独调试前端逻辑，但与文档联动仍需回到WPS。

与宿主联调时，使用wpsjs debug命令将加载项指向开发服务或本地构建目录。提交前执行npm run lint和npm run format保持代码风格一致。完整静态资源构建则运行npm run build，生成dist目录。

⚠️ 注意：联调时需确保WPS版本与wpsjs工具链兼容，避免接口差异导致加载失败。

加载项打包命令详解

项目提供了多种打包命令以适应不同场景：

  • npm run build:wps：执行Vite构建并打包为WPS加载项目录结构。
  • npm run build:wps-online：仅生成在线资源包。
  • npm run build:wps-offline：仅生成离线包。
  • npm run build:wps-all：全量打包，适合后续生成macOS pkg或Linux deb。

构建产物位于release目录下的install-staging，包含publish.xml、install.json及插件文件夹。install.json中的addonFolder字段需与目录名一致，安装脚本据此拷贝文件。

推荐：日常开发使用npm run build:wps即可，全量构建仅用于发布前。

️ Windows自解压exe安装

在Windows上，运行npm run build:wps-exe可生成双击即装的exe文件。该命令调用wpsjs build --exe，要求package.json包名为纯ASCII（如chayuan）。成功后，exe文件位于release目录，包含Windows与架构信息。

用户双击后，插件文件被解压并复制到%AppData%\Kingsoft\wps\jsaddons路径。若企业策略拦截未签名exe，需走内部软件分发或先对安装包签名。开发自测时，更推荐使用wpsjs debug指向本地目录，避免每次生成exe。

建议：使用TypeScript或JavaScript编写自定义安装脚本，可增强exe的兼容性。

macOS pkg安装与注意事项

pkg包仅在macOS上构建，需确保本机有bash、pkgbuild、python3等工具。执行bash scripts/build-macos-pkg.sh，脚本先运行npm run build:wps-all，然后将install-staging内容铺到/Library/Application Support/ChayuanWPS，并包含postinstall脚本。

生成的pkg文件位于release目录，命名如chayuan-版本号-macos-arm64.pkg。用户双击安装后，postinstall脚本将插件目录拷贝到沙箱路径：~/Library/Containers/com.kingsoft.wpsoffice.mac/Data/.kingsoft/wps/jsaddons，并对旧版非沙箱布局做最佳尝试写入。

⚠️ 常见问题：未签名pkg可能被Gatekeeper拦截，可通过右键“打开”绕过一次，或使用企业证书签名。

Linux deb包构建与部署

deb包适用于Debian/Ubuntu系，需安装dpkg-deb（可通过sudo apt install dpkg-dev安装）。执行bash scripts/build-linux-deb.sh，同样依赖npm run build:wps-all产物。控制文件声明包名chayuan-wps-addon，依赖python3（用于postinst脚本解析install.json）。

安装命令为sudo dpkg -i 包名.deb。postinst脚本会通过SUDO_USER等变量推断真实登录用户，避免装进root目录。写入路径包括~/.local/share/Kingsoft或~/.local/share/kingsoft小写变体，以及/opt/kingsoft/wps-office/office6/jsaddons等系统级路径。装完后重启WPS即可生效。

技巧：若加载项未显示，可尝试运行quickstartoffice restart刷新宿主。

Ollama与内网模型最小连通

本机安装Ollama并拉取模型后，默认监听11434端口。在察元设置中新增或启用Ollama供应商，基础地址填http://127.0.0.1:11434，模型名与Ollama列表一致。保存后发送一条短消息做探活，比单纯curl更可靠，因为WPS的网络沙箱策略可能与终端不同。

若使用OneAPI或Xinference，将基础URL替换为网关对外地址，并确认路径兼容OpenAI的chat completions接口。云端密钥类供应商则在设置页填写API Key与官方base url，注意不要将密钥提交到公开仓库。

扩展：可结合Go或Python编写自定义模型代理，支持更复杂的鉴权与路由逻辑。

日常使用与最佳实践

首次打开WPS并启用加载项后，先验证模型连通性，再了解能力边界。主界面包含模型下拉、会话区、引用开关及写回操作（插入、替换、批注等）。Ribbon上的文本分析、翻译、多模态等分组对应不同内置助手，右键可快速将选中段落加入助手上下文。

自定义助手在设置中配置系统提示、用户模板和写回位置，将高频场景拆成多个短提示助手，比单一长提示更稳定。任务清单适合固定多步检查（如先摘要再保密检查），每步之间建议人工确认。

⚠️ 安全：涉及脱密、全局替换等操作，务必先备份docx原件到受控位置。

️ 排错与维护

加载项不显示时，检查publish.xml是否在jsaddons根目录且插件子目录名与xml中url一致，并确认enable为“true”。模型报错时核对base url、代理、防火墙与模型别名。JSON类助手解析失败多为模型输出多余文字，可降低温度并强调仅输出合法JSON。

所有路径以仓库脚本与README为准，版本升级时目录名中的版本段会随package.json同步变化，需以手头install.json为准。

总结

察元AI助手展示了如何利用JavaScript和Vue 3构建WPS加载项，并通过多平台打包实现广泛分发。掌握其技术架构与部署流程，能显著提升开发效率。无论是Windows、macOS还是Linux，本文提供的指南均能助你快速集成AI能力到WPS中。