# dsh-univer-plugin

> 让 DeepSeek Harness 直接读写表格、文档、幻灯片、多维表格与画布,所有改动先放在隔离 worktree 中预览,确认后再合入或丢弃。

## Metadata

- Author: [@dream-num](https://github.com/dream-num)
- Repo: <https://github.com/dream-num/dsh-univer-plugin.git>
- GitHub: [dream-num/dsh-univer-office](https://github.com/dream-num/dsh-univer-office)
- Stars: 55
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://univer.ai>
- Topics: `deepseek-harness`, `deepseek-harness-plugin`, `dsh-plugin`, `office`, `office-harness`
- Forks: 6
- Open Issues: 1
- Last push: 2026-08-20T13:32:19.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

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

## 核心能力
- 创建和编辑 Excel 兼容的电子表格,支持单元格、公式、样式、图表、透视表、筛选器和迷你图,导出为 `.xlsx`、`.csv`、`.tsv`
- 创建和排版 Word 兼容文档,支持段落、列表、表格、图片、图表、页眉页脚、分页和页面布局,导出为 `.docx`
- 从大纲生成 PPT 兼容的演示文稿,支持重设计指定页、编辑形状和图表、检查文字越界/溢出/重叠,导出为 `.pptx`
- 搭建多维表格数据库和可编辑画板,支持公式字段、筛选、排序、分组、连接线和原生图表
- 处理常见 Office 文件,导入 `.xlsx`、`.csv`、`.tsv`、`.docx`、`.pptx`,修改后按对应格式导出
- 所有写入操作走隔离的 worktree 流程,支持草稿编辑、提交审阅、重新打开、合入主线和丢弃

## 技术实现
- **语言**: 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 提供平台二进制,需要安装时拉取对应平台产物 |

## 安装方式
```bash
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)

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-univer-plugin](https://deepseek-plugin.org/plugins/dream-num/dsh-univer-plugin)
Wiki generated by AI (model: `MiniMax-M3`)