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.
- package/README.md +21 -44
- package/README.zh-CN.md +21 -44
- package/docs/architecture.md +77 -46
- package/lib/client.js +211 -80
- package/lib/index.js +943 -165
- package/lib/index.js.map +4 -4
- package/lib/types/client/components/review-panel.d.ts.map +1 -1
- package/lib/types/client/components/univer-dock.d.ts.map +1 -1
- package/lib/types/client/components/worktree-window.d.ts +6 -3
- package/lib/types/client/components/worktree-window.d.ts.map +1 -1
- package/lib/types/client/styles/worktree.d.ts +1 -1
- package/lib/types/client/styles/worktree.d.ts.map +1 -1
- package/lib/types/host/adapters/gateway/mapping.d.ts +6 -0
- package/lib/types/host/adapters/gateway/mapping.d.ts.map +1 -1
- package/lib/types/host/adapters/gateway/worktree-api.d.ts +6 -2
- package/lib/types/host/adapters/gateway/worktree-api.d.ts.map +1 -1
- package/lib/types/host/adapters/unit-content/protocol.d.ts +6 -2
- package/lib/types/host/adapters/unit-content/protocol.d.ts.map +1 -1
- package/lib/types/host/artifacts/paths.d.ts +1 -1
- package/lib/types/host/artifacts/paths.d.ts.map +1 -1
- package/lib/types/host/config.d.ts +3 -0
- package/lib/types/host/config.d.ts.map +1 -1
- package/lib/types/host/index.d.ts.map +1 -1
- package/lib/types/host/processes/gateway/supervisor.d.ts +1 -1
- package/lib/types/host/processes/gateway/supervisor.d.ts.map +1 -1
- package/lib/types/host/provider/gateway-univer-service.d.ts +21 -8
- package/lib/types/host/provider/gateway-univer-service.d.ts.map +1 -1
- package/lib/types/host/provider/unit-content-operations.d.ts +6 -1
- package/lib/types/host/provider/unit-content-operations.d.ts.map +1 -1
- package/lib/types/host/service/identifiers.d.ts +4 -0
- package/lib/types/host/service/identifiers.d.ts.map +1 -1
- package/lib/types/host/service/types.d.ts +76 -27
- package/lib/types/host/service/types.d.ts.map +1 -1
- package/lib/types/host/service/univer-service.d.ts +6 -2
- package/lib/types/host/service/univer-service.d.ts.map +1 -1
- package/lib/types/host/service/workspace.d.ts +21 -0
- package/lib/types/host/service/workspace.d.ts.map +1 -0
- package/lib/types/host/skills/plugin.d.ts +6 -0
- package/lib/types/host/skills/plugin.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/api.d.ts +4 -0
- package/lib/types/host/tools/definitions/api.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/execute.d.ts.map +1 -1
- package/lib/types/host/tools/definitions/export.d.ts.map +1 -1
- package/lib/types/host/tools/definitions/import.d.ts +4 -0
- package/lib/types/host/tools/definitions/import.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/inspect.d.ts.map +1 -1
- package/lib/types/host/tools/definitions/new.d.ts +4 -0
- package/lib/types/host/tools/definitions/new.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/status.d.ts +4 -0
- package/lib/types/host/tools/definitions/status.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/unit.d.ts +4 -0
- package/lib/types/host/tools/definitions/unit.d.ts.map +1 -0
- package/lib/types/host/tools/definitions/worktree.d.ts.map +1 -1
- package/lib/types/host/tools/plugin.d.ts.map +1 -1
- package/lib/types/host/tools/presentation.d.ts +29 -2
- package/lib/types/host/tools/presentation.d.ts.map +1 -1
- package/lib/types/host/tools/workspace.d.ts +16 -0
- package/lib/types/host/tools/workspace.d.ts.map +1 -0
- package/lib/types/host/webServer/routes/state.d.ts.map +1 -1
- package/lib/types/host/webServer/routes/worktree-action.d.ts.map +1 -1
- package/lib/types/host/webServer/session-scope.d.ts +3 -1
- package/lib/types/host/webServer/session-scope.d.ts.map +1 -1
- package/lib/types/shared/wire/actions.d.ts +1 -1
- package/lib/types/shared/wire/actions.d.ts.map +1 -1
- package/package.json +7 -8
- package/scripts/copy-gateway-dependencies.mjs +36 -1
- package/skills/univer/SKILL.md +40 -0
- package/skills/univer-base/SKILL.md +14 -0
- package/skills/univer-board/SKILL.md +14 -0
- package/skills/univer-doc/SKILL.md +16 -0
- package/skills/univer-sheet/SKILL.md +36 -0
- package/skills/univer-slide/SKILL.md +16 -0
- package/vendor/collaboration/artifacts/gateway.cjs +104 -18
- package/vendor/unit-content/artifacts/unit-content-worker.mjs +19 -1
- package/lib/types/host/tools/definitions/create.d.ts +0 -4
- package/lib/types/host/tools/definitions/create.d.ts.map +0 -1
- 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
|
|
20
|
-
│ │ (read-only, real-time) │ │ drag /
|
|
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
|
|
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
|
|
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
|
|
46
|
-
- No global Univer CLI installation is required. The plugin bundles its Gateway, Viewer, headless Unit Content Worker, Office converter, Univer license,
|
|
47
|
-
-
|
|
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.
|
|
92
|
-
2.
|
|
93
|
-
3.
|
|
94
|
-
4.
|
|
95
|
-
5. Submit
|
|
96
|
-
6.
|
|
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-
|
|
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
|
|
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/`
|
|
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
|
|
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
|
-
|
|
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
|
-
- **浮窗交互** ——
|
|
38
|
-
- **ready + 会话结束 → 自动关闭并嵌入合并页** —— 会话转入空闲后,所有**非终态** worktree 自动进入会话下方的审阅 dock:`ready` 显示合并预览(`scope=mergePreview`)+
|
|
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
|
-
-
|
|
46
|
-
- 不需要全局安装 Univer CLI。插件内置 Gateway、Viewer、无头 Unit Content Worker、Office 转换器、Univer license
|
|
47
|
-
-
|
|
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.
|
|
89
|
-
2.
|
|
90
|
-
3.
|
|
91
|
-
4.
|
|
92
|
-
5.
|
|
93
|
-
6.
|
|
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-
|
|
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 和
|
|
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/`
|
|
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/`
|
|
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
|
-
|
|
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
|
|
package/docs/architecture.md
CHANGED
|
@@ -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
|
|
22
|
+
用户只安装本插件即可使用全部功能。全局 `univer` CLI 不属于运行依赖;Unit 的导入、检查、执行和导出由插件内置的一次性 Unit Content Worker 完成。
|
|
22
23
|
|
|
23
|
-
代码、API 和界面使用具体名称 `Gateway`、`Viewer`、`Unit Content Worker` 和 `artifacts`,不使用含义宽泛的 `runtime` 或 `daemon`
|
|
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
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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 #
|
|
153
|
-
client.js #
|
|
154
|
-
types/ #
|
|
173
|
+
index.js # gitignored 的 Host 生成入口
|
|
174
|
+
client.js # gitignored 的 ModuleLoader Client bundle
|
|
175
|
+
types/ # gitignored 的类型声明
|
|
155
176
|
vendor/
|
|
156
177
|
collaboration/
|
|
157
|
-
|
|
158
|
-
artifacts/
|
|
178
|
+
artifacts/viewer/ # 版本化的预构建 Viewer
|
|
179
|
+
artifacts/gateway.cjs # 从 gateway-app 生成,gitignored
|
|
159
180
|
unit-content/
|
|
160
|
-
|
|
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
|
-
|
|
169
|
-
|
|
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 /
|
|
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.
|
|
194
|
-
7.
|
|
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
|
-
-
|
|
203
|
-
-
|
|
204
|
-
-
|
|
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
|
-
-
|
|
246
|
+
- 启动随包发布、由 `src/gateway-app` 构建的 Gateway;
|
|
218
247
|
- 等待健康检查成功;
|
|
219
248
|
- 提供 Gateway origin 与 Viewer origin;
|
|
220
249
|
- 在所属 Cordis fiber 结束时终止插件启动的进程。
|
|
221
250
|
|
|
222
|
-
Unit
|
|
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
|
-
- `
|
|
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
|
-
- `
|
|
280
|
+
- `univer_api`
|
|
248
281
|
|
|
249
282
|
每个工具有独立的参数 schema、结果 schema、超时/取消处理和纯 presentation。工具结果必须包含恢复 Client 预览目标所需的结构化文件、worktree 与 unit 标识,并进入 DSH 会话日志。Client 优先从 `tool/call` 与 `tool/result` 事件恢复目标,不依赖 bash 文本解析。
|
|
250
283
|
|
|
251
|
-
`ready
|
|
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. `
|
|
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.
|
|
281
|
-
5.
|
|
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
|
-
|
|
319
|
+
## 12. 构建与发布
|
|
288
320
|
|
|
289
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
348
|
+
- 不把 Gateway 业务实现写进 Host Service/Provider;Gateway 保持独立 application 与进程;
|
|
319
349
|
- 不在当前阶段仅为目录整齐拆成多个 npm 包;
|
|
320
|
-
-
|
|
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
|
-
-
|
|
360
|
+
- 工具能力与 bundled Skills 的对应关系;
|
|
361
|
+
- 源码构建、预构建 Viewer 与许可证策略;
|
|
331
362
|
- 单包与多包的发布决策。
|