dsh-univer-office 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +181 -104
  2. package/README.zh-CN.md +181 -101
  3. package/docs/architecture.md +9 -8
  4. package/docs/assets/readme/chart-and-formatting.png +0 -0
  5. package/docs/assets/readme/live-worktree.png +0 -0
  6. package/docs/assets/readme/presentation-live.png +0 -0
  7. package/docs/assets/readme/presentation-request.png +0 -0
  8. package/docs/assets/readme/presentation-review.png +0 -0
  9. package/docs/assets/readme/review-result.png +0 -0
  10. package/docs/assets/readme/spreadsheet-request.png +0 -0
  11. package/docs/univer-turn-projection-and-surfaces.md +243 -0
  12. package/lib/client.js +440 -475
  13. package/lib/index.js +24 -13
  14. package/package.json +2 -6
  15. package/lib/index.js.map +0 -7
  16. package/lib/types/host/adapters/gateway/client.d.ts +0 -15
  17. package/lib/types/host/adapters/gateway/client.d.ts.map +0 -1
  18. package/lib/types/host/adapters/gateway/file-api.d.ts +0 -18
  19. package/lib/types/host/adapters/gateway/file-api.d.ts.map +0 -1
  20. package/lib/types/host/adapters/gateway/mapping.d.ts +0 -31
  21. package/lib/types/host/adapters/gateway/mapping.d.ts.map +0 -1
  22. package/lib/types/host/adapters/gateway/worktree-api.d.ts +0 -21
  23. package/lib/types/host/adapters/gateway/worktree-api.d.ts.map +0 -1
  24. package/lib/types/host/adapters/unit-content/protocol.d.ts +0 -61
  25. package/lib/types/host/adapters/unit-content/protocol.d.ts.map +0 -1
  26. package/lib/types/host/adapters/unit-content/worker.d.ts +0 -10
  27. package/lib/types/host/adapters/unit-content/worker.d.ts.map +0 -1
  28. package/lib/types/host/artifacts/paths.d.ts +0 -13
  29. package/lib/types/host/artifacts/paths.d.ts.map +0 -1
  30. package/lib/types/host/config.d.ts +0 -45
  31. package/lib/types/host/config.d.ts.map +0 -1
  32. package/lib/types/host/index.d.ts +0 -14
  33. package/lib/types/host/index.d.ts.map +0 -1
  34. package/lib/types/host/processes/gateway/gateway-process.d.ts +0 -10
  35. package/lib/types/host/processes/gateway/gateway-process.d.ts.map +0 -1
  36. package/lib/types/host/processes/gateway/launcher.d.ts +0 -8
  37. package/lib/types/host/processes/gateway/launcher.d.ts.map +0 -1
  38. package/lib/types/host/processes/gateway/protocol.d.ts +0 -5
  39. package/lib/types/host/processes/gateway/protocol.d.ts.map +0 -1
  40. package/lib/types/host/processes/gateway/supervisor.d.ts +0 -19
  41. package/lib/types/host/processes/gateway/supervisor.d.ts.map +0 -1
  42. package/lib/types/host/provider/gateway-univer-service.d.ts +0 -59
  43. package/lib/types/host/provider/gateway-univer-service.d.ts.map +0 -1
  44. package/lib/types/host/provider/plugin.d.ts +0 -6
  45. package/lib/types/host/provider/plugin.d.ts.map +0 -1
  46. package/lib/types/host/provider/render-operations.d.ts +0 -36
  47. package/lib/types/host/provider/render-operations.d.ts.map +0 -1
  48. package/lib/types/host/provider/state-cache.d.ts +0 -13
  49. package/lib/types/host/provider/state-cache.d.ts.map +0 -1
  50. package/lib/types/host/provider/unit-content-operations.d.ts +0 -32
  51. package/lib/types/host/provider/unit-content-operations.d.ts.map +0 -1
  52. package/lib/types/host/provider/worktree-operations.d.ts +0 -13
  53. package/lib/types/host/provider/worktree-operations.d.ts.map +0 -1
  54. package/lib/types/host/service/errors.d.ts +0 -8
  55. package/lib/types/host/service/errors.d.ts.map +0 -1
  56. package/lib/types/host/service/identifiers.d.ts +0 -22
  57. package/lib/types/host/service/identifiers.d.ts.map +0 -1
  58. package/lib/types/host/service/types.d.ts +0 -134
  59. package/lib/types/host/service/types.d.ts.map +0 -1
  60. package/lib/types/host/service/univer-service.d.ts +0 -28
  61. package/lib/types/host/service/univer-service.d.ts.map +0 -1
  62. package/lib/types/host/service/workspace.d.ts +0 -21
  63. package/lib/types/host/service/workspace.d.ts.map +0 -1
  64. package/lib/types/host/skills/plugin.d.ts +0 -6
  65. package/lib/types/host/skills/plugin.d.ts.map +0 -1
  66. package/lib/types/host/tools/definitions/api.d.ts +0 -4
  67. package/lib/types/host/tools/definitions/api.d.ts.map +0 -1
  68. package/lib/types/host/tools/definitions/compile-svg.d.ts +0 -4
  69. package/lib/types/host/tools/definitions/compile-svg.d.ts.map +0 -1
  70. package/lib/types/host/tools/definitions/execute.d.ts +0 -4
  71. package/lib/types/host/tools/definitions/execute.d.ts.map +0 -1
  72. package/lib/types/host/tools/definitions/export.d.ts +0 -4
  73. package/lib/types/host/tools/definitions/export.d.ts.map +0 -1
  74. package/lib/types/host/tools/definitions/import.d.ts +0 -4
  75. package/lib/types/host/tools/definitions/import.d.ts.map +0 -1
  76. package/lib/types/host/tools/definitions/inspect.d.ts +0 -4
  77. package/lib/types/host/tools/definitions/inspect.d.ts.map +0 -1
  78. package/lib/types/host/tools/definitions/lint.d.ts +0 -4
  79. package/lib/types/host/tools/definitions/lint.d.ts.map +0 -1
  80. package/lib/types/host/tools/definitions/new.d.ts +0 -4
  81. package/lib/types/host/tools/definitions/new.d.ts.map +0 -1
  82. package/lib/types/host/tools/definitions/status.d.ts +0 -4
  83. package/lib/types/host/tools/definitions/status.d.ts.map +0 -1
  84. package/lib/types/host/tools/definitions/unit.d.ts +0 -4
  85. package/lib/types/host/tools/definitions/unit.d.ts.map +0 -1
  86. package/lib/types/host/tools/definitions/worktree.d.ts +0 -4
  87. package/lib/types/host/tools/definitions/worktree.d.ts.map +0 -1
  88. package/lib/types/host/tools/plugin.d.ts +0 -7
  89. package/lib/types/host/tools/plugin.d.ts.map +0 -1
  90. package/lib/types/host/tools/presentation.d.ts +0 -64
  91. package/lib/types/host/tools/presentation.d.ts.map +0 -1
  92. package/lib/types/host/tools/workspace.d.ts +0 -16
  93. package/lib/types/host/tools/workspace.d.ts.map +0 -1
  94. package/lib/types/host/webServer/plugin.d.ts +0 -7
  95. package/lib/types/host/webServer/plugin.d.ts.map +0 -1
  96. package/lib/types/host/webServer/router.d.ts +0 -8
  97. package/lib/types/host/webServer/router.d.ts.map +0 -1
  98. package/lib/types/host/webServer/routes/gateway.d.ts +0 -4
  99. package/lib/types/host/webServer/routes/gateway.d.ts.map +0 -1
  100. package/lib/types/host/webServer/routes/state.d.ts +0 -5
  101. package/lib/types/host/webServer/routes/state.d.ts.map +0 -1
  102. package/lib/types/host/webServer/routes/status.d.ts +0 -5
  103. package/lib/types/host/webServer/routes/status.d.ts.map +0 -1
  104. package/lib/types/host/webServer/routes/worktree-action.d.ts +0 -13
  105. package/lib/types/host/webServer/routes/worktree-action.d.ts.map +0 -1
  106. package/lib/types/host/webServer/session-scope.d.ts +0 -6
  107. package/lib/types/host/webServer/session-scope.d.ts.map +0 -1
  108. package/lib/types/shared/wire/actions.d.ts +0 -15
  109. package/lib/types/shared/wire/actions.d.ts.map +0 -1
  110. package/lib/types/shared/wire/state.d.ts +0 -38
  111. package/lib/types/shared/wire/state.d.ts.map +0 -1
  112. package/lib/types/shared/wire/status.d.ts +0 -22
  113. package/lib/types/shared/wire/status.d.ts.map +0 -1
  114. package/lib/types/workers/unit-content/license.d.ts +0 -6
  115. package/lib/types/workers/unit-content/license.d.ts.map +0 -1
package/README.zh-CN.md CHANGED
@@ -1,159 +1,239 @@
1
- # DeepSeek Harness (DSH) × Univer 插件
1
+ # DSH × Univer Office
2
2
 
3
- > **在 DeepSeek Harness 中创建、检查、编辑和审阅 Univer 文件。**
3
+ > 让 DeepSeek Harness 直接创建、编辑、检查和交付表格、文档、幻灯片、多维表格与画布。
4
4
 
5
- [English](README.md) · [中文](README.zh-CN.md)
5
+ [English](README.md) · 简体中文
6
6
 
7
- 在 DeepSeek Harness(简称 DSH)应用内直接创建并预览 Univer 办公文件(表格、文档、幻灯片、Base)。回合使用结构化 `univer_*` 工具后,每个被操作的 `.univer` 文件都会显示一张独立预览卡片,点击即可在应用内全屏展开;worktree 编辑显示实时浮窗,会话结束后的审阅也留在会话内完成。
7
+ [![npm](https://img.shields.io/npm/v/dsh-univer-office)](https://www.npmjs.com/package/dsh-univer-office)
8
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.19-339933?logo=node.js&logoColor=white)](package.json)
9
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
8
10
 
9
- ```
10
- ┌────────────────────────────────────────┐
11
- │ 📊 销售表格.univer [wt-xxx] [展开预览 ▾] │ ← 回合尾部卡片
12
- │ /Users/.../销售表格.univer │
13
- └────────────────────────────────────────┘
14
-
15
- ┌──────────────────────────────┐
16
- │ ● agent-draft · 销售表格 │ ← 实时浮窗(draft worktree)
17
- │ [修改中] [−] [⤢] [✕] │
18
- │ ┌──────────────────────────┐ │
19
- │ │ 实时 worktree Viewer │ │ 双击标题栏最大化,
20
- │ │ (只读 · 实时同步) │ │ 可拖拽 / 缩放 / 折叠
21
- │ └──────────────────────────┘ │
22
- └──────────────────────────────┘
23
-
24
- ┌────────────────────────────────────────┐
25
- │ 🧾 合并预览「agent-draft」 [待确认] ▾ │ ← 会话结束合并面板
26
- │ ┌────────────────────────────────────┐ │
27
- │ │ 合并预览页面(内嵌) │ │
28
- │ └────────────────────────────────────┘ │
29
- └────────────────────────────────────────┘
30
- ```
11
+ `dsh-univer-office` 是 DeepSeek Harness(DSH)的 Univer 办公插件。告诉 Agent 你想要什么,它可以创建和编辑电子表格、文档、演示文稿、多维表格与画布,也可以处理现有的 Excel、Word 和 PowerPoint 文件。所有修改都会经过校验,并留在会话中供你预览、确认或放弃。
31
12
 
32
- ## 功能
13
+ 安装后直接用自然语言描述目标即可。Agent 会完成创建、编辑和校验,你可以在会话中实时查看过程、审阅结果,并把电子表格导出为 Excel(`.xlsx`),或按需交付 Word(`.docx`)和 PowerPoint(`.pptx`)文件。
33
14
 
34
- - **回合尾部预览卡片** —— 使用结构化 `univer_*` 工具的回合结束后,每个被操作的 `.univer` 文件显示一张独立卡片。
35
- - **应用内全屏预览** —— 点卡片在应用内 iframe 中打开表格;✕ / 遮罩 / Esc 关闭。
36
- - **实时浮窗** —— agent 创建或更新 worktree 后,**右上角**弹出小浮窗,内嵌只读实时 worktree 页面;修改会实时出现在浮窗里。一个 worktree 改动多个 unit(如表格+PPT)时,浮窗与审阅面板顶部的 **unit 切换 chips** 只列出有变动的单元(+新增 / ✎修改 / -删除 / ⚠冲突),未变动的单元不显示;默认打开第一个变动单元。
37
- - **浮窗交互** —— 拖标题栏移动,双击标题栏最大化;使用独立的折叠、最大化/还原和关闭按钮;拖任意边缘或角调整大小。折叠时保留已加载的 Viewer,展开可立即恢复。移动、缩放和视口变化都会保持完整窗口可见。
38
- - **ready + 会话结束 → 自动关闭并嵌入审阅卡片** —— 会话转入空闲后,每个 worktree 都会以审阅卡片嵌入最近一次操作它的已结束回合末尾。紧凑卡片 header 首行显示 Univer 文件名及其右侧的 worktree 名称,次行只显示完整文件路径,右侧显示生命周期状态和控制按钮;不同生命周期的展开卡片使用相同宽度和内容高度。Univer 页面可折叠但不会卸载,并支持一键全屏和按 Esc 退出。`ready` 显示完整合并页(`scope=mergePreview`),丢弃 / 合入当前版本只使用页面内置操作,不在卡片底部重复显示;**`draft` 也会显示**完整实时页面以及提交确认 / 丢弃按钮。merge 或 discard 后,同一张卡片继续保留,移除修改操作,并把完整页面切换到主线。后续回合再次操作该 worktree 时,旧回合保留同款审阅 header 作为历史标记,完整交互卡片移动到新回合末尾。Univer 文件尚无 Unit 时,只把原空状态标题改为“空文件”。会话仍在运行时,非终态 worktree 在右上角浮窗显示。
39
- - **审阅卡片视区** —— 桌面端展开后的卡片默认总高度约 650px;卡片内嵌的完整 Univer 页面默认收起左侧边栏,仍可在页面内手动展开。卡片进入全屏后隐藏折叠按钮,退出全屏后恢复。
40
- - **内置 Gateway 管理** —— 插件自带协作 Gateway 与 Viewer;绿点 = 运行中,黄点 = 未运行,点击即可启动插件持有的 Gateway。
41
- - **多会话并行** —— 各会话显示各自回合的卡片、浮窗与合并面板。
42
- - **双语界面** —— 插件外壳和所有已打开的 Viewer 都跟随应用语言(中/英)。
15
+ ## 看看实际效果
43
16
 
44
- ## 环境要求
17
+ 下面的电子表格由 Agent 根据自然语言要求创建,并在同一个会话中继续添加条件格式和图表。完成后可以直接预览、继续修改、合入当前版本或丢弃。
45
18
 
46
- - DeepSeek Harness 与 Node.js 22.19 或更高版本;当前平台的原生依赖由包管理器从 registry 安装。Slide 布局检查和 SVG 真实文字测量需要本机 Chrome/Chromium,或设置 `UNIVER_RENDER_BROWSER`。
47
- - 不需要全局安装 Univer CLI。插件内置 Gateway、Viewer、无头 Unit Content Worker、machine render page、Office 转换器、Univer license、当前平台的原生依赖及 8 个版本匹配、按需加载的 Univer Skills:核心编排、5 类 Unit 指南、Embed 与跨 Unit 公式。除 DSH Tool/Client 预览替代 CLI command、以及插件尚未开放的能力外,工作流与 Univer CLI 保持一致。插件注册 `univer_new`、`univer_status`、`univer_worktree`、`univer_unit`、`univer_import`、`univer_inspect`、`univer_execute`、`univer_export`、`univer_lint`、`univer_compile_svg` 和 `univer_api`。
48
- - 暂不提供模型截图能力。bundled Skill 会在视觉效果尚未验证时明确说明,不会声称已经完成视觉确认。
19
+ ![在 DSH 会话中审阅带条件格式和图表的电子表格](docs/assets/readme/chart-and-formatting.png)
49
20
 
50
- ## 安装
21
+ > **可以直接交付 Excel 文件:** 审阅完成后,让 Agent 将电子表格导出为 `.xlsx`,即可使用 Excel、WPS Office 等常见办公软件继续打开和编辑。
51
22
 
52
- 本包是一个标准 [DSH bundle](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.md):声明了 `dsh.bundle` 并自带 `cordis.patch.yml`,可通过标准 loader 安装:
23
+ <details>
24
+ <summary>查看从提出需求到审阅结果的完整过程</summary>
53
25
 
54
- ### 从 git 安装
26
+ ### 1. 用自然语言描述任务
55
27
 
56
- ```sh
57
- dsh plugin --profile web add github:dream-num/dsh-univer-office
28
+ ![要求 Agent 创建班级成绩表](docs/assets/readme/spreadsheet-request.png)
29
+
30
+ ### 2. 修改过程中实时查看结果
31
+
32
+ ![Agent 工作时显示实时电子表格浮窗](docs/assets/readme/live-worktree.png)
33
+
34
+ ### 3. 在会话中确认或放弃修改
35
+
36
+ ![任务完成后的电子表格审阅卡片](docs/assets/readme/review-result.png)
37
+
38
+ </details>
39
+
40
+ ### 从一句话生成可交付的演示文稿
41
+
42
+ Agent 可以根据主题、受众、页数、内容结构和视觉要求生成完整演示文稿,在制作过程中逐页检查内容与布局,并把结果留在会话中审阅。
43
+
44
+ ![在 DSH 会话中审阅冒泡排序教学演示文稿](docs/assets/readme/presentation-review.png)
45
+
46
+ > **可以直接交付 PowerPoint 文件:** 审阅完成后,让 Agent 将演示文稿导出为 `.pptx`,即可使用 PowerPoint、WPS Office 等常见办公软件继续播放和编辑。
47
+
48
+ <details>
49
+ <summary>查看演示文稿从需求到成品的制作过程</summary>
50
+
51
+ #### 1. 说明主题、受众和页面要求
52
+
53
+ ![要求 Agent 创建冒泡排序教学演示文稿](docs/assets/readme/presentation-request.png)
54
+
55
+ #### 2. 制作过程中实时查看和校验页面
56
+
57
+ ![Agent 制作演示文稿时显示实时预览窗口](docs/assets/readme/presentation-live.png)
58
+
59
+ </details>
60
+
61
+ ## 你可以让它做什么
62
+
63
+ - **分析和制作表格**:读取或创建 Excel 数据,清洗字段,编写公式,设置格式、数据验证和条件格式,创建表格、图表、透视表、筛选器、迷你图与图片,最后导出为 `.xlsx`、`.csv` 或 `.tsv`。
64
+ - **撰写和排版文档**:创建段落、富文本、列表、任务、表格、图片、图表、页眉页脚、分页与页面布局。
65
+ - **创建和修改演示文稿**:从大纲生成整套幻灯片,重设计指定页面,编辑文字、形状、图片、表格、图表与转场,并检查越界、溢出和文本重叠。
66
+ - **搭建多维表格**:创建表、字段、记录和视图,使用公式字段、筛选、排序、分组及 Sheet 数据引用。
67
+ - **绘制可编辑画布**:创建形状、文本、连接线、图片、原生图表和流程图,并检查连接关系与布局。
68
+ - **组合多种内容**:一个 `.univer` 文件可以同时包含 Sheet、Doc、Slide、多维表格(Base)和 Board;公式或嵌入内容可以引用同一文件中的其他 Unit。
69
+ - **处理 Office 文件**:导入 `.xlsx`、`.csv`、`.tsv`、`.docx`、`.pptx`,修改后按对应格式导出。
70
+ - **安全审阅 Agent 修改**:所有写入先进入独立 worktree。你可以实时预览差异,在会话末尾选择合并或丢弃,不会让 Agent 直接覆盖当前版本。
71
+
72
+ ### 试试这些任务
73
+
74
+ ```text
75
+ 分析 sales.xlsx,修复日期和金额字段,新增月度趋势、地区对比图和汇总页,交付 xlsx。
76
+
77
+ 根据 brief.md 创建一份 8 页中文路演 PPT,使用深蓝色视觉体系,每页完成布局检查,最后导出 pptx。
78
+
79
+ 把 meeting-notes.md 整理成正式项目周报,包含执行摘要、风险表、下周计划和页眉页脚,交付 docx。
80
+
81
+ 创建一个客户跟进多维表格,包含公司、联系人、阶段、预计金额和下次行动,并提供按阶段分组的视图。
82
+
83
+ 在同一个 .univer 文件里创建销售数据 Sheet 和汇报 Slide,让 Slide 图表引用 Sheet 数据。
58
84
  ```
59
85
 
60
- ### 从 npm 安装
86
+ ## 能力一览
87
+
88
+ | 内容类型 | 创建与编辑 | 校验与审阅 | 导入 | 导出 |
89
+ | --- | --- | --- | --- | --- |
90
+ | Sheet | 单元格、公式、样式、表格、图表、透视表、筛选、验证、图片等 | 结构化范围检查、公式重算、实时预览 | `.xlsx` `.csv` `.tsv` | `.xlsx` `.csv` `.tsv` |
91
+ | Doc | 段落、富文本、列表、任务、表格、图片、图表、页眉页脚、分页 | 文档结构回读、实时预览 | `.docx` | `.docx` |
92
+ | Slide | 页面、文字、形状、图片、表格、图表、SVG 布局、转场 | 结构检查、文字越界/溢出/重叠检查、实时预览 | `.pptx` | `.pptx` |
93
+ | 多维表格(Base) | 表、字段、记录、视图、公式字段、筛选、排序、分组 | Facade 数据回读、实时预览 | — | `.xlsx` `.csv` `.tsv` |
94
+ | Board | 形状、文字、连接线、图片、原生图表、自动布线 | 元素与连接关系分析、实时预览 | — | — |
95
+
96
+ 所有类型都支持在隔离 worktree 中编辑、提交审阅、重新打开、合并或丢弃。多维表格和 Board 当前通过 Facade 回读完成结构校验;Board 暂不支持文件导出。
97
+
98
+ ## 3 分钟上手
99
+
100
+ ### 1. 安装插件
101
+
102
+ 从 npm 安装:
61
103
 
62
104
  ```sh
63
105
  dsh plugin --profile web add dsh-univer-office
64
106
  ```
65
107
 
66
- ### 从本地 checkout 安装(开发用)
108
+ 或者直接从 GitHub 安装最新版本:
67
109
 
68
110
  ```sh
69
- dsh plugin --profile web add /path/to/dsh-univer-office
111
+ dsh plugin --profile web add github:dream-num/dsh-univer-office
70
112
  ```
71
113
 
72
- > profile 首次使用会自动初始化;`dsh` 会把该 bundle 追加到 `dsh.profile.bundles`,pnpm 链接包后,loader 自动应用插件的 `cordis.patch.yml` 层。可用 `dsh --profile web --dump-config` 验证(应能看到 `# == dsh-univer-office` 层)。
114
+ 安装完成后,在 DeepSeek Harness 窗口按 **Cmd+R / Ctrl+R** 刷新。
73
115
 
74
- 任何方式安装后:在 DeepSeek Harness 窗口按 **Cmd+R / Ctrl+R** 刷新。
116
+ ### 2. 直接描述结果
75
117
 
76
- ## 使用
118
+ ```text
119
+ 创建 reports/q2-review.univer。读取 data/q2-sales.xlsx,生成一个带汇总指标、月度趋势和地区排名的管理看板。
120
+ ```
77
121
 
78
- 1. 创建空 `.univer` 文件,再创建隔离 worktree
79
- 2. 在 draft worktree 中创建指定类型的 Unit,或导入 Office 文件
80
- 3. 模型会主动加载核心 Skill 与对应 Unit Skill;Embed 和跨 Unit 公式还会加载各自 Topic Skill;需要准确 Facade 或方法时用 `univer_api` 查询
81
- 4. 用 `univer_execute` 修改,用 `univer_inspect` 检查内容,并对 Slide 运行 `univer_lint` 检查文字布局
82
- 5. 需要用 SVG 替换或叠加指定 Slide 页面时使用 `univer_compile_svg`;只在用户要求时导出
83
- 6. 用 `ready` 提交确认;同一任务需要继续修改时用 `reopen`
84
- 7. 只有用户明确要求且 DSH 审批通过后才 merge 或 discard;应用内审阅面板也提供相同决策
85
- 8. 预览卡片、实时 worktree 浮窗和会话结束审阅面板会随结构化工具结果更新
122
+ Agent 会自动选择对应 Skills 和 `univer_*` 工具。通常会依次创建文件与 worktree、导入或创建 Unit、修改内容、回读校验,然后把 worktree 标记为待确认。
86
123
 
87
- ## 卸载
124
+ ### 3. 在会话中审阅
88
125
 
89
- ```sh
90
- dsh plugin --profile web remove dsh-univer-office
126
+ - 新建 `.univer` 文件、创建或重开 worktree、写入内容以及提交确认时,右上角实时浮窗会同步显示结果;上一轮保持打开的非终态 worktree 会在下一轮继续显示。
127
+ - 每个被操作且在回合结束时仍存在的 `.univer` 文件都使用统一的回合卡片,可折叠或在应用内全屏打开;历史回合保留同款卡片并默认折叠。过程中创建后又删除的临时文件不显示卡片。
128
+ - 提交、合并和丢弃使用卡片内完整 Univer 页面提供的操作,不在卡片外重复显示按钮。
129
+
130
+ ## 工作方式
131
+
132
+ 一个 `.univer` 文件是可组合的办公容器,其中可以放置多个不同类型的 Unit。插件把 Agent 的每次任务放入独立 worktree:
133
+
134
+ ```text
135
+ 你的要求
136
+ ↓
137
+ 按需加载 Univer Skill
138
+ ↓
139
+ 在 draft worktree 中创建 / 导入 / 编辑
140
+ ↓
141
+ 结构回读 + 公式重算 + Slide 布局检查
142
+ ↓
143
+ 实时预览与会话内审阅
144
+ ↓
145
+ 继续修改 / 合并 / 丢弃
91
146
  ```
92
147
 
93
- ## 结构
148
+ 只有 `merge` 和 `discard` 会结束 worktree,且两者都需要用户明确授权和 DSH 审批。`ready` 只是提交审阅,不会修改主线。
94
149
 
95
- 本项目是一个可安装的 DSH bundle,内部由多个 Cordis 角色组成:
150
+ ## 内置工具
96
151
 
97
- - Host 根插件组合 Univer Service Provider、webServer Consumer、Tools Consumer 和 bundled lazy Skill Provider;
98
- - Consumer 只调用 `ctx.univer`,不会直接访问 Gateway、CLI、子进程或文件系统;
99
- - `host/webServer` 提供 `GET /univer-api/status`、`POST /univer-api/gateway/start`、`GET /univer-api/state` 和 `POST /univer-api/worktree-action`;
100
- - Tools Consumer 注册领域工具,不提供通用 CLI 透传;
101
- - `host/processes/gateway` 管理内置 Gateway 进程和 Viewer 资源;`host/adapters/unit-content` 为 import、inspect、execute、export 和 render-source 读取启动来自 `workers/unit-content` 的一次性 Unit Content Worker;machine render page 提供 Slide 布局事实和 SVG 文字测量,但不暴露截图;
102
- - Client 从持久化工具事件恢复结构化目标,通过统一 API 层轮询状态,再由预览、实时浮窗和审阅组件渲染。
152
+ 日常使用不需要手动调用工具;DSH 会根据任务自动选择。下面的列表可以帮助你理解插件的覆盖范围。
103
153
 
104
- `src/` 包含 Host、Client、Gateway、Unit Content Worker 和 Viewer 源码。Viewer application 及其本地渲染支撑源码从 `univer-cli` 复制而来,本仓库会构建自己发布的所有 application。目录、依赖方向和信任边界见[架构决策](docs/architecture.md)。
154
+ | 工具 | 作用 |
155
+ | --- | --- |
156
+ | `univer_new` | 创建空 `.univer` 文件,不覆盖已有文件 |
157
+ | `univer_status` | 查看主线与 worktree 中的 Unit 和状态 |
158
+ | `univer_worktree` | 创建、提交、重开、合并或丢弃隔离 worktree |
159
+ | `univer_unit` | 创建或删除 Sheet、Doc、Slide、多维表格(Base)、Board Unit |
160
+ | `univer_import` | 把 Office 文件导入为新 Unit |
161
+ | `univer_inspect` | 读取文档结构或指定 Sheet 范围 |
162
+ | `univer_execute` | 执行精确 Univer Facade API 读取或修改 |
163
+ | `univer_export` | 导出 Sheet、Doc、Slide 或多维表格 |
164
+ | `univer_lint` | 检查 Slide 文字越界、溢出和重叠 |
165
+ | `univer_compile_svg` | 用真实字体度量把 SVG 编译到指定 Slide 页面 |
166
+ | `univer_api` | 按意图检索插件实际包含的 Univer Facade API |
105
167
 
106
- ## 开发
168
+ 插件还包含 8 个版本匹配、按需加载的 Skills:核心编排、Sheet、Doc、Slide、多维表格(Base)、Board、Embed 和跨 Unit 公式。
169
+
170
+ ## 预览与审阅体验
107
171
 
108
- `lib/`、`artifacts/`、`dist/` 及归档产物(`univer-dsh-plugin.zip`、`*.tgz`)均为**生成物**,不入库。`pnpm run build` 从 `src/` 构建 Host、Client、Gateway、Unit Content Worker、machine render page 和 Viewer。
172
+ - **实时 Univer 窗口**:新建文件或创建、重开、写入和提交 worktree 时主动显示,可拖动、缩放、折叠和全屏;保持打开的非终态 worktree 会跨回合延续。
173
+ - **统一回合卡片**:每个被操作且当前仍存在的 `.univer` 文件都有独立的完整 Univer 卡片;纯读取不会覆盖同一回合已经发生的 worktree 生命周期结果,已删除的临时文件不会留下加载卡片。
174
+ - **历史审阅**:`draft`、`ready`、合并和丢弃结果都使用同款卡片保留在原回合,历史卡片默认折叠。
175
+ - **多会话隔离**:每个 DSH 会话只展示属于自己的窗口、卡片和审阅状态。
176
+ - **中英文界面**:插件外壳和已打开的 Viewer 跟随 DSH 的界面语言。
177
+
178
+ ## 要求与限制
179
+
180
+ - DeepSeek Harness,以及 Node.js `>=22.19.0`。
181
+ - Slide 布局检查和 SVG 真实文字度量需要本机 Chrome/Chromium;也可以通过 `UNIVER_RENDER_BROWSER` 指定浏览器路径。
182
+ - 插件目前不向模型提供截图,因此结构和布局检查不能替代逐像素视觉验收。你仍然可以在实时 Viewer 中人工检查结果。
183
+ - Slide 的母版、版式页和演讲者备注不在当前编辑范围内。
184
+ - Board 的思维导图、表格、墨迹和高级编辑,以及 Board 文件导出尚未开放。
185
+
186
+ ## 配置
187
+
188
+ 默认配置适合本地使用:Gateway 会在首次读取文件状态时自动启动,并依次尝试端口 `9123` 和 `8000`。如需定制,可在 bundle 的 Cordis 配置层设置:
189
+
190
+ | 字段 | 默认值 | 说明 |
191
+ | --- | --- | --- |
192
+ | `gatewayPorts` | `[9123, 8000]` | 内置 Gateway 尝试使用的本地端口 |
193
+ | `autoStartGateway` | `true` | 首次访问时自动启动 Gateway |
194
+ | `gatewayStartupTimeoutMs` | `10000` | Gateway 启动超时 |
195
+ | `gatewayRequestTimeoutMs` | `3000` | 状态读取超时 |
196
+ | `gatewayMutationTimeoutMs` | `60000` | Gateway 写操作超时 |
197
+ | `unitContentOperationTimeoutMs` | `120000` | 导入、导出、检查和执行超时 |
198
+ | `tools` | `true` | 注册 `univer_*` 工具 |
199
+ | `skills` | `true` | 注册内置 Univer Skills |
200
+
201
+ 其余缓存与提交确认选项见 [`src/host/config.ts`](src/host/config.ts)。
202
+
203
+ ## 卸载
109
204
 
110
205
  ```sh
111
- pnpm run build
112
- pnpm run test
206
+ dsh plugin --profile web remove dsh-univer-office
113
207
  ```
114
208
 
115
- 然后重建发布产物:
209
+ ## 开发
210
+
211
+ 本项目是一个标准 [DSH bundle](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.md)。Host 组合 Univer Service Provider、Tools Consumer、webServer Consumer 和 Skill Provider;插件自带 Gateway、Viewer、无头 Unit Content Worker 与 Slide render machine。依赖方向和运行时边界见[架构文档](docs/architecture.md)。
116
212
 
117
213
  ```sh
118
- bash scripts/build-dist.sh
214
+ pnpm install
215
+ pnpm run build
216
+ pnpm run test
119
217
  ```
120
218
 
121
- 该脚本会重新生成 `dist/univer/`(发布包内容)、npm tarball `dist/univer-office-<version>.tgz` 与 zip 分发包 `univer-dsh-plugin.zip`(包内容)。
122
-
123
- 单独运行冒烟测试:
219
+ 构建 npm tarball 和 zip 发布包:
124
220
 
125
221
  ```sh
126
- node test/host-smoke.mjs
127
- node test/client-smoke.mjs
128
- node test/skills-smoke.mjs
129
- npm run test:integration
222
+ bash scripts/build-dist.sh
130
223
  ```
131
224
 
132
- 发布:`npm publish`(遵循 `files` 白名单);zip/tgz 挂到 GitHub Release 供终端用户下载。
225
+ `lib/`、`artifacts/`、`dist/`、`*.tgz` 和 `univer-dsh-plugin.zip` 都是生成物,不提交到仓库。
133
226
 
134
- ## 预留的 npm 包名
227
+ ## 官方包名
135
228
 
136
- 以下无 scope 的裸名已由本项目预留,用于防 typosquatting(恶意仿冒)——`redirects/<name>/` 各目录存放占位包(deprecated,指向官方包名),不含任何代码:
229
+ 请只安装 `dsh-univer-office`。以下相似名称是本项目为防止仿冒而保留的 deprecated npm 占位包,不包含插件代码:
137
230
 
138
- - [`dsh-univer-plugin`](https://www.npmjs.com/package/dsh-univer-plugin)
231
+ - `dsh-univer-plugin`
139
232
  - `dsh-univer-office-suite`
140
233
  - `dsh-univer-suite`
141
234
  - `univer-office-suite`
142
235
  - `univer-office`
143
236
 
144
- **请始终安装官方包:**
145
-
146
- ```sh
147
- dsh plugin --profile web add github:dream-num/dsh-univer-office # 从 git
148
- dsh plugin --profile web add dsh-univer-office # 从 npm
149
- ```
150
-
151
- ## 元数据
152
-
153
- - **Topic**:[`dsh-plugin`](https://github.com/topics/dsh-plugin)
154
- - **Bundle manifest**:`dsh.bundle.patch` → `./cordis.patch.yml`
155
- - **Client manifest**:`dsh.client`(`platform: "web"` + `inject`)
156
-
157
237
  ## 许可
158
238
 
159
239
  [Apache-2.0](LICENSE)
@@ -25,14 +25,14 @@
25
25
 
26
26
  ## 2. 必须保留的产品功能
27
27
 
28
- - 在 DSH 会话中发现 `.univer` 文件,并为每个文件显示独立的回合尾部预览卡片;
28
+ - 在 DSH 会话中发现 `.univer` 文件,并为每个文件显示采用统一审阅布局的回合尾部卡片;
29
29
  - 在 DSH 内以 Viewer 全屏预览文件;
30
30
  - worktree 创建或更新后显示实时浮动窗口;
31
31
  - 一个 worktree 改动多个 unit 时,只列出有改动的 unit 并允许切换;
32
32
  - 会话结束后在最近一次操作各 worktree 的回合末尾为 `draft` 或 `ready` worktree 显示嵌入式审阅面板;
33
- - 后续回合再次操作同一 worktree 时,旧回合保留同款审阅 header 作为历史标记,不回退到文件预览卡片;
33
+ - 后续回合再次操作同一 worktree 时,旧回合保留同一张完整卡片并默认折叠,不回退到旧文件预览卡片或单独历史 header;
34
34
  - 审阅卡片使用紧凑 header:首行显示 Univer 文件名和右侧的 worktree 名称,次行只显示完整文件路径,状态、折叠和全屏控制位于右侧;桌面端不同生命周期的展开卡片默认总高度约 650px,内嵌完整页面默认折叠左侧边栏,卡片折叠保留已加载页面;全屏时隐藏折叠按钮,Esc 退出全屏;
35
- - draft 审阅卡片可执行提交确认和丢弃;ready 状态的丢弃与合入当前版本只使用完整 Univer 页面内置操作;
35
+ - draft、ready 状态的提交确认、丢弃与合入当前版本只使用完整 Univer 页面内置操作,卡片外壳不重复提供 action footer;
36
36
  - worktree 进入 `merged` 或 `discarded` 终态后不再显示浮窗或修改操作,但保留审阅卡片并在完整页面中显示主线;
37
37
  - 插件按需启动并管理内置 Gateway 和 Viewer;
38
38
  - 多个 DSH 会话的预览目标与审阅状态相互隔离;
@@ -158,13 +158,11 @@ src/
158
158
  api/
159
159
  univer-api.ts # 唯一 HTTP 访问层
160
160
  conversation/
161
- univer-target-definition.ts # 从会话事件恢复预览目标
161
+ univer-turn-definition.ts # 归约可回放的 Turn 操作与生命周期结果
162
162
  hooks/
163
163
  use-univer-state.ts
164
- use-worktree-action.ts
165
164
  components/
166
165
  preview-card.tsx
167
- preview-dialog.tsx
168
166
  worktree-window.tsx
169
167
  review-panel.tsx
170
168
  unit-chips.tsx
@@ -173,7 +171,6 @@ src/
173
171
  en.ts
174
172
  zh.ts
175
173
  styles/
176
- preview.ts
177
174
  worktree.ts
178
175
  shared/
179
176
  wire/
@@ -307,7 +304,9 @@ Client 只解析结构化 `univer_*` 工具事件,不从 bash 命令或自由
307
304
 
308
305
  Client 是状态投影,不拥有 worktree 真相。预览目标来自可回放的会话事件;实时状态来自 Host API;Viewer iframe 负责文档内容的实时展示。
309
306
 
310
- 回合尾部 PreviewCard 打开完整的 standalone Viewer 页面,与 `univer-cli open` 的页面模式一致;实时 worktree 浮窗和会话结束审阅面板继续使用 `mode=embedded`,分别绑定 `worktree` 与 `mergePreview` scope。
307
+ Client 通过 `univerTurnDefinition` 按 `callId` 配对结构化工具调用与结果,并分别归约生命周期、内容写入和读取操作;读取操作不能覆盖同一 Turn 已完成的 ready、reopen、merge 或 discard 转换。统一回合卡片把该投影与 Host `FileState` 组合,按权威状态打开 trunk、worktree 或 merge preview 完整页面;若 Host 明确确认投影中的文件已不存在,则不渲染该卡片,以覆盖 Agent 在同一 Turn 中创建并通过其他工具删除临时文件的场景。
308
+
309
+ 实时浮窗只由 `univer_new`、worktree create/reopen/ready 和内容写入主动拉起,纯 status、inspect、lint 与 export 不主动打开窗口。用户保持打开的文件或非终态 worktree 会在下一 Turn 继续显示;用户关闭优先,merged 与 discarded 清除打开意图。
311
310
 
312
311
  Client 必须满足:
313
312
 
@@ -317,6 +316,8 @@ Client 必须满足:
317
316
  - mutation 期间禁用重复操作,完成后重新获取 Host 状态;
318
317
  - Viewer URL 的文件、worktree、unit、mode 与 scope 参数视为不透明值;Client 只能设置不改变资源身份和授权范围的展示参数;
319
318
  - 终态 worktree 在原回合末尾保留审阅卡片,移除修改操作并显示主线完整页面;
319
+ - 所有 Turn 使用同一种卡片布局;状态加载失败只显示该布局的不可用状态,不回退旧卡片;
320
+ - 卡片不复制 Viewer 已提供的 ready、merge 或 discard 操作;
320
321
  - UI 文案来自 locale 模块。
321
322
 
322
323
  ## 11. CLI 移除决策