@bilibili-notify/extension 0.0.0-stage → 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.mts ADDED
@@ -0,0 +1,2222 @@
1
+ import { ZodType, z } from "zod";
2
+ import { IncomingMessage } from "node:http";
3
+ import { Duplex } from "node:stream";
4
+ /**
5
+ * 操作结果与失败码 —— 成功、失败、标准失败码,以及 zod 报错的扁平化。
6
+ *
7
+ * 零依赖:只许 `import type`,值级 import 只能指向零依赖名单里的同伴。
8
+ * 面板与 contract 经 `@bilibili-notify/internal/result` 取值。
9
+ */
10
+ /**
11
+ * 标准码表(决策 3)。`retry` 是「自动重试」那一列:`no` 不重试,`later` 稍后重试,
12
+ * `depends` 看场合,`never` 绝不重试(结果不明,可能已经成功,重来会重复)。
13
+ *
14
+ * `unavailable` 与 `not_configured` 别混:前者等一会儿就好(推送链路还没就绪、库还没读完),
15
+ * 后者等多久都不会好,得主人先去配(装 Chrome、填 key、打开开关)。
16
+ */
17
+ declare const FAILURE_CODES: {
18
+ readonly not_found: {
19
+ readonly retry: "no";
20
+ };
21
+ readonly invalid: {
22
+ readonly retry: "no";
23
+ };
24
+ readonly unauthorized: {
25
+ readonly retry: "no";
26
+ };
27
+ readonly rate_limited: {
28
+ readonly retry: "later";
29
+ };
30
+ readonly unavailable: {
31
+ readonly retry: "later";
32
+ };
33
+ readonly not_configured: {
34
+ readonly retry: "no";
35
+ };
36
+ readonly timeout: {
37
+ readonly retry: "later";
38
+ };
39
+ readonly unsupported: {
40
+ readonly retry: "no";
41
+ };
42
+ readonly conflict: {
43
+ readonly retry: "depends";
44
+ };
45
+ readonly indeterminate: {
46
+ readonly retry: "never";
47
+ };
48
+ readonly unknown: {
49
+ readonly retry: "no";
50
+ };
51
+ };
52
+ type FailureCode = keyof typeof FAILURE_CODES;
53
+ /** 校验或检查不过的一条原因。`path` 从被校验的那一层往下数;落在根上的没有 `path`。 */
54
+ interface Issue {
55
+ path?: (string | number)[];
56
+ message: string;
57
+ }
58
+ /** 一次操作失败的那一支。上游平台自己的码只放 `upstreamCode`,永远不占 `code`。 */
59
+ interface Failure {
60
+ ok: false;
61
+ code: FailureCode;
62
+ message: string;
63
+ upstreamCode?: number | string;
64
+ issues?: Issue[];
65
+ }
66
+ /** 一次操作的结果。成功那一支的内容铺平在 `ok` 旁边。 */
67
+ type Result<T extends object = Record<never, never>> = ({
68
+ ok: true;
69
+ } & T) | Failure;
70
+ /** 成功的结果。内容不许自带 `ok` 这一格 —— 它会把判别键盖掉。 */
71
+ declare function ok(): {
72
+ ok: true;
73
+ };
74
+ declare function ok<T extends object & {
75
+ ok?: never;
76
+ }>(value: T): {
77
+ ok: true;
78
+ } & T;
79
+ /**
80
+ * 失败的结果。没给的附加格不出现(不留值为 undefined 的键)。
81
+ * 码保留字面量,只会拒收的地方可以把失败那一支写成 `Failure & { code: "invalid" }`。
82
+ */
83
+ declare function fail<C extends FailureCode>(code: C, message: string, extras?: {
84
+ upstreamCode?: number | string;
85
+ issues?: Issue[];
86
+ }): Failure & {
87
+ code: C;
88
+ };
89
+ /** 订阅来源的键:`bilibili` 或拓展 id,不加前缀(拓展 id 不许用保留 id,由宿主校验)。 */
90
+ type SourceKey = string;
91
+ /** 一条订阅订的是谁。判重看这两格是否都相等。 */
92
+ interface Identity {
93
+ sourceKey: SourceKey;
94
+ /** 来源那头的 id,BN 不解读;B 站就是 uid。 */
95
+ externalId: string;
96
+ }
97
+ /** 取字时填占位符的值;`count` 同时决定挑哪个单复数类别。 */
98
+ type TextValues = Readonly<Record<string, string | number>>;
99
+ /**
100
+ * 连接上存的那份平台描述 —— {@link PlatformDescriptor} 去掉 `platform`。只有宿主写
101
+ * (新建时从适配器的候选抄,认不出的填 {@link neutralPlatformSnapshot})。
102
+ */
103
+ declare const PlatformSnapshotSchema: z.ZodObject<{
104
+ label: z.ZodString;
105
+ shortLabel: z.ZodString;
106
+ color: z.ZodString;
107
+ icon: z.ZodOptional<z.ZodString>;
108
+ targetKind: z.ZodEnum<{
109
+ session: "session";
110
+ endpoint: "endpoint";
111
+ }>;
112
+ scopes: z.ZodArray<z.ZodEnum<{
113
+ group: "group";
114
+ private: "private";
115
+ channel: "channel";
116
+ }>>;
117
+ addressNouns: z.ZodObject<{
118
+ group: z.ZodOptional<z.ZodString>;
119
+ private: z.ZodOptional<z.ZodString>;
120
+ channel: z.ZodOptional<z.ZodString>;
121
+ }, z.core.$strip>;
122
+ }, z.core.$strip>;
123
+ type PlatformSnapshot = z.infer<typeof PlatformSnapshotSchema>;
124
+ /** 描述一个聊天平台(适配器的连接候选里带的那份)。 */
125
+ type PlatformDescriptor = PlatformSnapshot & {
126
+ platform: string;
127
+ };
128
+ /**
129
+ * Connection — 一条"连接实例"。一个借来的 / 自己连的 bot,被多个 PushTarget 复用。
130
+ *
131
+ * `settings` 的形状归适配器的 `settingsSchema`,核心不认识任何一个适配器的设置。
132
+ * `platformSnapshot` 与 `probeState` 只有宿主写。
133
+ */
134
+ declare const ConnectionSchema: z.ZodObject<{
135
+ settings: z.ZodUnknown;
136
+ platformSnapshot: z.ZodObject<{
137
+ label: z.ZodString;
138
+ shortLabel: z.ZodString;
139
+ color: z.ZodString;
140
+ icon: z.ZodOptional<z.ZodString>;
141
+ targetKind: z.ZodEnum<{
142
+ session: "session";
143
+ endpoint: "endpoint";
144
+ }>;
145
+ scopes: z.ZodArray<z.ZodEnum<{
146
+ group: "group";
147
+ private: "private";
148
+ channel: "channel";
149
+ }>>;
150
+ addressNouns: z.ZodObject<{
151
+ group: z.ZodOptional<z.ZodString>;
152
+ private: z.ZodOptional<z.ZodString>;
153
+ channel: z.ZodOptional<z.ZodString>;
154
+ }, z.core.$strip>;
155
+ }, z.core.$strip>;
156
+ probeState: z.ZodOptional<z.ZodObject<{
157
+ status: z.ZodEnum<{
158
+ unsupported: "unsupported";
159
+ reachable: "reachable";
160
+ unreachable: "unreachable";
161
+ }>;
162
+ lastCheckedAt: z.ZodString;
163
+ latencyMs: z.ZodOptional<z.ZodNumber>;
164
+ message: z.ZodOptional<z.ZodString>;
165
+ }, z.core.$strip>>;
166
+ id: z.ZodUUID;
167
+ name: z.ZodString;
168
+ enabled: z.ZodBoolean;
169
+ adapterKey: z.ZodString;
170
+ platform: z.ZodString;
171
+ }, z.core.$strip>;
172
+ type Connection = z.infer<typeof ConnectionSchema>;
173
+ declare const PushTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
174
+ kind: z.ZodLiteral<"session">;
175
+ scope: z.ZodEnum<{
176
+ group: "group";
177
+ private: "private";
178
+ channel: "channel";
179
+ }>;
180
+ address: z.ZodString;
181
+ parentAddress: z.ZodOptional<z.ZodString>;
182
+ id: z.ZodUUID;
183
+ name: z.ZodString;
184
+ connectionId: z.ZodUUID;
185
+ enabled: z.ZodBoolean;
186
+ managedBy: z.ZodOptional<z.ZodLiteral<"connection">>;
187
+ reachability: z.ZodOptional<z.ZodObject<{
188
+ status: z.ZodEnum<{
189
+ reachable: "reachable";
190
+ unreachable: "unreachable";
191
+ }>;
192
+ changedAt: z.ZodString;
193
+ latencyMs: z.ZodOptional<z.ZodNumber>;
194
+ message: z.ZodOptional<z.ZodString>;
195
+ }, z.core.$strip>>;
196
+ }, z.core.$strip>, z.ZodObject<{
197
+ kind: z.ZodLiteral<"endpoint">;
198
+ id: z.ZodUUID;
199
+ name: z.ZodString;
200
+ connectionId: z.ZodUUID;
201
+ enabled: z.ZodBoolean;
202
+ managedBy: z.ZodOptional<z.ZodLiteral<"connection">>;
203
+ reachability: z.ZodOptional<z.ZodObject<{
204
+ status: z.ZodEnum<{
205
+ reachable: "reachable";
206
+ unreachable: "unreachable";
207
+ }>;
208
+ changedAt: z.ZodString;
209
+ latencyMs: z.ZodOptional<z.ZodNumber>;
210
+ message: z.ZodOptional<z.ZodString>;
211
+ }, z.core.$strip>>;
212
+ }, z.core.$strip>], "kind">;
213
+ type PushTarget = z.infer<typeof PushTargetSchema>;
214
+ /**
215
+ * 一个会话的两坐标 —— 范围 + 地址,取自会话目标自己的类型(`Pick`),不另抄一份声明。
216
+ *
217
+ * 不经推送目标表、直接往某个会话回话的口子用它(链接解析回到来源群):用哪条连接由调用方另给,
218
+ * 这里只说「连接上的哪个会话」。
219
+ */
220
+ type SessionRef = Pick<Extract<PushTarget, {
221
+ kind: "session";
222
+ }>, "scope" | "address" | "parentAddress">;
223
+ /** 端点目标的「发到哪」—— webhook 写进冻结 JSON 的正是这三格。 */
224
+ type EndpointRef = Pick<Extract<PushTarget, {
225
+ kind: "endpoint";
226
+ }>, "id" | "name">;
227
+ /**
228
+ * 适配器发送口收的「发到哪」—— 推送目标里**发送要用的那几格**,按 `kind` 分两支。
229
+ * 开关、所属连接、平台这些不在其中:那些检查只在派发器做一份(ADR-0024 决策 13)。
230
+ */
231
+ type DestinationRef = Pick<Extract<PushTarget, {
232
+ kind: "session";
233
+ }>, "kind" | keyof SessionRef> | Pick<Extract<PushTarget, {
234
+ kind: "endpoint";
235
+ }>, "kind" | keyof EndpointRef>;
236
+ /**
237
+ * 推送目标的会话种类。`schema/targets.ts` 的 `PushTargetScopeSchema` 从这里取值 ——
238
+ * 词表住零依赖模块,前端才拿得到运行时的那一份(与 `features.ts` 的 FEATURE_KEYS 同一套安排)。
239
+ */
240
+ declare const PUSH_TARGET_SCOPES: readonly ["group", "private", "channel"];
241
+ type PushTargetScope = (typeof PUSH_TARGET_SCOPES)[number];
242
+ /**
243
+ * 图库引用形状 —— `<sha256>.<ext>` 的扩展名和校验正则。
244
+ *
245
+ * 零依赖:只许 `import type`,值级 import 只能指向零依赖名单里的同伴。
246
+ * 不开子路径,只从根入口转。
247
+ */
248
+ /**
249
+ * 图库引用:图库 `images/` 里的文件名 `<sha256>.<ext>`,扩展名按嗅探(png / jpg / gif / webp,JPEG 一律
250
+ * 叫 jpg)。作品图、直播封面、头像、历史快照、聊天附件共用;引用自己就说明了格式,不另存 mime(ADR-0022
251
+ * 决策 9 下 10-03 的 🔗)。
252
+ */
253
+ type ImageRef = string;
254
+ /** 出卡认 `ref`;`url` 给「查看原图」;抓不到图库的图(B 站抓图失败)时出卡仍靠它画。 */
255
+ interface PostImage {
256
+ ref?: ImageRef;
257
+ url?: string;
258
+ width?: number;
259
+ height?: number;
260
+ isAnimated?: boolean;
261
+ }
262
+ interface Creator {
263
+ name: string;
264
+ avatar?: ImageRef;
265
+ isPremium?: boolean;
266
+ }
267
+ /**
268
+ * 正文的一个片段,只用来出卡高亮。五种,全中立:换行留在 `text` 里当 `\n`;`topic.name` 不带 `#`;
269
+ * `emoji.text` 是「[doge]」这种代码,没图时当文字画。卡片只画片段的 `text`(有图标就画图标)。
270
+ */
271
+ type RichTextSegment = {
272
+ kind: "text";
273
+ text: string;
274
+ } | {
275
+ kind: "mention";
276
+ text: string;
277
+ externalId?: string;
278
+ } | {
279
+ kind: "topic";
280
+ text: string;
281
+ name: string;
282
+ } | {
283
+ kind: "link";
284
+ text: string;
285
+ url: string;
286
+ icon?: ImageRef;
287
+ } | {
288
+ kind: "emoji";
289
+ text: string;
290
+ image?: ImageRef;
291
+ };
292
+ type RichText = RichTextSegment[];
293
+ /** 附加块:封闭联合,出图器按种类直接画。 */
294
+ type Attachment = {
295
+ kind: "card";
296
+ eyebrow?: string;
297
+ cover?: PostImage;
298
+ title: string;
299
+ lines?: {
300
+ text: string;
301
+ icon?: ImageRef;
302
+ }[];
303
+ button?: {
304
+ text: string;
305
+ enabled: boolean;
306
+ };
307
+ } | {
308
+ kind: "video";
309
+ cover: PostImage;
310
+ title: string;
311
+ durationSec?: number;
312
+ subtitle?: string;
313
+ } | {
314
+ kind: "goods";
315
+ eyebrow?: string;
316
+ items: {
317
+ cover: PostImage;
318
+ name: string;
319
+ price?: string;
320
+ }[];
321
+ };
322
+ interface Post {
323
+ creator: Creator;
324
+ /** ISO 时间。 */
325
+ publishedAt: string;
326
+ /** 「投稿了视频」这类说明,来源给。 */
327
+ label?: string;
328
+ topic?: string;
329
+ /** 有这格就按文章排版;`images` 是文章配图。 */
330
+ article?: {
331
+ title: string;
332
+ images?: PostImage[];
333
+ };
334
+ /** 有标题、但不是文章的作品(带标题的图文、笔记)的标题:画在正文上方,排版照普通作品。 */
335
+ title?: string;
336
+ /** 纯文本,只放正文;标题、视频标题、被转发的原作品各在自己的格里。 */
337
+ text: string;
338
+ /** 片段的 `text` 拼起来必须等于 `text`,见 {@link normalizePost}。 */
339
+ richText?: RichText;
340
+ /** BN 自己说的一句,画在正文后面。 */
341
+ notice?: string;
342
+ /** 专属内容锁,替掉正文。 */
343
+ locked?: {
344
+ icon?: PostImage;
345
+ title: string;
346
+ hint: string;
347
+ };
348
+ /** 只表示图集。 */
349
+ images?: PostImage[];
350
+ /**
351
+ * 作品本身就是这个视频。播放与弹幕是视频自己的展示数字,点赞评论转发在 `stats`。
352
+ * 时长选填(与 `Attachment.video` 一致):直播回放、首映这类没有时长,缺了就不画时长角标。
353
+ */
354
+ video?: {
355
+ cover: PostImage;
356
+ title: string;
357
+ description: string;
358
+ durationSec?: number;
359
+ views?: number;
360
+ danmaku?: number;
361
+ };
362
+ attachment?: Attachment;
363
+ /** 被转发的原作品。 */
364
+ repost?: Post;
365
+ stats?: {
366
+ shares?: number;
367
+ comments?: number;
368
+ likes?: number;
369
+ };
370
+ }
371
+ /**
372
+ * 来源交的一条作品(`reportPost(externalId, report)` 的第二个参数):图都已是图库引用。
373
+ * 来源不知道订阅 id,订阅由核心(接线)按身份查出来。
374
+ */
375
+ interface PostReport {
376
+ /** 来源自己给这条作品的 id(统计据此去重)。 */
377
+ postId: string;
378
+ /** 作品地址;推送里的链接部件就是它。 */
379
+ url: string;
380
+ post: Post;
381
+ }
382
+ interface MembershipEvent {
383
+ subscriptionId: string;
384
+ viewer: {
385
+ id: string;
386
+ name: string;
387
+ avatar?: ImageRef;
388
+ };
389
+ /** 体系 id,见 {@link MembershipProgram.id}。 */
390
+ program: string;
391
+ tier: {
392
+ key: string;
393
+ name: string;
394
+ rank?: number;
395
+ };
396
+ action?: "new" | "renew" | "upgrade";
397
+ months?: number;
398
+ /** 时长等级:虎牙的 V 等级、累计月数。 */
399
+ tenure?: string;
400
+ gift?: {
401
+ gifter: string;
402
+ count: number;
403
+ };
404
+ amount?: number;
405
+ currency?: string;
406
+ }
407
+ interface SuperchatEvent {
408
+ subscriptionId: string;
409
+ viewer: {
410
+ id: string;
411
+ name: string;
412
+ avatar?: ImageRef;
413
+ };
414
+ text: string;
415
+ amount: number;
416
+ currency: string;
417
+ /** 醒目留言的档,来源按平台规矩算;`durationSec` 是留言挂多久。 */
418
+ tier?: {
419
+ rank: number;
420
+ durationSec?: number;
421
+ };
422
+ }
423
+ /**
424
+ * 特别关注名单上的人在直播间里发了弹幕(特别弹幕)。认人靠 `viewer.id`(整串比对),名字只拿去套文案;
425
+ * `text` 是弹幕正文。与 {@link SuperchatEvent} 同族:带订阅 id,来源上报时去掉它({@link LiveInteractionReport})。
426
+ */
427
+ interface ViewerChatEvent {
428
+ subscriptionId: string;
429
+ viewer: {
430
+ id: string;
431
+ name: string;
432
+ };
433
+ text: string;
434
+ }
435
+ /** 特别关注名单上的人进了直播间(特别进场)。认人同 {@link ViewerChatEvent}。 */
436
+ interface ViewerEnterEvent {
437
+ subscriptionId: string;
438
+ viewer: {
439
+ id: string;
440
+ name: string;
441
+ };
442
+ }
443
+ /** 一场直播的内容。 */
444
+ interface LiveDetails {
445
+ title?: string;
446
+ cover?: PostImage;
447
+ category?: string;
448
+ url?: string;
449
+ /** 此刻在线。 */
450
+ currentViewers?: number;
451
+ /** 本场累计观看。 */
452
+ totalViewers?: number;
453
+ likes?: number;
454
+ description?: string;
455
+ creator?: Creator;
456
+ }
457
+ /** 来源推送式上报的直播信号:发生了就报,`reportLive(externalId, signal)`。时刻一律是 ISO。 */
458
+ type LiveSignalReport = {
459
+ kind: "start";
460
+ startedAt?: string;
461
+ details: LiveDetails;
462
+ } | {
463
+ kind: "status";
464
+ isLive: boolean;
465
+ startedAt?: string;
466
+ details: LiveDetails;
467
+ } | {
468
+ kind: "end";
469
+ endedAt: string;
470
+ startedAt?: string;
471
+ details?: LiveDetails;
472
+ };
473
+ /**
474
+ * 拉取式:核心定时问来源 `fetchLiveStatus` 的结果(ADR-0026 决策 4;ADR-0021 决策 27)。
475
+ *
476
+ * - `live`:此刻在播,带数据(核心记进在播表,周期「正在直播」开着才推卡);
477
+ * - `offline`:此刻没在播,核心当成漏收的下播,走下播同一条路,时长算到「发现已下播的那一刻」;
478
+ * - `ok: false`:这一轮没取到 —— 核心跳过、记日志,**不停止监听、也不替来源报问题**(问题来源自己经
479
+ * `ctx.reportProblem` 报)。
480
+ */
481
+ type LiveStatusResult = {
482
+ ok: true;
483
+ kind: "live";
484
+ startedAt?: string;
485
+ details: LiveDetails;
486
+ } | {
487
+ ok: true;
488
+ kind: "offline";
489
+ } | {
490
+ ok: false;
491
+ code: string;
492
+ message: string;
493
+ };
494
+ /**
495
+ * 来源经 `reportLiveInteraction(externalId, report)` 上报的观众互动:形状是对应事件去掉 `subscriptionId`
496
+ * (订阅 id 来源不知道,核心按身份展开成每条订阅一份时补上)。四种:特别弹幕、特别进场、醒目留言、会员。
497
+ *
498
+ * `fallbackText`:出不了卡时发的那句;来源给了就用它(平台自己的叫法由来源拼好),没给就用核心字典里一句中性的。
499
+ */
500
+ type LiveInteractionReport = ({
501
+ kind: "viewerChat";
502
+ } & Omit<ViewerChatEvent, "subscriptionId">) | ({
503
+ kind: "viewerEnter";
504
+ } & Omit<ViewerEnterEvent, "subscriptionId">) | ({
505
+ kind: "superchat";
506
+ } & Omit<SuperchatEvent, "subscriptionId"> & {
507
+ fallbackText?: string;
508
+ }) | ({
509
+ kind: "membership";
510
+ } & Omit<MembershipEvent, "subscriptionId"> & {
511
+ fallbackText?: string;
512
+ });
513
+ /**
514
+ * 登录 / 扫码建连接的中立状态。状态值 kebab;订阅侧的 `SourceAuth` 与推送侧的
515
+ * `connectionAuth` 共用这一份,取值是两边的并集。
516
+ *
517
+ * - `logged-out`:没登录。
518
+ * - `awaiting-scan`:等扫码。`qr.dataUrl` 是 `data:image/…;base64,…` 的整串,面板直接画;
519
+ * `qr.expiresAt` 是 ISO 字符串,**最晚作废时刻**。给不出真过期时刻的平台取
520
+ * 「创建时刻 + 清扫时限」,所以它是上界,不是平台二维码真正的过期时刻。
521
+ * - `confirming`:**BN 还在等 / 还在核,此刻不算登录**。是 BN 推断的状态,不是平台报的。
522
+ * 两种情况都用它:手机上已扫、等主人在手机上点确认;手里有登录信息、还没向平台确认有效。
523
+ * `message` 由服务端给人话(两种情况要主人做的事不同,读的人分不出来);没有 `message`
524
+ * 时读的人写「正在确认」。`connectionAuth` 没有产出者(QQ 没有「已扫、等确认」)。
525
+ * - `logged-in`:`loggedInAt` 是这个进程里这一段登录第一次被确认的时刻(不落盘)。
526
+ * - `expired`:**已经登着的登录失效了,要重新登录**。只有订阅侧会发;`connectionAuth`
527
+ * 没有「已经登着的登录」,不发它。
528
+ * - `error`:这一次没办成,`message` 说原因。**二维码超时、失效两边都报它**。
529
+ *
530
+ * `error` / `expired` 的 `message` 由服务端给人话,面板只显示,不靠比对文字做判断。
531
+ */
532
+ type AuthState = {
533
+ status: "logged-out";
534
+ } | {
535
+ status: "awaiting-scan";
536
+ qr: {
537
+ dataUrl: string;
538
+ expiresAt: string;
539
+ };
540
+ } | {
541
+ status: "confirming";
542
+ message?: string;
543
+ } | {
544
+ status: "logged-in";
545
+ loggedInAt: string;
546
+ } | {
547
+ status: "expired" | "error";
548
+ message: string;
549
+ };
550
+ /** 即将发出的一跳(含第一次请求)。 */
551
+ interface Hop {
552
+ /** 这一跳要去的地址。 */
553
+ url: URL;
554
+ /** 第几跳:第一次请求是 0,之后每跟一次重定向加 1。 */
555
+ index: number;
556
+ /** 上一跳的地址与它回的状态码(重定向要去的就是 `url`);第 0 跳没有。 */
557
+ from?: {
558
+ url: URL;
559
+ status: number;
560
+ };
561
+ }
562
+ /**
563
+ * 每一跳发出之前调(第一次请求也算),回 `ok()` 放行,回失败就否决:`fetch` 把这个失败原样
564
+ * 回给调用方、这一跳不发。前一跳的 Set-Cookie 此时已经摄进罐子。可以是异步的。
565
+ */
566
+ type HopHandler = (hop: Hop) => Result | Promise<Result>;
567
+ interface FetchOptions {
568
+ /** 默认 GET。 */
569
+ method?: string;
570
+ /** 这一次请求的头,盖过客户端默认头与身份(大小写不敏感)。 */
571
+ headers?: Headers | Record<string, string>;
572
+ /**
573
+ * 请求体。只收能原样重发的类型(307 / 308 要重发)。GET / HEAD 不许带。
574
+ * `FormData` 每一跳由运行时现序列化(boundary 也是运行时补的,别自己写 `Content-Type`);
575
+ * 但它不能和宿主自用的 `addressCheck` 同用(那条路是 npm `undici`,不认全局的 `FormData`),当场回 `invalid`。
576
+ */
577
+ body?: string | Uint8Array<ArrayBuffer> | FormData;
578
+ /** 调用方的中止信号。 */
579
+ signal?: AbortSignal;
580
+ /** 这一次请求的单跳超时毫秒,默认取客户端的。 */
581
+ timeoutMs?: number;
582
+ /**
583
+ * 最多跟几跳重定向,默认 5。`0` 就是不跟。跟满了遇到的下一个 3xx 不当失败,原样回给调用方
584
+ * (状态码 3xx、带 Location 头),由调用方判 —— 所以 `maxRedirects: 0` 就是「只看第一跳的 Location」。
585
+ */
586
+ maxRedirects?: number;
587
+ /** 每一跳发出之前的检查,可否决。 */
588
+ beforeHop?: HopHandler;
589
+ /**
590
+ * `"exchange"`(默认)外发罐子的 cookie、也把响应的 Set-Cookie 摄进罐子;
591
+ * `"send-only"` 只外发、不摄入(罐子里的东西这个请求只读)。
592
+ */
593
+ cookies?: "exchange" | "send-only";
594
+ /**
595
+ * 「不带浏览器身份、不碰罐」一档:不补身份四件、不带客户端的默认头、不带 `Cookie`、不收 `Set-Cookie`
596
+ * (重定向的每一跳也一样,`cookies` 选项在这一档下不起作用)。调用方这一次自己写的头照发。
597
+ * 内置的适配器调官方接口 / 主人填的地址用它:那些对端不该看到 B 站这套浏览器指纹与登录态。
598
+ */
599
+ bare?: boolean;
600
+ /**
601
+ * 响应体的字节上限。超了回 `invalid`:带 `Content-Length` 且已经超的不读体;其余边读边数,读过上限当场掐断
602
+ * (不把超大的体整个读进内存再量)。不给就整个读完。只管最后落脚的那个回应,重定向跳的体本来就不读。
603
+ */
604
+ maxBodyBytes?: number;
605
+ }
606
+ /**
607
+ * 一次请求的回应。成功那一支的内容铺平在 `ok` 旁边(`Result<HttpResponse>`),所以这里**没有**
608
+ * `ok` 这一格:先看 `result.ok`(请求有没有走通),再看 `status`(对端怎么说)。
609
+ */
610
+ interface HttpResponse {
611
+ /** 最后落脚的地址(跟过重定向之后)。 */
612
+ url: string;
613
+ status: number;
614
+ headers: Headers;
615
+ /** 原始字节。 */
616
+ body: Uint8Array;
617
+ /** 状态码是不是 2xx。 */
618
+ isSuccess: boolean;
619
+ /** 按 UTF-8 转文本(去掉 BOM)。 */
620
+ text(): string;
621
+ /** 按 JSON 解析:不是合法 JSON 回 `invalid`(对端回了别的东西不是 bug,不抛)。 */
622
+ json(): Result<{
623
+ value: unknown;
624
+ }>;
625
+ }
626
+ /**
627
+ * `websocket()` 交出的连接 —— `ws` 的 WebSocket 的最小子集,不把第三方库的类型摆进对外面。
628
+ *
629
+ * 事件(`open` / `message` / `error` / `close`)用 `on` 订阅,监听器的参数照 `ws` 给:
630
+ * `message` 是 `(data, isBinary)`,`close` 是 `(code, reason)`。**一定要挂 `error`**:
631
+ * 握手期被关(含 `signal` 中止)时 `ws` 会先报一次 `error` 再 `close`,没人接会炸进程。
632
+ */
633
+ interface WebSocketLike {
634
+ /** 二进制帧交给 `message` 监听器的形态;常用 `"nodebuffer"`。 */
635
+ binaryType: string;
636
+ /** 连接状态,取值照 WHATWG:0 建连中 / 1 已连上 / 2 关闭中 / 3 已关。 */
637
+ readonly readyState: number;
638
+ on(event: string, listener: (...args: unknown[]) => void): void;
639
+ /** 字符串发文本帧,字节发二进制帧(`ws` 本来就这么分)。 */
640
+ send(data: string | Uint8Array): void;
641
+ close(): void;
642
+ }
643
+ interface WebSocketOptions {
644
+ /**
645
+ * 附加的握手头。默认头(`Cookie`、`User-Agent`)在前,这里同名(大小写不敏感)的盖过它、
646
+ * 留在原位置,别的追加在后面。
647
+ */
648
+ headers?: Record<string, string>;
649
+ /**
650
+ * 中止就关掉连接(建连时已经中止的,连接一建好就关)。握手期被关会先报一次 `error` 再 `close`。
651
+ * 集成停下时自动关就靠它(3a 把 `ctx.signal` 接到这里)。
652
+ */
653
+ signal?: AbortSignal;
654
+ /** 「不带身份、不碰罐」一档:握手不带 `Cookie` 与身份的 `User-Agent`,只有上面的 `headers`。 */
655
+ bare?: boolean;
656
+ }
657
+ /**
658
+ * 每个集成一个的请求客户端(对外的那一面)。`fetch` 非 2xx 不抛、网络断 / 超时 / 被中止都回结果形状;
659
+ * `websocket` 给错地址回 `invalid`,不抛。
660
+ */
661
+ interface HttpClient {
662
+ fetch(url: string | URL, options?: FetchOptions): Promise<Result<HttpResponse>>;
663
+ /** 用这个客户端的身份与罐子建一条 WebSocket;帧、心跳、重连归调用方。 */
664
+ websocket(url: string | URL, options?: WebSocketOptions): Result<{
665
+ socket: WebSocketLike;
666
+ }>;
667
+ }
668
+ /** 能原样进出 JSON 的值。数字只收有限数;对象只收普通对象。 */
669
+ type Json = string | number | boolean | null | Json[] | {
670
+ [key: string]: Json;
671
+ };
672
+ /** 一批改动里的一步(一步操作叫 `Op`,判别键叫 `kind`;取值就是方法名)。 */
673
+ type KeyValueOp = {
674
+ kind: "set";
675
+ key: string;
676
+ value: Json;
677
+ } | {
678
+ kind: "delete";
679
+ key: string;
680
+ };
681
+ /**
682
+ * 集成的小存储。`state` 与 `secrets` 是同一个接口,差别只在保管(ADR-0025 决策 9)。
683
+ * - `get` 同步:宿主在 `start` / `activate` 之前读进内存;交回的是一份拷贝,改它不影响存着的。
684
+ * - 写不抛(决策 10):超上限、写了 `http.` 开头的键、值不是 JSON 回 `invalid`;磁盘写失败回 `unavailable`。
685
+ * - 读得到的永远是落了盘的:`await` 回来之前 `get` 还是旧值。
686
+ */
687
+ interface KeyValueStore {
688
+ get<T extends Json>(key: string): T | undefined;
689
+ set(key: string, value: Json): Promise<Result>;
690
+ delete(key: string): Promise<Result>;
691
+ /**
692
+ * 一批改动,**保证一起成或一起不成**:先整批校验(任何一步不合规矩,整批回 `invalid`,一步都不做),
693
+ * 再按顺序应用、一次原子写落盘;写失败整批不生效。同一个键出现几次,后面的盖前面的。空批直接回成功。
694
+ */
695
+ batch(ops: readonly KeyValueOp[]): Promise<Result>;
696
+ }
697
+ /**
698
+ * 设置 / 连接配置表单里的一格的形状,面板照它画、宿主照它对表。中立概念:今天只有拓展交,
699
+ * 内置集成第 4 期交同一种(ADR-0025 决策 3)。
700
+ */
701
+ /**
702
+ * 一格**设置项 / 连接配置项** —— 面板照它画一栏,按**数据类型**分、不按控件分
703
+ * (ADR-0019 决策 17)。它落在清单里(`settings.fields` / `contributes.push.settingsFields`):
704
+ * 官方拓展由构建从规则导出(规则上写 {@link SettingsFieldMeta},`settingsFieldsFromSchema`),
705
+ * 手写清单的与代码里那份 zod 是两份声明。两种都在加载时对表。
706
+ *
707
+ * 🔴 **这是清单那份 schema 的手写镜像**:宿主把清单里读出来的格原样交给面板,所以
708
+ * `SettingsField` 必须与它严格相等 —— `manifest-shape-pin.ts` 的类型检查会替两份钉住。
709
+ *
710
+ * 🔴 `secret: true` 同时是**备份脱敏的依据**。脱敏本来靠一份键名黑名单,而集成的键名归
711
+ * 集成自己起 —— 不声明的话,那个 token 会原样躺在主人发出去求助的备份文件里。
712
+ */
713
+ type SettingsField = SettingsScalarField | SettingsListField;
714
+ /** 单值的那几种。推送源的连接配置项只能是它们(连接的 config 是扁平的一层键值)。 */
715
+ type SettingsScalarField = SettingsStringField | SettingsNumberField | SettingsBooleanField | SettingsEnumField;
716
+ /** 内置连接描述使用的扩展;拓展清单仍只收 SettingsScalarField。 */
717
+ type ConnectionSettingsField = (SettingsScalarField | SettingsRecordField) & {
718
+ /** 这一格只在指定的分支里显示。 */
719
+ when?: {
720
+ key: string;
721
+ value: string;
722
+ };
723
+ /** 切换分支时整体重建设置,保留声明的共用值。 */
724
+ variants?: Readonly<Record<string, {
725
+ settings: Readonly<Record<string, unknown>>;
726
+ preserve: readonly {
727
+ key: string;
728
+ truthy?: boolean;
729
+ }[];
730
+ }>>;
731
+ /** 同一适配器的候选平台可有不同的提示文字。 */
732
+ byPlatform?: Readonly<Record<string, {
733
+ description?: string;
734
+ placeholder?: string;
735
+ }>>;
736
+ /** 端口字段旁显示由访问主机与端口组成的接入地址。 */
737
+ listener?: {
738
+ scheme: "ws";
739
+ };
740
+ };
741
+ interface SettingsRecordField extends SettingsFieldBase {
742
+ type: "record";
743
+ default?: Record<string, string>;
744
+ }
745
+ interface SettingsStringField extends SettingsFieldBase {
746
+ type: "string";
747
+ default?: string;
748
+ placeholder?: string;
749
+ secret?: boolean;
750
+ multiline?: boolean;
751
+ monospace?: boolean;
752
+ /** 面板替主人生成一串,新建时明文显示一次。 */
753
+ generate?: boolean;
754
+ }
755
+ interface SettingsNumberField extends SettingsFieldBase {
756
+ type: "number";
757
+ default?: number;
758
+ min?: number;
759
+ max?: number;
760
+ step?: number;
761
+ unit?: string;
762
+ }
763
+ interface SettingsBooleanField extends SettingsFieldBase {
764
+ type: "boolean";
765
+ default?: boolean;
766
+ }
767
+ interface SettingsEnumField extends SettingsFieldBase {
768
+ type: "enum";
769
+ /**
770
+ * 选项图标是图片的 base64 data URL(png / jpeg / webp / svg),面板当 `<img>` 画;
771
+ * 清单格式那一步已经把它限定成图片、封了顶。
772
+ */
773
+ options: readonly {
774
+ value: string;
775
+ label: string;
776
+ icon?: string;
777
+ }[];
778
+ default?: string;
779
+ }
780
+ /**
781
+ * 对象数组:每一项一张卡。只嵌一层 —— 项里只有单值。
782
+ *
783
+ * 项的 `id` 由 BN 生成、藏起来、不许改(视图按它把积木挂到那一项上),不在 `fields` 里。
784
+ */
785
+ interface SettingsListField extends SettingsFieldBase {
786
+ type: "list";
787
+ fields: readonly SettingsScalarField[];
788
+ /** 哪一格当卡片标题(项里一格必填的 string)。 */
789
+ title: string;
790
+ /** 一项叫什么(「接入」)。不给就用 `label`。 */
791
+ itemLabel?: string;
792
+ /** 哪个 enum 的选中项图标当卡片左上的方块。 */
793
+ mark?: string;
794
+ /** 哪一格 boolean 画成「停用 / 启用」。 */
795
+ toggle?: string;
796
+ /** 新建弹窗底部要成对复制的几样:BN 现算的地址,或者本项的某一格。 */
797
+ newItemCopy?: readonly ({
798
+ host: "extensionUrl";
799
+ label: string;
800
+ } | {
801
+ field: string;
802
+ })[];
803
+ /** 删除确认里「删了会怎样」那句。 */
804
+ removeWarning?: string;
805
+ }
806
+ interface SettingsFieldBase {
807
+ /** 值落在 `settings[key]` / `config[key]` —— **同时是这一栏的身份**。 */
808
+ key: string;
809
+ label: string;
810
+ description?: string;
811
+ required?: boolean;
812
+ }
813
+ /**
814
+ * 规则上给人看的那几格,写在 zod 4 的 `.meta({...})` 里(`z.string().meta({ label: "名字" } satisfies SettingsFieldMeta)`),
815
+ * 由 `settingsFieldsFromSchema` 与规则本身一起导出成 {@link SettingsField}。**类型、默认值、必填、上下限、
816
+ * 枚举的取值读规则本身,这里不写第二份。**
817
+ *
818
+ * - 写了 `label` 的键才出一栏;不给人填的键(连接里由拓展交的、列表项的 `id`)不写。
819
+ * - 每一格只用在对应的那一种上(下面按种类分组),写在别的种类上导出时抛。
820
+ * - meta 写在哪一层都行:`.optional()` / `.default()` 套在外面也读得到。
821
+ */
822
+ interface SettingsFieldMeta {
823
+ label: string;
824
+ description?: string;
825
+ placeholder?: string;
826
+ secret?: boolean;
827
+ multiline?: boolean;
828
+ monospace?: boolean;
829
+ generate?: boolean;
830
+ step?: number;
831
+ unit?: string;
832
+ options?: Readonly<Record<string, {
833
+ label: string;
834
+ icon?: string;
835
+ }>>;
836
+ title?: string;
837
+ itemLabel?: string;
838
+ mark?: string;
839
+ toggle?: string;
840
+ newItemCopy?: SettingsListField["newItemCopy"];
841
+ removeWarning?: string;
842
+ }
843
+ /**
844
+ * 一次连接探测的结果(ADR-0026):通了是 `{ ok: true, latencyMs }`,没通是 `Failure`。
845
+ * 这个适配器没有探测协议时回 `unsupported` —— 它不是「探了、没通」,调用方据此不改连接的状态。
846
+ */
847
+ type ProbeResult = Result<{
848
+ latencyMs: number;
849
+ }>;
850
+ /**
851
+ * 一个平台实现 —— 认领哪些连接、怎么建连、报文怎么编、地址怎么解、有什么能力。
852
+ * 矩阵({@link TargetDispatcher})拿它按连接的 `adapterKey` 找。
853
+ *
854
+ * 成员分两拨,但**文件刻意没拆**:「怎么连」(建连、重连退避、心跳、生命周期)是通用的,
855
+ * 一条 WS 长连怎么退避重连,跟对面说的是 OneBot 还是 QQ 网关无关,接桥那期的 `koishi` /
856
+ * `astrbot` 只会用到这一拨 —— 桥后面挂着哪些平台是它探出来告诉我们的,我们不为那些平台写
857
+ * 任何编解码;「说哪国话」(报文、地址、能力)只管把 {@link NotificationPayload} 译成对面
858
+ * 听得懂的东西,并回答「这个目标现在发得出去吗」。抽象只有一个长连接用例验证过,别的等
859
+ * 真有了第二个用例再动。
860
+ *
861
+ * 实现**不许抛**:失败回 `fail(code, message)`(码取标准码表,平台自己的码放 `upstreamCode`),
862
+ * 重试由路由层决定。真抛了算 bug,派发器在边界接住按 `unavailable` 记。
863
+ *
864
+ * 方法可以吃 `this`(class 写的、方法在原型上都行):宿主造视图、派生表、拓展包装、能力注入时
865
+ * 按成员表取成员、并把方法 `bind` 回原实例,不用对象展开。接口里多一个成员,宿主那张成员表
866
+ * (`apps/server/src/push/adapter-members.ts`)编译不过,逼着一起加。
867
+ */
868
+ interface PlatformAdapter {
869
+ /**
870
+ * 适配器键 —— 登记表与分发按它找。内置的是 `"onebot"` / `"qq-official"` / `"webhook"`
871
+ * (webhook 那一族:飞书 / 钉钉 / 企微 / 通用共用一个),拓展的由宿主填成拓展 id。
872
+ */
873
+ readonly adapterKey: string;
874
+ /**
875
+ * 这个适配器的脸与连接配置项(ADR-0024 决策 3),`GET /api/adapters` 照它列。写成方法:名字是给人看的字,
876
+ * 要在出字那一刻按当前语言取(ADR-0037 决策 1),每次读都现调;字段会在宿主造视图时冻住。
877
+ *
878
+ * 拓展的由宿主照清单 `contributes.push` 填,拓展自己交的不认(ADR-0024 决策 3 下 10-14 的 🔗)。
879
+ * 内置三个的 `settingsFields` 随 4-29 和表单一起设计,在那之前是空表。
880
+ */
881
+ descriptor(): PlatformAdapterDescriptor;
882
+ /**
883
+ * Side-effect-free reachability probe. Used by the connection status indicator
884
+ * and the auto-poller. Implementations that have no out-of-band ping should
885
+ * return `fail("unsupported", …)` so the UI can render "probe unsupported".
886
+ */
887
+ probe(connection: Connection): Promise<ProbeResult>;
888
+ /**
889
+ * 登记即启动 —— 登记表在适配器进表之后调一次(ADR-0024 决策 3)。有状态的连接器在这里
890
+ * 按 `ctx.connections()` 建连 / 起监听,再用 `ctx.onConnectionsChanged` 订连接配置的变动、
891
+ * 变了就对一次账。对账必须幂等、够便宜(没变就是空操作),且**不许写配置、不许触发探测**
892
+ * (会经 `config-changed` 绕回来)。无状态的实现留空。
893
+ *
894
+ * 抛了(或交回的 Promise 拒了)算登记失败:登记表把键与表里那一项撤掉,再把错原样交回去
895
+ * (交回 Promise 的以拒绝的形式),登记成功的通知也不会发。异步初始化直接写 `async start()`。
896
+ */
897
+ start(ctx: PlatformAdapterContext): void | Promise<void>;
898
+ /**
899
+ * 注销即停止 —— 登记表在把适配器摘出表之后调一次。关掉所有连接 / 监听 / 定时器,幂等。
900
+ * 回 Promise 时登记表不等它,失败由登记表记一行 warn。
901
+ */
902
+ stop(): void | Promise<void>;
903
+ /**
904
+ * Return whether this adapter can deliver to `destination` over `connection` right now.
905
+ * 连接 / 目标的启停与「目标属哪个平台」由派发器查过了,这里只答**运行期**的事:配置齐不齐、
906
+ * 这个去向的种类自己收不收。
907
+ */
908
+ isAvailable(connection: Connection, destination: DestinationRef): boolean;
909
+ /** Deliver `payload` to `destination` over `connection`. 群还是私聊只看 `destination.scope`。 */
910
+ send(connection: Connection, destination: DestinationRef, payload: NotificationPayload): Promise<DeliveryResult>;
911
+ /**
912
+ * 这条连接的能力(三态;探测结果读缓存,同步读、不打网络)。内置适配器都实现;没实现的
913
+ * (老的拓展适配器)各项按「还不知道」算,怎么对待「还不知道」见 internal 的
914
+ * `shouldSendAtAll` / `canReceiveReply` / `listsForLinkPreview`。
915
+ */
916
+ capabilities?(connection: Connection): ConnectionCapabilities;
917
+ /** 主动探一次能力,结果进缓存。连上时、健康探测时、用之前都可以叫;零副作用。 */
918
+ probeCapabilities?(connection: Connection): Promise<ConnectionCapabilities>;
919
+ /**
920
+ * 这种连接的 `settings` 的校验。宿主拿它:保存时校验、把连接递给适配器之前先解一遍
921
+ * (**递到适配器手上的连接,`settings` 一律是它解过的输出**,适配器只认键、不再自己解)、
922
+ * 找密钥标记。
923
+ */
924
+ readonly settingsSchema: ZodType;
925
+ /**
926
+ * 列新建连接时供挑的候选(ADR-0024 决策 4),必备。内置三个交写死的模板候选(平台描述从平台
927
+ * 注册表现取、设置是默认值),拓展(桥)交在线的 bot;新建连接时宿主只认这里列出来的平台。
928
+ */
929
+ listConnectionCandidates(signal: AbortSignal): Promise<readonly ConnectionCandidate[]>;
930
+ /**
931
+ * 列这条连接上可挑的地址。只查 `scope` 那一种 —— 有的种类是内存里现成的,有的要现去平台拉,
932
+ * 调用方要哪种就只付哪种的代价。不实现 = 这种连接没有可列的地址,面板让主人手填。
933
+ * 不对拓展开放(ADR-0024 决策 11):拓展的 `adapter` 类型把它排除掉。
934
+ */
935
+ listAddressCandidates?(connection: Connection, scope: PushTargetScope, signal: AbortSignal): Promise<Result<{
936
+ candidates: readonly AddressCandidate[];
937
+ }>>;
938
+ /**
939
+ * 扫码之类的建连接流程(ADR-0024 决策 3)。不实现 = 这种连接只能手填。
940
+ * 不对拓展开放(ADR-0024 决策 11):拓展的 `adapter` 类型把它排除掉。
941
+ */
942
+ connectionAuth?: ConnectionAuth;
943
+ }
944
+ /**
945
+ * 一个平台适配器给面板的描述(ADR-0012 决策 33 / 46 那三格外观,加要主人填的那几栏):
946
+ * 推送目标页照它画新建连接那一排的名字、连接卡上那张脸、以及连接配置项。中立概念:拓展写在清单里,
947
+ * 内置适配器经 {@link PlatformAdapter.descriptor} 交同一种(ADR-0024 决策 3)。
948
+ *
949
+ * **就这几格**:作用域、地址名词、能不能 @全体这些都是**bot 所在平台**的事(一条拓展连接
950
+ * 就是一个借来的 bot,决策 45),从 bot 报的 `platform` 查注册表,不从这儿来。
951
+ *
952
+ * 拓展写在清单里,拓展停着也有(ADR-0019 决策 41)。**有它不等于拓展在场** —— 要在场的看它的运行状态。
953
+ */
954
+ interface PlatformAdapterDescriptor {
955
+ /** 全名:新建连接那一排、「经 xxx 借来的」那句。 */
956
+ label: string;
957
+ /** 短名:卡片上那个方章。 */
958
+ shortLabel: string;
959
+ /** 方章的底色,hex。 */
960
+ color: string;
961
+ /** 平台图标:图片 data URL(面板第 4 期按描述画时当 `<img>` 画,这一版还不读)。 */
962
+ icon?: string;
963
+ /** 要主人填的连接配置项;不需要配置的适配器就是空表。 */
964
+ settingsFields: readonly ConnectionSettingsField[];
965
+ /** 内置扫码入口的说明;拓展清单本版不开放。 */
966
+ auth?: {
967
+ description: string;
968
+ warning?: string;
969
+ experimental?: boolean;
970
+ };
971
+ }
972
+ /**
973
+ * 扫码建连接的三步。三个方法都不依赖 `this`(同文件头那条承重的规矩),都不许抛。
974
+ *
975
+ * 与订阅侧 `SourceAuth.state()` 同名不同形:这边异步、按任务号、回结果形状(要出网,会失败),
976
+ * 那边同步、无参、直接回 `AuthState`。同名是有意的(都是「读此刻的状态」),别为了对齐改成对方的样子。
977
+ */
978
+ interface ConnectionAuth {
979
+ /** 发起一次:开一个任务,回任务号(适配器自己发)、此刻的状态与建议的问询间隔(秒)。 */
980
+ begin(signal: AbortSignal): Promise<Result<{
981
+ taskId: string;
982
+ state: AuthState;
983
+ pollIntervalSeconds: number;
984
+ }>>;
985
+ /** 读这个任务此刻的状态。可反复读;回包不带草稿、不清草稿。 */
986
+ state(taskId: string, signal: AbortSignal): Promise<Result<{
987
+ state: AuthState;
988
+ }>>;
989
+ /**
990
+ * 取走这次认证拿到的那几格设置(键是适配器自己 `settingsSchema` 里的键)。
991
+ * 只在状态到了 `logged-in` 之后成功一次,取走即清;之后这个任务号找不到。
992
+ */
993
+ takeDraft(taskId: string): Promise<Result<{
994
+ settings: Record<string, unknown>;
995
+ }>>;
996
+ }
997
+ /** 挑地址时的一个候选(ADR-0024 决策 3 的 listAddressCandidates)。 */
998
+ interface AddressCandidate {
999
+ /** 填进目标 `address` 的那个值。 */
1000
+ address: string;
1001
+ /** 给人认的名字;平台给不出就没有(QQ 的群事件不带群名,只有触发者的名字可作提示)。 */
1002
+ name?: string;
1003
+ /** 上级地址,填进目标的 `parentAddress`(QQ 频道:子频道所属的频道服务器 id)。 */
1004
+ parentAddress?: string;
1005
+ /** 上级的名字,面板拿它给候选分组。 */
1006
+ parentName?: string;
1007
+ }
1008
+ /**
1009
+ * 新建连接时供挑的一个候选(ADR-0024 决策 3、4)。平台固定的适配器交写死的模板候选(OneBot 一个、
1010
+ * QQ 官方一个、webhook 四个):`settings` 是默认值、不带 `boundConnectionId`、可以反复用;
1011
+ * 桥交在线的 bot。挑中之后宿主把 `platform` 去掉 `platform` 那格存成连接的 `platformSnapshot`,
1012
+ * `settings` 原样落进连接。
1013
+ */
1014
+ interface ConnectionCandidate {
1015
+ /** 给人认的名字。 */
1016
+ name: string;
1017
+ /** 候选连接所在平台的描述;宿主新建连接时把它去掉 `platform` 的部分存成 `platformSnapshot`。 */
1018
+ platform: PlatformDescriptor;
1019
+ /** 落进连接的 `settings`;宿主看不懂它,按适配器自己的 `settingsSchema` 校验后原样存。 */
1020
+ settings: unknown;
1021
+ selfId?: string;
1022
+ /** 经由谁借来的(桥:那条接入的名字)—— 两条桥各驮一个同名 bot 时分得开。 */
1023
+ via?: string;
1024
+ /** 已被哪条连接用上 —— 面板标「已加过」。模板候选没有这一格。 */
1025
+ boundConnectionId?: string;
1026
+ }
1027
+ /**
1028
+ * 适配器 `start` 时拿到的上下文:集成上下文,加上「自己的连接」的两样 —— 与拓展的推送源把手同形。
1029
+ */
1030
+ interface PlatformAdapterContext extends IntegrationContext {
1031
+ /**
1032
+ * 归这个适配器管的连接(按 `adapterKey` 认领),**现读**。别缓存 —— 缓存与真相会漂,症状是
1033
+ * 「面板上停用了它还连着」;变更通知是用来做动作的,不是用来更新缓存的。
1034
+ */
1035
+ connections(): readonly Connection[];
1036
+ /** 连接配置动过了(增删改都算),叫一声。适配器停下时自动摘掉。 */
1037
+ onConnectionsChanged(fn: () => void): Disposable;
1038
+ /**
1039
+ * 在集成层的上报上多一格 `connectionId`:带了就是关于这条连接的问题(宿主核它是不是这个适配器的连接,
1040
+ * 不是、或不存在的被拒);不带就是适配器自己的问题。连接删了,关于它的问题宿主跟着清。
1041
+ */
1042
+ reportProblem(problem: {
1043
+ connectionId?: string;
1044
+ code: string;
1045
+ message: string;
1046
+ notify?: boolean;
1047
+ recoveryMessage?: string;
1048
+ }): void;
1049
+ /**
1050
+ * 清掉一个问题(同 `reportProblem` 的对象规矩);语义同集成层的 `resolveProblem`。
1051
+ * 带 `connectionId` 时,连接已删的,清是空操作、不算被拒(宿主删连接时已经清过它名下的问题)。
1052
+ */
1053
+ resolveProblem(problem: {
1054
+ connectionId?: string;
1055
+ code: string;
1056
+ notify?: boolean;
1057
+ }): void;
1058
+ /**
1059
+ * 把收到的私聊 / 群消息交给宿主(ADR-0024 决策 12)。适配器只报**是哪条连接**收到的(`connectionId`),
1060
+ * 平台不由适配器自报:宿主核这条连接是不是这个适配器的(按 `adapterKey`,不是、或不存在的丢掉并记一行),
1061
+ * 平台取连接上那一格,补成完整的 {@link InboundMeta} 再交下一层。两个成员都在 —— 没人接的那一路宿主静默丢。
1062
+ */
1063
+ inbound: {
1064
+ private(msg: InboundPrivateMessage, meta: Pick<InboundMeta, "connectionId">): void;
1065
+ group(msg: InboundGroupMessage, meta: Pick<InboundMeta, "connectionId">): void;
1066
+ };
1067
+ }
1068
+ /**
1069
+ * 入站消息 —— 各平台事件帧到「谁在哪说了什么」的收口。**归一化在 adapter 里做**:
1070
+ * 消费者(指令分发、链接解析)只认下面两个形状,谁也不该再去碰平台的原始帧。两个
1071
+ * adapter 交出来的是同一个形状,接线层才不用替每个平台各写一份映射。
1072
+ */
1073
+ /** 收到这条消息的那条连接 —— 「回到消息来的那个群」得知道用哪条连接的凭据发。 */
1074
+ interface InboundMeta {
1075
+ connectionId: string;
1076
+ /**
1077
+ * 收到这条消息的平台 —— **宿主按连接补上的**,适配器不自报(适配器交入站时只带 `connectionId`)。
1078
+ *
1079
+ * 主人身份的比对要按平台走:OneBot 的 QQ 号与官机的 C2C openid 是两个命名空间,
1080
+ * 光比字符串就是在赌两边永远不撞。这一格让那句「绝不能跨平台比对」第一次真的可校验。
1081
+ */
1082
+ platform: string;
1083
+ }
1084
+ /** 一条私聊。指令分发器只认这个;`address` 在 OneBot 是 QQ 号,在官机是 C2C 用户 openid。 */
1085
+ interface InboundPrivateMessage {
1086
+ address: string;
1087
+ text: string;
1088
+ }
1089
+ /** 一条群消息。链接解析只认这个;`address` 在 OneBot 是群号,在官机是群 openid。 */
1090
+ interface InboundGroupMessage {
1091
+ address: string;
1092
+ /** 发言者。官机给的是群成员域的 openid,与 C2C 用户 openid 不是一个命名空间,别拿去比对主人。 */
1093
+ senderId: string;
1094
+ /** 收到这条消息的 bot 自己的号(OneBot 有);与 senderId 相同就是自己发的。 */
1095
+ selfId?: string;
1096
+ /** 用户敲的正文 —— 就是正文,不掺别的。 */
1097
+ text: string;
1098
+ /**
1099
+ * 分享卡里的链接候选,按出现顺序。与正文分开放:下一个群消息消费者拿到的 `text` 得还是
1100
+ * 「用户敲的那句话」,而不是被接了一串卡片链接的东西。正文里的链接不在这儿,由消费者自己从 `text` 挑。
1101
+ */
1102
+ sharedLinks: {
1103
+ url: string;
1104
+ /**
1105
+ * 这条链接来自哪种卡。`"nativeShare"` 是平台自己的原生分享卡(QQ 小程序卡,B 站 App
1106
+ * 「分享到 QQ」发出的那种):群里已经有一张能点开播放的卡了,链接解析再回一张(不管是图片卡
1107
+ * 还是小程序卡)都是重复 —— 主人 2026-09-07 拍板一律不回。别的卡(json / xml 结构化
1108
+ * 消息)记 `"card"`。
1109
+ */
1110
+ kind: "card" | "nativeShare";
1111
+ }[];
1112
+ }
1113
+ /** 通用资源释放接口;adapter 提供,业务持有,dispose 时统一调用。 */
1114
+ interface Disposable {
1115
+ dispose(): void;
1116
+ }
1117
+ /** 业务核心从宿主获取的 logger 抽象(独立端包 pino)。 */
1118
+ interface Logger {
1119
+ info(msg: string, ...args: unknown[]): void;
1120
+ warn(msg: string, ...args: unknown[]): void;
1121
+ error(msg: string, ...args: unknown[]): void;
1122
+ debug(msg: string, ...args: unknown[]): void;
1123
+ }
1124
+ /** 一个集成读自己设置的把手:交一份 zod 进来,拿回它。 */
1125
+ interface SettingsReader<T> {
1126
+ /**
1127
+ * 此刻这一份。读得懂回过了那份 zod 的值;读不懂回 `invalid`,`issues` 里是逐条原因
1128
+ * (整个设置文件读不懂时只有一条、不带 `path`)。**不抛**,`start` 里与运行中都一样。
1129
+ */
1130
+ get(): Result<{
1131
+ settings: T;
1132
+ }>;
1133
+ /** 这一份「变了」才叫:值变了,或读得懂与读不懂之间翻了。别的集成的设置动了不叫。 */
1134
+ onChange(fn: () => void): Disposable;
1135
+ }
1136
+ /**
1137
+ * 每个集成(拓展、内置集成)拿到的那一面:日志、停下信号、收尾钩子、两份小存储、日志打码登记、问题上报、
1138
+ * 读自己的设置。成员后面各片还会往上加。
1139
+ * 宿主握着的另一面(收回它的把手)住服务端,集成拿不到。
1140
+ */
1141
+ interface IntegrationContext {
1142
+ /** 整台时区的有效IANA名,每次现读。 */
1143
+ timezone(): string;
1144
+ /** 时区真变时叫;不补叫,停下时自动摘掉。 */
1145
+ onTimezoneChanged(fn: () => void): Disposable;
1146
+ readonly logger: Logger;
1147
+ /** 集成停下(停用、卸载、关停)时中止;在收尾钩子跑之前就已经中止。 */
1148
+ readonly signal: AbortSignal;
1149
+ /** 收尾钩子,后登记的先跑。停下之后再登记不生效,记一行。 */
1150
+ onDispose(fn: () => void | Promise<void>): void;
1151
+ /** 程序自己记的小状态:明文,不进备份。单键 64KB、整份 1MB;`http.` 开头的键归宿主。 */
1152
+ readonly state: KeyValueStore;
1153
+ /** 凭据:主密钥加密,只进完整备份。整份 256KB;`http.` 开头的键归宿主。 */
1154
+ readonly secrets: KeyValueStore;
1155
+ /**
1156
+ * 登记一个**还没存进 `secrets`** 的临时凭据(比如扫码刚拿到的令牌),日志按值把它遮成 `***`。
1157
+ * 一次登记一个,只增不减,直到集成停下(宿主那时撤掉);连续登记不会互相冲掉。存进 `secrets` 的值、
1158
+ * cookie 罐里的每条 cookie 一到就自动登记,不用再登记。少于 8 个字符的值不遮;空串、不是字符串的忽略;
1159
+ * 停下之后再登记不生效。
1160
+ */
1161
+ redact(value: string): void;
1162
+ /**
1163
+ * 报一个这个集成自己的问题(对面连不上……)。句子写平实、只说事:不称呼主人、不自称女仆、不写宿主的界面
1164
+ * 与操作;私聊时宿主按口吻补完整。有登录口的来源不要报登录,宿主看登录状态报与清。
1165
+ * `code` 是 snake 风格,同一个集成下同一个
1166
+ * code 只有一条,再报只换文案(与 `notify`、`recoveryMessage`)。`notify: true` 请核心私聊主人一次。
1167
+ * 没有返回值;形状不对(含空白的 `message` / `recoveryMessage`)、集成已停下的上报被丢弃。
1168
+ * 平台的数字码写进 `message`,不占 `code`。
1169
+ *
1170
+ * `recoveryMessage`:这件事清掉、且当初真私聊过时核心发的那一句;不给就用宿主带名字的通用说法。
1171
+ * 集成停下时它报的全清(核心清的,不补「已恢复」)。
1172
+ *
1173
+ * ⚠️ 方法写法(不是属性函数):子层(来源、适配器)同名方法多带一格对象,靠的是方法参数的双变。
1174
+ */
1175
+ reportProblem(problem: {
1176
+ code: string;
1177
+ message: string;
1178
+ notify?: boolean;
1179
+ recoveryMessage?: string;
1180
+ }): void;
1181
+ /**
1182
+ * 清掉自己报的一个问题。清掉时核心对当初私聊过的补一句「已恢复」;`notify: false` = 这次不是修好了、
1183
+ * 只是不再适用,不补。表里没有这一条什么都不做。
1184
+ */
1185
+ resolveProblem(problem: {
1186
+ code: string;
1187
+ notify?: boolean;
1188
+ }): void;
1189
+ /**
1190
+ * 读这个集成自己的设置(`config/settings/<集成键>.json` 那一段)。可以交多份 zod,各读各的格(zod 的
1191
+ * 对象默认剥掉不认识的键);没设过的拿空对象过规则:过得了是成功并带默认值,过不了回 `not_configured`。
1192
+ * 把手随集成停下自动收掉(来源与适配器的上下文里,订阅还随来源 / 适配器停下摘掉),不必在 `stop()` 里记得摘。
1193
+ */
1194
+ settings<T>(schema: ZodType<T>): SettingsReader<T>;
1195
+ /**
1196
+ * 这个集成自己的请求客户端:身份与 cookie 罐都是它自己的(宿主管着存与升),集成之间互不相干。
1197
+ * `fetch` 非 2xx 不抛、失败回结果形状;`websocket` 随集成停下自动关(`fetch` 不跟着断,在途的请求由调用方的
1198
+ * `signal` 管)。不拦内网(局域网里的 RSSHub 要连得上),拦内网只在 {@link IntegrationContext.fetchImage} 上。
1199
+ */
1200
+ readonly http: HttpClient;
1201
+ /**
1202
+ * 把一张远端的图抓进图库,回引用。走 {@link IntegrationContext.http} 同一个客户端(同一套身份与 cookie),
1203
+ * 平台要的头(Referer、签名)由这次传。每一跳都拦内网;单张 8 MiB、按内容嗅探(只认 png / jpg / gif / webp)。
1204
+ * 失败的码:`invalid`(地址不对、内网、太大、不是图、其余 4xx)、`unauthorized`(401 / 403)、`not_found`(404 / 410)、
1205
+ * `rate_limited`(429)、`timeout`、`unavailable`(连不上、5xx、磁盘写失败)、`indeterminate`(调用方中止)。
1206
+ * 只攥在集成自己手里、没交给宿主的引用,过了 24 小时的宽限期不保。
1207
+ */
1208
+ fetchImage(url: string, options?: {
1209
+ headers?: Record<string, string>;
1210
+ signal?: AbortSignal;
1211
+ }): Promise<Result<{
1212
+ ref: ImageRef;
1213
+ }>>;
1214
+ /** 手里已经是字节的图存进图库,回引用。同一套嗅探与 8 MiB;留存的规矩同 {@link IntegrationContext.fetchImage}。 */
1215
+ storeImage(bytes: Uint8Array, options?: {
1216
+ signal?: AbortSignal;
1217
+ }): Promise<Result<{
1218
+ ref: ImageRef;
1219
+ }>>;
1220
+ }
1221
+ /** 单段消息载荷类型。composite 中的 segment 之一。 */
1222
+ type PayloadSegment = {
1223
+ kind: "text";
1224
+ text: string;
1225
+ } | {
1226
+ kind: "image";
1227
+ buffer: Buffer;
1228
+ mime: string;
1229
+ } | {
1230
+ kind: "link";
1231
+ href: string;
1232
+ title?: string;
1233
+ } |
1234
+ /**
1235
+ * @全体成员 段。各 platform adapter 自行翻译:
1236
+ * - OneBot v11: `{ type: "at", data: { qq: "all" } }`(真实 @ 全体)
1237
+ * - Webhook: 通用 JSON 里写成 `{ type: "at-all" }`(线上的名字不随内部改),由接收方自行处理
1238
+ * - Web Dashboard: 渲染成可视化 "@全体" 文本(非真实 @)
1239
+ *
1240
+ * **它是一条自己的消息,不是本体的修饰**(ADR-0016):`PushRouter` 把这一段单独包成
1241
+ * 一条 composite payload,排在本体之前发出,落历史时 `role: "extra"` —— 与下播的词云 /
1242
+ * AI 总结同类,都是挂在某把主特性下面的附加项。发不发由「全局 + per-UP 合并后的
1243
+ * `features.extras.atAll<Scope>`」定,某个目标要不要另说则看订阅上的三态表
1244
+ * `extraTargets.atAll<Scope>[targetId]`。
1245
+ */
1246
+ {
1247
+ kind: "at-all";
1248
+ };
1249
+ /**
1250
+ * 原生分享的中立描述(一张「点开进应用某一页」的分享卡):链接解析器只说「分享什么」,
1251
+ * 签名由适配器去签。`LinkPreview.nativeShare` 与载荷的 `native-share` 一支共用这一个类型。
1252
+ */
1253
+ interface NativeShare {
1254
+ /** 小程序 / 应用的标识,适配器按它挑怎么签。 */
1255
+ appId: string;
1256
+ title: string;
1257
+ description: string;
1258
+ imageUrl: string;
1259
+ /** 应用内的页面路径。 */
1260
+ pagePath: string;
1261
+ /** 不支持原生分享的客户端点开的网页地址。 */
1262
+ webUrl: string;
1263
+ iconUrl?: string;
1264
+ }
1265
+ /**
1266
+ * 平台中立的消息载荷。Adapter 翻译为各平台原生格式:
1267
+ * - OneBot: text/image → message segment 数组;composite → 段拼接
1268
+ * - Webhook: 序列化为 JSON
1269
+ */
1270
+ type NotificationPayload = {
1271
+ kind: "text";
1272
+ text: string;
1273
+ } | {
1274
+ kind: "image";
1275
+ image: {
1276
+ buffer: Buffer;
1277
+ mime: string;
1278
+ };
1279
+ caption?: string;
1280
+ } | {
1281
+ kind: "composite";
1282
+ segments: PayloadSegment[];
1283
+ } |
1284
+ /**
1285
+ * 图集 payload(典型来源:动态图集 / 多张大图)。适配器照 `images[].url` 发(`ref` 只是带着);
1286
+ * 尺寸来自来源的图集元数据,仅 QQ 官方原生 markdown 多图(`![文字 #宽px #高px](url)`)需要它来
1287
+ * 正常渲染,缺了不影响别的平台。`mergeForward` 决定 adapter 用哪种
1288
+ * 平台原生形式投递:
1289
+ * - `true` —— 走 OneBot `send_group_forward_msg`,
1290
+ * 渲染成「聊天记录」卡片。视觉好但走长消息通道(NapCat 的 `SsoSendLongMsg`
1291
+ * trpc 在某些部署上不稳),失败时所有图都丢。
1292
+ * - `false` —— 走 OneBot `send_group_msg` 多 image segment。
1293
+ * 普通多图。稳但 N+ 张大图会一排刷屏。
1294
+ * 默认值由设置里的 `imageGroup.mergeForward`(全局与逐订阅覆盖)决定。
1295
+ */
1296
+ {
1297
+ kind: "image-group";
1298
+ images: PostImage[];
1299
+ mergeForward: boolean;
1300
+ } |
1301
+ /**
1302
+ * 原生分享:链接解析器交的中立描述原样装进来(见 {@link NativeShare})。怎么签、签不签得了
1303
+ * 归适配器自己挑 —— 认识这个 `appId` 的适配器去签,不认识的、或这条连接签不了的,回
1304
+ * `ok: false`,由链接解析那头回落图片卡。
1305
+ *
1306
+ * `pagePath` 是**应用里的页面路径**,`webUrl` 是网页链接。两个都要:签名协议里页面路径决定
1307
+ * 点开落在哪一页,网页链接给不支持的客户端;把网址填进页面路径签出来的卡点开是「页面不存在」
1308
+ * (2026-09-07 群友反馈那次)。不能原生分享的平台降级成文字时只用 `webUrl`。
1309
+ */
1310
+ ({
1311
+ kind: "native-share";
1312
+ } & NativeShare);
1313
+ /**
1314
+ * 一次投递的结果(ADR-0026):送达了是 `{ ok: true, latencyMs }`,没送达是 `Failure`。
1315
+ * 耗时只在成功那一支 —— 没真发出去的失败不带一个假的 `0`。
1316
+ *
1317
+ * `isSynthetic`:这条投递**没有真的出网**(目前只有 devtools 的推送截流会这么标)。结果照样往上回,
1318
+ * 好让调用链跑完;但它不携带任何「目标通不通」的信息 —— 拿它去翻 `target.reachability`
1319
+ * 就是凭空把一个发不出去的目标标成绿的,而且会落盘、活得比截流本身还久。
1320
+ * 读之前先过 {@link isReachabilityEvidence}。
1321
+ */
1322
+ type DeliveryResult = Result<{
1323
+ latencyMs: number;
1324
+ isSynthetic?: true;
1325
+ }>;
1326
+ /**
1327
+ * 一项能力的三态 —— 支持 / 不支持 / 还不知道。**「还不知道」不是「不支持」**:前者是「试试看,可能行」,
1328
+ * 后者是结论;读它的地方各自决定「还不知道」时怎么办(见 `ConnectionCapabilities` 各格的注释),
1329
+ * 面板上两者也要分开显示。
1330
+ *
1331
+ * - `supported`:确认支持,`checkedAt` 是确认的时刻。
1332
+ * - `unsupported`:确认不支持,`reason` 给人看的一句话,`checkedAt` 是确认的时刻。
1333
+ * - `unknown`:还没探出来(没探过、连不上、对面没报),`reason` 可选。
1334
+ *
1335
+ * `checkedAt` 是**带时区的 ISO**;宿主交出来的一律是 `Z` 结尾的 UTC(`toISOString()` 的写法)。
1336
+ */
1337
+ type CapabilitySupport = {
1338
+ state: "supported";
1339
+ checkedAt: string;
1340
+ } | {
1341
+ state: "unsupported";
1342
+ reason: string;
1343
+ checkedAt: string;
1344
+ } | {
1345
+ state: "unknown";
1346
+ reason?: string;
1347
+ };
1348
+ /** 一条连接的能力快照,由这条连接的适配器回答。 */
1349
+ interface ConnectionCapabilities {
1350
+ /**
1351
+ * 能不能单发 @全体。派发器的 `supportsAtAll` 与订阅抽屉里的 @全体 开关读它;
1352
+ * 「还不知道」时**照发**(发错只是多一条消息)。
1353
+ */
1354
+ atAll: CapabilitySupport;
1355
+ /**
1356
+ * 主人在这条连接上回一句话,女仆收不收得到。锐评审批(要靠主人回复)与 devtools 的入站场景读它;
1357
+ * 「还不知道」时**审批不能开**(开错了整期草稿都会等到超时作废);
1358
+ * 链接解析设置列不列这个群也读它,「还不知道」时**照列**(今天对拓展连接一律列)。
1359
+ */
1360
+ inbound: CapabilitySupport;
1361
+ /**
1362
+ * 能不能发原生分享(平台自己的分享卡)。链接预览的门读它:发不了就回落图片;
1363
+ * 「还不知道」时门先探一次,探完仍未知按不能算。
1364
+ */
1365
+ nativeShare: CapabilitySupport;
1366
+ }
1367
+ /**
1368
+ * 订阅特性与附加项词表 —— 哪些事件能单独开关、每个附加项跟着谁走、出厂值是什么。
1369
+ *
1370
+ * 零依赖:只许 `import type`,值级 import 只能指向零依赖名单里的同伴。
1371
+ * 面板与 contract 经 `@bilibili-notify/internal/features` 取值。
1372
+ */
1373
+ /**
1374
+ * 全部可订阅的特性键 —— 每一把都是一类**能单独开关、能配路由**的推送。新增或删除会扩散到
1375
+ * FeatureFlags、SubscriptionRouting、Subscription.overrides。
1376
+ *
1377
+ * 附加项(@全体 / 词云 / AI 总结)不在这里:它们各自挂在某把主特性下面(见
1378
+ * {@link PUSH_EXTRAS}),跟着那把特性的开关与目标走,自己没有路由。
1379
+ */
1380
+ declare const FEATURE_KEYS: readonly ["post", "liveStart", "liveStreaming", "liveEnd", "membership", "superchat", "viewerChat", "viewerEnter"];
1381
+ type FeatureKey = (typeof FEATURE_KEYS)[number];
1382
+ /** 解析器交回的一份预览:一个作品,加「这是哪一个」的规范 id,可选的原生分享描述。 */
1383
+ interface LinkPreview {
1384
+ /** 要出卡的作品;核心照常出图卡、吃皮肤。 */
1385
+ post: Post;
1386
+ /** 同一个东西不论链接换了什么写法都一样的 id(带参数、移动端域名、短链……),冷却按它去重。 */
1387
+ canonicalId: string;
1388
+ /**
1389
+ * 原生分享卡的中立描述。有它、且发送的这条连接支持,才会回原生分享;没有或签不了就回图片。
1390
+ * 描述只说「分享什么」,签名由适配器去签(解析器不碰任何平台的签名接口)。
1391
+ */
1392
+ nativeShare?: NativeShare;
1393
+ }
1394
+ /** 一个平台的链接解析器。 */
1395
+ interface LinkResolver {
1396
+ /** 平台名(「B 站」),给日志与面板用。 */
1397
+ label: string;
1398
+ /** 这条网址归不归我。同步、不联网。 */
1399
+ matches(url: string): boolean;
1400
+ /** 查出这条网址的预览;失败回失败结果,不抛。`signal` 是进程关停的那个。 */
1401
+ resolve(url: string, signal: AbortSignal): Promise<Result<LinkPreview>>;
1402
+ }
1403
+ /**
1404
+ * 注入工具的**富返回值** —— 除了回灌给模型的文本,还能顺带收窄接下来的工具面。
1405
+ *
1406
+ * 直接返回字符串等价于 `{ text }`,绝大多数工具用不上这个形状。
1407
+ */
1408
+ interface AiToolResult {
1409
+ /** 回灌给模型的文本,与直接返回字符串等价。 */
1410
+ text: string;
1411
+ /**
1412
+ * **下一轮起**把工具表收窄到这些名字。
1413
+ *
1414
+ * 语义是**交集,只减不加**:名字不在当前工具表上就当没写,凭空长不出工具来。
1415
+ * 这条不是口味 —— 唯一的用户是「读取技能」那把工具,而技能正文是主人(或他从
1416
+ * 网上抄来的一份)写的**数据**;用户可写的数据永远不能扩大能力面。
1417
+ *
1418
+ * 想让某把工具在收窄之后仍然在场(比如这把工具自己),**把它的名字一并写进来**
1419
+ * —— generator 不为任何工具开后门。
1420
+ *
1421
+ * 收窄只活这一次请求:工具表随请求现造,下一条用户消息拿回完整的那份。
1422
+ */
1423
+ restrictTools?: readonly string[];
1424
+ /**
1425
+ * 要交给模型**看**的图(data URL 或公网地址)。
1426
+ *
1427
+ * tool 消息只收文字,所以图不跟着结果走:主模型看得见图,就在这一轮的工具结果后面
1428
+ * 补一条带图的 user 消息;配了看图副模型,就转成文字并进结果;两样都没有,就在结果
1429
+ * 后面说一句看不见。**哪条路由 generator 定** —— 看图配置在它手上,工具不必知道。
1430
+ * 看不见不算失败(ADR-0015 决策 19)。
1431
+ */
1432
+ images?: readonly string[];
1433
+ }
1434
+ /**
1435
+ * 调用方**注入**的额外工具 —— 挂在调用点上,不进 `@bilibili-notify/ai` 的 `TOOL_DEFINITIONS`。
1436
+ *
1437
+ * 那张表是三端共用的、且只读(见 `executeTool` 的文档与 read-only-tools-gate);
1438
+ * 而写能力只有**有权限门的那一端**才配拥有。所以口子开在调用点:注入者给定义 +
1439
+ * 执行器,generator 只管挂上与转发,不认识它的语义。目前唯一的注入者是独立端
1440
+ * dashboard 的聊天(cookie session 后面,只有主人本人)。
1441
+ *
1442
+ * `execute` 拿到的入参已被逐值 String 归一(见 `execToolCall`)—— 布尔到手是
1443
+ * `"true"` / `"false"`,数字是字符串,按字符串判。
1444
+ */
1445
+ interface AiTool {
1446
+ definition: {
1447
+ type: "function";
1448
+ function: {
1449
+ name: string;
1450
+ description?: string;
1451
+ parameters?: Record<string, unknown>;
1452
+ strict?: boolean | null;
1453
+ };
1454
+ };
1455
+ /** 给人看的名字 —— 聊天里那条「她正在查什么」小条上的字(必填:漏配就是界面上一个英文标识符)。 */
1456
+ label: string;
1457
+ /**
1458
+ * 小条上补哪一格入参。`keys` 是候选参数名,按顺序取第一个有值的;`format` 只翻那一格的值
1459
+ * (卡种 `live` → 「直播卡」),不给就原样显示。不给 `labelArg` = 不补。
1460
+ */
1461
+ labelArg?: {
1462
+ keys: readonly string[];
1463
+ format?: (value: string) => string;
1464
+ };
1465
+ /**
1466
+ * `onProgress` 是**给慢工具的活口**:工具轮不产生正文,一趟几分钟的活儿在界面上
1467
+ * 跟卡死长得一模一样。报的是「已经吐了多少字符」这种粗粒度进度 —— 别把工具的
1468
+ * 中间产物往里塞,那条路会一路流到界面上。不报也行,只是主人得干等。
1469
+ */
1470
+ execute: (args: Record<string, string>, onProgress?: (chars: number) => void) => Promise<Result<AiToolResult>>;
1471
+ }
1472
+ /**
1473
+ * 一条女仆技能的全部内容(主人盘上的 `SKILL.md`、内置的、提供方带来的都是这个形状)。
1474
+ * `builtin` 之类的身份由技能库另行标注,不属于技能本身。
1475
+ */
1476
+ interface MaidSkill {
1477
+ /** kebab-case,既是目录名也是斜杠命令。提供方交的是本名,登记表补上来源的命名空间。 */
1478
+ name: string;
1479
+ /** 一句话说清它干什么 —— 模型靠它决定要不要自选这条。 */
1480
+ description: string;
1481
+ /**
1482
+ * 允许用的工具名**子集**;`undefined` = 不限(用这场对话本来的工具面)。提供方的工具写全名。
1483
+ *
1484
+ * **只减不加**(ADR 决策 11):用户可写的数据永远不能扩大工具面。所以这里给出
1485
+ * 的名字只用来做交集,写一个不存在的工具名不会凭空长出一把工具来。
1486
+ */
1487
+ allowedTools?: string[];
1488
+ /** 退出模型自选,只留斜杠命令这条路。 */
1489
+ disableModelInvocation: boolean;
1490
+ /** frontmatter 之后的正文,首尾空白已剥。 */
1491
+ body: string;
1492
+ }
1493
+ /**
1494
+ * 来源交的一组只读工具:在自己的 `start(ctx)` 里经 `ctx.registerAiToolProvider` 登记。
1495
+ *
1496
+ * 每把工具的 `definition.function.name` 是提供方自己的本名;宿主统一加命名空间,
1497
+ * 模型看到的全名是 `<命名空间>__<本名>`。
1498
+ */
1499
+ interface AiToolProvider {
1500
+ readOnly: readonly AiTool[];
1501
+ /** 提供方带来的技能,名字给本名,宿主加命名空间(`<来源键>-<本名>`);`allowedTools` 写工具全名。 */
1502
+ skills?: MaidSkill[];
1503
+ }
1504
+ /** 名单里的一条:只认人、不带订阅 id。 */
1505
+ interface SourceSubscriptionView {
1506
+ externalId: string;
1507
+ /** 这个人开着的特性(只看开关,不看有没有目标)。 */
1508
+ features: ReadonlySet<FeatureKey>;
1509
+ /** 宿主按 {@link needsLiveMonitor} 算好:这个人有没有哪条启用中的订阅要监听直播间。 */
1510
+ monitorsLive: boolean;
1511
+ }
1512
+ interface SourceContext extends IntegrationContext {
1513
+ /** 名单,现读:只列启用中的;同一个人遗留的重复订阅合成一条、features 取并集。别缓存。 */
1514
+ subscriptions(): readonly SourceSubscriptionView[];
1515
+ /** 名单可能变了就叫一声(不保证真变了);要做事自己对比新旧名单。来源停下时自动摘掉。 */
1516
+ onSubscriptionsChanged(fn: () => void): Disposable;
1517
+ /** 交一条作品。没有返回值;判新、去重、限流归来源。 */
1518
+ reportPost(externalId: string, report: PostReport): void;
1519
+ /**
1520
+ * 交一条直播信号(开播、直播状态、下播),发生了就报。没有返回值;宿主按身份展开成这个人名下每一条订阅的一份,
1521
+ * 判场次、断流接续、出卡、推送都归核心。图一律先 `storeImage` 存进图库再带引用。时刻写 ISO;`startedAt` /
1522
+ * `endedAt` 解析不出、下播没带 `endedAt`、来源已停下的上报被丢弃并记错误。
1523
+ */
1524
+ reportLive(externalId: string, report: LiveSignalReport): void;
1525
+ /**
1526
+ * 交一条观众互动(特别关注名单上的人发了弹幕、进了场……)。没有返回值;宿主按身份展开成这个人名下每一条订阅
1527
+ * 的一份,名单、特性开关、文案都按那条订阅现折的设置判,来源只管如实报「谁说了什么、谁进场了」。观众的 `id`
1528
+ * 是名单比对用的,要和名单里写的同一种 id。来源已停下的上报被丢弃并记错误。
1529
+ */
1530
+ reportLiveInteraction(externalId: string, report: LiveInteractionReport): void;
1531
+ /**
1532
+ * 报一个人的资料(名字、头像、简介、粉丝数、粉丝团名),变了或刚拿到就报。没有返回值;宿主按身份展开成这个人名下
1533
+ * **启用中**的每一条订阅(停用的不收),写进资料缓存、叫面板跟着变、粉丝数记进粉丝时序。头像一律先 `storeImage`
1534
+ * 存进图库再带引用。没给的格沿用缓存里原来的(名字没给又没旧值才是空)。来源已停下的上报被丢弃并记错误。
1535
+ */
1536
+ reportProfile(externalId: string, report: CreatorProfileReport): void;
1537
+ /**
1538
+ * 报一个问题(某个人不再监听了……)。句子写平实、只说事:不称呼主人、不自称女仆、不写宿主的界面与操作;
1539
+ * 私聊时宿主按口吻补完整。有登录口的来源不要报登录,宿主看登录状态报与清。
1540
+ * 不带 `externalId` 是来源自己的问题;带了由宿主换成
1541
+ * 这个人名下的每一条订阅。`code` 是 snake 风格,同一个对象下同一个 code 只有一条,再报只换文案。
1542
+ * `notify: true` 请核心私聊主人一次。没有返回值;形状不对(含空白的 `message` / `recoveryMessage`)、
1543
+ * 来源已停下的上报被丢弃。
1544
+ *
1545
+ * `recoveryMessage`:这件事清掉、且当初真私聊过时核心发的那一句(发的是私聊出去那一刻的那句);
1546
+ * 不给就用宿主带来源名的通用说法(接当初私聊的原文)。
1547
+ */
1548
+ reportProblem(problem: {
1549
+ externalId?: string;
1550
+ code: string;
1551
+ message: string;
1552
+ notify?: boolean;
1553
+ recoveryMessage?: string;
1554
+ }): void;
1555
+ /**
1556
+ * 清掉一个问题(同 `reportProblem` 的对象规矩)。清掉时核心对私聊过的补一句「已恢复」;
1557
+ * `notify: false` = 这次不是修好了、只是不再适用,不补。没有这一条什么都不做。
1558
+ */
1559
+ resolveProblem(problem: {
1560
+ externalId?: string;
1561
+ code: string;
1562
+ notify?: boolean;
1563
+ }): void;
1564
+ /**
1565
+ * 登记这个来源的链接解析器(群里贴链接时核心问它认不认)。在自己的 `start(ctx)` 里登;键就是这个来源
1566
+ * 的键,不用来源自己给。来源停下时宿主自动撤掉,不必在 `stop()` 里记得摘。来源已停下之后再登不生效
1567
+ * (交回一个什么都不做的把手,与「来源已停下的上报被丢弃」同一个待遇)。同一个来源登第二个会抛
1568
+ * (一个键一个主人);自己撤了之后可以重登。
1569
+ */
1570
+ registerLinkResolver(resolver: LinkResolver): Disposable;
1571
+ /**
1572
+ * 登记这个来源的 AI 工具提供方。在自己的 `start(ctx)` 里登;键就是这个来源的键,不用来源自己给。
1573
+ * 工具名是提供方自己的本名,宿主统一加命名空间,模型看到的是 `<命名空间>__<本名>`(命名空间由
1574
+ * 来源键换成工具名允许的字符而来,所以不会和核心工具或别家的撞);本名不合 `[A-Za-z0-9_-]`、
1575
+ * 同一组里重名、全名超过 64 个字符、或命名空间与别家相撞时抛。来源停下时宿主自动撤掉,
1576
+ * 不必在 `stop()` 里记得摘。来源已停下
1577
+ * 之后再登不生效(交回一个什么都不做的把手)。同一个来源登第二个会抛(一个键一个主人);
1578
+ * 自己撤了之后可以重登。
1579
+ */
1580
+ registerAiToolProvider(provider: AiToolProvider): Disposable;
1581
+ }
1582
+ /** 来源此刻的健康状况:给 `status` 指令(以后还有健康卡)的一行字。 */
1583
+ interface SourceHealth {
1584
+ summary: string;
1585
+ }
1586
+ /**
1587
+ * 来源交的一份创作者资料(`fetchProfile` 交的就是它,字段照 `docs/1.0/data-model.md`)。核心把它写进资料缓存;
1588
+ * 没给的格沿用缓存里原来的。搜人的候选在它上面加一个 `externalId`。
1589
+ */
1590
+ interface CreatorProfileReport {
1591
+ /** 创作者的名字。 */
1592
+ name: string;
1593
+ /** 图库引用;来源先把平台头像抓进图库,再交引用。 */
1594
+ avatar?: ImageRef;
1595
+ /** 简介或签名。 */
1596
+ bio?: string;
1597
+ /** 粉丝数。 */
1598
+ followers?: number;
1599
+ /** 粉丝团名;只有有粉丝团的平台才给。 */
1600
+ fanClubName?: string;
1601
+ }
1602
+ /**
1603
+ * `searchCreators` 交的一个候选(最多 10 个)。`externalId` 就是选中后新建订阅用的外部 id;
1604
+ * 头像是图库引用(先 `ctx.fetchImage` 再交),没被订阅用上的由图库按引用清扫;面板的搜人口读回成 data URL。
1605
+ */
1606
+ interface CreatorCandidate extends CreatorProfileReport {
1607
+ externalId: string;
1608
+ }
1609
+ /** 中性的平台描述:名字就是平台名,目标按会话算、三种范围都给,地址叫法留空。每次造新的一份。 */
1610
+ export declare function neutralPlatformDescriptor(platform: string): PlatformDescriptor;
1611
+ /**
1612
+ * 面板左栏的五组。`web` 是浏览器里跑的那半,其余四组都在服务端。
1613
+ */
1614
+ type DevScenarioGroup = "event" | "state" | "timer" | "capture" | "web" | "ext";
1615
+ /**
1616
+ * 一个参数字段。七种,面板照 `kind` 画控件:
1617
+ *
1618
+ * - `sub` / `target` / `connection` —— 从站内既有列表里挑一个(订阅 / 推送目标 / 连接),
1619
+ * 值是它们的 id。**只给核心的场景**:别家认领时用了就整包拒(ADR-0031 决策 2)。
1620
+ * - `creator` —— 交这个场景的那个来源名单里的一个人,值是他的 `externalId`;名单是来源 `ctx.subscriptions()`
1621
+ * 那一份(启用的、按人去重)。给了不在名单里的,宿主回 `invalid`。
1622
+ * - 上面四种**省略时的默认值住服务端**(场景自己挑,比如第一个启用的订阅),面板不猜。
1623
+ * - `number` / `enum` / `text` —— 自带默认值。
1624
+ */
1625
+ type DevParamField = {
1626
+ key: string;
1627
+ label: string;
1628
+ kind: "sub";
1629
+ } | {
1630
+ key: string;
1631
+ label: string;
1632
+ kind: "target";
1633
+ } | {
1634
+ key: string;
1635
+ label: string;
1636
+ kind: "connection";
1637
+ } | {
1638
+ key: string;
1639
+ label: string;
1640
+ kind: "creator";
1641
+ } | {
1642
+ key: string;
1643
+ label: string;
1644
+ kind: "number";
1645
+ default: number;
1646
+ min?: number;
1647
+ max?: number;
1648
+ } | {
1649
+ key: string;
1650
+ label: string;
1651
+ kind: "enum";
1652
+ options: ReadonlyArray<{
1653
+ value: string;
1654
+ label: string;
1655
+ }>;
1656
+ default: string;
1657
+ } | {
1658
+ key: string;
1659
+ label: string;
1660
+ kind: "text";
1661
+ default?: string;
1662
+ placeholder?: string;
1663
+ };
1664
+ interface DevScenarioDescriptor {
1665
+ /**
1666
+ * 全局唯一,两半共用一个命名空间(`core.update.state` / `bilibili.live.start` / `web.toast-flood`)。
1667
+ * 服务端那半在场景里写不带前缀的短名,`<提供方>.` 由宿主汇总时加。
1668
+ */
1669
+ id: string;
1670
+ /**
1671
+ * 交这个场景的那一家:`core`、来源键或拓展 id。宿主汇总时填,场景里写了也会被盖掉;面板那半的场景没有这一格。
1672
+ * 面板的 `creator` 选择器按它挑那个来源的人。
1673
+ */
1674
+ provider?: string;
1675
+ group: DevScenarioGroup;
1676
+ title: string;
1677
+ /** 一句说明:它会造成什么、以及要注意什么(「按重启会真的退出」)。 */
1678
+ desc?: string;
1679
+ params: DevParamField[];
1680
+ /** 在左下角药丸上占一个快捷位 —— 只给最常按的那几个。 */
1681
+ quick?: boolean;
1682
+ /**
1683
+ * 图标名(`@bilibili-notify/ui` 的 `IconName`),快捷位与卡片上用;不给就按分组取。
1684
+ * 同一组里有两个快捷位时必须给 —— 开播 / 下播都画成铃铛就分不清了。
1685
+ */
1686
+ icon?: string;
1687
+ }
1688
+ /** 面板交上来的参数:key → 值。缺的字段服务端按默认值补。 */
1689
+ type DevParamValues = Record<string, string | number>;
1690
+ /**
1691
+ * 当前生效的一条注入(假状态 / 截流 / 单点覆盖)。事件类场景跑完即走,不在这里;
1692
+ * 状态类的一直生效到收摊,或者到那条真动作把它顶掉。
1693
+ */
1694
+ interface DevInjection {
1695
+ /** 谁造的 —— 场景 id;收摊按它找。 */
1696
+ scenarioId: string;
1697
+ /** 一句人话,「当前生效」条上念的:「更新状态 → ready 0.99.0」。 */
1698
+ label: string;
1699
+ }
1700
+ interface DevScenarioDef extends DevScenarioDescriptor {
1701
+ run(params: DevParamValues): Result<{
1702
+ summary?: string;
1703
+ }> | Promise<Result<{
1704
+ summary?: string;
1705
+ }>>;
1706
+ /** 状态类场景:现在生效着的那条注入,没有就 null。事件类不写。 */
1707
+ active?(): DevInjection | null;
1708
+ /**
1709
+ * 状态类场景:收摊。可以是异步的 —— 有的收摊要写盘(静音),写失败得能一路冒到路由,
1710
+ * 而不是变成一个没人接的 promise 把进程带走。
1711
+ */
1712
+ reset?(): void | Promise<void>;
1713
+ }
1714
+ /**
1715
+ * 一家集成交给 devtools 的那一包场景。B 站是第一个实现者(`bilibili/devtools/`),拓展经
1716
+ * 清单 `contributes.devtools` 的开发入口交它(只在开发版)。
1717
+ *
1718
+ * 场景里写**不带前缀**的 id:提供方前缀由汇总那一处统一加(`providers.scenarios()`),
1719
+ * 各家不用知道自己叫什么、也冒充不了别家(ADR-0031 决策 2)。核心自己的场景也一样,前缀是 `core`。
1720
+ */
1721
+ interface DevtoolsProvider {
1722
+ scenarios: DevScenarioDef[];
1723
+ }
1724
+ /**
1725
+ * 拓展交给面板的「视图」—— v2 的 `ctx.publishView` 交的就是它(ADR-0019 决策 20 / 26–28,09-23
1726
+ * 决策 39 改过一轮)。
1727
+ *
1728
+ * 一组**封闭的积木**,由 BN 照着画;派生的东西由拓展算好交来,BN 不发明表达式语言。
1729
+ *
1730
+ * 🔴 这是同一包里 `ExtensionViewSchema` 的**手写镜像**,两份由 `view-shape-pin.ts`
1731
+ * **双向严格相等**地钉住 —— 这里多一个可选键,那边就过不了类型检查。
1732
+ *
1733
+ * 不合规矩时宿主**按块 / 按项**降级(决策 40):页上坏一块只换掉那一块,列表坏一项那张卡写「状态
1734
+ * 未知」,摘要坏了就不画。那些「坏了」的标记只有宿主加得了,不在这个类型里。
1735
+ */
1736
+ interface ExtensionView {
1737
+ /** 拓展列表页那一行。 */
1738
+ summary?: ExtensionViewSummary;
1739
+ /** 挂在头卡正文里的积木。 */
1740
+ page?: readonly ExtensionBlock[];
1741
+ /**
1742
+ * 列表设置项的 key → 项的 id → 那一项在卡上的样子。第一层的键必须是清单里声明过的**列表**
1743
+ * 设置项、第二层是那张列表里现存的项 —— 对不上的宿主丢掉并记一行日志。
1744
+ */
1745
+ items?: Readonly<Record<string, Readonly<Record<string, ExtensionItemView>>>>;
1746
+ /**
1747
+ * 图片字典:键 → 图片的 base64 data URL(png / jpeg / webp / svg,单张封顶,与选项图标同一条)。
1748
+ * 表格的图标格、二维码按键引用 —— 同一张图只放一份。整份视图序列化后有字节上限(256 KiB)。
1749
+ */
1750
+ images?: Readonly<Record<string, string>>;
1751
+ }
1752
+ /** 拓展列表页那一行。 */
1753
+ interface ExtensionViewSummary {
1754
+ tone?: ExtensionTone;
1755
+ text: ExtensionViewText;
1756
+ }
1757
+ /** 状态的语气,同时决定卡角那团颜色。 */
1758
+ type ExtensionTone = "ok" | "warn" | "error" | "off";
1759
+ /**
1760
+ * 一段字:一个字符串,或者一串片段。片段只有五种 —— 字、加粗、等宽、一个时刻(浏览器按
1761
+ * 「N 分钟前」画,`suffix` 接在后面)、BN 在浏览器里现算的地址。
1762
+ */
1763
+ type ExtensionViewText = string | readonly ExtensionViewTextSegment[];
1764
+ type ExtensionViewTextSegment = string | {
1765
+ b: string;
1766
+ } | {
1767
+ mono: string;
1768
+ } | {
1769
+ time: string;
1770
+ suffix?: string;
1771
+ } | {
1772
+ host: "extensionUrl";
1773
+ };
1774
+ /**
1775
+ * 一颗按钮,显式带 `kind`:
1776
+ * - `action`:调拓展(清单 `actions` 里声明、代码 `ctx.onAction` 接)—— 名字不在清单里的,宿主把那一块 /
1777
+ * 那一项按降级画;
1778
+ * - `set`:让 BN 改**这一项**的一格设置 —— 只许挂在列表项上,只许改那张列表声明过的格,不碰
1779
+ * `id`、密钥与生成的格,值的类型要对得上(`enum` 要在选项里)。
1780
+ */
1781
+ type ExtensionButton = {
1782
+ kind: "action";
1783
+ label: string;
1784
+ action: string;
1785
+ } | {
1786
+ kind: "set";
1787
+ label: string;
1788
+ set: Readonly<Record<string, string | number | boolean>>;
1789
+ };
1790
+ /** 列表的一项在卡上的那几格。停用的项由 BN 盖成「已停用」,`status` 报什么都不算。 */
1791
+ interface ExtensionItemView {
1792
+ status?: {
1793
+ tone: ExtensionTone;
1794
+ text: string;
1795
+ };
1796
+ pill?: string;
1797
+ subtitle?: ExtensionViewText;
1798
+ buttons?: readonly ExtensionButton[];
1799
+ /** 画在 BN 画的字段行(token 行这种)上面的积木。 */
1800
+ lead?: readonly ExtensionBlock[];
1801
+ /** 画在字段行下面的积木。 */
1802
+ blocks?: readonly ExtensionBlock[];
1803
+ }
1804
+ type ExtensionTableColumn = {
1805
+ kind: "icon";
1806
+ } | {
1807
+ kind: "text";
1808
+ width?: number;
1809
+ } | {
1810
+ kind: "mono";
1811
+ } | {
1812
+ kind: "tristate";
1813
+ label: string;
1814
+ };
1815
+ /**
1816
+ * 表格的一格 —— **自带种类**,与列的 `kind` 同一套词;宿主核「这一格与这一列同种」。图标格的
1817
+ * `image` 是 {@link ExtensionView.images} 里的键,没有就印 `fallback` 那两个字。
1818
+ */
1819
+ type ExtensionTableCell = {
1820
+ kind: "icon";
1821
+ image?: string;
1822
+ fallback: string;
1823
+ } | {
1824
+ kind: "text";
1825
+ text: string;
1826
+ sub?: string;
1827
+ } | {
1828
+ kind: "mono";
1829
+ text: string;
1830
+ } | {
1831
+ kind: "tristate";
1832
+ value: "yes" | "no" | "unknown";
1833
+ };
1834
+ type ExtensionBlock = {
1835
+ type: "keyValue";
1836
+ items: readonly {
1837
+ label: string;
1838
+ value: ExtensionViewText;
1839
+ tone?: ExtensionTone;
1840
+ }[];
1841
+ } | {
1842
+ type: "table";
1843
+ title?: string;
1844
+ count?: boolean;
1845
+ empty?: ExtensionViewText;
1846
+ columns: readonly ExtensionTableColumn[];
1847
+ rows: readonly (readonly ExtensionTableCell[])[];
1848
+ } | {
1849
+ type: "notice";
1850
+ tone: "info" | "warn" | "error";
1851
+ text: ExtensionViewText;
1852
+ button?: ExtensionButton;
1853
+ } | {
1854
+ type: "copy";
1855
+ label: string;
1856
+ value: string | {
1857
+ host: "extensionUrl";
1858
+ };
1859
+ note?: ExtensionViewText;
1860
+ } |
1861
+ /** `image` 是 {@link ExtensionView.images} 里的键。 */
1862
+ {
1863
+ type: "qr";
1864
+ image: string;
1865
+ caption?: ExtensionViewText;
1866
+ } | {
1867
+ type: "button";
1868
+ button: ExtensionButton;
1869
+ };
1870
+ type Simplify<T> = { [K in keyof T]: T[K]; } & {};
1871
+ /**
1872
+ * 拓展交给宿主的 HTTP 处理函数。
1873
+ *
1874
+ * 是**标准 fetch 形状**而不是一个 Hono 子应用:拓展包旁边没有 node_modules,它 import
1875
+ * 不到 hono。`Request` / `Response` 是运行时自带的。
1876
+ */
1877
+ type ExtensionFetchHandler = (req: Request) => Response | Promise<Response>;
1878
+ /** 一条落到某个拓展名下的 WS upgrade。 */
1879
+ interface ExtensionUpgrade {
1880
+ /** 原样的请求 —— `ws` 的 `handleUpgrade` 吃的就是这三样。 */
1881
+ req: IncomingMessage;
1882
+ socket: Duplex;
1883
+ head: Buffer;
1884
+ /**
1885
+ * 去掉 `/ext/<id>` 之后那一段(至少是 `/`)。
1886
+ *
1887
+ * 单给一格而**不改 `req.url`**:`upgrade` 事件上还挂着别的监听器(面板那条 `/ws`),
1888
+ * 改掉它等于在别人脚下换地板。
1889
+ */
1890
+ path: string;
1891
+ }
1892
+ type ExtensionUpgradeHandler = (upgrade: ExtensionUpgrade) => void;
1893
+ /**
1894
+ * 平台适配器交给宿主的整个定义:行为与自己的设置 schema 一起登记。
1895
+ *
1896
+ * 描述(外观与连接配置项)是静态数据,写在清单的 `contributes.push` 里(ADR-0019 决策 16),宿主读清单拿;
1897
+ * 代码里别再交一份 —— 两份声明会打架,宿主注册那一刻就会抛。`adapterKey` 由宿主按拓展 id 填。
1898
+ *
1899
+ * `settingsSchema` 是连接设置的校验:宿主拿它解连接,解不出的那条只隔离、不交给适配器;注册那一刻还拿它
1900
+ * 与清单里的连接配置项逐格对表(键、类型、默认值),对不上直接抛(ADR-0019 决策 17)。
1901
+ *
1902
+ * `listAddressCandidates` 与 `connectionAuth` 不对拓展开放(ADR-0024 决策 11),类型里排除,宿主运行时也会摘掉。
1903
+ */
1904
+ type PlatformAdapterDef = Simplify<Pick<PlatformAdapter, "probe" | "start" | "stop" | "isAvailable" | "send" | "capabilities" | "probeCapabilities" | "settingsSchema" | "listConnectionCandidates">>;
1905
+ /** 注册完一个平台适配器之后拿到的把手。 */
1906
+ interface PlatformAdapterHandle {
1907
+ /** 注销适配器;幂等,调用后不再接收消息,也不再发送。 */
1908
+ dispose(): void;
1909
+ }
1910
+ /**
1911
+ * 从核心 `Creator` 只挑拓展能交的 `name` / `avatar`,并把两者都放宽为可缺;`isPremium` 不开放。
1912
+ * 没有带的那一样由宿主按订阅资料补。
1913
+ */
1914
+ type SubscriptionCreator = Simplify<Pick<Creator, "avatar"> & {
1915
+ /** 1–128 字。 */
1916
+ name?: Creator["name"];
1917
+ }>;
1918
+ /**
1919
+ * 从核心 `RichTextSegment` 只挑当前开放的五个 `kind`;以后核心加片段种类,拓展这边不会跟着开放。
1920
+ */
1921
+ type ExtensionRichTextSegment = Extract<RichTextSegment, {
1922
+ kind: "text" | "mention" | "topic" | "link" | "emoji";
1923
+ }>;
1924
+ /**
1925
+ * 从核心 `RichText` 的片段类型推导,保留五个开放片段组成的可变数组;片段的 `text` 拼起来必须等于正文 `text`。
1926
+ */
1927
+ type ExtensionRichText = ExtensionRichTextSegment[];
1928
+ /**
1929
+ * 从核心 `PostReport` / `Post` 推导作品上报:只挑拓展开放的格,并覆盖图库引用、可缺作者与可缺视频格。
1930
+ * 不开放标题、文章、转发、附加块、锁、提醒、会员标记等格;`publishedAt` 是带时区的 ISO 8601 时刻。
1931
+ */
1932
+ type ExtensionPostReport = Simplify<Pick<PostReport, "postId" | "url"> & {
1933
+ post: Simplify<Pick<Post, "publishedAt" | "text" | "topic" | "stats"> & {
1934
+ /** 出卡优先用这里的创作者;缺的格由订阅资料补。 */
1935
+ creator?: SubscriptionCreator;
1936
+ /** 正文片段;给了就要与 `text` 对得上。 */
1937
+ richText?: ExtensionRichText;
1938
+ /** 作品图,图库引用。 */
1939
+ images?: ImageRef[];
1940
+ video?: Simplify<Pick<NonNullable<Post["video"]>, "durationSec" | "views"> & {
1941
+ cover?: ImageRef;
1942
+ title?: string;
1943
+ description?: string;
1944
+ }>;
1945
+ }>;
1946
+ }>;
1947
+ /**
1948
+ * 从核心 `LiveDetails` 推导直播详情:只挑拓展开放的格,并把作者换成可缺的 {@link SubscriptionCreator}、
1949
+ * 封面换成图库引用。
1950
+ */
1951
+ type ExtensionLiveDetails = Simplify<Pick<LiveDetails, "title" | "category" | "url" | "currentViewers" | "totalViewers" | "likes" | "description"> & {
1952
+ creator?: SubscriptionCreator;
1953
+ cover?: ImageRef;
1954
+ }>;
1955
+ /**
1956
+ * 从核心 `LiveSignalReport` 的三种 `kind` 分支推导,并把 `details` 换成拓展版;
1957
+ * 下播支额外放宽 `endedAt` 为可缺(不交时宿主取到达那一刻)。来源推送式上报的一场直播变化;
1958
+ * 时刻都是带时区的 ISO 8601。
1959
+ */
1960
+ type ExtensionLiveSignalReport = Simplify<(Pick<Extract<LiveSignalReport, {
1961
+ kind: "start";
1962
+ }>, "kind" | "startedAt"> & {
1963
+ details: ExtensionLiveDetails;
1964
+ }) | (Pick<Extract<LiveSignalReport, {
1965
+ kind: "status";
1966
+ }>, "kind" | "isLive" | "startedAt"> & {
1967
+ details: ExtensionLiveDetails;
1968
+ }) | (Pick<Extract<LiveSignalReport, {
1969
+ kind: "end";
1970
+ }>, "kind" | "startedAt"> & {
1971
+ endedAt?: Extract<LiveSignalReport, {
1972
+ kind: "end";
1973
+ }>["endedAt"];
1974
+ details?: ExtensionLiveDetails;
1975
+ })>;
1976
+ /**
1977
+ * 从核心 `LiveStatusResult` 的三个分支推导,并把在播详情换成拓展版、失败码收紧成标准 `FailureCode`;
1978
+ * 离线条整支取核心形状。来源拉取式直播状态;失败回标准结果形状,不抛。
1979
+ */
1980
+ type ExtensionLiveStatusResult = Simplify<(Pick<Extract<LiveStatusResult, {
1981
+ kind: "live";
1982
+ }>, "ok" | "kind" | "startedAt"> & {
1983
+ details: ExtensionLiveDetails;
1984
+ }) | Extract<LiveStatusResult, {
1985
+ kind: "offline";
1986
+ }> | (Pick<Extract<LiveStatusResult, {
1987
+ ok: false;
1988
+ }>, "ok" | "message"> & {
1989
+ code: FailureCode;
1990
+ })>;
1991
+ /**
1992
+ * 从核心 `SourceContext` 白名单挑出拓展当前开放的成员,并覆盖两种上报的参数为拓展版;
1993
+ * 互动上报与两个登记口不开放。与核心那一份同一套名单、请求与收尾口,只开放作品、直播、资料三种
1994
+ * 上报;上报返回 `void`,被拒也不回话(`reportProfile` 同样:停用的订阅不收)。
1995
+ */
1996
+ type ExtensionSourceContext = Simplify<Pick<SourceContext, "timezone" | "onTimezoneChanged" | "subscriptions" | "onSubscriptionsChanged" | "reportProfile" | "reportProblem" | "resolveProblem" | "logger" | "signal" | "onDispose" | "state" | "secrets" | "redact" | "settings" | "http" | "fetchImage" | "storeImage"> & {
1997
+ /** 交一条作品。没有返回值;图和时刻按拓展契约交。 */
1998
+ reportPost(externalId: string, report: ExtensionPostReport): void;
1999
+ /** 交一条直播信号。没有返回值;`status` 不触发推送。 */
2000
+ reportLive(externalId: string, report: ExtensionLiveSignalReport): void;
2001
+ }>;
2002
+ /** 注册完一个订阅源之后拿到的唯一把手:注销这个来源。 */
2003
+ interface SourceHandle {
2004
+ /** 注销来源;幂等,调用后来源不再上报。 */
2005
+ dispose(): void;
2006
+ }
2007
+ /**
2008
+ * 订阅源代码那一半。清单负责外观与能力声明;这里的成员按表拿,未开放的成员即使给了也不认。
2009
+ */
2010
+ interface SourceDef {
2011
+ /**
2012
+ * 启动来源。拿到名单与三种上报口;这里可以同步返回,也可以回 Promise。
2013
+ * `stop()` 之后不许再上报。
2014
+ */
2015
+ start(ctx: ExtensionSourceContext): void | Promise<void>;
2016
+ /** 停下来源。宿主先叫它,再中止 `ctx.signal` 并跑收尾钩子。 */
2017
+ stop(): void | Promise<void>;
2018
+ /**
2019
+ * 搜人:输入可以是链接、id 或名字,原样交进来。最多回 10 个候选;
2020
+ * 查无此人是成功的空数组,失败回结果形状、不抛。`signal` 中止后应尽快收手。
2021
+ */
2022
+ searchCreators(query: string, signal: AbortSignal): Promise<Result<{
2023
+ candidates: CreatorCandidate[];
2024
+ }>>;
2025
+ /**
2026
+ * 取一个人的资料。可选;不实现就靠 `ctx.reportProfile` 主动上报。
2027
+ * 失败回结果形状、不抛,`signal` 中止后应尽快收手。
2028
+ */
2029
+ fetchProfile?(identity: Identity, signal: AbortSignal): Promise<Result<CreatorProfileReport>>;
2030
+ /**
2031
+ * 此刻这个人在不在播,时刻按带时区的 ISO 8601 交。声明了周期直播必须实现它,否则拓展装不上。
2032
+ * 不实现就只靠 `ctx.reportLive` 推送式上报。
2033
+ */
2034
+ fetchLiveStatus?(identity: Identity, signal: AbortSignal): Promise<ExtensionLiveStatusResult>;
2035
+ /** 此刻的健康状况,同步、不出网。不交就不占状态行。 */
2036
+ health?(): SourceHealth;
2037
+ }
2038
+ /**
2039
+ * 拓展取自己包里译文的口(`ctx.i18n`,ADR-0037 决策 14)。译文放在包里的 `locales/<语言码>.json`,
2040
+ * 宿主在读目录时读好;拓展没带译文也照样有这一格,`t` 回键本身。
2041
+ *
2042
+ * 语言整台一种、由主人在面板上选;取字时读当前那一种,所以**别把 `t` 的结果存起来用**。
2043
+ * 口吻不交给拓展:这里只有平实一层,没有女仆层。
2044
+ */
2045
+ interface ExtensionI18n {
2046
+ /**
2047
+ * 当前语言,**现读**。是 `string` 而不是一个固定的语言码表:宿主以后加了新语言,不该在类型上
2048
+ * 就把旧拓展挡在外面。
2049
+ */
2050
+ locale(): string;
2051
+ /**
2052
+ * 按键取字。占位符写 `{名字}`,从 `values` 里填;`values.count` 是数字时按当前语言挑单复数类别
2053
+ * (译文里写成 `键#one` / `键#other` …)。
2054
+ *
2055
+ * 回落链固定:当前语言 → 简中 → 英文 → 键本身,**按句**回落 —— 当前语言缺哪一句,只那一句落到后面。
2056
+ * 缺键回键本身(露出来好查),不抛。
2057
+ */
2058
+ t(key: string, values?: TextValues): string;
2059
+ /**
2060
+ * 当前语言**真的换了**时叫(只换了口吻不叫)。换了语言以后 `t` 取到的就是新语言。
2061
+ * 视图是现取的,宿主已经替每个在跑的拓展喊过一次「面板数据变了」,面板会自己重取 ——
2062
+ * 拓展**不用自己再喊** `statusChanged()`;只有自己缓存了译文算出来的东西时,才在这里重算。
2063
+ * 卸载时自动摘掉。
2064
+ */
2065
+ onChange(fn: () => void): Disposable;
2066
+ }
2067
+ /**
2068
+ * 交给拓展的那面 —— **第一版刻意很窄**(ADR-0012 决策 13)。
2069
+ *
2070
+ * 窄面加宽容易,反过来不行;而我们手上只有一个真实用例(桥接),凭空设计「宿主应该提供
2071
+ * 什么」就是在猜。⛔ **`bus` 永远不在这里** —— `MessageBus` 是全仓唯一事件通道,给出去
2072
+ * 就等于允许写第二条通道之间的转发器(CLAUDE.md 那条硬约束:会自喂死循环爆栈)。
2073
+ *
2074
+ * 🔴 拓展的**一切副作用都得从这里过**:裸 `setInterval`、裸挂端点都是禁止的。这是
2075
+ * 「卸载得干净」的唯一承重条件 —— 留一条旁路,卸载就不干净,而不干净的卸载比要求重启
2076
+ * 更难 debug(面板写着「已停用」,定时器还在跑)。
2077
+ */
2078
+ interface ExtensionContext extends IntegrationContext {
2079
+ /** 它自己的 id —— 同时是挂载点、装载目录与记账键那一段。 */
2080
+ readonly id: string;
2081
+ /** 宿主**当前**的契约档位(它认的区间的上沿)。拓展自己也可能要按它分叉。 */
2082
+ readonly hostApiVersion: number;
2083
+ /**
2084
+ * 独立端自己的版本号(载荷版本)。**与契约版本是两件事** —— 那个决定「加不加载」,
2085
+ * 这个是拿去报给对家看的(桥在 `welcome` 帧里把它告诉插件)。
2086
+ */
2087
+ readonly hostVersion: string;
2088
+ /**
2089
+ * 行的标签就是拓展的 id(面板日志页按它筛),正文里不用也不会再带 id。日志等级跟日志设置里它自己的那一格
2090
+ * (`logging.levels.<id>`),没写就跟总等级。
2091
+ */
2092
+ readonly logger: Logger;
2093
+ /** 自己包里的译文与当前语言,见 {@link ExtensionI18n}。只挂拓展的上下文,不在 `IntegrationContext` 上。 */
2094
+ readonly i18n: ExtensionI18n;
2095
+ /** 可回收定时器。卸载时宿主统一清,拓展自己漏了也不会留下幽灵。 */
2096
+ setTimeout(fn: () => void, ms: number): Disposable;
2097
+ setInterval(fn: () => void, ms: number): Disposable;
2098
+ /**
2099
+ * 申请一条 HTTP 总入口,回宿主分配的前缀(`/ext/<自己的 id>`)。
2100
+ *
2101
+ * **拓展不该知道自己挂在哪**(决策 12):handler 收到的路径已经剥掉前缀,要拼绝对
2102
+ * 地址时才用这个返回值。一个拓展只有一条总入口,再申请一次会抛。
2103
+ */
2104
+ mount(handler: ExtensionFetchHandler): string;
2105
+ /**
2106
+ * 注册这个拓展的平台适配器 —— 一个拓展只有一个(决策 28),再注册一次会抛。
2107
+ *
2108
+ * 清单得开 `contributes.push`,否则抛。`def.start(ctx)` 拿到与核心平台适配器同一套的上下文
2109
+ * ({@link PlatformAdapterContext}),自己的连接与入站都从那里取;交回的把手只管注销。
2110
+ *
2111
+ * **分发键由宿主按拓展 id 填**:自报的话,一个拓展可以声明 `"onebot"` 把内置那条连接的推送整个截走,
2112
+ * 归属是宿主的判断。描述写在清单的 `contributes.push` 里。停用 / 卸载时宿主替它撤登记
2113
+ * (先叫 `stop()`,再中止 `ctx.signal`);把手的 `dispose()` 幂等。
2114
+ */
2115
+ registerPlatformAdapter(def: PlatformAdapterDef): PlatformAdapterHandle;
2116
+ /**
2117
+ * 注册这个拓展的订阅源(当前契约形状)—— 一个拓展就是一个平台,**只许登一次**,再登会抛。
2118
+ *
2119
+ * 清单得开了 `contributes.subscription`,否则抛。`def.start(ctx)` 拿到与核心来源同一套的上下文
2120
+ * ({@link ExtensionSourceContext}),三种上报都在 `ctx` 上;交回的把手只管注销。
2121
+ *
2122
+ * 🔴 登记是**异步**的:这里同步交回把手,宿主在后台等 `start` 落定;`start` 抛了,这一次加载就失败
2123
+ * (原因进拓展列表),与推送源的 `start` 抛了同一个结局。停用 / 卸载时宿主替它撤登记
2124
+ * (先叫 `stop()`,再中止 `ctx.signal`);把手的 `dispose()` 幂等。
2125
+ */
2126
+ registerSource(def: SourceDef): SourceHandle;
2127
+ /**
2128
+ * 认领 `/ext/<id>` 底下的 WS upgrade。
2129
+ *
2130
+ * 交给它的是**原样的三样原料**(`req` / `socket` / `head`)加一段剥掉前缀的路径:
2131
+ * 握手、鉴权、帧上限、心跳全归拓展 —— 那些是协议语义(决策 26)。宿主只回答
2132
+ * 「这条 upgrade 归谁」。
2133
+ */
2134
+ onUpgrade(handler: ExtensionUpgradeHandler): void;
2135
+ /**
2136
+ * 交给面板看的「视图」(ADR-0019 决策 20 / 39)—— **当前契约**。宿主在 `/api/ext/<id>/status`
2137
+ * 下发:走 `/api/*` 才吃得到 dashboard 会话鉴权,而 `/ext/<id>/*` 是**刻意**在鉴权外的。
2138
+ * **现取**,不缓存:面板每问一次,宿主叫一次这个回调。
2139
+ *
2140
+ * 🔴 回调要**同步**交回视图。交回 Promise(`async` 回调就是这样)宿主当场报错 —— 那一口画成
2141
+ * 一条「publishView 的回调要同步交回视图」的提示,不会静默变成一份空视图;要等的东西自己先算好
2142
+ * 存着,变了喊一声 {@link statusChanged}。
2143
+ *
2144
+ * 宿主先校验再画,不合规矩的**按块 / 按项**降级(决策 40):页上坏一块只换掉那一块,列表坏一项
2145
+ * 那张卡写「状态未知」,摘要坏了就不画 —— 每一处都点名哪儿、为什么,日志里也记一行。
2146
+ */
2147
+ publishView(fn: () => ExtensionView): void;
2148
+ /**
2149
+ * 交上去的那份数据**变了**,喊一声。`publishView` 是现取的,盲点在「什么时候该再取」:
2150
+ * 桥那头刚握完手,面板上那张卡还灰着,得切一下页才刷新。宿主把这一声推到面板(WS
2151
+ * `state` 频道),面板当场重取 `/api/ext/<id>/status` 与 bot 名单。什么算「变了」由
2152
+ * 拓展自己定 —— 桥:一条接入连上 / 断开。
2153
+ *
2154
+ * 放心连喊:宿主**按拓展合并**,一个短窗口(四分之一秒)里的连喊只推一次,落在窗口的尾沿 —— 最后
2155
+ * 那一喊之后一定还有一次,面板重取到的是它之后的样子。拓展不用自己攒。
2156
+ */
2157
+ statusChanged(): void;
2158
+ /**
2159
+ * 自己的持久设置 —— 主人在面板上给**这个拓展**填的那些(桥的接入名单就住这儿),落盘在
2160
+ * `config/settings/extensions/<id>.json`,**形状归拓展自己那份 zod**,宿主只保证存得住。交一份
2161
+ * zod 进来,拿回一个现读的 {@link SettingsReader}(与内置集成读自己的设置是同一个口)。
2162
+ * 可以叫多次,每次都是同一份数据的一个视图。(签名继承自 `IntegrationContext.settings`,这里同签名重写
2163
+ * 只为写拓展专属的说明;推送源 `start(ctx).settings` 与它是同一份实现。)
2164
+ *
2165
+ * 与连接是两回事:连接是「一个 bot」,是宿主认识、推送目标能挂上去的东西;设置是拓展
2166
+ * 为了拿到那些 bot 而需要主人填的东西(token、对家的名字……),宿主一格都不认识。
2167
+ * ⛔ **没有写口** —— 配置的写路径在这仓里只有面板那一条(决策 30 同一条纪律)。
2168
+ *
2169
+ * `get()` 回 `Result<{ settings }>`、**不抛**:
2170
+ * - 没设过:拿空对象过这份 zod。过得了是成功并带默认值,过不了回 `not_configured`(拓展照跑,
2171
+ * 等主人填);
2172
+ * - 带异步规则、交进来那一刻判不完:回 `unavailable`,等一拍再读;
2173
+ * - **跑着时**存着的那份被旁路写坏(恢复备份、手改文件):回 `invalid`、带原因,并叫一次 `onChange`
2174
+ * —— 宿主随后把拓展收掉(ADR-0019 决策 36)。这一拍里别把 `invalid` 当成空设置:桥的做法是记着
2175
+ * 上一份好的名单。
2176
+ *
2177
+ * 当前拓展的这份 zod 要与清单里的 `settings.fields` 对得上(键、类型、默认值),对不上
2178
+ * 当场抛 —— 面板照清单画表单、宿主照 zod 解,两份漂开就是「填了存不进去」。清单声明了设置项的
2179
+ * 当前契约**必须在 `activate` 里交**(ADR-0019 决策 35):面板写进来的值要再过它这一道,不交按加载失败算。
2180
+ *
2181
+ * 🔴 **只有 `activate` 期间**存着的那份过不了这份 zod 会当场抛(ADR-0019 决策 36)—— 别接住了接着
2182
+ * 往下起:宿主认的是它自己记下的那一笔,接住了也照样不起,面板上是「设置读不了」,主人改对了宿主会
2183
+ * 再起它一次。
2184
+ */
2185
+ settings<T>(schema: ZodType<T>): SettingsReader<T>;
2186
+ /**
2187
+ * 接面板上的一个「调拓展」按钮(ADR-0019 决策 22 / 42)。`name` 必须在清单的 `actions`(一串动作名)
2188
+ * 里声明过 —— 清单是面板能按哪些钮的全集,没声明的注册当场抛;同一个名字接两次也抛。
2189
+ *
2190
+ * 面板经 `POST /api/ext/<id>/actions/<name>` 调(走面板会话鉴权)。抛出来的错**原话**给到面板;
2191
+ * 30 秒没回按超时算。界面该跟着变的话,自己叫一声 `statusChanged()`。卸载时自动摘掉。
2192
+ *
2193
+ * 🔴 `signal` 在两种时候中止,handler 要听它、手上的请求 / 轮询接着它停:
2194
+ * - **超时**(`reason` 是 `TimeoutError`):宿主已经回了面板一句「超时」,再接着跑下去,做完的事主人
2195
+ * 看不见(扫码登录会在背后多存下一份账号);
2196
+ * - **拓展停用 / 收摊**(`AbortError`):在 `onDispose` 的钩子跑之前就中止了,钩子里可以等它们收尾。
2197
+ *
2198
+ * 同一个动作在跑时再按,宿主直接回面板「还在跑」(409),不排队、不并发 —— 「在跑」算到 handler
2199
+ * 真的回来为止:超时叫停了却不停的,照样挡着下一发。不同的动作互不相干。
2200
+ */
2201
+ onAction(name: string, handler: (signal: AbortSignal) => void | Promise<void>): void;
2202
+ }
2203
+ /**
2204
+ * 开发入口拿到的上下文:就是这个拓展 `activate` 时那份 `ExtensionContext`,外加 `mountUrl()`。
2205
+ *
2206
+ * 开发入口的约定:
2207
+ * - 包里固定文件名 `devtools.mjs` —— 名字由宿主定,清单只写 `"devtools": {}` 开口、不带路径
2208
+ * (ADR-0012 决策 35);
2209
+ * - 导出 `devtools(ctx: ExtensionDevtoolsContext): DevtoolsProvider`,**同步**交回;模块顶层不存状态;
2210
+ * - 只在开发版加载;拓展停用 / 卸载 / 重载时宿主撤掉它的场景(`ctx.signal` 中止);
2211
+ * - 场景 id 写不带前缀的,宿主加 `<拓展 id>.`;参数这一版只收 `text` / `number` / `enum`,
2212
+ * 别的种类整包拒;`run` 回结果,只用自己的 ctx 做事。
2213
+ */
2214
+ interface ExtensionDevtoolsContext extends ExtensionContext {
2215
+ /**
2216
+ * 自己那条总入口在本机回环上的完整地址(形如 `http://127.0.0.1:<端口>/ext/<自己的 id>`);
2217
+ * HTTP 还没起来时回 `undefined`,每次现取。开发入口拿它连回自己的端点 —— `ctx.mount()`
2218
+ * 只许主入口申请一次,回的也只是前缀。
2219
+ */
2220
+ mountUrl(): string | undefined;
2221
+ }
2222
+ export { type CapabilitySupport, type Connection, type ConnectionCandidate, type ConnectionCapabilities, type CreatorCandidate, type CreatorProfileReport, type DeliveryResult, type DestinationRef, type DevInjection, type DevParamField, type DevParamValues, type DevScenarioDef, type DevScenarioDescriptor, type DevScenarioGroup, type DevtoolsProvider, type Disposable, type ExtensionBlock, type ExtensionButton, type ExtensionContext, type ExtensionDevtoolsContext, type ExtensionFetchHandler, type ExtensionI18n, type ExtensionItemView, type ExtensionLiveDetails, type ExtensionLiveSignalReport, type ExtensionLiveStatusResult, type ExtensionPostReport, type ExtensionRichText, type ExtensionRichTextSegment, type ExtensionSourceContext, type ExtensionTableCell, type ExtensionTableColumn, type ExtensionTone, type ExtensionUpgrade, type ExtensionUpgradeHandler, type ExtensionView, type ExtensionViewSummary, type ExtensionViewText, type ExtensionViewTextSegment, type Failure, type FailureCode, type FeatureKey, type FetchOptions, type Hop, type HopHandler, type HttpClient, type HttpResponse, type Identity, type ImageRef, type InboundGroupMessage, type InboundMeta, type InboundPrivateMessage, type IntegrationContext, type Json, type KeyValueOp, type KeyValueStore, type Logger, type NotificationPayload, type PayloadSegment, type PlatformAdapter, type PlatformAdapterContext, type PlatformAdapterDef, type PlatformAdapterDescriptor, type PlatformAdapterHandle, type PlatformDescriptor, type ProbeResult, type PushTarget, type PushTargetScope, type Result, type SettingsField, type SettingsFieldMeta, type SettingsListField, type SettingsReader, type SettingsScalarField, type SourceDef, type SourceHandle, type SourceHealth, type SourceSubscriptionView, type SubscriptionCreator, type TextValues, type WebSocketLike, type WebSocketOptions, fail, ok };