dsh-plugin-wps-office-next

dsh-plugin-wps-office-next

让 DSH 替你动手操作 WPS 表格 / 文字 / 演示。你用中文把要求说清楚，它去改数据、排格式、画图、导出，最后把文件存好。

装好以后，你可以直接这样提要求：

把桌面上的《销售明细.xlsx》按地区汇总到一张新工作表，降序排，再画一张柱状图，最后导出成 PDF 放到同一个文件夹。

这件事对两种人最有用：天天在 WPS 里重复做表格、排版、套模板的人，以及已经在用 DSH 处理文字、希望它直接动手改文件而不是只写一段操作说明的人。

你不需要给 WPS 装加载项，不需要配环境变量，也不需要写一行代码。改动都发生在你本机已经打开的 WPS 里，插件自己不联网、不会把文件传到别处；真正会读到文档内容的是你正在使用的那个 AI 模型，敏感文件请按你所用的模型服务的隐私政策自行判断。

安装也简单：把下面「怎么装」那一段整段复制给你的 DSH AI，剩下交给它。你唯一要亲手做的是重启一次 DSH。

它能帮你做什么

表格（WPS 表格 / Excel）

• 读数据、写数据、批量填充，跨工作表搬来搬去
• 排序、筛选、去重、分列、分类汇总、合并计算
• 写公式并重算，单变量求解（给定目标值，倒推出需要的输入）
• 单元格格式、数字格式、条件格式、数据验证
• 图表（可以带标题和数据标签）、透视表（新建、刷新、清除）
• 表格对象、命名范围、批注、冻结窗格、分级显示
• 页面设置和打印（打印标题、页眉页脚、横向 A4 之类）
• 导出图片、转 PDF、另存成别的格式

文字（WPS 文字 / Word）

• 新建、打开、保存、另存、关闭
• 读写正文和段落，设置字体、样式、行距、对齐
• 查找和替换。注意「只查找」和「替换」是两个明确不同的动作，不会顺手改坏文档
• 文档里表格的读写和编辑，增删行列、合并拆分、套样式
• 页眉页脚、按节的页码格式与分节重编号、分节、分栏、按节的页面设置（一节一个纸张方向）
• 目录、书签、超链接、脚注尾注、索引、交叉引用、内容控件
• 批注和修订的查看、接受与拒绝，以及字数统计
• 邮件合并：拿一张 CSV 表，一次生成几十份文档，母版不动

演示（WPS 演示 / PPT）

• 新建、打开、保存演示文稿
• 增删幻灯片、套用版式、填标题和正文
• 文本框、形状、填充和字体、形状效果
• 插入表格和图片，统一样式
• 切换效果、动画、演讲者备注
• 把幻灯片导出成图片

几个应用一起用

• 在三个应用之间搬数据，比如「Excel 里算好的数字写进 Word 报告，再导出 PDF」
• 保存、另存为、格式互转（含转 PDF）
• 查看当前开着哪些工作簿、文档、演示，以及 WPS 连接状态
• 一次批量执行多个操作（单次上限 50 个），省得来回等

完整的工具清单在 skills/ 各目录下的 reference.md 里；在 DSH 里直接问「WPS 能做哪些事」也行。

可以这样对它说

下面这些都能直接照着说，改动一下细节就能用：

怎么装

不用自己敲命令。打开 DSH 新建一个会话，把下面整段复制粘贴发出去，剩下的交给它：

请帮我在本机安装 DeepSeek Harness 插件 dsh-plugin-wps-office-next
（npm 包名就是这个；仓库：github.com/sueccku/dsh-plugin-wps-office-next）。

用途：装上之后，我可以用中文让你操作本机的 WPS 表格 / 文字 / 演示
（读写数据、排版、做图表、转 PDF 等）。

请按下面的步骤执行，遇到不确定的地方先问我：

1. 环境检查：本插件只支持 64 位 Windows 10/11 + WPS Office 12.1+（64 位）；
   还需要 Node.js ≥ 22.19 和 pnpm。不满足的项目直接告诉我，不要硬装。
2. 判断我当前正在使用的 DSH profile（把 <profile> 换成它的名字）。
3. 执行安装：
   dsh plugin --profile <profile> add dsh-plugin-wps-office-next
   如果报 ERR_PNPM_FETCH_404 或装不上，改用 GitHub 标签重试：
   dsh plugin --profile <profile> add github:sueccku/dsh-plugin-wps-office-next#v0.8.2
4. 用下面这条命令确认接线成功（输出里应出现 wps-office-next-plugin 与 mcp-wps-office-next）：
   dsh --profile <profile> --dump-config | Select-String wps
5. 然后告诉我「请完全关闭并重新打开 DSH，回来再让我验证」。
   插件是在 DSH 启动时加载的，必须重启才会生效。
6. 我重启回来后，先提醒我启动 WPS 并打开一个表格/文档，然后调用 wps_status，
   确认返回 connected: true（此时 advertisedTools 应为 95，registeredTools 应为 270）。

安装、排错与卸载的完整说明见 README 的「给 AI 的安装指引」一节：
https://github.com/sueccku/dsh-plugin-wps-office-next#给-ai-的安装指引

AI 装完后，按它说的完全关闭 DSH 再重新打开。重启后新建一个会话，问一句「WPS 连上了吗」就行。

自己动手前顺手确认两件事：系统是 64 位 Windows，WPS 是 12.1 及以上的 64 位版本。其他环境（Node.js、pnpm 之类）AI 会自己查，缺什么它会告诉你怎么办。

用之前，有几件事值得知道

• 重要文件先备份。 COM 的改动不一定进撤销栈，Ctrl+Z 不一定救得回来。批量改动之前先复制一份，花的是一分钟。
• 结果里的 warnings 要扫一眼。 它的意思是「主要操作已经做完，但某个次要步骤没成功」，通常需要你确认一下。
• 关闭「从来没保存过」的文件时，插件会自动选不保存并关闭，同时回报一条 warning，免得弹出保存对话框把流程卡死。文件里有重要东西的话，请自己手动保存。
• 同一时间只让一个程序操作 WPS。 多个 DSH 会话，或者你一边手工点、AI 一边改，会互相干扰，因为它们共用同一个 WPS 实例。插件现在会主动拦下第二个 DSH 会话并回一句中文说明，但「你手工操作」和「AI 操作」之间的打架只能靠你避开。
• 以文件为准。 插件改动后会自己复验一遍，但涉及重要数据时，建议你还是打开确认一下。
• DSH 自带的 office 技能和本插件不是一回事。 DSH 0.2.0 起内置 office-docx / office-xlsx / office-pptx（离线读写文件，基于 LibreOffice），本插件是操作你正在运行的 WPS 窗口（改完你眼前那份、看得见）。两者不冲突，但同一件事可能走两条路——想让它用 WPS，就在要求里点名「用 WPS 打开 / 操作」。

现在还做不到的

• 只支持 Windows x64 + WPS 12.1+（64 位）。 macOS / Linux 支持已经整体移除；32 位的 WPS 和「多组件模式」也不行。
• 不给 WPS 装或卸加载项。 走的是纯 COM 通道，本来就不需要加载项。
• 不承诺能撤销。 COM 改动不一定进撤销栈。
• 带打开密码的文件不会被打开。 WPS 遇到加密文档会弹一个密码框，而模态框一旦弹出来会把整个会话卡住（把后台进程杀掉也没用，框还在）。插件现在在打开之前先看文件本身：加密的文件会被直接认出来，不弹框、也不去碰 WPS，立刻报错并告诉你怎么办——先用 WPS 手工打开它、另存为一份不加密的副本，再对副本操作。三个应用（表格 / 文字 / 演示）以及「从另一个演示文稿插入幻灯片」都走这条预检。
• 文件正被别的程序占用、或者文件在网络盘上而网络掉线时，打开可能要等很久。 插件在打开前不做占用探测（WPS 自己就持有文件句柄，独占探测会误伤「重新打开已经打开的文件」），网络路径的可达性检查也没有便宜的做法；遇到这种情况请先在资源管理器里确认文件可用，再让 AI 重试。
• 超时的意思是「状态未知」，不是「已经失败」。 如果某个操作超时，插件会告诉你 WPS 可能被某个对话框挡住、或者已经没响应，并且不会替你关掉 WPS（关掉会丢了你没保存的东西）。请切到 WPS 窗口把弹框处理掉再重试。之后插件会先用一个较短的超时快速失败，成功一次就恢复正常。
• 下面这些能力卡在 WPS 自身，实测做不了，如实记录、不再反复尝试：
  • 水印：WPS 页眉的 Shapes 集合不接受任何图形；
  • 文档属性（内置和自定义）：BuiltInDocumentProperties / CustomDocumentProperties 是坏壳；
  • 切片器：缓存能建出来，但 Slicers.Count 永远是 0，用户看到的切片器不会出现；
  • 场景管理器：Worksheet.Scenarios 在 COM 里被暴露成方法，语义读不干净；
  • 演示里的圆角半径：Shape.Adjustments 实测同样是空壳 —— 连 VBScript 的标准赋值 （shp.Adjustments(1) = 0.4，与 VBA 同款）都改不动（before=1 after=1，而且报 set-ok，属于静默忽略）； 点号写法与反射（InvokeMember、SetProperty）四种写法也都无效。所以 wps_ppt_set_shape_style 的 roundness 在 WPS 上不可用，调用时会如实报失败（不会假装成功）。需要圆角请直接用圆角矩形（type: 5）的默认圆角。
  • 页码的"起始编号"：PageNumbers.StartingNumber 是只读的（写 1、回读永远 0）。所以页码支持 "格式"（阿拉伯 / 罗马 / 字母，numberStyle）和"本节从 1 重新开始 / 续前节"（restartSection）， 但不支持"从第 7 页起"。要这种效果只能重排内容，或接受从 1 开始。
  • 横向与纸张要一起给：只给 orientation: "landscape" 而不给 paperSize 时，WPS 会把纸张改成 "自定义"（不再是 A4/A3）。两个都给就正常；插件内部先设纸张、再设方向（顺序反了方向会被静默吃回纵向）。
  • 还有一个隐藏的逃生舱 wps_execute_method（不在广告面里，技能里也不推荐），只是最后手段，不保证成功。

给 AI 和开发者的部分

下面这些是给 DSH 里的 AI 和要动代码的人看的。普通用户看到这里就可以停了。

给 AI 的安装指引

用户把上面那段话发给你之后，按这里执行；用户也可以把整节内容一起发给你。

1. 环境要求

Windows PowerShell 5.1 是系统自带的，不需要装。硬性条件不满足时如实告诉用户，不要硬装。

DSH Desktop 用户注意：DSH Desktop 自带 Node，但不会把它放进宿主进程的 PATH，而 MCP 子进程的环境又会被清洗掉所有 DSH_* 变量（包括 DSH_DESKTOP_NODE_EXECUTABLE）。所以宿主 PATH 上没有 node 时，插件不会调用它——MCP 条目会改用 DSH 自带运行时里的真实 Node（%DSH_HOME%\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe），找不到才退到宿主自己的 process.execPath。想指定别的 Node，设 WPS_OFFICE_MCP_NODE 即可。

2. 判断要装进哪个 profile

插件必须装进用户当前正在使用的那个 profile，否则重启后没有任何效果。按顺序尝试：

# 从正在运行的 dsh 进程命令行里读出 profile
$cl = (Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
        Where-Object { $_.CommandLine -match 'dsh.*bin[.]js' } |
        Select-Object -First 1).CommandLine
if ($cl -match '--profile\s+(\S+)') { $profile = $Matches[1] }
elseif ($cl -match 'bin[.]js"?\s+(\S+)') { $profile = $Matches[1] }
$profile

• 常见结果：desktop（桌面客户端）、web（浏览器界面）、headless（命令行跑一次性任务）。
• 读不到时：若 $env:DSH_WEB_URL 有值，基本可以判定是 web。
• 仍不确定：看 $env:DSH_HOME\profiles 下有哪些目录，或者直接问用户「你平时是怎么启动 DSH 的」。
• dsh plugin 会把不存在的 profile 自动初始化，所以装错 profile 不会报错，只会"装完没反应"，宁可多问用户一句。

3. 执行安装

dsh plugin --profile <profile> add dsh-plugin-wps-office-next

• 首选 npm（包名 dsh-plugin-wps-office-next，发布于 registry.npmjs.org）。dsh plugin add 接受纯包名、本地绝对路径、Git 地址和 tarball 四种写法，纯包名走的是 npm registry，不依赖 github.com 的可达性。

• 包内已经带了预构建产物，没有任何构建步骤，正常不需要额外处理，也不会出现「构建脚本被拦截」的问题。

• 报 ERR_PNPM_FETCH_404（包名/版本取不到，或该机器改了 registry）或网络不通时，改用 GitHub 标签重试（标签就是发布版本，内容与 npm 包一致）：

  dsh plugin --profile <profile> add github:sueccku/dsh-plugin-wps-office-next#v0.8.2
  

  标签必须是真实存在、且能装上的那个。历史上这里写的是 v0.6.0，而 v0.6.0 从未打过 tag（它的 npm 版本还是坏的、已撤销），照着敲只会拿到 ERR_PNPM_GIT_RESOLVE_FAILED。 每次发版都要把这两处 tag 改成新版本（见 docs/release-checklist.md §6 的"发版动作"，那里把它列成了必做项）。

• 报 ERR_PNPM_GIT_RESOLVE_FAILED、could not connect to server、连接超时等，是这台机器访问 github.com 不稳定。此时优先回到上面那条 npm 命令；确实要走 GitHub 又连不上时，可用打包地址（已实测可行）：

  dsh plugin --profile <profile> add https://codeload.github.com/sueccku/dsh-plugin-wps-office-next/tar.gz/refs/tags/v0.8.2
  

• 注意 dsh 事后那句「构建脚本被拦截 / allowBuilds」提示：本包没有任何 prepare 脚本，也没装 esbuild 之类的原生依赖，所以永远不需要改 allowBuilds。dsh 在 pnpm 失败时会补上这句通用提示，照着改只会白费功夫——先看真正的错误：如果是 ERR_PNPM_GIT_RESOLVE_FAILED / Failed to connect to github.com，用上面的 codeload 地址重试即可（这一条已实测：4.1 秒装好）。

• 如果因为沙箱 / 权限限制写不了 $env:DSH_HOME（受限会话里常见），向用户申请一次授权后重试；或者把命令原样交给用户，让他在 PowerShell 里跑一次。

• 如果用本地克隆的仓库安装：dsh plugin --profile <profile> add <仓库绝对路径>。

4. 确认接线成功（不用重启就能查）

dsh --profile <profile> --dump-config | Select-String wps

输出里应出现 wps-office-next-plugin 和 mcp-wps-office-next（分别对应 DSH 插件入口和 MCP 客户端）。同时确认 profile 的 package.json 里 dsh.profile.bundles 已包含 dsh-plugin-wps-office-next——dsh plugin add 会自动加，不需要手改。

5. 让用户重启，然后验证

插件在 DSH 启动时加载，必须重启。请明确告诉用户：

请完全关闭 DSH 再重新打开（例如关掉窗口后重新运行 dsh web），然后回来告诉我。

用户回来之后：

1. 先让他启动 WPS，并打开一个表格 / 文档 / 演示；

2. 调用 wps_status，确认 connected: true；

3. 正常结果形如：

   connected: true
   advertisedTools: 95
   registeredTools: 270
   

第一次调用可能慢约 1 秒（COM 宿主冷启动），之后 1–2 毫秒，属于正常。

6. 排错

7. 完整环境自检（可选）

cd "$env:DSH_HOME\profiles\<profile>\node_modules\dsh-plugin-wps-office-next"
node scripts\doctor.mjs

宿主 PATH 上没有 node 时（DSH Desktop 自带 Node，但不会放进宿主 PATH），用 DSH 自带运行时跑：

$node = if ($env:DSH_HOME) { "$env:DSH_HOME\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe" } else { "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe" }
cd "$env:DSH_HOME\profiles\<profile>\node_modules\dsh-plugin-wps-office-next"
& $node scripts\doctor.mjs

逐项检查系统位数、Node 版本、MCP 子进程将要用的那个 Node（与宿主 PATH 无关，见「环境要求」下方的说明）、PowerShell STA、包内容是否完整、WPS 能否连上、已安装 WPS 的版本与架构（≥ 12.1 且 64 位）以及插件接线（cordis.patch.yml 里是否有 wps-office-next-plugin 与 mcp-wps-office-next 两个 id，且 MCP 行的 command 不是裸 node），最后打印 DOCTOR OK 或具体错误。

卸载

卸载同样可以交给 AI，把下面这句发给它：

请帮我卸载 DSH 插件 dsh-plugin-wps-office-next：先判断我当前使用的 profile，
然后执行 dsh plugin --profile <profile> remove dsh-plugin-wps-office-next，
完成后告诉我需要重启 DSH。

自己动手的话，就是这一条命令（把 web 换成你的 profile），然后重启 DSH：

dsh plugin --profile web remove dsh-plugin-wps-office-next

插件不会往 WPS 里装任何东西，所以卸载它不影响 WPS 本身。

它是怎么做的

node scripts\doctor.mjs

# 1) 类型检查 + 构建（dist 已入库，构建产物要与源码一致）
cd mcp; npx tsc; cd ..

# 2) 由桥源码重新生成 host/wps-actions.ps1（生成前会解析校验）
powershell -NoProfile -File scripts\build-host-actions.ps1

# 3) 由操作规格重新生成 spec/*.json，再由注册表重生成 4 份 reference.md、覆盖矩阵与现值数字
node scripts\gen-tool-surface.mjs
node scripts\gen-skill-tools.mjs
node scripts\gen-tool-coverage.mjs
node scripts\gen-numbers.mjs            # 只核对不落盘用 --check（文档数字与生成值必须一致，FIXES 91）

# 4) 门禁：项目 lint、门面 / 派发 / 预算 / action 数量三方一致、参数契约对账、静态测试
npm run lint
node scripts\verify.mjs --static        # 不带 --static 时会连 WPS 调一次 wps_status，那部分属第 5 步「按需」
node scripts\param-contract.mjs
node scripts\gen-numbers.mjs --check    # 文档声明值与生成值对账（不写盘）
node test\spec-reproduction.test.mjs    # P1 验收：spec 能复现出模型看到的工具面
npm run test:static                     # = node scripts\run-static-tests.mjs，跑 scripts\lib\static-tests.mjs 里的清单
npm run verify:package                 # 打包产物冒烟：装一遍 + 启动 MCP server 握手（不需要 WPS）
#    ↑ CI 也会跑（FIXES 84 的门禁）；改动 package.json 的 files 时**必须**本地跑一次

# 5) 需要本机 WPS 的部分 —— **按需，不要每次改完都跑**（见 AGENTS.md §1/§2）
#    只在准备 push 到 GitHub 且用户说「跑」时才执行。逐文件跑之前先清掉插件自己发布的
#    两个环境变量 —— 这个终端若是从「已装本插件」的 DSH 会话里起的，它们会指向 profile 里
#    那份副本，让 plugin.test.mjs 报一处假失败：
#    $env:WPS_OFFICE_MCP_ENTRY=$null; $env:WPS_OFFICE_HOST_SCRIPT=$null
node test\<文件名>.test.mjs             # 逐文件跑（把 <文件名> 换成 test/ 下的真实文件，如 excel-range）
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-tests.ps1  # 整轮 + 回收无头 WPS 孤儿
node scripts\e2e.mjs --profile <name>    # 一键端到端验收（含进程卫生断言）
node scripts\accept-install.mjs          # 全新 profile 安装验收（装一遍再拆掉）

许可

本仓库使用 MIT License，见 LICENSE。

致谢

本项目的底层实现起步于两个早期的开源项目，感谢它们的作者：

• lc2panda/wps-skills —— WPS COM 操作实现与 MCP 工具层；
• CatNebulaaaa/wps-dsh-plugin —— DSH bundle 的接线形态。

二者均为 MIT 许可，来源与处理方式见 THIRD_PARTY_NOTICES.md。经过多轮重构与扩展，本项目的架构、工具面与代码已与上游有很大差异，是独立演进的结果。

本项目为非官方项目，与金山办公、DeepSeek 及上述上游作者均无隶属关系。