dsh-univer-office 0.2.3 → 0.2.5
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 +8 -8
- package/README.zh-CN.md +8 -8
- package/artifacts/gateway.cjs +8 -2
- package/docs/architecture.md +10 -9
- package/docs/univer-turn-projection-and-surfaces.md +243 -0
- package/lib/client.js +440 -475
- package/lib/index.js +38 -20
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -123,9 +123,9 @@ The agent automatically loads the relevant skills and selects the `univer_*` too
|
|
|
123
123
|
|
|
124
124
|
### 3. Review it in the conversation
|
|
125
125
|
|
|
126
|
-
-
|
|
127
|
-
-
|
|
128
|
-
-
|
|
126
|
+
- Creating a `.univer` file, creating or reopening a worktree, writing content, and submitting for review opens a live window in the top-right. A non-terminal worktree left open in one turn stays open in the next.
|
|
127
|
+
- Every touched `.univer` file that still exists at the end of the Turn uses the same foldable, fullscreen-capable Turn card; historical Turns keep the same card collapsed by default. Temporary files created and then removed during the Turn do not leave cards behind.
|
|
128
|
+
- Submit, merge, and discard through the full Univer page embedded in the card instead of duplicate controls outside the Viewer.
|
|
129
129
|
|
|
130
130
|
## How it works
|
|
131
131
|
|
|
@@ -169,9 +169,9 @@ The plugin also ships eight version-matched, lazily loaded skills: core orchestr
|
|
|
169
169
|
|
|
170
170
|
## Preview and review experience
|
|
171
171
|
|
|
172
|
-
- **Live
|
|
173
|
-
- **
|
|
174
|
-
- **
|
|
172
|
+
- **Live Univer window** — file creation plus worktree creation, reopening, writing, and submission open it automatically. Drag, resize, fold, or maximize it; non-terminal windows left open carry into the next Turn.
|
|
173
|
+
- **Unified Turn cards** — every touched `.univer` file that still exists has its own full Univer card, later reads do not erase a lifecycle result already produced in that Turn, and deleted temporary files do not leave loading cards behind.
|
|
174
|
+
- **Historical review** — draft, ready, merged, and discarded results all remain in the same card layout at their original Turn, with historical cards collapsed by default.
|
|
175
175
|
- **Session isolation** — each DSH session shows only its own windows, cards, and review state.
|
|
176
176
|
- **English and Chinese UI** — the plugin shell and every open Viewer follow the DSH locale.
|
|
177
177
|
|
|
@@ -185,11 +185,11 @@ The plugin also ships eight version-matched, lazily loaded skills: core orchestr
|
|
|
185
185
|
|
|
186
186
|
## Configuration
|
|
187
187
|
|
|
188
|
-
The defaults are designed for local use: the Gateway starts on the first file-state request
|
|
188
|
+
The defaults are designed for local use: the Gateway starts on the first file-state request at `9080`. If that port is occupied, it tries `9081`, then continues upward one port at a time. Configure the bundle's Cordis layer when you need different values:
|
|
189
189
|
|
|
190
190
|
| Field | Default | Purpose |
|
|
191
191
|
| --- | --- | --- |
|
|
192
|
-
| `
|
|
192
|
+
| `gatewayPort` | `9080` | Initial loopback port for the bundled Gateway; occupied ports advance by one |
|
|
193
193
|
| `autoStartGateway` | `true` | Start the Gateway on first use |
|
|
194
194
|
| `gatewayStartupTimeoutMs` | `10000` | Gateway startup timeout |
|
|
195
195
|
| `gatewayRequestTimeoutMs` | `3000` | State-read timeout |
|
package/README.zh-CN.md
CHANGED
|
@@ -123,9 +123,9 @@ Agent 会自动选择对应 Skills 和 `univer_*` 工具。通常会依次创建
|
|
|
123
123
|
|
|
124
124
|
### 3. 在会话中审阅
|
|
125
125
|
|
|
126
|
-
-
|
|
127
|
-
-
|
|
128
|
-
-
|
|
126
|
+
- 新建 `.univer` 文件、创建或重开 worktree、写入内容以及提交确认时,右上角实时浮窗会同步显示结果;上一轮保持打开的非终态 worktree 会在下一轮继续显示。
|
|
127
|
+
- 每个被操作且在回合结束时仍存在的 `.univer` 文件都使用统一的回合卡片,可折叠或在应用内全屏打开;历史回合保留同款卡片并默认折叠。过程中创建后又删除的临时文件不显示卡片。
|
|
128
|
+
- 提交、合并和丢弃使用卡片内完整 Univer 页面提供的操作,不在卡片外重复显示按钮。
|
|
129
129
|
|
|
130
130
|
## 工作方式
|
|
131
131
|
|
|
@@ -169,9 +169,9 @@ Agent 会自动选择对应 Skills 和 `univer_*` 工具。通常会依次创建
|
|
|
169
169
|
|
|
170
170
|
## 预览与审阅体验
|
|
171
171
|
|
|
172
|
-
- **实时
|
|
173
|
-
-
|
|
174
|
-
-
|
|
172
|
+
- **实时 Univer 窗口**:新建文件或创建、重开、写入和提交 worktree 时主动显示,可拖动、缩放、折叠和全屏;保持打开的非终态 worktree 会跨回合延续。
|
|
173
|
+
- **统一回合卡片**:每个被操作且当前仍存在的 `.univer` 文件都有独立的完整 Univer 卡片;纯读取不会覆盖同一回合已经发生的 worktree 生命周期结果,已删除的临时文件不会留下加载卡片。
|
|
174
|
+
- **历史审阅**:`draft`、`ready`、合并和丢弃结果都使用同款卡片保留在原回合,历史卡片默认折叠。
|
|
175
175
|
- **多会话隔离**:每个 DSH 会话只展示属于自己的窗口、卡片和审阅状态。
|
|
176
176
|
- **中英文界面**:插件外壳和已打开的 Viewer 跟随 DSH 的界面语言。
|
|
177
177
|
|
|
@@ -185,11 +185,11 @@ Agent 会自动选择对应 Skills 和 `univer_*` 工具。通常会依次创建
|
|
|
185
185
|
|
|
186
186
|
## 配置
|
|
187
187
|
|
|
188
|
-
默认配置适合本地使用:Gateway
|
|
188
|
+
默认配置适合本地使用:Gateway 会在首次读取文件状态时从端口 `9080` 启动;若该端口被占用,则依次尝试 `9081`、`9082`。如需定制,可在 bundle 的 Cordis 配置层设置:
|
|
189
189
|
|
|
190
190
|
| 字段 | 默认值 | 说明 |
|
|
191
191
|
| --- | --- | --- |
|
|
192
|
-
| `
|
|
192
|
+
| `gatewayPort` | `9080` | 内置 Gateway 的起始本地端口;被占用时逐次加一 |
|
|
193
193
|
| `autoStartGateway` | `true` | 首次访问时自动启动 Gateway |
|
|
194
194
|
| `gatewayStartupTimeoutMs` | `10000` | Gateway 启动超时 |
|
|
195
195
|
| `gatewayRequestTimeoutMs` | `3000` | 状态读取超时 |
|
package/artifacts/gateway.cjs
CHANGED
|
@@ -315378,6 +315378,9 @@ var init_zh_latn_pinyin_BdYb_Ey = __esm({
|
|
|
315378
315378
|
// src/gateway-app/gateway-entry.ts
|
|
315379
315379
|
var import_node_process = __toESM(require("node:process"), 1);
|
|
315380
315380
|
|
|
315381
|
+
// src/shared/gateway-process-protocol.ts
|
|
315382
|
+
var GATEWAY_PORT_IN_USE_EXIT_CODE = 98;
|
|
315383
|
+
|
|
315381
315384
|
// src/gateway-app/server.ts
|
|
315382
315385
|
var import_promises = require("node:fs/promises");
|
|
315383
315386
|
var import_node_http = __toESM(require("node:http"), 1);
|
|
@@ -443397,7 +443400,7 @@ function listen(server, port) {
|
|
|
443397
443400
|
|
|
443398
443401
|
// src/gateway-app/gateway-entry.ts
|
|
443399
443402
|
async function main() {
|
|
443400
|
-
const port = Number(import_node_process.default.env.UNIVER_COLLAB_GATEWAY_PORT ??
|
|
443403
|
+
const port = Number(import_node_process.default.env.UNIVER_COLLAB_GATEWAY_PORT ?? 9080);
|
|
443401
443404
|
const viewAssetsRoot = import_node_process.default.env.UNIVER_VIEW_ASSETS_ROOT;
|
|
443402
443405
|
const allowedRoot = import_node_process.default.env.UNIVER_ALLOWED_ROOT;
|
|
443403
443406
|
const server = await startServer({
|
|
@@ -443411,5 +443414,8 @@ async function main() {
|
|
|
443411
443414
|
main().catch((error) => {
|
|
443412
443415
|
import_node_process.default.stderr.write(`[dsh-univer-gateway] failed to start: ${String(error)}
|
|
443413
443416
|
`);
|
|
443414
|
-
import_node_process.default.exitCode = 1;
|
|
443417
|
+
import_node_process.default.exitCode = isAddressInUse(error) ? GATEWAY_PORT_IN_USE_EXIT_CODE : 1;
|
|
443415
443418
|
});
|
|
443419
|
+
function isAddressInUse(error) {
|
|
443420
|
+
return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
|
|
443421
|
+
}
|
package/docs/architecture.md
CHANGED
|
@@ -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
|
|
33
|
+
- 后续回合再次操作同一 worktree 时,旧回合保留同一张完整卡片并默认折叠,不回退到旧文件预览卡片或单独历史 header;
|
|
34
34
|
- 审阅卡片使用紧凑 header:首行显示 Univer 文件名和右侧的 worktree 名称,次行只显示完整文件路径,状态、折叠和全屏控制位于右侧;桌面端不同生命周期的展开卡片默认总高度约 650px,内嵌完整页面默认折叠左侧边栏,卡片折叠保留已加载页面;全屏时隐藏折叠按钮,Esc 退出全屏;
|
|
35
|
-
- draft
|
|
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-
|
|
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/
|
|
@@ -264,7 +261,7 @@ Gateway Supervisor 只负责:
|
|
|
264
261
|
|
|
265
262
|
Unit 的导入、检查、执行和导出由 Unit Content Adapter 启动一次性 Unit Content Worker。Worker 连接 Gateway Supervisor 提供的同一个 Gateway,操作完成或取消后退出,不拥有独立持久状态。Gateway 的 worktree 控制面直接提供 Unit 创建与移除端点,并通过 collaboration service 与 lifecycle event 完成操作。写操作只能针对显式 draft worktree;Gateway 是提交结果和 revision 的唯一依据。
|
|
266
263
|
|
|
267
|
-
它不得复用或终止外部启动的 Gateway
|
|
264
|
+
它不得复用或终止外部启动的 Gateway。内置 Gateway 默认从 `9080` 启动,端口被占用时逐次加一;只有结构化确认端口占用时才能继续尝试下一端口,其他启动失败必须立即返回。健康检查需要验证 Viewer 身份,不能把任意返回 HTTP 200 的本地服务误认为 Gateway。
|
|
268
265
|
|
|
269
266
|
## 8. webServer Consumer 与浏览器协议
|
|
270
267
|
|
|
@@ -307,7 +304,9 @@ Client 只解析结构化 `univer_*` 工具事件,不从 bash 命令或自由
|
|
|
307
304
|
|
|
308
305
|
Client 是状态投影,不拥有 worktree 真相。预览目标来自可回放的会话事件;实时状态来自 Host API;Viewer iframe 负责文档内容的实时展示。
|
|
309
306
|
|
|
310
|
-
|
|
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 移除决策
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# Univer Turn 投影与预览界面设计
|
|
2
|
+
|
|
3
|
+
状态:已实施
|
|
4
|
+
|
|
5
|
+
日期:2026-08-18
|
|
6
|
+
|
|
7
|
+
本文记录回合级 Univer 操作投影、实时浮窗和回合尾部卡片的已实施设计。稳定的当前行为同时归入架构文档与双语 README。
|
|
8
|
+
|
|
9
|
+
## 1. 目标
|
|
10
|
+
|
|
11
|
+
- 从可回放的结构化会话事件中恢复每个 Turn 对 `.univer` 文件执行的全部操作及其状态变化;
|
|
12
|
+
- 卡片与浮窗共享同一份 Turn 投影,不各自猜测工具语义;
|
|
13
|
+
- 所有回合尾部展示统一使用当前审阅卡片布局,不再回退旧文件预览卡片或单独的历史 header;
|
|
14
|
+
- 生命周期操作、内容写入和读取操作分开归约,避免用最后一次工具调用覆盖真实结果;
|
|
15
|
+
- 浮窗只在明确的创建或修改时机主动拉起,同时延续用户在上一轮保持打开的非终态 worktree;
|
|
16
|
+
- Host `FileState` 始终是 worktree 当前状态与 Viewer URL 的权威来源。
|
|
17
|
+
|
|
18
|
+
## 2. 事实来源与职责
|
|
19
|
+
|
|
20
|
+
### 2.1 `UniverTurnProjection`
|
|
21
|
+
|
|
22
|
+
新增专门的 Conversation Definition,以纯 reducer 方式消费当前 Turn 的 `turn/start`、`tool/call` 与 `tool/result` 事件。它不访问 HTTP、不依赖 React、不生成 Viewer URL,也不持有用户界面打开状态。
|
|
23
|
+
|
|
24
|
+
投影按文件记录:
|
|
25
|
+
|
|
26
|
+
- 工具名和 worktree action;
|
|
27
|
+
- 操作顺序和执行阶段;
|
|
28
|
+
- 文件、worktree 与 Unit 标识;
|
|
29
|
+
- 操作属于创建、生命周期转换、内容写入还是读取;
|
|
30
|
+
- 成功操作对本 Turn outcome 造成的语义变化;
|
|
31
|
+
- 失败操作,但失败不提交成功的状态转换。
|
|
32
|
+
|
|
33
|
+
建议的数据形状为:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
interface UniverTurnProjection {
|
|
37
|
+
readonly turn: number
|
|
38
|
+
readonly files: readonly UniverTurnFileProjection[]
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
interface UniverTurnFileProjection {
|
|
42
|
+
readonly file: string
|
|
43
|
+
readonly operations: readonly UniverTurnOperation[]
|
|
44
|
+
readonly outcome: UniverTurnOutcome
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
interface UniverTurnOperation {
|
|
48
|
+
readonly tool: UniverOperationKind
|
|
49
|
+
readonly action?: string
|
|
50
|
+
readonly worktreeId?: string
|
|
51
|
+
readonly unitId?: string
|
|
52
|
+
readonly phase: 'pending' | 'succeeded' | 'failed'
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
interface UniverTurnOutcome {
|
|
56
|
+
readonly primaryWorktreeId: string | null
|
|
57
|
+
readonly lifecycle: 'trunk' | 'draft' | 'ready' | 'merged' | 'discarded' | 'unchanged'
|
|
58
|
+
readonly preferredUnitId?: string
|
|
59
|
+
readonly changedContent: boolean
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
工具结构化结果必须补齐稳定恢复上述事实所需的标识。Client 不解析自由文本或 bash 输出。
|
|
64
|
+
|
|
65
|
+
### 2.2 Host `FileState`
|
|
66
|
+
|
|
67
|
+
Host 状态查询继续提供:
|
|
68
|
+
|
|
69
|
+
- worktree 当前真实状态;
|
|
70
|
+
- changed Units;
|
|
71
|
+
- Trunk、worktree 和 merge preview 的不透明 Viewer URL。
|
|
72
|
+
|
|
73
|
+
轮询得到的完整 `FileState` 不写入历史 Turn。Turn 投影记录当时发生的操作事实,`FileState` 校准文件现在的真实状态,两者不能混为一种状态。
|
|
74
|
+
|
|
75
|
+
### 2.3 展示模型
|
|
76
|
+
|
|
77
|
+
卡片和浮窗分别使用纯派生器:
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
UniverTurnProjection + FileState
|
|
81
|
+
├── deriveUniverCardModel
|
|
82
|
+
└── deriveUniverFloatingWindowModel
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
卡片模型面向完整 Turn 的稳定结果;浮窗模型面向正在运行 Turn 的增量操作。浮窗当前停留的 scope 不反向修改 Turn outcome。
|
|
86
|
+
|
|
87
|
+
## 3. Turn 操作归约
|
|
88
|
+
|
|
89
|
+
不能用最后一次工具调用直接决定展示。操作分为以下类别独立归约。
|
|
90
|
+
|
|
91
|
+
### 3.1 生命周期操作
|
|
92
|
+
|
|
93
|
+
同一 worktree 的成功生命周期操作按发生顺序转换:
|
|
94
|
+
|
|
95
|
+
| 操作 | Turn outcome |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| `worktree create` | 选择返回的 worktree,进入 `draft` |
|
|
98
|
+
| `worktree reopen` | 选择该 worktree,进入 `draft` |
|
|
99
|
+
| `worktree ready` | 选择该 worktree,进入 `ready` |
|
|
100
|
+
| `worktree merge` | 记录该 worktree 已合入,展示 Trunk |
|
|
101
|
+
| `worktree discard` | 记录该 worktree 已丢弃,展示 Trunk |
|
|
102
|
+
|
|
103
|
+
只有后续成功的生命周期操作可以改变已有生命周期结论。
|
|
104
|
+
|
|
105
|
+
### 3.2 内容写入
|
|
106
|
+
|
|
107
|
+
以下操作选择其显式 worktree、标记内容发生变化,并记录优先 Unit;它们不覆盖已经成功产生的 `ready`、`merged` 或 `discarded` 结论:
|
|
108
|
+
|
|
109
|
+
- `univer_execute`;
|
|
110
|
+
- `univer_import`;
|
|
111
|
+
- `univer_unit create/remove`;
|
|
112
|
+
- `univer_compile_svg`。
|
|
113
|
+
|
|
114
|
+
Host 返回的最终 worktree 状态仍可校准投影预期。例如投影选择了一个 worktree,而 Host 已返回 `ready`,卡片应展示 merge preview。
|
|
115
|
+
|
|
116
|
+
### 3.3 读取操作
|
|
117
|
+
|
|
118
|
+
`univer_status`、`univer_inspect`、`univer_lint` 和 `univer_export` 不覆盖已有生命周期或主要 worktree,只补充 scope、优先 Unit 和操作记录。
|
|
119
|
+
|
|
120
|
+
如果整个 Turn 只有读取操作:
|
|
121
|
+
|
|
122
|
+
- 显式携带 `worktreeId` 时展示该 worktree 的当前状态;
|
|
123
|
+
- 没有 `worktreeId` 时展示 Trunk;
|
|
124
|
+
- 涉及多个 worktree 时,最后一个显式读取 scope 只决定 Viewer 的默认读取目标,不产生生命周期转换。
|
|
125
|
+
|
|
126
|
+
因此 `ready -> inspect -> status` 的 Turn outcome 仍为 `ready`;`inspect` 可以决定优先 Unit,`status` 不能把卡片切回普通 Trunk 预览。
|
|
127
|
+
|
|
128
|
+
## 4. 统一回合尾部卡片
|
|
129
|
+
|
|
130
|
+
每个 `Turn + file` 渲染一张统一卡片。卡片沿用当前审阅卡片布局:
|
|
131
|
+
|
|
132
|
+
- header 中显示文件名、worktree 名称、完整文件路径、状态、全屏和折叠控制;
|
|
133
|
+
- body 中显示 changed Unit chips 和完整 Univer Viewer;
|
|
134
|
+
- 不增加外部操作摘要、scope chips 或底部 action footer;
|
|
135
|
+
- 提交、丢弃和合入操作全部使用 Univer Viewer 内置按钮。
|
|
136
|
+
|
|
137
|
+
Viewer 选择由投影 scope 与权威状态共同决定:
|
|
138
|
+
|
|
139
|
+
| scope / 权威状态 | Viewer |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| Trunk | 当前版本 |
|
|
142
|
+
| `draft` | worktree 页面 |
|
|
143
|
+
| `ready` | merge preview 页面 |
|
|
144
|
+
| `merged` | 合入后的当前版本 |
|
|
145
|
+
| `discarded` | 未受该修改影响的当前版本 |
|
|
146
|
+
| 加载中 | 同一卡片布局内的加载状态 |
|
|
147
|
+
| worktree 不可用 | 同一卡片布局内的不可用状态 |
|
|
148
|
+
|
|
149
|
+
状态加载失败时不得回退旧卡片。一般网络、Gateway 或授权失败仍使用同一卡片表达加载中或不可用;若 Host 以结构化 `INVALID_FILE_PATH` 明确确认文件已不存在,则不渲染卡片。这覆盖 Agent 在同一 Turn 中创建临时 `.univer`、完成排查后再通过 Bash 删除的场景,避免留下永久加载卡片。历史 Turn 也使用同一组件和布局,默认折叠;其 worktree 状态可由当前 `FileState` 校准。若历史卡片允许展开,Viewer 表达的是当前状态,不能表述为历史内容快照。
|
|
150
|
+
|
|
151
|
+
## 5. 实时浮窗
|
|
152
|
+
|
|
153
|
+
### 5.1 主动拉起
|
|
154
|
+
|
|
155
|
+
浮窗只在以下当前 Turn 操作出现时主动拉起:
|
|
156
|
+
|
|
157
|
+
- `univer_new`:立即为文件拉起浮窗;创建完成后展示 Trunk,执行期间展示同一浮窗的加载状态;
|
|
158
|
+
- `univer_worktree create`:成功取得 `worktreeId` 后展示 draft worktree;
|
|
159
|
+
- `univer_worktree reopen`:展示 draft worktree;
|
|
160
|
+
- `univer_execute`;
|
|
161
|
+
- `univer_import`;
|
|
162
|
+
- `univer_unit create/remove`;
|
|
163
|
+
- `univer_compile_svg`;
|
|
164
|
+
- `univer_worktree ready`:展示或切换到 merge preview。
|
|
165
|
+
|
|
166
|
+
以下操作不主动拉起已关闭或尚未出现的浮窗:
|
|
167
|
+
|
|
168
|
+
- `univer_status`;
|
|
169
|
+
- `univer_inspect`;
|
|
170
|
+
- `univer_lint`;
|
|
171
|
+
- `univer_export`。
|
|
172
|
+
|
|
173
|
+
`merge` 与 `discard` 不主动拉起已关闭浮窗。若对应浮窗原本打开,则在 Host 确认终态后关闭。
|
|
174
|
+
|
|
175
|
+
### 5.2 跨 Turn 延续
|
|
176
|
+
|
|
177
|
+
浮窗控制器显式保存用户保持打开的目标,不再通过扫描整个 Session 的所有文件和 worktree 间接推断:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
interface UniverFloatingWindowState {
|
|
181
|
+
readonly openFiles: ReadonlySet<string>
|
|
182
|
+
readonly openWorktrees: ReadonlyMap<string, {
|
|
183
|
+
readonly file: string
|
|
184
|
+
readonly lastStatus: WorktreeStatus
|
|
185
|
+
}>
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
上一轮结束时浮窗可以停止渲染,但保留打开意图。下一轮开始后重新查询对应文件状态:
|
|
190
|
+
|
|
191
|
+
- `draft` 或 `ready` worktree 继续打开;
|
|
192
|
+
- `merged` 或 `discarded` worktree 清除打开意图,不再出现;
|
|
193
|
+
- 查询暂时失败时保留打开意图并等待重试,不能把失败当作终态;
|
|
194
|
+
- `univer_new` 拉起的文件浮窗在没有 worktree 时可继续展示 Trunk;后续创建 worktree 时原位升级到该 worktree。
|
|
195
|
+
|
|
196
|
+
用户手动关闭优先于自动延续。关闭后清除对应打开意图,下一轮不自动恢复;新的 `new`、创建、写入、`reopen` 或 `ready` 操作可以再次拉起。读取操作不能推翻用户的关闭决定。
|
|
197
|
+
|
|
198
|
+
同一 Turn 中同一文件最多保留一个浮窗。新的明确写入或生命周期 scope 更新现有浮窗,不为同一文件叠加多个窗口。
|
|
199
|
+
|
|
200
|
+
## 6. 组件边界
|
|
201
|
+
|
|
202
|
+
目标职责如下:
|
|
203
|
+
|
|
204
|
+
```text
|
|
205
|
+
会话结构化事件
|
|
206
|
+
↓
|
|
207
|
+
univerTurnDefinition
|
|
208
|
+
↓
|
|
209
|
+
UniverTurnProjection ───────────────┐
|
|
210
|
+
│ │
|
|
211
|
+
│ Host FileState
|
|
212
|
+
│ │
|
|
213
|
+
├── FloatingWindowController ─┤
|
|
214
|
+
│ ↓ │
|
|
215
|
+
│ Worktree/File Window │
|
|
216
|
+
│ │
|
|
217
|
+
└── deriveUniverCardModel ────┘
|
|
218
|
+
↓
|
|
219
|
+
UnifiedUniverCard
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
- `univerTurnDefinition`:捕获和归约可回放的 Turn 操作;
|
|
223
|
+
- `FileState` hook:读取当前权威协作状态;
|
|
224
|
+
- `FloatingWindowController`:管理主动拉起、跨 Turn 打开意图、用户关闭和终态清理;
|
|
225
|
+
- card model 派生器:把 Turn 事实与当前状态转换为稳定展示模型;
|
|
226
|
+
- 卡片和浮窗组件:只按模型渲染,不扫描其他 Turn、不推断工具语义、不直接请求 HTTP。
|
|
227
|
+
|
|
228
|
+
## 7. 必须覆盖的验证场景
|
|
229
|
+
|
|
230
|
+
- `ready -> inspect -> status` 仍展示 merge preview;
|
|
231
|
+
- `ready -> reopen -> execute` 展示 draft worktree;
|
|
232
|
+
- `ready -> merge -> status` 展示 Trunk 和已合入状态;
|
|
233
|
+
- `univer_new` 在执行期间拉起文件浮窗,成功后展示空文件 Trunk;
|
|
234
|
+
- 读取操作不会主动拉起已关闭浮窗;
|
|
235
|
+
- 上一轮保持打开的 `draft` 或 `ready` worktree 在下一轮继续显示;
|
|
236
|
+
- 用户手动关闭后,下一轮不会仅因读取操作恢复;
|
|
237
|
+
- 新写入、`reopen` 或 `ready` 可以重新拉起已关闭浮窗;
|
|
238
|
+
- `merged` 与 `discarded` 清除跨 Turn 打开意图;
|
|
239
|
+
- 状态查询失败不会清除打开意图,也不会回退旧卡片;
|
|
240
|
+
- Host 明确确认文件不存在时不渲染对应的回合卡片;
|
|
241
|
+
- 多会话的 Turn 投影、轮询状态和浮窗打开意图互不泄漏;
|
|
242
|
+
- 历史 Turn 使用统一卡片布局,不出现旧预览卡片或单独历史 header;
|
|
243
|
+
- 卡片不渲染 Viewer 已经提供的重复提交、丢弃或合入 footer。
|