一、技术轮廓与产物形态
察元 AI 文档助手是 WPS 文字的 JavaScript 加载项，前端用 Vue 3 与 Vite 组织界面与打包，通过 WPS JSAPI 读写文档、功能区与任务窗格。模型侧走 HTTP，以 OpenAI 兼容的对话与多模态接口为主，axios 发请求，具体后端可以是本机 Ollama、内网 Xinference 或 OneAPI 网关，也可以是各云厂商已适配的端点。仓库脚本会把 Vite 构建结果整理成 WPS 可识别的目录结构，并生成带 enable 标记的 publish.xml，避免在麒麟、UOS 等环境因未启用而不加载离线包。在线包与离线包在 npm 脚本上分路，离线侧常见为 7z 归档，与 wpsjs 生态习惯一致。
二、开发与联调环境
准备一台已安装 WPS 文字的开发机，再装 Node.js 与 npm，建议选用当前长期支持版 Node。克隆仓库后进入根目录执行 npm install 安装依赖。日常界面开发可执行 npm run dev，默认在本机 3889 端口起 Vite 开发服务，浏览器可单独打开该地址做纯前端排查，但与文档联动仍需回到 WPS。与宿主联调时按官方工具链使用 wpsjs debug，把加载项指向开发服务或本地构建目录，具体参数以你本机 wpsjs 版本帮助为准。提交前可执行 npm run lint 与 npm run format 保持风格一致。需要完整静态资源时再执行 npm run build 得到 dist，随后进入加载项打包环节。
三、加载项打包命令怎么选
npm run build:wps 会走项目自带的 build-wps-addon 脚本，完成 Vite 构建并把 Web 资源打成 WPS 加载项目录结构。若只想打在线资源或只想打离线包，可分别使用 npm run build:wps-online 与 npm run build:wps-offline，默认 npm run build:wps 往往两者都做，具体以脚本参数逻辑为准。打全量常用 npm run build:wps-all，便于接着做 macOS pkg 或 Linux deb。脚本会在 release 下生成 install-staging，其中有 publish.xml、install.json 以及形如 chayuan_版本号的插件文件夹，install.json 里的 addonFolder 字段与目录名一致，安装后 post 脚本会据此拷贝。
四、Windows 安装与自解压 exe
在 Windows 上若需要给同事一个双击即装的形态，可在仓库根目录执行 npm run build:wps-exe。该命令内部调用 wpsjs build --exe，要求 package.json 里的包名为纯 ASCII，当前 chayuan 满足条件。成功后会在 wps-addon-build 下生成 exe，脚本再复制到 release 目录，文件名带 windows 与架构信息。用户双击运行后，典型行为是把插件文件解压并复制到当前用户的 AppData 下 Kingsoft wps jsaddons 路径。若企业策略拦截未签名 exe，需要走内部软件分发或先对安装包做签名。仅做开发自测时，更常见的是 wpsjs debug 指向本地目录或开发端口，而不必每次生成 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 脚本。生成的文件位于 release 目录，形如 chayuan-版本号-macos-arm64.pkg 或 x64 变体，与构建机 uname 结果一致。用户双击安装后，postinstall 会尝试把插件目录与 publish.xml 拷到当前控制台用户的沙箱 WPS 路径，即用户目录下 Library Containers com kingsoft wpsoffice mac Data dot kingsoft wps jsaddons，并对旧版非沙箱布局做 best effort 写入 Application Support Kingsoft wps jsaddons。若安装时检测不到桌面用户，文件会留在安装根目录，需先打开一次 WPS 再重装，或按提示手工拷到 jsaddons。未签名的 pkg 可能被门禁拦截，可用右键打开方式绕过一次或走企业证书。
六、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 要用 python3 读 install.json 并合并 publish。安装命令为 sudo dpkg -i 后跟 release 里生成的 chayuan-版本号-linux-架构 deb。postinst 会优先根据 SUDO_USER 等推断真实登录用户，避免只装进 root 家目录；在图形界面双击安装导致没有 SUDO_USER 时，脚本还会尝试 loginctl 与 run user 等启发式。写入路径包括用户下 dot local share Kingsoft 或 kingsoft 小写变体的 wps jsaddons，并对多套 office6 布局做复制，例如 opt kingsoft wps-office office6 jsaddons 以及 UOS 商店版常见路径。装完后重启 WPS。若仍未出现加载项，README 与脚本注释里提到可尝试商店版自带的 quickstartoffice restart 一类命令刷新宿主。
七、Ollama 与内网模型最小连通步骤
本机装好 Ollama 并拉取模型后，默认监听 11434 端口。在察元设置里新增或启用 Ollama 供应商，基础地址填 http 本机 11434，模型名与 Ollama 列表一致。保存后在主对话里发一条短消息做探活，比单纯用 curl 更可靠，因为 WPS 对网络沙箱策略可能与终端不同。若走 OneAPI 或 Xinference，把基础 URL 换成网关对外地址，并确认路径兼容 OpenAI 风格 chat completions。云端密钥类供应商则在设置页填 key 与官方文档给出的 base url，注意不要把密钥写进可被版本管理的配置文件再提交到公开仓库。
八、日常使用流程建议
第一次打开 WPS 并启用加载项后，先做设置里的模型连通性验证，再打开关于页了解能力边界。主界面察元 AI 助手一般有模型下拉、会话区、选区或全文引用开关，以及写回条。写回动作包括插入、替换、批注、链接批注、追加等，单位若强留痕可优先批注类。Ribbon 上文本分析、翻译、多模态、编审等分组对应不同内置助手，具体名称与行为以当前版本为准。右键可快速把选中段落加到助手上下文，减少来回复制。自定义助手在设置里配置系统提示、用户模板、默认写回与显示位置，可把高频场景拆成多个短提示助手，比一个大而全的提示更稳定。任务清单与任务编排适合固定多步检查，例如先摘要再保密检查，每步之间仍建议人工确认。
九、修订模式与备份习惯
在 WPS 开启修订时使用替换类写回，会产生修订记录，是否与单位文控冲突需自行判断。批注类通常更易被审稿接受。凡涉及脱密、全局替换、批量清理样式等操作，务必先备份 docx 原件到受控位置，避免不可逆损失。
十、排错思路简述
加载项不显示时先确认 publish.xml 是否在 jsaddons 根目录且插件子目录名与 xml 中 url 一致，再确认 xml 里 enable 为 enable。模型报错时核对 base url、代理、防火墙与模型别名。JSON 类助手解析失败多为模型多输出了说明文字，可降低温度并在提示中强调仅输出合法 JSON。以上步骤与路径均以仓库脚本与 README 第九节为准，发行物若升级版本号，目录名中的版本段会随 package.json 同步变化，安装说明里引用版本处请以你手头的 install.json 为准。