@bilibili-notify/extension 0.0.0-stage → 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 ADDED
@@ -0,0 +1,36 @@
1
+ # BN 拓展:agent 契约指引
2
+
3
+ 实现细节查[作者指南](DEVELOPMENT.md)。准确的接口字段以当前安装版本的 `index.d.mts` 和 `build.d.mts` 为准;SDK 的 npm 版本与清单中的宿主 API 版本分别管理。
4
+
5
+ ## 入口与构建
6
+
7
+ - 运行入口具名导出 `activate(ctx: ExtensionContext)`。默认对象里的 `activate` 不是宿主入口。
8
+ - 运行代码只从 `@bilibili-notify/extension` 获取 BN 契约;`/build` 只用于根构建配置。使用公开类型,不从私有宿主模块补接口。
9
+ - 模块顶层只定义规则和函数。构建插件会导入入口,副作用在激活或来源、适配器生命周期中开始。
10
+ - `settingsSchema`、`connectionSettingsSchema` 由入口导出,构建插件生成清单字段;同一套设置规则同时交给 ctx,不维护第二份字段表。
11
+ - 产物是自包含的 `index.mjs`,运行时没有独立的 `node_modules`。增加依赖后核对构建产物是否仍能独立导入。
12
+ - 联调按作者指南的“源码拓展联调”:通过`vp dlx @bilibili-notify/bn@alpha dev`启动开发宿主,从拓展页挂载已安装依赖的源码工程;BN直接读取src/index.ts并负责监听、局部重载和收尾。拓展工程没有独立dev/start命令,生产才构建;自动重载不会替你启用停用项。
13
+
14
+ ## 契约查找
15
+
16
+ | 任务 | 从公开类型开始 |
17
+ | ------------------------------ | ---------------------------------------------------------------- |
18
+ | 搜索创作者、获取资料、轮询订阅 | `SourceDef`、`ExtensionSourceContext` |
19
+ | 群聊作品链接与长短链冷却 | `contributes.linkResolver`、`SourceDef.resolveLink`、`ExtensionLinkPreview` |
20
+ | 作品和直播上报 | `ExtensionPostReport`、`ExtensionLiveSignalReport` |
21
+ | 推送出口、探测和发送 | `PlatformAdapterDef`、`PlatformAdapterContext`、`DeliveryResult` |
22
+ | 设置及设置页动作 | `SettingsReader`、`ExtensionContext`、`ExtensionView` |
23
+
24
+ ## 容易误用的边界
25
+
26
+ - `settings.get()` 返回 `Result<{ settings }>`;先处理失败,再读 `result.settings`。
27
+ - 请求、WebSocket、图片、定时器、状态、凭据与日志经 ctx;状态写入也返回 Result,检查写入结果。凭据存 `ctx.secrets`,临时凭据先交 `ctx.redact`。
28
+ - 来源只持有 `externalId`,用上报接口交给宿主;订阅 UUID、规则、路由、发送和历史由宿主负责。上报返回 `void`,不是发送回执;直播 `status` 不触发推送。
29
+ - 可读账号用 `displayId`,稳定身份仍用 `externalId`;字段语义、叫法与最低宿主修订号见作者指南“展示账号”。
30
+ - `stop()` 先停止新工作与上报;宿主随后中止上下文信号并收尾。不要在 `stop()` 里无限等待只能靠后续中止信号结束的任务。
31
+ - 成功用 `ok`,预期失败用 `fail` 和标准失败码。发送结果不明用 `indeterminate`,不能当作未发送而自动重试。
32
+ - 展示文字由 `ctx.i18n.t` 现取;用户输入、创作者原文及上游诊断不改写成翻译键。
33
+
34
+ ## 能力缺口
35
+
36
+ 当前 SDK 没有的能力先说明具体使用场景和缺少的契约,不借私有 import、直接修改宿主配置或伪造成功结果绕过。拓展清单、SDK 类型和宿主版本需要共同满足兼容性。
package/DEVELOPMENT.md ADDED
@@ -0,0 +1,188 @@
1
+ # 拓展作者指南
2
+
3
+ 本指南随SDK的npm包分发,安装后可直接读取,不需要访问BN主仓。公开类型的完整字段和注释在`index.d.mts`,构建辅助在`build.d.mts`。
4
+
5
+ ## 版本与工程
6
+
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
+
9
+ 创建器默认生成独立Git工程、示例来源、完整vp命令、锁文件、提交hooks与GitHub Actions:
10
+
11
+ ```sh
12
+ pnpm create bn-ext@alpha
13
+ # 也可用 npm create bn-ext@alpha
14
+ cd my-extension
15
+ vp run verify
16
+ git add .
17
+ git commit -m "feat: create extension"
18
+ ```
19
+
20
+ 创建器使用`.node-version`固定Node,`packageManager`固定包管理器,开发依赖也固定版本。后续克隆用`vp install --frozen-lockfile`。若使用`--no-git`,先在工程根初始化自己的Git仓库,再运行`vp hooks enable`;安装过程会避开外层仓库。
21
+
22
+ 终端向导询问工程目录、拓展 ID 和显示名,目录和显示名可按回车使用默认值。尚未创建 GitHub 仓库也可以开发和打包。脚本可用 `vp dlx create-bn-ext@alpha my-extension --id example.demo --name "Example"` 跳过向导。
23
+
24
+ `example.demo`里的`example`是市场命名空间,与GitHub的`owner`无关。第三方清单id必须包含这个命名空间;无点的id留给官方源。作者可选择自己的命名空间,但同一BN实例不允许两个不同来源占用同一命名空间。
25
+
26
+ ## 源码拓展联调
27
+
28
+ `create-bn-ext`生成独立拓展;`@bilibili-notify/bn`直接取得并运行宿主成品。工具发布后:
29
+
30
+ ```sh
31
+ vp dlx @bilibili-notify/bn@alpha dev
32
+ ```
33
+
34
+ 无需检出BN主仓或在隐藏目录构建宿主。正式运行使用`npx @bilibili-notify/bn@alpha web`;alpha发行期间入口带`@alpha`,本地审阅归档不代表已经发布。开发BN本体仍克隆主仓、按主仓指引使用vp。
35
+
36
+ 启动器从npm包内解包宿主,并按版本与用途核对缓存。默认数据分别在`~/.bilibili-notify/dev-data`与`~/.bilibili-notify/data`;配置、凭据和其他持久数据位于该数据目录,启动配置文件为`bn.config.yaml`。可用`--data-dir <绝对目录>`明确指定;缓存删除不影响持久数据,其他实例的数据需要通过`--data-dir`显式指定。端口可用`--port`调整。npm包与依赖装好后,启动宿主不再下载载荷,也不需要额外的离线参数;删除缓存后仍可从包内重建。
37
+
38
+ 拓展工程由创建器安装好依赖;已有工程先运行`vp install --frozen-lockfile`。只需启动BN,打开拓展页,点击“挂载开发拓展”,输入源码工程在BN机器上的绝对路径,再沿原开关启用。BN直接加载`src/index.ts`,负责运行、监听源码与子依赖、局部重载和收尾。工程不需要`dist/`,也没有独立的dev/start命令;`build`与打包用于生产。多个工程可同时挂载,保存一个只重载对应项。
39
+
40
+ 源码及其导入依赖、设置规则与清单预检通过后,BN沿原生命周期停止旧实例、启动新版;预检失败会在卡片显示错误,旧实例继续运行,修正后恢复更新。停用项不会因保存而自动启用。需要开发场景时,在清单声明`contributes.devtools: {}`,具名导出`src/devtools/index.ts`中的`devtools()`。解除或关闭BN时停止实例与监听,保留源工程;本次挂载不持久化,下次启动后重新指定。
41
+
42
+ 手动挂载存在于源码开发版和`bn dev`专用成品。`bn web`、Docker、桌面及普通生产构建没有此入口;运行期环境变量不能打开它。两个宿主使用相同默认端口时需先停止其中一个;多个拓展应挂到同一台开发BN。
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
+
57
+ ## 包与入口
58
+
59
+ 根目录保留`extension.json`。新模板将市场名称、命名空间和作者资料放在 `.bn-extension/marketplace.json`。发行ZIP包含构建后的`extension.json`、单文件`index.mjs`,可选`README.md`、`CHANGELOG.md`及`locales/<语言码>.json`;开发入口`devtools.mjs`不进入发行ZIP。
60
+
61
+ 生产拓展运行时没有自己的`node_modules`。生成配置把SDK与第三方依赖内联到入口;增加依赖后仍需保持单入口、自包含构建。源码开发使用工程已安装的依赖,不能据此假定生产也能读取它们;发布前仍需实际构建与装包校验。原生插件和运行时额外读文件的依赖需要另行设计,不能只凭构建成功判断可运行。
62
+
63
+ SDK有两个入口:
64
+
65
+ | 入口 | 使用处 |
66
+ | --- | --- |
67
+ | `@bilibili-notify/extension` | `src/`中的类型、`ok`、`fail`、平台描述辅助 |
68
+ | `@bilibili-notify/extension/build` | 根构建配置中的`extensionPackageFiles`、`manifestWithSettingsFields` |
69
+
70
+ 不要从宿主或私有`internal`取模块,也不要把`/build`导入运行源码。模块顶层只定义类型、规则和函数;宿主及构建插件可能多次导入入口,实际副作用在`activate`或来源/适配器的生命周期里开始。
71
+
72
+ ## 先做一个订阅来源
73
+
74
+ 清单的`contributes.subscription`描述外观、接受的搜索输入与支持的推送特性,运行入口通过`ctx.registerSource(def)`交给宿主。一个拓展只能登记一个订阅来源。
75
+
76
+ ```ts
77
+ import type { ExtensionContext, SourceDef } from "@bilibili-notify/extension";
78
+ import { ok } from "@bilibili-notify/extension";
79
+ import { z } from "zod";
80
+
81
+ export const settingsSchema = z.object({
82
+ greeting: z.string().default("Hello").meta({ label: "Greeting" }),
83
+ });
84
+
85
+ export function activate(ctx: ExtensionContext): void {
86
+ const settings = ctx.settings(settingsSchema);
87
+ const source: SourceDef = {
88
+ start() {},
89
+ stop() {},
90
+ async searchCreators(query) {
91
+ const read = settings.get();
92
+ if (!read.ok) return read;
93
+ const name = query.trim();
94
+ return ok({ candidates: name ? [{ externalId: name, name }] : [] });
95
+ },
96
+ };
97
+ ctx.registerSource(source);
98
+ }
99
+ ```
100
+
101
+ `searchCreators`最多返回10个候选;查不到是成功的空数组。可选`fetchProfile(identity, signal)`拉取资料,`fetchLiveStatus(identity, signal)`提供在播状态;声明周期直播时必须实现后者。按每次调用的`signal`尽快中止请求。
102
+
103
+ `start(sourceCtx)`得到运行中的来源上下文:从`subscriptions()`读取自己平台的创作者名单,监听`onSubscriptionsChanged`,以`externalId`上报。`reportProfile`更新资料,`reportPost`交作品,`reportLive`交开播、状态或下播信号;具体载荷使用SDK的`ExtensionPostReport`、`ExtensionLiveSignalReport`等公开类型。直播`status`只更新状态,不触发推送。
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
+
111
+ 拓展不持有BN内部订阅id,也不自己发送通知。宿主处理订阅开关、去重、规则、卡片、推送目标和历史。上报返回`void`,不把它当作发送回执;不合规的上报会留在宿主的上报问题记录里。
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
+
138
+ ## 设置与副作用
139
+
140
+ 设置规则只维护一份。入口导出`settingsSchema`并在`activate`交给`ctx.settings`;生成的构建配置用`extensionPackageFiles`把字段、默认值和说明写进`dist/extension.json`。推送连接的设置规则同理导出`connectionSettingsSchema`,写入`contributes.push.settingsFields`。
141
+
142
+ `settings.get()`返回`Result<{ settings }>`。规则不能通过时处理失败分支,不把错误当空对象。没有配置时,可通过默认值的规则仍可读取;需要主人补字段时返回`not_configured`。当前契约在激活期发现坏设置会拒绝启动;不要捕获后继续伪装成正常运行。
143
+
144
+ | 能力 | 使用方式 |
145
+ | --- | --- |
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。 |
148
+ | 状态 | `ctx.state`存公开业务状态,`ctx.secrets`存凭据;`http.`前缀由宿主保留 |
149
+ | 图片 | 通过`fetchImage`或`storeImage`得到图库引用,再交给上报载荷;不要把任意远端图地址冒充引用 |
150
+ | 定时与收尾 | `ctx.setTimeout` / `setInterval`、`signal`、`onDispose`;保存自己需要等待的任务并收尾 |
151
+ | 诊断 | `ctx.logger`、`reportProblem` / `resolveProblem`;日志的拓展id与级别由宿主处理 |
152
+ | 设置页 | `publishView`、`onAction`、`statusChanged`;动作名先在根清单声明 |
153
+ | 私有服务入口 | `mount` / `onUpgrade`申请宿主分配的入口,使用其实际前缀 |
154
+
155
+ 宿主先调用来源/适配器的`stop`,随后中止上下文信号并执行收尾。`stop`先停止派发新工作,避免等待一个只能靠后续宿主中止信号结束的无限任务。长期请求、连接和循环必须能退出。
156
+
157
+ 推送适配器通过`ctx.registerPlatformAdapter`登记,并在清单声明`contributes.push`。自己的连接及入站能力由适配器`start`收到的上下文提供;适配器键由宿主填成拓展id。它与订阅来源是两套接口,具体使用`PlatformAdapterDef`及其公开注释。
158
+
159
+ ## 失败与译文
160
+
161
+ 可预期失败返回`fail(code, message)`,成功返回`ok(...)`。`code`使用SDK的标准失败码;上游自己的错误码放`upstreamCode`。超时、限流、凭据失效与确实不存在分别处理;不要把所有错误都变成“找不到”。发送结果不明用`indeterminate`,不能自动重发。
162
+
163
+ 给人看的拓展文字放在`locales/zh-CN.json`、`zh-TW.json`、`en.json`、`ja.json`,使用`ctx.i18n.t(key, values)`现取,不缓存翻译结果。未提供译文的语言按宿主回落规则处理。作者、创作者、输入和上游诊断原文不作为翻译键。
164
+
165
+ 市场卡片复用这些文件里的`$manifest.name`和`$manifest.description`。当前版本的市场说明可写为普通译文键`marketplace.notes`;发布命令从实际构建的`dist/locales/`提取到索引的可选`locales`字段,不另建市场译文文件。缺项按“当前语言 → 简中 → 英文 → 默认文字”逐字段回落,历史CHANGELOG保留原文。
166
+
167
+ ## 检查、安装与发布
168
+
169
+ ```sh
170
+ vp run lint
171
+ vp run format
172
+ vp run format:check
173
+ vp run typecheck
174
+ vp run test
175
+ vp run build
176
+ vp run pack:extension
177
+ vp run release --tag v0.1.0 --dry-run
178
+ ```
179
+
180
+ `verify`串起代码门禁、构建和打包;发布命令还复验Conventional Commits。ZIP与SHA256在`artifacts/`,可在BN拓展页上传安装。SDK版本变化不替你更改清单的宿主契约要求。
181
+
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。
187
+
188
+ 用户在BN“拓展 → 市场源”输入`owner/repository`或GitHub仓库网址,即定位到固定`bn-marketplace` Release上的`marketplace.json`。只支持公开可读取的索引和ZIP;第三方来源仍需用户信任,SDK和创建器不会赋予官方身份。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Akokko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,46 @@
1
- # Temporary Holding Version
1
+ # bilibili-notify extension SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ BN拓展的公开契约与构建辅助。仅支持ESM和Node.js 24及以上;宿主兼容性按拓展清单的`apiVersion` / `apiRevision`判断,与SDK的npm版本号分开。
4
+
5
+ ## 入口
6
+
7
+ - `@bilibili-notify/extension`:拓展运行代码使用的类型、`ok()` / `fail()`及中性平台描述辅助。
8
+ - `@bilibili-notify/extension/build`:只给构建配置使用的清单导出与文件复制插件。
9
+
10
+ 拓展从SDK这一处获取BN契约,第三方依赖由拓展自己声明。SDK不提供宿主内部模块、MessageBus或订阅配置的写路径;副作用和收尾经宿主交给拓展的ctx执行。
11
+
12
+ ```ts
13
+ import type { ExtensionContext, SourceDef } from "@bilibili-notify/extension";
14
+ import { ok } from "@bilibili-notify/extension";
15
+
16
+ const source: SourceDef = {
17
+ start() {},
18
+ stop() {},
19
+ async searchCreators() {
20
+ return ok({ candidates: [] });
21
+ },
22
+ };
23
+
24
+ export function activate(ctx: ExtensionContext) {
25
+ ctx.registerSource(source);
26
+ }
27
+ ```
28
+
29
+ 完整拓展还需根目录的`extension.json`声明来源外观与能力。`settingsSchema`和`connectionSettingsSchema`可由构建辅助生成清单设置字段。创建工程、契约小号与群聊作品解析、生命周期、上报、设置、译文和发布见[作者指南](./DEVELOPMENT.md),此文件也包含在npm包里,可在安装目录直接读取。
30
+
31
+ ## Agent 开发入口
32
+
33
+ [Agent 契约指引](./AGENT_GUIDE.md)和[开发 skill](./skills/bn-extension-development/SKILL.md)随包提供。创建器会在新工程生成 `AGENTS.md`、`CLAUDE.md`,并为 Codex 与 Claude 准备共享正文的 skill 入口。手工搭建工程时,可把包里的 `skills/bn-extension-development` 复制到项目的 `.agents/skills/`,再将本包的 agent 指引接入已有项目说明。
34
+
35
+ ## 源码与发行目录
36
+
37
+ 仓内SDK仍是私有workspace包,源码从internal转出唯一契约定义。构建会内联所需实现和类型,并在`lib/`生成独立的公开npm清单、说明和许可证;仓外消费者不需要internal。
38
+
39
+ 在主仓根执行:
40
+
41
+ ```sh
42
+ vp run -F @bilibili-notify/extension build
43
+ vp -C packages/extension pm pack --out sdk.tgz
44
+ ```
45
+
46
+ `publishConfig.directory`使归档使用`lib/`中的公开清单。SDK与创建器各自的版本保存在对应`package.json`,与主程序的开发占位版本、宿主API档位分开。发行前先完成仓外工程验证,再发布已验过的归档。
package/build.d.mts ADDED
@@ -0,0 +1,25 @@
1
+ /** 入口里这两个名字交的是规则;别的导出构建不看。 */
2
+ interface ExtensionEntrySchemas {
3
+ settingsSchema?: unknown;
4
+ connectionSettingsSchema?: unknown;
5
+ }
6
+ type Json = Record<string, unknown>;
7
+ /**
8
+ * 源码清单 + 入口导出的规则 → 包里那份清单。一栏都不出的不写;导出完过一遍加载时的对表与清单格式,
9
+ * 错在构建时就报、点名到那一格。
10
+ */
11
+ export declare function manifestWithSettingsFields(source: unknown, entry: ExtensionEntrySchemas): Json;
12
+ /**
13
+ * 打包插件:入口那份打包配置写完 `dist/index.mjs` 之后,把**清单 + 译文**放进 `dist/`,让它原样就是一个
14
+ * 能装的包目录(ADR-0012 决策 8、ADR-0037 决策 14)。清单是源码根的 `extension.json` 加上从规则导出的设置项;
15
+ * `locales/` 有才拷。
16
+ *
17
+ * 规则从刚打好的 `index.mjs` 里取:那份里内联的 zod 就是拓展跑起来用的那份,`.meta()` 读得到。
18
+ * 🔴 拓展的模块顶层不许有副作用(装载器也会反复 import 它,ADR-0012 决策 10),这里 import 一次也一样安全。
19
+ * 监听重打时每次换一个查询串,否则 import 拿到的是第一次的缓存。
20
+ */
21
+ export declare function extensionPackageFiles(root: string): {
22
+ name: string;
23
+ closeBundle(): Promise<void>;
24
+ };
25
+ export type { ExtensionEntrySchemas };