@bilibili-notify/extension 0.1.0-alpha.0 → 0.1.0-alpha.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/AGENT_GUIDE.md CHANGED
@@ -16,6 +16,7 @@
16
16
  | 任务 | 从公开类型开始 |
17
17
  | ------------------------------ | ---------------------------------------------------------------- |
18
18
  | 搜索创作者、获取资料、轮询订阅 | `SourceDef`、`ExtensionSourceContext` |
19
+ | 群聊作品链接与长短链冷却 | `contributes.linkResolver`、`SourceDef.resolveLink`、`ExtensionLinkPreview` |
19
20
  | 作品和直播上报 | `ExtensionPostReport`、`ExtensionLiveSignalReport` |
20
21
  | 推送出口、探测和发送 | `PlatformAdapterDef`、`PlatformAdapterContext`、`DeliveryResult` |
21
22
  | 设置及设置页动作 | `SettingsReader`、`ExtensionContext`、`ExtensionView` |
@@ -25,6 +26,7 @@
25
26
  - `settings.get()` 返回 `Result<{ settings }>`;先处理失败,再读 `result.settings`。
26
27
  - 请求、WebSocket、图片、定时器、状态、凭据与日志经 ctx;状态写入也返回 Result,检查写入结果。凭据存 `ctx.secrets`,临时凭据先交 `ctx.redact`。
27
28
  - 来源只持有 `externalId`,用上报接口交给宿主;订阅 UUID、规则、路由、发送和历史由宿主负责。上报返回 `void`,不是发送回执;直播 `status` 不触发推送。
29
+ - 可读账号用 `displayId`,稳定身份仍用 `externalId`;字段语义、叫法与最低宿主修订号见作者指南“展示账号”。
28
30
  - `stop()` 先停止新工作与上报;宿主随后中止上下文信号并收尾。不要在 `stop()` 里无限等待只能靠后续中止信号结束的任务。
29
31
  - 成功用 `ok`,预期失败用 `fail` 和标准失败码。发送结果不明用 `indeterminate`,不能当作未发送而自动重试。
30
32
  - 展示文字由 `ctx.i18n.t` 现取;用户输入、创作者原文及上游诊断不改写成翻译键。
package/DEVELOPMENT.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## 版本与工程
6
6
 
7
- 当前宿主契约是`apiVersion: 1`、`apiRevision: 0`。SDK的npm版本、拓展自己的`version`与这两个契约数字各自独立。历史设计中的“v3”不是当前可安装的清单版本。
7
+ 宿主契约为 `apiVersion: 1`,群聊作品与来源扫码登录要求 `apiRevision: 1`,展示账号要求 `apiRevision: 2`。只用原有能力的拓展仍可省略小号(按 0 处理)。SDK 的 npm 版本和拓展自己的 `version` 分别管理。SDK `0.1.0-alpha.1` 包含这里描述的 1/2 契约,`0.1.0-alpha.0` 仅提供 1/0;使用新增能力时应声明对应小号并核对宿主兼容性。
8
8
 
9
9
  创建器默认生成独立Git工程、示例来源、完整vp命令、锁文件、提交hooks与GitHub Actions:
10
10
 
@@ -19,7 +19,7 @@ git commit -m "feat: create extension"
19
19
 
20
20
  创建器使用`.node-version`固定Node,`packageManager`固定包管理器,开发依赖也固定版本。后续克隆用`vp install --frozen-lockfile`。若使用`--no-git`,先在工程根初始化自己的Git仓库,再运行`vp hooks enable`;安装过程会避开外层仓库。
21
21
 
22
- 终端向导依次询问工程目录、拓展ID、GitHub仓库和显示名;回车可用目录和显示名的默认值,输错会在当前项重问。脚本仍可用`vp dlx create-bn-ext@alpha my-extension --id example.demo --repository owner/repository --name "Example"`完整传参;非终端缺参数时直接退出。发布到`latest`后可省略`@alpha`,生成工程的开发命令仍统一用vp。
22
+ 终端向导询问工程目录、拓展 ID 和显示名,目录和显示名可按回车使用默认值。尚未创建 GitHub 仓库也可以开发和打包。脚本可用 `vp dlx create-bn-ext@alpha my-extension --id example.demo --name "Example"` 跳过向导。
23
23
 
24
24
  `example.demo`里的`example`是市场命名空间,与GitHub的`owner`无关。第三方清单id必须包含这个命名空间;无点的id留给官方源。作者可选择自己的命名空间,但同一BN实例不允许两个不同来源占用同一命名空间。
25
25
 
@@ -33,7 +33,7 @@ vp dlx @bilibili-notify/bn@alpha dev
33
33
 
34
34
  无需检出BN主仓或在隐藏目录构建宿主。正式运行使用`npx @bilibili-notify/bn@alpha web`;alpha发行期间入口带`@alpha`,本地审阅归档不代表已经发布。开发BN本体仍克隆主仓、按主仓指引使用vp。
35
35
 
36
- 启动器按版本与用途校验、缓存官方宿主。默认数据分别在`~/.bilibili-notify/dev-data`与`~/.bilibili-notify/data`,配置与凭据保存在该数据目录的`bn.config.yaml`。可用`--data-dir <绝对目录>`明确指定;缓存删除不影响持久数据,其他实例的数据需要通过`--data-dir`显式指定。端口可用`--port`调整,离线运行使用`--offline`及已经校验的缓存。
36
+ 启动器从npm包内解包宿主,并按版本与用途核对缓存。默认数据分别在`~/.bilibili-notify/dev-data`与`~/.bilibili-notify/data`;配置、凭据和其他持久数据位于该数据目录,启动配置文件为`bn.config.yaml`。可用`--data-dir <绝对目录>`明确指定;缓存删除不影响持久数据,其他实例的数据需要通过`--data-dir`显式指定。端口可用`--port`调整。npm包与依赖装好后,启动宿主不再下载载荷,也不需要额外的离线参数;删除缓存后仍可从包内重建。
37
37
 
38
38
  拓展工程由创建器安装好依赖;已有工程先运行`vp install --frozen-lockfile`。只需启动BN,打开拓展页,点击“挂载开发拓展”,输入源码工程在BN机器上的绝对路径,再沿原开关启用。BN直接加载`src/index.ts`,负责运行、监听源码与子依赖、局部重载和收尾。工程不需要`dist/`,也没有独立的dev/start命令;`build`与打包用于生产。多个工程可同时挂载,保存一个只重载对应项。
39
39
 
@@ -41,9 +41,22 @@ vp dlx @bilibili-notify/bn@alpha dev
41
41
 
42
42
  手动挂载存在于源码开发版和`bn dev`专用成品。`bn web`、Docker、桌面及普通生产构建没有此入口;运行期环境变量不能打开它。两个宿主使用相同默认端口时需先停止其中一个;多个拓展应挂到同一台开发BN。
43
43
 
44
+ ## 订阅来源的账号和扫码
45
+
46
+ 需要登录的来源在清单写 `apiVersion: 1`、`apiRevision: 1`,并在 `ctx.registerSource` 的 `auth` 提供 `SourceAuth`。宿主在「系统 → 账号」列出来源,并通过 `onChange` 重读同步的 `state()`、`account()`。独立来源分别登录和退出。仍在使用契约 1/0 的宿主会要求升级。
47
+
48
+ `beginLogin()` 生成新二维码。以 `awaiting-scan` 返回 `qr.dataUrl`(PNG data URL)和 ISO 格式的 `qr.expiresAt`。等待手机确认用 `confirming`。已有会话失效用 `expired`,二维码过期或无可用验证途径用 `error` 并给出可公开的原因。仅在上游确认凭据有效后进入 `logged-in`。
49
+
50
+ 需要二次验证时,在 `confirming.verification` 提供以下一种操作。
51
+
52
+ - 短信验证码使用 `{ kind: "sms", attemptId }`。同一次发码与验码共享内存中的上游会话。每个挑战新建一个 1–128 位的随机公开标识(字母、数字、下划线或连字符),再用 `submitVerification(attemptId, code)` 接收 4–8 位数字。拓展在发请求和采用其结果前都须核对会话。新扫码、退出、停用时取消旧轮询和验码请求,忽略迟到的响应。
53
+ - 图形验证使用 `{ kind: "external", url }`。仅接受平台提供的官方 HTTPS 地址,拓展校验来源和跳转,等待用户在官方页面完成后继续向上游确认。
54
+
55
+ 登录凭据按拓展隔离保存在 `ctx.secrets`。启动时读取并重新确认,退出时清除。验证码、上游票据与待扫会话只留内存;只把可公开的字段放进状态、账号、错误和日志。账号切换时中止旧账号的业务请求,使先发出的响应无法覆盖新状态。
56
+
44
57
  ## 包与入口
45
58
 
46
- 根目录保留`extension.json`,`.bn/marketplace.json`只保存作者与仓库配置。发行ZIP包含构建后的`extension.json`、单文件`index.mjs`,可选`README.md`、`CHANGELOG.md`及`locales/<语言码>.json`;开发入口`devtools.mjs`不进入发行ZIP。
59
+ 根目录保留`extension.json`。新模板将市场名称、命名空间和作者资料放在 `.bn-extension/marketplace.json`。发行ZIP包含构建后的`extension.json`、单文件`index.mjs`,可选`README.md`、`CHANGELOG.md`及`locales/<语言码>.json`;开发入口`devtools.mjs`不进入发行ZIP。
47
60
 
48
61
  生产拓展运行时没有自己的`node_modules`。生成配置把SDK与第三方依赖内联到入口;增加依赖后仍需保持单入口、自包含构建。源码开发使用工程已安装的依赖,不能据此假定生产也能读取它们;发布前仍需实际构建与装包校验。原生插件和运行时额外读文件的依赖需要另行设计,不能只凭构建成功判断可运行。
49
62
 
@@ -89,8 +102,39 @@ export function activate(ctx: ExtensionContext): void {
89
102
 
90
103
  `start(sourceCtx)`得到运行中的来源上下文:从`subscriptions()`读取自己平台的创作者名单,监听`onSubscriptionsChanged`,以`externalId`上报。`reportProfile`更新资料,`reportPost`交作品,`reportLive`交开播、状态或下播信号;具体载荷使用SDK的`ExtensionPostReport`、`ExtensionLiveSignalReport`等公开类型。直播`status`只更新状态,不触发推送。
91
104
 
105
+ ### 展示账号(API 1 修订 2)
106
+
107
+ `externalId`是稳定身份,始终用于候选选择、请求和上报。用户可读但可能改变的公开账号放在`CreatorProfileReport.displayId`,搜索候选和`fetchProfile`也用同一字段。省略时保留旧资料,空串清除,最长256字。界面优先展示该账号,缺失时显示原身份;不会按展示账号合并或迁移订阅。
108
+
109
+ 清单的`contributes.subscription.displayIdNoun`声明该账号的叫法,`$manifest.contributes.subscription.displayIdNoun`提供译文;它只装短名词。使用展示账号时将清单`apiRevision`设为2,旧宿主会在加载前说明契约不兼容。简介`bio`仅保存创作者原文,展示账号独立提供。
110
+
92
111
  拓展不持有BN内部订阅id,也不自己发送通知。宿主处理订阅开关、去重、规则、卡片、推送目标和历史。上报返回`void`,不把它当作发送回执;不合规的上报会留在宿主的上报问题记录里。
93
112
 
113
+ ## 群聊作品链接
114
+
115
+ 在根清单给订阅源声明可解析的网址。旧宿主看到小号 1 会提示升级。
116
+
117
+ ```json
118
+ {
119
+ "apiVersion": 1,
120
+ "apiRevision": 1,
121
+ "contributes": {
122
+ "subscription": { "label": "作品来源", "supportedFeatures": ["post"] },
123
+ "linkResolver": {
124
+ "patterns": [
125
+ { "host": "www.example.com", "pathPrefix": "/video/" },
126
+ { "host": "www.example.com", "pathPrefix": "/note/" },
127
+ { "host": "share.example.com", "pathPrefix": "/" }
128
+ ]
129
+ }
130
+ }
131
+ }
132
+ ```
133
+
134
+ `host` 填小写完整域名,每个子域分别列出。路径按段匹配,`/video` 匹配该路径和它的子路径,`/video/` 从该目录开始匹配。宿主只分派标准端口的 HTTP(S) 链接,裸域名补 HTTPS。来源在 `SourceDef.resolveLink(url, signal)` 收到命中的单条完整网址。把 `signal` 接到所有请求;短链展开用 `ctx.http.fetch` 的 `beforeHop` 在请求每一跳前检查协议、域名和端口,匿名展开时使用 `bare`。
135
+
136
+ 成功返回 `ok({ postId, url, post })`,即 `Result<ExtensionLinkPreview>`。同一作品的各种链接都返回相同的 `postId`,`url` 填声明范围内的规范网址。即使没有该作者的订阅,`post.creator.name` 也必须有值;作品时刻、正文和图库引用沿用 `ExtensionPostReport`。获取失败返回 `fail(code, message)`。宿主执行逐群开关、额度与冷却,按配置回图片或文字,选原生分享时这类作品回落图片。停用来源会撤销解析并中止在途请求。
137
+
94
138
  ## 设置与副作用
95
139
 
96
140
  设置规则只维护一份。入口导出`settingsSchema`并在`activate`交给`ctx.settings`;生成的构建配置用`extensionPackageFiles`把字段、默认值和说明写进`dist/extension.json`。推送连接的设置规则同理导出`connectionSettingsSchema`,写入`contributes.push.settingsFields`。
@@ -100,6 +144,7 @@ export function activate(ctx: ExtensionContext): void {
100
144
  | 能力 | 使用方式 |
101
145
  | --- | --- |
102
146
  | 网络 | `ctx.http.fetch` / `websocket`,接上传入的中止信号;明确不需要浏览器身份及cookie时才选`bare` |
147
+ | 隔离登录会话(API 1 修订 1) | 顶层 `ctx.createCookieSession(saved?)` 创建独立内存罐。每跳用 `ingest(url, line)` 接收 Set-Cookie,`header(url)` 取该 URL 的 Cookie。宿主登记凭据脱敏。需恢复时将 `snapshot()` 字符串显式存入 `ctx.secrets`,坏快照抛出 TypeError。 |
103
148
  | 状态 | `ctx.state`存公开业务状态,`ctx.secrets`存凭据;`http.`前缀由宿主保留 |
104
149
  | 图片 | 通过`fetchImage`或`storeImage`得到图库引用,再交给上报载荷;不要把任意远端图地址冒充引用 |
105
150
  | 定时与收尾 | `ctx.setTimeout` / `setInterval`、`signal`、`onDispose`;保存自己需要等待的任务并收尾 |
@@ -117,6 +162,8 @@ export function activate(ctx: ExtensionContext): void {
117
162
 
118
163
  给人看的拓展文字放在`locales/zh-CN.json`、`zh-TW.json`、`en.json`、`ja.json`,使用`ctx.i18n.t(key, values)`现取,不缓存翻译结果。未提供译文的语言按宿主回落规则处理。作者、创作者、输入和上游诊断原文不作为翻译键。
119
164
 
165
+ 市场卡片复用这些文件里的`$manifest.name`和`$manifest.description`。当前版本的市场说明可写为普通译文键`marketplace.notes`;发布命令从实际构建的`dist/locales/`提取到索引的可选`locales`字段,不另建市场译文文件。缺项按“当前语言 → 简中 → 英文 → 默认文字”逐字段回落,历史CHANGELOG保留原文。
166
+
120
167
  ## 检查、安装与发布
121
168
 
122
169
  ```sh
@@ -132,6 +179,10 @@ vp run release --tag v0.1.0 --dry-run
132
179
 
133
180
  `verify`串起代码门禁、构建和打包;发布命令还复验Conventional Commits。ZIP与SHA256在`artifacts/`,可在BN拓展页上传安装。SDK版本变化不替你更改清单的宿主契约要求。
134
181
 
135
- 发布前更新根清单版本,提交修改,再打匹配的`v<版本>`标签并推送到自己的GitHub仓库。生成的Release工作流先以读取权限跑dry-run,成功后发布作业才取得`contents: write`;手动触发默认只验证。完整流程、`.bn/`字段和中断重跑方法见生成工程的README。
182
+ 市场作者名默认为拓展命名空间,可在市场配置的 `owner.name` 修改。创建时若已确定仓库,可选传 `--repository owner/repo`,以 GitHub 所有者作为作者名初值,并在初始化 Git 时设置 `origin`。
183
+
184
+ 准备发布时,GitHub Actions 从 `GITHUB_REPOSITORY` 取得目标仓库。本地预演和发布使用 `origin` 的推送地址。尚未设置时,先用 `git remote add origin <GitHub 仓库地址>` 添加,再用 `git remote get-url --push origin` 核对。
185
+
186
+ 发布前更新根清单版本,提交修改,再打匹配的 `v<版本>` 标签并推送到自己的 GitHub 仓库。生成的 Release 工作流先以读取权限跑 dry-run,成功后发布作业才取得 `contents: write`。手动触发默认只验证。完整流程和中断重跑方法见生成工程的 README。
136
187
 
137
188
  用户在BN“拓展 → 市场源”输入`owner/repository`或GitHub仓库网址,即定位到固定`bn-marketplace` Release上的`marketplace.json`。只支持公开可读取的索引和ZIP;第三方来源仍需用户信任,SDK和创建器不会赋予官方身份。
package/README.md CHANGED
@@ -26,7 +26,7 @@ export function activate(ctx: ExtensionContext) {
26
26
  }
27
27
  ```
28
28
 
29
- 完整拓展还需根目录的`extension.json`声明来源外观与能力。`settingsSchema`和`connectionSettingsSchema`可由构建辅助生成清单设置字段。创建工程、当前1/0契约、生命周期、上报、设置、译文和发布见[作者指南](./DEVELOPMENT.md),此文件也包含在npm包里,可在安装目录直接读取。
29
+ 完整拓展还需根目录的`extension.json`声明来源外观与能力。`settingsSchema`和`connectionSettingsSchema`可由构建辅助生成清单设置字段。创建工程、契约小号与群聊作品解析、生命周期、上报、设置、译文和发布见[作者指南](./DEVELOPMENT.md),此文件也包含在npm包里,可在安装目录直接读取。
30
30
 
31
31
  ## Agent 开发入口
32
32
 
package/build.mjs CHANGED
@@ -3272,7 +3272,7 @@ const EXTENSION_IMAGE_MAX_CHARS = 32768;
3272
3272
  * ⚠️ 不带 `g`:几处共用这一个对象,带 `g` 的话 `test()` 会在两次调用之间记着 `lastIndex`。
3273
3273
  */
3274
3274
  const EXTENSION_IMAGE_DATA_URL_RE = /^data:image\/(?:png|jpeg|webp|svg\+xml);base64,[A-Za-z0-9+/]+=*$/;
3275
- // ../internal/lib/settings-fields-from-schema-C6Bl0zEt.mjs
3275
+ // ../internal/lib/settings-fields-from-schema-CpiuxNUl.mjs
3276
3276
  const VARIABLE_QUANTIFIER = String.raw`(?:[+*]|\{\d+,\d*\})`;
3277
3277
  const NESTED_QUANTIFIER = new RegExp(String.raw`\((?:\?[:=!][^)]*|[^)]*)${VARIABLE_QUANTIFIER}[^)]*\)\s*(?:[+*]|\{\d+(?:,\d*)?\})`);
3278
3278
  function hasOverlappingAlternationUnderQuantifier(src) {
@@ -3351,7 +3351,7 @@ const CREATOR_SEARCH_KINDS = [
3351
3351
  const EXTENSION_API_RANGE = Object.freeze({
3352
3352
  min: 1,
3353
3353
  current: 1,
3354
- revision: 0
3354
+ revision: 2
3355
3355
  });
3356
3356
  /** 这一档落不落在区间里(不看小号)。 */
3357
3357
  function tierAccepted(apiVersion, range) {
@@ -3663,6 +3663,11 @@ const SupportedFeaturesSchema = z.array(z.enum(EXTENSION_SOURCE_FEATURES)).min(1
3663
3663
  const PACKAGE_PATH_SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
3664
3664
  const PackagePathSchema = z.string().max(128).regex(new RegExp(`^${PACKAGE_PATH_SEGMENT}(?:/${PACKAGE_PATH_SEGMENT})*$`), { error: () => packageText("internal.schema.extension-manifest.22") });
3665
3665
  const ContributesSchema = z.strictObject({
3666
+ /** 宿主按完整域名和路径范围挑出候选,拓展没有观察群消息的入口。 */
3667
+ linkResolver: z.strictObject({ patterns: z.array(z.strictObject({
3668
+ host: z.string().max(253).regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
3669
+ pathPrefix: z.string().max(256).regex(/^\/(?:[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*\/?)?$/)
3670
+ })).min(1).max(32) }).optional(),
3666
3671
  push: z.strictObject({
3667
3672
  ...displayShape,
3668
3673
  /** 主人新建连接时要填的那几栏。桥那种「连接是挑出来的」可以不写。 */
@@ -3678,6 +3683,7 @@ const ContributesSchema = z.strictObject({
3678
3683
  creatorNoun: ShortNounSchema.optional(),
3679
3684
  /** 这个平台管外部 id 叫什么(如「账号」)。身份标签用它,不给就写平台名。 */
3680
3685
  externalIdNoun: ShortNounSchema.optional(),
3686
+ displayIdNoun: ShortNounSchema.optional(),
3681
3687
  /**
3682
3688
  * 搜人输入框收哪几种输入(id / 链接 / 名字);提示句由核心按这份声明拼,来源不自己写句子。拼句的
3683
3689
  * 叫法函数随第 4 期,在那之前面板对拓展一律用通用说法。
@@ -3706,6 +3712,9 @@ const ContributesSchema = z.strictObject({
3706
3712
  * 单开这一口的拓展在发行版里什么都不做。
3707
3713
  */
3708
3714
  devtools: z.strictObject({}).optional()
3715
+ }).refine((contributes) => !contributes.linkResolver || contributes.subscription, {
3716
+ path: ["linkResolver"],
3717
+ message: "linkResolver requires contributes.subscription"
3709
3718
  }).refine((contributes) => EXTENSION_PROVIDES.some((key) => contributes[key] !== void 0), { error: () => packageText("internal.schema.extension-manifest.23") });
3710
3719
  /**
3711
3720
  * 动作名 —— 它要进 URL(`POST /api/ext/:id/actions/:name`),所以只许小写字母开头的
@@ -3740,6 +3749,12 @@ const MANIFEST_SCHEMAS = { 1: z.strictObject({
3740
3749
  }).optional(),
3741
3750
  /** 开哪几口、每口的声明 —— `provides` 由它的键推出来。 */
3742
3751
  contributes: ContributesSchema
3752
+ }).refine((manifest) => !manifest.contributes.linkResolver || (manifest.apiRevision ?? 0) >= 1, {
3753
+ path: ["apiRevision"],
3754
+ message: "contributes.linkResolver requires apiRevision 1"
3755
+ }).refine((manifest) => !manifest.contributes.subscription?.displayIdNoun || (manifest.apiRevision ?? 0) >= 2, {
3756
+ path: ["apiRevision"],
3757
+ message: "contributes.subscription.displayIdNoun requires apiRevision 2"
3743
3758
  }) };
3744
3759
  /** 只读这一格 —— 其余部分长什么样要看它。 */
3745
3760
  const ApiVersionOnlySchema = z.object({ apiVersion: z.number().int().min(1) });
package/index.d.mts CHANGED
@@ -540,6 +540,14 @@ type AuthState = {
540
540
  } | {
541
541
  status: "confirming";
542
542
  message?: string;
543
+ /** Public challenge only. The upstream ticket and submitted code stay in the source's session. */
544
+ verification?: {
545
+ kind: "sms";
546
+ attemptId: string;
547
+ } | {
548
+ kind: "external";
549
+ url: string;
550
+ };
543
551
  } | {
544
552
  status: "logged-in";
545
553
  loggedInAt: string;
@@ -1579,6 +1587,29 @@ interface SourceContext extends IntegrationContext {
1579
1587
  */
1580
1588
  registerAiToolProvider(provider: AiToolProvider): Disposable;
1581
1589
  }
1590
+ /** 来源登录着的账号:名字必有;头像抓进图库之后才有 `avatar`(图库引用,不是平台的图片地址)。 */
1591
+ interface SourceAccount {
1592
+ name: string;
1593
+ avatar?: ImageRef;
1594
+ }
1595
+ /**
1596
+ * 要登录才用得了的来源交的登录口(ADR-0021 决策 45)。只有扫码这一种登录办法;等第一个有两种登录办法的来源
1597
+ * 再加 `methods` 与 `beginLogin` 的参数。没有「刷新」:续期是来源自己的事。
1598
+ */
1599
+ interface SourceAuth {
1600
+ /** 发起一次扫码登录。成功后二维码在 `state()` 里;已有一次在进行时重新开始、换一张新码。 */
1601
+ beginLogin(): Promise<Result>;
1602
+ /** Answer only the current SMS challenge. A replaced attempt must never accept its old answer. */
1603
+ submitVerification?(attemptId: string, code: string): Promise<Result>;
1604
+ /** 忘掉登录。没登录时也能调。不碰主密钥。 */
1605
+ logout(): Promise<Result>;
1606
+ /** 此刻的状态,同步、不出网。 */
1607
+ state(): AuthState;
1608
+ /** 登录着的账号;没登录或还没取到是 `null`。头像抓进图库之后才有 `avatar`。 */
1609
+ account?(): SourceAccount | null;
1610
+ /** 状态或账号可能变了就叫一声;要做事自己再读 `state()` / `account()`。 */
1611
+ onChange(fn: () => void): Disposable;
1612
+ }
1582
1613
  /** 来源此刻的健康状况:给 `status` 指令(以后还有健康卡)的一行字。 */
1583
1614
  interface SourceHealth {
1584
1615
  summary: string;
@@ -1590,6 +1621,8 @@ interface SourceHealth {
1590
1621
  interface CreatorProfileReport {
1591
1622
  /** 创作者的名字。 */
1592
1623
  name: string;
1624
+ /** 用户可读账号,与稳定身份externalId分开。省略沿用,空串清除;最多256字。 */
1625
+ displayId?: string;
1593
1626
  /** 图库引用;来源先把平台头像抓进图库,再交引用。 */
1594
1627
  avatar?: ImageRef;
1595
1628
  /** 简介或签名。 */
@@ -1944,6 +1977,12 @@ type ExtensionPostReport = Simplify<Pick<PostReport, "postId" | "url"> & {
1944
1977
  }>;
1945
1978
  }>;
1946
1979
  }>;
1980
+ /** 群聊作品无须先有订阅,作者名随作品返回。postId 是长短链接共用的规范作品 ID。 */
1981
+ type ExtensionLinkPreview = Simplify<Omit<ExtensionPostReport, "post"> & {
1982
+ post: Simplify<Omit<ExtensionPostReport["post"], "creator"> & {
1983
+ creator: Simplify<SubscriptionCreator & Required<Pick<SubscriptionCreator, "name">>>;
1984
+ }>;
1985
+ }>;
1947
1986
  /**
1948
1987
  * 从核心 `LiveDetails` 推导直播详情:只挑拓展开放的格,并把作者换成可缺的 {@link SubscriptionCreator}、
1949
1988
  * 封面换成图库引用。
@@ -2008,6 +2047,10 @@ interface SourceHandle {
2008
2047
  * 订阅源代码那一半。清单负责外观与能力声明;这里的成员按表拿,未开放的成员即使给了也不认。
2009
2048
  */
2010
2049
  interface SourceDef {
2050
+ /** 清单声明 contributes.linkResolver 时必交。只接收命中的单条网址,来源停用时取消。 */
2051
+ resolveLink?(url: string, signal: AbortSignal): Promise<Result<ExtensionLinkPreview>>;
2052
+ /** System account login. Requires manifest apiRevision >= 1. */
2053
+ readonly auth?: SourceAuth;
2011
2054
  /**
2012
2055
  * 启动来源。拿到名单与三种上报口;这里可以同步返回,也可以回 Promise。
2013
2056
  * `stop()` 之后不许再上报。
@@ -2076,6 +2119,12 @@ interface ExtensionI18n {
2076
2119
  * 更难 debug(面板写着「已停用」,定时器还在跑)。
2077
2120
  */
2078
2121
  interface ExtensionContext extends IntegrationContext {
2122
+ /** 独立的内存登录会话。快照包含凭据,只经 secrets 显式保存;坏快照抛 TypeError。 */
2123
+ createCookieSession(snapshot?: string): {
2124
+ header(url: string): string;
2125
+ ingest(url: string, line: string): void;
2126
+ snapshot(): string;
2127
+ };
2079
2128
  /** 它自己的 id —— 同时是挂载点、装载目录与记账键那一段。 */
2080
2129
  readonly id: string;
2081
2130
  /** 宿主**当前**的契约档位(它认的区间的上沿)。拓展自己也可能要按它分叉。 */
@@ -2219,4 +2268,4 @@ interface ExtensionDevtoolsContext extends ExtensionContext {
2219
2268
  */
2220
2269
  mountUrl(): string | undefined;
2221
2270
  }
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 };
2271
+ export { type AuthState, 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 ExtensionLinkPreview, 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 SourceAccount, type SourceAuth, type SourceDef, type SourceHandle, type SourceHealth, type SourceSubscriptionView, type SubscriptionCreator, type TextValues, type WebSocketLike, type WebSocketOptions, fail, ok };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@bilibili-notify/extension",
3
3
  "description": "Public contract and build helpers for bilibili-notify extensions",
4
- "version": "0.1.0-alpha.0",
4
+ "version": "0.1.0-alpha.1",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "https://github.com/Akokk0/bilibili-notify"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: bn-extension-development
3
- description: Develop and fix standalone bilibili-notify extensions using the public SDK. Use for subscription sources, push adapters, ctx integration, extension packaging, and release dry-runs; not for changing the BN host itself.
3
+ description: Develop and fix bilibili-notify extensions using the public SDK, in standalone projects or official workspace extensions. Use for sources, push adapters, ctx integration, packaging, and release dry-runs; not for changing the BN host itself.
4
4
  ---
5
5
 
6
6
  # BN 拓展开发
@@ -9,22 +9,27 @@ description: Develop and fix standalone bilibili-notify extensions using the pub
9
9
 
10
10
  ## 定位契约
11
11
 
12
- 从项目根读取 `extension.json`、`package.json` 与 `README.md`,确认声明的是订阅来源、推送适配器还是两者,以及当前宿主兼容要求。
12
+ 从拓展工程根读取 `extension.json`、`package.json` 与 `README.md`,确认声明的是订阅来源、推送适配器还是两者,以及当前宿主兼容要求。先判断它是创建器生成的仓外工程,还是 BN 主仓 `extensions/<id>/` 中的官方拓展;命令与发行方式使用各自工程已定义的入口。
13
13
 
14
- 读取已安装 SDK 的 `node_modules/@bilibili-notify/extension/AGENT_GUIDE.md`。具体实现再查同目录的 `DEVELOPMENT.md`、`index.d.mts` 和 `build.d.mts`;这些资料随包提供,不需要私有 BN 主仓。依赖尚未安装时先执行 `vp install`。
14
+ 读取该工程实际使用的 SDK 的 `AGENT_GUIDE.md`。仓外工程的入口是 `node_modules/@bilibili-notify/extension/AGENT_GUIDE.md`,workspace 工程读取本仓 SDK 对应文档。具体实现再查同一 SDK 的 `DEVELOPMENT.md`、`index.d.mts` 和 `build.d.mts`;仓外所需资料随包提供,不依赖私有 BN 主仓。依赖尚未安装时先执行 `vp install`,所用 API 以实际安装的 SDK 与宿主兼容范围为准。
15
15
 
16
16
  ## 实现与验证
17
17
 
18
18
  1. 把请求转换为公开可观察的行为,明确正常结果、失败和停用后的表现。沿现有公开测试入口先复现或补刻画,再修改;测试使用合成输入和受控的上游响应。
19
19
  2. 订阅来源使用 `SourceDef`,推送适配器使用 `PlatformAdapterDef`;按已安装类型接线,副作用经 ctx。新增能力与当前清单声明对应,避免在契约之外接入宿主内部模块。
20
20
  3. 运行实际构建入口,核对具名 `activate`、从 schema 导出的清单字段和自包含产物。接口类型通过不代表上报载荷、收尾或重试行为正确,按改动验证这些行为。
21
- 4. JS/TS 操作经 vp;执行项目脚本用 `vp run`。定向验证改动后运行 `vp run verify`,让 lint、格式、类型、测试、构建和 ZIP 校验共同通过。测试从 `vite-plus/test` 导入运行入口。
21
+ 4. JS/TS 操作经 vp;执行项目脚本用 `vp run`,测试从 `vite-plus/test` 导入。创建器工程定向验证后运行已有的 `vp run verify`;其他工程按 `package.json` 和工程指引执行对应的 lint、格式、类型、测试、构建与 ZIP 校验。官方拓展使用主仓的包过滤和打包入口,不凭空添加 `verify` 脚本。
22
22
 
23
- 需要宿主联调时,读SDK作者指南的“源码拓展联调”。安装拓展依赖后,用`vp dlx @bilibili-notify/bn@alpha dev`启动专用开发宿主,从拓展页挂载源码工程绝对路径;BN负责加载src/index.ts、监听和重载,工程无需先构建或单独启动。多个工程挂到同一宿主。检查源码预检失败仍保留旧实例、修改只重载对应项、解除不删除源码及停用语义。记录所用宿主版本和用途,结束时收掉自己的挂载和服务。
23
+ 需要宿主联调时,读 SDK 作者指南的“源码拓展联调”。优先复用用户指定且兼容的开发宿主;需要新实例时,按实际发行状态选可用版本,对应包已发布时使用 `vp dlx @bilibili-notify/bn@alpha dev`;尚不可用时使用用户提供的本地成品,或按 BN 主仓指引启动源码宿主。源码开发 BN 使用主仓 `vp run dev:apps`,不把“源码已实现”当成“npm 包已发布”。
24
+
25
+ 安装拓展依赖后,从拓展页挂载源码工程绝对路径;BN 负责加载 `src/index.ts`、监听和重载,工程无需先构建或单独启动。多个工程可挂到同一宿主。按改动核对预检失败保留旧实例、只重载对应项、解除不删除源码及停用语义。记录宿主版本和用途;结束时收掉自己新增的挂载和服务,保留用户原有实例及挂载。
24
26
 
25
27
  ## 打包与发布
26
28
 
27
- 仅做开发或打包时,以本地产物和验证结果交付。用户要求发行时,先读项目 README 的发布与恢复流程,核对 `.bn/marketplace.json`、清单版本和目标仓库,再运行 `vp run release --tag v<清单版本> --dry-run`。
29
+ 仅做开发或打包时,以本地产物和验证结果交付。用户要求发行时,按工程类型读取对应流程:
30
+
31
+ - 仓外创建器工程使用 `.bn-extension/marketplace.json`;在 GitHub Actions 核对 `GITHUB_REPOSITORY`,在本地核对 `git remote get-url --push origin`,按 README 运行已有 `vp run release --tag v<清单版本> --dry-run`。
32
+ - BN 主仓的官方拓展使用主仓 `docs/agents/extension-marketplace.md`,无需创建 `.bn-extension/`;清单、更新记录与 `extension/<id>@<版本>` tag 对齐,沿官方工作流预检和发布。
28
33
 
29
34
  dry-run 通过只证明本地校验与预览完成。真实发布按用户已授权的目标和版本执行;不要把“运行 dry-run”扩成发布授权。发布器负责版本 ZIP、校验值与固定索引的顺序;已有版本字节冲突时使用新版本,按文档接续中断任务。
30
35