dsh-univer-office 0.2.0-alpha → 0.2.0

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 (77) hide show
  1. package/README.md +21 -44
  2. package/README.zh-CN.md +21 -44
  3. package/docs/architecture.md +77 -46
  4. package/lib/client.js +211 -80
  5. package/lib/index.js +943 -165
  6. package/lib/index.js.map +4 -4
  7. package/lib/types/client/components/review-panel.d.ts.map +1 -1
  8. package/lib/types/client/components/univer-dock.d.ts.map +1 -1
  9. package/lib/types/client/components/worktree-window.d.ts +6 -3
  10. package/lib/types/client/components/worktree-window.d.ts.map +1 -1
  11. package/lib/types/client/styles/worktree.d.ts +1 -1
  12. package/lib/types/client/styles/worktree.d.ts.map +1 -1
  13. package/lib/types/host/adapters/gateway/mapping.d.ts +6 -0
  14. package/lib/types/host/adapters/gateway/mapping.d.ts.map +1 -1
  15. package/lib/types/host/adapters/gateway/worktree-api.d.ts +6 -2
  16. package/lib/types/host/adapters/gateway/worktree-api.d.ts.map +1 -1
  17. package/lib/types/host/adapters/unit-content/protocol.d.ts +6 -2
  18. package/lib/types/host/adapters/unit-content/protocol.d.ts.map +1 -1
  19. package/lib/types/host/artifacts/paths.d.ts +1 -1
  20. package/lib/types/host/artifacts/paths.d.ts.map +1 -1
  21. package/lib/types/host/config.d.ts +3 -0
  22. package/lib/types/host/config.d.ts.map +1 -1
  23. package/lib/types/host/index.d.ts.map +1 -1
  24. package/lib/types/host/processes/gateway/supervisor.d.ts +1 -1
  25. package/lib/types/host/processes/gateway/supervisor.d.ts.map +1 -1
  26. package/lib/types/host/provider/gateway-univer-service.d.ts +21 -8
  27. package/lib/types/host/provider/gateway-univer-service.d.ts.map +1 -1
  28. package/lib/types/host/provider/unit-content-operations.d.ts +6 -1
  29. package/lib/types/host/provider/unit-content-operations.d.ts.map +1 -1
  30. package/lib/types/host/service/identifiers.d.ts +4 -0
  31. package/lib/types/host/service/identifiers.d.ts.map +1 -1
  32. package/lib/types/host/service/types.d.ts +76 -27
  33. package/lib/types/host/service/types.d.ts.map +1 -1
  34. package/lib/types/host/service/univer-service.d.ts +6 -2
  35. package/lib/types/host/service/univer-service.d.ts.map +1 -1
  36. package/lib/types/host/service/workspace.d.ts +21 -0
  37. package/lib/types/host/service/workspace.d.ts.map +1 -0
  38. package/lib/types/host/skills/plugin.d.ts +6 -0
  39. package/lib/types/host/skills/plugin.d.ts.map +1 -0
  40. package/lib/types/host/tools/definitions/api.d.ts +4 -0
  41. package/lib/types/host/tools/definitions/api.d.ts.map +1 -0
  42. package/lib/types/host/tools/definitions/execute.d.ts.map +1 -1
  43. package/lib/types/host/tools/definitions/export.d.ts.map +1 -1
  44. package/lib/types/host/tools/definitions/import.d.ts +4 -0
  45. package/lib/types/host/tools/definitions/import.d.ts.map +1 -0
  46. package/lib/types/host/tools/definitions/inspect.d.ts.map +1 -1
  47. package/lib/types/host/tools/definitions/new.d.ts +4 -0
  48. package/lib/types/host/tools/definitions/new.d.ts.map +1 -0
  49. package/lib/types/host/tools/definitions/status.d.ts +4 -0
  50. package/lib/types/host/tools/definitions/status.d.ts.map +1 -0
  51. package/lib/types/host/tools/definitions/unit.d.ts +4 -0
  52. package/lib/types/host/tools/definitions/unit.d.ts.map +1 -0
  53. package/lib/types/host/tools/definitions/worktree.d.ts.map +1 -1
  54. package/lib/types/host/tools/plugin.d.ts.map +1 -1
  55. package/lib/types/host/tools/presentation.d.ts +29 -2
  56. package/lib/types/host/tools/presentation.d.ts.map +1 -1
  57. package/lib/types/host/tools/workspace.d.ts +16 -0
  58. package/lib/types/host/tools/workspace.d.ts.map +1 -0
  59. package/lib/types/host/webServer/routes/state.d.ts.map +1 -1
  60. package/lib/types/host/webServer/routes/worktree-action.d.ts.map +1 -1
  61. package/lib/types/host/webServer/session-scope.d.ts +3 -1
  62. package/lib/types/host/webServer/session-scope.d.ts.map +1 -1
  63. package/lib/types/shared/wire/actions.d.ts +1 -1
  64. package/lib/types/shared/wire/actions.d.ts.map +1 -1
  65. package/package.json +7 -8
  66. package/scripts/copy-gateway-dependencies.mjs +36 -1
  67. package/skills/univer/SKILL.md +40 -0
  68. package/skills/univer-base/SKILL.md +14 -0
  69. package/skills/univer-board/SKILL.md +14 -0
  70. package/skills/univer-doc/SKILL.md +16 -0
  71. package/skills/univer-sheet/SKILL.md +36 -0
  72. package/skills/univer-slide/SKILL.md +16 -0
  73. package/vendor/collaboration/artifacts/gateway.cjs +104 -18
  74. package/vendor/unit-content/artifacts/unit-content-worker.mjs +19 -1
  75. package/lib/types/host/tools/definitions/create.d.ts +0 -4
  76. package/lib/types/host/tools/definitions/create.d.ts.map +0 -1
  77. package/scripts/install.js +0 -125
package/README.md CHANGED
@@ -16,8 +16,8 @@ Create and preview Univer office files (sheets, docs, slides, bases) directly in
16
16
  │ ● agent-draft · sales.univer │ ← floating live window (draft worktree)
17
17
  │ [in progress] [−] [⤢] [✕] │
18
18
  │ ┌──────────────────────────┐ │
19
- │ │ live worktree Viewer │ │ click the bar to enlarge,
20
- │ │ (read-only, real-time) │ │ drag / fold / dismiss anytime
19
+ │ │ live worktree Viewer │ │ double-click to maximize,
20
+ │ │ (read-only, real-time) │ │ drag / resize / fold anytime
21
21
  │ └──────────────────────────┘ │
22
22
  └──────────────────────────────┘
23
23
 
@@ -34,17 +34,17 @@ Create and preview Univer office files (sheets, docs, slides, bases) directly in
34
34
  - **Inline preview cards** — a card appears at the end of turns that use the structured `univer_*` tools.
35
35
  - **In-app fullscreen viewer** — click the card to open the sheet in an in-app iframe; close with ✕ / mask / Esc.
36
36
  - **Live floating worktree window** — when the agent creates or updates a worktree, a small window pops up in the **top-right corner** embedding the live read-only worktree page. Edits appear in real time. When one worktree touches several units (e.g. a sheet plus a deck), the window and the review panel show **unit chips** that list ONLY changed units (+ added / ✎ modified / - deleted / ⚠ conflict) with status icons, defaulting to the first one.
37
- - **Window interactions** — drag the dark bar to move; click the bar (without dragging) to enlarge; `−` folds down to the bare title bar, `⤢` maximizes, **drag the bottom-right corner to resize**, `✕` dismisses until the worktree status changes.
38
- - **Ready + session end → close, then merge panel** — once the session goes idle, every **non-terminal** worktree moves into the review dock below the conversation: `ready` shows the merge preview (`scope=mergePreview`) plus Resume editing / Discard / Merge into current version actions; **`draft` shows up too**, with the live worktree page plus Submit for confirmation / Discard actions (so a modification the agent forgot to submit is still reviewable). While the session is still running, non-terminal worktrees stay as top-right windows. **Merged or discarded worktrees (terminal states) show nothing — no window, no panel.**
37
+ - **Window interactions** — drag the title bar to move and double-click it to maximize; use the dedicated fold, maximize/restore, and close controls; drag any edge or corner to resize. Folding keeps the loaded Viewer mounted for instant restoration. Movement, resizing, and viewport changes keep the full window reachable on screen.
38
+ - **Ready + session end → close, then merge panel** — once the session goes idle, every **non-terminal** worktree moves into the review dock below the conversation: `ready` shows the merge preview (`scope=mergePreview`) plus Discard / Merge into current version actions; **`draft` shows up too**, with the live worktree page plus Submit for confirmation / Discard actions (so a modification the agent forgot to submit is still reviewable). While the session is still running, non-terminal worktrees stay as top-right windows. **Merged or discarded worktrees (terminal states) show nothing — no window, no panel.**
39
39
  - **Bundled Gateway management** — the plugin ships the collaboration Gateway and Viewer; green dot = running, yellow dot = stopped, click to start the plugin-owned Gateway.
40
40
  - **Multi-session** — each session shows its own turn's cards, windows, and merge panels.
41
41
  - **Bilingual UI** — the card follows the app locale (zh / en).
42
42
 
43
43
  ## Requirements
44
44
 
45
- - DeepSeek Harness on Apple Silicon macOS for the current checked-in native artifacts
46
- - No global Univer CLI installation is required. The plugin bundles its Gateway, Viewer, headless Unit Content Worker, Office converter, Univer license, and platform-native dependencies. It registers `univer_create`, `univer_inspect`, `univer_execute`, `univer_export`, and `univer_worktree`.
47
- - The sync scripts support producing Linux x64/arm64 and Windows x64 native artifacts on those target platforms; platform-specific release publishing is still pending.
45
+ - DeepSeek Harness and Node.js 22.19 or newer; platform-native dependencies are installed from the registry for the current machine
46
+ - No global Univer CLI installation is required. The plugin bundles its Gateway, Viewer, headless Unit Content Worker, Office converter, Univer license, platform-native dependencies, and lazy Univer skills. It registers `univer_new`, `univer_status`, `univer_worktree`, `univer_unit`, `univer_import`, `univer_inspect`, `univer_execute`, `univer_export`, and `univer_api`.
47
+ - Model screenshot capture is intentionally not included yet. The bundled skill reports when appearance remains unverified instead of claiming visual confirmation.
48
48
 
49
49
  ## Install
50
50
 
@@ -73,52 +73,40 @@ dsh plugin --profile web add /path/to/dsh-univer-office
73
73
  > plugin's `cordis.patch.yml` layer automatically. Verify with
74
74
  > `dsh --profile web --dump-config` (you should see a `# == dsh-univer-office` layer).
75
75
 
76
- ### Alternative: one-command installer (no dsh CLI)
77
-
78
- If you cannot run the `dsh` CLI, a convenience installer is provided:
79
-
80
- ```sh
81
- pnpm install
82
- bash install.sh
83
- ```
84
-
85
- The source-checkout installer copies the already-installed Gateway dependencies. For the macOS zip distribution they are already included; double-click `install.command` (see `packaging/INSTALL.txt`).
86
-
87
76
  After any install: **refresh DeepSeek Harness (Cmd+R / Ctrl+R)**.
88
77
 
89
78
  ## Usage
90
79
 
91
- 1. Let the agent use the `univer_*` domain tools
92
- 2. When the turn ends, a preview card appears at its tail
93
- 3. Click the card → in-app fullscreen preview
94
- 4. Create a worktree → the floating live window appears in the corner; watch the agent's edits in real time
95
- 5. Submit the modification for confirmation in the review panel → when the session ends, the live window closes and the merge preview embeds below the conversation
96
- 6. If the bundled Gateway is not running, the card shows a yellow dot; click it to start the Gateway
80
+ 1. Create an empty `.univer` file, then create an isolated worktree
81
+ 2. Create a typed Unit or import an Office file into that draft worktree
82
+ 3. Use the matching lazy Unit skill and `univer_api` when an exact Facade or method is needed
83
+ 4. Modify with `univer_execute`, verify content with `univer_inspect`, and export only when requested
84
+ 5. Submit with `ready`; use `reopen` when the same task needs another edit
85
+ 6. Merge or discard only on an explicit request and after DSH approval; the in-app review panel provides the same decisions
86
+ 7. Preview cards, the live worktree window, and the session-end review panel reflect the structured tool results
97
87
 
98
88
  ## Uninstall
99
89
 
100
90
  ```sh
101
- univer-dsh uninstall
91
+ dsh plugin --profile web remove dsh-univer-office
102
92
  ```
103
93
 
104
- Or remove the plugin manually: delete `~/.dsh/profiles/node_modules/dsh-univer-office` and the matching `cordis.patch.yml` entry.
105
-
106
94
  ## Architecture
107
95
 
108
96
  The package is one installable DSH bundle with several internal Cordis roles:
109
97
 
110
- - the root Host plugin composes the Univer Service Provider, webServer Consumer, and Tools Consumer;
98
+ - the root Host plugin composes the Univer Service Provider, webServer Consumer, Tools Consumer, and bundled lazy Skill Provider;
111
99
  - `ctx.univer` is the only Host domain API used by the consumers;
112
100
  - `host/webServer` exposes `GET /univer-api/status`, `POST /univer-api/gateway/start`, `GET /univer-api/state`, and `POST /univer-api/worktree-action`;
113
101
  - the Tools Consumer exposes domain tools instead of a generic CLI passthrough;
114
- - `host/processes/gateway` owns the bundled Gateway process and Viewer assets; `host/adapters/unit-content` starts an isolated one-shot Unit Content Worker from `workers/unit-content` for inspect, execute, and export;
102
+ - `host/processes/gateway` owns the bundled Gateway process and Viewer assets; `host/adapters/unit-content` starts an isolated one-shot Unit Content Worker from `workers/unit-content` for import, inspect, execute, and export;
115
103
  - the Client recovers structured targets from durable tool events, polls state through its API layer, and renders preview, live-window, and review components.
116
104
 
117
- `src/` is the hand-written plugin source; `lib/index.js`, `lib/client.js`, and `lib/types/` are generated. Vendored upstream source and generated artifacts live under `vendor/collaboration` and `vendor/unit-content`. See [the architecture decision](docs/architecture.md) for directories, dependencies, and trust boundaries.
105
+ `src/` contains the hand-written Host, Client, Gateway application, and Unit Content Worker sources. `lib/`, the Gateway executable, and the Worker executable are generated and gitignored; only the prebuilt Viewer remains a checked-in runtime asset. See [the architecture decision](docs/architecture.md) for directories, dependencies, and trust boundaries.
118
106
 
119
107
  ## Development
120
108
 
121
- `dist/` and the archives (`univer-dsh-plugin.zip`, `*.tgz`) are **generated** — they are gitignored and never committed. `vendor/collaboration/artifacts/` and `vendor/unit-content/artifacts/` are intentionally versioned and shipped. Build and test the source first:
109
+ `lib/`, the Gateway and Worker executables, `dist/`, and the archives (`univer-dsh-plugin.zip`, `*.tgz`) are **generated** and never committed. `pnpm run build` compiles all three applications from `src/`; the Viewer bundle under `vendor/collaboration/artifacts/viewer` is the only checked-in runtime artifact.
122
110
 
123
111
  ```sh
124
112
  pnpm run build
@@ -131,25 +119,14 @@ Then build the release artifacts:
131
119
  bash scripts/build-dist.sh
132
120
  ```
133
121
 
134
- Refresh the Gateway, Viewer, and collaboration source snapshot from a Univer CLI checkout with:
135
-
136
- ```sh
137
- npm run sync:collaboration -- /path/to/univer-cli
138
- ```
139
-
140
- Refresh the Unit Content Worker, embedded Univer development credential, and current-platform native dependencies with:
141
-
142
- ```sh
143
- UNIVER_CLI_SOURCE=/path/to/univer-cli npm run sync:unit-content
144
- ```
145
-
146
- This regenerates `dist/univer/` (the shipped package contents), the npm tarball `dist/univer-office-<version>.tgz`, and the zip distribution `univer-dsh-plugin.zip` (package contents + `install.command` + `INSTALL*.txt` from `packaging/`).
122
+ This regenerates `dist/univer/` (the shipped package contents), the npm tarball `dist/univer-office-<version>.tgz`, and the zip distribution `univer-dsh-plugin.zip` (package contents).
147
123
 
148
124
  Individual smoke tests:
149
125
 
150
126
  ```sh
151
127
  node test/host-smoke.mjs
152
128
  node test/client-smoke.mjs
129
+ node test/skills-smoke.mjs
153
130
  npm run test:integration
154
131
  ```
155
132
 
package/README.zh-CN.md CHANGED
@@ -16,8 +16,8 @@
16
16
  │ ● agent-draft · 销售表格 │ ← 实时浮窗(draft worktree)
17
17
  │ [修改中] [−] [⤢] [✕] │
18
18
  │ ┌──────────────────────────┐ │
19
- │ │ 实时 worktree Viewer │ │ 点击标题栏放大,
20
- │ │ (只读 · 实时同步) │ │ 可拖拽 / 折叠 / 关闭
19
+ │ │ 实时 worktree Viewer │ │ 双击标题栏最大化,
20
+ │ │ (只读 · 实时同步) │ │ 可拖拽 / 缩放 / 折叠
21
21
  │ └──────────────────────────┘ │
22
22
  └──────────────────────────────┘
23
23
 
@@ -34,17 +34,17 @@
34
34
  - **回合尾部预览卡片** —— 使用结构化 `univer_*` 工具的回合结束后自动出现预览卡片。
35
35
  - **应用内全屏预览** —— 点卡片在应用内 iframe 中打开表格;✕ / 遮罩 / Esc 关闭。
36
36
  - **实时浮窗** —— agent 创建或更新 worktree 后,**右上角**弹出小浮窗,内嵌只读实时 worktree 页面;修改会实时出现在浮窗里。一个 worktree 改动多个 unit(如表格+PPT)时,浮窗与审阅面板顶部的 **unit 切换 chips** 只列出有变动的单元(+新增 / ✎修改 / -删除 / ⚠冲突),未变动的单元不显示;默认打开第一个变动单元。
37
- - **浮窗交互** —— 拖深色标题栏移动;点击标题栏(未拖动)即放大;`−` 折叠成只剩标题条,`⤢` 最大化,**拖右下角调整大小**,`✕` 关闭(worktree 状态变化后自动重新出现)。
38
- - **ready + 会话结束 → 自动关闭并嵌入合并页** —— 会话转入空闲后,所有**非终态** worktree 自动进入会话下方的审阅 dock:`ready` 显示合并预览(`scope=mergePreview`)+ 恢复编辑 / 丢弃 / 合入当前版本按钮;**`draft` 也进入 dock**,显示实时页面 + 提交确认 / 丢弃按钮(agent 忘了提交确认也能直接审阅)。会话仍在运行时,非终态 worktree 在右上角浮窗显示。**merge 或 discard 之后(终态)不再显示任何浮窗或面板。**
37
+ - **浮窗交互** —— 拖标题栏移动,双击标题栏最大化;使用独立的折叠、最大化/还原和关闭按钮;拖任意边缘或角调整大小。折叠时保留已加载的 Viewer,展开可立即恢复。移动、缩放和视口变化都会保持完整窗口可见。
38
+ - **ready + 会话结束 → 自动关闭并嵌入合并页** —— 会话转入空闲后,所有**非终态** worktree 自动进入会话下方的审阅 dock:`ready` 显示合并预览(`scope=mergePreview`)+ 丢弃 / 合入当前版本按钮;**`draft` 也进入 dock**,显示实时页面 + 提交确认 / 丢弃按钮(agent 忘了提交确认也能直接审阅)。会话仍在运行时,非终态 worktree 在右上角浮窗显示。**merge 或 discard 之后(终态)不再显示任何浮窗或面板。**
39
39
  - **内置 Gateway 管理** —— 插件自带协作 Gateway 与 Viewer;绿点 = 运行中,黄点 = 未运行,点击即可启动插件持有的 Gateway。
40
40
  - **多会话并行** —— 各会话显示各自回合的卡片、浮窗与合并面板。
41
41
  - **双语界面** —— 卡片跟随应用语言(中/英)。
42
42
 
43
43
  ## 环境要求
44
44
 
45
- - 当前已提交及预构建原生产物要求 Apple Silicon macOS + DeepSeek Harness
46
- - 不需要全局安装 Univer CLI。插件内置 Gateway、Viewer、无头 Unit Content Worker、Office 转换器、Univer license 与当前平台的原生依赖,并注册 `univer_create`、`univer_inspect`、`univer_execute`、`univer_export` 和 `univer_worktree`。
47
- - 同步脚本可在 Linux x64/arm64 与 Windows x64 目标环境生成对应原生产物;这些平台的分平台发布流程尚未建立。
45
+ - DeepSeek Harness 与 Node.js 22.19 或更高版本;当前平台的原生依赖由包管理器从 registry 安装
46
+ - 不需要全局安装 Univer CLI。插件内置 Gateway、Viewer、无头 Unit Content Worker、Office 转换器、Univer license、当前平台的原生依赖及按需加载的 Univer Skills,并注册 `univer_new`、`univer_status`、`univer_worktree`、`univer_unit`、`univer_import`、`univer_inspect`、`univer_execute`、`univer_export` 和 `univer_api`。
47
+ - 暂不提供模型截图能力。bundled Skill 会在视觉效果尚未验证时明确说明,不会声称已经完成视觉确认。
48
48
 
49
49
  ## 安装
50
50
 
@@ -70,52 +70,40 @@ dsh plugin --profile web add /path/to/dsh-univer-office
70
70
 
71
71
  > profile 首次使用会自动初始化;`dsh` 会把该 bundle 追加到 `dsh.profile.bundles`,pnpm 链接包后,loader 自动应用插件的 `cordis.patch.yml` 层。可用 `dsh --profile web --dump-config` 验证(应能看到 `# == dsh-univer-office` 层)。
72
72
 
73
- ### 备用:一键安装脚本(无 dsh CLI 时)
74
-
75
- 无法运行 `dsh` CLI 时,可使用便利安装脚本:
76
-
77
- ```sh
78
- pnpm install
79
- bash install.sh
80
- ```
81
-
82
- 源码 checkout 安装器会复制已安装的 Gateway 依赖。macOS zip 已包含这些依赖,可直接双击 `install.command`(见 `packaging/INSTALL.txt`)。
83
-
84
73
  任何方式安装后:在 DeepSeek Harness 窗口按 **Cmd+R / Ctrl+R** 刷新。
85
74
 
86
75
  ## 使用
87
76
 
88
- 1. 让 agent 使用 `univer_*` 领域工具
89
- 2. 回合结束后,回合尾部自动出现预览卡片
90
- 3. 点卡片 → 应用内全屏预览
91
- 4. 创建 worktree → 角落弹出实时浮窗,agent 的每次修改实时可见
92
- 5. 在审阅面板提交修改等待确认;会话结束后浮窗自动关闭,合并预览嵌入会话下方
93
- 6. 内置 Gateway 未运行时卡片上显示黄色圆点,点击即可启动 Gateway
77
+ 1. 创建空 `.univer` 文件,再创建隔离 worktree
78
+ 2. 在 draft worktree 中创建指定类型的 Unit,或导入 Office 文件
79
+ 3. 按需加载对应 Unit Skill;需要准确 Facade 或方法时用 `univer_api` 查询
80
+ 4. 用 `univer_execute` 修改,用 `univer_inspect` 检查内容,只在用户要求时导出
81
+ 5. 用 `ready` 提交确认;同一任务需要继续修改时用 `reopen`
82
+ 6. 只有用户明确要求且 DSH 审批通过后才 merge 或 discard;应用内审阅面板也提供相同决策
83
+ 7. 预览卡片、实时 worktree 浮窗和会话结束审阅面板会随结构化工具结果更新
94
84
 
95
85
  ## 卸载
96
86
 
97
87
  ```sh
98
- univer-dsh uninstall
88
+ dsh plugin --profile web remove dsh-univer-office
99
89
  ```
100
90
 
101
- 或手动删除:删除 `~/.dsh/profiles/node_modules/dsh-univer-office` 及 `cordis.patch.yml` 中对应条目。
102
-
103
91
  ## 结构
104
92
 
105
93
  本项目是一个可安装的 DSH bundle,内部由多个 Cordis 角色组成:
106
94
 
107
- - Host 根插件组合 Univer Service Provider、webServer Consumer 和 Tools Consumer;
95
+ - Host 根插件组合 Univer Service Provider、webServer Consumer、Tools Consumer 和 bundled lazy Skill Provider;
108
96
  - Consumer 只调用 `ctx.univer`,不会直接访问 Gateway、CLI、子进程或文件系统;
109
97
  - `host/webServer` 提供 `GET /univer-api/status`、`POST /univer-api/gateway/start`、`GET /univer-api/state` 和 `POST /univer-api/worktree-action`;
110
98
  - Tools Consumer 注册领域工具,不提供通用 CLI 透传;
111
- - `host/processes/gateway` 管理内置 Gateway 进程和 Viewer 资源;`host/adapters/unit-content` 为 inspect、execute、export 启动来自 `workers/unit-content` 的一次性 Unit Content Worker;
99
+ - `host/processes/gateway` 管理内置 Gateway 进程和 Viewer 资源;`host/adapters/unit-content` 为 import、inspect、execute、export 启动来自 `workers/unit-content` 的一次性 Unit Content Worker;
112
100
  - Client 从持久化工具事件恢复结构化目标,通过统一 API 层轮询状态,再由预览、实时浮窗和审阅组件渲染。
113
101
 
114
- `src/` 是插件手写源码,`lib/index.js`、`lib/client.js` 和 `lib/types/` 均由构建生成;vendored 上游源码与生成产物分别位于 `vendor/collaboration` 和 `vendor/unit-content`。目录、依赖方向和信任边界见[架构决策](docs/architecture.md)。
102
+ `src/` 包含手写的 Host、Client、Gateway application 和 Unit Content Worker 源码。`lib/`、Gateway executable 与 Worker executable 均由构建生成并被 gitignore;只有预构建 Viewer 是版本化的运行资产。目录、依赖方向和信任边界见[架构决策](docs/architecture.md)。
115
103
 
116
104
  ## 开发
117
105
 
118
- `dist/` 与归档产物(`univer-dsh-plugin.zip`、`*.tgz`)是**生成物**——已加入 `.gitignore`,不入库。`vendor/collaboration/artifacts/` 与 `vendor/unit-content/artifacts/` 需要版本化并随包发布。先构建并测试源码:
106
+ `lib/`、Gateway 与 Worker executable、`dist/` 及归档产物(`univer-dsh-plugin.zip`、`*.tgz`)均为**生成物**,不入库。`pnpm run build` 从 `src/` 编译三个 application;`vendor/collaboration/artifacts/viewer` 下的 Viewer bundle 是唯一版本化的运行资产。
119
107
 
120
108
  ```sh
121
109
  pnpm run build
@@ -128,25 +116,14 @@ pnpm run test
128
116
  bash scripts/build-dist.sh
129
117
  ```
130
118
 
131
- 从 Univer CLI checkout 同步 Gateway、Viewer 与协作源码快照:
132
-
133
- ```sh
134
- npm run sync:collaboration -- /path/to/univer-cli
135
- ```
136
-
137
- 同步 Unit Content Worker、内嵌 Univer development credential 与当前平台原生依赖:
138
-
139
- ```sh
140
- UNIVER_CLI_SOURCE=/path/to/univer-cli npm run sync:unit-content
141
- ```
142
-
143
- 该脚本会重新生成 `dist/univer/`(发布包内容)、npm tarball `dist/univer-office-<version>.tgz` 与 zip 分发包 `univer-dsh-plugin.zip`(包内容 + 来自 `packaging/` 的 `install.command` + `INSTALL*.txt`)。
119
+ 该脚本会重新生成 `dist/univer/`(发布包内容)、npm tarball `dist/univer-office-<version>.tgz` 与 zip 分发包 `univer-dsh-plugin.zip`(包内容)。
144
120
 
145
121
  单独运行冒烟测试:
146
122
 
147
123
  ```sh
148
124
  node test/host-smoke.mjs
149
125
  node test/client-smoke.mjs
126
+ node test/skills-smoke.mjs
150
127
  npm run test:integration
151
128
  ```
152
129
 
@@ -13,14 +13,15 @@
13
13
  - `provider` 实现该接口并拥有状态缓存、文件操作和 worktree 操作;
14
14
  - `webServer` 把需要浏览器访问的服务能力映射为 Host HTTP API;
15
15
  - `tools` 把适合模型调用的内容创作能力映射为 DSH 工具;
16
+ - `skills` 向 DSH Skill Registry 提供按需加载的 Univer 工作流与 Unit 专项知识;
16
17
  - `processes/gateway` 负责插件内置 Gateway 进程和 Viewer 资源;
17
18
  - `workers/unit-content` 是一次性 Unit Content Worker 的子进程入口;
18
19
  - `client` 负责 DSH 浏览器端的预览、实时 worktree 窗口和用户审阅界面;
19
20
  - `shared/wire` 只存放 Host 与 Client 共享的纯 JSON 数据类型。
20
21
 
21
- 用户只安装本插件即可使用全部功能。全局 `univer` CLI 不属于运行依赖;Unit 的检查、执行和导出由插件内置的一次性 Unit Content Worker 完成。
22
+ 用户只安装本插件即可使用全部功能。全局 `univer` CLI 不属于运行依赖;Unit 的导入、检查、执行和导出由插件内置的一次性 Unit Content Worker 完成。
22
23
 
23
- 代码、API 和界面使用具体名称 `Gateway`、`Viewer`、`Unit Content Worker` 和 `artifacts`,不使用含义宽泛的 `runtime` 或 `daemon` 作为本插件领域名称。上游 vendored 代码中的既有名称可以原样保留。
24
+ 代码、API 和界面使用具体名称 `Gateway`、`Viewer`、`Unit Content Worker` 和 `artifacts`,不使用含义宽泛的 `runtime` 或 `daemon` 作为本插件领域名称。
24
25
 
25
26
  ## 2. 必须保留的产品功能
26
27
 
@@ -29,12 +30,14 @@
29
30
  - worktree 创建或更新后显示实时浮动窗口;
30
31
  - 一个 worktree 改动多个 unit 时,只列出有改动的 unit 并允许切换;
31
32
  - 会话结束后为 `draft` 或 `ready` worktree 显示嵌入式审阅面板;
32
- - 用户可执行提交确认、恢复编辑、丢弃和合入当前版本操作;
33
+ - 用户可在审阅面板执行提交确认、丢弃和合入当前版本操作;
33
34
  - worktree 进入 `merged` 或 `discarded` 终态后不再显示浮窗或审阅面板;
34
35
  - 插件按需启动并管理内置 Gateway 和 Viewer;
35
36
  - 多个 DSH 会话的预览目标与审阅状态相互隔离;
36
37
  - 中英文界面;
37
- - 最终由 `univer_*` 工具完成内容创建、检查、执行和导出,不要求用户安装 CLI。
38
+ - 模型可创建空 `.univer` 文件、管理 worktree 与 Unit、导入 Office 文件、查询 Univer API、修改、检查和导出内容;
39
+ - `ready` 与 `reopen` 属于模型工作流,`merge` 与 `discard` 只在用户明确要求且 DSH 审批通过后执行;
40
+ - 当前不提供模型截图工具;视觉结果重要时必须明确说明尚未完成视觉验证。
38
41
 
39
42
  原型的文件布局、类名、HTTP 路径、CSS 类名、bash 命令解析方式和内部数据格式均不需要保留。
40
43
 
@@ -43,6 +46,8 @@
43
46
  ```mermaid
44
47
  flowchart LR
45
48
  Model["Agent / Model"] --> Tools["Tools Consumer"]
49
+ Model --> SkillRegistry["DSH Skill Registry"]
50
+ Skills["Bundled Skill Provider"] --> SkillRegistry
46
51
  Browser["DSH Client"] --> WebServer["Host webServer Consumer"]
47
52
  Tools --> Service["Univer Service"]
48
53
  WebServer --> Service
@@ -57,7 +62,7 @@ flowchart LR
57
62
  Browser --> Viewer["Bundled Viewer served by Gateway"]
58
63
  ```
59
64
 
60
- 根插件是组合入口。它必须由 DSH 配置以裸包名加载,使 DSH 能发现包清单中的 `dsh.client`;根插件再在独立 Cordis fiber 中挂载 Provider、webServer Consumer 和 Tools Consumer。
65
+ 根插件是组合入口。它必须由 DSH 配置以裸包名加载,使 DSH 能发现包清单中的 `dsh.client`;根插件再在独立 Cordis fiber 中挂载 Provider、webServer Consumer、Tools Consumer 和可配置的 Skill Provider。
61
66
 
62
67
  ### Host 与 Client 的边界
63
68
 
@@ -78,6 +83,7 @@ src/
78
83
  univer-service.ts # Service Definition
79
84
  types.ts # 服务请求与返回类型
80
85
  identifiers.ts # branded file/worktree/unit ids
86
+ workspace.ts # workspace 路径解析与 realpath 授权
81
87
  errors.ts # 稳定的领域错误
82
88
  provider/
83
89
  plugin.ts # Service Provider
@@ -96,13 +102,20 @@ src/
96
102
  worktree-action.ts
97
103
  tools/
98
104
  plugin.ts # Tools Consumer
105
+ workspace.ts # 从 tool exec session 取得 workspace scope
99
106
  presentation.ts # 纯工具卡片呈现函数
100
107
  definitions/
101
- create.ts
108
+ new.ts
109
+ status.ts
110
+ worktree.ts
111
+ unit.ts
112
+ import.ts
102
113
  inspect.ts
103
114
  execute.ts
104
115
  export.ts
105
- worktree.ts
116
+ api.ts
117
+ skills/
118
+ plugin.ts # bundled lazy Skill Provider
106
119
  adapters/
107
120
  gateway/
108
121
  client.ts
@@ -121,6 +134,14 @@ src/
121
134
  workers/
122
135
  unit-content/
123
136
  entry.ts # 一次性无头 Univer 子进程入口
137
+ license.ts # Worker 使用的 Univer license
138
+ runtime/ # 本地 snapshot/reference adapters
139
+ gateway-app/
140
+ gateway-entry.ts # Gateway 子进程入口
141
+ transport/http.ts # 文件、worktree 与 Unit HTTP 控制面
142
+ collab-service.ts # Gateway 协作领域实现
143
+ contract/ # Gateway wire types
144
+ univerfile-sqlite/ # `.univer` 持久化
124
145
  client/
125
146
  index.tsx # dsh.client 入口
126
147
  api/
@@ -149,24 +170,29 @@ src/
149
170
  state.ts
150
171
  actions.ts
151
172
  lib/
152
- index.js # 生成的 Host 入口
153
- client.js # 生成的 ModuleLoader Client bundle
154
- types/ # 生成的类型声明
173
+ index.js # gitignored 的 Host 生成入口
174
+ client.js # gitignored 的 ModuleLoader Client bundle
175
+ types/ # gitignored 的类型声明
155
176
  vendor/
156
177
  collaboration/
157
- upstream/ # Gateway 与 Viewer 上游源码快照
158
- artifacts/ # 发布使用的 Gateway 与 Viewer
178
+ artifacts/viewer/ # 版本化的预构建 Viewer
179
+ artifacts/gateway.cjs # 从 gateway-app 生成,gitignored
159
180
  unit-content/
160
- upstream/ # 尚未发包的 Univer CLI 应用辅助源码快照
161
- artifacts/ # Worker、公式引擎与 Office 转换器
181
+ artifacts/unit-content-worker.mjs # 从 workers/unit-content 生成,gitignored
162
182
  test/
163
183
  host-smoke.mjs
164
184
  client-smoke.mjs
165
185
  integration-smoke.mjs
186
+ skills-smoke.mjs
166
187
  scripts/
167
188
  build.mjs
168
- sync-collaboration.mjs
169
- sync-unit-content.mjs
189
+ skills/
190
+ univer/SKILL.md # 核心工作流与安全规则
191
+ univer-sheet/SKILL.md
192
+ univer-doc/SKILL.md
193
+ univer-slide/SKILL.md
194
+ univer-base/SKILL.md
195
+ univer-board/SKILL.md
170
196
  ```
171
197
 
172
198
  当前仍采用单包发布。只有当某一层具备独立版本、独立消费方或明显不同的发布节奏时才拆 npm 包;目录分层本身不是拆包理由。
@@ -180,7 +206,8 @@ client components -> client hooks -> client api -> shared/wire
180
206
  webServer consumer -> service <----- tools consumer
181
207
  ^
182
208
  |
183
- provider -> adapters -> processes / workers / vendor
209
+ provider -> adapters -> processes / workers / gateway-app
210
+ bundled skill provider -> DSH skill registry
184
211
  ```
185
212
 
186
213
  具体约束:
@@ -190,18 +217,20 @@ webServer consumer -> service <----- tools consumer
190
217
  3. `host/processes/gateway` 只管理 Gateway 进程与资源,不包含 worktree、unit、merge 等业务规则。
191
218
  4. Client component 不直接 `fetch`;HTTP 访问集中在 `client/api`,轮询和 mutation 状态集中在 hooks。
192
219
  5. `shared/wire` 不依赖 Node.js、React、Cordis 或上游 Univer 包,且所有值必须可 JSON 序列化。
193
- 6. vendored 上游目录不放插件专用代码;一次性 Worker 入口属于 `src/workers/unit-content`,只通过固定 revision 的上游模块实现功能。必须修改上游行为时,在 adapter 中包裹,或在同步清单中记录可重放的补丁。
194
- 7. 所有 Cordis 注册通过 effect 生命周期撤销;插件卸载后不得遗留路由、工具、定时器或子进程。
220
+ 6. Gateway 与 Worker 的应用源码分别属于 `src/gateway-app` 和 `src/workers/unit-content`。它们通过精确版本 SDK package 构建,不从外部 checkout 同步源码;生成 executable 不入库。
221
+ 7. Skill Provider 只负责发现与加载包内 Markdown,不调用 Service,也不复制工具 schema。
222
+ 8. 所有 Cordis 注册通过 effect 生命周期撤销;插件卸载后不得遗留路由、工具、Skill provider、定时器或子进程。
195
223
 
196
224
  ## 6. Service Definition
197
225
 
198
226
  `UniverService` 是 Host 内部唯一稳定的领域入口。Service Definition 只描述调用方依赖的行为,不暴露 HTTP、Gateway endpoint、worker 协议或子进程对象。
199
227
 
200
- 服务能力分为三组:
228
+ 服务能力分为四组:
201
229
 
202
- - Gateway:查询状态并确保插件持有的 Gateway 可用;
203
- - Unit Content:创建文件和首个 Unit,以及检查、执行和导出 Unit 内容;
204
- - Collaboration:读取文件/worktree 状态、生成 Viewer 目标、执行 worktree 生命周期操作。
230
+ - File 与状态:创建空 `.univer` 容器,读取 trunk、worktree 与 Unit 状态;
231
+ - Collaboration:创建 worktree,执行 ready、reopen、merge 与 discard 生命周期操作;
232
+ - Unit Content:在 draft worktree 中创建、移除或导入 Unit,以及检查、执行和导出 Unit 内容;
233
+ - API Reference:查找 API 候选并读取指定 Facade/方法的完整参考。
205
234
 
206
235
  所有文件操作都接收显式 workspace scope。Provider 必须将文件解析为绝对路径,并拒绝 scope 外路径。文件 ID、worktree ID 和 unit ID 在服务层使用 branded 类型,不能以无语义的裸字符串跨层传递。
207
236
 
@@ -214,12 +243,12 @@ Provider 按规范化文件路径维护缓存;同一个插件实例只持有
214
243
  Gateway Supervisor 只负责:
215
244
 
216
245
  - 选择并验证监听端口;
217
- - 启动 vendored Gateway;
246
+ - 启动随包发布、由 `src/gateway-app` 构建的 Gateway;
218
247
  - 等待健康检查成功;
219
248
  - 提供 Gateway origin 与 Viewer origin;
220
249
  - 在所属 Cordis fiber 结束时终止插件启动的进程。
221
250
 
222
- Unit 的检查、执行和导出由 Unit Content Adapter 启动一次性 Unit Content Worker。Worker 连接 Gateway Supervisor 提供的同一个 Gateway,操作完成或取消后退出,不拥有独立持久状态。写操作只能针对显式 draft worktree 与 unit;Gateway 是提交结果和 revision 的唯一依据。
251
+ Unit 的导入、检查、执行和导出由 Unit Content Adapter 启动一次性 Unit Content Worker。Worker 连接 Gateway Supervisor 提供的同一个 Gateway,操作完成或取消后退出,不拥有独立持久状态。Gateway 的 worktree 控制面直接提供 Unit 创建与移除端点,并通过 collaboration service 与 lifecycle event 完成操作。写操作只能针对显式 draft worktree;Gateway 是提交结果和 revision 的唯一依据。
223
252
 
224
253
  它不得复用或终止外部启动的 Gateway。已占用的候选端口必须跳过;健康检查需要验证 Viewer 身份,不能把任意返回 HTTP 200 的本地服务误认为 Gateway。
225
254
 
@@ -240,15 +269,21 @@ worktree 修改审阅操作必须绑定当前 DSH 会话及其 workspace scope
240
269
 
241
270
  Tools Consumer 注册面向模型的领域工具,而不是一个透传 CLI 的通用工具:
242
271
 
243
- - `univer_create`
272
+ - `univer_new`
273
+ - `univer_status`
274
+ - `univer_worktree`
275
+ - `univer_unit`
276
+ - `univer_import`
244
277
  - `univer_inspect`
245
278
  - `univer_execute`
246
279
  - `univer_export`
247
- - `univer_worktree`
280
+ - `univer_api`
248
281
 
249
282
  每个工具有独立的参数 schema、结果 schema、超时/取消处理和纯 presentation。工具结果必须包含恢复 Client 预览目标所需的结构化文件、worktree 与 unit 标识,并进入 DSH 会话日志。Client 优先从 `tool/call` 与 `tool/result` 事件恢复目标,不依赖 bash 文本解析。
250
283
 
251
- `ready`、`reopen`、`discard` 和 `merge` 是用户审阅决策,不提供给模型工具。`univer_worktree` 只覆盖 agent 工作所需且不会代替用户批准的操作,例如创建、查询或更新工作分支。
284
+ `univer_status` 是发现文件状态与显式 Unit ID 的入口。所有内容工具要求显式 Unit ID,所有文件和输出路径都绑定当前 tool exec session 的 workspace,并在 Provider 边界再次验证。`ready` 提交修改等待审阅;同一任务需要继续修改时用 `reopen`。`merge` 与 `discard` 只有在用户明确要求时才可调用,并通过 `tools/pre-execute` 返回审批请求,不能由模型自行决定。
285
+
286
+ 包内 `univer` Skill 描述完整编排顺序,sheet、doc、slide、base 与 board Skill 只在对应 Unit 工作时按需加载。Skill 不提供截图能力,也不把可变 API 签名固化在 Markdown 中;不确定的 API 必须通过 `univer_api` 查询。
252
287
 
253
288
  Client 只解析结构化 `univer_*` 工具事件,不从 bash 命令或自由文本猜测文件与 worktree。
254
289
 
@@ -274,26 +309,20 @@ Client 必须满足:
274
309
 
275
310
  当前实现满足以下约束:
276
311
 
277
- 1. `univer_create` 通过 Gateway 创建 `.univer` 容器和首个显式类型的 Unit;
278
- 2. `univer_execute` 只写入显式 draft worktree,并由 Gateway revision 确认提交;
312
+ 1. `univer_new` 只创建空 `.univer` 容器,Unit 由 `univer_unit` 或 `univer_import` 显式加入 draft worktree;
313
+ 2. `univer_execute` 只写入显式 draft worktree 与 Unit,并由 Gateway revision 确认提交;
279
314
  3. `univer_inspect` 与 `univer_export` 可读取 trunk 或显式 worktree;
280
- 4. Client 只从结构化工具事件恢复预览目标;
281
- 5. 全新环境仅安装本插件即可完成创建、修改、检查、导出、预览和 worktree 修改审阅。
282
-
283
- ## 12. 构建、发布与 vendoring
284
-
285
- `src` 是插件自有手写源码,`vendor/*/upstream` 只保存尚未发包且必须复制的固定 revision 上游源码,`lib` 是构建生成物并随 npm 包发布。`univer-cli-sdk` 的公开 package 通过内部 npm registry 以精确版本安装,不复制进 `vendor`;生成 Unit Content Worker 时将这些依赖打入 artifact。Host 构建为 Node ESM,Client 构建为 DSH ModuleLoader 可加载的浏览器 bundle。删除原型的手工 bundle 拼接脚本,构建必须从 Client 源码确定性地产生完整 bundle。
315
+ 4. `univer_api` 使用包依赖的精确版本 API Reference,不调用外部 CLI;
316
+ 5. Client 只从结构化工具事件恢复预览目标;
317
+ 6. 全新环境仅安装本插件即可完成创建、导入、修改、检查、导出、预览和 worktree 修改审阅。
286
318
 
287
- 发布包包含运行所需的 Gateway、Viewer、Unit Content Worker、Office 转换器、平台依赖与 Univer license。`vendor/collaboration/SOURCE.json` 和 `vendor/unit-content/SOURCE.json` 固定复制源码的上游 revision,并记录用于生成 artifact 的 SDK package 版本;同步脚本负责复制必要源码、生成 artifacts、许可证和依赖,不允许人工修改 artifacts 后遗漏来源记录。
319
+ ## 12. 构建与发布
288
320
 
289
- 原生公式引擎、Office 转换器与 SQLite 依赖使 artifacts 具有平台属性。一个发布产物只能声明并携带同一目标平台的原生依赖,`SOURCE.json` 记录目标平台;正式发包流程建立后,应为 macOS arm64、Linux x64/arm64 和 Windows x64 分别构建并验证,不能把当前平台产物描述为跨平台包。
321
+ `src` 是插件自有手写源码。`pnpm run build` 分别生成 Host/Client bundle、Unit Content Worker 和 Gateway;`lib`、Worker executable 与 Gateway executable 都被 gitignore,并在打包前重新生成。Host 构建为 Node ESM,Client 构建为 DSH ModuleLoader 可加载的浏览器 bundle,Gateway 构建为 Node CJS 子进程,Worker 构建为 Node ESM 子进程。
290
322
 
291
- 在协作 packages 尚无可依赖发包流程时,可以复制其实现进入 vendor 或明确归属的 adapter,但必须:
323
+ 发布包包含运行所需的 Gateway、Viewer、Unit Content Worker、Office 转换器、平台依赖、Univer license 与 bundled Skills。Gateway、Worker 和 Host 直接使用 manifest 中精确版本的 Univer SDK/API Reference packages;JavaScript SDK 被 bundle,平台原生 package 由包管理器为目标机器安装。Viewer bundle 是唯一版本化的预构建运行资产。
292
324
 
293
- - 保留原许可证与 notice;
294
- - 记录精确来源 revision;
295
- - 将上游源码与本插件代码分开;
296
- - 预留替换为正式依赖的单一 adapter 接缝。
325
+ 原生公式引擎、Office 转换器与 SQLite 依赖仍具有平台属性。release workflow 必须在目标平台安装 lockfile 所指定的依赖后构建和测试,不能把一个平台的 `node_modules` 复制为通用发布物。
297
326
 
298
327
  ## 13. 验证策略
299
328
 
@@ -303,6 +332,7 @@ Client 必须满足:
303
332
  - `provider`:路径 scope、缓存失效、Gateway 映射、worktree 状态与错误;
304
333
  - `webServer`:method、JSON、字段、会话授权和错误响应;
305
334
  - `tools`:schema、取消、结构化结果和 presentation;
335
+ - `skills`:发现顺序、按需加载、frontmatter 剥离和发布包收录;
306
336
  - `client`:事件恢复、轮询生命周期、浮窗交互、unit 切换和审阅 mutation;
307
337
  - `integration`:无全局 CLI 的全新环境中,仅安装插件完成端到端功能。
308
338
 
@@ -315,9 +345,9 @@ Client 必须满足:
315
345
  - 不使用 `capability` 作为目录名;DSH 架构中的 capability seam 由这里的 Service Definition、Provider 和 Consumer 共同实现;
316
346
  - 不使用 `daemon` 作为本插件领域名称;
317
347
  - 不让用户长期同时安装插件和 CLI;
318
- - 不把 Gateway 和 Viewer 的完整实现重新手写进 Host;
348
+ - 不把 Gateway 业务实现写进 Host Service/Provider;Gateway 保持独立 application 与进程;
319
349
  - 不在当前阶段仅为目录整齐拆成多个 npm 包;
320
- - 不让模型替用户执行 merge、discard 等审阅决策。
350
+ - 不让模型自行决定 merge 或 discard;显式用户请求仍必须经过 DSH 工具审批。
321
351
 
322
352
  ## 15. 变更规则
323
353
 
@@ -327,5 +357,6 @@ Client 必须满足:
327
357
  - Host、Client、Gateway 与 Unit Content Worker 的信任边界;
328
358
  - 是否依赖外部 CLI 或外部 Gateway;
329
359
  - worktree 用户审阅权归属;
330
- - vendored 源码与许可证策略;
360
+ - 工具能力与 bundled Skills 的对应关系;
361
+ - 源码构建、预构建 Viewer 与许可证策略;
331
362
  - 单包与多包的发布决策。