@tanzerfe/page-use 0.0.9 → 0.0.11

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.
@@ -0,0 +1,1206 @@
1
+ import { PageAgentConfig } from "page-agent";
2
+ import { z } from "zod/v4";
3
+ import { LitElement, TemplateResult } from "lit";
4
+ //#region src/core/types.d.ts
5
+ /**
6
+ * Page Use 对外类型:菜单结构、能力 API、进度事件、任务结果。
7
+ * 对接方(其它智能体)只需依赖本文件与 capability/ 下的导出。
8
+ */
9
+ /**
10
+ * 宿主导航菜单节点:用于生成站点地图写入系统提示,并据此生成「打开 XX」快捷指令。
11
+ * path 为路由路径(不含 hash 前缀 `#`,前导 `/` 可有可无);有子节点的分组节点可不填 path。
12
+ */
13
+ interface PageUseMenuNode {
14
+ label: string;
15
+ path?: string;
16
+ /** 保留路由但不在导航中展示:模型无法点击到达,不列入站点地图 */
17
+ hidden?: boolean;
18
+ children?: PageUseMenuNode[];
19
+ }
20
+ /**
21
+ * 任务来源标识,用于面板展示、历史记录与日志排查。
22
+ * 约定值:'launcher' 调试面板;其它智能体自行命名(如 'assistant')。
23
+ */
24
+ type PageUseTaskSource = string;
25
+ /** 调用失败原因(任务未真正开始执行时) */
26
+ type PageUseErrorCode =
27
+ /** 未调用 createPageUse,或未配置 LLM 端点 baseURL */
28
+ 'NOT_CONFIGURED' |
29
+ /** 已配置但宿主已销毁(destroy 之后、例如登出) */
30
+ 'NOT_READY' |
31
+ /** 已有任务执行中;同一时刻只允许一个任务操作页面 */
32
+ 'BUSY' |
33
+ /** 指令为空 */
34
+ 'EMPTY_TASK' |
35
+ /** agent 构造或钩子抛出的外部错误 */
36
+ 'AGENT_ERROR';
37
+ /**
38
+ * 任务最终状态:
39
+ * - completed:模型调用 done 且声明成功
40
+ * - failed:模型调用 done 但声明未达成
41
+ * - stopped:被终止(调用方 abort、stop() 或面板「终止」)
42
+ * - error:执行出错(模型异常、超出最大步数等)或未能开始(见 errorCode)
43
+ */
44
+ type PageUseTaskStatus = 'completed' | 'failed' | 'stopped' | 'error';
45
+ interface PageUseStepLog {
46
+ index: number;
47
+ /** 工具名,用于图标与颜色区分;另有 'error' / 'retry' 两个伪工具名表示执行出错与重试 */
48
+ tool: string;
49
+ /** 模型对上一步的评估 */
50
+ evaluation: string;
51
+ /** 模型对下一步的目标描述 */
52
+ goal: string;
53
+ /** 工具名 + 关键入参摘要 */
54
+ action: string;
55
+ output: string;
56
+ /** 该步是否失败(工具返回以 ❌ 开头或出现"失败"字样) */
57
+ failed: boolean;
58
+ }
59
+ interface PageUseTaskResult {
60
+ /** 本次任务 ID;未能开始时为空串 */
61
+ taskId: string;
62
+ task: string;
63
+ source: PageUseTaskSource;
64
+ status: PageUseTaskStatus;
65
+ /** 等价于 status === 'completed' */
66
+ success: boolean;
67
+ /** 模型给出的结论,或失败原因 */
68
+ summary: string;
69
+ /** 仅在任务未能开始或外部错误时有值 */
70
+ errorCode?: PageUseErrorCode;
71
+ steps: PageUseStepLog[];
72
+ tokens: number;
73
+ durationMs: number;
74
+ }
75
+ /** 进度事件:run() 的 onProgress 只收到本任务事件;subscribe() 收到全部任务事件 */
76
+ type PageUseProgressEvent = ({
77
+ type: 'started';
78
+ taskId: string;
79
+ task: string;
80
+ source: PageUseTaskSource;
81
+ } | {
82
+ type: 'activity';
83
+ taskId: string;
84
+ text: string;
85
+ } | {
86
+ type: 'step';
87
+ taskId: string;
88
+ step: PageUseStepLog;
89
+ } | {
90
+ type: 'question';
91
+ taskId: string;
92
+ question: string;
93
+ } | {
94
+ type: 'finished';
95
+ taskId: string;
96
+ result: PageUseTaskResult;
97
+ }) & {
98
+ silent?: boolean;
99
+ };
100
+ interface PageUseRunOptions {
101
+ /** 任务来源,默认 'unknown' */
102
+ source?: PageUseTaskSource;
103
+ /** 中断信号:abort 后任务以 stopped 结束 */
104
+ signal?: AbortSignal;
105
+ onProgress?: (event: PageUseProgressEvent) => void;
106
+ /**
107
+ * 模型向用户提问(ask_user 工具)时的回答方式。
108
+ * 不传时:调试面板已挂载则由面板作答;否则自动回复「无法补充信息」让模型自行决策或结束。
109
+ */
110
+ onAskUser?: (question: string) => Promise<string>;
111
+ /**
112
+ * 页面讲解风格 key(如 'user'、'trainer'),仅影响「介绍当前页面」类任务的讲解方式。
113
+ * 优先级:本参数 > 面板设置 > pageTour.defaultStyle;不存在的 key 忽略。
114
+ */
115
+ tourStyle?: string;
116
+ }
117
+ /** 能力状态快照(非响应式) */
118
+ interface PageUseSnapshot {
119
+ /** 已配置端点且宿主未销毁,可立即接收任务 */
120
+ ready: boolean;
121
+ running: boolean;
122
+ taskId: string;
123
+ task: string;
124
+ source: PageUseTaskSource;
125
+ activity: string;
126
+ steps: number;
127
+ }
128
+ /** 快捷指令:label 为按钮文字,task 为下达的完整指令 */
129
+ interface PageUsePreset {
130
+ label: string;
131
+ task: string;
132
+ /** 执行该快捷指令时使用的讲解风格 key,如 { label: '介绍当前页面(培训)', task: '介绍当前页面', tourStyle: 'trainer' } */
133
+ tourStyle?: string;
134
+ }
135
+ //#endregion
136
+ //#region src/flow/types.d.ts
137
+ declare const FLOW_SCHEMA_VERSION: "1";
138
+ declare const FLOW_BUNDLE_VERSION: "1";
139
+ /** 沿用现有面板定义,由宿主声明,不根据 UA 或视口自动切换。 */
140
+ type FlowClient = 'desktop' | 'mobile';
141
+ type FlowMode = 'local' | 'cloud';
142
+ type JsonValue = null | boolean | number | string | JsonValue[] | {
143
+ [key: string]: JsonValue;
144
+ };
145
+ type JsonObject = {
146
+ [key: string]: JsonValue;
147
+ };
148
+ type FlowErrorCode = 'INVALID_SCENE' | 'UNSUPPORTED_SCHEMA' | 'CLIENT_MISMATCH' | 'BINDING_UNAVAILABLE' | 'INVALID_INPUT' | 'INVALID_REFERENCE' | 'CONFLICT' | 'STORAGE_UNAVAILABLE' | 'DEPENDENCY_MISSING' | 'UNAUTHORIZED' | 'EXPIRED' | 'CLOUD_UNAVAILABLE' | 'ACTION_FAILED' | 'READY_TIMEOUT' | 'TARGET_NOT_FOUND' | 'KNOWLEDGE_UNAVAILABLE' | 'BUSY' | 'STOPPED' | 'DESTROYED' | 'PAGE_MISMATCH' | 'CONTEXT_MISMATCH' | 'REGION_AMBIGUOUS' | 'REGION_TIMEOUT' | 'REGION_SELECTION_INVALID' | 'CHECK_UNCERTAIN';
149
+ declare class FlowError extends Error {
150
+ readonly code: FlowErrorCode;
151
+ readonly path?: string | undefined;
152
+ constructor(code: FlowErrorCode, message: string, path?: string | undefined);
153
+ }
154
+ interface FlowInputDefinition {
155
+ type: 'string' | 'number' | 'boolean';
156
+ label?: string;
157
+ required?: boolean;
158
+ default?: string | number | boolean;
159
+ }
160
+ interface FlowOutputReference {
161
+ fromOutput: {
162
+ stepId: string;
163
+ actionId: string;
164
+ path?: string;
165
+ };
166
+ }
167
+ type FlowParameter = JsonValue | {
168
+ fromInput: string;
169
+ } | FlowOutputReference;
170
+ interface FlowAction {
171
+ id: string;
172
+ /** 使用者直接填写的页面操作指令,{{参数名}} 引用启动参数或操作参数。 */
173
+ task?: string;
174
+ effect?: FlowActionBinding['effect'];
175
+ repeatable?: boolean;
176
+ /** 兼容已有场景的宿主绑定;新建操作直接使用 task。 */
177
+ ref?: string;
178
+ params?: Record<string, FlowParameter>;
179
+ }
180
+ interface FlowCheckOptions {
181
+ params?: Record<string, FlowParameter>;
182
+ timeoutMs?: number;
183
+ pollIntervalMs?: number;
184
+ }
185
+ interface FlowBoundCheck extends FlowCheckOptions {
186
+ ref: string;
187
+ description?: never;
188
+ pageId?: never;
189
+ }
190
+ interface FlowDescriptionCheck extends FlowCheckOptions {
191
+ pageId: string;
192
+ description: string;
193
+ ref?: never;
194
+ }
195
+ /** 描述与绑定二选一;ready 缺省使用空数组,不要求注册检查。 */
196
+ type FlowCheck = FlowBoundCheck | FlowDescriptionCheck;
197
+ interface FlowSegment {
198
+ id: string;
199
+ /** 缺省仅讲解;定义随段落存储,DOM 仅在本次定位中产生。 */
200
+ region?: FlowRegion;
201
+ baseText: string;
202
+ requiredPoints?: string[];
203
+ lockedPhrases?: string[];
204
+ knowledgeRefs?: string[];
205
+ contextRefs?: string[];
206
+ allowPolish?: boolean;
207
+ }
208
+ interface FlowStep {
209
+ id: string;
210
+ name: string;
211
+ required?: boolean;
212
+ advance?: 'auto' | 'manual';
213
+ actions: FlowAction[];
214
+ ready: FlowCheck[];
215
+ segments: FlowSegment[];
216
+ }
217
+ interface FlowScene {
218
+ schemaVersion: typeof FLOW_SCHEMA_VERSION;
219
+ id: string;
220
+ name: string;
221
+ revision: string;
222
+ client: FlowClient;
223
+ variantId: string;
224
+ bindingSet: string;
225
+ description?: string;
226
+ inputs?: Record<string, FlowInputDefinition>;
227
+ /** 发布时固定本地知识版本;外部知识同样按此版本解析。 */
228
+ knowledgeVersions?: Record<string, string>;
229
+ completion?: 'keep-current' | 'restore';
230
+ steps: FlowStep[];
231
+ metadata?: JsonObject;
232
+ }
233
+ interface FlowContext {
234
+ sessionId: string;
235
+ scene: FlowScene;
236
+ input: JsonObject;
237
+ /** 按步骤、动作隔离,只有绑定声明的 outputPaths 可被后续引用。 */
238
+ outputs: Record<string, Record<string, JsonValue>>;
239
+ signal: AbortSignal;
240
+ runTask(task: string, options?: PageUseRunOptions): Promise<PageUseTaskResult>;
241
+ }
242
+ interface FlowParameterDefinition extends FlowInputDefinition {
243
+ description?: string;
244
+ }
245
+ interface FlowActionBinding {
246
+ label: string;
247
+ description?: string;
248
+ /** write 为修改业务数据,必须由宿主开放并取得使用者确认。 */
249
+ effect: 'view' | 'query' | 'write';
250
+ repeatable?: boolean;
251
+ params?: Record<string, FlowParameterDefinition>;
252
+ outputPaths?: string[];
253
+ execute(params: JsonObject, context: FlowContext): Promise<JsonValue | void>;
254
+ }
255
+ interface FlowCheckBinding {
256
+ label: string;
257
+ params?: Record<string, FlowParameterDefinition>;
258
+ check(params: JsonObject, context: FlowContext): Promise<boolean | {
259
+ ready: boolean;
260
+ reason?: string;
261
+ }>;
262
+ }
263
+ interface FlowResolvedTarget {
264
+ root: Element;
265
+ anchor?: Element;
266
+ }
267
+ type FlowRegionAnchor = {
268
+ kind: 'attribute';
269
+ attribute: 'data-page-use-region' | 'data-flow-target' | 'id';
270
+ value: string;
271
+ } | {
272
+ kind: 'semantic';
273
+ role: string;
274
+ name: string;
275
+ containerName?: string;
276
+ } | {
277
+ kind: 'dom';
278
+ path: Array<{
279
+ tag: string;
280
+ index: number;
281
+ shadow?: boolean;
282
+ }>;
283
+ };
284
+ interface FlowRegion {
285
+ name: string;
286
+ pageId: string;
287
+ description: string;
288
+ anchor?: FlowRegionAnchor;
289
+ /** 未设置时只核验页面与区域,不承诺同一业务记录。 */
290
+ contextMatch?: Record<string, FlowParameter>;
291
+ }
292
+ interface FlowRegionPage {
293
+ id: string;
294
+ label: string;
295
+ }
296
+ interface FlowRegionContext {
297
+ pageId: string;
298
+ ready: boolean;
299
+ record?: JsonObject;
300
+ /** 当前内容及 teleport 根;不得返回隐藏的 KeepAlive 页面。 */
301
+ roots?: Element[];
302
+ }
303
+ interface FlowRegionHost {
304
+ /** 包内默认模式只在当前 DOM 定位,无需选择路由或接入页面目录。 */
305
+ scope?: 'current-page';
306
+ listPages(client: FlowClient, signal: AbortSignal): Promise<FlowRegionPage[]>;
307
+ getContext(client: FlowClient, signal: AbortSignal): Promise<FlowRegionContext>;
308
+ canAccess(pageId: string, client: FlowClient, signal: AbortSignal): Promise<boolean>;
309
+ }
310
+ interface FlowRegionCandidate {
311
+ /** 仅本次快照有效,不持久化。 */
312
+ id: string;
313
+ name: string;
314
+ role: string;
315
+ containerName?: string;
316
+ summary: string;
317
+ }
318
+ type FlowRegionSelector = (request: {
319
+ description: string;
320
+ candidates: FlowRegionCandidate[];
321
+ sessionId: string;
322
+ }, signal: AbortSignal) => Promise<string | null>;
323
+ interface FlowCompletionDecision {
324
+ ready: boolean | null;
325
+ reason?: string;
326
+ }
327
+ type FlowCompletionEvaluator = (request: {
328
+ description: string;
329
+ pageId: string;
330
+ candidates: FlowRegionCandidate[];
331
+ record?: JsonObject;
332
+ sessionId: string;
333
+ }, signal: AbortSignal) => Promise<FlowCompletionDecision>;
334
+ interface FlowRegionFailure {
335
+ name: string;
336
+ pageId: string;
337
+ code: FlowErrorCode;
338
+ reason: string;
339
+ canReselect: boolean;
340
+ canContinueWithoutRegion: boolean;
341
+ }
342
+ interface FlowContextBinding {
343
+ label: string;
344
+ resolve(context: FlowContext): JsonValue | Promise<JsonValue>;
345
+ }
346
+ interface FlowBindings {
347
+ id: string;
348
+ /** 面向业务维护者的显示名称;id 继续用于协议校验和存储隔离。 */
349
+ label?: string;
350
+ actions: Record<string, FlowActionBinding>;
351
+ checks: Record<string, FlowCheckBinding>;
352
+ contexts?: Record<string, FlowContextBinding>;
353
+ restore?: (context: FlowContext) => Promise<void>;
354
+ }
355
+ interface FlowKnowledge {
356
+ id: string;
357
+ name: string;
358
+ text: string;
359
+ revision: string;
360
+ source?: string;
361
+ }
362
+ interface FlowScope {
363
+ appId: string;
364
+ workspaceId: string;
365
+ userScope: string;
366
+ client: FlowClient;
367
+ bindingSet: string;
368
+ }
369
+ interface FlowSceneRecord {
370
+ key: string;
371
+ draft: FlowScene;
372
+ version: number;
373
+ source: FlowMode;
374
+ revisions: FlowScene[];
375
+ publishedRevision?: string;
376
+ cloudRevision?: string;
377
+ updatedAt: number;
378
+ }
379
+ interface FlowKnowledgeRecord {
380
+ draft: FlowKnowledge;
381
+ version: number;
382
+ revisions: FlowKnowledge[];
383
+ publishedRevision?: string;
384
+ source?: FlowMode;
385
+ cloudRevision?: string;
386
+ updatedAt: number;
387
+ }
388
+ interface FlowPermissions {
389
+ execute: boolean;
390
+ edit: boolean;
391
+ publish: boolean;
392
+ delete: boolean;
393
+ }
394
+ interface FlowIdentity {
395
+ appId: string;
396
+ /** 中台返回的完整空间范围,跨租户/组织不能复用相同的范围标识。 */
397
+ workspaceId: string;
398
+ userId: string;
399
+ /** 稳定的逻辑登录会话标识,不是 token,不随凭证续期变化。 */
400
+ sessionId: string;
401
+ permissions: FlowPermissions;
402
+ }
403
+ interface FlowCloudRelease {
404
+ scene: FlowScene;
405
+ knowledge: FlowKnowledge[];
406
+ permissions?: Partial<FlowPermissions>;
407
+ }
408
+ interface FlowCloudCache {
409
+ identity: FlowIdentity;
410
+ viewId: string;
411
+ catalogVersion: string;
412
+ /** UTC Unix 毫秒,与客户端 Date.now() 比较。 */
413
+ validUntil: number;
414
+ offlineAllowed: boolean;
415
+ releases: FlowCloudRelease[];
416
+ }
417
+ interface FlowTombstone {
418
+ kind: 'scene' | 'knowledge';
419
+ key: string;
420
+ baseRevision?: string;
421
+ operationId: string;
422
+ }
423
+ interface FlowRepositorySnapshot {
424
+ version: number;
425
+ scenes: FlowSceneRecord[];
426
+ knowledge: FlowKnowledgeRecord[];
427
+ cloud?: FlowCloudCache;
428
+ tombstones: FlowTombstone[];
429
+ runs: FlowRunResult[];
430
+ /** 成功确认前持久保留操作 ID,跨刷新重试不会重复云端写入。 */
431
+ pendingOperations?: Array<{
432
+ key: string;
433
+ operationId: string;
434
+ }>;
435
+ }
436
+ interface FlowRepository {
437
+ readonly scope: FlowScope;
438
+ read(): Promise<FlowRepositorySnapshot>;
439
+ /** 同步 mutation 在单次读写事务内执行,不允许返回 Promise。 */
440
+ transact<T>(mutation: (snapshot: FlowRepositorySnapshot) => T): Promise<T>;
441
+ listScenes(): Promise<FlowSceneRecord[]>;
442
+ getScene(key: string): Promise<FlowSceneRecord | undefined>;
443
+ saveSceneDraft(scene: FlowScene, expectedVersion?: number, source?: FlowMode): Promise<FlowSceneRecord>;
444
+ publishScene(key: string, expectedVersion: number): Promise<FlowScene>;
445
+ disableScene(key: string, expectedVersion: number): Promise<void>;
446
+ deleteScene(key: string, expectedVersion: number): Promise<void>;
447
+ listKnowledge(): Promise<FlowKnowledgeRecord[]>;
448
+ saveKnowledge(knowledge: FlowKnowledge, expectedVersion?: number, source?: FlowMode): Promise<FlowKnowledgeRecord>;
449
+ publishKnowledge(id: string, expectedVersion: number): Promise<FlowKnowledge>;
450
+ deleteKnowledge(id: string, expectedVersion: number): Promise<void>;
451
+ close(): void;
452
+ }
453
+ interface FlowBundle {
454
+ bundleVersion: typeof FLOW_BUNDLE_VERSION;
455
+ exportedAt: string;
456
+ appId: string;
457
+ scenes: FlowSceneRecord[];
458
+ knowledge: FlowKnowledgeRecord[];
459
+ }
460
+ interface FlowImportPreview {
461
+ bundle: FlowBundle;
462
+ repositoryVersion: number;
463
+ sceneConflicts: string[];
464
+ knowledgeConflicts: string[];
465
+ warnings: string[];
466
+ }
467
+ type FlowImportStrategy = 'keep-local' | 'use-import' | 'copy';
468
+ interface FlowExportOptions {
469
+ sceneKeys?: string[];
470
+ includeDrafts?: boolean;
471
+ }
472
+ interface FlowSessionContext {
473
+ appId: string;
474
+ workspaceId?: string;
475
+ userId?: string;
476
+ [key: string]: JsonValue | undefined;
477
+ }
478
+ interface FlowConfigResponse {
479
+ viewId: string;
480
+ catalogVersion: string;
481
+ kind: 'full' | 'delta';
482
+ /** UTC Unix 毫秒,有效期到达后不能继续使用授权。 */
483
+ validUntil: number;
484
+ offlineAllowed?: boolean;
485
+ releases: FlowCloudRelease[];
486
+ removedSceneKeys?: string[];
487
+ /** 内容升级不撤销旧会话;明确撤销的版本才阻止其继续。 */
488
+ revokedRevisions?: Array<{
489
+ key: string;
490
+ revision: string;
491
+ }>;
492
+ permissions?: FlowPermissions;
493
+ }
494
+ interface FlowCloudAdapter {
495
+ /** 直接维护接口返回完整清单;缺失的未修改中台条目从本地视图移除。 */
496
+ managedListsAreComplete?: boolean;
497
+ resolveSession(context: FlowSessionContext, signal: AbortSignal): Promise<FlowIdentity>;
498
+ pullConfig(request: {
499
+ identity: FlowIdentity;
500
+ client: FlowClient;
501
+ bindingSet: string;
502
+ schemaVersion: typeof FLOW_SCHEMA_VERSION;
503
+ catalogVersion?: string;
504
+ }, signal: AbortSignal): Promise<FlowConfigResponse>;
505
+ pullManagedScenes?(identity: FlowIdentity, signal: AbortSignal): Promise<FlowScene[]>;
506
+ pullManagedKnowledge?(identity: FlowIdentity, signal: AbortSignal): Promise<FlowKnowledge[]>;
507
+ saveDraft?(request: {
508
+ identity: FlowIdentity;
509
+ scene: FlowScene;
510
+ baseRevision?: string;
511
+ operationId: string;
512
+ }, signal: AbortSignal): Promise<{
513
+ revision: string;
514
+ scene?: FlowScene;
515
+ }>;
516
+ publishRevision?(request: {
517
+ identity: FlowIdentity;
518
+ key: string;
519
+ revision: string;
520
+ operationId: string;
521
+ }, signal: AbortSignal): Promise<{
522
+ status: 'published' | 'pending';
523
+ release?: FlowCloudRelease;
524
+ }>;
525
+ deleteScene?(request: {
526
+ identity: FlowIdentity;
527
+ key: string;
528
+ baseRevision?: string;
529
+ operationId: string;
530
+ }, signal: AbortSignal): Promise<void>;
531
+ saveKnowledge?(request: {
532
+ identity: FlowIdentity;
533
+ knowledge: FlowKnowledge;
534
+ baseRevision?: string;
535
+ operationId: string;
536
+ }, signal: AbortSignal): Promise<{
537
+ revision: string;
538
+ knowledge?: FlowKnowledge;
539
+ }>;
540
+ publishKnowledge?(request: {
541
+ identity: FlowIdentity;
542
+ id: string;
543
+ revision: string;
544
+ operationId: string;
545
+ }, signal: AbortSignal): Promise<{
546
+ status: 'published' | 'pending';
547
+ knowledge?: FlowKnowledge;
548
+ }>;
549
+ deleteKnowledge?(request: {
550
+ identity: FlowIdentity;
551
+ id: string;
552
+ baseRevision?: string;
553
+ operationId: string;
554
+ }, signal: AbortSignal): Promise<void>;
555
+ }
556
+ /** 六接口接入使用业务已有请求信封;code=0 成功,401/403/409 分别为登录、权限、并发冲突。 */
557
+ interface FlowApiResponse<T = unknown> {
558
+ code: number;
559
+ message?: string;
560
+ data: T;
561
+ }
562
+ type FlowApiRequest = (url: string, options: {
563
+ method: 'POST';
564
+ data: Record<string, unknown>;
565
+ signal: AbortSignal;
566
+ }) => Promise<FlowApiResponse>;
567
+ interface FlowApiSyncOptions {
568
+ endpoints: {
569
+ scenes: string;
570
+ saveScene: string;
571
+ deleteScene: string;
572
+ knowledge: string;
573
+ saveKnowledge: string;
574
+ deleteKnowledge: string;
575
+ };
576
+ /** 复用业务当前登录身份,无需额外的身份接口;切换登录范围后调用 refreshSession。 */
577
+ getIdentity(context: FlowSessionContext, signal: AbortSignal): FlowIdentity | Promise<FlowIdentity>;
578
+ /** 缺省使用同源 fetch;自定义请求须返回业务信封,并沿用现有鉴权。 */
579
+ request?: FlowApiRequest;
580
+ refresh?: 'manual' | 'on-session-change';
581
+ }
582
+ interface FlowCloudState {
583
+ status: 'idle' | 'syncing' | 'ready' | 'error';
584
+ identity?: FlowIdentity;
585
+ error?: string;
586
+ errorCode?: FlowErrorCode;
587
+ updatedAt?: number;
588
+ }
589
+ interface FlowCloudController {
590
+ refresh(): Promise<void>;
591
+ getState(): FlowCloudState;
592
+ subscribe(listener: (state: FlowCloudState) => void): () => void;
593
+ getRepository(): Promise<FlowRepository>;
594
+ getRelease(key: string): Promise<FlowCloudRelease>;
595
+ saveDraft(key: string): Promise<void>;
596
+ publish(key: string): Promise<'published' | 'pending'>;
597
+ deleteScene(key: string): Promise<void>;
598
+ saveKnowledge(id: string): Promise<void>;
599
+ publishKnowledge(id: string): Promise<'published' | 'pending'>;
600
+ deleteKnowledge(id: string): Promise<void>;
601
+ stop(): void;
602
+ }
603
+ type FlowStatus = 'idle' | 'running' | 'waiting' | 'paused' | 'completed' | 'partial' | 'failed' | 'stopped';
604
+ interface FlowSegmentLog {
605
+ stepId: string;
606
+ segmentId: string;
607
+ text: string;
608
+ fallbackReason?: string;
609
+ regionSkippedReason?: string;
610
+ }
611
+ interface FlowRunResult {
612
+ sessionId: string;
613
+ sceneId: string;
614
+ revision: string;
615
+ client: FlowClient;
616
+ /** partial 表示演示已结束,但使用者主动越过了未完成的必选步骤。 */
617
+ status: 'completed' | 'partial' | 'failed' | 'stopped';
618
+ completedSteps: string[];
619
+ skippedSteps: string[];
620
+ segments: FlowSegmentLog[];
621
+ durationMs: number;
622
+ error?: string;
623
+ errorCode?: FlowErrorCode;
624
+ }
625
+ interface FlowSnapshot {
626
+ status: FlowStatus;
627
+ sessionId?: string;
628
+ sceneId?: string;
629
+ /** 启动时固定的场景名称,不随目录或草稿修改。 */
630
+ sceneName?: string;
631
+ revision?: string;
632
+ stepId?: string;
633
+ stepName?: string;
634
+ /** false 表示当前环节可选;未进入环节时不提供。 */
635
+ stepRequired?: boolean;
636
+ segmentId?: string;
637
+ text?: string;
638
+ stepIndex: number;
639
+ totalSteps: number;
640
+ reason?: string;
641
+ errorCode?: FlowErrorCode;
642
+ regionFailure?: FlowRegionFailure;
643
+ /** 正在中止旧步骤,期间不接受重复的步骤切换。 */
644
+ switchingStep?: boolean;
645
+ result?: FlowRunResult;
646
+ }
647
+ interface FlowEvent {
648
+ type: 'state' | 'segment' | 'finished';
649
+ snapshot: FlowSnapshot;
650
+ segment?: FlowSegmentLog;
651
+ result?: FlowRunResult;
652
+ }
653
+ interface FlowRunOptions {
654
+ input?: JsonObject;
655
+ signal?: AbortSignal;
656
+ onEvent?: (event: FlowEvent) => void;
657
+ /** 试讲只通过有权限的管理入口开放,云端正式运行仍须检查发布授权。 */
658
+ preview?: boolean;
659
+ }
660
+ interface FlowRunner {
661
+ run(scene: FlowScene, options?: FlowRunOptions): Promise<FlowRunResult>;
662
+ pause(): void;
663
+ resume(): void;
664
+ stop(): Promise<void>;
665
+ replayCurrent(): void;
666
+ skipStep(): void;
667
+ /** 主动结束当前步骤并进入下一步;未完成内容计入 skippedSteps。 */
668
+ nextStep(): Promise<void>;
669
+ /** 返回上一环节并重播;已完成且不可重复的修改操作不会再次提交。 */
670
+ previousStep(): Promise<void>;
671
+ retryRegion(): void;
672
+ reselectRegion(region: FlowRegion): void;
673
+ continueWithoutRegion(): void;
674
+ getSnapshot(): FlowSnapshot;
675
+ subscribe(listener: (event: FlowEvent) => void): () => void;
676
+ }
677
+ interface FlowExecutionPorts {
678
+ acquire(owner: symbol, stop: () => Promise<void>): () => void;
679
+ runTask(owner: symbol, task: string, options?: PageUseRunOptions): Promise<PageUseTaskResult>;
680
+ stopTask(owner: symbol): Promise<void>;
681
+ }
682
+ type FlowGenerator = (request: {
683
+ segment: FlowSegment;
684
+ knowledge: FlowKnowledge[];
685
+ facts: JsonObject;
686
+ context: FlowContext;
687
+ }, signal: AbortSignal) => Promise<string>;
688
+ type FlowPresenter = (target: FlowResolvedTarget | null, text: string, signal: AbortSignal) => Promise<void>;
689
+ interface FlowManagerState {
690
+ loading: boolean;
691
+ error?: string;
692
+ permissions: FlowPermissions;
693
+ cloud?: FlowCloudState;
694
+ }
695
+ interface FlowManager {
696
+ readonly mode: FlowMode;
697
+ /** 六接口模式保存即同步,不提供独立的中台发布入口。 */
698
+ readonly cloudPublishing?: boolean;
699
+ readonly client: FlowClient;
700
+ readonly bindings: FlowBindings;
701
+ /** 另一端仅用于编辑和发布,不能使当前运行端执行其页面能力。 */
702
+ getBindings?(client: FlowClient): FlowBindings | undefined;
703
+ listRegionPages?(client: FlowClient, signal: AbortSignal): Promise<FlowRegionPage[]>;
704
+ previewRegion?(scene: FlowScene, region: FlowRegion, input: JsonObject, signal: AbortSignal): Promise<FlowResolvedTarget>;
705
+ getState(): FlowManagerState;
706
+ subscribe(listener: (state: FlowManagerState) => void): () => void;
707
+ getRepository(): Promise<FlowRepository>;
708
+ listScenes(): Promise<FlowSceneRecord[]>;
709
+ saveSceneDraft(scene: FlowScene, expectedVersion?: number): Promise<FlowSceneRecord>;
710
+ publishScene(key: string, expectedVersion: number): Promise<FlowScene>;
711
+ disableScene(key: string, expectedVersion: number): Promise<void>;
712
+ deleteScene(key: string, expectedVersion: number): Promise<void>;
713
+ listKnowledge(): Promise<FlowKnowledgeRecord[]>;
714
+ saveKnowledge(knowledge: FlowKnowledge, expectedVersion?: number): Promise<FlowKnowledgeRecord>;
715
+ publishKnowledge(id: string, expectedVersion: number): Promise<FlowKnowledge>;
716
+ deleteKnowledge(id: string, expectedVersion: number): Promise<void>;
717
+ exportBundle(options?: FlowExportOptions): Promise<FlowBundle>;
718
+ previewImport(bundle: unknown): Promise<FlowImportPreview>;
719
+ importBundle(preview: FlowImportPreview, strategy: FlowImportStrategy): Promise<void>;
720
+ refresh(): Promise<void>;
721
+ saveCloudDraft(key: string): Promise<void>;
722
+ publishCloud(key: string): Promise<'published' | 'pending'>;
723
+ deleteCloudScene(key: string): Promise<void>;
724
+ saveCloudKnowledge(id: string): Promise<void>;
725
+ publishCloudKnowledge(id: string): Promise<'published' | 'pending'>;
726
+ deleteCloudKnowledge(id: string): Promise<void>;
727
+ }
728
+ interface PageUseFlowHandle extends FlowRunner {
729
+ readonly manager: FlowManager;
730
+ readonly client: FlowClient;
731
+ readonly mode: FlowMode;
732
+ readonly regionHost?: FlowRegionHost;
733
+ runScene(sceneIdOrKey: string, options?: FlowRunOptions): Promise<FlowRunResult>;
734
+ refreshSession(): Promise<void>;
735
+ destroy(): void;
736
+ }
737
+ interface PageUseFlowOptions {
738
+ mode?: FlowMode;
739
+ client: FlowClient;
740
+ bindings: FlowBindings;
741
+ managementBindings?: Partial<Record<FlowClient, FlowBindings>>;
742
+ storage: {
743
+ scope: {
744
+ appId: string;
745
+ workspaceId: string;
746
+ userScope: string;
747
+ };
748
+ /** 测试及特殊宿主可注入 IDBFactory,运行期默认浏览器原生实例。 */
749
+ factory?: IDBFactory;
750
+ namePrefix?: string;
751
+ };
752
+ sync?: FlowApiSyncOptions;
753
+ getSessionContext?: () => FlowSessionContext | Promise<FlowSessionContext>;
754
+ resolveExternalKnowledge?: (ref: string, revision: string, context: FlowContext) => Promise<FlowKnowledge>;
755
+ generateSpeech?: FlowGenerator;
756
+ /** 默认使用包内当前页面 DOM 点选;可覆盖为带页面/IAM 校验的业务适配。点选仅支持桌面端。 */
757
+ regionHost?: FlowRegionHost;
758
+ selectRegionCandidate?: FlowRegionSelector;
759
+ evaluateCompletionCheck?: FlowCompletionEvaluator;
760
+ allowedEffects?: Array<FlowActionBinding['effect']>;
761
+ confirmAction?: (action: FlowAction, context: FlowContext) => Promise<boolean>;
762
+ }
763
+ //#endregion
764
+ //#region src/flow/validation.d.ts
765
+ /** 与现有逐段播报限制兼容;长稿拆分为多段,不在播放时静默截断。 */
766
+ declare const FLOW_SEGMENT_MAX_CHARS = 300;
767
+ declare function newRevision(): string;
768
+ declare function sceneKey(scene: Pick<FlowScene, 'id' | 'client' | 'variantId'>): string;
769
+ declare function scopeKey(scope: FlowScope): string;
770
+ declare function parseFlowScene(value: unknown): FlowScene;
771
+ declare function parseFlowSceneDraft(value: unknown): FlowScene;
772
+ declare function parseFlowKnowledge(value: unknown): FlowKnowledge;
773
+ declare function parseFlowBundle(value: unknown): FlowBundle;
774
+ declare function validateSceneBindings(scene: FlowScene, bindings: FlowBindings, currentClient: FlowScene['client']): void;
775
+ declare function validateFlowInputs(scene: FlowScene, values?: JsonObject): JsonObject;
776
+ declare function parseFlowRegion(value: unknown): FlowRegion;
777
+ //#endregion
778
+ //#region src/flow/ui/manager.d.ts
779
+ declare const PAGE_USE_MANAGER_TAG = "tz-page-use-manager";
780
+ /** 管理表单与面向使用者的正式场景目录共用当前流程句柄。 */
781
+ type PageUseManagerPresentation = 'manager' | 'scenarios';
782
+ declare class PageUseManagerElement extends LitElement {
783
+ static styles: import("lit").CSSResult;
784
+ private _flow?;
785
+ private _presentation;
786
+ private unsubscribeManager?;
787
+ private unsubscribeFlow?;
788
+ private unsubscribePageState?;
789
+ private headerObserver?;
790
+ private observedHeader?;
791
+ private generation;
792
+ private lifecycle;
793
+ private picker?;
794
+ private pages;
795
+ private pagesClient?;
796
+ private pagesController?;
797
+ private previewController?;
798
+ private identityKey?;
799
+ private hiddenSessionId?;
800
+ private managerState?;
801
+ private scenes;
802
+ private knowledge;
803
+ private loading;
804
+ private busy;
805
+ private _error;
806
+ private errorNotice;
807
+ private errorSource;
808
+ private errorTimer?;
809
+ private get error();
810
+ private set error(value);
811
+ private get currentError();
812
+ private get visibleError();
813
+ private syncErrorNotice;
814
+ private _notice;
815
+ private noticeTimer?;
816
+ private get notice();
817
+ private set notice(value);
818
+ private conflict;
819
+ private view;
820
+ private page;
821
+ private advancedText?;
822
+ private advancedInvalid;
823
+ private jsonExpanded;
824
+ private jsonCopyState;
825
+ private jsonCopyToken;
826
+ private jsonCopyTimer?;
827
+ private search;
828
+ private scene?;
829
+ private record?;
830
+ /** -1 表示所有步骤收起,展开状态不写入场景配置。 */
831
+ private selectedStep;
832
+ private knowledgeDraft?;
833
+ private knowledgeRecord?;
834
+ private dirty;
835
+ private pendingNavigation?;
836
+ private deleteConfirm?;
837
+ private runInput;
838
+ private snapshot;
839
+ private importPreview?;
840
+ private importStrategy;
841
+ private exportScope;
842
+ private bundleText;
843
+ private executionKey?;
844
+ private executionInput;
845
+ private startingScene;
846
+ get presentation(): PageUseManagerPresentation;
847
+ set presentation(value: PageUseManagerPresentation);
848
+ /** 设置页知识库入口复用管理页,不绕过未保存内容确认。 */
849
+ openKnowledge(): void;
850
+ /** 每次重新进入管理页默认显示场景;跨标签仍遵循未保存内容确认。 */
851
+ openSceneManager(): void;
852
+ private switchPresentation;
853
+ get flow(): PageUseFlowHandle | undefined;
854
+ set flow(value: PageUseFlowHandle | undefined);
855
+ connectedCallback(): void;
856
+ disconnectedCallback(): void;
857
+ protected updated(): void;
858
+ private attach;
859
+ private detach;
860
+ private getIdentityKey;
861
+ private load;
862
+ private get canEdit();
863
+ private get canPublish();
864
+ private get canSave();
865
+ private isSaved;
866
+ private get canDelete();
867
+ private get canDeleteScene();
868
+ private get canDeleteKnowledge();
869
+ private get disabled();
870
+ private get regionPickDisabledReason();
871
+ private get editingBindings();
872
+ private get catalogCompatible();
873
+ private navigate;
874
+ private discardAndNavigate;
875
+ private changeView;
876
+ private selectScene;
877
+ private createScene;
878
+ private edit;
879
+ private perform;
880
+ private sceneForEditing;
881
+ private previewScene;
882
+ private saveScene;
883
+ private saveAndNavigate;
884
+ private reloadCurrent;
885
+ private control;
886
+ private defaultInput;
887
+ private validRunInput;
888
+ private field;
889
+ private flushTextFields;
890
+ protected render(): TemplateResult;
891
+ private renderWarnings;
892
+ private get businessScenes();
893
+ private selectBusinessScene;
894
+ private renderBusinessScenes;
895
+ private refreshBusinessScenes;
896
+ private startBusinessScene;
897
+ private renderScenes;
898
+ private renderListSkeleton;
899
+ private renderSceneEditor;
900
+ private renderBasic;
901
+ private changeEditorPage;
902
+ private renderAdvanced;
903
+ private copySceneJSON;
904
+ private writeSceneJSON;
905
+ private resetJSONCopy;
906
+ private tabKeydown;
907
+ private addInput;
908
+ private renderInputDefinition;
909
+ private renameInput;
910
+ private renderScalar;
911
+ private applyAdvanced;
912
+ private renderSteps;
913
+ private addStep;
914
+ private moveStep;
915
+ private addAction;
916
+ private addCheck;
917
+ private renderAction;
918
+ private renderCheck;
919
+ private renderParameters;
920
+ private outputActions;
921
+ private renderSegment;
922
+ private pickRegion;
923
+ /** 原面板与独立播放器通过同一运行门面完成会话内重选。 */
924
+ reselectCurrentRegion(): void;
925
+ private openPicker;
926
+ private previewRegion;
927
+ private renderPreview;
928
+ private renderPlayback;
929
+ private startPreview;
930
+ private deleteScene;
931
+ private refresh;
932
+ private cloudPublish;
933
+ private selectKnowledge;
934
+ private createKnowledge;
935
+ private renderKnowledge;
936
+ private saveKnowledge;
937
+ private reloadKnowledge;
938
+ private cloudPublishKnowledge;
939
+ private deleteKnowledge;
940
+ private renderExchangeSkeleton;
941
+ private renderExchange;
942
+ private exportJSON;
943
+ private readImportFile;
944
+ private previewJSON;
945
+ private commitImport;
946
+ }
947
+ //#endregion
948
+ //#region src/flow/ui/mount.d.ts
949
+ interface MountPageUseManagerOptions {
950
+ handle: {
951
+ flow?: PageUseFlowHandle;
952
+ };
953
+ target?: HTMLElement;
954
+ /** 默认沿用执行端;显式布局必须与执行端一致。 */
955
+ layout?: FlowClient;
956
+ /** 默认管理表单;scenarios 仅呈现正式场景目录和播放控制。 */
957
+ presentation?: PageUseManagerPresentation;
958
+ }
959
+ declare function definePageUseManagerElement(): void;
960
+ /** 管理 UI 不应出现在 page-agent 的页面扫描中,卸载同步清理订阅。 */
961
+ declare function mountPageUseManager(options: MountPageUseManagerOptions): () => void;
962
+ //#endregion
963
+ //#region src/flow/tool.d.ts
964
+ declare const PAGE_USE_FLOW_TOOL: {
965
+ readonly type: "function";
966
+ readonly function: {
967
+ readonly name: "run_business_scene";
968
+ readonly description: "按业务脚本演示已发布的完整流程。只能选择当前账号和终端可用目录中的场景;场景含修改操作时由宿主确认。执行期间不可同时操作页面。";
969
+ readonly parameters: {
970
+ readonly type: "object";
971
+ readonly properties: {
972
+ readonly sceneId: {
973
+ readonly type: "string";
974
+ readonly description: "可用目录中返回的完整场景 key";
975
+ };
976
+ readonly input: {
977
+ readonly type: "object";
978
+ readonly description: "场景声明的启动参数,例如业务编号";
979
+ };
980
+ };
981
+ readonly required: readonly ["sceneId"];
982
+ readonly additionalProperties: false;
983
+ };
984
+ };
985
+ };
986
+ declare function getPageUseFlowCatalog(flow: PageUseFlowHandle): Promise<{
987
+ key: string;
988
+ id: string;
989
+ name: string;
990
+ description: string | undefined;
991
+ client: FlowClient;
992
+ revision: string;
993
+ inputs: Record<string, FlowInputDefinition>;
994
+ }[]>;
995
+ declare function runPageUseFlowTool(flow: PageUseFlowHandle, args: unknown, options?: Omit<FlowRunOptions, 'input' | 'preview'>): Promise<{
996
+ result: FlowRunResult;
997
+ content: string;
998
+ }>;
999
+ //#endregion
1000
+ //#region src/tour/styles.d.ts
1001
+ /**
1002
+ * 页面讲解风格:同一页面面向不同受众时,讲解的侧重点、详略与语气不同。
1003
+ * 风格说明追加在按页提示的模块清单之后;用户指令中另有讲解要求时以用户指令为准(见工具描述)。
1004
+ */
1005
+ interface PageUseTourStyle {
1006
+ /** 唯一标识,快捷指令与运行参数按此引用 */
1007
+ key: string;
1008
+ /** 面板中显示的名称 */
1009
+ label: string;
1010
+ /** 给模型的讲解要求:受众、侧重点、每段篇幅、语气 */
1011
+ prompt: string;
1012
+ }
1013
+ /** 内置风格 key:日常使用者 */
1014
+ declare const TOUR_STYLE_USER = "user";
1015
+ /** 内置风格 key:培训讲师 */
1016
+ declare const TOUR_STYLE_TRAINER = "trainer";
1017
+ /** 内置风格;宿主以相同 key 配置时覆盖对应项 */
1018
+ declare const DEFAULT_TOUR_STYLES: readonly PageUseTourStyle[];
1019
+ //#endregion
1020
+ //#region src/voice/engine.d.ts
1021
+ /**
1022
+ * 演示播报的语音合成引擎接口。
1023
+ * 宿主可通过 PageUseOptions.tts 注入一个或多个(如不同厂商的在线 TTS 服务),与内置浏览器引擎一起供设置切换。
1024
+ * 播报队列(待播、抢占、清空)由 speaker 统一处理,引擎只负责「把一段文本播出来」。
1025
+ */
1026
+ interface PageUseTtsVoice {
1027
+ /** 写入设置 voiceNames[引擎 id] 的值 */
1028
+ value: string;
1029
+ /** 下拉框显示名 */
1030
+ label: string;
1031
+ }
1032
+ interface PageUseTtsSpeakOptions {
1033
+ /** 语速倍率(设置 voiceRate,1 为正常语速);引擎自行换算为服务参数 */
1034
+ rate: number;
1035
+ /** 当前引擎在设置 voiceNames 中的音色;空串表示由引擎自动选择 */
1036
+ voice: string;
1037
+ /** 播报被抢占或清空时触发:引擎应立即停止自身的合成与播放并 resolve */
1038
+ signal: AbortSignal;
1039
+ }
1040
+ interface PageUseTtsEngine {
1041
+ /**
1042
+ * 稳定标识:作为设置中所选引擎(voiceEngineId)与各引擎音色(voiceNames)的保存键,
1043
+ * 修改后已保存的选择会失效。'browser' 保留给内置浏览器引擎,注入同名引擎会被忽略。
1044
+ */
1045
+ id: string;
1046
+ /** 引擎名称,显示在调试面板播报设置中 */
1047
+ label: string;
1048
+ /**
1049
+ * true:一组句子逐句调用 speak(适合本地合成,句间无额外延迟);
1050
+ * false:整组句子合并为一次调用(适合在线服务,避免每句建连的停顿与调用次数)。
1051
+ */
1052
+ splitSentences: boolean;
1053
+ /** 当前环境是否可用;不可用时播报静默跳过,设置面板显示提示 */
1054
+ isAvailable(): boolean;
1055
+ /** 可选音色列表;不提供或返回空时设置面板不显示音色下拉框 */
1056
+ listVoices?(): PageUseTtsVoice[];
1057
+ /**
1058
+ * 播报一段文本,播完、失败或被中止时 resolve。
1059
+ * 约定不 reject:失败由引擎自行记录,队列继续推进(speaker 仍会兜底捕获)。
1060
+ */
1061
+ speak(text: string, options: PageUseTtsSpeakOptions): Promise<void>;
1062
+ }
1063
+ //#endregion
1064
+ //#region src/core/options.d.ts
1065
+ /** 默认模型,仅为示例取值;接入其它端点时应通过 llm.model 显式指定支持 function calling 的模型 */
1066
+ declare const DEFAULT_MODEL = "deepseek-chat";
1067
+ /** 单次任务最大步数;每步一次 LLM 调用,防止死循环消耗 token */
1068
+ declare const DEFAULT_MAX_STEPS = 20;
1069
+ /** 默认会话头:OpenCode Go 要求每个会话带稳定的 x-opencode-session 用于路由与提示缓存 */
1070
+ declare const DEFAULT_SESSION_HEADER = "x-opencode-session";
1071
+ /** localStorage / sessionStorage 键前缀,可通过 storageKeyPrefix 覆盖 */
1072
+ declare const DEFAULT_STORAGE_KEY_PREFIX = "tz-page-use";
1073
+ /** 页面讲解单次最多切换 Tab 的次数(不含结束时切回);每次切换多一次 LLM 调用,限制演示时长 */
1074
+ declare const DEFAULT_TOUR_MAX_TAB_SWITCHES = 5;
1075
+ interface PageUseLLMOptions {
1076
+ /**
1077
+ * OpenAI 兼容端点(到版本前缀为止,如 https://api.deepseek.com/v1)。
1078
+ * 可传相对路径(如本地代理 /__page-use-llm),会按当前 origin 补为绝对地址。
1079
+ */
1080
+ baseURL: string;
1081
+ /**
1082
+ * 前端直连时的 Key。生产环境建议留空,由网关/代理注入,避免 Key 出现在前端产物中。
1083
+ */
1084
+ apiKey?: string;
1085
+ model?: string;
1086
+ maxSteps?: number;
1087
+ /** 部分模型拒绝对象形式 tool_choice("Invalid tool_choice type")时打开 */
1088
+ disableNamedToolChoice?: boolean;
1089
+ /** 额外合并进请求体的字段,例:DeepSeek 关闭思考模式 { thinking: { type: 'disabled' } } */
1090
+ extraBody?: Record<string, unknown>;
1091
+ /**
1092
+ * 会话 ID 请求头名,每个任务生成一个新 ID;false 表示不发送
1093
+ * (直连不需要该头的端点时关闭,避免 CORS 预检拒绝自定义头)。默认 x-opencode-session。
1094
+ */
1095
+ sessionHeader?: string | false;
1096
+ }
1097
+ /**
1098
+ * 路由模式,决定站点地图中路径的写法与默认的当前路径读取方式:
1099
+ * - hash:页面 URL 形如 `/#/a/b`
1100
+ * - history:页面 URL 形如 `/a/b`
1101
+ */
1102
+ type PageUseRouterMode = 'hash' | 'history';
1103
+ /** 页面讲解(「介绍当前页面」)的配置 */
1104
+ interface PageUseTourOptions {
1105
+ /** 单次讲解最多切换 Tab 的次数,默认 5;结束时切回初始 Tab 不计入 */
1106
+ maxTabSwitches?: number;
1107
+ /**
1108
+ * 讲解风格:与内置「日常使用者」(user)「培训讲师」(trainer)合并,同 key 覆盖内置项,新 key 追加。
1109
+ * 快捷指令的 tourStyle、运行参数 tourStyle 与面板设置按 key 引用。
1110
+ */
1111
+ styles?: PageUseTourStyle[];
1112
+ /** 未指定风格时使用的 key,默认 'user';不存在时回退为第一个风格 */
1113
+ defaultStyle?: string;
1114
+ }
1115
+ interface PageUseOptions {
1116
+ llm: PageUseLLMOptions;
1117
+ /** 系统名称,写入系统提示「你正在「xxx」内替用户操作页面」 */
1118
+ appName: string;
1119
+ /** 每次任务开始(及每一步)时读取最新的可见菜单;返回空时站点地图为空 */
1120
+ getMenus?: () => PageUseMenuNode[] | undefined;
1121
+ /** 默认 'hash' */
1122
+ routerMode?: PageUseRouterMode;
1123
+ /** 读取当前路由路径(不含 `#`);默认按 routerMode 从 location 读取 */
1124
+ getCurrentPath?: () => string;
1125
+ /** 由路径解析路由名,用于匹配 routeHints;不传时 routeHints 仅按路径匹配 */
1126
+ resolveRouteName?: (path: string) => string | undefined;
1127
+ /** 按页操作提示:key 为路由名或路径(不含前导 `/`),value 为提示文本 */
1128
+ routeHints?: Record<string, string>;
1129
+ /** 页面布局描述,替换系统提示中的「页面结构」段落;不传时使用通用描述 */
1130
+ layoutHint?: string;
1131
+ /** 任务开始前的宿主预处理,例如展开折叠的侧栏,使菜单文字对模型可见 */
1132
+ beforeTask?: () => void | Promise<void>;
1133
+ /** 调试面板设置中 beforeTask 开关的显示名,默认「任务开始前执行宿主预处理」 */
1134
+ beforeTaskLabel?: string;
1135
+ /** 存储键前缀,默认 'tz-page-use';同源多应用共存时用于隔离 */
1136
+ storageKeyPrefix?: string;
1137
+ /** 透传给 page-agent 的配置,覆盖包内默认值(stepDelay、language 等) */
1138
+ pageAgentOptions?: Partial<PageAgentConfig>;
1139
+ /** 是否安装 window.__TZ_PAGE_USE__ 全局桥接,默认 true */
1140
+ exposeGlobal?: boolean;
1141
+ /**
1142
+ * 演示播报的语音合成引擎(如不同厂商的在线 TTS 服务),可传单个或数组。
1143
+ * 内置浏览器引擎(本地语音)始终可选且为默认引擎,排在下拉框最前;用户可在调试面板设置中切换到注入的引擎。
1144
+ */
1145
+ tts?: PageUseTtsEngine | PageUseTtsEngine[];
1146
+ /**
1147
+ * 页面内容区根节点,页面讲解只在其中识别模块与 Tab(排除顶部栏、导航菜单)。
1148
+ * 未传或返回空时依次使用 main、[role=main]、document.body。
1149
+ */
1150
+ getContentRoot?: () => Element | null | undefined;
1151
+ /**
1152
+ * 页面讲解:默认开启,注册讲解工具并在按页提示中附带模块清单;
1153
+ * false 关闭(不注册工具、不附带清单);对象形式可调整 Tab 切换上限。
1154
+ */
1155
+ pageTour?: boolean | PageUseTourOptions;
1156
+ /** 场景功能开关:默认关闭;true 使用桌面端本地配置,对象用于自定义终端、身份与云端能力。 */
1157
+ flow?: boolean | PageUseFlowOptions;
1158
+ }
1159
+ interface NormalizedTourOptions {
1160
+ enabled: boolean;
1161
+ maxTabSwitches: number;
1162
+ /** 内置与宿主合并后的风格,至少含两个内置风格 */
1163
+ styles: PageUseTourStyle[];
1164
+ /** 已校验存在于 styles 中 */
1165
+ defaultStyle: string;
1166
+ }
1167
+ interface NormalizedLLMOptions {
1168
+ /** 绝对地址;page-agent 内部 `new URL(baseURL)` 解析,相对路径会抛错 */
1169
+ baseURL: string;
1170
+ apiKey: string;
1171
+ model: string;
1172
+ maxSteps: number;
1173
+ disableNamedToolChoice: boolean;
1174
+ extraBody: Record<string, unknown>;
1175
+ /** 空串表示不发送会话头 */
1176
+ sessionHeader: string;
1177
+ }
1178
+ interface NormalizedPageUseOptions {
1179
+ llm: NormalizedLLMOptions;
1180
+ appName: string;
1181
+ getMenus: () => PageUseMenuNode[] | undefined;
1182
+ routerMode: PageUseRouterMode;
1183
+ getCurrentPath: () => string;
1184
+ resolveRouteName?: (path: string) => string | undefined;
1185
+ routeHints: Record<string, string>;
1186
+ layoutHint?: string;
1187
+ beforeTask?: () => void | Promise<void>;
1188
+ beforeTaskLabel: string;
1189
+ storageKeyPrefix: string;
1190
+ pageAgentOptions: Partial<PageAgentConfig>;
1191
+ exposeGlobal: boolean;
1192
+ /** 可选引擎:注入引擎(去重)在前,浏览器引擎在最后;至少含浏览器引擎 */
1193
+ ttsEngines: PageUseTtsEngine[];
1194
+ /** 已含回退逻辑,始终返回元素(无 DOM 环境时为 null) */
1195
+ getContentRoot: () => Element | null;
1196
+ pageTour: NormalizedTourOptions;
1197
+ flow?: PageUseFlowOptions;
1198
+ }
1199
+ declare function normalizeOptions(options: PageUseOptions): NormalizedPageUseOptions;
1200
+ /**
1201
+ * 调试面板是否显示。优先级:URL 参数(并记入本会话)> 会话记录 > fallback。
1202
+ * fallback 由宿主决定(例如「开发环境显示,生产环境隐藏」)。
1203
+ */
1204
+ declare function readLauncherSwitch(fallback: boolean, storageKeyPrefix?: string): boolean;
1205
+ //#endregion
1206
+ export { FlowClient as $, FlowStep as $t, FLOW_SEGMENT_MAX_CHARS as A, FlowPresenter as At, validateSceneBindings as B, FlowRepositorySnapshot as Bt, runPageUseFlowTool as C, FlowManager as Ct, PAGE_USE_MANAGER_TAG as D, FlowParameter as Dt, mountPageUseManager as E, FlowOutputReference as Et, parseFlowScene as F, FlowRegionFailure as Ft, FlowApiRequest as G, FlowScene as Gt, FLOW_SCHEMA_VERSION as H, FlowRunOptions as Ht, parseFlowSceneDraft as I, FlowRegionHost as It, FlowBindings as J, FlowSegment as Jt, FlowApiResponse as K, FlowSceneRecord as Kt, sceneKey as L, FlowRegionPage as Lt, parseFlowBundle as M, FlowRegionAnchor as Mt, parseFlowKnowledge as N, FlowRegionCandidate as Nt, PageUseManagerElement as O, FlowParameterDefinition as Ot, parseFlowRegion as P, FlowRegionContext as Pt, FlowCheckBinding as Q, FlowStatus as Qt, scopeKey as R, FlowRegionSelector as Rt, getPageUseFlowCatalog as S, FlowKnowledgeRecord as St, definePageUseManagerElement as T, FlowMode as Tt, FlowAction as U, FlowRunResult as Ut, FLOW_BUNDLE_VERSION as V, FlowResolvedTarget as Vt, FlowActionBinding as W, FlowRunner as Wt, FlowBundle as X, FlowSessionContext as Xt, FlowBoundCheck as Y, FlowSegmentLog as Yt, FlowCheck as Z, FlowSnapshot as Zt, DEFAULT_TOUR_STYLES as _, FlowIdentity as _t, DEFAULT_TOUR_MAX_TAB_SWITCHES as a, PageUseErrorCode as an, FlowCompletionDecision as at, TOUR_STYLE_USER as b, FlowInputDefinition as bt, PageUseLLMOptions as c, PageUseProgressEvent as cn, FlowContext as ct, PageUseTourOptions as d, PageUseStepLog as dn, FlowError as dt, FlowTombstone as en, FlowCloudAdapter as et, normalizeOptions as f, PageUseTaskResult as fn, FlowErrorCode as ft, PageUseTtsVoice as g, FlowGenerator as gt, PageUseTtsSpeakOptions as h, FlowExportOptions as ht, DEFAULT_STORAGE_KEY_PREFIX as i, PageUseFlowOptions as in, FlowCloudState as it, newRevision as j, FlowRegion as jt, PageUseManagerPresentation as k, FlowPermissions as kt, PageUseOptions as l, PageUseRunOptions as ln, FlowContextBinding as lt, PageUseTtsEngine as m, PageUseTaskStatus as mn, FlowExecutionPorts as mt, DEFAULT_MODEL as n, JsonValue as nn, FlowCloudController as nt, NormalizedLLMOptions as o, PageUseMenuNode as on, FlowCompletionEvaluator as ot, readLauncherSwitch as p, PageUseTaskSource as pn, FlowEvent as pt, FlowApiSyncOptions as q, FlowScope as qt, DEFAULT_SESSION_HEADER as r, PageUseFlowHandle as rn, FlowCloudRelease as rt, NormalizedPageUseOptions as s, PageUsePreset as sn, FlowConfigResponse as st, DEFAULT_MAX_STEPS as t, JsonObject as tn, FlowCloudCache as tt, PageUseRouterMode as u, PageUseSnapshot as un, FlowDescriptionCheck as ut, PageUseTourStyle as v, FlowImportPreview as vt, MountPageUseManagerOptions as w, FlowManagerState as wt, PAGE_USE_FLOW_TOOL as x, FlowKnowledge as xt, TOUR_STYLE_TRAINER as y, FlowImportStrategy as yt, validateFlowInputs as z, FlowRepository as zt };