前言¶

DeepSeek Harness（DSH）的插件化理念让开发者能通过技能组合扩展智能体的能力。对于需要直接操作企业级协作工具的开发者来说，手动导出文档再交给 agent 处理存在信息丢失与格式错位的问题。本插件配合官方 wps365-cli，把 WPS 365 云文档的读写能力直接嵌入到 DSH 技能体系里，让 agent 能直接读/写文档、表格与多维表，不再需要人工转发文件。

插件定位¶

本插件是 DSH 的一个客户端插件，提供 wps365-docs 技能，用于读取与写入 WPS 365 云文档（智能文档、Office 文件、多维表）。插件本体不保存账号信息，所有操作由用户本机安装的 wps365-cli 完成。维护者 YiuTerran，开源协议 MIT。

核心能力¶

读写智能文档（.otl）¶

• 读智能文档：将 .otl 还原为 Markdown，保留标题、列表、表格、引用、加粗、代码块，长文自动分页读取，避免上下文溢出。
• 下载内嵌图片：提取文档内所有图片（含表格单元格中的图、processon 图），按需读入上下文。
• 写入智能文档：支持整篇替换、追加到末尾、插入到最前；支持写入前预演块结构。
• 逐段编辑：支持对智能文档的段落进行原地修改，无需整篇重写。
• 冲突检测：写入前比对云端是否被他人修改，发现冲突会停止并提示位置，避免静默覆盖。

读写 Office 文件¶

• 读取 .docx / .xlsx / .pptx：下载原件到本地，抽出正文 Markdown、表格、公式原文，每个工作表一份 CSV。
• 本地编辑后上传：对附件表格编辑后整文件上传，保持 file_id 与分享链接不变，版本历史与回滚能力保留；也支持新建文件。

读写云端表格（.xlsx）¶

• 一条龙操作：下载 → 改单元格 → 重算公式缓存值 → 上传，一条命令完成。
• 公式与格式：依赖 openpyxl 读取公式与格式，写入后重算缓存值。

读写多维表（.dbt）¶

• 读多维表：先查看 schema，再分页/过滤读取记录；支持视图、字段选择、附件清单。
• 写入多维表：支持部分更新，使用快照 → 校验 → 更新 → 读回校验的流程；非法值会被静默清空，脚本会报错。
• 限制：多维表不是文档/文件夹，drive file list 返回空，file-content 报“文档内容抽取失败”，只能走 dbsheet schema/records。

附件与分享链接¶

• 下载附件：从 raw 记录取 uploadId 下载附件；按文件头纠正扩展名（服务器会把 PNG 转成 JPEG）。
• 分享链接解析：从 kdocs / plus 分享链接解析出文档并正常读取，无需“接收文件”等前置动作。

内置坑点处理¶

插件内置了踩坑经验，包括 17 条智能文档硬约束、15 条多维表硬约束、普通文件接口细节与并发写入语义，能避免表格整块消失、公式变空值、代码块语言降级、写入后下载仍为旧内容、多维表写入成功但字段为空等问题。

安装¶

推荐从 npm 安装：

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

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

从本地目录安装（用于开发调试）：

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

或让 agent 调用：

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

卸载：

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

装好后新开一个会话，用一句“读一下这篇 WPS 文档 <file_id>”测试。技能正文末尾会附带一段「本机资源」，给出脚本目录、wps365-cli 路径与 Python 解释器。

前置准备¶

1. WPS 365 企业版账号：插件仅适用于 WPS 365 企业版账号，个人版账号请勿安装。
2. 安装 wps365-cli：所有云文档操作由这个官方 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

装好后完成应用绑定与授权：

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

授权有效期：access token 2 小时，但 CLI 会自动刷新；delegated refresh token 有效 365 天。授权过期时脚本会自动刷新或打开浏览器重试。

3. Python（带 openpyxl）：读 .xlsx 的公式与云端改表格需要 openpyxl。
4. 会话里有 shell 工具：脚本由模型通过 shell 执行（macOS / Linux 是 bash，Windows 是 PowerShell 或 cmd）。
5. 删除同名本地技能：如果你之前把 wps365-docs 放在 ~/.dsh/skills/wps365-docs，同名技能优先级更高，需先删除才能用插件版本：

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

配置（可选）¶

插件行的 id 是 skill-wps365-docs，默认值即可使用。如需覆盖，在 profile 的 cordis.patch.yml 里写入：

- id: skill-wps365-docs
  name: './index.js'
  config:
    cli: /opt/wps365/bin/wps365-cli
    python: /opt/python/bin/python3

字段名写错会在激活时直接报错。配置表单不会自动渲染，需按 YAML 手写。

使用注意事项¶

• 云文档没有本地撤销：插件会导出备份，重要文档建议手动备份。
• 写入超时不等于失败：接口可能已在服务端提交，脚本会先查块数/记录数避免重写。
• 写入前必须看冲突结论：发现冲突应重新拉最新版本、合并后再写。
• 规模上限：智能文档单次写入 1000 块，脚本自动分批；多维表单请求最多 1024 条，限流约 10 次/秒；代码块语言只有接口枚举内的才保留。
• 普通文件走“下载 → 本地改 → 传回”：.docx / .xlsx / .pptx 没有逐段写接口，公式、格式、合并、多工作表全靠整文件传回。
• 多维表是数据库，不是文档/文件夹：只能走 dbsheet schema/records。
• 权限边界：用你本机 wps365-cli 的身份和权限操作云文档，插件不保存凭据。

适用场景¶

• 需要智能体直接读取 WPS 365 智能文档并提取结构化信息。
• 需要智能体批量处理云端表格、修改单元格或公式。
• 需要智能体操作多维表，进行筛选、过滤或部分更新。
• 需要智能体从分享链接解析并读取文档，无需人工转发。

结尾¶

本插件把 WPS 365 云文档的读写能力直接接入 DSH，适合需要与企业协作平台深度集成的智能体开发场景。插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。

目录页：https://www.skillhub.cn/plugins/YiuTerran/dsh-wps365-plugin
GitHub：https://github.com/YiuTerran/dsh-wps365-plugin