dsh-univer-plugin

一句话定位

这是一个给 DeepSeek Harness 用的办公套件插件,让 AI 在对话中直接帮你创建、修改、检查和导出 Excel 表格、Word 文档、PowerPoint 幻灯片、多维表格和画板。所有改动先放进独立的"草稿副本",你可以在会话里实时预览,满意后再合入或丢弃。

语言: TypeScript (ESM)
关键依赖: @univerjs/core 与 @univerjs-pro/* 系列 Univer SDK、@deepseek-ai/cordis 4.0+、libsql (SQLite) 作为 .univer 文件持久层,以及 puppeteer-core + @puppeteer/browsers 驱动 Slide 布局渲染
架构模式: 标准 DSH Cordis bundle —— Host 组合一个 Service Provider (把 Univer 操作挂到 ctx.univer)、一个 Tools Consumer (注册 univer_* 工具)、一个 webServer Consumer (暴露 /univer-api/* HTTP 路由) 和一个 Skill Provider (挂载分单元技能);自带独立的 Gateway 子进程、无头 Unit Content Worker、Viewer 前端应用和 Slide render machine
入口文件: src/host/index.ts (Host 主入口)、src/client/index.tsx (浏览器侧入口)、cordis.patch.yml (Cordis 挂载点声明)

希望让 DSH 在对话里直接产出可用的表格、文档、PPT、数据库或画板,而不是只能在终端跑命令的用户。比如告诉 Agent "做一个班级成绩表,自动汇总平均分和不及格人数",或者"做一份冒泡排序课件,6 页,每页完成布局检查",或者"把这份 Excel 整理成周报并导出 docx"。

依赖	最低版本	说明
Node.js	>=22.19.0	由 `package.json#engines` 强制,Worker 与 Gateway 子进程都基于 Node 运行
DeepSeek Harness	0.1.0-rc.6	通过 peerDependencies 固定,需要 DSH Web/Desktop 宿主
Chrome / Chromium	本机可执行	仅 Slide 布局检查和 SVG 真实文字度量需要;可执行文件缺失会导致相关工具报错,可用 `UNIVER_RENDER_BROWSER` 指定路径
原生模块	libsql、@univerjs-pro/exchange-node-binding、@univerjs-pro/engine-formula-rust-binding	由本插件自己的 node_modules 提供平台二进制,需要安装时拉取对应平台产物

dsh plugin --profile web add github:dream-num/dsh-univer-plugin

安装后需重启 DSH (dsh web),并在浏览器里刷新已有页面,新插件才会被加载。

配置	类型	说明	默认值
gatewayPort	数字	内置 Gateway 子进程占用的起始本地端口;被占用时依次尝试加一	9080
autoStartGateway	布尔	首次访问文件状态时是否自动拉起 Gateway 子进程	true
gatewayStartupTimeoutMs	数字	Gateway 启动健康检查的超时时间(毫秒)	10000
gatewayRequestTimeoutMs	数字	读取文件状态等只读请求的超时时间(毫秒)	3000
gatewayMutationTimeoutMs	数字	写操作的 Gateway 调用超时时间(毫秒)	60000
unitContentOperationTimeoutMs	数字	导入、导出、结构和执行操作的 Worker 调用超时时间(毫秒)	120000
unitContentCommitTimeoutMs	数字	协作提交确认时,等待服务端应答的最大时间(毫秒)	5000
stateCacheTtlMs	数字	文件状态读取结果的本地缓存时长(毫秒)	1000
unitCacheTtlMs	数字	单元变更读取结果的本地缓存时长(毫秒)	5000
tools	布尔	是否注册 `univer_*` 模型工具	true
skills	布尔	是否注册随插件发布的 8 个 Univer 技能	true

merge 和 discard 是终态操作,会触发 DSH 显式审批;ready 只是把改动标记为待确认,不会修改主线文件。

Q: 安装后还需要做什么?

A: 必须重启 DSH (dsh web),并在已有的浏览器页面里按 Cmd+R / Ctrl+R 刷新。运行中安装不会让当前 DSH 进程自动加载新插件。

Q: 这套插件能在哪些系统上运行?

A: 需要 Node.js 22.19 及以上版本和 DeepSeek Harness。Slide 布局检查和 SVG 文字度量依赖本机 Chrome/Chromium,可用环境变量 UNIVER_RENDER_BROWSER 指定浏览器可执行文件路径。

Q: 改坏了当前文件怎么办?

A: Agent 的每次写入都先进入独立的 worktree,主线文件不会被覆盖。worktree 处于 draft 或 ready 状态时你可以直接丢弃;一旦 merged 或 discarded 就进入终态,不能再 reopen,只能通过历史卡片回看。

Q: 为什么要走 worktree 流程,而不是直接改文件?

A: 这是为了让你在会话里实时预览 Agent 的改动并决定是否合入。ready 只是把改动标记为待确认;只有你显式发起 merge 或 discard 并经 DSH 审批,改动才会落地或被丢弃。

Q: 哪些 Univer 内容类型暂不支持?

A: Slide 的母版、版式页和演讲者备注不在当前编辑范围内;Board 的思维导图、表格、墨迹和高级编辑以及文件导出暂未开放。多维表格和 Board 当前通过 Facade 回读完成结构校验。

Q: 它能直接给我一份 Excel / Word / PPT 吗?

A: 可以。让 Agent 用 univer_import 把 Office 文件导入为新 Unit,改完后用 univer_export 导出 .xlsx、.docx 或 .pptx,可在 Excel、WPS Office、PowerPoint 等常见办公软件继续打开和编辑。

Q: 我没有装 Chrome 会影响哪些功能?

A: 仅影响 Slide 布局检查 (univer_lint) 和 SVG 真实文字度量 (univer_compile_svg)。表格、文档、多维表格与画板的导入、编辑、导出、回读都不依赖浏览器。

Q: 这个插件会自动截图给模型吗?

A: 不会。当前插件不向模型提供截图,结构和布局检查不能替代逐像素视觉验收;你仍然可以在实时 Viewer 里人工检查结果。

进阶 — 需要理解 worktree 生命周期 (ready / merge / discard)、会浏览浏览器侧实时浮窗和回合卡片,并在需要时按本机环境补齐 Chrome 才能用上 Slide 布局检查。

Slide 的母版、版式页和演讲者备注不在当前编辑范围内 (来源: README.md:185)
Board 的思维导图、表格、墨迹、高级编辑以及文件导出暂未开放 (来源: README.md:186)
当前插件不向模型提供截图,结构回读和 Slide lint 不能替代逐像素视觉验收,需要人工在 Viewer 里看 (来源: README.md:184)
Slide 布局检查和 SVG 真实文字度量依赖本机 Chrome/Chromium 可执行文件,缺失会让相关工具失败 (来源: README.md:183)
多维表格和 Board 的结构校验当前依赖 Facade 回读,不是结构化 inspect (来源: README.md:96)
libsql 0.5.29 在 Windows 上关闭数据库时不会 finalize prepared statement,可能触发子进程退出码异常 (来源: src/gateway-app/univerfile-sqlite/connection.ts:50)