@tryao/dsh-wps365-plugin

dsh plugin --profile web add @tryao/dsh-wps365-plugin

@tryao/dsh-wps365-plugin

给你的 DSH 装上 WPS 365 云文档能力。

本仓库同时支持 DSH 插件和 Codex 本地插件适配，二者版本同步；安装方式分别说明。Codex 版本的源码与构建说明见 [codex/](codex/README.md)。

装好之后不用再手动导出、复制粘贴：你可以直接让 agent 读一篇 WPS 智能文档、把内容写进云文档、改云端表格里的某个单元格，它都能真的去读写你的 WPS 365 文档 —— 包括别人通过分享链接给你的文档。

⚠️ 本插件仅适用于 WPS 365 企业版账号，个人版账号请勿使用。

它调用的是 WPS 365 企业版提供的云文档接口，wps365-cli 也必须用企业版账号完成授权。WPS 个人版账号没有这些能力，装上也读写不了任何文档；个人版用户请不要安装，也不要尝试用它处理本地文件。

插件本体只提供技能（wps365-docs）与配套脚本，不含任何 WPS 账号信息；所有云文档操作都由你自己安装的 wps365-cli 完成。

---

它能帮你做什么

你可以这样说 · 它会做什么

"把这篇 WPS 文档总结一下" / "这篇智能文档里有哪些待办" · 读智能文档（.otl）：还原成 Markdown（标题、列表、表格、引用、加粗、代码块），长文自动分页读，不把全文塞进上下文

"文档里的那张架构图给我看看" · 下载文档里所有内嵌图片到本地（含表格单元格里的图、processon 图），只按需把你要看的那几张读进上下文

"把这份 Markdown 写进这篇智能文档" · 写入智能文档：整篇替换 / 追加到末尾 / 插到最前；写入前可先预演块结构

"把文档里第二段改掉" · 逐段原地编辑智能文档（块级 API），不用整篇重写

"读一下这个 .docx / .xlsx / .pptx" · 下载原件到本地，并抽出正文 Markdown、表格、公式原文、每个工作表一份 CSV

"把附件里的这个表格改一下再传回去" · 本地编辑后整文件传回：file_id 与分享链接不变，版本历史保留、可回滚；也能新建文件

"把云端表格里 B2 改成 99，D2 加上公式" · 云端 .xlsx 一条龙：下载 → 改 → 重算公式缓存值 → 传回，一条命令完成

"把这个多维表里的周报列出来" / "按项目筛一下" · 读多维表（.dbt）：先看 schema，再分页/过滤读记录；支持视图、字段选择、附件清单，Form 视图会提示改读底层表

"把这条记录的备注改掉" · 快照 → 部分更新 → 读回校验；Link/选项非法值会被接口静默清空，脚本会先校验、写后比对并明确报错

"把周报里那张图下载下来" · 从 raw 记录取 uploadId 下载附件；按文件头纠正扩展名（实测服务器会把 PNG 转成 JPEG）

"这是别人分享给我的链接，帮我读一下" · 从 kdocs / plus 分享链接解析出文档并正常读取（无需"接收文件"这类前置动作）

"帮我把这份文档改一下" · 写入前先比对云端是否已被他人修改；发现冲突就停下、告诉你冲突在哪，绝不静默覆盖

它内置了这套流程里踩过的坑（17 条智能文档硬约束、15 条多维表硬约束、普通文件接口细节、并发写入的实测语义），所以遇到"表格整块消失""公式变成空值""代码块语言被降级""写完下载还是旧内容""多维表写入成功但字段空了"这类问题，它知道该怎么绕。

需要先准备什么

1. WPS 365 企业版账号（必须）

本插件只适用于 WPS 365 企业版账号；WPS 个人版账号不受支持，请勿安装和使用。wps365-cli 需要先用企业版账号授权，本文提到的智能文档、云文档读写与分享链接解析能力才会生效。

2. wps365-cli（运行本插件的必要条件；本插件不安装它，只使用它）

所有云文档操作都由这个官方 CLI 完成；没装它，插件读写不了任何文档。wps365-open/cli 是它的源码与文档仓库，用官方安装脚本安装：

macOS / Linux

   curl -fsSL https://open-docs.wpscdn.cn/cli/install.sh | bash

Windows（PowerShell）

   irm https://open-docs.wpscdn.cn/cli/install.ps1 | iex

Windows（Git Bash）

   curl -fsSL https://open-docs.wpscdn.cn/cli/install.sh | bash

macOS / Linux 默认装到 ~/.local/bin（无需 sudo），Windows 上是 ~\.local\bin\wps365-cli.exe。要指定版本或安装目录，在管道末尾的 bash 前加环境变量：... | WPS365_VERSION=v0.3.6 bash、... | WPS365_INSTALL_DIR=~/.local/bin bash；不想用脚本就去 Release 页面 下载对应平台的二进制文件。

装好后完成应用绑定与授权（只需一次）：

   wps365-cli config init        # 新建/绑定应用，在浏览器里完成
   wps365-cli auth login --device
   wps365-cli user me            # 确认当前登录身份

config init 会打开浏览器完成应用创建/绑定与授权确认；企业管理员建议预先设置 CLI 应用免审规则，手动创建应用、配置回调地址与申请权限的完整流程见官方前置准备：创建应用与权限配置。装在别处就在配置里指定 cli（见下；支持 ~ 与 %NAME%/${NAME} 展开，也可以直接写裸命令名让它在 PATH 里找）。CLI 缺失或未授权不会让插件失效：技能照常可用，只是会在技能正文里明确告诉你 CLI 没找到。

授权有效期：access token 只有 2 小时，但 CLI 会在过期前自动刷新、401 透明重试；delegated refresh token 有效 365 天且每次刷新轮换。正常情况下 auth login --device 一年一次，不必每 2 小时重新登录。refresh token 过期/被撤销、token 存储丢失，或 CLI 回退到 app 身份后报 required delegated scopes 时，插件脚本会自动 auth refresh --delegated，失败则运行 auth login --device 打开浏览器并重试一次；不想自动弹窗可设 WPS365_NO_AUTO_LOGIN=1。直接调用 CLI 前也可手动执行 python3 <技能目录>/scripts/auth.py ensure --cli <cli>。不要设置 WPS365_ACCESS_TOKEN，它会绕过刷新，2 小时后必然失效。官方依据：用户授权流程（refresh_token 365 天、刷新时轮换）与 CLI 认证说明（自动刷新与 401 重试）。刚登录后 refresh_token_expires_at 可能显示 0001-01-01（Go 零值/未提供），这不是过期；auth.py 会显示为“未知”，不会误触发刷新或重登。

3. Python（带 openpyxl）

读 .xlsx 的公式、以及云端改表格需要 openpyxl。默认让 agent 用 load_workspace_dependencies 返回的解释器（该环境自带 openpyxl / python-docx）；想固定一个就在配置里指定 python。

4. 会话里有 shell 工具

脚本由模型通过 shell 执行（macOS / Linux 是 bash，Windows 是 PowerShell 或 cmd）；另外还需要文件读取工具分页读导出的 doc.md、read_image 看图片。

5. 平台差异（Windows）

技能正文里的命令一律是单行、占位符由插件注入真实值，所以两个平台都能直接照抄；注入的「本机资源」一节会告诉你本机平台、Python 解释器、wps365-cli 路径与临时目录。Windows 上另需注意：路径含空格时用双引号包住。

6. 删掉手动安装的同名技能（重要）

如果你之前把这份技能手动放在 ~/.dsh/skills/wps365-docs，同名技能里它优先级更高（用户目录里的技能盖住插件自带的），插件的版本就不会被用上。想让插件版本生效：

   rm -rf ~/.dsh/skills/wps365-docs

技能目录是被 watch 的，删完不用重启。

安装

从 npm 装（推荐） —— 已发布到 npm，按包名安装即可：

dsh plugin --profile desktop add @tryao/dsh-wps365-plugin

也可以在 DSH 的插件管理器界面里搜索 @tryao/dsh-wps365-plugin 安装。

从本地目录装（改插件时用，软链到仓库，改完即时生效；这里的路径是仓库目录，与 npm 包名无关）：

dsh plugin --profile desktop add /绝对路径/dsh-wps365-plugin

或让 agent 调用：

plugin_manager { action: "install_bundle", target: "@tryao/dsh-wps365-plugin" }

装好后新开一个会话，问一句"读一下这篇 WPS 文档 <file_id>"。确认生效的方法：加载进来的技能正文末尾会附带一段「本机资源（由 @tryao/dsh-wps365-plugin 注入）」，里面给出脚本目录、wps365-cli 路径和该用哪个 Python。

卸载：

plugin_manager { action: "remove_bundle", target: "@tryao/dsh-wps365-plugin" }

⚠️ DSH 插件请使用 0.1.1 或更高版本。DSH 的 0.1.0 有一个会让 Harness 打不开的严重问题，它从未发布到 npm；详见 [CHANGELOG.md](CHANGELOG.md)。

在 Codex 中使用

Codex 版本由 codex/ 中的源码构建，和上面的 DSH 插件分别安装。Codex 版本同样仅适用于 WPS 365 企业版账号，个人版账号请勿使用。克隆仓库后，在仓库根目录构建并运行打包检查：

git clone https://github.com/YiuTerran/dsh-wps365-plugin.git
cd dsh-wps365-plugin
npm --prefix codex run build
npm --prefix codex test

构建需要 Node.js 22 或更高版本；生成 .tar.gz 归档还需要系统提供 tar 命令。无需运行 npm install，构建和检查使用 Node.js 内置模块。构建会生成完整插件目录 codex/dist/wps365-docs/ 和归档 codex/dist/wps365-docs-0.2.7.tar.gz。请把构建生成的目录注册并安装；codex/wps365-docs/ 是源码，不含构建复制进去的共享 Python 脚本，不能直接作为完整插件安装。

在 Codex 中可以这样请求安装：

将当前仓库构建得到的 codex/dist/wps365-docs 注册到我的个人本地插件市场，并帮我安装。保留已有市场配置。

Codex 的本地插件市场由本机配置发现，市场清单中的插件路径相对于市场根目录。安装到个人本地市场只对当前用户和设备生效，不会发布给其他用户；每位使用者都要安装并授权自己的 wps365-cli（安装与授权步骤见上文「需要先准备什么」第 2 条）：

wps365-cli config init
wps365-cli auth login --device

可参考 [Codex 官方插件构建说明](https://developer

…(truncated)