@zhin.js/adapter 1.1.0 → 1.1.2

package/README.md

@@ -16,6 +16,18 @@ export default defineAdapter({
 本包只依赖 Kernel 与 Feature Kit，不包含具体平台 SDK。生产 manifest 指向
 `lib/provider.js`；开发时可通过 conditional export 读取源码。
 
+单文件插件可用 `setup({ addAdapter })` 注册 `defineAdapter(...)`；Endpoint 仍由同一个
+AdapterIndex 和 generation handoff 管理。
+
+## Endpoint 生命周期基座（createEndpointLifecycle）
+
+WS/SSE 类端点的 start/stop/重连/心跳统一走 `createEndpointLifecycle`
+（`src/endpoint-lifecycle.ts`），不要手写 `#started`/`#scheduleReconnect` 状态机——
+napcat/milky/onebot11/onebot12/satori 已迁移（各自曾独立犯过同一个 start 失败竞态）。
+基座内置：start 失败复位不武装重连、仅曾 open 才按退避重连（指数+jitter 可配）、
+stop 主动断开不重连、心跳 PONG 看门狗、定时器集中清理、陈旧 socket 事件防叠套。
+迁移指引见该文件 JSDoc。
+
 ## Adapter ↔ Endpoint：固定 1 对多
 
 一个 adapter 插件实例固定对应一到多个 endpoint：

package/lib/adapter-index.d.ts

@@ -1,5 +1,5 @@
 import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import type { AdapterCapability, AdapterDefinition, EndpointInstance, EndpointSendRequest } from './definition.js';
+import type { AdapterCapability, AdapterDefinition, AdapterSegmentPolicy, EndpointInstance, EndpointSendRequest } from './definition.js';
 import { type EndpointManagementCapability } from './endpoint-management.js';
 export interface AdapterDescriptor {
     readonly id: CapabilityId;
@@ -37,6 +37,11 @@ export declare class AdapterIndex {
      */
     instance(adapter: string, endpointId: string): EndpointInstance | undefined;
     owner(id: CapabilityId): PluginId;
+    /**
+     * Endpoint 的消息段能力声明（出站协商降级依据）；
+     * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
+     */
+    segmentPolicy(id: CapabilityId): AdapterSegmentPolicy | undefined;
     start(): Promise<void>;
     open(): void;
     close(): Promise<void>;

package/lib/adapter-index.js

@@ -37,6 +37,7 @@ export class AdapterIndex {
                         source: slot.source,
                         capabilities: slot.definition.capabilities,
                         endpoint: endpoint.instance,
+                        ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
                         unconfigured: endpoint.unconfigured,
                         started: false,
                         open: false,
@@ -62,7 +63,7 @@ export class AdapterIndex {
         }
     }
     list() {
-        return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured, started: _started, open: _open, stopped: _stopped, failed: _failed, startAttempted: _startAttempted, ...descriptor }) => Object.freeze(descriptor));
+        return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured, started: _started, open: _open, stopped: _stopped, failed: _failed, startAttempted: _startAttempted, segments: _segments, ...descriptor }) => Object.freeze(descriptor));
     }
     /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
     describe() {
@@ -108,6 +109,13 @@ export class AdapterIndex {
             throw new Error(`Unknown Adapter Endpoint: ${id}`);
         return record.owner;
     }
+    /**
+     * Endpoint 的消息段能力声明（出站协商降级依据）；
+     * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
+     */
+    segmentPolicy(id) {
+        return this.#records.get(id)?.segments;
+    }
     async start() {
         // Soft-start in parallel with a short wait so kitchen-sink Roots do not
         // stall generation. Configured platforms that need longer (QQ auth, Slack

package/lib/definition.d.ts

@@ -3,6 +3,10 @@ import type { CapabilityContext } from '@zhin.js/feature-kit';
 import type { EndpointManagement } from './endpoint-management.js';
 declare const adapterBrand: "zhin.adapter/1";
 export type AdapterCapability = 'inbound' | 'outbound';
+/** 端点可消费的出站媒体来源形式。 */
+export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
+/** 交互段（卡片/按钮等富交互）的端点消费方式。 */
+export type AdapterInteractiveMode = 'native' | 'text';
 export interface EndpointSendRequest {
     readonly target: string;
     readonly payload: unknown;
@@ -29,11 +33,47 @@ export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TCo
     readonly id: CapabilityId;
     readonly name: string;
 }
+/**
+ * html 段出站策略：
+ * - `direct`：端点直接消费 html 段（Console UI 类端点），核心不做任何转换；
+ * - `image`：经 html-renderer 渲染成 image 段，无渲染器时降级 text（缺省）；
+ * - `text`：直接降级为 text 段。
+ */
+export type HtmlOutboundMode = 'direct' | 'image' | 'text';
+/**
+ * 端点消息段能力声明（出站协商降级的依据）。
+ * 缺省（未声明 `segments`）保持历史行为：仅 html 段按 image/text 处理，
+ * 其余段原样透传给端点。
+ */
+export interface AdapterSegmentPolicy {
+    /**
+     * 端点原生可消费的 wire 段类型（如 `['text', 'image', 'at']`）。
+     * 声明后，未列出的段由核心按 `formatSegmentPreview` 降级为 text 段；
+     * 不声明则不过滤（全部透传）。
+     */
+    readonly supported?: readonly string[];
+    /** html 段处理策略，缺省 `image`。 */
+    readonly html?: HtmlOutboundMode;
+    /** 端点可消费的媒体来源形式；缺省表示不做媒体来源协商。 */
+    readonly outboundMedia?: readonly AdapterOutboundMedia[];
+    /**
+     * 交互段（卡片/按钮等富交互）消费方式：`native` 原生渲染 / `text` 降级纯文本。
+     * 目前仅为声明（供出站协商与门禁消费），`text` 的降级执行随 Wave 2 落地。
+     */
+    readonly interactive?: AdapterInteractiveMode;
+}
 export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
     readonly $feature: typeof adapterBrand;
     readonly capabilities: readonly AdapterCapability[];
+    /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
+    readonly segments?: AdapterSegmentPolicy;
     create(context: AdapterContext<TConfig>): EndpointInstance<TResult> | Promise<EndpointInstance<TResult>>;
 }
+declare module '@zhin.js/plugin-runtime' {
+    interface PluginSetupContext<TConfig> {
+        addAdapter<TResult = unknown>(localName: string, definition: AdapterDefinition<TConfig, TResult>): void;
+    }
+}
 export declare function defineAdapter<TConfig = unknown, TResult = unknown>(definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>): Readonly<AdapterDefinition<TConfig, TResult>>;
 export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
 export {};

package/lib/definition.js

@@ -1,4 +1,8 @@
 const adapterBrand = 'zhin.adapter/1';
+const HTML_OUTBOUND_MODES = ['direct', 'image', 'text'];
+const OUTBOUND_MEDIA_FORMS = [
+    'url', 'path', 'base64', 'upload',
+];
 export function defineAdapter(definition) {
     if (typeof definition.create !== 'function') {
         throw new TypeError('Adapter create must be a function');
@@ -8,10 +12,46 @@ export function defineAdapter(definition) {
         || capabilities.some((value) => value !== 'inbound' && value !== 'outbound')) {
         throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
     }
+    const segments = normalizeSegmentPolicy(definition.segments);
     return Object.freeze({
         ...definition,
         $feature: adapterBrand,
         capabilities: Object.freeze(capabilities),
+        ...(segments ? { segments } : {}),
+    });
+}
+function normalizeSegmentPolicy(policy) {
+    if (policy === undefined)
+        return undefined;
+    if (!policy || typeof policy !== 'object') {
+        throw new TypeError('Adapter segments policy must be an object');
+    }
+    if (policy.supported !== undefined
+        && (!Array.isArray(policy.supported)
+            || policy.supported.some((type) => typeof type !== 'string' || !type))) {
+        throw new TypeError('Adapter segments.supported must be an array of segment type names');
+    }
+    if (policy.html !== undefined && !HTML_OUTBOUND_MODES.includes(policy.html)) {
+        throw new TypeError('Adapter segments.html must be direct, image or text');
+    }
+    if (policy.outboundMedia !== undefined
+        && (!Array.isArray(policy.outboundMedia)
+            || policy.outboundMedia.length === 0
+            || policy.outboundMedia.some((form) => !OUTBOUND_MEDIA_FORMS.includes(form)))) {
+        throw new TypeError("Adapter segments.outboundMedia must be a non-empty array of 'url' | 'path' | 'base64' | 'upload'");
+    }
+    if (policy.interactive !== undefined
+        && policy.interactive !== 'native'
+        && policy.interactive !== 'text') {
+        throw new TypeError("Adapter segments.interactive must be 'native' or 'text'");
+    }
+    return Object.freeze({
+        ...(policy.supported ? { supported: Object.freeze([...new Set(policy.supported)]) } : {}),
+        ...(policy.html ? { html: policy.html } : {}),
+        ...(policy.outboundMedia
+            ? { outboundMedia: Object.freeze([...new Set(policy.outboundMedia)]) }
+            : {}),
+        ...(policy.interactive ? { interactive: policy.interactive } : {}),
     });
 }
 export function parseAdapterDefinition(value) {
@@ -24,6 +64,8 @@ export function parseAdapterDefinition(value) {
         || definition.capabilities.length === 0
         || definition.capabilities.some((capability) => capability !== 'inbound' && capability !== 'outbound'))
         throw invalidAdapter();
+    // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
+    normalizeSegmentPolicy(definition.segments);
     return definition;
 }
 function invalidAdapter() {

package/lib/endpoint-commands.d.ts

@@ -0,0 +1,127 @@
+import { type Token } from '@zhin.js/plugin-runtime';
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行管理命令；未配置则放行。
+ */
+export declare function isEndpointOperator(config: unknown, input: unknown): boolean;
+/** add/remove 的拒绝文案（list 只读，不校验）。 */
+export declare function endpointCommandForbidden(adapterDisplayName: string): string;
+export type EndpointCommandReply = (text: string) => Promise<unknown>;
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export declare function extractEndpointCommandReply(input: unknown): EndpointCommandReply;
+export interface EndpointRunningInfo {
+    readonly name: string;
+    /** 连接模式（ws / wss / polling / socket-mode …），仅用于 list 展示。 */
+    readonly mode?: string;
+}
+export interface EndpointRuntimeState {
+    /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+    readonly endpoints: Map<string, EndpointRunningInfo>;
+}
+export declare function createEndpointRuntimeState(): EndpointRuntimeState;
+/** 每个适配器在模块顶层调用一次，创建自己的 runtime state token。 */
+export declare function defineEndpointRuntimeStateToken(adapterKey: string): Token<EndpointRuntimeState>;
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export declare function resolveProjectRoot(): string;
+/** 派生 endpoint 凭据的 env 键：`${ADAPTER}_${NAME}_${FIELD}`（如 `TELEGRAM_MY_BOT_TOKEN`） */
+export declare function buildEndpointEnvKey(adapterKey: string, endpointName: string, fieldKey: string): string;
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export declare function persistEndpointEnvValues(values: Readonly<Record<string, string>>, projectRoot?: string): void;
+export interface ConfiguredEndpointEntry {
+    name: string;
+    [key: string]: unknown;
+}
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export declare function findEndpointConfigFile(adapterKey: string, projectRoot?: string): string;
+/** 读取 plugins.<adapterKey>.endpoints（plain JS）；plugins/<adapterKey> 缺失或形态不符时返回 [] */
+export declare function listConfiguredEndpoints(adapterKey: string, projectRoot?: string): ConfiguredEndpointEntry[];
+/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；name 已存在时报错 */
+export declare function addEndpointToConfig(adapterKey: string, entry: ConfiguredEndpointEntry, projectRoot?: string): string;
+/** 按 name 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
+export declare function removeEndpointFromConfig(adapterKey: string, name: string, projectRoot?: string): {
+    removed: boolean;
+    filePath: string;
+};
+/** add 命令可录入的字段描述（与 schema.json 的 endpoints.items.properties 对齐）。 */
+export interface EndpointFieldSpec {
+    /** 配置字段 key（如 token / access_token / url / baseUrl） */
+    readonly key: string;
+    /** add 时必填（schema 中 required 的凭据/连接字段） */
+    readonly required?: boolean;
+    /** 凭据类字段：值写入 .env，yaml 保存 ${REF} 引用；否则内联写入 yaml */
+    readonly env?: boolean;
+    /** 字段说明（用于用法提示） */
+    readonly description?: string;
+}
+export type EndpointCommandUse = <T>(token: Token<T>) => T;
+/** bindFlow 钩子上下文：接管 add 命令的自定义绑定流程（如 QQ 扫码）。 */
+export interface EndpointBindFlowContext {
+    /** 命令参数 name（未指定时为 undefined，流程可自行决定终名） */
+    readonly name?: string;
+    /** 向当前会话推送后续状态（二维码刷新 / 成功 / 失败） */
+    readonly reply: EndpointCommandReply;
+    readonly config: unknown;
+    readonly input: unknown;
+    readonly use: EndpointCommandUse;
+}
+export interface EndpointCommandsSpec {
+    /** 实例 key（zhin.config.yml 的 plugins.<key>，如 telegram / napcat） */
+    readonly adapterKey: string;
+    /** 展示名（QQ / Telegram / NapCat …），用于权限与列表文案 */
+    readonly adapterDisplayName: string;
+    /** add 命令可录入字段（bindFlow 接管 add 时仅用于展示） */
+    readonly fields?: readonly EndpointFieldSpec[];
+    /** 运行中 endpoints 数据源（可选）：通常读 adapter create 注册的 runtime state */
+    readonly running?: (use: EndpointCommandUse) => Iterable<EndpointRunningInfo>;
+    /** list 中配置项的附加描述（如 entry => `appid: ${entry.appid}`） */
+    readonly describeEntry?: (entry: ConfiguredEndpointEntry) => string;
+    /** list 末尾的附加行（如 QQ 的进行中扫码提示）；返回 undefined 不加行 */
+    readonly listFooter?: (use: EndpointCommandUse) => string | undefined;
+    /** 自定义 add 流程（扫码绑定等）；提供时 add 命令忽略 kv 参数，交给钩子 */
+    readonly bindFlow?: (context: EndpointBindFlowContext) => Promise<string> | string;
+    /** add 命令描述覆盖 */
+    readonly addDescription?: string;
+}
+/**
+ * 命令定义的最小结构（与 @zhin.js/command 的 CommandDefinition 结构兼容）。
+ * provider 层不允许 import @zhin.js/command，故 defineCommand 由调用方注入，
+ * 这里只描述结构；适配器侧传入 defineCommand 后 TCommand 即 Readonly<CommandDefinition>。
+ *
+ * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象），
+ * 否则注入的 defineCommand 会因 TS 逆变检查失败（TS2345）。
+ */
+export interface EndpointCommandContext {
+    readonly config: unknown;
+    /**
+     * 与 `@zhin.js/command` 的 `CommandContext.input` 对齐：IM 命中时有值，
+     * Host / 无消息路径可为 `undefined`。须保持可选，否则注入 `defineCommand` 会因
+     * execute 参数逆变检查失败（TS2345）。
+     */
+    readonly input?: unknown;
+    readonly args: readonly string[];
+    readonly params: Readonly<Record<string, string | number | boolean | Readonly<Record<string, unknown>> | null>>;
+    readonly use: EndpointCommandUse;
+}
+export interface EndpointCommandDefinition {
+    readonly description?: string;
+    execute(context: EndpointCommandContext): unknown;
+}
+export interface EndpointCommands<TCommand = EndpointCommandDefinition> {
+    readonly list: TCommand;
+    readonly add: TCommand;
+    readonly remove: TCommand;
+}
+/** list 文案：运行中 + 配置中两段，footer 可选。 */
+export declare function formatEndpointList(spec: Pick<EndpointCommandsSpec, 'adapterKey' | 'adapterDisplayName' | 'describeEntry'>, source: {
+    readonly running: Iterable<EndpointRunningInfo>;
+    readonly configured: readonly ConfiguredEndpointEntry[];
+    readonly footer?: string;
+}): string;
+/** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
+export declare function addEndpointFromKeyValues(spec: EndpointCommandsSpec, name: string, args: readonly string[], projectRoot?: string): string;
+/** remove 的完整业务逻辑：从 yaml 移除；返回回复文本。 */
+export declare function removeEndpointByName(spec: Pick<EndpointCommandsSpec, 'adapterKey'>, name: string, projectRoot?: string): string;
+/** 生成 `<adapter> endpoint` 的 list / add / remove 三个命令定义（见文件头接入步骤）。 */
+export declare function createEndpointCommands<TCommand>(spec: EndpointCommandsSpec, defineCommand: (definition: EndpointCommandDefinition) => TCommand): EndpointCommands<TCommand>;