@bilibili-notify/extension 0.1.0-alpha.0 → 0.1.0-alpha.2

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`;保存自己需要等待的任务并收尾 |
@@ -111,12 +156,16 @@ export function activate(ctx: ExtensionContext): void {
111
156
 
112
157
  推送适配器通过`ctx.registerPlatformAdapter`登记,并在清单声明`contributes.push`。自己的连接及入站能力由适配器`start`收到的上下文提供;适配器键由宿主填成拓展id。它与订阅来源是两套接口,具体使用`PlatformAdapterDef`及其公开注释。
113
158
 
159
+ 可选实现`createTestPayload(connection, destination, kind, samples)`,让推送目标页测试真实能力。使用宿主提供的图片、SILK语音和文字构造`NotificationPayload`,不在此方法发送;不支持时返回`unsupported`,不能发送纯文本替代品。省略此方法的旧适配器仍可测试普通文本。接收测试由宿主经既有入站入口核对短时测试码,适配器不用另开接口。明确的`audio`和`markdown`载荷不应降级为普通文本。
160
+
114
161
  ## 失败与译文
115
162
 
116
163
  可预期失败返回`fail(code, message)`,成功返回`ok(...)`。`code`使用SDK的标准失败码;上游自己的错误码放`upstreamCode`。超时、限流、凭据失效与确实不存在分别处理;不要把所有错误都变成“找不到”。发送结果不明用`indeterminate`,不能自动重发。
117
164
 
118
165
  给人看的拓展文字放在`locales/zh-CN.json`、`zh-TW.json`、`en.json`、`ja.json`,使用`ctx.i18n.t(key, values)`现取,不缓存翻译结果。未提供译文的语言按宿主回落规则处理。作者、创作者、输入和上游诊断原文不作为翻译键。
119
166
 
167
+ 市场卡片复用这些文件里的`$manifest.name`和`$manifest.description`。当前版本的市场说明可写为普通译文键`marketplace.notes`;发布命令从实际构建的`dist/locales/`提取到索引的可选`locales`字段,不另建市场译文文件。缺项按“当前语言 → 简中 → 英文 → 默认文字”逐字段回落,历史CHANGELOG保留原文。
168
+
120
169
  ## 检查、安装与发布
121
170
 
122
171
  ```sh
@@ -132,6 +181,10 @@ vp run release --tag v0.1.0 --dry-run
132
181
 
133
182
  `verify`串起代码门禁、构建和打包;发布命令还复验Conventional Commits。ZIP与SHA256在`artifacts/`,可在BN拓展页上传安装。SDK版本变化不替你更改清单的宿主契约要求。
134
183
 
135
- 发布前更新根清单版本,提交修改,再打匹配的`v<版本>`标签并推送到自己的GitHub仓库。生成的Release工作流先以读取权限跑dry-run,成功后发布作业才取得`contents: write`;手动触发默认只验证。完整流程、`.bn/`字段和中断重跑方法见生成工程的README。
184
+ 市场作者名默认为拓展命名空间,可在市场配置的 `owner.name` 修改。创建时若已确定仓库,可选传 `--repository owner/repo`,以 GitHub 所有者作为作者名初值,并在初始化 Git 时设置 `origin`。
185
+
186
+ 准备发布时,GitHub Actions 从 `GITHUB_REPOSITORY` 取得目标仓库。本地预演和发布使用 `origin` 的推送地址。尚未设置时,先用 `git remote add origin <GitHub 仓库地址>` 添加,再用 `git remote get-url --push origin` 核对。
187
+
188
+ 发布前更新根清单版本,提交修改,再打匹配的 `v<版本>` 标签并推送到自己的 GitHub 仓库。生成的 Release 工作流先以读取权限跑 dry-run,成功后发布作业才取得 `contents: write`。手动触发默认只验证。完整流程和中断重跑方法见生成工程的 README。
136
189
 
137
190
  用户在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
@@ -70,6 +70,7 @@ function translate(dict, locale, key, values = {}) {
70
70
  const UNBOUND_LAYERS = {
71
71
  "zh-CN": {
72
72
  plain: {
73
+ "internal.settings.imageAllowedCidrs": "请填写有效的 IPv4 或 IPv6 CIDR 地址段,例如 198.18.0.0/16。",
73
74
  "internal.commands.aliasBlank": "别名不能为空或带首尾空格",
74
75
  "internal.commands.prefixBlank": "前缀不能是纯空白",
75
76
  "internal.commands.prefixLeadingSpace": "前缀不能以空白开头",
@@ -859,6 +860,7 @@ const UNBOUND_LAYERS = {
859
860
  },
860
861
  "zh-TW": {
861
862
  plain: {
863
+ "internal.settings.imageAllowedCidrs": "請填寫有效的 IPv4 或 IPv6 CIDR 網段,例如 198.18.0.0/16。",
862
864
  "storage.log.masterReadFailed": "主金鑰讀取失敗(非缺失),保留原檔案並停止載入",
863
865
  "storage.log.masterLoaded": "主金鑰已載入",
864
866
  "storage.log.masterInvalid": "主金鑰檔案格式無效(應為 64 位十六進位),將重新產生;原有憑證將無法解密,需重新登入或設定",
@@ -1647,6 +1649,7 @@ const UNBOUND_LAYERS = {
1647
1649
  }
1648
1650
  },
1649
1651
  en: { plain: {
1652
+ "internal.settings.imageAllowedCidrs": "Enter a valid IPv4 or IPv6 CIDR range, such as 198.18.0.0/16.",
1650
1653
  "storage.log.masterReadFailed": "Cannot read the existing master key; preserving the file and stopping the load",
1651
1654
  "storage.log.masterLoaded": "Master key loaded",
1652
1655
  "storage.log.masterInvalid": "Invalid master key file (expected 64 hexadecimal characters); regenerating it will make existing credentials unreadable and require login or configuration again",
@@ -2352,6 +2355,7 @@ const UNBOUND_LAYERS = {
2352
2355
  } },
2353
2356
  ja: {
2354
2357
  plain: {
2358
+ "internal.settings.imageAllowedCidrs": "198.18.0.0/16 など、有効な IPv4 または IPv6 の CIDR 範囲を入力してください。",
2355
2359
  "storage.log.masterReadFailed": "既存のマスターキーを読み取れません。ファイルを保持して読み込みを中止します",
2356
2360
  "storage.log.masterLoaded": "マスターキーを読み込みました",
2357
2361
  "storage.log.masterInvalid": "マスターキーファイルの形式が無効です(64 桁の16進数が必要)。再生成により既存の認証情報を復号できなくなるため、再ログインまたは再設定が必要です",
@@ -3272,7 +3276,7 @@ const EXTENSION_IMAGE_MAX_CHARS = 32768;
3272
3276
  * ⚠️ 不带 `g`:几处共用这一个对象,带 `g` 的话 `test()` 会在两次调用之间记着 `lastIndex`。
3273
3277
  */
3274
3278
  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
3279
+ // ../internal/lib/settings-fields-from-schema-CU2DEonf.mjs
3276
3280
  const VARIABLE_QUANTIFIER = String.raw`(?:[+*]|\{\d+,\d*\})`;
3277
3281
  const NESTED_QUANTIFIER = new RegExp(String.raw`\((?:\?[:=!][^)]*|[^)]*)${VARIABLE_QUANTIFIER}[^)]*\)\s*(?:[+*]|\{\d+(?:,\d*)?\})`);
3278
3282
  function hasOverlappingAlternationUnderQuantifier(src) {
@@ -3351,7 +3355,7 @@ const CREATOR_SEARCH_KINDS = [
3351
3355
  const EXTENSION_API_RANGE = Object.freeze({
3352
3356
  min: 1,
3353
3357
  current: 1,
3354
- revision: 0
3358
+ revision: 2
3355
3359
  });
3356
3360
  /** 这一档落不落在区间里(不看小号)。 */
3357
3361
  function tierAccepted(apiVersion, range) {
@@ -3663,6 +3667,11 @@ const SupportedFeaturesSchema = z.array(z.enum(EXTENSION_SOURCE_FEATURES)).min(1
3663
3667
  const PACKAGE_PATH_SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
3664
3668
  const PackagePathSchema = z.string().max(128).regex(new RegExp(`^${PACKAGE_PATH_SEGMENT}(?:/${PACKAGE_PATH_SEGMENT})*$`), { error: () => packageText("internal.schema.extension-manifest.22") });
3665
3669
  const ContributesSchema = z.strictObject({
3670
+ /** 宿主按完整域名和路径范围挑出候选,拓展没有观察群消息的入口。 */
3671
+ linkResolver: z.strictObject({ patterns: z.array(z.strictObject({
3672
+ host: z.string().max(253).regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
3673
+ pathPrefix: z.string().max(256).regex(/^\/(?:[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*\/?)?$/)
3674
+ })).min(1).max(32) }).optional(),
3666
3675
  push: z.strictObject({
3667
3676
  ...displayShape,
3668
3677
  /** 主人新建连接时要填的那几栏。桥那种「连接是挑出来的」可以不写。 */
@@ -3678,6 +3687,7 @@ const ContributesSchema = z.strictObject({
3678
3687
  creatorNoun: ShortNounSchema.optional(),
3679
3688
  /** 这个平台管外部 id 叫什么(如「账号」)。身份标签用它,不给就写平台名。 */
3680
3689
  externalIdNoun: ShortNounSchema.optional(),
3690
+ displayIdNoun: ShortNounSchema.optional(),
3681
3691
  /**
3682
3692
  * 搜人输入框收哪几种输入(id / 链接 / 名字);提示句由核心按这份声明拼,来源不自己写句子。拼句的
3683
3693
  * 叫法函数随第 4 期,在那之前面板对拓展一律用通用说法。
@@ -3706,6 +3716,9 @@ const ContributesSchema = z.strictObject({
3706
3716
  * 单开这一口的拓展在发行版里什么都不做。
3707
3717
  */
3708
3718
  devtools: z.strictObject({}).optional()
3719
+ }).refine((contributes) => !contributes.linkResolver || contributes.subscription, {
3720
+ path: ["linkResolver"],
3721
+ message: "linkResolver requires contributes.subscription"
3709
3722
  }).refine((contributes) => EXTENSION_PROVIDES.some((key) => contributes[key] !== void 0), { error: () => packageText("internal.schema.extension-manifest.23") });
3710
3723
  /**
3711
3724
  * 动作名 —— 它要进 URL(`POST /api/ext/:id/actions/:name`),所以只许小写字母开头的
@@ -3740,6 +3753,12 @@ const MANIFEST_SCHEMAS = { 1: z.strictObject({
3740
3753
  }).optional(),
3741
3754
  /** 开哪几口、每口的声明 —— `provides` 由它的键推出来。 */
3742
3755
  contributes: ContributesSchema
3756
+ }).refine((manifest) => !manifest.contributes.linkResolver || (manifest.apiRevision ?? 0) >= 1, {
3757
+ path: ["apiRevision"],
3758
+ message: "contributes.linkResolver requires apiRevision 1"
3759
+ }).refine((manifest) => !manifest.contributes.subscription?.displayIdNoun || (manifest.apiRevision ?? 0) >= 2, {
3760
+ path: ["apiRevision"],
3761
+ message: "contributes.subscription.displayIdNoun requires apiRevision 2"
3743
3762
  }) };
3744
3763
  /** 只读这一格 —— 其余部分长什么样要看它。 */
3745
3764
  const ApiVersionOnlySchema = z.object({ apiVersion: z.number().int().min(1) });
package/index.d.mts CHANGED
@@ -239,6 +239,10 @@ type DestinationRef = Pick<Extract<PushTarget, {
239
239
  */
240
240
  declare const PUSH_TARGET_SCOPES: readonly ["group", "private", "channel"];
241
241
  type PushTargetScope = (typeof PUSH_TARGET_SCOPES)[number];
242
+ /** 面板逐项测试的词表;`inbound` 需要回传,其他项目各发送一次真实样例。 */
243
+ declare const TARGET_TEST_KINDS: readonly ["text", "atAll", "nativeShare", "image", "imageGroup", "forward", "audio", "markdown", "inbound"];
244
+ type TargetTestKind = (typeof TARGET_TEST_KINDS)[number];
245
+ type SendTestKind = Exclude<TargetTestKind, "inbound">;
242
246
  /**
243
247
  * 图库引用形状 —— `<sha256>.<ext>` 的扩展名和校验正则。
244
248
  *
@@ -540,6 +544,14 @@ type AuthState = {
540
544
  } | {
541
545
  status: "confirming";
542
546
  message?: string;
547
+ /** Public challenge only. The upstream ticket and submitted code stay in the source's session. */
548
+ verification?: {
549
+ kind: "sms";
550
+ attemptId: string;
551
+ } | {
552
+ kind: "external";
553
+ url: string;
554
+ };
543
555
  } | {
544
556
  status: "logged-in";
545
557
  loggedInAt: string;
@@ -847,6 +859,22 @@ interface SettingsFieldMeta {
847
859
  type ProbeResult = Result<{
848
860
  latencyMs: number;
849
861
  }>;
862
+ /** 宿主提供的自包含测试素材。适配器只编载荷;真正发送仍由 TargetDispatcher 调 send。 */
863
+ interface PlatformTestOptions {
864
+ text: string;
865
+ image: {
866
+ buffer: Buffer;
867
+ mime: string;
868
+ };
869
+ secondImage: {
870
+ buffer: Buffer;
871
+ mime: string;
872
+ };
873
+ audio: {
874
+ buffer: Buffer;
875
+ mime: "audio/silk";
876
+ };
877
+ }
850
878
  /**
851
879
  * 一个平台实现 —— 认领哪些连接、怎么建连、报文怎么编、地址怎么解、有什么能力。
852
880
  * 矩阵({@link TargetDispatcher})拿它按连接的 `adapterKey` 找。
@@ -908,12 +936,22 @@ interface PlatformAdapter {
908
936
  isAvailable(connection: Connection, destination: DestinationRef): boolean;
909
937
  /** Deliver `payload` to `destination` over `connection`. 群还是私聊只看 `destination.scope`。 */
910
938
  send(connection: Connection, destination: DestinationRef, payload: NotificationPayload): Promise<DeliveryResult>;
939
+ /** 构造对应能力的真实样例;不支持时拒绝,不用文本替代。没有此成员的旧适配器仍可测试普通文本。 */
940
+ createTestPayload?(connection: Connection, destination: DestinationRef, kind: SendTestKind, samples: PlatformTestOptions): Result<{
941
+ payload: NotificationPayload;
942
+ }>;
911
943
  /**
912
944
  * 这条连接的能力(三态;探测结果读缓存,同步读、不打网络)。内置适配器都实现;没实现的
913
945
  * (老的拓展适配器)各项按「还不知道」算,怎么对待「还不知道」见 internal 的
914
946
  * `shouldSendAtAll` / `canReceiveReply` / `listsForLinkPreview`。
915
947
  */
916
948
  capabilities?(connection: Connection): ConnectionCapabilities;
949
+ /** 宿主只读查询会话内身份与使用记录;暂不向拓展开放。 */
950
+ fetchDestinationStatus?(connection: Connection, destination: DestinationRef, signal: AbortSignal, options?: {
951
+ refresh?: boolean;
952
+ }): Promise<Result<{
953
+ status: DestinationStatus;
954
+ }>>;
917
955
  /** 主动探一次能力,结果进缓存。连上时、健康探测时、用之前都可以叫;零副作用。 */
918
956
  probeCapabilities?(connection: Connection): Promise<ConnectionCapabilities>;
919
957
  /**
@@ -1270,6 +1308,11 @@ interface NativeShare {
1270
1308
  type NotificationPayload = {
1271
1309
  kind: "text";
1272
1310
  text: string;
1311
+ } |
1312
+ /** 明确要求原生 Markdown;不支持的适配器拒绝,不剥成纯文字冒充成功。 */
1313
+ {
1314
+ kind: "markdown";
1315
+ text: string;
1273
1316
  } | {
1274
1317
  kind: "image";
1275
1318
  image: {
@@ -1277,6 +1320,14 @@ type NotificationPayload = {
1277
1320
  mime: string;
1278
1321
  };
1279
1322
  caption?: string;
1323
+ } |
1324
+ /** 单条语音。当前发送实现接收 SILK;格式转换由调用方完成,适配器不降级成文字。 */
1325
+ {
1326
+ kind: "audio";
1327
+ audio: {
1328
+ buffer: Buffer;
1329
+ mime: "audio/silk";
1330
+ };
1280
1331
  } | {
1281
1332
  kind: "composite";
1282
1333
  segments: PayloadSegment[];
@@ -1328,7 +1379,7 @@ type DeliveryResult = Result<{
1328
1379
  * 后者是结论;读它的地方各自决定「还不知道」时怎么办(见 `ConnectionCapabilities` 各格的注释),
1329
1380
  * 面板上两者也要分开显示。
1330
1381
  *
1331
- * - `supported`:确认支持,`checkedAt` 是确认的时刻。
1382
+ * - `supported`:确认支持,`checkedAt` 是确认的时刻,可用 `reason` 说明适用范围。
1332
1383
  * - `unsupported`:确认不支持,`reason` 给人看的一句话,`checkedAt` 是确认的时刻。
1333
1384
  * - `unknown`:还没探出来(没探过、连不上、对面没报),`reason` 可选。
1334
1385
  *
@@ -1337,6 +1388,7 @@ type DeliveryResult = Result<{
1337
1388
  type CapabilitySupport = {
1338
1389
  state: "supported";
1339
1390
  checkedAt: string;
1391
+ reason?: string;
1340
1392
  } | {
1341
1393
  state: "unsupported";
1342
1394
  reason: string;
@@ -1345,8 +1397,32 @@ type CapabilitySupport = {
1345
1397
  state: "unknown";
1346
1398
  reason?: string;
1347
1399
  };
1400
+ /** 机器人在某个会话里的状态,独立于整条连接的能力。 */
1401
+ interface DestinationStatus {
1402
+ role: {
1403
+ state: "known";
1404
+ value: "member" | "admin" | "owner";
1405
+ checkedAt: string;
1406
+ } | {
1407
+ state: "unknown";
1408
+ reason?: string;
1409
+ };
1410
+ /** BN 的当日发送记录,不是平台返回的剩余额度。 */
1411
+ atAllUsage?: {
1412
+ state: "not-recorded" | "used" | "exhausted" | "indeterminate";
1413
+ date: string;
1414
+ timezone: string;
1415
+ source: "bn";
1416
+ };
1417
+ }
1348
1418
  /** 一条连接的能力快照,由这条连接的适配器回答。 */
1349
1419
  interface ConnectionCapabilities {
1420
+ /** 额外展示能力;旧适配器未报告时按未知,不用于推断群内权限。 */
1421
+ image?: CapabilitySupport;
1422
+ imageGroup?: CapabilitySupport;
1423
+ forward?: CapabilitySupport;
1424
+ audio?: CapabilitySupport;
1425
+ markdown?: CapabilitySupport;
1350
1426
  /**
1351
1427
  * 能不能单发 @全体。派发器的 `supportsAtAll` 与订阅抽屉里的 @全体 开关读它;
1352
1428
  * 「还不知道」时**照发**(发错只是多一条消息)。
@@ -1579,6 +1655,29 @@ interface SourceContext extends IntegrationContext {
1579
1655
  */
1580
1656
  registerAiToolProvider(provider: AiToolProvider): Disposable;
1581
1657
  }
1658
+ /** 来源登录着的账号:名字必有;头像抓进图库之后才有 `avatar`(图库引用,不是平台的图片地址)。 */
1659
+ interface SourceAccount {
1660
+ name: string;
1661
+ avatar?: ImageRef;
1662
+ }
1663
+ /**
1664
+ * 要登录才用得了的来源交的登录口(ADR-0021 决策 45)。只有扫码这一种登录办法;等第一个有两种登录办法的来源
1665
+ * 再加 `methods` 与 `beginLogin` 的参数。没有「刷新」:续期是来源自己的事。
1666
+ */
1667
+ interface SourceAuth {
1668
+ /** 发起一次扫码登录。成功后二维码在 `state()` 里;已有一次在进行时重新开始、换一张新码。 */
1669
+ beginLogin(): Promise<Result>;
1670
+ /** Answer only the current SMS challenge. A replaced attempt must never accept its old answer. */
1671
+ submitVerification?(attemptId: string, code: string): Promise<Result>;
1672
+ /** 忘掉登录。没登录时也能调。不碰主密钥。 */
1673
+ logout(): Promise<Result>;
1674
+ /** 此刻的状态,同步、不出网。 */
1675
+ state(): AuthState;
1676
+ /** 登录着的账号;没登录或还没取到是 `null`。头像抓进图库之后才有 `avatar`。 */
1677
+ account?(): SourceAccount | null;
1678
+ /** 状态或账号可能变了就叫一声;要做事自己再读 `state()` / `account()`。 */
1679
+ onChange(fn: () => void): Disposable;
1680
+ }
1582
1681
  /** 来源此刻的健康状况:给 `status` 指令(以后还有健康卡)的一行字。 */
1583
1682
  interface SourceHealth {
1584
1683
  summary: string;
@@ -1590,6 +1689,8 @@ interface SourceHealth {
1590
1689
  interface CreatorProfileReport {
1591
1690
  /** 创作者的名字。 */
1592
1691
  name: string;
1692
+ /** 用户可读账号,与稳定身份externalId分开。省略沿用,空串清除;最多256字。 */
1693
+ displayId?: string;
1593
1694
  /** 图库引用;来源先把平台头像抓进图库,再交引用。 */
1594
1695
  avatar?: ImageRef;
1595
1696
  /** 简介或签名。 */
@@ -1901,7 +2002,7 @@ type ExtensionUpgradeHandler = (upgrade: ExtensionUpgrade) => void;
1901
2002
  *
1902
2003
  * `listAddressCandidates` 与 `connectionAuth` 不对拓展开放(ADR-0024 决策 11),类型里排除,宿主运行时也会摘掉。
1903
2004
  */
1904
- type PlatformAdapterDef = Simplify<Pick<PlatformAdapter, "probe" | "start" | "stop" | "isAvailable" | "send" | "capabilities" | "probeCapabilities" | "settingsSchema" | "listConnectionCandidates">>;
2005
+ type PlatformAdapterDef = Simplify<Pick<PlatformAdapter, "probe" | "start" | "stop" | "isAvailable" | "send" | "createTestPayload" | "capabilities" | "probeCapabilities" | "settingsSchema" | "listConnectionCandidates">>;
1905
2006
  /** 注册完一个平台适配器之后拿到的把手。 */
1906
2007
  interface PlatformAdapterHandle {
1907
2008
  /** 注销适配器;幂等,调用后不再接收消息,也不再发送。 */
@@ -1944,6 +2045,12 @@ type ExtensionPostReport = Simplify<Pick<PostReport, "postId" | "url"> & {
1944
2045
  }>;
1945
2046
  }>;
1946
2047
  }>;
2048
+ /** 群聊作品无须先有订阅,作者名随作品返回。postId 是长短链接共用的规范作品 ID。 */
2049
+ type ExtensionLinkPreview = Simplify<Omit<ExtensionPostReport, "post"> & {
2050
+ post: Simplify<Omit<ExtensionPostReport["post"], "creator"> & {
2051
+ creator: Simplify<SubscriptionCreator & Required<Pick<SubscriptionCreator, "name">>>;
2052
+ }>;
2053
+ }>;
1947
2054
  /**
1948
2055
  * 从核心 `LiveDetails` 推导直播详情:只挑拓展开放的格,并把作者换成可缺的 {@link SubscriptionCreator}、
1949
2056
  * 封面换成图库引用。
@@ -2008,6 +2115,10 @@ interface SourceHandle {
2008
2115
  * 订阅源代码那一半。清单负责外观与能力声明;这里的成员按表拿,未开放的成员即使给了也不认。
2009
2116
  */
2010
2117
  interface SourceDef {
2118
+ /** 清单声明 contributes.linkResolver 时必交。只接收命中的单条网址,来源停用时取消。 */
2119
+ resolveLink?(url: string, signal: AbortSignal): Promise<Result<ExtensionLinkPreview>>;
2120
+ /** System account login. Requires manifest apiRevision >= 1. */
2121
+ readonly auth?: SourceAuth;
2011
2122
  /**
2012
2123
  * 启动来源。拿到名单与三种上报口;这里可以同步返回,也可以回 Promise。
2013
2124
  * `stop()` 之后不许再上报。
@@ -2076,6 +2187,12 @@ interface ExtensionI18n {
2076
2187
  * 更难 debug(面板写着「已停用」,定时器还在跑)。
2077
2188
  */
2078
2189
  interface ExtensionContext extends IntegrationContext {
2190
+ /** 独立的内存登录会话。快照包含凭据,只经 secrets 显式保存;坏快照抛 TypeError。 */
2191
+ createCookieSession(snapshot?: string): {
2192
+ header(url: string): string;
2193
+ ingest(url: string, line: string): void;
2194
+ snapshot(): string;
2195
+ };
2079
2196
  /** 它自己的 id —— 同时是挂载点、装载目录与记账键那一段。 */
2080
2197
  readonly id: string;
2081
2198
  /** 宿主**当前**的契约档位(它认的区间的上沿)。拓展自己也可能要按它分叉。 */
@@ -2219,4 +2336,4 @@ interface ExtensionDevtoolsContext extends ExtensionContext {
2219
2336
  */
2220
2337
  mountUrl(): string | undefined;
2221
2338
  }
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 };
2339
+ 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 PlatformTestOptions, type ProbeResult, type PushTarget, type PushTargetScope, type Result, type SendTestKind, 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.2",
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