前言¶
DeepSeek Harness (DSH) 通过插件机制扩展能力，允许 AI Agent 在 Web UI 中与后端资源交互。在电子表格场景下，如果需要在浏览器界面中实时打开、新建或修改 Excel 文件，就需要一个前端驱动来桥接 AI 工具与 SpreadJS 引擎。该插件旨在解决 AI 无法直接操作 Web UI 中电子表格的问题。
这是什么¶
grapecityxa/dsh-plugin-spreadjs-driver 是一个客户端插件，由 GrapeCityXA 维护。它允许 AI 在 DSH Web UI 中打开、新建和操作 SpreadJS 工作簿。
其核心逻辑是“桥接”：
* Editor 负责：拥有 Workbook 实例、SpreadJS 引擎、界面加载、保存和恢复。
* Driver 负责：提供 AI 工具、路由聊天请求、执行 JavaScript 代码。
插件不包含 SpreadJS/Designer 引擎，也没有运行时依赖，完全依赖配套的 Editor 提供环境。
安装与依赖¶
使用前需满足环境要求：Node.js >= 22.19，DSH 版本 >= 0.2.0-rc.2。
该插件必须与 @grapecity-software/dsh-spreadjs-editor 配合使用。两者需安装到同一个 web profile 中：
dsh plugin --profile web add @grapecity-software/dsh-spreadjs-editor
dsh plugin --profile web add @grapecity-software/dsh-spreadjs-driver
配置完成后，在 DSH Web UI 的“设置 → 电子表格编辑器”中选择该 driver，并等待加载完成。
核心工具¶
插件提供三个核心工具，用于状态查询、文件操作和代码执行：
- sjs_live_status：查询当前聊天的连接状态及可用工作簿。
- sjs_live_open：打开工作区文件并等待 Workbook 就绪；通过
create: true参数可从内置空白模板新建.xlsx。 - sjs_live_execute：在 editor 提供的 Workbook 实例上执行 JavaScript 代码。
典型用法¶
打开或新建工作簿¶
在 AI Skill 的上下文中调用工具：
// 新建文件
sjs_live_open({ path: "test-output/report.xlsx", create: true })
执行代码修改数据¶
在执行工具中编写 JavaScript，使用提供的 sheet()、setValue() 和 snapshot() 等辅助函数：
const s = sheet()
s.setValue(0, 0, '合计')
return snapshot()
执行期间，代码运行在 editor 页面环境，修改会立即显示在界面上。
注意事项与机制¶
- 独占锁机制：执行
sjs_live_execute期间，editor 会授予独占 lease，阻止用户在执行期间进行并发编辑、保存或导出操作。 - 保存时机：修改仅实时显示在 editor 中。只有当用户在 Web UI 中手动请求保存时，数据才会写入磁盘。脚本中调用
save: true不会直接触发保存，而是将状态标记为“待保存”。 - 环境隔离：执行环境提供
spread/workbook、GC、sheet(name?)、snapshot()、console和signal（AbortSignal）。结果必须可 JSON 序列化。 - 兼容性：同一聊天有多个可用实例（如多个标签页）时，必须通过
sjs_live_status获取完整的id并指定给target，不要自行拼接路径。 - 纯 CLI 限制：服务端无需安装 Chrome/Edge，但纯命令行模式无法操作工作簿，必须依赖 Web UI。
生态与链接¶
该插件遵循 MIT 许可证。DSH 插件生态与 DeepSeek 或幻方无官方从属关系。
- 目录页：[catalog_url]
- 源码：[github_url]
