@plume-canvas/cloud-server 0.0.0-stage → 0.1.1
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 +18 -2
- package/builtin-manifest.json +28 -0
- package/dist/cli.js +81 -0
- package/dist/index.d.ts +3555 -0
- package/dist/index.js +38 -0
- package/package.json +51 -4
- package/providers/seed-audio-volc.js +402 -0
- package/providers/seed-audio.js +376 -0
- package/providers/web2api-audio.js +500 -0
- package/providers/web2api-image.js +497 -0
- package/providers/web2api-video.js +490 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,3555 @@
|
|
|
1
|
+
import { Hono } from 'hono';
|
|
2
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* 一个动作的声明。
|
|
6
|
+
*
|
|
7
|
+
* 前半段是**给前端渲染**的(菜单长什么样);后半段是**给后台执行**的
|
|
8
|
+
* (用哪个工具、怎么拼参数),前端拿到也不认识、会忽略。
|
|
9
|
+
*/
|
|
10
|
+
export declare interface ActionDef {
|
|
11
|
+
/** 动作 id(全局唯一;同名 = 替换) */
|
|
12
|
+
id: string;
|
|
13
|
+
/** 按钮 / 下拉里显示的名字(通常就是模型名) */
|
|
14
|
+
title: string;
|
|
15
|
+
description?: string;
|
|
16
|
+
group?: string;
|
|
17
|
+
/** 排序(小的在前) */
|
|
18
|
+
order?: number;
|
|
19
|
+
/** 服务哪些节点类型;省略 = 都适用 */
|
|
20
|
+
nodeTypes?: ProviderNodeType[];
|
|
21
|
+
/** 要不要底栏那个大输入框 */
|
|
22
|
+
needsPrompt?: boolean;
|
|
23
|
+
/** 输入框和节点哪个字段绑('text' = 文本节点) */
|
|
24
|
+
promptBinding?: 'none' | 'text';
|
|
25
|
+
/** 可视化参数(前端据此长控件) */
|
|
26
|
+
fields?: ActionParam[];
|
|
27
|
+
/** 该动作交给 provider 的哪个工具(provider 自己解释,内核不管) */
|
|
28
|
+
tool?: string;
|
|
29
|
+
/** 平台侧的模型名(如 seedance_v2.0_mini) */
|
|
30
|
+
model?: string;
|
|
31
|
+
/** 参数怎么传:chat-auto = 拼进提示词前缀;plain = 当工具参数直传 */
|
|
32
|
+
promptMode?: 'chat-auto' | 'plain';
|
|
33
|
+
/** chat-auto 时的媒体模式 */
|
|
34
|
+
mediaMode?: 'image' | 'video';
|
|
35
|
+
/** 本动作自己的轮询节奏(长视频不能被共享的短超时误杀) */
|
|
36
|
+
pollIntervalMs?: number;
|
|
37
|
+
pollTimeoutMs?: number;
|
|
38
|
+
/**
|
|
39
|
+
* 本动作的进度显示口径(给加载 UI 用,前端只照画)。
|
|
40
|
+
*
|
|
41
|
+
* · `suffix`:大数字后面的单位,默认 `%`;token 类动作写 `tokens`。
|
|
42
|
+
* · `startValue`:提交那一帧显示的数字(还没有任何轮询结果时先显示它),默认 0。
|
|
43
|
+
*
|
|
44
|
+
* 为什么放在动作上:第一个进度帧在 provider 第一次 poll 之前就写了,
|
|
45
|
+
* 那时候还没有任何轮询结果;把口径写在动作声明里,提交帧就能照口径显示
|
|
46
|
+
* (用户 2026-11-10:点发送立刻要看到 `0tokens`,不是等一两秒再变)。
|
|
47
|
+
*/
|
|
48
|
+
progressDisplay?: {
|
|
49
|
+
suffix?: string;
|
|
50
|
+
startValue?: number;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* 本动作**自己的执行方式**(用户 2026-11-10)。
|
|
54
|
+
*
|
|
55
|
+
* 为什么放在动作上而不是 provider 上:一个 provider 文件里常常声明好几条动作,
|
|
56
|
+
* 它们的执行逻辑差别很大(有的能取消、有的不能;有的有服务端任务号、有的是本地
|
|
57
|
+
* 长跑;有的轮询节奏不同)。挂在 provider 上的 `submit/poll/cancel` 只有一份,
|
|
58
|
+
* 分不清哪条动作支持什么 —— 于是「取消」按钮对不支持的节点也照画、点了没反应。
|
|
59
|
+
*
|
|
60
|
+
* 给了这里的函数就用它;没给就回落到 provider 上的同名函数(老 provider 不用改)。
|
|
61
|
+
*/
|
|
62
|
+
submit?: ProviderActionSubmit;
|
|
63
|
+
poll?: (taskId: string, ctx: ActionRunContext) => Promise<ProviderPollResult>;
|
|
64
|
+
/**
|
|
65
|
+
* 取消这条动作产出的任务。**声明了才代表这条动作真的能取消** ——
|
|
66
|
+
* 前端据此决定显不显示「取消」按钮,后台据此决定要不要发取消。
|
|
67
|
+
*/
|
|
68
|
+
cancel?: (taskId: string, ctx: ActionRunContext) => Promise<void> | void;
|
|
69
|
+
/** 刷新后接着查(有服务端任务号的动作才有意义) */
|
|
70
|
+
resume?: (taskId: string, ctx: ActionRunContext) => Promise<ProviderPollResult>;
|
|
71
|
+
/**
|
|
72
|
+
* 这条动作在**参数下拉**上显示什么(用户 2026-11-17)。
|
|
73
|
+
*
|
|
74
|
+
* 不给就回落默认摘要(「只显示改过默认值的参数」)。给了就由 provider 决定标题,
|
|
75
|
+
* 例如把当前档位的花费写进去。返回空串 = 用默认。
|
|
76
|
+
*/
|
|
77
|
+
selectLabel?: (input: ActionTextInput) => string;
|
|
78
|
+
/**
|
|
79
|
+
* 这条动作在**发送按钮**里显示什么(用户 2026-11-17)。
|
|
80
|
+
*
|
|
81
|
+
* 关键词是「花费」:返回「0.65积分」这类短文案,直接画在按钮内的图标右边。
|
|
82
|
+
* 返回空串 = 按钮只显示图标。
|
|
83
|
+
*/
|
|
84
|
+
sendLabel?: (input: ActionTextInput) => string;
|
|
85
|
+
/** provider 可以塞自己的东西;内核与前端都不读 */
|
|
86
|
+
[k: string]: unknown;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* 动作参数声明。
|
|
91
|
+
*
|
|
92
|
+
* `kind` 是**语义类型**(比例 / 时长 / 音色…),前端据此挑对应的控件;
|
|
93
|
+
* `type` 只是兜底的控件类型(服务端 schema 表达不出"哪个是比例"这种知识)。
|
|
94
|
+
*/
|
|
95
|
+
export declare interface ActionParam {
|
|
96
|
+
key: string;
|
|
97
|
+
/** 语义类型:ratio / duration / resolution / speaker / camera / count / speed / format… */
|
|
98
|
+
kind?: string;
|
|
99
|
+
label?: string;
|
|
100
|
+
/**
|
|
101
|
+
* 一句话说明:这个参数是干什么的、怎么选。
|
|
102
|
+
*
|
|
103
|
+
* 原样送到前端,前端在参数标题下方渲染成一行灰色小字;
|
|
104
|
+
* 参数被"铺到外面"(只有一个下拉时)则作为下拉展开后的说明行 + 悬停提示。
|
|
105
|
+
* 写长一点没关系,前端会换行。
|
|
106
|
+
*/
|
|
107
|
+
description?: string;
|
|
108
|
+
/**
|
|
109
|
+
* 基础控件(与内核 ToolParamDef 同一套词表)。
|
|
110
|
+
*
|
|
111
|
+
* `text` 是 `string` 的老写法,仍然认 —— 已经有 provider 这么写了,
|
|
112
|
+
* 前端两种都画成单行输入框。
|
|
113
|
+
*/
|
|
114
|
+
type: 'select' | 'grid' | 'string' | 'text' | 'number' | 'boolean';
|
|
115
|
+
default?: string | number | boolean;
|
|
116
|
+
options?: ParamOption[];
|
|
117
|
+
min?: number;
|
|
118
|
+
max?: number;
|
|
119
|
+
step?: number;
|
|
120
|
+
unit?: string;
|
|
121
|
+
/** 按钮类控件的列数(grid / number+options / kind:ratio) */
|
|
122
|
+
columns?: number;
|
|
123
|
+
/** type='string' 时的输入提示 */
|
|
124
|
+
placeholder?: string;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** 动作自带的执行上下文(与 provider 级函数拿到的形参一致) */
|
|
128
|
+
declare interface ActionRunContext {
|
|
129
|
+
/** 完整动作声明(provider 自己塞的字段从这里读) */
|
|
130
|
+
action: ActionDef;
|
|
131
|
+
/** 下单时的入参(取消 / 续查时为 undefined) */
|
|
132
|
+
input?: JobInput;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export declare function actionsRoutes(registry: ProviderRegistry,
|
|
136
|
+
/** 宿主注入:按平台 id 查账号清单(拿不到就只有模型行,不出账号二级菜单) */
|
|
137
|
+
accountsOf?: (providerId: string) => Array<{
|
|
138
|
+
id: string;
|
|
139
|
+
name?: string;
|
|
140
|
+
default?: boolean;
|
|
141
|
+
}>,
|
|
142
|
+
/**
|
|
143
|
+
* 宿主注入:按平台 id 查被用户关掉的模型(动作 id)。
|
|
144
|
+
*
|
|
145
|
+
* 关掉的模型**不再下发给前端**,于是底栏的模型下拉里就没有它了(用户口径 2026-11-20)。
|
|
146
|
+
* 拿不到这个函数 = 一个都不关,行为与旧版一致。
|
|
147
|
+
*/
|
|
148
|
+
disabledModelsOf?: (providerId: string) => string[]): Hono;
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* 一条下拉标题 / 发送按钮文案的计算入参(provider 的可选渲染函数用它)。
|
|
152
|
+
*
|
|
153
|
+
* 为什么是**数据**而不是函数:动作声明要能过 JSON 送到前端。
|
|
154
|
+
*/
|
|
155
|
+
declare interface ActionTextInput {
|
|
156
|
+
/** 这条动作的 id */
|
|
157
|
+
actionId: string;
|
|
158
|
+
/** 用户当前选的全部参数值(键 = ActionParam.key) */
|
|
159
|
+
values: Record<string, unknown>;
|
|
160
|
+
/** 每个参数的当前显示文案(有 options 用 label,否则原样),键 = ActionParam.key */
|
|
161
|
+
labels: Record<string, string>;
|
|
162
|
+
/** 已按「只显示改过默认值的」规则拼好的摘要(默认表现就是它) */
|
|
163
|
+
summary: string;
|
|
164
|
+
/** 上游连进来的素材条数(按 kind 分) */
|
|
165
|
+
resources: {
|
|
166
|
+
image: number;
|
|
167
|
+
video: number;
|
|
168
|
+
audio: number;
|
|
169
|
+
text: number;
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** 新增连线的入参 */
|
|
174
|
+
export declare interface AddEdgeInput {
|
|
175
|
+
source: string;
|
|
176
|
+
target: string;
|
|
177
|
+
id?: string;
|
|
178
|
+
/** 边的类型;缺省与数据层一致取 'custom'(不写会导致云端与本地对同一条边判定不一致) */
|
|
179
|
+
type?: string;
|
|
180
|
+
sourceHandle?: string;
|
|
181
|
+
targetHandle?: string;
|
|
182
|
+
data?: Record<string, unknown>;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** 新增节点的入参 */
|
|
186
|
+
export declare interface AddNodeInput {
|
|
187
|
+
type: string;
|
|
188
|
+
id?: string;
|
|
189
|
+
position?: {
|
|
190
|
+
x: number;
|
|
191
|
+
y: number;
|
|
192
|
+
};
|
|
193
|
+
data?: Record<string, unknown>;
|
|
194
|
+
size?: {
|
|
195
|
+
w: number;
|
|
196
|
+
h: number;
|
|
197
|
+
};
|
|
198
|
+
parentId?: string;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** 允许的扩展名(上传时按它过滤,白名单外的回落空串) */
|
|
202
|
+
export declare const ALLOWED_EXT: readonly string[];
|
|
203
|
+
|
|
204
|
+
declare interface Asset {
|
|
205
|
+
id: string;
|
|
206
|
+
name: string;
|
|
207
|
+
kind: AssetKind;
|
|
208
|
+
/** 可加载的地址(生成的指回画布资源;上传的指 assets/files) */
|
|
209
|
+
url: string;
|
|
210
|
+
/**
|
|
211
|
+
* **本机绝对路径**(有字节落盘时才有;外部地址 / 字节不在本机 → 无此字段)。
|
|
212
|
+
*
|
|
213
|
+
* 为什么要有它(用户口径):引用要能**复制到本机 Agent**(Codex 等)直接用 ——
|
|
214
|
+
* 给相对 URL 的话对方得先猜 base、再下载到本地才能读,绕好几步;
|
|
215
|
+
* 绝对路径一步 readFile 到位。与「技能引用给 SKILL.md 绝对路径」同一条规矩。
|
|
216
|
+
*/
|
|
217
|
+
path?: string;
|
|
218
|
+
/** 所属文件夹(undefined = 根目录「个人资产库」) */
|
|
219
|
+
folderId?: string;
|
|
220
|
+
/** 标签(固定清单:角色/场景/物品/风格/音效) */
|
|
221
|
+
tags?: string[];
|
|
222
|
+
/** 来源画布(生成产物才有;用于溯源,也便于画布删除时清理) */
|
|
223
|
+
canvasId?: string;
|
|
224
|
+
size?: number;
|
|
225
|
+
source: 'generated' | 'upload';
|
|
226
|
+
createdAt: number;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** 资产文件夹:树形(parentId 指向父文件夹,根为 undefined) */
|
|
230
|
+
declare interface AssetFolder {
|
|
231
|
+
id: string;
|
|
232
|
+
name: string;
|
|
233
|
+
parentId?: string;
|
|
234
|
+
/** 图标(图标选择器选的名字;空 = 默认文件夹图标) */
|
|
235
|
+
icon?: string;
|
|
236
|
+
createdAt: number;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* 资产类型。
|
|
241
|
+
*
|
|
242
|
+
* node-package 是**节点包**(可视化节点 + 它依赖的后台脚本打成一个 .plumenode)。
|
|
243
|
+
* 单独一类而不是丢进 other:左侧抽屉据此知道它是"能拖出节点的东西",
|
|
244
|
+
* 拖到画布时的落点是"还原节点 + 写脚本",而不是"建一个媒体节点"。
|
|
245
|
+
*/
|
|
246
|
+
declare type AssetKind = 'image' | 'video' | 'audio' | 'node-package' | 'node-group' | 'other';
|
|
247
|
+
|
|
248
|
+
declare class AssetStore {
|
|
249
|
+
private readonly root;
|
|
250
|
+
constructor(root: string);
|
|
251
|
+
/**
|
|
252
|
+
* 本店所有「读—改—写」的串行链。
|
|
253
|
+
*
|
|
254
|
+
* 为什么必须有(用户报的现场 2026-10-14):「批量删除之后刷新页面,又会出现一些内容」。
|
|
255
|
+
* 前端「全选删除」的形状是 `for (id of ids) void deleteAssetById(id)` —— **并发**发 N 个 DELETE,
|
|
256
|
+
* 每个请求各自「读整张 index.json → 去掉一条 → 整份写回」。读改写不串行时,N 个请求读到的是
|
|
257
|
+
* **同一份旧账**,各自写回,后写的把先写的整条覆盖掉 —— 实测 12 条并发删只剩 1 条真被删掉
|
|
258
|
+
* (真机 HTTP 复现:5 条并发删只删掉 1 条)。
|
|
259
|
+
*
|
|
260
|
+
* 与 KvStore 的 `runExclusive` / CanvasStore 的 `writeChains` 同款解法(那边是为「写同一份配置」、
|
|
261
|
+
* 这边是为「同一份资产账」)。区别只在粒度:资产登记表 + 文件夹表都是小文件、都参与同一批
|
|
262
|
+
* 批量操作,合成**一条**链最简单也最不容易漏(按文件分链反而会漏掉「移文件夹同时改条目归属」
|
|
263
|
+
* 这种跨两个文件的组合操作)。
|
|
264
|
+
*/
|
|
265
|
+
private chain;
|
|
266
|
+
/** 把一次读改写排进链尾(链上任务抛错不卡住后面的) */
|
|
267
|
+
private runExclusive;
|
|
268
|
+
/**
|
|
269
|
+
* 读整张登记表(**链内**用)。
|
|
270
|
+
*
|
|
271
|
+
* 名字带 Locked 是提醒:只能从 `runExclusive` 的任务里调。链内再调一次 `runExclusive` 会在等
|
|
272
|
+
* 自己那条链 —— 直接死锁(job 等自己)。所以对内一律用这一份,对外才用 `list()`。
|
|
273
|
+
*/
|
|
274
|
+
private listLocked;
|
|
275
|
+
list(): Promise<Asset[]>;
|
|
276
|
+
/** 读文件夹表(**链内**用;只能从 runExclusive 的任务里调) */
|
|
277
|
+
private listFoldersLocked;
|
|
278
|
+
listFolders(): Promise<AssetFolder[]>;
|
|
279
|
+
private writeFolders;
|
|
280
|
+
createFolder(name: string, parentId?: string): Promise<AssetFolder>;
|
|
281
|
+
renameFolder(id: string, name: string): Promise<AssetFolder | undefined>;
|
|
282
|
+
/** 更新文件夹图标(图标选择器「应用」;空串 = 清除回默认) */
|
|
283
|
+
setFolderIcon(id: string, icon: string): Promise<AssetFolder | undefined>;
|
|
284
|
+
/** 移动文件夹(检查环:不能挪进自己的子孙里) */
|
|
285
|
+
moveFolder(id: string, newParentId?: string): Promise<AssetFolder | undefined>;
|
|
286
|
+
/** 删文件夹:里面的资产和子文件夹都上移到它的父级(不销毁数据) */
|
|
287
|
+
removeFolder(id: string): Promise<boolean>;
|
|
288
|
+
private write;
|
|
289
|
+
/**
|
|
290
|
+
* 登记一条**已有地址**的资产(生成产物走这条)。同 url 幂等。
|
|
291
|
+
* @returns 新登记 / 已存在的那条
|
|
292
|
+
*/
|
|
293
|
+
addByUrl(input: {
|
|
294
|
+
url: string;
|
|
295
|
+
name?: string;
|
|
296
|
+
canvasId?: string;
|
|
297
|
+
source?: Asset['source'];
|
|
298
|
+
folderId?: string;
|
|
299
|
+
/** 本机绝对路径(有字节落盘时传;外部地址不传) */
|
|
300
|
+
path?: string;
|
|
301
|
+
}): Promise<Asset>;
|
|
302
|
+
/**
|
|
303
|
+
* 从「本机可定位的 url」推出绝对路径;外部地址(别的服务的 http://)→ undefined(不瞎编)。
|
|
304
|
+
*
|
|
305
|
+
* 认两种形态:
|
|
306
|
+
* - /api/assets/files/<hash> → <root>/assets/files/<hash>
|
|
307
|
+
* - /api/canvases/<canvasId>/resources/<hash> → <root>/canvases/<canvasId>/resources/<hash>
|
|
308
|
+
*/
|
|
309
|
+
private localPathFromUrl;
|
|
310
|
+
/** 存一份**上传**的字节(内容寻址去重)并登记。 */
|
|
311
|
+
saveUpload(bytes: Uint8Array, name: string, folderId?: string): Promise<Asset>;
|
|
312
|
+
/** 读上传资产字节(名字不合法 / 不存在 → undefined) */
|
|
313
|
+
readFile(hashName: string): Promise<Uint8Array<ArrayBuffer> | undefined>;
|
|
314
|
+
remove(id: string): Promise<boolean>;
|
|
315
|
+
/** 资产挪到某个文件夹(folderId 传空 = 回根目录) */
|
|
316
|
+
setAssetFolder(id: string, folderId?: string): Promise<Asset | undefined>;
|
|
317
|
+
/**
|
|
318
|
+
* 整组资产挪到某个文件夹(批量「移动到 / 添加到」共用)。
|
|
319
|
+
*
|
|
320
|
+
* 整组**一次**读改写,而不是逐条 setAssetFolder:逐条会让「读—写」来回 N 趟,
|
|
321
|
+
* 中间夹进来的并发写照样能覆盖(与批量删除同一条病)。
|
|
322
|
+
*/
|
|
323
|
+
setAssetsFolder(ids: string[], folderId?: string): Promise<number>;
|
|
324
|
+
/** 覆盖式设置标签(固定清单,前端约束) */
|
|
325
|
+
setAssetTags(id: string, tags: string[]): Promise<Asset | undefined>;
|
|
326
|
+
/** 资产改名 */
|
|
327
|
+
renameAsset(id: string, name: string): Promise<Asset | undefined>;
|
|
328
|
+
/** 画布被删时,摘掉它名下的生成产物登记(上传的资产与画布无关,不动) */
|
|
329
|
+
removeByCanvas(canvasId: string): Promise<void>;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** 批量增删改的结果(与 mcp-server 的 BatchResult 同形状,便于客户端迁移) */
|
|
333
|
+
export declare interface BatchResult {
|
|
334
|
+
ok: boolean;
|
|
335
|
+
added: string[];
|
|
336
|
+
deleted: string[];
|
|
337
|
+
updated: string[];
|
|
338
|
+
errors: {
|
|
339
|
+
op: string;
|
|
340
|
+
index: number;
|
|
341
|
+
message: string;
|
|
342
|
+
}[];
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* 扫描插件目录,生成清单条目。
|
|
347
|
+
*
|
|
348
|
+
* 收录条件(三条都要满足,宁可少列也不要列出装不上的):
|
|
349
|
+
* 1. `dist/` 下存在 .js(源码包不算:浏览器装不了 .ts);
|
|
350
|
+
* 2. 该产物是**可以按 URL 直接 import 的 ES 模块**(见 looksLikeEsm);
|
|
351
|
+
* 3. 目录名不以 `_`/`.` 开头。
|
|
352
|
+
*
|
|
353
|
+
* 为什么第 2 条必须卡住:画布那边的加载路径是 fetch 文本 → `import(data:text/javascript,...)`。
|
|
354
|
+
* 仓库里多数插件打的是 UMD(给 `<script>` 用,靠全局 Vue/VueFlow 注入),这种产物走 data: URL
|
|
355
|
+
* 会**在加载时直接抛错**。把它们列进清单只会让画布每次开都在 console 里刷一串告警,
|
|
356
|
+
* 却什么也没装上——不如不列。想被外部装载,就把该插件改成 `formats: ['es']`(参考 plugin-cloud-client)。
|
|
357
|
+
*/
|
|
358
|
+
export declare function buildManifest(pluginsDir: string | undefined): Promise<ManifestPluginEntry[]>;
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* 扫插件目录,生成插件管理要的清单。
|
|
362
|
+
*
|
|
363
|
+
* 入参可以是**单个目录**(兼容旧调用),也可以是两级根(全局优先、随包兜底)。
|
|
364
|
+
* 后者是 2026-11-12 的口径:同一个插件在两个目录里都有时,**全局那份生效**,
|
|
365
|
+
* 首启不再把随包插件复制到全局目录。
|
|
366
|
+
*/
|
|
367
|
+
export declare function buildPluginCatalog(pluginsDir: string | PluginRoots | undefined): Promise<PluginCatalog>;
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* `ctx.canUninstall(name)` 的判定结果(决策 1:调用方"先问再动")。
|
|
371
|
+
*
|
|
372
|
+
* 为什么要这个三态而不是布尔:`uninstallPlugin` 沿用既有契约返回 `false`,但 `false` 既可能是
|
|
373
|
+
* "核心插件不让卸"也可能是"根本没这个插件"——不区分原因就会写出"先删了配置才发现卸不动"的副作用。
|
|
374
|
+
*/
|
|
375
|
+
declare type CanUninstallResult = {
|
|
376
|
+
ok: true;
|
|
377
|
+
} | {
|
|
378
|
+
ok: false;
|
|
379
|
+
reason: 'core' | 'not-found' | 'not-started';
|
|
380
|
+
};
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* 一次画布变更(写成功后发出)。
|
|
384
|
+
*
|
|
385
|
+
* 为什么要有:实时通道(SSE)原本靠 KvStore 的写事件驱动,而画布数据**已经不经过 kv 了**。
|
|
386
|
+
* 没有这个信号,AI 改完画布网页端永远收不到通知 —— 得手动刷新才看得见。
|
|
387
|
+
*/
|
|
388
|
+
declare interface CanvasChangeEvent {
|
|
389
|
+
canvasId: string;
|
|
390
|
+
/** 变了哪一块:本体(节点 + 边,一起住 canvas.json)还是视口 */
|
|
391
|
+
key: 'graph' | 'graph-edges' | 'graph-viewport';
|
|
392
|
+
/** 本次图提交后的版本;视口事件不带(视口不是图内容) */
|
|
393
|
+
revision?: number;
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/** 画布本体。name / createdAt 是画布信息,随节点边一起住 canvas.json */
|
|
397
|
+
export declare interface CanvasData {
|
|
398
|
+
nodes: unknown[];
|
|
399
|
+
edges: unknown[];
|
|
400
|
+
name?: string;
|
|
401
|
+
createdAt?: number;
|
|
402
|
+
/**
|
|
403
|
+
* 画布**图**版本(只增不减)。前端定时核对靠它发现“漏了一帧通知”。
|
|
404
|
+
* 只在图(节点/边)真正提交时递增;改名 / 视口 / 纯读取都不动它。
|
|
405
|
+
* 旧文件没有这个字段时按 0 读(见 readCanvas)。
|
|
406
|
+
*/
|
|
407
|
+
revision?: number;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/** 某个画布的目录 */
|
|
411
|
+
export declare function canvasDir(root: string, id: string): string;
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* CanvasDocument 的最小用面(工具只用到这几个方法)。
|
|
415
|
+
*
|
|
416
|
+
* 抽成接口是为了「按画布取文档」—— 默认画布用服务启动时建好的那一个实例,
|
|
417
|
+
* 其它画布每次现建一个(轻量对象,内部只是拼路径)。
|
|
418
|
+
*/
|
|
419
|
+
declare interface CanvasDocLike {
|
|
420
|
+
read(): Promise<{
|
|
421
|
+
nodes: Array<{
|
|
422
|
+
id: string;
|
|
423
|
+
type: string;
|
|
424
|
+
data?: Record<string, unknown>;
|
|
425
|
+
}>;
|
|
426
|
+
edges: Array<{
|
|
427
|
+
source: string;
|
|
428
|
+
target: string;
|
|
429
|
+
}>;
|
|
430
|
+
viewport?: unknown;
|
|
431
|
+
}>;
|
|
432
|
+
/** 返回值里 `url` 是**同源 URL**(`/api/canvases/<画布id>/resources/<哈希>`) */
|
|
433
|
+
saveResource(bytes: Uint8Array, opts?: {
|
|
434
|
+
fileName?: string;
|
|
435
|
+
mime?: string;
|
|
436
|
+
}): Promise<{
|
|
437
|
+
url: string;
|
|
438
|
+
size: number;
|
|
439
|
+
mime: string;
|
|
440
|
+
}>;
|
|
441
|
+
listResources(): Promise<string[]>;
|
|
442
|
+
/**
|
|
443
|
+
* 带类型信息的资源清单(可选:老调用方 / 极简替身不一定实现)。
|
|
444
|
+
* 缺了时 resource_list 退回 listResources + 本地拼 —— 但拿不到 mime/kind,前端只能按名字猜。
|
|
445
|
+
*/
|
|
446
|
+
listResourceInfos?(): Promise<Array<{
|
|
447
|
+
name: string;
|
|
448
|
+
mime: string;
|
|
449
|
+
kind: 'image' | 'video' | 'audio' | 'other';
|
|
450
|
+
url: string;
|
|
451
|
+
}>>;
|
|
452
|
+
batchNodes(input: unknown): Promise<{
|
|
453
|
+
ok: boolean;
|
|
454
|
+
added: string[];
|
|
455
|
+
deleted: string[];
|
|
456
|
+
updated: string[];
|
|
457
|
+
errors: Array<{
|
|
458
|
+
message: string;
|
|
459
|
+
}>;
|
|
460
|
+
}>;
|
|
461
|
+
batchEdges(input: unknown): Promise<{
|
|
462
|
+
ok: boolean;
|
|
463
|
+
added: string[];
|
|
464
|
+
deleted: string[];
|
|
465
|
+
updated: string[];
|
|
466
|
+
errors: Array<{
|
|
467
|
+
message: string;
|
|
468
|
+
}>;
|
|
469
|
+
}>;
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
/** 按画布 id 取文档;返回 undefined = 该画布不存在(工具据此报错,而不是悄悄写进 default) */
|
|
473
|
+
declare type CanvasDocResolver = (canvasId: string) => Promise<CanvasDocLike | undefined> | CanvasDocLike | undefined;
|
|
474
|
+
|
|
475
|
+
export declare class CanvasDocument {
|
|
476
|
+
private readonly store;
|
|
477
|
+
private readonly resources?;
|
|
478
|
+
private readonly canvasId;
|
|
479
|
+
/**
|
|
480
|
+
* @param store 画布文件夹(canvas.json / view.json)
|
|
481
|
+
* @param resources 本画布资源(节点里存逻辑 ID `<画布id>/<hash>`;迁移期旧同源 URL 仍可读)
|
|
482
|
+
* @param canvasId 画布 id(前端界面当前只有一张,默认 default)
|
|
483
|
+
*/
|
|
484
|
+
constructor(store: CanvasStore, resources?: CanvasResourceStore | undefined, canvasId?: string);
|
|
485
|
+
/**
|
|
486
|
+
* 写操作串行链(见 runExclusive 的说明)。
|
|
487
|
+
*
|
|
488
|
+
* 只对「写」串行,读不加锁 —— 读不会让数据变坏,没必要跟着排队。
|
|
489
|
+
*/
|
|
490
|
+
private lock;
|
|
491
|
+
/**
|
|
492
|
+
* 把一次写操作排进串行链,返回它自己的结果。
|
|
493
|
+
*
|
|
494
|
+
* 为什么必须有:本对象的写都是「读全量 → 改 → 写全量」。两个写方(AI 与网页端)
|
|
495
|
+
* 若同时进来,会各自读到同一份旧数据、再各自写回只有自己那点改动的结果,**后写的把先写的整个盖掉**
|
|
496
|
+
* (AI 刚加的节点凭空消失)。排成一条链后,后一个跑在「前一个的结果」上,两边都在。
|
|
497
|
+
*
|
|
498
|
+
* 注意:本锁只在**同一个进程**内有效。这是自托管单进程服务(AI 与网页共用一个服务),
|
|
499
|
+
* 够用;若将来要跑多进程,得换成文件锁或真正的数据库事务。
|
|
500
|
+
*/
|
|
501
|
+
private runExclusive;
|
|
502
|
+
/**
|
|
503
|
+
* 存一个资源(图片/视频等字节),返回**同源 URL**。
|
|
504
|
+
*
|
|
505
|
+
* 为什么 MCP 需要这个:AI 要往画布里放图,得先把字节交给服务器 —— 否则节点里只能写
|
|
506
|
+
* 一个外链(可能挂、可能跨域、用户换机器就取不到)。
|
|
507
|
+
*
|
|
508
|
+
* 节点里现在存 **URL**(`/api/canvases/<画布id>/resources/<hash>`,浏览器直接就能请求):
|
|
509
|
+
* 渲染、下单、资产登记都不必再拼一次地址。
|
|
510
|
+
*/
|
|
511
|
+
saveResource(bytes: Uint8Array, opts?: {
|
|
512
|
+
fileName?: string;
|
|
513
|
+
mime?: string;
|
|
514
|
+
}): Promise<{
|
|
515
|
+
hashName: string;
|
|
516
|
+
url: string;
|
|
517
|
+
size: number;
|
|
518
|
+
mime: string;
|
|
519
|
+
}>;
|
|
520
|
+
/** 列出本画布已存资源(AI 排查"我传的图在不在"用) */
|
|
521
|
+
listResources(): Promise<string[]>;
|
|
522
|
+
/**
|
|
523
|
+
* 带**类型信息**的资源清单(给 MCP 的 resource_list 用)。
|
|
524
|
+
*
|
|
525
|
+
* 为什么不能只给文件名:资源按内容哈希落盘、很多没有扩展名 —— 调用方拿到一串名字
|
|
526
|
+
* 只能拿名字猜类型,音频会被塞进 `<img>` 当图片渲染,表现就是裂图(用户报过)。
|
|
527
|
+
* 这里把 mime / kind 一并给出,调用方照着 kind 决定怎么展示。
|
|
528
|
+
*
|
|
529
|
+
* mime 先按扩展名(便宜的查表);查不出(octet-stream = 没扩展名)时才开文件读**前 16 字节**嗅探
|
|
530
|
+
* —— 只读头部,不整读(资源里有不少几 MB 的图,列表一次要判几十个)。
|
|
531
|
+
*/
|
|
532
|
+
listResourceInfos(): Promise<Array<{
|
|
533
|
+
name: string;
|
|
534
|
+
mime: string;
|
|
535
|
+
kind: 'image' | 'video' | 'audio' | 'other';
|
|
536
|
+
url: string;
|
|
537
|
+
}>>;
|
|
538
|
+
/** 读整张画布。从未保存过 = 空画布(不是错误) */
|
|
539
|
+
read(): Promise<CanvasSnapshot>;
|
|
540
|
+
/**
|
|
541
|
+
* 只读图版本(客户端定时核对用)。
|
|
542
|
+
* 画布不存在时返回 undefined,由路由翻译成 404 —— 不要用 0 冒充“存在但为空”。
|
|
543
|
+
*/
|
|
544
|
+
readRevision(): Promise<number | undefined>;
|
|
545
|
+
/**
|
|
546
|
+
* 写整张画布。
|
|
547
|
+
* 只写 nodes/edges 两个 key(**不碰 viewport**:AI 编辑不该重置用户当前视野)。
|
|
548
|
+
*/
|
|
549
|
+
write(snapshot: {
|
|
550
|
+
nodes: CanvasNode[];
|
|
551
|
+
edges: CanvasEdge[];
|
|
552
|
+
}): Promise<void>;
|
|
553
|
+
/**
|
|
554
|
+
* 图提交的唯一入口(已持锁时调用):先判断节点/边**确实变了**,再发 revision + 1,
|
|
555
|
+
* 并把 `{nodes, edges, revision}` 作为**同一次 canvas.json 原子写**落盘。
|
|
556
|
+
*
|
|
557
|
+
* 为什么必须在这里、而不是 CanvasStore.writeCanvas:
|
|
558
|
+
* - 那是通用写口,改名 / 复制也走它,无法判断“这是不是一次有效图变更”;
|
|
559
|
+
* - 版本号必须与图数据同一次原子写,且只由一个地方发号;
|
|
560
|
+
* - 空操作(如 lenient 删除不存在的边)不能涨版本,否则客户端会做无意义整包拉取。
|
|
561
|
+
*
|
|
562
|
+
* @returns 这次是否真的写盘(无变化时返回 false,调用方可据此跳过通知)
|
|
563
|
+
*/
|
|
564
|
+
private commitGraph;
|
|
565
|
+
/**
|
|
566
|
+
* 「以这份为准」整体重写(网页端整包保存走这条)。
|
|
567
|
+
*
|
|
568
|
+
* 与 batchNodes 的区别:batch 是「在现有画布上增删改」,这条是「整个换成我这份」。
|
|
569
|
+
* 用户删光节点、恢复历史、导入画布这类操作必须用它 —— 用 batch 表达不出
|
|
570
|
+
* 「删掉你没提到的那些」。同样进串行链:否则它与 AI 的增量写并发时会互相覆盖。
|
|
571
|
+
*/
|
|
572
|
+
replaceAll(nodes: unknown[], edges: unknown[]): Promise<void>;
|
|
573
|
+
/**
|
|
574
|
+
* 视图状态(视口)整体改写。
|
|
575
|
+
*
|
|
576
|
+
* 与 `write`(画布本体)分开:改动视野不该重写整份节点边。
|
|
577
|
+
* 同样进串行链 —— 它也是一次落盘。
|
|
578
|
+
*/
|
|
579
|
+
writeView(view: unknown): Promise<void>;
|
|
580
|
+
/** 读视口(宿主恢复视野用) */
|
|
581
|
+
readView<T = {
|
|
582
|
+
x: number;
|
|
583
|
+
y: number;
|
|
584
|
+
zoom: number;
|
|
585
|
+
}>(): Promise<T | undefined>;
|
|
586
|
+
/**
|
|
587
|
+
* 给新增节点挑一个"不压在别人身上"的位置(没显式给 position 时用)。
|
|
588
|
+
* 规则:摆在现有节点右侧一段距离,纵向对齐最上面那个。让 AI 建出来的节点一眼能看见。
|
|
589
|
+
*/
|
|
590
|
+
private nextFreePosition;
|
|
591
|
+
/**
|
|
592
|
+
* 生成一个不与现有节点冲突的节点 id:**自增数字**(与网页端同一套规则)。
|
|
593
|
+
*
|
|
594
|
+
* 过去用 `ai-` 前缀是为了和网页端的数字 id 区分开;现在两边统一成数字了,
|
|
595
|
+
* AI 建的节点与网页建的节点就是同一种东西(用户要求:AI 加节点不必自己指定 id,
|
|
596
|
+
* 由服务端发号并在 added 里回给调用方)。
|
|
597
|
+
*/
|
|
598
|
+
private newNodeId;
|
|
599
|
+
/**
|
|
600
|
+
* 给 MCP 新建的节点补一个默认名(写进 data.label),与网页端"图片 1"同款。
|
|
601
|
+
*
|
|
602
|
+
* 语义与前端 nodeStore.nextDefaultName 对齐:
|
|
603
|
+
* - 名字 = `<类型中文名> <序号>`,序号**按类型独立计数**;
|
|
604
|
+
* - 序号从**现有同类型节点的名字**里推断(找名字末尾的数字取最大),所以
|
|
605
|
+
* "先由 AI 建两个图片、再让 AI 建第三个"会得到「图片 3」,而不是从头开始;
|
|
606
|
+
* - 调用方已显式给 label 时不生成(尊重调用方的名字)。
|
|
607
|
+
*
|
|
608
|
+
* 为什么在这里做、而不是让前端补:MCP 写的是同一份 canvas.json,写进去就该是完整的;
|
|
609
|
+
* 等前端补等于"没打开页面时建的节点永远没名字"。
|
|
610
|
+
*/
|
|
611
|
+
private defaultNodeName;
|
|
612
|
+
/**
|
|
613
|
+
* 生成一个不与现有边冲突的 id:**自增数字**(与网页端同一套规则)。
|
|
614
|
+
*
|
|
615
|
+
* 为什么不沿用过去的 `e-{source}-{target}`:那边 id 形态五花八门(见 canvas-data 的 edgeStore),
|
|
616
|
+
* 现在统一成数字,AI 建的边与网页建的边才是同一种东西。取「现有最大数字 + 1」,
|
|
617
|
+
* 并跳过已被其它 id 占用的号。
|
|
618
|
+
*/
|
|
619
|
+
private nextEdgeId;
|
|
620
|
+
/**
|
|
621
|
+
* 节点批量增删改(一次调用合并执行)。
|
|
622
|
+
*
|
|
623
|
+
* 语义与 mcp-server 的 canvas_batch_nodes 对齐:**先整体预校验,再按 delete→add→update 应用**。
|
|
624
|
+
* 预校验不过就整批拒绝、一个都不动 —— 半成品最难查(AI 以为改成功了,画布却是错的)。
|
|
625
|
+
*/
|
|
626
|
+
batchNodes(input: NodeBatchInput): Promise<BatchResult>;
|
|
627
|
+
/** batchNodes 的实际实现(已持锁:内部读写都看同一份缓存,不受并发干扰) */
|
|
628
|
+
private batchNodesLocked;
|
|
629
|
+
/**
|
|
630
|
+
* 输出类型改过之后,把**已经不合规**的连线断掉。
|
|
631
|
+
*
|
|
632
|
+
* 用户 2026-11-17 的口径:可视化节点原来输出图片、下游连着图片节点;把 uiOutputType 改成
|
|
633
|
+
* 音频后,那条线就不成立了 —— 必须自动断开,不能留一条点不动的线。
|
|
634
|
+
*
|
|
635
|
+
* 为什么后台也要有一份:网页端在 GraphDocument 里做(updateNode 后自动 prune),
|
|
636
|
+
* 但 AI 经 MCP、任务脚本经增量口写节点时**不经过网页端**。只做一边的话,
|
|
637
|
+
* 「网页上连着的时候 AI 改了类型」会留下一条脏边,直到用户刷新才被前端清掉。
|
|
638
|
+
*
|
|
639
|
+
* 规则刻意只有一条、且与前端同一口径:只有 `type === 'ui'` 的节点,输出类型读
|
|
640
|
+
* `data.uiOutputType`(image / video / audio / text);空或认不出 = 没有输出口。
|
|
641
|
+
* 上游输入口收这些类型;下游输入口如果声明了能收哪些类型(这里没有类型注册表,
|
|
642
|
+
* 只能按已知的四类节点判断),不匹配就删边。
|
|
643
|
+
*/
|
|
644
|
+
private pruneEdgesForOutputType;
|
|
645
|
+
/**
|
|
646
|
+
* 连线批量增删改。语义与 batchNodes 一致(先预校验,再 delete→add→update)。
|
|
647
|
+
* 新增时会校验两端节点存在,且不允许自连 —— 不然画出一堆孤儿边,渲染层还得兜。
|
|
648
|
+
*/
|
|
649
|
+
batchEdges(input: EdgeBatchInput): Promise<BatchResult>;
|
|
650
|
+
/** batchEdges 的实际实现(已持锁) */
|
|
651
|
+
private batchEdgesLocked;
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/** 画布连线 */
|
|
655
|
+
export declare interface CanvasEdge {
|
|
656
|
+
id: string;
|
|
657
|
+
source: string;
|
|
658
|
+
target: string;
|
|
659
|
+
type?: string;
|
|
660
|
+
sourceHandle?: string;
|
|
661
|
+
targetHandle?: string;
|
|
662
|
+
data?: Record<string, unknown>;
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
/** 全部画布的父目录(列目录用;不涉及具体 id) */
|
|
666
|
+
export declare function canvasesRoot(root: string): string;
|
|
667
|
+
|
|
668
|
+
export declare function canvasesRoutes(store: CanvasStore, resources: CanvasResourceStore, doc: CanvasDocument,
|
|
669
|
+
/**
|
|
670
|
+
* 按画布 id 取该画布的文档(多画布)。
|
|
671
|
+
*
|
|
672
|
+
* **不传 = 只服务默认画布**(老宿主 / 旧测试):此时对别的 id 一律 404,
|
|
673
|
+
* 而不是静默写进默认画布 —— 那正是 2026-10-14 真机踩到的坑:
|
|
674
|
+
* `PUT /api/canvases/<别的画布>` 被当成了「写 default」,把用户那张默认画布整份覆盖掉。
|
|
675
|
+
*/
|
|
676
|
+
docForCanvas?: (canvasId: string) => CanvasDocument | undefined,
|
|
677
|
+
/**
|
|
678
|
+
* 资源上传的额外放行判定(可选)。
|
|
679
|
+
*
|
|
680
|
+
* 任务脚本(`plugin-node-ui` 的子进程)写产物就是走这条路由;子进程拿不到管理令牌,
|
|
681
|
+
* 也不该拿。所以由宿主注入一个「只允许写本节点槽位」的判定:看 `x-task-token`,
|
|
682
|
+
* 校验它是否等于本节点脚本执行令牌,并且请求必须带 `slot`。
|
|
683
|
+
* 不传 = 不额外放行(行为与旧版一致)。
|
|
684
|
+
*/
|
|
685
|
+
allowTaskUpload?: (input: {
|
|
686
|
+
token: string | undefined;
|
|
687
|
+
canvasId: string;
|
|
688
|
+
slot: string | undefined;
|
|
689
|
+
}) => boolean): Hono;
|
|
690
|
+
|
|
691
|
+
/**
|
|
692
|
+
* 三个数据文件的路径。
|
|
693
|
+
* `which` 是闭合词表(不是任意文件名)—— 调用方传不进来自外部的字符串,杜绝任意路径写入。
|
|
694
|
+
*/
|
|
695
|
+
export declare function canvasFilePath(root: string, id: string, which: 'canvas' | 'view' | 'history'): string;
|
|
696
|
+
|
|
697
|
+
/** 画布节点(与 @plume-canvas/canvas-data 的同名字段对齐;这里只留数据层用得到的) */
|
|
698
|
+
export declare interface CanvasNode {
|
|
699
|
+
id: string;
|
|
700
|
+
type: string;
|
|
701
|
+
position: {
|
|
702
|
+
x: number;
|
|
703
|
+
y: number;
|
|
704
|
+
};
|
|
705
|
+
data: Record<string, unknown>;
|
|
706
|
+
/** 声明尺寸(可选;渲染层实测尺寸不进这里) */
|
|
707
|
+
size?: {
|
|
708
|
+
w: number;
|
|
709
|
+
h: number;
|
|
710
|
+
};
|
|
711
|
+
/** 父节点(分组嵌套,可选) */
|
|
712
|
+
parentId?: string;
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/** 某个画布的资源目录 */
|
|
716
|
+
export declare function canvasResourcesDir(root: string, id: string): string;
|
|
717
|
+
|
|
718
|
+
export declare class CanvasResourceStore {
|
|
719
|
+
private readonly root;
|
|
720
|
+
constructor(root: string);
|
|
721
|
+
/**
|
|
722
|
+
* 存一个资源;同内容不重复写。返回**同源 URL**(写进节点 data 的那个)与磁盘名。
|
|
723
|
+
*
|
|
724
|
+
* 这里就返回 URL 而不是 `res:<hash>`:写入侧只有这一个出口,统一了才不会有人漏改。
|
|
725
|
+
*/
|
|
726
|
+
save(canvasId: string, bytes: Uint8Array, ext?: string): Promise<SavedResource>;
|
|
727
|
+
/**
|
|
728
|
+
* **把字节覆盖到某个槽位**(同一个槽位永远同一份文件,内容直接被换掉)。
|
|
729
|
+
*
|
|
730
|
+
* ## 为什么要有它(与 save 的区别)
|
|
731
|
+
*
|
|
732
|
+
* `save` 是内容寻址:内容一变就是**新文件**,天然去重、地址可长缓存。
|
|
733
|
+
* 但「可视化节点的输出」不行 —— 用户画一笔就要出一份新图,内容寻址会让磁盘上
|
|
734
|
+
* 每笔多一个文件(画 100 笔 = 100 个文件,而这些历史版本一个都不需要)。
|
|
735
|
+
*
|
|
736
|
+
* 所以另开一条:**按槽位固定命名、原地覆盖**。一个节点一个槽位,永远只有最新一份。
|
|
737
|
+
* 参数化扩展名,图片 / 视频 / 音频共用同一条路(slot-<节点id>.png / .mp4 / .mp3)。
|
|
738
|
+
*
|
|
739
|
+
* 代价(必须知道):URL 不变而内容会变 —— 所以读取侧**不能长缓存**,
|
|
740
|
+
* 见 routes/canvases.ts 里按 isSlotName 分流的 cache-control。
|
|
741
|
+
*/
|
|
742
|
+
saveSlot(canvasId: string, slotId: string, bytes: Uint8Array, ext?: string): Promise<SavedResource>;
|
|
743
|
+
/** 读本画布某个资源;名字不合法或不存在 → undefined */
|
|
744
|
+
read(canvasId: string, hashName: string): Promise<Uint8Array<ArrayBuffer> | undefined>;
|
|
745
|
+
/**
|
|
746
|
+
* 只读文件头 n 字节(类型嗅探用,见 mime.sniffMimeFromHead)。
|
|
747
|
+
*
|
|
748
|
+
* 为什么不复用 read:资源里有不少几 MB 的图,只为了判个类型把整张读进内存纯属浪费
|
|
749
|
+
* (列表接口一次要判几十个)。名字不合法 / 不存在 → undefined(与 read 同口径)。
|
|
750
|
+
*/
|
|
751
|
+
readHead(canvasId: string, hashName: string, n?: number): Promise<Uint8Array | undefined>;
|
|
752
|
+
/** 列本画布的资源名 */
|
|
753
|
+
list(canvasId: string): Promise<string[]>;
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
/** 画布全量快照 */
|
|
757
|
+
export declare interface CanvasSnapshot {
|
|
758
|
+
nodes: CanvasNode[];
|
|
759
|
+
edges: CanvasEdge[];
|
|
760
|
+
viewport?: {
|
|
761
|
+
x: number;
|
|
762
|
+
y: number;
|
|
763
|
+
zoom: number;
|
|
764
|
+
};
|
|
765
|
+
/** 画布图版本(旧文件没有时是 0);前端定时核对靠它 */
|
|
766
|
+
revision: number;
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
export declare class CanvasStore {
|
|
770
|
+
private readonly root;
|
|
771
|
+
private readonly listeners;
|
|
772
|
+
/**
|
|
773
|
+
* 每个文件一条写链。
|
|
774
|
+
*
|
|
775
|
+
* 为什么必须在这一层做(与 KvStore 同款问题、同款解法):写是「写临时文件 → rename 到目标」
|
|
776
|
+
* 两步,而 **Windows 上两个 rename 打同一个目标会直接 EPERM**("另一个程序正在使用此文件")。
|
|
777
|
+
* CanvasDocument 上层虽有写锁,但它只覆盖画布写路径,而这里的地基是**所有**画布文件写
|
|
778
|
+
* (canvas.json / view.json)。实测过:并发写时偶发 500,重试一次就好了 —— 与其赌运气,
|
|
779
|
+
* 不如把同文件的写排成一条链,再对残余的瞬时占用做几次退避重试。
|
|
780
|
+
*/
|
|
781
|
+
private readonly writeChains;
|
|
782
|
+
constructor(root: string);
|
|
783
|
+
/**
|
|
784
|
+
* 数据根目录(`<root>/canvases/<id>` 的上一级)。
|
|
785
|
+
*
|
|
786
|
+
* 为什么暴露它:外挂后台插件(如可视化节点的任务脚本)要**与画布并列**地找自己的目录
|
|
787
|
+
* (`<root>/task-scripts`),而它拿不到服务注入的其它路径名 ——
|
|
788
|
+
* 少了这个入口,它就只能猜(猜错的后果是"非默认画布里的节点一个脚本都扫不到",
|
|
789
|
+
* 表现为"导出这个节点,包里一个脚本都没有",2026-10-13 用户实测)。
|
|
790
|
+
*/
|
|
791
|
+
dataRoot(): string;
|
|
792
|
+
/** 把一次写排进「同文件串行」的链尾(不同文件互不影响) */
|
|
793
|
+
private runFor;
|
|
794
|
+
/** 订阅「某张画布被写过」。返回取消订阅函数。 */
|
|
795
|
+
onChange(listener: (e: CanvasChangeEvent) => void): () => void;
|
|
796
|
+
/** 广播变更;单个订阅者抛错不影响其它订阅者,也不影响这次写 */
|
|
797
|
+
private notify;
|
|
798
|
+
/** 读画布本体;没存过返回 undefined */
|
|
799
|
+
readCanvas(id: string): Promise<CanvasData | undefined>;
|
|
800
|
+
/**
|
|
801
|
+
* 写画布本体。
|
|
802
|
+
*
|
|
803
|
+
* 画布信息要**继承**:调用方通常只交来节点与边,若每次都重建对象,
|
|
804
|
+
* 名字与创建时间会被悄悄抹掉。所以先读旧值,缺的字段用旧的补。
|
|
805
|
+
*/
|
|
806
|
+
writeCanvas(id: string, data: CanvasData): Promise<void>;
|
|
807
|
+
/** 读视口;没存过返回 undefined */
|
|
808
|
+
readView<T = {
|
|
809
|
+
x: number;
|
|
810
|
+
y: number;
|
|
811
|
+
zoom: number;
|
|
812
|
+
}>(id: string): Promise<T | undefined>;
|
|
813
|
+
writeView(id: string, view: unknown): Promise<void>;
|
|
814
|
+
/**
|
|
815
|
+
* 只改画布名(不读-改-写整张画布)。
|
|
816
|
+
*
|
|
817
|
+
* 为什么单开:改名与图提交是两条不同的业务。若先 readCanvas 再整包写回,
|
|
818
|
+
* 中间发生的图提交会被旧 nodes/edges 覆盖;而且 revision 不能因为改名而涨。
|
|
819
|
+
* 画布不存在返回 false(由路由决定是否 404)。
|
|
820
|
+
*/
|
|
821
|
+
writeName(id: string, name: string): Promise<boolean>;
|
|
822
|
+
/** 列出全部画布 id(目录不存在 = 还没有画布,返回空数组而不是抛错) */
|
|
823
|
+
list(): Promise<string[]>;
|
|
824
|
+
/**
|
|
825
|
+
* 删掉一张画布的整个文件夹(画布本体 / 视口 / 历史 / 资源 / agent 会话一起没)。
|
|
826
|
+
* 目录不存在也算删成功(幂等)。
|
|
827
|
+
*/
|
|
828
|
+
remove(id: string): Promise<void>;
|
|
829
|
+
/**
|
|
830
|
+
* 把一张画布的内容**复制进另一张已存在的画布文件夹**(「复制画布」用)。
|
|
831
|
+
*
|
|
832
|
+
* 复制的范围:节点 + 边 + 资源字节 + 生成历史。
|
|
833
|
+
* **视口不复制** —— 复制是为了分享内容,不是分享「我当时看到哪儿」(设计文档已定)。
|
|
834
|
+
*
|
|
835
|
+
* 关键一步是**把资源引用改到新画布**,两种形态都要处理:
|
|
836
|
+
* - 新逻辑 ID `<画布id>/<哈希>`(节点 `data.resourceId` 的唯一形态)→ 换前缀;
|
|
837
|
+
* - 旧同源 URL `/api/canvases/<画布id>/resources/<哈希>`(迁移期存档)→ 换 URL 里的 id。
|
|
838
|
+
*
|
|
839
|
+
* 不换的话副本里的图全都指回原画布(原画布一删,副本全裂)。换掉之后副本自包含,
|
|
840
|
+
* 与「复制文件夹 = 复制画布」同义。
|
|
841
|
+
*/
|
|
842
|
+
copyInto(fromId: string, toId: string, name?: string): Promise<void>;
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
/** 能力层:把"能力段 / 内置服务 / 配置登记"这三件事交给上层实现。 */
|
|
846
|
+
declare interface CapabilityLayer {
|
|
847
|
+
/**
|
|
848
|
+
* 为某个 ctx 视图产出能力段(会被 Object.assign 到该视图上)。
|
|
849
|
+
* 根上下文 scopeName="<host>",插件用插件名。
|
|
850
|
+
*/
|
|
851
|
+
buildSegments(ctx: PluginScope, scopeName: string): Record<string, unknown>;
|
|
852
|
+
/**
|
|
853
|
+
* 内置服务实例(名 → 实例)。语义:ctx.get 恒可取到、依赖判定恒满足、
|
|
854
|
+
* 不进服务表(因此不与 inject/provide 的重名检查冲突)。
|
|
855
|
+
*/
|
|
856
|
+
builtins(): Record<string, unknown>;
|
|
857
|
+
/**
|
|
858
|
+
* 生命周期重置(ctx.stop 时调用):由实现决定哪些内置服务重建、哪些跨 stop 保留。
|
|
859
|
+
* 插件副作用已随各自 fiber 回收,这里只清"表内残留"。
|
|
860
|
+
*/
|
|
861
|
+
reset(): void;
|
|
862
|
+
/**
|
|
863
|
+
* 把插件 Config schema 的标量字段登记进"配置单一数据源"(供 UI 面板长控件)。
|
|
864
|
+
* @param dev 开发态(可给冲突告警)
|
|
865
|
+
* @returns 随该插件回收的清理函数(由框架登记进插件 fiber)
|
|
866
|
+
*/
|
|
867
|
+
declareConfig(schema: ConfigSchema, config: Record<string, unknown>, pluginName: string, dev: boolean): () => void;
|
|
868
|
+
}
|
|
869
|
+
|
|
870
|
+
/** 把清单折成一个 32 位整数版本号(同内容同号,改了内容就变) */
|
|
871
|
+
export declare function catalogVersion(entries: PluginCatalogEntry[]): number;
|
|
872
|
+
|
|
873
|
+
export declare interface CloudServer {
|
|
874
|
+
/** Hono 应用(测试可直接 app.fetch(new Request(...)),不必启端口) */
|
|
875
|
+
app: Hono;
|
|
876
|
+
/**
|
|
877
|
+
* 内核上下文(后台插件系统的宿主 ctx)。
|
|
878
|
+
* 暴露它用途有二:① 测试里验证「路由确实由插件提供」(卸载即失效);
|
|
879
|
+
* ② 将来宿主想动态装卸后台插件(热装需重建 app,见计划 §九)。
|
|
880
|
+
*/
|
|
881
|
+
ctx: Context;
|
|
882
|
+
/** 启服务;resolve 后服务已在监听 */
|
|
883
|
+
start(): Promise<{
|
|
884
|
+
port: number;
|
|
885
|
+
url: string;
|
|
886
|
+
}>;
|
|
887
|
+
/** 停服务 */
|
|
888
|
+
stop(): void;
|
|
889
|
+
/** 解析后的实际路径(启动时用于打印,便于确认数据落在哪) */
|
|
890
|
+
paths: {
|
|
891
|
+
data: string;
|
|
892
|
+
kv: string;
|
|
893
|
+
canvases: string;
|
|
894
|
+
providers: string;
|
|
895
|
+
ui?: string;
|
|
896
|
+
plugins?: string;
|
|
897
|
+
};
|
|
898
|
+
/** MCP 是否开着 */
|
|
899
|
+
mcpEnabled: boolean;
|
|
900
|
+
/** 开放的 MCP 工具清单(关闭时为空数组) */
|
|
901
|
+
tools: readonly {
|
|
902
|
+
name: string;
|
|
903
|
+
description: string;
|
|
904
|
+
}[];
|
|
905
|
+
/** 管理令牌(启动日志与前端手填用;`adminAuthEnabled=false` 时为空串) */
|
|
906
|
+
adminToken: string;
|
|
907
|
+
/** 令牌来源:env 固定 / 数据根文件 / 已关闭 */
|
|
908
|
+
adminTokenSource: 'env' | 'file' | 'disabled';
|
|
909
|
+
/** 令牌文件路径(env 固定令牌时为 null) */
|
|
910
|
+
adminTokenFile: string | null;
|
|
911
|
+
/** 实际生效的 Host / Origin 白名单(启动日志要逐行打印,配错时能一眼看出来) */
|
|
912
|
+
trust: {
|
|
913
|
+
hosts: string[];
|
|
914
|
+
origins: string[];
|
|
915
|
+
};
|
|
916
|
+
/** 独立调试源的地址(未启用 / 没起来时为空串;文档里让用户去启动日志找它) */
|
|
917
|
+
debugOriginUrl: string;
|
|
918
|
+
/** 重扫 provider 目录(目录变了由 watcher 调;也可手动触发) */
|
|
919
|
+
reloadProviders(): Promise<{
|
|
920
|
+
count: number;
|
|
921
|
+
version: number;
|
|
922
|
+
}>;
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
export declare interface CloudServerOptions {
|
|
926
|
+
/** 监听端口(缺省 8865;0 = 让系统分配,单测/多实例用) */
|
|
927
|
+
port?: number;
|
|
928
|
+
/** 数据根目录(缺省 .plume):其下 kv/(小数据)与 canvases/(一个画布一个文件夹) */
|
|
929
|
+
dir?: string;
|
|
930
|
+
/** 监听地址(缺省 127.0.0.1:本机自用,不对外暴露) */
|
|
931
|
+
hostname?: string;
|
|
932
|
+
/** ui 构建产物目录;不传则自动探测 apps/web/dist(探测不到 → 页面给"先构建"提示) */
|
|
933
|
+
uiDist?: string;
|
|
934
|
+
/** 插件目录(含各插件的 dist);不传则自动探测 packages/plugins */
|
|
935
|
+
pluginsDir?: string;
|
|
936
|
+
/** 技能一键导入的来源目录(缺省 ~/.agents/skills;测试注入临时目录,避免读到真实家目录) */
|
|
937
|
+
agentSkillSources?: string[];
|
|
938
|
+
/** 是否装配 Agent(对话助手)。缺省 true;测试里可关掉 */
|
|
939
|
+
agent?: boolean;
|
|
940
|
+
/** 平台提供方目录(后台的"投递箱");不传则用 <数据根>/providers */
|
|
941
|
+
providersDir?: string;
|
|
942
|
+
/**
|
|
943
|
+
* 是否盯着 provider 目录自动重载(缺省开)。测试里关掉,避免定时器影响用例。
|
|
944
|
+
*/
|
|
945
|
+
watchProviders?: boolean;
|
|
946
|
+
/**
|
|
947
|
+
* 是否同时提供 MCP 接口(`/mcp`)。缺省 **开**:
|
|
948
|
+
* AI 与网页画布共用同一个服务、同一份数据,是这个服务的主要用法。
|
|
949
|
+
* 只想当静态托管 + KV 接口用时可关掉。
|
|
950
|
+
*/
|
|
951
|
+
mcp?: boolean;
|
|
952
|
+
/**
|
|
953
|
+
* 是否把**自身的画布 MCP**自动写进 Agent 的 MCP 清单(缺省开)。
|
|
954
|
+
*
|
|
955
|
+
* 产品口径:这个画布 MCP 是随 Agent 内置的,用户零配置。
|
|
956
|
+
* 测试里可关掉 —— 那些用例要验「用户没配 MCP 时是什么样」的行为。
|
|
957
|
+
*/
|
|
958
|
+
builtinCanvasMcp?: boolean;
|
|
959
|
+
/**
|
|
960
|
+
* 管理令牌鉴权(缺省**开**)。
|
|
961
|
+
*
|
|
962
|
+
* 关掉要配合 `PLUME_ALLOW_INSECURE=1`(命令行 `--no-admin-auth` 也是这条规则),
|
|
963
|
+
* 否则任何人都能用一个环境变量把整个管理面敞开。
|
|
964
|
+
*/
|
|
965
|
+
adminAuth?: boolean;
|
|
966
|
+
/** 固定管理令牌(缺省读 `PLUME_ADMIN_TOKEN`;都没有就生成/复用 <数据根>/admin-token) */
|
|
967
|
+
adminToken?: string;
|
|
968
|
+
/**
|
|
969
|
+
* 请求来源边界(Host/Origin)。缺省**开**。
|
|
970
|
+
* 测试里关掉(`app.fetch` 造出来的 Request 没有可信 Host),真机必须开。
|
|
971
|
+
*/
|
|
972
|
+
requestTrust?: boolean;
|
|
973
|
+
/** 额外信任的 Host(如 `localhost:8865`、反代域名),与启动时的 hostname:port 一并生效 */
|
|
974
|
+
trustedHosts?: string[];
|
|
975
|
+
/** 额外信任的 Origin(如 dev 的 `http://localhost:5288`) */
|
|
976
|
+
trustedOrigins?: string[];
|
|
977
|
+
}
|
|
978
|
+
|
|
979
|
+
/** 命令条目(CommandDef 的自省形状) */
|
|
980
|
+
declare interface CommandSurface {
|
|
981
|
+
id: string;
|
|
982
|
+
title?: string;
|
|
983
|
+
keys?: string[];
|
|
984
|
+
areas?: string[];
|
|
985
|
+
group?: string;
|
|
986
|
+
order?: number;
|
|
987
|
+
/** 图标(字符串标识或 svg 路径;UI 按它渲染) */
|
|
988
|
+
icon?: string;
|
|
989
|
+
source: string;
|
|
990
|
+
/**
|
|
991
|
+
* 这条命令从哪读到的:
|
|
992
|
+
* - 'field':注册场(`ctx.commands.register` 糖的落点,含插件注册的命令);
|
|
993
|
+
* - 'service':`services` 里名为 `command` 的服务直注册。画布层已不再上架这个名字;
|
|
994
|
+
* 保留这条读口,供仍按服务名提供命令的独立宿主/嵌入方自省。
|
|
995
|
+
* 两处都要读才完整 —— 只读场会漏掉服务直注册的命令。
|
|
996
|
+
*/
|
|
997
|
+
origin: 'field' | 'service';
|
|
998
|
+
}
|
|
999
|
+
|
|
1000
|
+
/**
|
|
1001
|
+
* 一个可配置字段的 schema(type 决定校验与 UI 控件)。
|
|
1002
|
+
* - 标量(string/color/number/boolean/select):与旧 SettingSchema 对齐,登记 settings 面板长控件。
|
|
1003
|
+
* - `array`(如"多目标列表"):默认是数组;可配 `item` 描述元素 schema,逐元素递归校验/补默认。
|
|
1004
|
+
* - `object`(嵌套选项):可配 `fields` 递归子 schema,逐键校验、补默认、丢未知 key。
|
|
1005
|
+
* array/object 是"给 apply 的结构化配置",不登记进 settings 单一数据源(面板为标量控件)。
|
|
1006
|
+
*/
|
|
1007
|
+
declare interface ConfigField {
|
|
1008
|
+
/** 字段类型 */
|
|
1009
|
+
type: ConfigFieldType;
|
|
1010
|
+
/** 默认值(装配未提供时补齐;标量也作 UI/单一数据源初值) */
|
|
1011
|
+
default: ConfigValue;
|
|
1012
|
+
/** UI 显示文案(标量控件用) */
|
|
1013
|
+
label?: string;
|
|
1014
|
+
/** UI 描述/说明(可选,标量控件在控件下方渲染小字;缺省不显示) */
|
|
1015
|
+
description?: string;
|
|
1016
|
+
/**
|
|
1017
|
+
* UI 占位文字(可选,string/text 控件空值时显示在输入框里)。
|
|
1018
|
+
*
|
|
1019
|
+
* 为什么需要它:说明文字在左侧、输入框在右侧,空值字段看起来就是一块
|
|
1020
|
+
* 没有任何提示的灰条 —— 用户 2026-11-05 实测「上游资源接口」时原话:
|
|
1021
|
+
* 「这个输入框就摆在那里,没有任何描述,会让人感觉很疑惑」。
|
|
1022
|
+
* 只影响展示,不参与校验、不写进配置值。
|
|
1023
|
+
*/
|
|
1024
|
+
placeholder?: string;
|
|
1025
|
+
/** UI 分组名(面板按组展示;缺省 = 插件名) */
|
|
1026
|
+
group?: string;
|
|
1027
|
+
/** number 用:最小/最大(装配 raw 越界 → 校验错 FAILED;运行时面板 set 仍走 store 夹取) */
|
|
1028
|
+
min?: number;
|
|
1029
|
+
max?: number;
|
|
1030
|
+
/** number 用:滑块步长(UI 用;缺省 1)。小数比例字段须显式给 step(如 0.05),否则滑块卡死 */
|
|
1031
|
+
step?: number;
|
|
1032
|
+
/** select 用:可选枚举(raw 不在其中 → 校验错) */
|
|
1033
|
+
options?: ConfigSelectOption[];
|
|
1034
|
+
/** array 用:元素 schema(缺省则只做"是数组"检查,元素原样保留) */
|
|
1035
|
+
item?: ConfigField;
|
|
1036
|
+
/** object 用:递归子 schema(缺省则只做"是普通对象"检查,内部原样保留) */
|
|
1037
|
+
fields?: ConfigSchema;
|
|
1038
|
+
/**
|
|
1039
|
+
* color 用:是否允许留空(用户把颜色删掉)。
|
|
1040
|
+
*
|
|
1041
|
+
* 语义(用户口径):删掉自定义色 → 回落主题色;只有该颜色存在时才用它。
|
|
1042
|
+
* 允许留空时空串是合法值(表示没有自定义色),校验放行;缺省 false = 必须有颜色。
|
|
1043
|
+
*/
|
|
1044
|
+
optional?: boolean;
|
|
1045
|
+
}
|
|
1046
|
+
|
|
1047
|
+
/** 全部字段类型:标量 + array + object(DSH/Schemastery 的"数组/嵌套对象"子集) */
|
|
1048
|
+
declare type ConfigFieldType = ConfigScalarType | 'array' | 'object';
|
|
1049
|
+
|
|
1050
|
+
/**
|
|
1051
|
+
* configSchema —— 轻量"对象配置 schema"(自研 cordis ch5 语义,零第三方、零 Vue,Node 可单测)。
|
|
1052
|
+
*
|
|
1053
|
+
* 用途(docs/plan/plugin-cordis-migration-plan.md P4):插件作者在模块级导出一个 `Config` schema,
|
|
1054
|
+
* 声明它这份插件的可配置项;装配处给 config → 内核 `resolveConfig` 校验 + 补齐默认值 → `apply(ctx, config)`
|
|
1055
|
+
* 收到的永远是"经 schema 校验、默认值已补齐"的完整 config。校验失败 → 插件 fiber 进 FAILED 并响亮报错。
|
|
1056
|
+
*
|
|
1057
|
+
* 与旧 ctx.settings 的关系:
|
|
1058
|
+
* - 本 schema 是"声明入口";内核激活时把其字段 + 校验后初值登记进 SettingsStore(单一数据源),
|
|
1059
|
+
* 面板/demo/插件仍可按 group 读、set、onChange 就地窄更新(实时生效,逻辑同旧 settings.onChange)。
|
|
1060
|
+
* - 类型集合有意对齐旧 `SettingSchema`(color/number/select/boolean + string),扩成"对象级 schema"。
|
|
1061
|
+
*/
|
|
1062
|
+
declare type ConfigPrimitive = string | number | boolean;
|
|
1063
|
+
|
|
1064
|
+
/** 可配置字段的标量类型(settings 面板可长控件、SettingsStore 支持) */
|
|
1065
|
+
declare type ConfigScalarType = 'string' | 'color' | 'number' | 'boolean' | 'select';
|
|
1066
|
+
|
|
1067
|
+
/** 对象级 config schema:字段名 → 字段 schema */
|
|
1068
|
+
declare type ConfigSchema = Record<string, ConfigField>;
|
|
1069
|
+
|
|
1070
|
+
/** select 的可选项:值字符串,或带展示文案的 { value, label } */
|
|
1071
|
+
declare type ConfigSelectOption = string | {
|
|
1072
|
+
value: string;
|
|
1073
|
+
label?: string;
|
|
1074
|
+
};
|
|
1075
|
+
|
|
1076
|
+
/** 一个 config 值:原始标量,或 array/object 的嵌套结构(递归)。 */
|
|
1077
|
+
declare type ConfigValue = ConfigPrimitive | ConfigValue[] | {
|
|
1078
|
+
[key: string]: ConfigValue;
|
|
1079
|
+
};
|
|
1080
|
+
|
|
1081
|
+
/**
|
|
1082
|
+
* 每个插件在 setup(ctx) 里拿到的"能力视图"见 types.ts 的 PluginScope(Context 实现之)。
|
|
1083
|
+
*/
|
|
1084
|
+
/**
|
|
1085
|
+
* Context —— 根上下文(宿主创建:createContext(),然后 plugin()×N,最后 start())。
|
|
1086
|
+
*
|
|
1087
|
+
* 职责(API 契约定稿):
|
|
1088
|
+
* - 装载/生命周期:plugin / start / stop
|
|
1089
|
+
* - 服务注入:inject / get
|
|
1090
|
+
* - 类型化事件:on / once / emit(单源)
|
|
1091
|
+
* - 作用域副作用:effect
|
|
1092
|
+
*
|
|
1093
|
+
* 类型增强缝(cordis ch3 声明合并):作者 declare module '@plume-canvas/kernel'
|
|
1094
|
+
* { interface Context { greeter: GreeterService } } 与下方 class Context 同名 interface 合并,
|
|
1095
|
+
* 使 `ctx.greeter` 在本文件声明的 Context 类型上也可见(运行时靠服务解析 Proxy / ctx.get 提供)。
|
|
1096
|
+
*/
|
|
1097
|
+
/**
|
|
1098
|
+
* Context 的类型 = 框架自身成员 + 能力段(PluginCapabilities)。
|
|
1099
|
+
*
|
|
1100
|
+
* 为什么用 extends 而非在类里重声明 nodes/theme/…:类的类型只含它自己声明的成员,
|
|
1101
|
+
* `implements PluginScope` 不会把属性带进来。让接口继承(空的)能力段接口,能力层经
|
|
1102
|
+
* 声明合并补进来的段就自动出现在 ctx 上 —— 于是框架包不必写下任何画布字眼。
|
|
1103
|
+
*/
|
|
1104
|
+
declare interface Context extends PluginCapabilities {
|
|
1105
|
+
}
|
|
1106
|
+
|
|
1107
|
+
declare class Context implements PluginScope {
|
|
1108
|
+
readonly bus: EventBus;
|
|
1109
|
+
/** 根作用域:只服务根 ctx.effect(宿主/非插件的顶层副作用);插件副作用一律归各自 fiber */
|
|
1110
|
+
private rootScope;
|
|
1111
|
+
private services;
|
|
1112
|
+
/** 每个服务名 → 谁注入的(插件名 / '<host>');surface() 用它回答"谁放的" */
|
|
1113
|
+
private serviceSources;
|
|
1114
|
+
private plugins;
|
|
1115
|
+
private lifecycles;
|
|
1116
|
+
/** 每插件一个 fiber 运行时句柄(P1:状态机 + 副作用容器;卸载即 runDisposers/移除) */
|
|
1117
|
+
private fibers;
|
|
1118
|
+
/** 每插件的装配 config(P4:ctx.plugin/installPlugin 第二参存入,激活时经其 Config schema 校验) */
|
|
1119
|
+
private configs;
|
|
1120
|
+
/**
|
|
1121
|
+
* 声明了核心标识的插件名(决策 1:拒绝动态热卸)。
|
|
1122
|
+
*
|
|
1123
|
+
* 为什么不现查 plugins map:FAILED 插件会被移出 plugins 表(fiber 保留供诊断),
|
|
1124
|
+
* 现查会丢掉核心身份。装载归一时刻记一份,卸载随卸载清除、stop 随生命周期清空。
|
|
1125
|
+
*/
|
|
1126
|
+
private corePlugins;
|
|
1127
|
+
/**
|
|
1128
|
+
* 生命周期状态。
|
|
1129
|
+
* 字段名带下划线:新原语 ctx.state() 要占这个成员名(设计文档 §二),字段与方法是两回事,别撞。
|
|
1130
|
+
*/
|
|
1131
|
+
private _state;
|
|
1132
|
+
private dev;
|
|
1133
|
+
/**
|
|
1134
|
+
* 注册场表:kind → 场实例。
|
|
1135
|
+
*
|
|
1136
|
+
* 为什么按 kind 各一份而不是一个大表:键空间彼此独立('node/shell' 与 'theme' 的键不共享),
|
|
1137
|
+
* 而 keys() 这类枚举天然该只看本 kind——分开存最省事,也避免不同 kind 同名键互相干扰。
|
|
1138
|
+
*/
|
|
1139
|
+
private registries;
|
|
1140
|
+
/** 依赖扫描是否进行中(防止 provide 在 drain 内触发 reentrant drain) */
|
|
1141
|
+
private draining;
|
|
1142
|
+
/**
|
|
1143
|
+
* 能力层(可选):框架不认识的"能力段"由它产出(画布层示例:ctx.nodes/theme/commands/tools/slots/settings)。
|
|
1144
|
+
* 来源优先级:构造时显式传入 > 组合根装的全局默认(见 capabilityLayer.setDefaultCapabilityLayerFactory)。
|
|
1145
|
+
* 不装能力层的 Context 就是纯插件内核。
|
|
1146
|
+
*/
|
|
1147
|
+
private readonly capabilityLayer?;
|
|
1148
|
+
/**
|
|
1149
|
+
* 内核自带的"工具"注册表(ctx.tools / ctx.get('tools'))。
|
|
1150
|
+
*
|
|
1151
|
+
* 为什么由内核自带:工具是通用能力——"注册一个外部能力、别人按名调用",
|
|
1152
|
+
* 与画布无关(画布只是消费方之一:把能出图的工具列出给节点)。所以它属框架自带服务,
|
|
1153
|
+
* 与 `slots/settings` 这类由能力层提供的段不同:`tools` 不装能力层也**恒在**。
|
|
1154
|
+
*/
|
|
1155
|
+
private builtinTools;
|
|
1156
|
+
constructor(options?: {
|
|
1157
|
+
dev?: boolean;
|
|
1158
|
+
capabilityLayer?: CapabilityLayer;
|
|
1159
|
+
});
|
|
1160
|
+
/**
|
|
1161
|
+
* 装载一个插件模块(登记;真正 setup 在 start())。该插件的 fiber 句柄可经 ctx.fiber(name) 取得。
|
|
1162
|
+
* 支持类形态(cordis 03):直接传 Service 子类(如 GreeterService),内核归一成 {name, inject, Config, apply:new 类}
|
|
1163
|
+
* 后走与对象插件一致的依赖 PENDING / config 校验 / fiber 回收路径。
|
|
1164
|
+
* @param config 装配 config(可选):start 激活时经插件 `Config` schema 校验+补默认,再传给 apply(ctx, config)。
|
|
1165
|
+
*/
|
|
1166
|
+
plugin(mod: PluginModule, config?: unknown): this;
|
|
1167
|
+
plugin(mod: PluginClassLike, config?: unknown): this;
|
|
1168
|
+
/** 启动:按"服务/插件依赖"确定性多轮激活 → 依赖满足的插件逐个 setup → 其余 PENDING → emit ctx:ready。 */
|
|
1169
|
+
start(): Promise<void>;
|
|
1170
|
+
/**
|
|
1171
|
+
* 确定性多轮扫描:反复激活"所有 inject 依赖现已满足"的插件,直到无新进展。
|
|
1172
|
+
* 依赖满足判定(每项 d):
|
|
1173
|
+
* - 已注入/提供 的服务名(services map,含内置 slots/settings)→ 满足;
|
|
1174
|
+
* - 或 是已登记插件名且其 fiber 已 ACTIVE → 满足;
|
|
1175
|
+
* - 否则该插件停留 PENDING(cordis 语义:不抛,等提供方出现后由 wakePending 唤醒)。
|
|
1176
|
+
* 激活顺序 = plugins map 登记序(确定性)。
|
|
1177
|
+
* @returns 本批实际激活(含已 ACTIVE 的计数)的插件名数组
|
|
1178
|
+
*/
|
|
1179
|
+
private drain;
|
|
1180
|
+
/** 判定某插件 inject 依赖项是否现已满足 */
|
|
1181
|
+
private depSatisfied;
|
|
1182
|
+
/**
|
|
1183
|
+
* 尝试激活一个插件:依赖满足则 apply 并置 ACTIVE,返回 true;依赖不满足则保持 PENDING 返回 false。
|
|
1184
|
+
* 装配 config 经其 `Config` schema 校验(缺默认补齐),失败 → fiber FAILED 并抛出(响亮报错)。
|
|
1185
|
+
* apply 抛错:置 FAILED 并抛出(半成品副作用已回收)。
|
|
1186
|
+
*/
|
|
1187
|
+
private tryActivate;
|
|
1188
|
+
/** 唤醒依赖现已满足但仍在 PENDING 的插件(服务被 provide/插件被激活后调用) */
|
|
1189
|
+
private wakePending;
|
|
1190
|
+
/** 停止:逆序释放各插件 fiber(含全部副作用,async disposer 也会被触发/等待),回到 created 可重新 start。 */
|
|
1191
|
+
stop(): void;
|
|
1192
|
+
/**
|
|
1193
|
+
* 同步停止 + 等待全部插件异步 disposer 结算(P1-3)。
|
|
1194
|
+
* 页面关闭/宿主卸载需确保最后一批异步清理(如异步保存)完成时调用;
|
|
1195
|
+
* 内部先执行与 stop() 相同的同步清理,再 await 各 fiber 的 dispose 结算。
|
|
1196
|
+
*/
|
|
1197
|
+
stopAsync(): Promise<void>;
|
|
1198
|
+
/** 当前状态 */
|
|
1199
|
+
getState(): ContextState;
|
|
1200
|
+
/** 是否已处于运行中(started)且可接受动态装/卸 */
|
|
1201
|
+
get running(): boolean;
|
|
1202
|
+
/**
|
|
1203
|
+
* 运行中热装一个插件(start 之后调用):依赖满足则立即可用;否则保持 PENDING 待提供方出现。
|
|
1204
|
+
* 等价于冷启动时 plugin()。支持类形态(Service 子类)与 PluginModule 对象。
|
|
1205
|
+
*
|
|
1206
|
+
* @param config 装配 config(可选):激活时经插件 `Config` schema 校验+补默认再传 apply;校验失败 → fiber FAILED + 抛错。
|
|
1207
|
+
* @throws 未 start / 插件名重复 / config 校验失败 / apply 抛错(半成品副作用已回收)
|
|
1208
|
+
* @returns 插件名
|
|
1209
|
+
*/
|
|
1210
|
+
installPlugin(mod: PluginModule, config?: unknown): string;
|
|
1211
|
+
installPlugin(mod: PluginClassLike, config?: unknown): string;
|
|
1212
|
+
/**
|
|
1213
|
+
* 运行中热卸一个插件:dispose 它的 Scope → 全部副作用/注册/UI 自动回收;
|
|
1214
|
+
* 随后把「现在因它消失而不满足其声明依赖」的已 ACTIVE 依赖方一并回退 PENDING(等依赖恢复后重载)。
|
|
1215
|
+
*
|
|
1216
|
+
* **核心插件拒卸(决策 1)**:插件声明了 `core: true` 则本方法直接返回 `false`,
|
|
1217
|
+
* 且**不 dispose fiber、不发 `ctx:plugin-uninstalled`、不触发 `retractUnsatisfiedActives`**
|
|
1218
|
+
* ——一次真副作用都不产生(依赖方不会被连带回退 PENDING)。想区分"被拦"与"不存在",
|
|
1219
|
+
* 用 `ctx.canUninstall(name)` 先问。
|
|
1220
|
+
*
|
|
1221
|
+
* 注意:`stop()` / `stopAsync()` 不走本守卫——整体生命周期终结不是动态卸载,
|
|
1222
|
+
* 页面关闭时核心插件也必须正常回收。
|
|
1223
|
+
* @returns 是否真卸到(未装/已卸/**核心插件**返回 false)
|
|
1224
|
+
*/
|
|
1225
|
+
uninstallPlugin(name: string): boolean;
|
|
1226
|
+
/**
|
|
1227
|
+
* 能否动态卸载某插件(决策 1:"先问再动")。
|
|
1228
|
+
*
|
|
1229
|
+
* `uninstallPlugin` 把"核心插件拒卸"与"插件不存在"同值成 `false`(沿用既有契约),
|
|
1230
|
+
* 但调用方(pluginManager / 宿主 UI)常常**在卸载前有副作用要做**(例如先删配置),
|
|
1231
|
+
* 或者要在被拦时抛一个说明白的错误。本方法把原因给出来:
|
|
1232
|
+
*
|
|
1233
|
+
* - `{ ok: true }`:可卸;
|
|
1234
|
+
* - `{ ok: false, reason: 'core' }`:核心插件(声明了 `core: true`);
|
|
1235
|
+
* - `{ ok: false, reason: 'not-found' }`:没装过 / 已卸;
|
|
1236
|
+
* - `{ ok: false, reason: 'not-started' }`:内核还没 start(此时任何动态卸载都不生效)。
|
|
1237
|
+
*
|
|
1238
|
+
* 纯只读,不改任何状态。
|
|
1239
|
+
*/
|
|
1240
|
+
canUninstall(name: string): CanUninstallResult;
|
|
1241
|
+
/**
|
|
1242
|
+
* 该插件是否声明了核心标识(决策 1)。
|
|
1243
|
+
*
|
|
1244
|
+
* 判定只认"`PluginModule.core === true`",在 plugin()/installPlugin() 归一时刻记进本表 ——
|
|
1245
|
+
* 不现查 `plugins` map:FAILED 插件会被移出 plugins 表(fiber 保留供诊断),若现查就会
|
|
1246
|
+
* 丢掉它的核心身份。
|
|
1247
|
+
*/
|
|
1248
|
+
private isCorePlugin;
|
|
1249
|
+
/**
|
|
1250
|
+
* 提供方被卸/换后调用:回收「此刻不再满足其声明依赖」的 ACTIVE 插件并回退 PENDING。
|
|
1251
|
+
* 迭代处理传递链——D 被回退时其 fiber 连带摘除它提供的服务,故下一轮 E(依赖 D 的服务)也会被回退。
|
|
1252
|
+
* 被回退插件仍保留在 plugins/fibers/configs 登记(还是已装插件),依赖恢复后由 wakePending→drain 重载。
|
|
1253
|
+
* 判定依据 = depSatisfied(d)(依赖的是插件名或它提供的服务名皆被覆盖:P 的插件名/服务已随 fiber.runDisposers
|
|
1254
|
+
* 与 plugins.delete 从满足集消失)。
|
|
1255
|
+
*/
|
|
1256
|
+
private retractUnsatisfiedActives;
|
|
1257
|
+
/** 回收单个 ACTIVE 插件的副作用并置回 PENDING(保留 plugins/fibers/configs 登记,可重载复用) */
|
|
1258
|
+
private retractPlugin;
|
|
1259
|
+
/** 已装载(含动态)的插件名 */
|
|
1260
|
+
listPlugins(): string[];
|
|
1261
|
+
/**
|
|
1262
|
+
* 取已装载插件的模块(只读)。
|
|
1263
|
+
*
|
|
1264
|
+
* 为什么宿主需要它:应用级插件也可能有「画布会话钩子」(onCanvasReady),
|
|
1265
|
+
* 而画布会话只拿得到自己那份画布级插件数组。宿主靠这个入口把应用级插件一起叫一遍,
|
|
1266
|
+
* 不必让每个插件自己去监听 doc 出现(那会在切换画布时重复挂)。
|
|
1267
|
+
* 只返回登记表里的模块,不触发装载、不改状态。
|
|
1268
|
+
*/
|
|
1269
|
+
pluginModule(name: string): PluginModule | undefined;
|
|
1270
|
+
/**
|
|
1271
|
+
* P5 只读查询:每个"已装/仍在 runtime"插件的运行时态快照,供宿主/管理器/console 诊断。
|
|
1272
|
+
*
|
|
1273
|
+
* 覆盖两类条目:
|
|
1274
|
+
* - `plugins` 表里的插件(ACTIVE / PENDING…);
|
|
1275
|
+
* - 已从 `plugins` 表移出但 fiber 仍保留的 **FAILED** 插件(config/apply 抛错后保留供诊断,可重装复用)。
|
|
1276
|
+
* `missingDeps` = 该插件 deps 中此刻未满足的项(判定对齐私有 depSatisfied:既非内置 slots/settings、也非已注入
|
|
1277
|
+
* 服务名、也非"已登记且 ACTIVE"的插件名)。state!=='active' 时据此回答"到底缺哪个依赖"。
|
|
1278
|
+
* 纯只读,不改动装载/编排/激活逻辑。
|
|
1279
|
+
*/
|
|
1280
|
+
inspectPlugins(): PluginRuntimeStatus[];
|
|
1281
|
+
/**
|
|
1282
|
+
* 插件注册表只读视图(cordis 06:诊断 PENDING / 可枚举每插件 fiber)。
|
|
1283
|
+
* 每次访问现算返回一个 name → { status, fiber } 的只读 Map;fiber 供 await/dispose、
|
|
1284
|
+
* status 供 PENDING 诊断(缺哪个依赖)。纯只读,不改装载/激活。
|
|
1285
|
+
*/
|
|
1286
|
+
get registry(): ReadonlyMap<string, {
|
|
1287
|
+
status: PluginRuntimeStatus;
|
|
1288
|
+
fiber: Fiber | undefined;
|
|
1289
|
+
}>;
|
|
1290
|
+
/** 提供服务(宿主/根层用);返回撤销函数。注:本根方法不自动登记清理,撤销由调用方持有并执行;插件层请走注入的 PluginScope.provide(撤销随插件 fiber 自动清)。 */
|
|
1291
|
+
inject<Service>(name: string, impl: Service): () => void;
|
|
1292
|
+
/** 提供服务(cordis 语义,与 inject 等价);Service 子类 super(ctx,name) 内部调用。 */
|
|
1293
|
+
provide<Service>(name: string, impl: Service): () => void;
|
|
1294
|
+
/**
|
|
1295
|
+
* 取服务。
|
|
1296
|
+
*
|
|
1297
|
+
* **首选写法是在模块顶层用 `export const inject = ['xxx']` 声明依赖**(对齐
|
|
1298
|
+
* docs/user/develop/framework/service.zh.md):框架保证 apply 执行时依赖已就绪;
|
|
1299
|
+
* 缺提供方该插件停留 PENDING 不跑;提供方被卸/换时依赖方自动回收、恢复后自动重载。
|
|
1300
|
+
*
|
|
1301
|
+
* 本方法用于**可选依赖**:某能力缺失插件也能跑时,跳过 inject、在使用处探测 ——
|
|
1302
|
+
* 缺服务返回 `undefined`(不抛)。即"能不用就不用"的是本方法,而不是 inject。
|
|
1303
|
+
*/
|
|
1304
|
+
/** 按服务名推导(Services 里声明过时);扩展/可选依赖走显式泛型重载 */
|
|
1305
|
+
get<K extends keyof Services>(name: K): Services[K];
|
|
1306
|
+
get<Service = unknown>(name: string): Service;
|
|
1307
|
+
/** 取内置服务(内核自带 tools,或能力层提供的其它内置服务);无此名 → undefined */
|
|
1308
|
+
private builtinService;
|
|
1309
|
+
/**
|
|
1310
|
+
* `get` 的显式别名:缺服务返回 undefined(不抛)。
|
|
1311
|
+
* 供作者把"这里是可选依赖"表达清楚——硬依赖请改在模块顶层写 `export const inject = [...]`。
|
|
1312
|
+
*/
|
|
1313
|
+
/** 按服务名推导(Services 声明过时);扩展/可选依赖走显式泛型重载 */
|
|
1314
|
+
tryGet<K extends keyof Services>(name: K): Services[K] | undefined;
|
|
1315
|
+
tryGet<Service = unknown>(name: string): Service | undefined;
|
|
1316
|
+
/** 是否已注入某服务(含能力层内置服务) */
|
|
1317
|
+
hasService(name: string): boolean;
|
|
1318
|
+
/** 已注入的服务名列表(供 dev 诊断) */
|
|
1319
|
+
injectedServices(): string[];
|
|
1320
|
+
/**
|
|
1321
|
+
* 取某 kind 的注册场(设计文档 §2.1 / 决策 6)。入口叫 registryOf ——
|
|
1322
|
+
* ctx.registry 已被插件运行态诊断占用,不要动它。
|
|
1323
|
+
*
|
|
1324
|
+
* 同一 kind 各处拿到的是**同一张表**(插件之间互相看得见,这正是注册场的意义);
|
|
1325
|
+
* 视图只决定两件事:add/wrap/subscribe 是否随本作用域自动回收、add/wrap 写进 entry.source(谁放的)。
|
|
1326
|
+
* 宿主(根 ctx)用:source 记作 '<host>',返回的句柄由调用方自己持有(不自动回收)。
|
|
1327
|
+
*/
|
|
1328
|
+
registryOf<T>(kind: string): Registry<T>;
|
|
1329
|
+
/**
|
|
1330
|
+
* 自省快照(§新原语:surface):一次列出三根轴上「注册了什么、各自支持什么」。
|
|
1331
|
+
* - 服务轴:services 表(含插件 provide 的);
|
|
1332
|
+
* - 注册轴:registries 表全部 kind + 键 + 条目数 + 明细(source 可诊断);
|
|
1333
|
+
* - 语义视图:command 场 → 命令(含 keys/areas/group);tool 场 → 模型可调用工具
|
|
1334
|
+
* (含 parameters/outputSchema);ctx.tools → 生成工具(含声明式 params)。
|
|
1335
|
+
*
|
|
1336
|
+
* 只读、零副作用、不触发事件,created/started 皆可调。诊断面板 / 文档 / AI 探查用。
|
|
1337
|
+
*/
|
|
1338
|
+
surface(): SurfaceReport;
|
|
1339
|
+
/**
|
|
1340
|
+
* 插件私有状态(§二 原语 ⑥):内核只存值、不做响应式(响应式由渲染层决定)。
|
|
1341
|
+
* 不占服务名——它是插件自己的数据,不是"别人按名取的能力"(规则 7)。
|
|
1342
|
+
* 插件作用域上的 state 随插件 scope 自动回收(见 deriveScope)。
|
|
1343
|
+
*/
|
|
1344
|
+
state<T>(initial: T): State<T>;
|
|
1345
|
+
/** 是否开发态(原 private dev 公开化:插件与消费者都要能读) */
|
|
1346
|
+
get isDev(): boolean;
|
|
1347
|
+
/** kind → 场实例(没有则建一份;整张表随 stop 清空) */
|
|
1348
|
+
private registryTable;
|
|
1349
|
+
on<K extends string>(name: K, handler: EventHandlerFor<K>): Disposable_2;
|
|
1350
|
+
once<K extends string>(name: K, handler: EventHandlerFor<K>): Disposable_2;
|
|
1351
|
+
emit<K extends string>(name: K, ...args: EventArgsFor<K>): void;
|
|
1352
|
+
/** 并发跑所有监听并一同等待 */
|
|
1353
|
+
parallel<K extends string>(name: K, ...args: EventArgsFor<K>): Promise<void>;
|
|
1354
|
+
/** 顺序 await,第一个 bail 值胜出并停止 */
|
|
1355
|
+
serial<K extends string>(name: K, ...args: EventArgsFor<K>): Promise<any>;
|
|
1356
|
+
/** serial 的同步版(同步短路) */
|
|
1357
|
+
bail<K extends string>(name: K, ...args: EventArgsFor<K>): any;
|
|
1358
|
+
/** 环绕中间件 */
|
|
1359
|
+
waterfall<K extends string>(name: K, ...args: EventArgsFor<K>): any;
|
|
1360
|
+
effect(fn: EffectFn): Disposable_2;
|
|
1361
|
+
private deriveScope;
|
|
1362
|
+
private setLifecycle;
|
|
1363
|
+
/**
|
|
1364
|
+
* 取某插件的 fiber 句柄(查状态/await/dispose)。未装/已卸返回 undefined。
|
|
1365
|
+
* @param name 插件名
|
|
1366
|
+
*/
|
|
1367
|
+
fiber(name: string): Fiber | undefined;
|
|
1368
|
+
/** 建/取某插件的 fiber;deps 以插件 inject 字段初始化。 */
|
|
1369
|
+
private attachFiber;
|
|
1370
|
+
private assertState;
|
|
1371
|
+
}
|
|
1372
|
+
|
|
1373
|
+
/** Context 生命周期状态 */
|
|
1374
|
+
declare type ContextState = 'created' | 'started' | 'stopped';
|
|
1375
|
+
|
|
1376
|
+
export declare function createCanvasMcpServer(doc: CanvasDocument | CanvasDocLike, registry?: ProviderRegistry, tasks?: TaskManager,
|
|
1377
|
+
/** 插件注册的额外 MCP 工具(ctx.mcp 的落点);缺省 = 没有插件工具 */
|
|
1378
|
+
pluginTools?: McpToolDef[],
|
|
1379
|
+
/**
|
|
1380
|
+
* 按画布取文档。**必须给**才能多画布工作:AI 传 `canvasId` 时用它取对应画布,
|
|
1381
|
+
* 不传则用默认画布(`doc`)。缺省时退回「只有默认画布」的旧行为(测试 / 单画布够用)。
|
|
1382
|
+
*/
|
|
1383
|
+
resolveDoc?: CanvasDocResolver,
|
|
1384
|
+
/** 列出全部画布(画布 id + 名字)。给 AI 用来发现「该往哪张画布写」的 id */
|
|
1385
|
+
listCanvases?: () => Promise<Array<{
|
|
1386
|
+
id: string;
|
|
1387
|
+
name: string;
|
|
1388
|
+
}>>): McpServer;
|
|
1389
|
+
|
|
1390
|
+
export declare function createCloudServer(opts?: CloudServerOptions): Promise<CloudServer>;
|
|
1391
|
+
|
|
1392
|
+
/** 默认画布 id(前端界面当前只有一张画布) */
|
|
1393
|
+
export declare const DEFAULT_CANVAS_ID = "default";
|
|
1394
|
+
|
|
1395
|
+
/**
|
|
1396
|
+
* 默认数据目录:固定在用户主目录下的 `.plume`。
|
|
1397
|
+
*
|
|
1398
|
+
* 不能写成相对路径:`pnpm start` 最后是在 `apps/server` 里执行 `serve`,
|
|
1399
|
+
* 相对路径会按启动目录解析,数据就散到 `apps/server/.plume` 去了。
|
|
1400
|
+
* 数据目录只认一份,跟从哪里启动无关。
|
|
1401
|
+
*/
|
|
1402
|
+
export declare const DEFAULT_DATA_DIR: string;
|
|
1403
|
+
|
|
1404
|
+
/** 历史条数上限:超出丢最旧的(生成要花钱,量不会大;但账本不能无限长) */
|
|
1405
|
+
export declare const DEFAULT_HISTORY_LIMIT = 500;
|
|
1406
|
+
|
|
1407
|
+
/** 默认轮询间隔(ms) */
|
|
1408
|
+
export declare const DEFAULT_INTERVAL = 1500;
|
|
1409
|
+
|
|
1410
|
+
/** 默认分页大小 */
|
|
1411
|
+
export declare const DEFAULT_PAGE_SIZE = 20;
|
|
1412
|
+
|
|
1413
|
+
/** 默认端口:避开 ui dev 的 5288 与 mcp-server 的 8765 */
|
|
1414
|
+
export declare const DEFAULT_PORT = 8865;
|
|
1415
|
+
|
|
1416
|
+
/** 默认的 provider 目录名(挂在数据根下,与 kv / canvases 并列) */
|
|
1417
|
+
export declare const DEFAULT_PROVIDERS_DIR = "providers";
|
|
1418
|
+
|
|
1419
|
+
/** 默认整体超时(ms)—— 长视频会被动作自己的 pollTimeoutMs 顶掉 */
|
|
1420
|
+
export declare const DEFAULT_TIMEOUT = 300000;
|
|
1421
|
+
|
|
1422
|
+
/** 可释放对象:调用即执行清理,幂等安全 */
|
|
1423
|
+
declare interface Disposable_2 {
|
|
1424
|
+
dispose(): void;
|
|
1425
|
+
}
|
|
1426
|
+
|
|
1427
|
+
/** 连线批量入参(三段都可省略) */
|
|
1428
|
+
export declare interface EdgeBatchInput {
|
|
1429
|
+
add?: AddEdgeInput[];
|
|
1430
|
+
delete?: string[];
|
|
1431
|
+
/** 新增一个已存在的边 id → 当成更新(同步口用;理由同 NodeBatchInput.upsert) */
|
|
1432
|
+
upsert?: boolean;
|
|
1433
|
+
/** 删除/更新不存在的东西 → 静默跳过而不是整批拒绝(同步口用;理由同 NodeBatchInput.lenient) */
|
|
1434
|
+
lenient?: boolean;
|
|
1435
|
+
update?: {
|
|
1436
|
+
id: string;
|
|
1437
|
+
source?: string;
|
|
1438
|
+
target?: string;
|
|
1439
|
+
sourceHandle?: string;
|
|
1440
|
+
targetHandle?: string;
|
|
1441
|
+
data?: Record<string, unknown>;
|
|
1442
|
+
}[];
|
|
1443
|
+
}
|
|
1444
|
+
|
|
1445
|
+
/**
|
|
1446
|
+
* effect 回调:可返回一个清理函数(会被登记进当前 scope)。
|
|
1447
|
+
*/
|
|
1448
|
+
declare type EffectFn = () => void | (() => void) | Disposable_2;
|
|
1449
|
+
|
|
1450
|
+
/**
|
|
1451
|
+
* 场里的一条。source = **谁放的**,是"分不清谁是谁"的解药。
|
|
1452
|
+
*
|
|
1453
|
+
* source 怎么来的:由 RegistryImpl 的 source 解析器给出。Context 挂给插件时,
|
|
1454
|
+
* 解析器 = 该插件的名字(registryOf 在插件 scope 上被调用,放置方就是那个插件);
|
|
1455
|
+
* 宿主直接放置时为 '<host>';独立 new RegistryImpl() 不传解析器时为 '<anonymous>'。
|
|
1456
|
+
*/
|
|
1457
|
+
declare interface Entry<T> {
|
|
1458
|
+
/** 条目 id(同 key 内唯一;同 id 再 add = 替换该条) */
|
|
1459
|
+
id: string;
|
|
1460
|
+
/** 值(组件 / 命令 / 描述,opaque) */
|
|
1461
|
+
value: T;
|
|
1462
|
+
/** 排序:小 = 在外 / 覆盖者 */
|
|
1463
|
+
order: number;
|
|
1464
|
+
/** 谁放的(插件名 / '<host>' / '<anonymous>') */
|
|
1465
|
+
source: string;
|
|
1466
|
+
}
|
|
1467
|
+
|
|
1468
|
+
/** 事件分发参数按事件名解析(emit/parallel/serial/bail/waterfall 的 rest 参) */
|
|
1469
|
+
declare type EventArgsFor<K extends string> = K extends keyof Events ? Parameters<Events[K]> : K extends EventName ? [payload: EventMap[K & EventName]] : any[];
|
|
1470
|
+
|
|
1471
|
+
declare class EventBus {
|
|
1472
|
+
private handlers;
|
|
1473
|
+
/** dev 下是否对"未在 EventMap 声明"的 emit 给 warn(治漏转发静默失效) */
|
|
1474
|
+
private devWhitelistWarn;
|
|
1475
|
+
/** dev warn 已提示过的事件名(每名只 warn 一次,避免刷屏) */
|
|
1476
|
+
private seen;
|
|
1477
|
+
constructor(options?: {
|
|
1478
|
+
devWhitelistWarn?: boolean;
|
|
1479
|
+
});
|
|
1480
|
+
/** 解析某事件名的监听列表(按注册序)。 */
|
|
1481
|
+
private hooks;
|
|
1482
|
+
/** 订阅事件(自动随所属 scope/fiber 回收由调用方 scope.onDispose 负责)。返回取消订阅句柄。 */
|
|
1483
|
+
on(name: string, handler: (...args: any[]) => any): () => void;
|
|
1484
|
+
/** 订阅一次。 */
|
|
1485
|
+
once(name: string, handler: (...args: any[]) => any): () => void;
|
|
1486
|
+
/** 取消订阅。 */
|
|
1487
|
+
off(name: string, handler: (...args: any[]) => any): void;
|
|
1488
|
+
/** 派发:同步广播,忽略监听返回值(不等待 promise)。 */
|
|
1489
|
+
emit(name: string, ...args: any[]): void;
|
|
1490
|
+
/** 并发跑所有监听并等待全部 settle(有拒绝则 AggregateError)。 */
|
|
1491
|
+
parallel(name: string, ...args: any[]): Promise<void>;
|
|
1492
|
+
/** 顺序 await,第一个 bail 值(non-null/false/undefined)胜出并停止。 */
|
|
1493
|
+
serial(name: string, ...args: any[]): Promise<any>;
|
|
1494
|
+
/** 同步短路(serial 的同步版)。 */
|
|
1495
|
+
bail(name: string, ...args: any[]): any;
|
|
1496
|
+
/**
|
|
1497
|
+
* 环绕中间件。最后一个参数视为"最内层 next"(内置行为);监听器最外层先跑:
|
|
1498
|
+
* 调用 next() 进入下一层;不调用直接返回=有意短路(否决下游)。
|
|
1499
|
+
*/
|
|
1500
|
+
waterfall(name: string, ...args: any[]): any;
|
|
1501
|
+
/** 清空所有监听。 */
|
|
1502
|
+
clear(): void;
|
|
1503
|
+
/** 某事件是否有监听者(供决定是否需要构造昂贵 payload) */
|
|
1504
|
+
has(name: string): boolean;
|
|
1505
|
+
}
|
|
1506
|
+
|
|
1507
|
+
/**
|
|
1508
|
+
* PluginScope —— 单个插件在 setup(ctx) 里拿到的"能力视图"。
|
|
1509
|
+
*
|
|
1510
|
+
* 它把根 Context 的能力暴露给插件,但**所有副作用自动登记进本插件自己的 Scope**:
|
|
1511
|
+
* - on/effect/inject 登记进本插件 scope → 插件卸载(scope.dispose)即自动清光。
|
|
1512
|
+
* - get/emit 是读操作 / 广播,不登记。
|
|
1513
|
+
* - nodes/theme/commands/slots 是注册收口(见 PluginCapabilities)。
|
|
1514
|
+
*/
|
|
1515
|
+
/**
|
|
1516
|
+
* 事件监听回调按事件名解析:
|
|
1517
|
+
* - K 在 `interface Events` 里(含内置与作者 declare module 扩展)→ Events[K](监听函数签名,参数即事件参数)
|
|
1518
|
+
* - K 仅在 EventMap(单 payload 对象事件,向后兼容)→ EventListener<K>
|
|
1519
|
+
* - 否则(未登记任意事件名)→ 松 (...args) => any
|
|
1520
|
+
*/
|
|
1521
|
+
declare type EventHandlerFor<K extends string> = K extends keyof Events ? Events[K] : K extends EventName ? EventListener<K & EventName> : (...args: any[]) => any;
|
|
1522
|
+
|
|
1523
|
+
/**
|
|
1524
|
+
* 一个事件总线的监听句柄:dispose 即取消监听(幂等)。
|
|
1525
|
+
*/
|
|
1526
|
+
declare type EventListener<K extends EventName = EventName> = (payload: EventMap[K]) => void;
|
|
1527
|
+
|
|
1528
|
+
/**
|
|
1529
|
+
* 事件契约表:事件名 → payload 类型。
|
|
1530
|
+
* 内置内核事件在此;插件用 `declare module './types' { interface EventMap { ... } }` 扩展。
|
|
1531
|
+
*/
|
|
1532
|
+
declare interface EventMap {
|
|
1533
|
+
/** 内核就绪(所有插件激活完毕) */
|
|
1534
|
+
'ctx:ready': {
|
|
1535
|
+
plugins: string[];
|
|
1536
|
+
};
|
|
1537
|
+
/** 插件安装完成 */
|
|
1538
|
+
'ctx:plugin-installed': {
|
|
1539
|
+
name: string;
|
|
1540
|
+
};
|
|
1541
|
+
/** 插件卸载完成 */
|
|
1542
|
+
'ctx:plugin-uninstalled': {
|
|
1543
|
+
name: string;
|
|
1544
|
+
};
|
|
1545
|
+
/** 生命周期状态变化 */
|
|
1546
|
+
'ctx:lifecycle-change': {
|
|
1547
|
+
name: string;
|
|
1548
|
+
lifecycle: Lifecycle;
|
|
1549
|
+
};
|
|
1550
|
+
}
|
|
1551
|
+
|
|
1552
|
+
/** 事件名 = EventMap 的键(供泛型约束用) */
|
|
1553
|
+
declare type EventName = keyof EventMap & string;
|
|
1554
|
+
|
|
1555
|
+
/**
|
|
1556
|
+
* 全局"事件表"(cordis ch4 声明合并缝):作者 declare module 扩展:
|
|
1557
|
+
* ```ts
|
|
1558
|
+
* declare module '@plume-canvas/kernel' {
|
|
1559
|
+
* interface Events { 'stats/report'(name: string, count: number): void }
|
|
1560
|
+
* }
|
|
1561
|
+
* ```
|
|
1562
|
+
* 每个键=事件名,其值=监听函数签名(参数即事件参数)。内置内核事件也在此列出
|
|
1563
|
+
* (与 EventMap 同键,监听签名=单 payload 形态),保证 `keyof Events` 非空——
|
|
1564
|
+
* ctx.on/once/emit/parallel/serial/bail/waterfall 据此做 K extends keyof Events 的类型化重载;
|
|
1565
|
+
* 声明合并补的条目(如 'stats/report')自动获得参数类型提示。
|
|
1566
|
+
*/
|
|
1567
|
+
declare interface Events {
|
|
1568
|
+
/** 内核就绪(所有插件激活完毕) */
|
|
1569
|
+
'ctx:ready'(payload: {
|
|
1570
|
+
plugins: string[];
|
|
1571
|
+
}): void;
|
|
1572
|
+
/** 插件安装完成 */
|
|
1573
|
+
'ctx:plugin-installed'(payload: {
|
|
1574
|
+
name: string;
|
|
1575
|
+
}): void;
|
|
1576
|
+
/** 插件卸载完成 */
|
|
1577
|
+
'ctx:plugin-uninstalled'(payload: {
|
|
1578
|
+
name: string;
|
|
1579
|
+
}): void;
|
|
1580
|
+
/** 生命周期状态变化 */
|
|
1581
|
+
'ctx:lifecycle-change'(payload: {
|
|
1582
|
+
name: string;
|
|
1583
|
+
lifecycle: Lifecycle;
|
|
1584
|
+
}): void;
|
|
1585
|
+
/**
|
|
1586
|
+
* 模型可调用工具进表(设计文档 §7.2 缺口①)。
|
|
1587
|
+
*
|
|
1588
|
+
* 参数:工具名(= \`registryOf('tool')\` 里的键)、工具定义、谁放的(插件名)。
|
|
1589
|
+
* 同 id 顶替时也会发(此前先发一条 \`tools/unregistered\`)。
|
|
1590
|
+
* 事件名已在 modelTool 模块加载时 registerEventName 登记(否则 dev 下会 warn,§7.4)。
|
|
1591
|
+
*/
|
|
1592
|
+
'tools/registered'(name: string, tool: ToolSpec, source: string): void;
|
|
1593
|
+
/** 模型可调用工具离表(显式撤销 / 清空 / 被同 id 顶替)。参数:工具名、此前谁放的 */
|
|
1594
|
+
'tools/unregistered'(name: string, source: string): void;
|
|
1595
|
+
/**
|
|
1596
|
+
* 一次模型可调用工具调用的**权威结果**(结果物化时发,先于调用方 promise 兑现)。
|
|
1597
|
+
*
|
|
1598
|
+
* 观察者插件靠它就能记录每次调用,且它**不需要 inject 任何服务**——
|
|
1599
|
+
* 这就是"今天根本写不出来"的那条缝(教程第 7 章的 tool-logger)。
|
|
1600
|
+
*/
|
|
1601
|
+
'tools/result'(exec: ToolExecView, result: ToolCallResult): void;
|
|
1602
|
+
}
|
|
1603
|
+
|
|
1604
|
+
/**
|
|
1605
|
+
* 反过来:MIME → 扩展名(上传时没有文件名可用,只能看 Content-Type)。
|
|
1606
|
+
* 只认白名单里的类型;不认识的返回空串(不猜)。
|
|
1607
|
+
*/
|
|
1608
|
+
export declare function extFromMime(mime: string): string;
|
|
1609
|
+
|
|
1610
|
+
/**
|
|
1611
|
+
* Fiber —— 插件实例的运行时句柄 + 状态机 + 副作用容器(自研 cordis 语义)。
|
|
1612
|
+
*/
|
|
1613
|
+
declare class Fiber {
|
|
1614
|
+
/** 插件唯一名 */
|
|
1615
|
+
readonly name: string;
|
|
1616
|
+
/** 依赖服务名(P2 用于 PENDING 编排) */
|
|
1617
|
+
readonly deps: string[];
|
|
1618
|
+
/** 装配 config(P4 起由 ctx 在激活前填好) */
|
|
1619
|
+
config: unknown;
|
|
1620
|
+
private _state;
|
|
1621
|
+
private _error;
|
|
1622
|
+
/** 登记在案的清理项(注册序;dispose 逆序跑) */
|
|
1623
|
+
private cleanups;
|
|
1624
|
+
/** 在途的异步 effect(其 setup 尚未 resolve,清理尚未登记);dispose 时先等齐再跑清理 */
|
|
1625
|
+
private inflight;
|
|
1626
|
+
private _disposeStarted;
|
|
1627
|
+
private _settled?;
|
|
1628
|
+
/** 状态变化回调(ctx 注入,用于 emit internal/status) */
|
|
1629
|
+
onTransition: FiberTransition | undefined;
|
|
1630
|
+
constructor(init: FiberInit);
|
|
1631
|
+
/** 当前生命周期状态 */
|
|
1632
|
+
get state(): FiberState;
|
|
1633
|
+
/** 当前状态可读名 */
|
|
1634
|
+
get stateName(): string;
|
|
1635
|
+
/** 是否已释放(DISPOSED) */
|
|
1636
|
+
get isDisposed(): boolean;
|
|
1637
|
+
/** 出错原因(FAILED 后可用) */
|
|
1638
|
+
get error(): unknown;
|
|
1639
|
+
/**
|
|
1640
|
+
* 登记一个清理项(插件经 ctx 建立的注册副作用都进这里)。
|
|
1641
|
+
* 返回"提前手动执行并从队列移除"的句柄(幂等)。
|
|
1642
|
+
*/
|
|
1643
|
+
onDispose(fn: FiberDisposer): () => void;
|
|
1644
|
+
/**
|
|
1645
|
+
* effect(fn):立即执行 fn;若 fn 返回清理函数(同步或 promise)则登记进本 fiber。
|
|
1646
|
+
* 对齐 cordis ctx.effect。fn 也可返回一个 generator/iterable,逐个登记其产出的清理。
|
|
1647
|
+
* @param label 诊断标签(预留,当前仅注释)
|
|
1648
|
+
*/
|
|
1649
|
+
effect(fn: () => unknown, _label?: string): () => void;
|
|
1650
|
+
/** 把 effect 产出归入清理列表(支持单清理函数 / 迭代器产出多个) */
|
|
1651
|
+
private collectResult;
|
|
1652
|
+
/** 推进到指定状态;真变化才触发 onTransition */
|
|
1653
|
+
private transition;
|
|
1654
|
+
/** apply 开始跑前调用:PENDING→LOADING */
|
|
1655
|
+
markLoading(): void;
|
|
1656
|
+
/** apply 成功跑完:LOADING→ACTIVE */
|
|
1657
|
+
markActive(): void;
|
|
1658
|
+
/**
|
|
1659
|
+
* 把 ACTIVE 的插件回退为 PENDING(P6/P2b2 语义:提供方被卸/换,依赖方随之回退等重载)。
|
|
1660
|
+
* 只翻转状态供 drain 重新装载;其副作用由调用方先经 runDisposers() 同步回收。
|
|
1661
|
+
* 对 DISPOSED 无效(transition 在 DISPOSED 上 no-op)。
|
|
1662
|
+
*/
|
|
1663
|
+
markPending(): void;
|
|
1664
|
+
/** apply/config 抛错:LOADING→FAILED */
|
|
1665
|
+
markFailed(err: unknown): void;
|
|
1666
|
+
/**
|
|
1667
|
+
* 同步逆序(LIFO)跑完并清空当前已登记的 disposers(不改状态机)。
|
|
1668
|
+
* 供"回退 PENDING/半成品失败"这类**还要复用本 fiber** 的路径同步清副作用;
|
|
1669
|
+
* 因为不置 DISPOSED,所以可随后 markPending → 依赖恢复后 drain 重载复用本 fiber。
|
|
1670
|
+
* 仅保证同步 disposer 立即执行;若存在异步 disposer/inflight 异步 effect(现插件副作用全同步,理论没有),
|
|
1671
|
+
* 请改用 dispose() 获得完整结算。
|
|
1672
|
+
*/
|
|
1673
|
+
runDisposers(): void;
|
|
1674
|
+
/** 单个清理:跑 fn,吞掉自己的 rejection/异常(单错不阻断)。供异步 effect 在途 resolve 后执行其清理。 */
|
|
1675
|
+
private safeRun;
|
|
1676
|
+
/**
|
|
1677
|
+
* 终结卸载:**同步 disposer 立即执行**(保证调用返回后同步副作用已清,供测试/热卸同步断言),
|
|
1678
|
+
* 异步 disposer 与在途异步 effect 则被收集并在返回的 promise 中 await 完成后,置 DISPOSED。
|
|
1679
|
+
* 幂等:重复调用返回同一完成 promise。
|
|
1680
|
+
*/
|
|
1681
|
+
dispose(): Promise<void>;
|
|
1682
|
+
/**
|
|
1683
|
+
* 等到 fiber 落到稳定态:
|
|
1684
|
+
* - ACTIVE / DISPOSED → resolve(本 fiber)
|
|
1685
|
+
* - FAILED → reject(error)
|
|
1686
|
+
* - 仍 PENDING/LOADING/UNLOADING → resolve(本 fiber 当前态);真正的装载/卸载由 ctx 驱动
|
|
1687
|
+
*/
|
|
1688
|
+
settle(): Promise<this>;
|
|
1689
|
+
}
|
|
1690
|
+
|
|
1691
|
+
/** fiber 清理函数:可同步返回、可返回 promise(异步 disposer) */
|
|
1692
|
+
declare type FiberDisposer = () => void | Promise<void>;
|
|
1693
|
+
|
|
1694
|
+
/** Fiber 构造入参 */
|
|
1695
|
+
declare interface FiberInit {
|
|
1696
|
+
/** 插件唯一名 */
|
|
1697
|
+
name: string;
|
|
1698
|
+
/** 依赖服务名(P2 PENDING 编排用) */
|
|
1699
|
+
deps?: string[];
|
|
1700
|
+
/** 初始状态(默认 PENDING) */
|
|
1701
|
+
state?: FiberState;
|
|
1702
|
+
}
|
|
1703
|
+
|
|
1704
|
+
/**
|
|
1705
|
+
* Fiber —— 单个插件实例的"运行时句柄 + 生命周期状态机"(cordis 语义,自研、零第三方)。
|
|
1706
|
+
*
|
|
1707
|
+
* 目标:docs/plan/plugin-cordis-migration-plan.md P1。作者 `ctx.plugin(mod)`/`ctx.installPlugin(mod)`
|
|
1708
|
+
* 拿到一个 fiber,可查 state/config/deps、await 到稳定态(成功/失败)、dispose()。
|
|
1709
|
+
*
|
|
1710
|
+
* 状态机(对齐 cordis FiberState):
|
|
1711
|
+
* PENDING → LOADING → ACTIVE
|
|
1712
|
+
* ↘ ↘
|
|
1713
|
+
* (缺依赖) FAILED(apply/config 抛错)
|
|
1714
|
+
* 卸载: ACTIVE/FAILED/PENDING → UNLOADING → DISPOSED(不可再启动)
|
|
1715
|
+
*
|
|
1716
|
+
* Fiber 也是插件的"副作用容器":经 ctx 建立的注册(on/inject/provide/nodes.register…)都
|
|
1717
|
+
* onDispose/effect 进本 fiber,dispose() 时按注册逆序逐个跑清理,**支持异步 disposer**(逐项 await、
|
|
1718
|
+
* 单错不阻断),最终 DISPOSED。dispose() 幂等。
|
|
1719
|
+
*
|
|
1720
|
+
* 本类独立于 Context 可单测;Context 的插件装载路径逐步切到它(见 PLAN P1)。
|
|
1721
|
+
*/
|
|
1722
|
+
/** fiber 生命周期状态(cordis FiberState;用字符串名便于诊断/展示/比较) */
|
|
1723
|
+
declare const enum FiberState {
|
|
1724
|
+
/** 已声明 / 在等所需服务(P2 起:依赖未到齐即停留此态) */
|
|
1725
|
+
PENDING = "pending",
|
|
1726
|
+
/** apply / config 正在跑 */
|
|
1727
|
+
LOADING = "loading",
|
|
1728
|
+
/** 已加载并提供服务 */
|
|
1729
|
+
ACTIVE = "active",
|
|
1730
|
+
/** apply 或 config 校验抛错 */
|
|
1731
|
+
FAILED = "failed",
|
|
1732
|
+
/** disposer 正在跑(清理中) */
|
|
1733
|
+
UNLOADING = "unloading",
|
|
1734
|
+
/** 已卸载,不可再启动 */
|
|
1735
|
+
DISPOSED = "disposed"
|
|
1736
|
+
}
|
|
1737
|
+
|
|
1738
|
+
/** fiber 事件回调(ctx 注入用:emit internal/status / lifecycle 事件) */
|
|
1739
|
+
declare interface FiberTransition {
|
|
1740
|
+
(next: FiberState, prev: FiberState, fiber: Fiber): void;
|
|
1741
|
+
}
|
|
1742
|
+
|
|
1743
|
+
/** 历史里的一笔(= 一次生成) */
|
|
1744
|
+
export declare interface HistoryEntry {
|
|
1745
|
+
id: string;
|
|
1746
|
+
jobId: string;
|
|
1747
|
+
canvasId: string;
|
|
1748
|
+
nodeId: string;
|
|
1749
|
+
actionId: string;
|
|
1750
|
+
/** 展示名(动作标题,如「豆包 Seedream 4.5」) */
|
|
1751
|
+
title: string;
|
|
1752
|
+
/** 生成物类型 —— 前端按它分组 / 计数 */
|
|
1753
|
+
kind: 'image' | 'video' | 'audio' | 'text' | 'other';
|
|
1754
|
+
status: 'done' | 'error';
|
|
1755
|
+
/**
|
|
1756
|
+
* 评级。目前是**占位**(还没有人工审核流程):归档时统一写 'passed',
|
|
1757
|
+
* 这样前端那个"所有评级 / 已通过 / 待审核 / 已拒绝"下拉不是死控件,
|
|
1758
|
+
* 等真有审核流程再往里写其它值。
|
|
1759
|
+
*/
|
|
1760
|
+
rating: 'passed' | 'pending' | 'rejected';
|
|
1761
|
+
urls?: string[];
|
|
1762
|
+
text?: string;
|
|
1763
|
+
/** 用户当时的提示词(生成参数的一部分;标签引用资源 id) */
|
|
1764
|
+
prompts?: Array<{
|
|
1765
|
+
type: 'tag' | 'prompt';
|
|
1766
|
+
value: string;
|
|
1767
|
+
}>;
|
|
1768
|
+
/** 用户当时选的参数(比例 / 时长 / 模型档位…,键 = 动作声明的 ActionParam.key) */
|
|
1769
|
+
values?: Record<string, unknown>;
|
|
1770
|
+
/**
|
|
1771
|
+
* 参考素材(连进节点 / @ 引用的图、视频、文本)。
|
|
1772
|
+
*
|
|
1773
|
+
* url 是**画布内地址**(/api/canvases/.../resources/...),详情弹窗可直接显示缩略图;
|
|
1774
|
+
* 参考文本放 value。
|
|
1775
|
+
*/
|
|
1776
|
+
resources?: Array<{
|
|
1777
|
+
id?: string;
|
|
1778
|
+
kind: string;
|
|
1779
|
+
name?: string;
|
|
1780
|
+
url?: string;
|
|
1781
|
+
value?: string;
|
|
1782
|
+
}>;
|
|
1783
|
+
/** 产物媒体元数据(尺寸 / 时长 / 字节数):卡片用它画比例与角标,不必等媒体加载完 */
|
|
1784
|
+
media?: {
|
|
1785
|
+
width?: number;
|
|
1786
|
+
height?: number;
|
|
1787
|
+
/** 视频 / 音频时长(毫秒) */
|
|
1788
|
+
durationMs?: number;
|
|
1789
|
+
/** 产物字节数(文件大小) */
|
|
1790
|
+
bytes?: number;
|
|
1791
|
+
};
|
|
1792
|
+
createdAt: number;
|
|
1793
|
+
finishedAt: number;
|
|
1794
|
+
error?: string;
|
|
1795
|
+
}
|
|
1796
|
+
|
|
1797
|
+
/** 历史查询结果(分页 + 汇总一起给) */
|
|
1798
|
+
export declare interface HistoryPage {
|
|
1799
|
+
items: HistoryEntry[];
|
|
1800
|
+
total: number;
|
|
1801
|
+
page: number;
|
|
1802
|
+
pageSize: number;
|
|
1803
|
+
/** 汇总:一共生成过多少,按类型分 */
|
|
1804
|
+
summary: {
|
|
1805
|
+
total: number;
|
|
1806
|
+
byKind: Record<string, number>;
|
|
1807
|
+
};
|
|
1808
|
+
}
|
|
1809
|
+
|
|
1810
|
+
/** 历史查询的筛选条件 */
|
|
1811
|
+
export declare interface HistoryQuery {
|
|
1812
|
+
page?: number;
|
|
1813
|
+
pageSize?: number;
|
|
1814
|
+
/** 生成物类型筛选 */
|
|
1815
|
+
kind?: string;
|
|
1816
|
+
/** 状态筛选(done / error) */
|
|
1817
|
+
status?: string;
|
|
1818
|
+
/** 评级筛选(all / passed / pending / rejected) */
|
|
1819
|
+
rating?: string;
|
|
1820
|
+
/** 时间排序(默认 desc = 最新在前) */
|
|
1821
|
+
order?: 'asc' | 'desc';
|
|
1822
|
+
/** 按画布筛(省略 = 全部画布) */
|
|
1823
|
+
canvasId?: string;
|
|
1824
|
+
}
|
|
1825
|
+
|
|
1826
|
+
export declare function historyRoutes(history: HistoryStore, assetStore?: AssetStore): Hono;
|
|
1827
|
+
|
|
1828
|
+
export declare class HistoryStore {
|
|
1829
|
+
private readonly root;
|
|
1830
|
+
private readonly limit;
|
|
1831
|
+
private readonly listeners;
|
|
1832
|
+
constructor(root: string, limit?: number);
|
|
1833
|
+
/** 订阅「有新的历史」(后端把它接到 SSE 的信号键上) */
|
|
1834
|
+
onChange(listener: () => void): () => void;
|
|
1835
|
+
private notify;
|
|
1836
|
+
/** 读某画布的全部历史(最新的在前) */
|
|
1837
|
+
readAll(canvasId: string): Promise<HistoryEntry[]>;
|
|
1838
|
+
/**
|
|
1839
|
+
* 归档一笔。
|
|
1840
|
+
*
|
|
1841
|
+
* 最新在前(新的一笔插到头部),超出上限丢尾部(最旧的)。
|
|
1842
|
+
*/
|
|
1843
|
+
append(canvasId: string, entry: HistoryEntry): Promise<void>;
|
|
1844
|
+
/** 按条目 id 删除(批量操作用;跨画布也能删 —— 逐画布找)。返回是否删到了。 */
|
|
1845
|
+
remove(canvasId: string, id: string): Promise<boolean>;
|
|
1846
|
+
/** 按条目 id 改评级(批量操作用)。找不到返回 undefined。 */
|
|
1847
|
+
setRating(canvasId: string, id: string, rating: HistoryEntry['rating']): Promise<HistoryEntry | undefined>;
|
|
1848
|
+
/** 查一条(拿 canvasId / urls 等元数据;批量动作的入口)。 */
|
|
1849
|
+
find(id: string): Promise<HistoryEntry | undefined>;
|
|
1850
|
+
/**
|
|
1851
|
+
* 查询:筛选 + 排序 + 分页 + 汇总。
|
|
1852
|
+
*
|
|
1853
|
+
* 汇总(一共生成过多少 / 按类型分)**不受分页影响** —— 前端那几个计数徽章要的是总量。
|
|
1854
|
+
*/
|
|
1855
|
+
query(q?: HistoryQuery): Promise<HistoryPage>;
|
|
1856
|
+
/** 跨全部画布读("全部画布"那个筛选) */
|
|
1857
|
+
private readAllCanvases;
|
|
1858
|
+
}
|
|
1859
|
+
|
|
1860
|
+
/** 校验作用域是否合法(挡住把任意路径写进来的可能) */
|
|
1861
|
+
export declare function isKvType(v: string): v is KvType;
|
|
1862
|
+
|
|
1863
|
+
export declare function isSafeCanvasId(id: string): boolean;
|
|
1864
|
+
|
|
1865
|
+
export declare function isSafeResourceName(name: string): boolean;
|
|
1866
|
+
|
|
1867
|
+
/** 校验一个来源不明的模块是不是合法 provider(目录里可能是手写的、写错的 js) */
|
|
1868
|
+
export declare function isValidProvider(v: unknown): v is Provider;
|
|
1869
|
+
|
|
1870
|
+
/** 一个正在跑(或刚跑完)的任务 */
|
|
1871
|
+
export declare interface Job {
|
|
1872
|
+
/** jobId —— 节点 runState.taskId 存的就是它(刷新续查 / 取消都打这个) */
|
|
1873
|
+
id: string;
|
|
1874
|
+
canvasId: string;
|
|
1875
|
+
nodeId: string;
|
|
1876
|
+
actionId: string;
|
|
1877
|
+
/** 哪个 provider 领的单(取消 / 续查要路由回它) */
|
|
1878
|
+
providerId: string;
|
|
1879
|
+
/** provider 自己的任务号(后台内部用,前端不关心) */
|
|
1880
|
+
providerTaskId?: string;
|
|
1881
|
+
status: JobStatus;
|
|
1882
|
+
progress?: number;
|
|
1883
|
+
message?: string;
|
|
1884
|
+
/**
|
|
1885
|
+
* 这条任务能不能取消(由动作 / 平台的 cancel 声明决定)。
|
|
1886
|
+
*
|
|
1887
|
+
* 每一帧 runState 都会带上它 —— 节点壳只读节点数据决定画不画「取消」按钮,
|
|
1888
|
+
* 不去查动作表(刷新后动作清单还没到的那一小会儿也不会误判)。
|
|
1889
|
+
*/
|
|
1890
|
+
canCancel?: boolean;
|
|
1891
|
+
/**
|
|
1892
|
+
* 加载 UI 的展示字段(由 provider 每拍给出,任务管理器原样透传)。
|
|
1893
|
+
*
|
|
1894
|
+
* 为什么放在 job 上而不是让前端算:用户口径 2026-11-10 —— 进度是**后台的**数据,
|
|
1895
|
+
* provider 的轮询结果决定显示什么(token 数 / 自定义单位 / 滚动小尾巴),
|
|
1896
|
+
* 前端只把字段画出来,不自己判断任务类型、也不自己估数。
|
|
1897
|
+
*/
|
|
1898
|
+
value?: number;
|
|
1899
|
+
suffix?: string;
|
|
1900
|
+
progressText?: string;
|
|
1901
|
+
tail?: string;
|
|
1902
|
+
/** 终态产物 */
|
|
1903
|
+
result?: {
|
|
1904
|
+
ok: boolean;
|
|
1905
|
+
urls?: string[];
|
|
1906
|
+
text?: string;
|
|
1907
|
+
error?: string;
|
|
1908
|
+
taskId?: string;
|
|
1909
|
+
/** 产物落进画布后的**引用**(`<画布id>/<hashName>`):地址是它的投影,前端据此对账 */
|
|
1910
|
+
resourceId?: string;
|
|
1911
|
+
};
|
|
1912
|
+
/**
|
|
1913
|
+
* 下单时的原始请求快照(提示词 / 参数 / 参考素材)。
|
|
1914
|
+
*
|
|
1915
|
+
* 存**原始引用**而不是 resolveInput 之后的数据地址:后者是 provider 用的内嵌字节,
|
|
1916
|
+
* 塞进历史会把账本撑爆(一条视频参考动辄几十 MB)。这里只留画布内地址与文本值,
|
|
1917
|
+
* 详情弹窗据此还原"当时用了什么"。
|
|
1918
|
+
*/
|
|
1919
|
+
request?: {
|
|
1920
|
+
prompts?: Array<{
|
|
1921
|
+
type: 'tag' | 'prompt';
|
|
1922
|
+
value: string;
|
|
1923
|
+
}>;
|
|
1924
|
+
values?: Record<string, unknown>;
|
|
1925
|
+
resources?: Array<{
|
|
1926
|
+
id?: string;
|
|
1927
|
+
kind: string;
|
|
1928
|
+
name?: string;
|
|
1929
|
+
url?: string;
|
|
1930
|
+
value?: string;
|
|
1931
|
+
}>;
|
|
1932
|
+
};
|
|
1933
|
+
createdAt: number;
|
|
1934
|
+
finishedAt?: number;
|
|
1935
|
+
}
|
|
1936
|
+
|
|
1937
|
+
/** 一次任务提交的入参(前端下单时给的) */
|
|
1938
|
+
export declare interface JobInput {
|
|
1939
|
+
canvasId: string;
|
|
1940
|
+
/** 结果写回的目标节点 */
|
|
1941
|
+
nodeId: string;
|
|
1942
|
+
actionId: string;
|
|
1943
|
+
/** 用户在输入框写的内容:标签引用资源 id,普通文字单独成段(顺序即输入顺序) */
|
|
1944
|
+
prompts?: Array<{
|
|
1945
|
+
type: 'tag' | 'prompt';
|
|
1946
|
+
value: string;
|
|
1947
|
+
}>;
|
|
1948
|
+
/** 用户在可视化控件里选的值(键 = ActionParam.key) */
|
|
1949
|
+
values?: Record<string, unknown>;
|
|
1950
|
+
/**
|
|
1951
|
+
* 上游连进来的素材(图片 / 视频 / 文本)。
|
|
1952
|
+
*
|
|
1953
|
+
* `url` 是**画布内引用**(res:<hash>)或绝对地址;provider 若需要真实字节/真实地址,
|
|
1954
|
+
* 由宿主在提交前解析好(见 tasks/ 的说明)。
|
|
1955
|
+
*/
|
|
1956
|
+
resources?: Array<{
|
|
1957
|
+
id?: string;
|
|
1958
|
+
kind: string;
|
|
1959
|
+
name?: string;
|
|
1960
|
+
url?: string;
|
|
1961
|
+
value?: string;
|
|
1962
|
+
}>;
|
|
1963
|
+
}
|
|
1964
|
+
|
|
1965
|
+
export declare function jobsRoutes(tasks: TaskManager): Hono;
|
|
1966
|
+
|
|
1967
|
+
/**
|
|
1968
|
+
* 任务(Job)与历史记录的形状。
|
|
1969
|
+
*
|
|
1970
|
+
* 一句话分工:
|
|
1971
|
+
* - **Job** 是"这件事在跑",活在内存里(服务重启后由节点上的 runState 兜底);
|
|
1972
|
+
* - **HistoryEntry** 是"这件事跑完了",落在画布文件夹里(账本,只增不减)。
|
|
1973
|
+
*
|
|
1974
|
+
* 唯一事实来源:进度与终态都写到**节点自己的 runState** 上。
|
|
1975
|
+
* 前端读的就是它 —— 所以"关掉页面任务照跑、回来一看进度还在"是天然成立的。
|
|
1976
|
+
*/
|
|
1977
|
+
export declare type JobStatus = 'running' | 'done' | 'error';
|
|
1978
|
+
|
|
1979
|
+
/** 可持久化的 JSON 值(产物规范化到这一层,才谈得上"可落盘") */
|
|
1980
|
+
declare type JsonValue = null | boolean | number | string | JsonValue[] | {
|
|
1981
|
+
[k: string]: JsonValue;
|
|
1982
|
+
};
|
|
1983
|
+
|
|
1984
|
+
/**
|
|
1985
|
+
* 一次 kv 变更(set 或 remove 之后发出)。
|
|
1986
|
+
*
|
|
1987
|
+
* type 是作用域,key 是**裸 key**(不带 type: 前缀,如 settings)—— 与
|
|
1988
|
+
* /api/kv/:type/:key 的 URL 段、keys() 的返回保持同一套写法,订阅方不用再做前缀拼接。
|
|
1989
|
+
*/
|
|
1990
|
+
declare interface KvChangeEvent {
|
|
1991
|
+
type: string;
|
|
1992
|
+
key: string;
|
|
1993
|
+
}
|
|
1994
|
+
|
|
1995
|
+
export declare function kvRoutes(store: KvStore): Hono;
|
|
1996
|
+
|
|
1997
|
+
/**
|
|
1998
|
+
* kvStore —— 全部小数据装在一个 settings.json 里。
|
|
1999
|
+
*
|
|
2000
|
+
* 语义:get 未命中返回 **undefined**(不是 null)—— 调用方(CloudKvAdapter)靠它判
|
|
2001
|
+
* "从未保存过",与客户端 SaveStore 的 undefined 语义对齐。
|
|
2002
|
+
*/
|
|
2003
|
+
export declare class KvStore {
|
|
2004
|
+
private readonly dir;
|
|
2005
|
+
/** 变更订阅者(见 onChange) */
|
|
2006
|
+
private readonly changeListeners;
|
|
2007
|
+
/**
|
|
2008
|
+
* 写链:**所有写都排这一条**。
|
|
2009
|
+
*
|
|
2010
|
+
* 与"一项一文件"时代的关键差别:那时可以按 (type,key) 各排一条(不同项互不影响);
|
|
2011
|
+
* 现在全部落同一个文件,读-改-写必须整体串行 —— 否则两个并发写各读到同一份旧内容、
|
|
2012
|
+
* 各自写回,后写的把先写的整段盖掉(丢配置)。
|
|
2013
|
+
*/
|
|
2014
|
+
private chain;
|
|
2015
|
+
/** 旧布局迁移:只做一次(首次访问触发);记住 promise,避免并发首访各迁一遍 */
|
|
2016
|
+
private migration;
|
|
2017
|
+
constructor(dir: string);
|
|
2018
|
+
/** 把一次写排进链尾(链上任务失败不卡住后面的) */
|
|
2019
|
+
private runExclusive;
|
|
2020
|
+
/**
|
|
2021
|
+
* 订阅"某一项被写过/删过"。返回取消函数。
|
|
2022
|
+
*
|
|
2023
|
+
* 存在的理由:网页端与 AI(MCP)共用一个服务、一份数据,但**写入口是分散的**。
|
|
2024
|
+
* 要让网页端在 AI 改完之后实时看到变化,就必须有个统一的"谁写完了"信号 ——
|
|
2025
|
+
* 放在这一层,因为所有写路径最终都要落到 set/remove。
|
|
2026
|
+
*
|
|
2027
|
+
* 有意只报"哪个 type/key 变了",不带新值:订阅方按需自己去读。
|
|
2028
|
+
*/
|
|
2029
|
+
onChange(listener: (e: KvChangeEvent) => void): () => void;
|
|
2030
|
+
/** 通知订阅者;单个订阅者抛错不影响其它订阅者,也不影响写操作本身 */
|
|
2031
|
+
private notifyChange;
|
|
2032
|
+
/**
|
|
2033
|
+
* 读整个文件。
|
|
2034
|
+
*
|
|
2035
|
+
* 内容坏掉(非法 JSON)**抛错**,不静默当空:
|
|
2036
|
+
* 若当成空再写回,会把用户剩下的全部配置一起抹掉 —— 宁可这次请求失败、让人看见。
|
|
2037
|
+
* (get() 会把这个错误降级成 undefined + 一条 warn。)
|
|
2038
|
+
*/
|
|
2039
|
+
private readFile;
|
|
2040
|
+
/** 写整个文件(原子写:临时文件 + rename,读者永远看到完整内容) */
|
|
2041
|
+
private writeFile;
|
|
2042
|
+
/** 读一项;不存在返回 undefined */
|
|
2043
|
+
get<T = unknown>(type: string, key: string): Promise<T | undefined>;
|
|
2044
|
+
/** 写一项 */
|
|
2045
|
+
set(type: string, key: string, value: unknown): Promise<void>;
|
|
2046
|
+
/** 删一项;返回是否真删到 */
|
|
2047
|
+
remove(type: string, key: string): Promise<boolean>;
|
|
2048
|
+
/** 列某作用域下全部裸 key(诊断/后台查看用) */
|
|
2049
|
+
keys(type: string): Promise<string[]>;
|
|
2050
|
+
/** 迁移只跑一次;并发首访共用同一个 promise */
|
|
2051
|
+
private ensureMigrated;
|
|
2052
|
+
/**
|
|
2053
|
+
* 把旧布局的文件折进 settings.json。
|
|
2054
|
+
*
|
|
2055
|
+
* 要认两种旧形态:
|
|
2056
|
+
* 1. {dir}/kv/{type}/{key}.json —— 上一版
|
|
2057
|
+
* 2. {dir}/kv/{type}%3A{key}.json —— 最早那版(整串转义)
|
|
2058
|
+
*
|
|
2059
|
+
* 只搬 STORED_TYPES 里的两类(config / shortcut):canvas / resource 早已各有目录,
|
|
2060
|
+
* 把它们搬回来只会往配置里塞死数据。
|
|
2061
|
+
*
|
|
2062
|
+
* 搬完把整个 kv 目录**改名**(不是删)成 kv.migrated —— 留一份人肉可查的备份。
|
|
2063
|
+
* 新文件已存在时整段跳过。
|
|
2064
|
+
*/
|
|
2065
|
+
private migrateLegacy;
|
|
2066
|
+
}
|
|
2067
|
+
|
|
2068
|
+
/** 允许的作用域(与客户端 SaveType 一致) */
|
|
2069
|
+
export declare type KvType = 'config' | 'canvas' | 'resource' | 'shortcut';
|
|
2070
|
+
|
|
2071
|
+
/** 生命周期状态(裁掉 v1 无调用路径的 deactivate/inactive 三态) */
|
|
2072
|
+
declare enum Lifecycle {
|
|
2073
|
+
INSTALLING = "installing",
|
|
2074
|
+
INSTALLED = "installed",
|
|
2075
|
+
ACTIVATING = "activating",
|
|
2076
|
+
ACTIVE = "active",
|
|
2077
|
+
UNINSTALLING = "uninstalling",
|
|
2078
|
+
UNINSTALLED = "uninstalled",
|
|
2079
|
+
ERROR = "error"
|
|
2080
|
+
}
|
|
2081
|
+
|
|
2082
|
+
/** 两个根里出现过的插件目录名(并集,排好序;跳过 `.` / `_` 开头的临时目录) */
|
|
2083
|
+
export declare function listPluginIds(roots: PluginRoots): Promise<string[]>;
|
|
2084
|
+
|
|
2085
|
+
/** 列出所有工具 */
|
|
2086
|
+
export declare function listTools(): McpTool[];
|
|
2087
|
+
|
|
2088
|
+
/**
|
|
2089
|
+
* 扫一个目录,把里面每个 `.js` 当成 provider 加载。
|
|
2090
|
+
*
|
|
2091
|
+
* @param dir provider 目录;不存在 → 返回空(不是错误:可以一个外挂都没有)
|
|
2092
|
+
*/
|
|
2093
|
+
export declare function loadProvidersFromDir(dir: string, opts?: {
|
|
2094
|
+
config?: ProviderConfigFile;
|
|
2095
|
+
}): Promise<LoadResult>;
|
|
2096
|
+
|
|
2097
|
+
declare interface LoadResult {
|
|
2098
|
+
providers: Provider[];
|
|
2099
|
+
/** 逐个文件的加载情况(诊断用:哪个文件坏了、为什么) */
|
|
2100
|
+
failures: Array<{
|
|
2101
|
+
file: string;
|
|
2102
|
+
error: string;
|
|
2103
|
+
}>;
|
|
2104
|
+
/** 成功装载的文件名(按装载顺序)—— 管理接口据此把 id 映射回文件 */
|
|
2105
|
+
files: string[];
|
|
2106
|
+
}
|
|
2107
|
+
|
|
2108
|
+
/** 清单里的一项(与计划 §四 的 /plugin-manifest.json 形状一致) */
|
|
2109
|
+
export declare interface ManifestPluginEntry {
|
|
2110
|
+
/** 稳定身份(取自 package.json 的 name,退回落目录名) */
|
|
2111
|
+
id: string;
|
|
2112
|
+
/** 浏览器要 fetch 的插件地址(同源) */
|
|
2113
|
+
url: string;
|
|
2114
|
+
disabled?: boolean;
|
|
2115
|
+
}
|
|
2116
|
+
|
|
2117
|
+
/** 一个参数的简表类型(够覆盖绝大多数工具;复杂 schema 走宿主内置工具) */
|
|
2118
|
+
declare type McpParamType = 'string' | 'number' | 'boolean';
|
|
2119
|
+
|
|
2120
|
+
/**
|
|
2121
|
+
* @param pluginTools 取「当前插件注册的 MCP 工具」的函数。
|
|
2122
|
+
* 为什么传函数而不是数组:MCP server 是**每请求新建**的(stateless),
|
|
2123
|
+
* 每次建时现取才能反映"插件刚装/刚卸"的最新集合。缺省 = 没有插件工具(行为与以前一字不差)。
|
|
2124
|
+
*/
|
|
2125
|
+
export declare function mcpRoutes(doc: CanvasDocument, registry?: ProviderRegistry, tasks?: TaskManager, pluginTools?: () => McpToolDef[],
|
|
2126
|
+
/** 按画布取文档:AI 传 canvasId 时用它取对应画布(否则一切读写都落进默认画布) */
|
|
2127
|
+
resolveDoc?: CanvasDocResolver,
|
|
2128
|
+
/** 列出全部画布(canvas_list_canvases 用) */
|
|
2129
|
+
listCanvases?: () => Promise<Array<{
|
|
2130
|
+
id: string;
|
|
2131
|
+
name: string;
|
|
2132
|
+
}>>): Hono;
|
|
2133
|
+
|
|
2134
|
+
/** 工具清单(给 `--list-tools` 与诊断用;与实际注册保持一致) */
|
|
2135
|
+
export declare interface McpTool {
|
|
2136
|
+
name: string;
|
|
2137
|
+
description: string;
|
|
2138
|
+
}
|
|
2139
|
+
|
|
2140
|
+
/** 插件注册一个 MCP 工具时的声明 */
|
|
2141
|
+
declare interface McpToolDef {
|
|
2142
|
+
/** 工具名(建议 `插件名.动作` 形式,避免与内置工具撞名) */
|
|
2143
|
+
name: string;
|
|
2144
|
+
/** 给 AI 看的一句话说明(写好这句,AI 才知道什么时候用) */
|
|
2145
|
+
description: string;
|
|
2146
|
+
/** 参数简表:键 = 参数名,值 = 类型。缺省 = 不收参数 */
|
|
2147
|
+
input?: Record<string, McpParamType>;
|
|
2148
|
+
/** 必填参数名(缺省全可选) */
|
|
2149
|
+
required?: string[];
|
|
2150
|
+
/** 执行体:收参数、返回可 JSON 化的值 */
|
|
2151
|
+
handler(args: Record<string, unknown>): unknown | Promise<unknown>;
|
|
2152
|
+
}
|
|
2153
|
+
|
|
2154
|
+
/** 由文件名推 MIME(未知扩展名回落 octet-stream) */
|
|
2155
|
+
export declare function mimeFromName(name: string): string;
|
|
2156
|
+
|
|
2157
|
+
/** 由资源 id / 文件名推 MIME(与 mimeFromName 同一实现,保留旧名字给既有调用方) */
|
|
2158
|
+
export declare function mimeOf(id: string): string;
|
|
2159
|
+
|
|
2160
|
+
/** 一个生成类型的默认模型(图片 / 视频 / 音频 / 文本 / 以后可能有 3D) */
|
|
2161
|
+
declare type ModelDefaults = Record<string, string>;
|
|
2162
|
+
|
|
2163
|
+
/** 模型可调用工具(registryOf('tool'))条目 */
|
|
2164
|
+
declare interface ModelToolSurface {
|
|
2165
|
+
name: string;
|
|
2166
|
+
description: string;
|
|
2167
|
+
parameters: unknown;
|
|
2168
|
+
/** 产物 schema;工具未声明 output 时为 undefined(不用 {} 冒充 —— 审查 B2) */
|
|
2169
|
+
outputSchema?: unknown;
|
|
2170
|
+
source: string;
|
|
2171
|
+
}
|
|
2172
|
+
|
|
2173
|
+
/** 节点批量入参(三段都可省略) */
|
|
2174
|
+
export declare interface NodeBatchInput {
|
|
2175
|
+
add?: AddNodeInput[];
|
|
2176
|
+
delete?: string[];
|
|
2177
|
+
/**
|
|
2178
|
+
* 新增时若 id 已存在:当成更新(而不是整批拒绝)。
|
|
2179
|
+
*
|
|
2180
|
+
* 给**同步口**用(网页端提交增量):AI 刚加的节点会被实时通道合进网页端,
|
|
2181
|
+
* 于是网页端下一次提交里就带上了「新增这个已在云端的节点」。对 AI 来说这种说法确实是错的,
|
|
2182
|
+
* 但对同步口来说它是**正常时序** —— 若照旧整批拒绝,用户那次真正的改动会被连带丢掉。
|
|
2183
|
+
*
|
|
2184
|
+
* 不给(缺省 false)= MCP 工具的严格语义:AI 说自己要建一个新 id,那它就该是新的。
|
|
2185
|
+
*/
|
|
2186
|
+
upsert?: boolean;
|
|
2187
|
+
/**
|
|
2188
|
+
* 删除/更新一个**不存在**的目标时:静默跳过,而不是整批拒绝。
|
|
2189
|
+
*
|
|
2190
|
+
* 同样只给同步口用,理由与 upsert 一样:网页端提交的是「我这份与上一份的差集」,
|
|
2191
|
+
* 而「我这边看起来还在、云端已经被 AI 删掉」是并发下的正常时序。
|
|
2192
|
+
* 若照旧整批拒绝,用户那次真实的改动会被一个过时的删除请求连带丢掉。
|
|
2193
|
+
*
|
|
2194
|
+
* 注意这不会掩盖真错误:AI 自己(MCP)仍然走严格语义,写错 id 会明确报出来。
|
|
2195
|
+
*/
|
|
2196
|
+
lenient?: boolean;
|
|
2197
|
+
update?: {
|
|
2198
|
+
id: string;
|
|
2199
|
+
position?: {
|
|
2200
|
+
x: number;
|
|
2201
|
+
y: number;
|
|
2202
|
+
};
|
|
2203
|
+
data?: Record<string, unknown>;
|
|
2204
|
+
/** 明确删除 data 的哪些 key(浅合并删不掉;网页同步与 MCP 都用它表达字段删除) */
|
|
2205
|
+
dataUnset?: string[];
|
|
2206
|
+
/** 尺寸(网页端「图片跟随尺寸」这类改动会写它;增量写不能漏这个字段) */
|
|
2207
|
+
size?: {
|
|
2208
|
+
w: number;
|
|
2209
|
+
h: number;
|
|
2210
|
+
};
|
|
2211
|
+
/** 父节点(分组嵌套);显式 null 表示解除父子 */
|
|
2212
|
+
parentId?: string | null;
|
|
2213
|
+
}[];
|
|
2214
|
+
}
|
|
2215
|
+
|
|
2216
|
+
/**
|
|
2217
|
+
/**
|
|
2218
|
+
* 找「随包插件目录」(只读兜底)。全局目录由 pluginRoots 按数据根算,不走这里。
|
|
2219
|
+
*
|
|
2220
|
+
* 2026-11-12 起插件**两层**:全局 `<数据根>/plugins` 优先、随包 `assets/plugins` 兜底,
|
|
2221
|
+
* 按插件解析实际生效的那一份 —— 见 src/plugins/pluginRoots.ts。
|
|
2222
|
+
*/
|
|
2223
|
+
export declare function packagedPluginsDir(): string;
|
|
2224
|
+
|
|
2225
|
+
/**
|
|
2226
|
+
* provider(平台提供方)契约 —— 「后台也能像前端那样丢文件扩展」的接口。
|
|
2227
|
+
*
|
|
2228
|
+
* 前端加能力 = 丢一个插件进目录;后台过去只能改源码。这一层把后台也开成目录扫描:
|
|
2229
|
+
* 每个 `.js` 就是一个 provider,声明它提供哪些动作、怎么提交任务、怎么查进度、怎么取消。
|
|
2230
|
+
*
|
|
2231
|
+
* 内置的 web2api 也**用同一套接口**写成第一个 provider —— 内置与外挂走同一条路,
|
|
2232
|
+
* 不存在「内置一套、外挂另一套」。照抄内置那个就知道自己该怎么写。
|
|
2233
|
+
*
|
|
2234
|
+
* 与前端的关系:后端拿所有 provider 的 `actions` 并集喂给前端当菜单。
|
|
2235
|
+
* 所以后台加一个平台,前端的模型下拉里自动多一项,前端一行不用改。
|
|
2236
|
+
*/
|
|
2237
|
+
/** 动作参数的一种取值(下拉用) */
|
|
2238
|
+
declare interface ParamOption {
|
|
2239
|
+
label: string;
|
|
2240
|
+
value: string;
|
|
2241
|
+
}
|
|
2242
|
+
|
|
2243
|
+
/**
|
|
2244
|
+
* 读产物运行时需要的 window 全局名。
|
|
2245
|
+
* 只认 UMD 头那段参数列表里的 e.Vue 形态(require 分支里是字符串 'vue',不算)——
|
|
2246
|
+
* 锚定到全局名之后 800 字符内,避免正文里的字符串误命中。
|
|
2247
|
+
*/
|
|
2248
|
+
export declare function parseRequiresGlobals(text: string): string[];
|
|
2249
|
+
|
|
2250
|
+
/**
|
|
2251
|
+
* 从 UMD 产物文本里读出它的全局名。
|
|
2252
|
+
*
|
|
2253
|
+
* 打包时 css-injected-by-js 会先插一段很长的 style,真正的 UMD 头被挤到几千字符之后,
|
|
2254
|
+
* 所以**不能只看文件开头**;直接全文找那段 e.PlumePluginXxx={} 。
|
|
2255
|
+
*/
|
|
2256
|
+
export declare function parseUmdGlobalName(text: string): string | undefined;
|
|
2257
|
+
|
|
2258
|
+
/**
|
|
2259
|
+
* 能力段形状:挂在插件 ctx 上的注册收口。
|
|
2260
|
+
*
|
|
2261
|
+
* 分两类:
|
|
2262
|
+
* - **内核自带**:`tools`(注册外部能力、按名调用;通用、与画布无关,恒在)。
|
|
2263
|
+
* - **能力层提供**:如画布的 `nodes/theme/commands/slots/settings`——框架不认识它们,
|
|
2264
|
+
* 形状由能力层经声明合并补进本接口(见 @plume-canvas/canvas-data 的 canvas/capabilityTypes.ts)。
|
|
2265
|
+
*/
|
|
2266
|
+
declare interface PluginCapabilities {
|
|
2267
|
+
/**
|
|
2268
|
+
* 工具(外部能力调用:文生图 / 文生文 / 任意可注册能力),自动回收。
|
|
2269
|
+
*
|
|
2270
|
+
* 工具作者:`export const inject = ['tools']` + `ctx.tools.register(def)`,
|
|
2271
|
+
* 加一个新能力 = 装一个注册了新工具的插件,消费方零改动。
|
|
2272
|
+
* 消费方:`ctx.tools.list({ produces: 'image' })` 挑工具 → `ctx.tools.invoke(name, input, opts)` 调用。
|
|
2273
|
+
*/
|
|
2274
|
+
tools: {
|
|
2275
|
+
/** 注册一个工具(返回撤销句柄,同名重复抛错)。注册随所属插件卸载自动回收 */
|
|
2276
|
+
register(def: ToolDef): Disposable_2;
|
|
2277
|
+
/** 按名注销;不存在返回 false */
|
|
2278
|
+
unregister(name: string): boolean;
|
|
2279
|
+
has(name: string): boolean;
|
|
2280
|
+
get(name: string): ToolDef | undefined;
|
|
2281
|
+
/** 枚举工具(可按分组 / 产出类型 / 可接受输入筛选) */
|
|
2282
|
+
list(filter?: ToolFilter): ToolDef[];
|
|
2283
|
+
/** 调用工具(自动驱动异步轮询 / 超时,进度经 onProgress 转发) */
|
|
2284
|
+
invoke(name: string, input: ToolInput, options?: ToolInvokeOptions): Promise<ToolResult>;
|
|
2285
|
+
};
|
|
2286
|
+
}
|
|
2287
|
+
|
|
2288
|
+
/** 整份清单 */
|
|
2289
|
+
export declare interface PluginCatalog {
|
|
2290
|
+
ok: true;
|
|
2291
|
+
/** 内容版本:清单一变就变;前端可据此省掉重复搬运 */
|
|
2292
|
+
version: number;
|
|
2293
|
+
plugins: PluginCatalogEntry[];
|
|
2294
|
+
/** 扫到但没收进来的文件及原因(诊断用,不影响使用) */
|
|
2295
|
+
skipped: Array<{
|
|
2296
|
+
file: string;
|
|
2297
|
+
reason: string;
|
|
2298
|
+
}>;
|
|
2299
|
+
/**
|
|
2300
|
+
* 自带插件(首启自动安装)的 id 列表。
|
|
2301
|
+
*
|
|
2302
|
+
* 归属由项目决定(src/plugins/builtinPlugins.ts),不读插件自己的 plume.builtin。
|
|
2303
|
+
* 前端首次启动时按它装;用户卸过之后以用户的选择为准。
|
|
2304
|
+
*/
|
|
2305
|
+
builtinInstallIds?: string[];
|
|
2306
|
+
/** 首启时排在最前面的插件(cloud-client 必须先装,否则后台能力不可用) */
|
|
2307
|
+
firstInstallIds?: string[];
|
|
2308
|
+
}
|
|
2309
|
+
|
|
2310
|
+
/** 清单里的一项 —— 插件管理据此渲染一行、并按 url 去加载 */
|
|
2311
|
+
export declare interface PluginCatalogEntry {
|
|
2312
|
+
/** 稳定身份(目录名);插件管理用它做「已装/未装」的键 */
|
|
2313
|
+
id: string;
|
|
2314
|
+
/** 插件在画布里的**真实名字**(源码 export 的 name;可用 package.json 的 plume.pluginName 声明) */
|
|
2315
|
+
name: string;
|
|
2316
|
+
/** 面板上显示的名字(package.json 的 plume.title,缺省用 id) */
|
|
2317
|
+
title: string;
|
|
2318
|
+
description?: string;
|
|
2319
|
+
/** 浏览器可直接请求的地址(**相对本服务**,如 /plugins/<pkg>/<file>) */
|
|
2320
|
+
url: string;
|
|
2321
|
+
/**
|
|
2322
|
+
* 产物形态 —— 决定面板用哪条路装它。
|
|
2323
|
+
*
|
|
2324
|
+
* - 'umd'(缺省):external 掉 vue/内核、靠 window 全局取依赖,用 <script> 加载;
|
|
2325
|
+
* - 'esm':自包含 ES 模块(零裸模块名 import),交宿主 manager.install({ url }) 走 import 加载。
|
|
2326
|
+
*
|
|
2327
|
+
* 为什么必须显式区分:两条路不通用(UMD 走 import 会炸;ESM 走 <script> 取不到全局对象)。
|
|
2328
|
+
* 缺省 'umd' 保持既有插件(全是 UMD)行为不变。
|
|
2329
|
+
*/
|
|
2330
|
+
format?: 'umd' | 'esm';
|
|
2331
|
+
/** UMD 产物在 window 上暴露的全局名(加载后从这里取插件对象) */
|
|
2332
|
+
globalName: string;
|
|
2333
|
+
/**
|
|
2334
|
+
* 全局对象上**哪一个导出**才是插件模块(如 `themeCanvasPlugin`)。
|
|
2335
|
+
*
|
|
2336
|
+
* 缺省表示「全局对象本身就是插件模块」(只导出 name/apply 的简单插件)。
|
|
2337
|
+
* 有值时必须取 `window[globalName][moduleExport]` —— 否则拿到的是整袋导出,
|
|
2338
|
+
* 内核会报 `apply is not a function`。
|
|
2339
|
+
*/
|
|
2340
|
+
moduleExport?: string;
|
|
2341
|
+
/** 该产物运行时需要哪些 window 全局(Vue / PlumeCore / …);缺了会加载失败 */
|
|
2342
|
+
requiresGlobals: string[];
|
|
2343
|
+
/** 是否默认安装(缺省 true) */
|
|
2344
|
+
defaultInstalled: boolean;
|
|
2345
|
+
/**
|
|
2346
|
+
* 是否**自带**(随应用冷启动装配、不可从插件管理页装卸)。
|
|
2347
|
+
*
|
|
2348
|
+
* 为什么要在清单里列出它们:用户要"即使自带的插件也显示出来,但不显示安装/卸载按钮" ——
|
|
2349
|
+
* 一个页面能看清"这台画布一共有哪些插件、哪些是我能动的",比只列可装卸的更完整。
|
|
2350
|
+
* 判据是**项目自己的内置清单**(builtinPlugins.ts 的目录名),不读插件
|
|
2351
|
+
* package.json 里的 plume.builtin —— 同一个插件在别的发行版里可能只是可装卸件,
|
|
2352
|
+
* 归属该由发行方决定。前端据此**只读展示**。
|
|
2353
|
+
*/
|
|
2354
|
+
builtin?: boolean;
|
|
2355
|
+
/**
|
|
2356
|
+
* 这个目录是**从 NPM 安装落盘**的副本(安装路由写入 package.json 的显式标记)。
|
|
2357
|
+
*
|
|
2358
|
+
* 用途:同名插件(源码包 + NPM 副本)去重时优先保留副本 —— 卸载只删副本,不动源码。
|
|
2359
|
+
* 用显式标记而不是猜 id 里有没有 `scope__`:包名去 scope 后那个判据会失效(审查指出)。
|
|
2360
|
+
*/
|
|
2361
|
+
npmInstalled?: boolean;
|
|
2362
|
+
/**
|
|
2363
|
+
* 后台插件产物(同一个包里若还有 dist/server.js,则这一项有值)。
|
|
2364
|
+
*
|
|
2365
|
+
* 为什么放在同一条清单项里:用户要的是「一个插件 = 前后端一起装」的体验。
|
|
2366
|
+
* 前后端是**同一个发布单元**的两半,用同一个 id 配对,界面上显示成一张卡片、
|
|
2367
|
+
* 两个状态灯(前端 ✓ / 后台 ✓)。只有一半的插件也合法(另一半留空)。
|
|
2368
|
+
*/
|
|
2369
|
+
server?: {
|
|
2370
|
+
/** 后台产物地址(相对本服务,如 /plugins/<pkg>/server.js) */
|
|
2371
|
+
url: string;
|
|
2372
|
+
/**
|
|
2373
|
+
* 后台产物的 sha256(**服务端算的信任源**,不是调用方声明的)。
|
|
2374
|
+
* 安装时用它校验完整性;没有它 → 拒绝安装(见 routes/serverPlugins.ts 的说明)。
|
|
2375
|
+
*/
|
|
2376
|
+
sha256?: string;
|
|
2377
|
+
/** 声明的权限(如 net / store / fs);目前只记录与展示,不做强制 */
|
|
2378
|
+
permissions?: string[];
|
|
2379
|
+
};
|
|
2380
|
+
version?: string;
|
|
2381
|
+
}
|
|
2382
|
+
|
|
2383
|
+
/**
|
|
2384
|
+
* 类形态插件装载单元(cordis 03):可 new 的类,通常 extends Service(构造即 super(ctx,name) 上架服务)。
|
|
2385
|
+
*
|
|
2386
|
+
* 核心插件标识也走静态字段:`static core = true` → `asPluginModule` 归一后透传进
|
|
2387
|
+
* PluginModule.core(决策 1)。类型上不强制声明(静态字段不在实例类型里)。
|
|
2388
|
+
*/
|
|
2389
|
+
declare type PluginClassLike = new (ctx: PluginScope, config?: any) => unknown;
|
|
2390
|
+
|
|
2391
|
+
/**
|
|
2392
|
+
* 插件模块形状(对齐 docs/goal/plugin-system-goal.md 2.1b 的 Cordis 式写法)。
|
|
2393
|
+
*
|
|
2394
|
+
* Cordis 式(推荐,教程主推):`.ts` 裸导出四样 `name / inject / Config / apply`——
|
|
2395
|
+
* - `name`:插件唯一名
|
|
2396
|
+
* - `inject`:依赖的服务/插件名数组(没有可省)
|
|
2397
|
+
* - `Config`(可选):本插件可配置项的 schema(cordis ch5 形态)。装配处给的 config 经它校验、
|
|
2398
|
+
* 默认补齐后,内核以第二个实参 `apply(ctx, config)` 传入;校验失败 → fiber FAILED + 响亮报错。
|
|
2399
|
+
* - `apply(ctx, config)`:注册函数,ctx 是能力台(ctx.nodes/theme/commands/slots/settings),注册自动回收
|
|
2400
|
+
*
|
|
2401
|
+
* 只认这四个字段;旧式的 `setup` / `deps` 不再接受。
|
|
2402
|
+
* apply 的返回值(cleanup)或经 ctx 登记的副作用都自动归入本插件的 scope,卸载即清。
|
|
2403
|
+
*/
|
|
2404
|
+
declare interface PluginModule<TConfig extends object = object> {
|
|
2405
|
+
/** 插件唯一名 */
|
|
2406
|
+
name: string;
|
|
2407
|
+
/**
|
|
2408
|
+
* 核心插件标识(决策 1):`true` = 拒绝动态热卸(`ctx.uninstallPlugin` 返回 `false`,
|
|
2409
|
+
* 且不 dispose fiber、不发 `ctx:plugin-uninstalled`、不连带回退依赖方)。
|
|
2410
|
+
*
|
|
2411
|
+
* 为什么必须:提供方一卸,依赖它的插件全部回退 PENDING。若画布基础服务由普通插件提供,
|
|
2412
|
+
* 它一被卸画布直接瘫——所以"谁能被卸"必须有答案。
|
|
2413
|
+
*
|
|
2414
|
+
* 只挡"动态卸载":整体生命周期终结(`ctx.stop()` / `stopAsync()`)不拦,页面关闭时核心插件
|
|
2415
|
+
* 也要正常回收。
|
|
2416
|
+
*
|
|
2417
|
+
* 两种形态都给得出来:对象形态 `{ name, core: true, apply }`;类形态 `static core = true`。
|
|
2418
|
+
*/
|
|
2419
|
+
core?: boolean;
|
|
2420
|
+
/**
|
|
2421
|
+
* 依赖的服务/插件名(**硬依赖**):缺失则该插件停在 PENDING、不加载。
|
|
2422
|
+
* 写法是模块顶层 `export const inject = ['tools']`(框架保证 apply 时就绪)。
|
|
2423
|
+
* 可选依赖不要写这里 —— 在使用处用 `ctx.get(name)` 探测。
|
|
2424
|
+
*/
|
|
2425
|
+
inject?: string[];
|
|
2426
|
+
/** 本插件的 config schema(cordis ch5)。装配 config 经它校验+补默认;apply(ctx,config) 收结果。 */
|
|
2427
|
+
Config?: ConfigSchema;
|
|
2428
|
+
/** 注册函数:ctx 是能力台,config 是校验并补默认后的配置。 */
|
|
2429
|
+
apply(ctx: PluginScope, config?: TConfig): void | (() => void) | Disposable_2;
|
|
2430
|
+
}
|
|
2431
|
+
|
|
2432
|
+
export declare interface PluginRoots {
|
|
2433
|
+
/** 全局目录(可写):安装 / 更新 / 用户自己放插件都在这里 */
|
|
2434
|
+
global: string;
|
|
2435
|
+
/** 随包目录(只读兜底);没有就 undefined */
|
|
2436
|
+
packaged?: string;
|
|
2437
|
+
}
|
|
2438
|
+
|
|
2439
|
+
/** 插件路由:清单 + 插件产物(两者都要扫描磁盘,改完刷新即生效) */
|
|
2440
|
+
export declare function pluginRoutes(pluginsDir: string | PluginRoots | undefined): Hono;
|
|
2441
|
+
|
|
2442
|
+
/** 单个插件的运行时态快照(P5:宿主/管理器/console 做 fiber 状态可查与 PENDING 诊断的只读视图) */
|
|
2443
|
+
declare interface PluginRuntimeStatus {
|
|
2444
|
+
/** 插件唯一名 */
|
|
2445
|
+
name: string;
|
|
2446
|
+
/** fiber 状态名(pending/loading/active/failed/unloading/disposed,字符串便于展示/比较) */
|
|
2447
|
+
state: string;
|
|
2448
|
+
/** 该插件 deps 中此刻仍未满足的依赖(仅当 state!=='active' 才可能非空;对齐 depSatisfied 判定) */
|
|
2449
|
+
missingDeps: string[];
|
|
2450
|
+
/** FAILED 时的错误信息(message 字符串,便于面板/console 展示);非 FAILED 缺省 */
|
|
2451
|
+
error?: string;
|
|
2452
|
+
/**
|
|
2453
|
+
* 是否核心插件(决策 1:拒绝动态热卸)。宿主 UI 据此**禁用卸载按钮**,
|
|
2454
|
+
* 而不是等用户点了才被拒(可诊断 > 事后报错)。非核心插件不带本字段。
|
|
2455
|
+
*/
|
|
2456
|
+
core?: boolean;
|
|
2457
|
+
}
|
|
2458
|
+
|
|
2459
|
+
/**
|
|
2460
|
+
* PluginScope —— 单个插件在 setup(ctx) 里拿到的"能力视图"。
|
|
2461
|
+
*
|
|
2462
|
+
* 它把根 Context 的能力暴露给插件,但**所有副作用自动登记进本插件自己的 Scope**:
|
|
2463
|
+
* - on/effect/inject 登记进本插件 scope → 插件卸载(scope.dispose)即自动清光。
|
|
2464
|
+
* - get/emit 是读操作 / 广播,不登记。
|
|
2465
|
+
* - nodes/theme/commands/slots 是注册收口(见 PluginCapabilities)。
|
|
2466
|
+
*/
|
|
2467
|
+
declare interface PluginScope extends PluginCapabilities {
|
|
2468
|
+
/** 订阅事件(自动回收)。事件名在 Events/EventMap 里则监听参数有类型;否则松类型。 */
|
|
2469
|
+
on<K extends string>(name: K, handler: EventHandlerFor<K>): Disposable_2;
|
|
2470
|
+
once<K extends string>(name: K, handler: EventHandlerFor<K>): Disposable_2;
|
|
2471
|
+
/** 广播事件(单源,不碰 window)。多参/单 payload 视事件表形态而定。 */
|
|
2472
|
+
emit<K extends string>(name: K, ...args: EventArgsFor<K>): void;
|
|
2473
|
+
/** 副作用(包 timer/watch/DOM,返回 cleanup 自动回收) */
|
|
2474
|
+
effect(fn: EffectFn): Disposable_2;
|
|
2475
|
+
/** 提供服务(上架);撤销自动登记进本插件 scope */
|
|
2476
|
+
inject<Service>(name: string, impl: Service): () => void;
|
|
2477
|
+
/** 提供服务(cordis 语义,与 inject 等价);Service 子类 super(ctx,name) 内部调用 */
|
|
2478
|
+
provide<Service>(name: string, impl: Service): () => void;
|
|
2479
|
+
/**
|
|
2480
|
+
* 取服务。
|
|
2481
|
+
*
|
|
2482
|
+
* 首选写法是模块顶层 `export const inject = ['xxx']` 声明依赖(框架保证 apply 时就绪;
|
|
2483
|
+
* 缺提供方则停在 PENDING)。本方法用于**可选依赖**:能力缺失时插件仍能跑,则跳过 inject、
|
|
2484
|
+
* 在此探测 —— 缺服务返回 undefined(不抛)。
|
|
2485
|
+
*/
|
|
2486
|
+
/**
|
|
2487
|
+
* 取服务。两种写法都支持:
|
|
2488
|
+
* - **按服务名推导**(首选):服务名在 interface Services 里声明过时,返回类型直接由名字决定
|
|
2489
|
+
* (get('doc') → DocService),不必再手写泛型。
|
|
2490
|
+
* - **显式指定**(扩展服务/可选探测):get<MyThing>('my-thing')。
|
|
2491
|
+
*/
|
|
2492
|
+
get<K extends keyof Services>(name: K): Services[K];
|
|
2493
|
+
get<Service = unknown>(name: string): Service;
|
|
2494
|
+
/** get 的可选依赖别名:缺服务返回 undefined(按服务名推导同理) */
|
|
2495
|
+
tryGet<K extends keyof Services>(name: K): Services[K] | undefined;
|
|
2496
|
+
tryGet<Service = unknown>(name: string): Service | undefined;
|
|
2497
|
+
/** 嵌套插件(本插件子作用域)。支持类形态(Service 子类)与 PluginModule 对象。 */
|
|
2498
|
+
plugin(mod: PluginModule | PluginClassLike): PluginScope;
|
|
2499
|
+
/**
|
|
2500
|
+
* 插件注册表只读视图(cordis 06):可枚举每插件的 fiber(含 PENDING 诊断/await)。
|
|
2501
|
+
* 返回 name → { status, fiber } 的只读 Map;纯只读。
|
|
2502
|
+
*/
|
|
2503
|
+
readonly registry: ReadonlyMap<string, {
|
|
2504
|
+
status: {
|
|
2505
|
+
name: string;
|
|
2506
|
+
state: string;
|
|
2507
|
+
missingDeps: string[];
|
|
2508
|
+
error?: string;
|
|
2509
|
+
};
|
|
2510
|
+
fiber: unknown;
|
|
2511
|
+
}>;
|
|
2512
|
+
/**
|
|
2513
|
+
* 取某 kind 的注册场(设计文档 §2.1 / 决策 6)。
|
|
2514
|
+
*
|
|
2515
|
+
* 同一 kind 各插件拿到的是同一张表(互相看得见,这正是"别人放的东西我能继续包"的前提);
|
|
2516
|
+
* 本插件视图只多两件事:写进条目的 source = 本插件名(谁放的,可诊断),
|
|
2517
|
+
* 以及本插件放置(add/wrap)的条目随本插件卸载自动回收。
|
|
2518
|
+
*
|
|
2519
|
+
* 注意:ctx.registry 是插件运行态诊断(cordis 06),与本方法无关,名字也不要改。
|
|
2520
|
+
*/
|
|
2521
|
+
registryOf<T>(kind: string): Registry<T>;
|
|
2522
|
+
/**
|
|
2523
|
+
* 插件私有状态(§二 原语 ⑥):内核只存值、不做响应式(响应式由渲染层决定)。
|
|
2524
|
+
* 不占服务名——它是插件自己的数据,不是"别人按名取的能力"(规则 7)。
|
|
2525
|
+
* 随本插件 scope 自动回收:卸载后 value 清空,状态不再可达。
|
|
2526
|
+
*/
|
|
2527
|
+
state<T>(initial: T): State<T>;
|
|
2528
|
+
/** 是否开发态(内核构造时的 dev 选项;原来只是 private 字段,插件读不到) */
|
|
2529
|
+
readonly isDev: boolean;
|
|
2530
|
+
/**
|
|
2531
|
+
* 能否动态卸载某插件(决策 1:调用方"先问再动")。
|
|
2532
|
+
*
|
|
2533
|
+
* `ctx.uninstallPlugin(name)` 把"核心插件拒卸"与"插件不存在"同值成 `false`(沿用既有契约),
|
|
2534
|
+
* 本方法给出原因,供调用方(pluginManager / 宿主 UI)在动手前分流,从根上避免
|
|
2535
|
+
* "先删了配置才发现卸不动"这类副作用。
|
|
2536
|
+
*/
|
|
2537
|
+
canUninstall(name: string): CanUninstallResult;
|
|
2538
|
+
/**
|
|
2539
|
+
* 自省快照:一次列出三根轴(服务 / 注册场 / 命令与工具)上「注册了什么、各自支持什么」。
|
|
2540
|
+
* 只读、零副作用,随时可调。诊断面板 / 文档生成 / AI 探查用。
|
|
2541
|
+
*/
|
|
2542
|
+
surface(): SurfaceReport;
|
|
2543
|
+
/** 并发跑所有监听并一同等待 */
|
|
2544
|
+
parallel<K extends string>(name: K, ...args: EventArgsFor<K>): Promise<void>;
|
|
2545
|
+
/** 顺序 await,第一个 bail 值胜出并停止 */
|
|
2546
|
+
serial<K extends string>(name: K, ...args: EventArgsFor<K>): Promise<any>;
|
|
2547
|
+
/** serial 的同步版(同步短路) */
|
|
2548
|
+
bail<K extends string>(name: K, ...args: EventArgsFor<K>): any;
|
|
2549
|
+
/** 环绕中间件:监听器可转写 next() 返回值或短路 */
|
|
2550
|
+
waterfall<K extends string>(name: K, ...args: EventArgsFor<K>): any;
|
|
2551
|
+
}
|
|
2552
|
+
|
|
2553
|
+
/**
|
|
2554
|
+
* 平台提供方。
|
|
2555
|
+
*
|
|
2556
|
+
* 一个文件、纯 JS、**不需要引任何东西** —— 丢进 providers 目录、重启即生效。
|
|
2557
|
+
* 三个方法都可选(只做同步生成的话,`submit` 直接返回 `{done:true}` 即可)。
|
|
2558
|
+
*/
|
|
2559
|
+
export declare interface Provider {
|
|
2560
|
+
/** provider id(唯一;用来把任务路由回它) */
|
|
2561
|
+
id: string;
|
|
2562
|
+
/**
|
|
2563
|
+
* 界面上显示的平台名字(中文名优先)。缺省时前端回落成 `id`。
|
|
2564
|
+
*
|
|
2565
|
+
* 用户口径 2026-11-10:平台要有自己的名称和介绍,与 `id` / `config` 同级直接写。
|
|
2566
|
+
*/
|
|
2567
|
+
title?: string;
|
|
2568
|
+
/** 一行介绍(显示在名字下面) */
|
|
2569
|
+
description?: string;
|
|
2570
|
+
/**
|
|
2571
|
+
* 平台图标:SVG 字符串 / `data:image/...;base64,...` / 图标名。
|
|
2572
|
+
*
|
|
2573
|
+
* 两处消费:① 平台管理列表;② 作为该平台模型的**兜底图标**(动作与 Agent 品牌图标都认不出时用它)。
|
|
2574
|
+
*/
|
|
2575
|
+
icon?: string;
|
|
2576
|
+
/** 它提供哪些动作 */
|
|
2577
|
+
actions: ActionDef[];
|
|
2578
|
+
/**
|
|
2579
|
+
* 它需要哪些配置项(管理页「平台」页据此长表单;多账号每套一份)。
|
|
2580
|
+
*
|
|
2581
|
+
* 已存的值由装载器注入成 `__mcProviderConfig` 常量:
|
|
2582
|
+
* { accounts: [{id, name, values}], values: 第一账号的 values, byId: {id → values} }
|
|
2583
|
+
* provider 里用 `typeof __mcProviderConfig === 'undefined'` 兜底
|
|
2584
|
+
* (测试 / 直接 import 源文件时该常量不存在,不能直接引用)。
|
|
2585
|
+
*/
|
|
2586
|
+
config?: ProviderConfigField[];
|
|
2587
|
+
/** 提交一个任务 */
|
|
2588
|
+
/**
|
|
2589
|
+
* @param signal 取消信号(TaskManager 的 AbortController):长跑型 submit(如 Agent 对话)
|
|
2590
|
+
* 用它响应节点上的「取消」;轮询型 submit 可以忽略 —— 那类取消走 cancel()。
|
|
2591
|
+
*/
|
|
2592
|
+
submit(action: ActionDef, input: JobInput, signal?: AbortSignal): Promise<ProviderSubmitResult>;
|
|
2593
|
+
/** 查一次进度(submit 给了 taskId 才需要) */
|
|
2594
|
+
poll?(taskId: string, action: ActionDef): Promise<ProviderPollResult>;
|
|
2595
|
+
/** 取消一个服务端任务(尽力而为) */
|
|
2596
|
+
cancel?(taskId: string, action: ActionDef): Promise<void>;
|
|
2597
|
+
}
|
|
2598
|
+
|
|
2599
|
+
/** 一个账号的一套配置值(key 与 provider 声明的 config[].key 对应) */
|
|
2600
|
+
declare interface ProviderAccount {
|
|
2601
|
+
id: string;
|
|
2602
|
+
name?: string;
|
|
2603
|
+
/** 默认账号:不选号时用它(用户口径 2026-11-10:要多账号里的默认号) */
|
|
2604
|
+
default?: boolean;
|
|
2605
|
+
/** secret 只存明文在服务端;下发接口给掩码 */
|
|
2606
|
+
values: Record<string, string | number | boolean>;
|
|
2607
|
+
}
|
|
2608
|
+
|
|
2609
|
+
/** 动作自带的投递函数(返回服务端任务号 / 立即完成 / 失败) */
|
|
2610
|
+
declare type ProviderActionSubmit = (ctx: ActionRunContext, signal?: AbortSignal) => Promise<ProviderSubmitResult>;
|
|
2611
|
+
|
|
2612
|
+
/**
|
|
2613
|
+
* provider 声明的一个配置项(管理页据此动态渲染表单)。
|
|
2614
|
+
*
|
|
2615
|
+
* 值按「账号」存:每个账号一套 values,key = 这里的 key。
|
|
2616
|
+
* secret 类型只在界面显示掩码,明文不下发。
|
|
2617
|
+
*/
|
|
2618
|
+
declare interface ProviderConfigField {
|
|
2619
|
+
key: string;
|
|
2620
|
+
label?: string;
|
|
2621
|
+
description?: string;
|
|
2622
|
+
/** secret = 只写不回读(管理页回显掩码;留空 = 不改) */
|
|
2623
|
+
type: 'string' | 'text' | 'number' | 'boolean' | 'select' | 'secret';
|
|
2624
|
+
default?: string | number | boolean;
|
|
2625
|
+
options?: ParamOption[];
|
|
2626
|
+
placeholder?: string;
|
|
2627
|
+
min?: number;
|
|
2628
|
+
max?: number;
|
|
2629
|
+
step?: number;
|
|
2630
|
+
}
|
|
2631
|
+
|
|
2632
|
+
/** providers-config.json 的完整形状 */
|
|
2633
|
+
declare interface ProviderConfigFile {
|
|
2634
|
+
version: 2;
|
|
2635
|
+
disabledFiles: string[];
|
|
2636
|
+
deletedFiles: string[];
|
|
2637
|
+
files: Record<string, ProviderFileConfig>;
|
|
2638
|
+
/** 平铺的点分隔 key → 值(新结构;缺省 = 还没迁移过来,继续读旧 files) */
|
|
2639
|
+
config?: Record<string, string | number | boolean>;
|
|
2640
|
+
/** platformId → 账号清单(名字、默认号) */
|
|
2641
|
+
platforms?: Record<string, ProviderPlatformMeta>;
|
|
2642
|
+
/** 生成类型 → 默认模型 id(全局,不分平台) */
|
|
2643
|
+
defaults?: ModelDefaults;
|
|
2644
|
+
/**
|
|
2645
|
+
* platformId → 被关掉的模型(动作 id)。
|
|
2646
|
+
*
|
|
2647
|
+
* 用户口径 2026-11-20:一个平台会导出很多模型,用户可能只常用其中几个;
|
|
2648
|
+
* 关掉的模型仍在配置里(随时可以打开),只是不再下发给前端的模型下拉。
|
|
2649
|
+
*/
|
|
2650
|
+
disabledModels?: Record<string, string[]>;
|
|
2651
|
+
}
|
|
2652
|
+
|
|
2653
|
+
/**
|
|
2654
|
+
* 算一个目录的内容签名。
|
|
2655
|
+
*
|
|
2656
|
+
* 只认会被扫的那些文件(`.js`、非 `_`/`.` 开头、普通文件),
|
|
2657
|
+
* 所以"丢进来一个无关文件(如 README)"不会触发重载。
|
|
2658
|
+
*/
|
|
2659
|
+
export declare function providerDirSignature(dir: string): Promise<string>;
|
|
2660
|
+
|
|
2661
|
+
/** 一个 provider 文件的配置(账号清单) */
|
|
2662
|
+
declare interface ProviderFileConfig {
|
|
2663
|
+
accounts: ProviderAccount[];
|
|
2664
|
+
}
|
|
2665
|
+
|
|
2666
|
+
/** 节点类型(动作服务哪几种节点) */
|
|
2667
|
+
export declare type ProviderNodeType = 'image' | 'video' | 'audio' | 'text';
|
|
2668
|
+
|
|
2669
|
+
/**
|
|
2670
|
+
* 新版「点分隔 key」配置:一个平铺对象,key 就是 `providerId.field` 或 `providerId.field.[n]`。
|
|
2671
|
+
*
|
|
2672
|
+
* 为什么要有它:用户口径 2026-11-10 —— 「所有 provider 的配置放在同一级别的 JSON 中,
|
|
2673
|
+
* key 支持点隔开;相同配置只需对应的 key 一样」。于是:
|
|
2674
|
+
* - `token01.baseUrl` = 平台通用(所有账号共用一份)
|
|
2675
|
+
* - `token01.apiKey.[0]` = 第 0 个账号的 apiKey(解析时还原成数组)
|
|
2676
|
+
* - `web2api.baseUrl` = 另一个平台引用同一个 key 名前缀,值天然共用一份
|
|
2677
|
+
*
|
|
2678
|
+
* 账号清单(id / name / 默认)仍放在 `platforms` 里 —— 数组下标本身不携带名字。
|
|
2679
|
+
*/
|
|
2680
|
+
declare interface ProviderPlatformMeta {
|
|
2681
|
+
accounts: Array<{
|
|
2682
|
+
id: string;
|
|
2683
|
+
name?: string;
|
|
2684
|
+
default?: boolean;
|
|
2685
|
+
}>;
|
|
2686
|
+
/** 平台展示信息快照:停用后 import 不到文件了,靠这份继续显示名字/介绍/图标 */
|
|
2687
|
+
title?: string;
|
|
2688
|
+
description?: string;
|
|
2689
|
+
icon?: string;
|
|
2690
|
+
}
|
|
2691
|
+
|
|
2692
|
+
/** 轮询一拍的返回 */
|
|
2693
|
+
export declare interface ProviderPollResult {
|
|
2694
|
+
status: 'running' | 'done' | 'error';
|
|
2695
|
+
progress?: number;
|
|
2696
|
+
message?: string;
|
|
2697
|
+
/**
|
|
2698
|
+
* 加载 UI 上那个**大数字**(不设上限)。
|
|
2699
|
+
*
|
|
2700
|
+
* 用户口径 2026-11-10:进度不一定是百分比 —— 对话要显示已收 token 数(20000 这种),
|
|
2701
|
+
* 百分比会被 100 封顶。provider 想显示什么由它自己决定,前端只照着画。
|
|
2702
|
+
*/
|
|
2703
|
+
value?: number;
|
|
2704
|
+
/** 大数字后面的单位,默认 `%`(token 场景传 `tokens`) */
|
|
2705
|
+
suffix?: string;
|
|
2706
|
+
/**
|
|
2707
|
+
* 整段进度文案(优先于 value + suffix)。
|
|
2708
|
+
* 例如「≈1.2k tokens」这种不适合拆成数字 + 单位的写法。
|
|
2709
|
+
*/
|
|
2710
|
+
progressText?: string;
|
|
2711
|
+
/**
|
|
2712
|
+
* 加载 UI 下方那行**滚动的小尾巴**:正在返回的一小段文字。
|
|
2713
|
+
* 与 partialText 分开:partialText 是作品正文(写进 data.text),
|
|
2714
|
+
* 这个只是给人看的进度提示,不进作品、不进历史。
|
|
2715
|
+
*/
|
|
2716
|
+
tail?: string;
|
|
2717
|
+
/** running 一拍的**部分文本**(文本生成流式预览用;整段覆盖式更新,不是拼接) */
|
|
2718
|
+
/** running 一拍的**部分文本**(文本生成流式预览用;整段覆盖式更新,不是拼接) */
|
|
2719
|
+
partialText?: string;
|
|
2720
|
+
/**
|
|
2721
|
+
* running 一拍的**已产出量**(文本生成用):加载层据此显示「已输出 N 字 / ≈M tokens」。
|
|
2722
|
+
* 只是过程信息,写进节点 runState.stats;不写作品字段、不进历史。
|
|
2723
|
+
*/
|
|
2724
|
+
stats?: {
|
|
2725
|
+
chars?: number;
|
|
2726
|
+
tokens?: number;
|
|
2727
|
+
};
|
|
2728
|
+
/** provider 自己的任务号(后台记着,取消时要用) */
|
|
2729
|
+
taskId?: string;
|
|
2730
|
+
/** status=done 时的产物 */
|
|
2731
|
+
urls?: string[];
|
|
2732
|
+
text?: string;
|
|
2733
|
+
/** status=error 时的原因 */
|
|
2734
|
+
error?: string;
|
|
2735
|
+
/**
|
|
2736
|
+
* 这一拍是不是「等外部条件」的中间态(**不占超时预算**)。
|
|
2737
|
+
*
|
|
2738
|
+
* 场景:web2api 的 `paused` 在等用户在浏览器里过验证码 —— 人处理多久不由程序决定,
|
|
2739
|
+
* 拿它去顶 pollTimeoutMs 会把人还在操作的任务判成超时失败(真出过的 bug)。
|
|
2740
|
+
* provider 标记 true 时,后台这一拍不计入超时。
|
|
2741
|
+
*/
|
|
2742
|
+
waiting?: boolean;
|
|
2743
|
+
}
|
|
2744
|
+
|
|
2745
|
+
export declare class ProviderRegistry {
|
|
2746
|
+
/** providerId → provider */
|
|
2747
|
+
private readonly providers;
|
|
2748
|
+
/** actionId → providerId(路由用) */
|
|
2749
|
+
private readonly actionOwner;
|
|
2750
|
+
private version;
|
|
2751
|
+
/**
|
|
2752
|
+
* 「只改了模型开关」这类**不重新装载**的变化,也要让版本号往前走。
|
|
2753
|
+
*
|
|
2754
|
+
* 为什么:前端拿 ifVersion 问「清单变了吗」,版本没变就直接跳过重拉。
|
|
2755
|
+
* 关掉一个模型并不需要重新 import provider 文件,但下发内容确实变了 ——
|
|
2756
|
+
* 不加这一下,用户拨完开关底栏要等到别的改动才更新(实测就是这么卡住的)。
|
|
2757
|
+
*/
|
|
2758
|
+
bumpVersion(): void;
|
|
2759
|
+
/** 装一批 provider(重复 id 覆盖旧的) */
|
|
2760
|
+
load(providers: Provider[]): void;
|
|
2761
|
+
add(provider: Provider): void;
|
|
2762
|
+
/** 清空重装(provider 目录变了时用:先清再装,避免删掉的 provider 还留着动作) */
|
|
2763
|
+
replaceAll(providers: Provider[]): void;
|
|
2764
|
+
/** 全部动作(按 order 升序;没给 order 的排最后) */
|
|
2765
|
+
listActions(): ActionDef[];
|
|
2766
|
+
/** 按动作 id 找动作(找不到 undefined) */
|
|
2767
|
+
getAction(actionId: string): ActionDef | undefined;
|
|
2768
|
+
/** 某个动作归哪个 provider(任务路由 / 取消 / 续查都用它) */
|
|
2769
|
+
providerOf(actionId: string): Provider | undefined;
|
|
2770
|
+
listProviders(): Provider[];
|
|
2771
|
+
/** 内容版本号:每次装载 +1(前端据此判断要不要重拉菜单,省掉全量比对) */
|
|
2772
|
+
get contentVersion(): number;
|
|
2773
|
+
}
|
|
2774
|
+
|
|
2775
|
+
/** 提交结果:要么给了 taskId(异步,要轮询),要么直接完成,要么直接失败 */
|
|
2776
|
+
export declare type ProviderSubmitResult = {
|
|
2777
|
+
taskId: string;
|
|
2778
|
+
urls?: string[];
|
|
2779
|
+
text?: string;
|
|
2780
|
+
} | {
|
|
2781
|
+
done: true;
|
|
2782
|
+
urls?: string[];
|
|
2783
|
+
text?: string;
|
|
2784
|
+
} | {
|
|
2785
|
+
error: string;
|
|
2786
|
+
};
|
|
2787
|
+
|
|
2788
|
+
export declare interface ProviderWatcher {
|
|
2789
|
+
/** 立刻比对一次(启动时用,也用于测试) */
|
|
2790
|
+
check(): Promise<boolean>;
|
|
2791
|
+
stop(): void;
|
|
2792
|
+
}
|
|
2793
|
+
|
|
2794
|
+
/**
|
|
2795
|
+
* 注册场(设计文档 §2.1 逐字对齐)。
|
|
2796
|
+
*
|
|
2797
|
+
* 写:add / remove / clear / clearByPrefix
|
|
2798
|
+
* 读:list / top / get / has / ids / keys
|
|
2799
|
+
* 组合与订阅:wrap / resolve / subscribe
|
|
2800
|
+
*/
|
|
2801
|
+
declare interface Registry<T> {
|
|
2802
|
+
/**
|
|
2803
|
+
* 放一条。同 id 重复 = 替换该 id 那条(不新增)。
|
|
2804
|
+
* @returns { id, dispose() }:老调用方取 .id(= 今天的 string),新调用方可 .dispose()。
|
|
2805
|
+
*/
|
|
2806
|
+
add(key: string, value: T, opts?: {
|
|
2807
|
+
id?: string;
|
|
2808
|
+
order?: number;
|
|
2809
|
+
}): {
|
|
2810
|
+
id: string;
|
|
2811
|
+
dispose(): void;
|
|
2812
|
+
};
|
|
2813
|
+
/**
|
|
2814
|
+
* 移除某条。**叠层语义**:摘掉该 id 最外(最新)的一层;其它放置方压的层原位不动,
|
|
2815
|
+
* 语义同"撤销最近一次放置"。整摞不要了请用 clear(key)。不存在该 id 返回 false。
|
|
2816
|
+
*/
|
|
2817
|
+
remove(key: string, id: string): boolean;
|
|
2818
|
+
/** 清空某键 */
|
|
2819
|
+
clear(key: string): void;
|
|
2820
|
+
/** 清空某前缀下全部键 */
|
|
2821
|
+
clearByPrefix(prefix: string): void;
|
|
2822
|
+
/** 整摞,按 order 升序 = 从外到里(覆盖者在最前);空键 [] */
|
|
2823
|
+
list(key: string): Entry<T>[];
|
|
2824
|
+
/** 最外面那条 = order 最小者;空键 undefined(= 今天的 first()) */
|
|
2825
|
+
top(key: string): Entry<T> | undefined;
|
|
2826
|
+
/** 按 id 精确取 */
|
|
2827
|
+
get(key: string, id: string): Entry<T> | undefined;
|
|
2828
|
+
/** 某键是否已有条目 */
|
|
2829
|
+
has(key: string): boolean;
|
|
2830
|
+
/** 某键已有条目的 id 列表(诊断 / 热卸用) */
|
|
2831
|
+
ids(key: string): string[];
|
|
2832
|
+
/** 已有条目的键列表(诊断 / 枚举用) */
|
|
2833
|
+
keys(): string[];
|
|
2834
|
+
/**
|
|
2835
|
+
* 包住下一层:fn 收到 inner(下面那层)返回新的 T。**缺省放在最外**(order = 当前最小 - 1)。
|
|
2836
|
+
* wrap 层在 list()/get() 里同样可见——它的 value 就是这个包函数本身(查历史层用)。
|
|
2837
|
+
* @returns 该层的撤销句柄(dispose 即移除这一层,其余层原位不动)
|
|
2838
|
+
*/
|
|
2839
|
+
wrap(key: string, fn: RegistryWrapper<T>, opts?: {
|
|
2840
|
+
id?: string;
|
|
2841
|
+
order?: number;
|
|
2842
|
+
}): Disposable_2;
|
|
2843
|
+
/**
|
|
2844
|
+
* 合成好的那一个:从里到外逐层套完;空键 undefined。
|
|
2845
|
+
*
|
|
2846
|
+
* @param base 最里层的**兜底值**(可选)。用于"场外还有一份默认实现"的场景:
|
|
2847
|
+
* 例如 `node/shell` 场外还有 theme 槽的默认壳,作者 `wrap` 时应当能收到那份默认壳当 inner,
|
|
2848
|
+
* 否则他这个 wrap 拿到的 inner 是 undefined、包不起来(设计文档案例 3/8 要的正是"原值不丢")。
|
|
2849
|
+
* 只给 base、场里没条目时返回 **base 本身**(不是包裹结果)—— 与"'缺省 = 没覆盖'语义一致。
|
|
2850
|
+
*/
|
|
2851
|
+
resolve(key: string, base?: T): T | undefined;
|
|
2852
|
+
/** 变了通知我(渲染侧订阅重绘);返回取消订阅句柄 */
|
|
2853
|
+
subscribe(fn: () => void): Disposable_2;
|
|
2854
|
+
}
|
|
2855
|
+
|
|
2856
|
+
/** 注册场条目:某 kind 场里的一条 */
|
|
2857
|
+
declare interface RegistryEntrySurface {
|
|
2858
|
+
kind: string;
|
|
2859
|
+
/** 场内键(如 'image/out:top') */
|
|
2860
|
+
key: string;
|
|
2861
|
+
id: string;
|
|
2862
|
+
order: number;
|
|
2863
|
+
source: string;
|
|
2864
|
+
/**
|
|
2865
|
+
* 该条目值的**顶层字段名**(best-effort 诊断信息,不是稳定契约)。
|
|
2866
|
+
* 值不是普通对象(函数 / 组件句柄 / 原始值)时为 undefined。
|
|
2867
|
+
*
|
|
2868
|
+
* 为什么给字段名而不是值:作者最常问的是"别人注册那条**有什么可读的**"
|
|
2869
|
+
* (比如 node/region 条目的 needs/props),把值整个摊出去既读不完也会泄漏句柄。
|
|
2870
|
+
*/
|
|
2871
|
+
fields?: string[];
|
|
2872
|
+
}
|
|
2873
|
+
|
|
2874
|
+
/** 注册场汇总:一个 kind + 它下面全部键 */
|
|
2875
|
+
declare interface RegistryKindSurface {
|
|
2876
|
+
kind: string;
|
|
2877
|
+
/** 该 kind 下每个键及其条目数(升序;不用两个平行数组靠下标对齐 —— 审查 B5) */
|
|
2878
|
+
keys: Array<{
|
|
2879
|
+
key: string;
|
|
2880
|
+
count: number;
|
|
2881
|
+
}>;
|
|
2882
|
+
}
|
|
2883
|
+
|
|
2884
|
+
/** 叠加器:wrap 放的"包住下一层"的函数,收到 inner(下面那层)返回新的 T */
|
|
2885
|
+
declare type RegistryWrapper<T> = (inner: T, entry: Entry<T>) => T;
|
|
2886
|
+
|
|
2887
|
+
/**
|
|
2888
|
+
* 解析一个「插件资源」请求:/plugins/<pkg>/<相对路径…>
|
|
2889
|
+
* 逐段校验 + 扩展名白名单;不合法给明确原因(服务端据此回 400)。
|
|
2890
|
+
*/
|
|
2891
|
+
export declare function resolvePluginAsset(urlPath: string): {
|
|
2892
|
+
rel: string;
|
|
2893
|
+
altRel?: string;
|
|
2894
|
+
} | {
|
|
2895
|
+
error: string;
|
|
2896
|
+
};
|
|
2897
|
+
|
|
2898
|
+
/**
|
|
2899
|
+
* 单个插件实际生效的目录。
|
|
2900
|
+
*
|
|
2901
|
+
* 规则(2026-11-12 用户实测修正):
|
|
2902
|
+
* - **自带插件默认用随包那份**。否则数据根里早先留下的旧副本会一直盖住新构建的
|
|
2903
|
+
* `assets/plugins`:`pnpm start` 明明重新编译了,页面却还是旧代码。
|
|
2904
|
+
* - 自带插件确实从 NPM 安装/更新过(`plume.npmInstalled: true`)时,仍用全局那份。
|
|
2905
|
+
* - 非自带插件维持「全局优先」(用户装的就在全局目录)。
|
|
2906
|
+
*
|
|
2907
|
+
* 都没有 → undefined(调用方按「这个插件不存在」处理)。
|
|
2908
|
+
*/
|
|
2909
|
+
export declare function resolvePluginDir(roots: PluginRoots, id: string): Promise<string | undefined>;
|
|
2910
|
+
|
|
2911
|
+
/**
|
|
2912
|
+
* 组装两个根。全局目录**不预先创建**:调用方需要写的时候自己建,
|
|
2913
|
+
* 这样「只读部署」不会因为读插件就在数据根里多出一个空目录。
|
|
2914
|
+
*/
|
|
2915
|
+
export declare function resolvePluginRoots(dataDir: string, packagedDir: string): Promise<PluginRoots>;
|
|
2916
|
+
|
|
2917
|
+
/**
|
|
2918
|
+
* 找 ui 构建产物目录:显式给了就用它(不存在则报错),否则按候选顺序探测。
|
|
2919
|
+
*
|
|
2920
|
+
* 候选顺序:**仓库内的路径优先**,随包 assets 兜底。
|
|
2921
|
+
* 理由是两种场景各取所需:
|
|
2922
|
+
* - 在仓库里跑(改 ui / 跑 e2e):走 apps/web/dist,看到的是刚构建的新产物;
|
|
2923
|
+
* - `npx plume-canvas serve`(空目录):仓库路径都不存在,落到随包 assets/ui,开箱即用。
|
|
2924
|
+
* 反过来(assets 优先)会让仓库里改了 ui 却一直看到 assets 里那份旧副本,很难查。
|
|
2925
|
+
*/
|
|
2926
|
+
export declare function resolveUiDist(explicit?: string, dataDir?: string): Promise<string | undefined>;
|
|
2927
|
+
|
|
2928
|
+
/** 从文件名里取一个安全的扩展名(不认识就空串,不猜) */
|
|
2929
|
+
export declare function safeExt(fileName: string): string;
|
|
2930
|
+
|
|
2931
|
+
export declare interface SavedResource {
|
|
2932
|
+
/** 写进节点 data 的地址(同源 URL:`/api/canvases/<画布id>/resources/<hashName>`) */
|
|
2933
|
+
url: string;
|
|
2934
|
+
/** 磁盘上的文件名 */
|
|
2935
|
+
hashName: string;
|
|
2936
|
+
/** 字节数 */
|
|
2937
|
+
size: number;
|
|
2938
|
+
}
|
|
2939
|
+
|
|
2940
|
+
/**
|
|
2941
|
+
* 服务注册表类型:插件可 declare module 扩展 `interface Services { ... }`
|
|
2942
|
+
* 以便 ctx.get<Services['foo']>('foo') 拿到类型。
|
|
2943
|
+
*/
|
|
2944
|
+
declare interface Services {
|
|
2945
|
+
}
|
|
2946
|
+
|
|
2947
|
+
/** 服务条目:一个按名可取的能手 */
|
|
2948
|
+
declare interface ServiceSurface {
|
|
2949
|
+
name: string;
|
|
2950
|
+
/** 注册方:插件名 / '<host>' / '<anonymous>' / '<builtin>'(内核或能力层内置) */
|
|
2951
|
+
source: string;
|
|
2952
|
+
/**
|
|
2953
|
+
* 该服务暴露的方法名(**best-effort 诊断信息**,不是稳定契约)。
|
|
2954
|
+
* descriptor 反射取:只读 value 为函数的自有属性 + 原型链,**不执行 getter**。
|
|
2955
|
+
* 压缩/混淆后可能失真;Vue 代理实例可能只暴露自有属性。缺省 = 拿不到。
|
|
2956
|
+
*/
|
|
2957
|
+
methods?: string[];
|
|
2958
|
+
}
|
|
2959
|
+
|
|
2960
|
+
/** 小数据落盘文件的绝对路径:{dir}/settings.json */
|
|
2961
|
+
export declare function settingsFilePath(dir: string): string;
|
|
2962
|
+
|
|
2963
|
+
/**
|
|
2964
|
+
* 插件私有状态(ctx.state):内核只存值、不做响应式。
|
|
2965
|
+
*
|
|
2966
|
+
* 为什么不占服务名:它是插件自己的数据,不是"别人按名取的能力"(设计文档规则 7)。
|
|
2967
|
+
* 响应式由渲染层决定(要响应式的消费方把这个对象塞进 reactive/ref 里)。
|
|
2968
|
+
*/
|
|
2969
|
+
declare interface State<T> {
|
|
2970
|
+
value: T;
|
|
2971
|
+
}
|
|
2972
|
+
|
|
2973
|
+
/** 一次 surface() 的完整快照 */
|
|
2974
|
+
declare interface SurfaceReport {
|
|
2975
|
+
state: ContextState;
|
|
2976
|
+
services: ServiceSurface[];
|
|
2977
|
+
registries: RegistryKindSurface[];
|
|
2978
|
+
registryEntries: RegistryEntrySurface[];
|
|
2979
|
+
commands: CommandSurface[];
|
|
2980
|
+
tools: ToolSurface[];
|
|
2981
|
+
modelTools: ModelToolSurface[];
|
|
2982
|
+
/**
|
|
2983
|
+
* 已登记的事件名(`registerEventName` 的登记表)。
|
|
2984
|
+
*
|
|
2985
|
+
* 为什么要这条轴:作者想问"这台画布上都有哪些事件可监听",此前只能翻源码;
|
|
2986
|
+
* 而 dev 下"未登记的事件名"会 warn,登记表因此正好是"有哪些事件"的权威清单。
|
|
2987
|
+
*/
|
|
2988
|
+
events: string[];
|
|
2989
|
+
}
|
|
2990
|
+
|
|
2991
|
+
/** 一次任务要用的外部能力(注入,便于单测给假货) */
|
|
2992
|
+
export declare interface TaskDeps {
|
|
2993
|
+
doc: CanvasDocument;
|
|
2994
|
+
/**
|
|
2995
|
+
* 按画布 id 取该画布的文档(多画布:**进度/终态要写进任务所属的那张画布**)。
|
|
2996
|
+
*
|
|
2997
|
+
* 不传时回落 `doc`(默认画布)。曾经的写法固定用 `doc`(默认画布的文档),于是
|
|
2998
|
+
* **非默认画布**上的任务,进度全写进了 default(那里根本没有那个节点 id)→ 静默失败,
|
|
2999
|
+
* 表现就是"进度一直卡在 0%"(用户实测)。
|
|
3000
|
+
*/
|
|
3001
|
+
docForCanvas?: (canvasId: string) => CanvasDocument;
|
|
3002
|
+
registry: ProviderRegistry;
|
|
3003
|
+
history: HistoryStore;
|
|
3004
|
+
/**
|
|
3005
|
+
* 把节点里的资源地址解析成 **provider 能拿到的素材**(多画布 + 跨服务器的关键)。
|
|
3006
|
+
*
|
|
3007
|
+
* 返回 **data URL**(内嵌字节),不是地址:cloud-server 与 web2api 是**两个独立服务**
|
|
3008
|
+
* (可能不在同一台机器),给 web2api 一个 cloud-server 的地址它可能根本下载不到。
|
|
3009
|
+
* 而 web2api 的 `utils/reference-images.ts` 明确支持 data URL(**它会自己落盘成本地文件**),
|
|
3010
|
+
* 所以把字节直接交给它最稳,不依赖任何网络可达性。
|
|
3011
|
+
*/
|
|
3012
|
+
resolveResourceUrl(canvasId: string, ref: string): Promise<string>;
|
|
3013
|
+
/** 测试可注入假时钟 / 睡眠 */
|
|
3014
|
+
now?: () => number;
|
|
3015
|
+
sleep?: (ms: number) => Promise<void>;
|
|
3016
|
+
/** 任务成功产出资源时的回调(server 用来把产物登记进资产目录;测试可省) */
|
|
3017
|
+
onArtifact?: (canvasId: string, urls: string[]) => void;
|
|
3018
|
+
/**
|
|
3019
|
+
* 取产物字节(落进画布资源目录用)。默认真 fetch;测试注入假货,免得去连真地址。
|
|
3020
|
+
*/
|
|
3021
|
+
fetchArtifact?: (url: string) => Promise<Uint8Array>;
|
|
3022
|
+
/**
|
|
3023
|
+
* 查某个节点**当前是否有在跑的任务**(用于挡住重复下单)。
|
|
3024
|
+
*
|
|
3025
|
+
* 返回 undefined 表示没有。宿主(server)可以用它做跨实例的判定;
|
|
3026
|
+
* 省略时 TaskManager 退回查自己内存里的任务表(单实例足够)。
|
|
3027
|
+
*/
|
|
3028
|
+
activeJob?: (canvasId: string, nodeId: string) => {
|
|
3029
|
+
id: string;
|
|
3030
|
+
} | undefined;
|
|
3031
|
+
onError?: (message: string, err?: unknown) => void;
|
|
3032
|
+
}
|
|
3033
|
+
|
|
3034
|
+
export declare class TaskManager {
|
|
3035
|
+
private readonly deps;
|
|
3036
|
+
private readonly jobs;
|
|
3037
|
+
/** 每个 job 一个取消句柄 */
|
|
3038
|
+
private readonly cancels;
|
|
3039
|
+
/** 已经不在跑的 job(终态);后台循环据此提前收工,不留悬挂的循环 */
|
|
3040
|
+
private readonly settled;
|
|
3041
|
+
/** 在跑的后台循环(dispose 要等它们退干净,否则关停后还有人在写盘) */
|
|
3042
|
+
private readonly running;
|
|
3043
|
+
constructor(deps: TaskDeps);
|
|
3044
|
+
/**
|
|
3045
|
+
* 停掉所有在跑的任务(服务关停 / 测试收尾)。
|
|
3046
|
+
*
|
|
3047
|
+
* **要 await**:abort 只是让循环"下一次检查时退出",它可能正卡在一次写盘中间;
|
|
3048
|
+
* 不等的话,关停之后还会有一次迟到的写入(测试里实测过:清理临时目录时报非空)。
|
|
3049
|
+
*/
|
|
3050
|
+
dispose(): Promise<void>;
|
|
3051
|
+
/**
|
|
3052
|
+
* 建一个任务。**立即返回**(后台开始跑)。
|
|
3053
|
+
*
|
|
3054
|
+
* 提交是同步等 provider 的 `submit`(拿到 taskId 或立即完成),
|
|
3055
|
+
* 之后的推进全在后台循环里 —— 所以前端点完"发送"马上拿得到 jobId。
|
|
3056
|
+
*/
|
|
3057
|
+
createJob(input: JobInput): Promise<Job | {
|
|
3058
|
+
error: string;
|
|
3059
|
+
}>;
|
|
3060
|
+
/** 查任务(前端轮询 / 续查用) */
|
|
3061
|
+
getJob(jobId: string): Job | undefined;
|
|
3062
|
+
/** 按节点反查(诊断用) */
|
|
3063
|
+
findJobByNode(canvasId: string, nodeId: string): Job | undefined;
|
|
3064
|
+
/** 列出全部任务(诊断用) */
|
|
3065
|
+
listJobs(): Job[];
|
|
3066
|
+
/**
|
|
3067
|
+
* 取消一个任务。
|
|
3068
|
+
*
|
|
3069
|
+
* 先 abort 本地等待(立刻收敛),再让 provider 去服务端真取消 ——
|
|
3070
|
+
* 只 abort 的话服务端那个任务还在跑、还在花钱。
|
|
3071
|
+
*/
|
|
3072
|
+
cancel(jobId: string): Promise<boolean>;
|
|
3073
|
+
private now;
|
|
3074
|
+
private sleep;
|
|
3075
|
+
/** 把节点里的资源地址换成 provider 能取的真实字节(data URL) */
|
|
3076
|
+
private resolveInput;
|
|
3077
|
+
/**
|
|
3078
|
+
* 产物该写进节点的哪个字段 —— 按节点类型决定(与前端 applier 同一套映射)。
|
|
3079
|
+
* 认不出类型时退回 imageUrl(图片是最常见的产物)。
|
|
3080
|
+
*
|
|
3081
|
+
* `image-compare` 必须写 `leftImageUrl`:它只读左右两槽,写 imageUrl 等于没写
|
|
3082
|
+
*(任务「成功」但对比窗口还是空的)。与 canvas-data 的 mediaUrlFieldsOf 同一张表。
|
|
3083
|
+
*/
|
|
3084
|
+
private mediaFieldFor;
|
|
3085
|
+
/**
|
|
3086
|
+
* 按产物后缀给出该写进节点的那对「尺寸字段」名。
|
|
3087
|
+
* 图片写 `imageWidth/imageHeight`、视频写 `videoWidth/videoHeight`(前端就是读这两对来定卡片比例)。
|
|
3088
|
+
*/
|
|
3089
|
+
private sizeFieldsFor;
|
|
3090
|
+
/** 从字节里量尺寸(按后缀选图片还是视频解析器;认不出返回 null) */
|
|
3091
|
+
private measureBytes;
|
|
3092
|
+
/**
|
|
3093
|
+
* 产物要落到**这个节点自己**的哪种地址字段。
|
|
3094
|
+
*
|
|
3095
|
+
* 为什么读节点而不是只看动作声明:同一个动作可以被不同节点类型接住 —— 比如可视化节点
|
|
3096
|
+
* (type=ui)也能接生成任务,它的产物地址统一存在 `uiOutputUrl`。只按动作的 nodeTypes 猜,
|
|
3097
|
+
* 会把地址写进一个该节点根本不读的字段(表现就是「任务成功了,卡片还是空的」)。
|
|
3098
|
+
* 读不到节点(已被删除 / 读盘失败)时退回动作声明。
|
|
3099
|
+
*/
|
|
3100
|
+
private targetNodeType;
|
|
3101
|
+
/**
|
|
3102
|
+
* UI 节点这次产出的内容类型(image / video / audio / text)。
|
|
3103
|
+
*
|
|
3104
|
+
* 与前端 plugin-node-ui 的 outputTypeForName 同一套口径:按产物扩展名认,
|
|
3105
|
+
* 认不出再看实测到的媒体类型(有些平台给 .bin,扩展名不可靠)。
|
|
3106
|
+
*/
|
|
3107
|
+
private uiOutputTypeOf;
|
|
3108
|
+
/**
|
|
3109
|
+
* 把**一份**产物的字节收进本画布资源目录,返回要写进节点的那份数据。
|
|
3110
|
+
*
|
|
3111
|
+
* 关键:不能只把 provider 的地址(`http://localhost:8033/...`)抄进节点 —— 那是另一个服务的地址,
|
|
3112
|
+
* 换机器 / 换端口就取不到,画布上只会显示「图片已失效」。必须先 `saveResource` 把字节落到
|
|
3113
|
+
* `<画布>/resources/`(按内容哈希,重复不重复存),再把 `saveResource` 返回的同源地址写进节点。
|
|
3114
|
+
* 这个地址形如 `/api/canvases/<画布>/resources/<hash>.<ext>`,文件**确实存在**,图片节点直接就能加载。
|
|
3115
|
+
*
|
|
3116
|
+
* 单份失败(地址取不到 / 存盘失败)只返回 undefined,让调用方跳过这一份 —— 不能因为第 3 张挂了,
|
|
3117
|
+
* 把前两张和整次任务一起判失败。
|
|
3118
|
+
*/
|
|
3119
|
+
private localizeArtifact;
|
|
3120
|
+
/** 一份已本地化的产物 → 写进节点的 data 字段(地址永远是 resourceId 的投影) */
|
|
3121
|
+
private fieldsForArtifact;
|
|
3122
|
+
/**
|
|
3123
|
+
* 多产物落地:第 1 张写回任务节点,其余每张**各建一个同类型节点**。
|
|
3124
|
+
*
|
|
3125
|
+
* 用户口径(2026-11-20):豆包这类网页自动化生图一次会回多张,现在只显示第一张。
|
|
3126
|
+
* 多出来的要「配置相同的输入节点,和底部状态栏的参数」:
|
|
3127
|
+
* - 位置:原节点右侧,一行 3 个,排满换行;
|
|
3128
|
+
* - 输入:复制原节点的入边(参考图 / 参考文字接上);
|
|
3129
|
+
* - 底栏:复制 `barValues` / `barPrompt` / `barPromptDoc`,点开就是同一个模型同一套参数;
|
|
3130
|
+
* - 状态:直接标 done(**不带 taskId**),前端对账不会把它当成原任务再写一遍;
|
|
3131
|
+
* - 名称:不复制 label,交给数据层自动起名「图片 N」,避免重名。
|
|
3132
|
+
*
|
|
3133
|
+
* 为什么不限数量:生图要花钱,正常不会回一大把;真出现了就都落下来,比悄悄丢掉强。
|
|
3134
|
+
* 同一张图(内容哈希相同)重复返回只建一个节点。
|
|
3135
|
+
*/
|
|
3136
|
+
private spawnExtraArtifactNodes;
|
|
3137
|
+
/** 写 runState(进度帧);extra 里的字段与 runState 同帧写入(文本生成写 data.text 用) */
|
|
3138
|
+
private writeRunState;
|
|
3139
|
+
/** 后台推进:提交 → 轮询 → 终态 → 归档 */
|
|
3140
|
+
private run;
|
|
3141
|
+
/** 终态:写节点 + 归档历史 */
|
|
3142
|
+
private finish;
|
|
3143
|
+
/** 从动作声明推断产物类型(前端按它分组 / 计数) */
|
|
3144
|
+
private kindOf;
|
|
3145
|
+
private toHistoryEntry;
|
|
3146
|
+
}
|
|
3147
|
+
|
|
3148
|
+
export declare const TOOL_LIST: McpTool[];
|
|
3149
|
+
|
|
3150
|
+
/** 一次调用的运行上下文(§7.2 缺口③):关联 + 可取消 */
|
|
3151
|
+
declare interface ToolCallContext {
|
|
3152
|
+
/** 一次调用的关联 id(调用方给;不给由内核生成)。贯穿 execute 与 tools/result */
|
|
3153
|
+
callId: string;
|
|
3154
|
+
/** 取消信号(调用方持有 AbortController)。工具应把它透传给 fetch 等可取消的下游 */
|
|
3155
|
+
signal: AbortSignal;
|
|
3156
|
+
}
|
|
3157
|
+
|
|
3158
|
+
/** 一次调用的终态结果(`content` 恒为数组,调用方无需判空) */
|
|
3159
|
+
declare interface ToolCallResult {
|
|
3160
|
+
ok: boolean;
|
|
3161
|
+
/** 工具名 */
|
|
3162
|
+
name: string;
|
|
3163
|
+
/** 本次调用的关联 id(与 tools/result 里的一致) */
|
|
3164
|
+
callId: string;
|
|
3165
|
+
/** ok=true 时的规范产物(`output.schema` 已校验) */
|
|
3166
|
+
value?: JsonValue;
|
|
3167
|
+
/** 可持久化的结果内容(`output.render` 的产出) */
|
|
3168
|
+
content: ToolContentBlock[];
|
|
3169
|
+
error?: string;
|
|
3170
|
+
}
|
|
3171
|
+
|
|
3172
|
+
/**
|
|
3173
|
+
* 结果内容块(Native renderer 的产出,**可持久化**)。
|
|
3174
|
+
*
|
|
3175
|
+
* 只有两种块:文本与 JSON。要更丰富的展示(卡片/缩略图)是消费方拿它再渲染的事,
|
|
3176
|
+
* 内核不认 UI 概念——这样存下来的结果在任何宿主里都读得回来。
|
|
3177
|
+
*/
|
|
3178
|
+
declare type ToolContentBlock = {
|
|
3179
|
+
type: 'text';
|
|
3180
|
+
text: string;
|
|
3181
|
+
} | {
|
|
3182
|
+
type: 'json';
|
|
3183
|
+
value: JsonValue;
|
|
3184
|
+
};
|
|
3185
|
+
|
|
3186
|
+
/** 一个工具的完整声明(注册进注册表的形状) */
|
|
3187
|
+
declare interface ToolDef {
|
|
3188
|
+
/** 唯一名(如 'image.generate:apimart-gpt-image-2');重复注册抛错 */
|
|
3189
|
+
name: string;
|
|
3190
|
+
/** UI 显示名(模型下拉里显示的就是它) */
|
|
3191
|
+
title?: string;
|
|
3192
|
+
/** 一句话说明(可用于 tooltip/说明) */
|
|
3193
|
+
description?: string;
|
|
3194
|
+
/** 分组(UI 可据此归类;如 '图片生成' / '文本生成') */
|
|
3195
|
+
group?: string;
|
|
3196
|
+
/** 这个工具产出什么(节点据此挑"能给我出图的工具") */
|
|
3197
|
+
produces?: ToolResourceKind;
|
|
3198
|
+
/** 这个工具接受哪些输入资源(节点据此判断"当前连的素材能不能喂给它";缺省=不挑) */
|
|
3199
|
+
accepts?: ToolResourceKind[];
|
|
3200
|
+
/** 声明式参数(UI 自动渲染下拉/开关) */
|
|
3201
|
+
params?: ToolParamDef[];
|
|
3202
|
+
/** 预设提示词模板(面板渲染"模板"下拉;加模板不用改面板) */
|
|
3203
|
+
templates?: ToolTemplate[];
|
|
3204
|
+
/** 执行体 */
|
|
3205
|
+
run(input: ToolInput, ctx: ToolRunContext): ToolOutcome | Promise<ToolOutcome>;
|
|
3206
|
+
}
|
|
3207
|
+
|
|
3208
|
+
/** tools/result 里给观察者的"这次调用是谁"(只读视图,不含可变状态) */
|
|
3209
|
+
declare interface ToolExecView {
|
|
3210
|
+
/** 场里的键 = 工具名 */
|
|
3211
|
+
name: string;
|
|
3212
|
+
callId: string;
|
|
3213
|
+
/** 归一化后的入参(已校验) */
|
|
3214
|
+
arguments: Record<string, unknown>;
|
|
3215
|
+
}
|
|
3216
|
+
|
|
3217
|
+
/** 列表筛选条件(键都可选;给的键之间是"与"关系) */
|
|
3218
|
+
declare interface ToolFilter {
|
|
3219
|
+
group?: string;
|
|
3220
|
+
produces?: ToolResourceKind;
|
|
3221
|
+
/** 只要**能吃下**该输入类型的工具 */
|
|
3222
|
+
accepts?: ToolResourceKind;
|
|
3223
|
+
}
|
|
3224
|
+
|
|
3225
|
+
/** 一次工具调用的输入 */
|
|
3226
|
+
declare interface ToolInput {
|
|
3227
|
+
/** 用户在输入框里写的内容(标签与文字分段给出,顺序就是输入框里的顺序) */
|
|
3228
|
+
prompts?: ToolPromptSegment[];
|
|
3229
|
+
/** 画布上下文资源(上游连进来的素材) */
|
|
3230
|
+
resources?: ToolResource[];
|
|
3231
|
+
/** 用户在 UI 上选的参数值(键 = ToolParamDef.key) */
|
|
3232
|
+
params?: Record<string, unknown>;
|
|
3233
|
+
[k: string]: unknown;
|
|
3234
|
+
}
|
|
3235
|
+
|
|
3236
|
+
/** invoke 的可选项 */
|
|
3237
|
+
declare interface ToolInvokeOptions {
|
|
3238
|
+
/** 运行上下文(节点 id / 画布 id 等) */
|
|
3239
|
+
ctx?: ToolRunContext;
|
|
3240
|
+
/** 每个 running 进度回调一次(UI 刷新进度条) */
|
|
3241
|
+
onProgress?: (p: ToolProgress) => void;
|
|
3242
|
+
/** 轮询间隔(ms,默认 650:与 v1 图片生成一致,进度看起来是连续的) */
|
|
3243
|
+
interval?: number;
|
|
3244
|
+
/** 超时(ms,默认 5 分钟;超时按失败返回,不留悬挂任务) */
|
|
3245
|
+
timeoutMs?: number;
|
|
3246
|
+
}
|
|
3247
|
+
|
|
3248
|
+
/**
|
|
3249
|
+
* 工具 run 的返回契约:
|
|
3250
|
+
* - 直接返回(或解析到)ToolResult → 同步完成;
|
|
3251
|
+
* - 返回 ToolPollFn → 异步任务,由 ToolRegistry.invoke 负责轮询到 done(并转发进度)。
|
|
3252
|
+
*
|
|
3253
|
+
* 这两种形态足以覆盖"同步 HTTP 一次返回"和"提交任务后轮询"两类第三方 API。
|
|
3254
|
+
*/
|
|
3255
|
+
declare type ToolOutcome = ToolResult | ToolPollFn;
|
|
3256
|
+
|
|
3257
|
+
/**
|
|
3258
|
+
* 声明式参数:UI 据此**自动**渲染控件(比例下拉、分辨率下拉、模板下拉…)。
|
|
3259
|
+
* 工具自己声明有什么参数,节点 UI 不需要认识"比例"这个业务概念——
|
|
3260
|
+
* 加一个新参数(比如"风格")不用改任何节点代码。
|
|
3261
|
+
*/
|
|
3262
|
+
declare interface ToolParamDef {
|
|
3263
|
+
key: string;
|
|
3264
|
+
/** 参数名(面板上显示的标签) */
|
|
3265
|
+
label?: string;
|
|
3266
|
+
/** 一句话说明(面板 tooltip / 辅助文字) */
|
|
3267
|
+
description?: string;
|
|
3268
|
+
/**
|
|
3269
|
+
* 语义类型(见 {@link ToolParamKind}):UI 层据此挑**预设组件**渲染本参数。
|
|
3270
|
+
* 缺省或不认识 → 回落下面的 type 内置控件。
|
|
3271
|
+
*/
|
|
3272
|
+
kind?: ToolParamKind | (string & {});
|
|
3273
|
+
/**
|
|
3274
|
+
* 基础控件类型(不给 component / kind 时按它渲染):
|
|
3275
|
+
* - `select` 下拉(配 options)
|
|
3276
|
+
* - `grid` 按钮网格,点一下就切换(配 options + columns)
|
|
3277
|
+
* - `string` 单行文本(配 placeholder)
|
|
3278
|
+
* - `number` 数字(配 min/max/step 用滑块+数字框;配 options 则变成按钮网格)
|
|
3279
|
+
* - `boolean` 开关
|
|
3280
|
+
*/
|
|
3281
|
+
type?: 'select' | 'grid' | 'string' | 'number' | 'boolean';
|
|
3282
|
+
/** 数值单位的显示后缀(如 '秒' / 'Hz'),显示在滑块标题右侧 */
|
|
3283
|
+
unit?: string;
|
|
3284
|
+
/** `select` / `grid` / `number` 的候选值(number + options = 按钮网格) */
|
|
3285
|
+
options?: ToolParamOption[];
|
|
3286
|
+
default?: string | number | boolean;
|
|
3287
|
+
/** `number` 的取值范围与步长(有范围才有滑块) */
|
|
3288
|
+
min?: number;
|
|
3289
|
+
max?: number;
|
|
3290
|
+
step?: number;
|
|
3291
|
+
/**
|
|
3292
|
+
* 每行几格:只对按钮类控件生效(`type: 'grid'`、`type: 'number'` + options、`kind: 'ratio'`)。
|
|
3293
|
+
* 省略时由 UI 按选项数自动排(≤6 个排一行)。
|
|
3294
|
+
*/
|
|
3295
|
+
columns?: number;
|
|
3296
|
+
/** type='string' 时的输入提示 */
|
|
3297
|
+
placeholder?: string;
|
|
3298
|
+
/**
|
|
3299
|
+
* **自定义渲染组件**(opaque 句柄,与节点 content 段同一语义:内核不解析、不 import Vue)。
|
|
3300
|
+
*
|
|
3301
|
+
* 给了它就用它渲染本参数,忽略 type —— 这是"内置控件不够用"时的逃生口:
|
|
3302
|
+
* 例如想让"思考程度"显示成一排可点的档位卡片、想让"风格"显示成带缩略图的画廊,
|
|
3303
|
+
* 工具作者自带一个组件即可,**面板与本内核都不用改**。
|
|
3304
|
+
*
|
|
3305
|
+
* 组件收到的约定 props(与内置控件一致,便于替换):
|
|
3306
|
+
* param: ToolParamDef(本定义,可读 label/options/…)
|
|
3307
|
+
* modelValue: 当前值
|
|
3308
|
+
* disabled?: boolean(生成中时禁用)
|
|
3309
|
+
* emits: update:modelValue(值变化时抛出,面板据此写回 params)
|
|
3310
|
+
*/
|
|
3311
|
+
component?: unknown;
|
|
3312
|
+
/** 透传给 component 的附加静态 props(自定义组件需要额外入参时用) */
|
|
3313
|
+
componentProps?: Record<string, unknown>;
|
|
3314
|
+
/**
|
|
3315
|
+
* 布局权重:同一行里占几份(默认 1)。面板按此把参数排成一行/多行,
|
|
3316
|
+
* 例如把"思考程度"这种短参数设成 1、"提示词增强"这种长参数设成 2。
|
|
3317
|
+
*/
|
|
3318
|
+
span?: number;
|
|
3319
|
+
}
|
|
3320
|
+
|
|
3321
|
+
/**
|
|
3322
|
+
* 参数的**语义类型**(比 type 更具体的一层:type 说"用哪种控件",
|
|
3323
|
+
* kind 说"这个参数是哪一类东西")。
|
|
3324
|
+
*
|
|
3325
|
+
* 为什么需要它:同一个"下拉"在参考实现里长得并不一样 —— 比例要画按真实宽高比缩放的
|
|
3326
|
+
* 小矩形,画质/清晰度/数量是一排等宽按钮,时长是滑块或两档按钮。光靠 type:select
|
|
3327
|
+
* 表达不出这层差异,只能让每个工具作者自己塞组件(那样每加一个模型都要写 UI)。
|
|
3328
|
+
*
|
|
3329
|
+
* 所以 kind 只留给**基础控件表达不了的专属 UI**:目前只有 `ratio`
|
|
3330
|
+
* (按真实宽高比画小矩形的网格)。其余需求都用 `type` 表达:
|
|
3331
|
+
* 下拉 / 文本 / 数字(含 min/max/step/unit)/ 开关 / 按钮网格(含 columns)。
|
|
3332
|
+
*
|
|
3333
|
+
* 词表是**开放**的:写别的名字不会炸,回落 `type` 的控件。
|
|
3334
|
+
*/
|
|
3335
|
+
/**
|
|
3336
|
+
* 语义类型:**只给「基础控件表达不了的专属 UI」用**。
|
|
3337
|
+
*
|
|
3338
|
+
* 现在只剩 `ratio` 一个 —— 它要按真实宽高比画小矩形,别的控件替代不了。
|
|
3339
|
+
* 其余都是基础控件能表达的(下拉 / 数字 / 开关 / 文本 / 按钮网格),
|
|
3340
|
+
* 不该再各占一个 kind:那会让同一个 UI 有两套入口,文档也得跟着列两遍。
|
|
3341
|
+
*
|
|
3342
|
+
* 想加「特殊 UI」时在这里加一个值,并在主题包 `paramKind.ts` 里给它一件组件。
|
|
3343
|
+
*/
|
|
3344
|
+
declare type ToolParamKind = 'ratio';
|
|
3345
|
+
|
|
3346
|
+
/** 工具参数下拉里的一项 */
|
|
3347
|
+
declare interface ToolParamOption {
|
|
3348
|
+
label: string;
|
|
3349
|
+
value: string;
|
|
3350
|
+
}
|
|
3351
|
+
|
|
3352
|
+
/** 自省报告里的参数形状 = ToolParamDef 去掉不透明句柄后的可读投影 */
|
|
3353
|
+
declare type ToolParamSurface = Omit<ToolParamDef, 'component' | 'componentProps'> & {
|
|
3354
|
+
/** 该参数是否自带自定义渲染组件(句柄本身 opaque,不外泄) */
|
|
3355
|
+
hasCustomComponent?: boolean;
|
|
3356
|
+
};
|
|
3357
|
+
|
|
3358
|
+
/** 异步工具返回的轮询函数:返回 'running' 则框架稍后再调,'done' 即终止 */
|
|
3359
|
+
declare type ToolPollFn = () => ToolPollState | Promise<ToolPollState>;
|
|
3360
|
+
|
|
3361
|
+
/** 轮询函数每次返回的状态 */
|
|
3362
|
+
declare type ToolPollState = ({
|
|
3363
|
+
status: 'running';
|
|
3364
|
+
} & ToolProgress) | {
|
|
3365
|
+
status: 'done';
|
|
3366
|
+
result: ToolResult;
|
|
3367
|
+
};
|
|
3368
|
+
|
|
3369
|
+
/** 运行中进度(UI 只依赖它渲染进度条与阶段文案) */
|
|
3370
|
+
declare interface ToolProgress {
|
|
3371
|
+
/** 0–100;外部只给阶段时可省略,UI 回落为进行中动画 */
|
|
3372
|
+
progress?: number;
|
|
3373
|
+
message?: string;
|
|
3374
|
+
taskId?: string;
|
|
3375
|
+
}
|
|
3376
|
+
|
|
3377
|
+
/**
|
|
3378
|
+
* 提示词里的一段:标签(引用某个资源)或普通文字。
|
|
3379
|
+
*
|
|
3380
|
+
* 为什么把标签单独拆出来(用户 2026-11-09):标签本身没有状态,资源才有;
|
|
3381
|
+
* 标签只要记资源 id,名称与地址都去 resources 里查,两处才能一一对上。
|
|
3382
|
+
*/
|
|
3383
|
+
declare interface ToolPromptSegment {
|
|
3384
|
+
type: 'tag' | 'prompt';
|
|
3385
|
+
/** tag = 资源 id;prompt = 原文 */
|
|
3386
|
+
value: string;
|
|
3387
|
+
}
|
|
3388
|
+
|
|
3389
|
+
/** 一次调用随行的画布上下文资源(上游连进来的图/文) */
|
|
3390
|
+
declare interface ToolResource {
|
|
3391
|
+
/** 上游节点 id(稳定身份) */
|
|
3392
|
+
id: string;
|
|
3393
|
+
kind: ToolResourceKind;
|
|
3394
|
+
/** 供 @ 引用与 UI 显示的名字 */
|
|
3395
|
+
name?: string;
|
|
3396
|
+
/** 图片来源(图片/视频类) */
|
|
3397
|
+
url?: string;
|
|
3398
|
+
/** 文本内容(文本类) */
|
|
3399
|
+
value?: string;
|
|
3400
|
+
}
|
|
3401
|
+
|
|
3402
|
+
/** 工具可以吃/产的资源类型(与节点连接的 acceptsTypes 同词表) */
|
|
3403
|
+
declare type ToolResourceKind = 'image' | 'text' | 'video' | 'audio';
|
|
3404
|
+
|
|
3405
|
+
/** 一次工具调用的终态结果 */
|
|
3406
|
+
declare interface ToolResult {
|
|
3407
|
+
ok: boolean;
|
|
3408
|
+
/** ok=false 时的原因(直接展示给用户) */
|
|
3409
|
+
error?: string;
|
|
3410
|
+
/** 产物地址(图片等) */
|
|
3411
|
+
urls?: string[];
|
|
3412
|
+
/** 文本产物(文生文类工具用) */
|
|
3413
|
+
text?: string;
|
|
3414
|
+
/** 外部任务 id(可查询/取消) */
|
|
3415
|
+
taskId?: string;
|
|
3416
|
+
}
|
|
3417
|
+
|
|
3418
|
+
/**
|
|
3419
|
+
* 调用时注入的运行上下文(**调用方自定义**,工具实现按需读取,不需要就忽略)。
|
|
3420
|
+
*
|
|
3421
|
+
* 内核只透传不解释:调用方 invoke 时传什么,工具 run 就收到什么。
|
|
3422
|
+
* 画布场景会放 nodeId/canvasId(把结果写回节点、后台按画布归属),别的宿主放自己的键。
|
|
3423
|
+
*/
|
|
3424
|
+
declare interface ToolRunContext {
|
|
3425
|
+
/** 发起调用的节点 id(画布场景约定键;别的宿主可以是别的含义或省略) */
|
|
3426
|
+
nodeId?: string;
|
|
3427
|
+
/** 画布 id(画布场景约定键;同上) */
|
|
3428
|
+
canvasId?: string;
|
|
3429
|
+
[k: string]: unknown;
|
|
3430
|
+
}
|
|
3431
|
+
|
|
3432
|
+
/** 注册进 `ctx.registryOf('tool')` 的完整形状(字段名与教程对齐:description/parameters/output/execute) */
|
|
3433
|
+
declare interface ToolSpec {
|
|
3434
|
+
name?: string;
|
|
3435
|
+
description: string;
|
|
3436
|
+
parameters: ToolValueSchema;
|
|
3437
|
+
output: {
|
|
3438
|
+
schema: ToolValueSchema;
|
|
3439
|
+
render(args: Record<string, unknown>, value: JsonValue): ToolContentBlock[];
|
|
3440
|
+
};
|
|
3441
|
+
execute(args: Record<string, unknown>, ctx: ToolCallContext): unknown | Promise<unknown>;
|
|
3442
|
+
}
|
|
3443
|
+
|
|
3444
|
+
/** 生成工具(ctx.tools)条目 */
|
|
3445
|
+
declare interface ToolSurface {
|
|
3446
|
+
name: string;
|
|
3447
|
+
title?: string;
|
|
3448
|
+
description?: string;
|
|
3449
|
+
group?: string;
|
|
3450
|
+
produces?: string;
|
|
3451
|
+
accepts?: string[];
|
|
3452
|
+
/** 声明式参数(UI 自动渲染下拉/开关用);形状直接复用 ToolParamDef,不手抄字段 */
|
|
3453
|
+
params?: ToolParamSurface[];
|
|
3454
|
+
/** 预设提示词模板(含正文与适用范围) */
|
|
3455
|
+
templates?: Array<{
|
|
3456
|
+
id: string;
|
|
3457
|
+
name: string;
|
|
3458
|
+
prompt: string;
|
|
3459
|
+
description?: string;
|
|
3460
|
+
forTools?: string[];
|
|
3461
|
+
}>;
|
|
3462
|
+
}
|
|
3463
|
+
|
|
3464
|
+
/**
|
|
3465
|
+
* 预设提示词模板(工具作者提供,面板据此渲染"模板"下拉;选中即把 prompt 填进输入框)。
|
|
3466
|
+
*
|
|
3467
|
+
* 为什么归工具而不是面板写死:模板与"这个模型擅长什么"强相关(写实模型和线稿模型的模板
|
|
3468
|
+
* 不是一套),由提供该模型的工具插件声明最合适;面板只负责列出与填入,加模板不用改面板。
|
|
3469
|
+
*/
|
|
3470
|
+
declare interface ToolTemplate {
|
|
3471
|
+
/** 模板 id(面板内唯一) */
|
|
3472
|
+
id: string;
|
|
3473
|
+
/** 下拉显示名 */
|
|
3474
|
+
name: string;
|
|
3475
|
+
/** 选中后填入输入框的提示词正文 */
|
|
3476
|
+
prompt: string;
|
|
3477
|
+
/** 可选一句话说明(tooltip/副标题用) */
|
|
3478
|
+
description?: string;
|
|
3479
|
+
/** 只对某些工具生效时列出工具名;缺省 = 该工具通用 */
|
|
3480
|
+
forTools?: string[];
|
|
3481
|
+
/**
|
|
3482
|
+
* 应用该模板时一并写入的参数值(键 = ToolParamDef.key)。
|
|
3483
|
+
* 缺省 = 只填提示词,不动参数。
|
|
3484
|
+
*/
|
|
3485
|
+
values?: Record<string, unknown>;
|
|
3486
|
+
}
|
|
3487
|
+
|
|
3488
|
+
/**
|
|
3489
|
+
* 给模型看的 JSON Schema 子集(够描述 function calling 参数与产物,且**不必引第三方库**)。
|
|
3490
|
+
*
|
|
3491
|
+
* 为什么不引 JSON Schema 库:核心里只要"声明 + 校验 + 序列化"三件事,
|
|
3492
|
+
* 依赖一个 schema 库会把内核从"零依赖"变成"跟库的版本走"。
|
|
3493
|
+
*/
|
|
3494
|
+
declare interface ToolValueSchema {
|
|
3495
|
+
/** 缺省 = 'json'(任意可持久化 JSON 值) */
|
|
3496
|
+
type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'json';
|
|
3497
|
+
/** 人类可读标题(参数的 label 映射成它) */
|
|
3498
|
+
title?: string;
|
|
3499
|
+
description?: string;
|
|
3500
|
+
/** 候选值(`type:'select'` 的参数映射成它) */
|
|
3501
|
+
enum?: readonly (string | number | boolean)[];
|
|
3502
|
+
/** 非校验性默认值(原样进 schema,供模型/UI 参考) */
|
|
3503
|
+
default?: JsonValue;
|
|
3504
|
+
minimum?: number;
|
|
3505
|
+
maximum?: number;
|
|
3506
|
+
multipleOf?: number;
|
|
3507
|
+
/** `type:'object'` 时的属性表 */
|
|
3508
|
+
properties?: Record<string, ToolValueSchema>;
|
|
3509
|
+
/** `type:'object'` 时的必填键 */
|
|
3510
|
+
required?: readonly string[];
|
|
3511
|
+
/** `type:'array'` 时的元素 schema(缺省 = 任意 JSON 值) */
|
|
3512
|
+
items?: ToolValueSchema;
|
|
3513
|
+
}
|
|
3514
|
+
|
|
3515
|
+
/**
|
|
3516
|
+
* 资源地址(新写入的唯一形态):`/api/canvases/<canvasId>/resources/<hashName>`。
|
|
3517
|
+
*
|
|
3518
|
+
* 为什么不带 origin:云端可能换机器 / 换端口 / 挂反代,写死 origin 迟早失效;
|
|
3519
|
+
* 同源相对路径在任何部署形态下都对。hashName 是 16 位十六进制 + 可选扩展名(白名单形态),
|
|
3520
|
+
* 无需 URL 转义。
|
|
3521
|
+
*/
|
|
3522
|
+
export declare function toResourceUrl(canvasId: string, hashName: string): string;
|
|
3523
|
+
|
|
3524
|
+
/** 画布界面路由:托管 ui 产物(SPA:找不到的路径回落 index.html) */
|
|
3525
|
+
export declare function uiRoutes(uiDist: string | undefined,
|
|
3526
|
+
/**
|
|
3527
|
+
* 托管页要不要**顺手把管理令牌写进页面**(缺省不写)。
|
|
3528
|
+
*
|
|
3529
|
+
* 为什么需要:后台默认给写入口加了令牌,而令牌要用户自己去「设置 → 插件」粘贴一次。
|
|
3530
|
+
* 同机打开画布的人,本来就从启动日志里能看到那串 —— 让他再抄一遍纯属多余;
|
|
3531
|
+
* 忘了抄的表现是「所有写操作 403、节点上写着执行失败」,且看不出原因(真实踩到)。
|
|
3532
|
+
*
|
|
3533
|
+
* 只在**本机回环地址**访问时才允许:远程访问(局域网 / 反代)不注入,
|
|
3534
|
+
* 否则等于把令牌发给任何能打开这个页面的人。
|
|
3535
|
+
*/
|
|
3536
|
+
adminTokenForLocal?: () => string | undefined,
|
|
3537
|
+
/**
|
|
3538
|
+
* **彻底关闭注入**的开关。
|
|
3539
|
+
*
|
|
3540
|
+
* 为什么需要:「有转发头就不注入」的分界只能挡住**标准**反代。反代若被配成
|
|
3541
|
+
* `--reset-headers`(透传 Host、删掉所有转发头),三个条件会同时成立,令牌照样泄露。
|
|
3542
|
+
* 部署者知道自己要挂反代时,设 `PLUME_NO_TOKEN_INJECTION=1` 一刀切 ——
|
|
3543
|
+
* 所有用户都去「设置 → 插件」手填,代价只是多一次粘贴。
|
|
3544
|
+
*/
|
|
3545
|
+
noTokenInjection?: boolean): Hono;
|
|
3546
|
+
|
|
3547
|
+
/**
|
|
3548
|
+
* 盯住目录;签名变了就调 `onChange`。
|
|
3549
|
+
*
|
|
3550
|
+
* @param intervalMs 轮询间隔(默认 3 秒:够快,且几乎不耗资源)
|
|
3551
|
+
* @param onChange 变更回调(由调用方去重扫 + 通知前端)
|
|
3552
|
+
*/
|
|
3553
|
+
export declare function watchProviders(dir: string, onChange: () => void | Promise<void>, intervalMs?: number): ProviderWatcher;
|
|
3554
|
+
|
|
3555
|
+
export { }
|