@yunzai-ng/core 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @yunzai-ng/core
+
+内核实现。插件从这里取 `definePlugin`、`s`(配置 schema)与若干工具。
+
+## 唯一入口
+
+```ts
+import { definePlugin, s } from "@yunzai-ng/core"
+```
+
+`src/index.ts` 刻意用 `export *` 而非逐个列举 —— 逐个列举的清单必然与实现脱节,而漏掉一个类型
+就要使用者改内核。作为交换,各模块自己须克制:**只 `export` 确实供外部使用的符号**。
+
+测试替身在 `@yunzai-ng/core/testing` 子路径,**不在主入口** —— 并进去会让替身实现进入生产依赖图。
+
+## 目录
+
+| 目录 | 职责 |
+|---|---|
+| `kernel/` | 应用生命周期 `create → start → stop`,以及运行期子系统的装配 |
+| `plugin/` | 插件宿主:发现、导入、上下文、卸载、热重载、市场 |
+| `pipeline/` | 消息管线:事件、中间件、路由、冷却、上下文问答、分发 |
+| `config/` | 配置 schema 构造器与 YAML 存取 |
+| `store/` | KV / SQL / JSON / 内存四种存储 |
+| `server/` | 共享 HTTP + WebSocket 服务器、面板 API、鉴权 |
+| `adapter/` | 适配器注册表、账号生命周期、Bot 门面 |
+| `render/` | 渲染注册表(内核不认识 puppeteer) |
+| `scheduler/` | 定时任务 |
+| `logger/` | 日志与轮转 |
+| `http/` | 全框架唯一的 HTTP 客户端 |
+| `platform/` | 目录布局、平台探测、磁盘与 GPU |
+| `util/` | 插件作者最常自己重复实现的那些(切分、LRU、退避重试、脱敏) |
+| `testing/` | 测试替身,经子路径导出 |
+
+## 三条不可动的约束
+
+**内核不依赖任何插件。** 由 `scripts/check-layering.mjs` 在 CI 里守着。
+
+**装配顺序不是任意排列。** 日志早于配置(否则「读配置时出错」无处记录)、存储早于插件(插件
+加载失败要写状态)、`listen()` 晚于插件加载(否则有「面板部分可用」的窗口)。逐条写在
+`kernel/app.ts` 的文件头。
+
+**卸载必须完整归还资源。** 每个注册型方法都把 disposer 登记进 `DisposalRegistry`,插件作者
+无从遗漏 —— 否则改十次代码就有十份定时器同时在跑。
+
+## 读源码的入口
+
+想看「一个插件是怎么跑起来的」:`plugin/host.ts` → `plugin/context.ts` → `plugin/hooks.ts`。
+最后那个是理解全局的关键 —— 它解释了为什么上下文不直接 import 各子系统。
+
+想看「一条消息是怎么走的」:`pipeline/dispatch.ts` → `pipeline/router.ts` → `adapter/bots.ts`。

package/dist/adapter/accounts.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 模块职责：账号生命周期管理（持久化、连接、重连、状态）+ 实现 `AccountsView`
+ * 依赖方向：依赖类型包、KV、适配器注册表、Bot 注册表、宿主工厂；**不认识任何具体协议**
+ * 生命周期：随内核创建；每个账号一份 `AccountRuntime`，随账号删除或内核停止回收
+ * 注意事项：账号是**数据**（KV 里的 `AccountRecord`），协议是**插件**（`AdapterProvider`），
+ *          两者在运行时撮合 —— 故增删账号不必重启进程。四个必须做对的点：
+ *
+ *          **重连要有退避、要能被取消。** 用 `backoffDelay`，日志按次数递减（首次 warn、
+ *          之后每 10 次一条）；账号一被禁用或删除，pending 的重连定时器立刻清掉。
+ *
+ *          **`connect()` 必须防重入。** 双击「连接」、重连定时器与手动连接撞在一起，都会让两个
+ *          driver 连同一个账号 —— 表现为消息收两遍、回两遍。用 `#connecting` 做单飞。
+ *
+ *          **每个账号一份 `DisposalRegistry` + 一个 `AbortController`，且顺序要对。** 断开时先
+ *          abort（让宿主立刻开始丢事件），再回收登记，最后才 await driver 的 `disconnect()`；
+ *          反了就会出现「已断开的账号还在往管线里灌事件」。`disconnect()` 同样先 abort 再 await
+ *          正在进行的 `connect()` —— 被动接入的适配器要等对端连入才返回，不先 abort 会卡住停机。
+ *
+ *          **适配器插件卸载时账号要同步下线。** `onUnregister` 是同步回调（见 registry.ts），
+ *          故此处同步改状态并 abort，异步的 socket 关闭交给 `#closing` 由 `stop()` 兜底 await。
+ */
+import type { AccountRecord, AccountState, AccountsView, KvNamespace, Logger } from "@yunzai-ng/types";
+import type { CoreEventBus } from "../plugin/events.js";
+import type { AdapterEntry, AdapterRegistry } from "./registry.js";
+import type { BotRegistry, SendPolicyView } from "./bots.js";
+import type { AdapterHostFactory } from "./host.js";
+/** 账号管理器构造参数 */
+export interface AccountManagerOptions {
+    /** 日志器 */
+    readonly logger: Logger;
+    /** 存账号记录的 KV 命名空间 */
+    readonly kv: KvNamespace;
+    /** 适配器注册表 */
+    readonly adapters: AdapterRegistry;
+    /** Bot 注册表 */
+    readonly bots: BotRegistry;
+    /** 宿主工厂 */
+    readonly createHost: AdapterHostFactory;
+    /** 内核事件总线 */
+    readonly events: CoreEventBus;
+    /** 发送策略视图，透传给每个 Bot 门面 */
+    readonly sendPolicy: SendPolicyView;
+}
+/**
+ * 账号管理器
+ *
+ * 既是 WebUI 的增删改查入口，也是 `AccountsView` 的实现（插件通过
+ * `ctx.app.accounts` 只读观察）。
+ */
+export declare class AccountManager implements AccountsView {
+    #private;
+    /**
+     * @param opts 构造参数
+     */
+    constructor(opts: AccountManagerOptions);
+    /** 账号总数 */
+    get size(): number;
+    /**
+     * 从 KV 载入全部账号记录（不连接）
+     *
+     * 与 `startAll()` 分开：内核 `load` 阶段就该知道有哪些账号（WebUI 要能显示
+     * 列表），但连接要等适配器插件全部注册完 —— 否则先加载的账号会因为
+     * "适配器未注册"白失败一次。
+     * @returns 载入的账号数
+     */
+    load(): Promise<number>;
+    /**
+     * 连接全部已启用的账号
+     *
+     * 并发连接：一个账号的对端没起来不该让后面的账号排队等它退避完。
+     * 单个账号失败只落日志（`connect` 内部已转成 error 状态 + 重连），
+     * 所以这里 `allSettled` 之后不需要检查结果。
+     */
+    startAll(): Promise<void>;
+    /**
+     * 列出全部账号及其状态
+     * @returns 状态快照数组
+     */
+    list(): AccountState[];
+    /**
+     * 按记录 id 取账号状态
+     * @param id 账号记录 id
+     * @returns 状态快照；不存在时 undefined
+     */
+    get(id: string): AccountState | undefined;
+    /**
+     * 新建账号
+     *
+     * 配置先过 `validateAccount()` 再落盘：非法配置一旦存入，只会在下次启动时
+     * 表现为一条无从判断原因的连接失败。
+     * @param adapterId 适配器 id
+     * @param config 账号配置（WebUI 提交的原始对象）
+     * @param label 备注名
+     * @param enabled 是否立即启用并连接，缺省 true
+     * @returns 新建的记录
+     * @throws 适配器未注册或配置校验失败时
+     */
+    create(adapterId: string, config: unknown, label?: string, enabled?: boolean): Promise<AccountRecord>;
+    /**
+     * 修改账号配置
+     *
+     * 改完必须重连：连接参数（地址、token）变了而 socket 还是旧的，
+     * 用户会以为"改了没生效"。
+     * @param id 账号记录 id
+     * @param patch 要改的字段
+     * @returns 更新后的记录
+     * @throws 账号不存在或配置校验失败时
+     */
+    update(id: string, patch: {
+        config?: unknown;
+        label?: string;
+        enabled?: boolean;
+    }): Promise<AccountRecord>;
+    /**
+     * 启用 / 禁用账号
+     * @param id 账号记录 id
+     * @param enabled 是否启用
+     * @returns 更新后的记录
+     * @throws 账号不存在时
+     */
+    setEnabled(id: string, enabled: boolean): Promise<AccountRecord>;
+    /**
+     * 删除账号
+     * @param id 账号记录 id
+     * @returns 是否删掉了（不存在时 false）
+     */
+    remove(id: string): Promise<boolean>;
+    /**
+     * 连接一个账号
+     *
+     * 幂等且防重入：已在线直接返回，正在连接则复用同一个 promise（文件头第 2 点）。
+     * 失败**不抛出异常** —— 账号无法连接属于常态（对端未启动），转为 `error` 状态并
+     * 安排重连即可；抛出异常只会使 WebUI 的批量操作在第一个账号处中断。
+     * @param id 账号记录 id
+     * @throws 账号不存在时
+     */
+    connect(id: string): Promise<void>;
+    /**
+     * 断开一个账号
+     * @param id 账号记录 id
+     * @param reason 断开原因（落日志与 `bot/offline`）
+     */
+    disconnect(id: string, reason?: string): Promise<void>;
+    /**
+     * 重连一个账号
+     * @param id 账号记录 id
+     */
+    reconnect(id: string): Promise<void>;
+    /**
+     * 适配器插件被卸载：同步让它名下的账号下线
+     *
+     * **同步部分**必须在本函数返回前完成（改状态 + abort + 从 Bot 注册表摘除），
+     * 因为调用方是同步的 `Disposer`。异步的 socket 关闭挂在 `rt.closing` 上，
+     * 由 `stop()` 兜底 await。见文件头第 4 点。
+     * @param adapterId 适配器 id
+     * @param entry 摘除的注册条目（仅用于日志）
+     */
+    detachAdapter(adapterId: string, entry?: AdapterEntry): void;
+    /**
+     * 适配器插件重新注册：把它名下已启用的账号连回来
+     *
+     * 热重载的另一半。不 await：注册通知也发生在同步路径上。
+     * @param adapterId 适配器 id
+     */
+    onAdapterRegistered(adapterId: string): void;
+    /**
+     * 停机：断开全部账号
+     *
+     * 并发断开并等到全部收尾，包括 `detachAdapter` 留下的异步尾巴 ——
+     * 否则进程退出时会留下没关的 socket，NapCat 侧要等到 TCP 超时才发现。
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=accounts.d.ts.map

package/dist/adapter/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../src/adapter/accounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EAEZ,YAAY,EAIZ,WAAW,EACX,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAIvD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,KAAK,EAAa,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,WAAW,CAAA;AAyCtE,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,UAAU;IACV,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;IACxB,aAAa;IACb,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,cAAc;IACd,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,WAAW;IACX,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,aAAa;IACb,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;CACpC;AAWD;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,YAAY;;IAsBjD;;OAEG;gBACS,IAAI,EAAE,qBAAqB;IAmBvC,WAAW;IACX,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IA4B7B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAW/B;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IAItB;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAOzC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAoCxG;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBhH;;;;;;OAMG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAItE;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1C;;;;;;;;OAQG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;OAIG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5D;;;OAGG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C;;;;;;;;OAQG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI;IAuB5D;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAU5C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAsT5B"}