@zhin.js/adapter 1.0.1 → 1.1.1

package/README.md

@@ -16,6 +16,42 @@ 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：
+
+- `plugins.<adapter>` 配置该 adapter 所有 endpoint 的**通用配置**（如凭据共享字段、
+  `master`、`intents`）。
+- `plugins.<adapter>.endpoints[index]` 配置单个 endpoint 的**特殊配置**，逐项覆盖通用
+  配置，`name` 必填。
+- 不写 `endpoints` 时退化为单 endpoint（历史行为），实例 config 原样传给 `create()`。
+
+展开由 `expandEndpointConfigs`（`src/adapter-index.ts`）完成：endpoint record id 为
+`<slotId>~<name>`，合并顺序 `{...通用, ...项}`（项优先），`endpoints` 键不下传给适配器。
+record name 即 entry.name——Console 展示、`resolve`/`instance` 查找、inbox 落库都按它命中
+唯一 endpoint（适配器实例的 live name 如 icqq uin 优先于它展示）。entry.name 不得含
+`~`/`\0`（会破坏 id 结构），重名/缺名的 entry 会被丢弃并 warn。
+多账号示例见 `plugins/adapters/icqq` / `plugins/adapters/qq` 的 README 与 schema。
+
+## 命令前缀（commandPrefix）
+
+适配器实例 config 支持 `commandPrefix`（默认 `''`）：`''` 表示任意文本都按命令匹配；
+`'/'` 则要求消息以 `/` 开头才进命令分发。`endpoints[i].commandPrefix` 可逐项覆盖。
+解析在 `@zhin.js/core` 的 `MessageDispatcher`（`defaultCommandPrefixResolver`）；
+`ImRuntime({ commandPrefix })` 可设全局静态前缀覆盖该行为。
+
 验证：`pnpm --filter @zhin.js/adapter test && pnpm --filter @zhin.js/adapter build`。
 
 架构说明见 [Plugin Monorepo 与 Feature Provider](../../../docs/architecture/target-implementation/plugin-monorepo-and-features.md)。

package/lib/adapter-index.d.ts

@@ -1,5 +1,6 @@
 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;
     readonly owner: PluginId;
@@ -12,6 +13,7 @@ export interface AdapterEndpointSummary extends AdapterDescriptor {
     readonly connected: boolean;
     readonly status: 'online' | 'offline';
     readonly phase: AdapterEndpointPhase;
+    readonly managementCapabilities: readonly EndpointManagementCapability[];
 }
 export type AdapterEndpointPhase = 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
 export declare class AdapterIndex {
@@ -35,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

@@ -1,6 +1,7 @@
 import { DisposeStack, } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { listEndpointManagementCapabilities, } from './endpoint-management.js';
 const logger = getLogger('Adapter');
 export class AdapterIndex {
     $projection = 'zhin.adapter-index/1';
@@ -23,24 +24,29 @@ export class AdapterIndex {
         const unconfigured = [];
         try {
             for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
-                const endpoint = await createEndpointSoft(slot, snapshot);
-                if (endpoint.unconfigured)
-                    unconfigured.push(slot.localName);
-                records.push({
-                    id: slot.id,
-                    owner: slot.owner,
-                    name: slot.localName,
-                    source: slot.source,
-                    capabilities: slot.definition.capabilities,
-                    endpoint: endpoint.instance,
-                    unconfigured: endpoint.unconfigured,
-                    started: false,
-                    open: false,
-                    failed: false,
-                    startAttempted: false,
-                    // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
-                    stopped: endpoint.unconfigured,
-                });
+                for (const expansion of expandEndpointConfigs(slot, snapshot)) {
+                    const endpoint = await createEndpointSoft(slot, snapshot, expansion);
+                    if (endpoint.unconfigured)
+                        unconfigured.push(expansion.name);
+                    records.push({
+                        id: expansion.id,
+                        owner: slot.owner,
+                        // 展开模式下 record name 即 endpoint 名（entry.name），
+                        // 保证 Console 展示与 resolve/instance 按 entry name 命中唯一 record
+                        name: expansion.name,
+                        source: slot.source,
+                        capabilities: slot.definition.capabilities,
+                        endpoint: endpoint.instance,
+                        ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
+                        unconfigured: endpoint.unconfigured,
+                        started: false,
+                        open: false,
+                        failed: false,
+                        startAttempted: false,
+                        // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
+                        stopped: endpoint.unconfigured,
+                    });
+                }
             }
             if (unconfigured.length > 0) {
                 logger.info(formatCompact({
@@ -57,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() {
@@ -71,6 +77,7 @@ export class AdapterIndex {
             connected: record.open && !record.stopped,
             status: record.open && !record.stopped ? 'online' : 'offline',
             phase: endpointPhase(record),
+            managementCapabilities: listEndpointManagementCapabilities(record.endpoint),
         })));
     }
     /**
@@ -102,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
@@ -252,8 +266,13 @@ export function isAdapterIndex(value) {
         && value.$projection === 'zhin.adapter-index/1';
 }
 function matchesEndpoint(record, adapter, endpointId) {
+    // 消息上的 $adapter 是 CapabilityId 的 localName 段（多 endpoint 展开后形如
+    // `icqq~8596238`）。CapabilityId 段分隔符是 \0（owner\0feature\0localName），
+    // 不能用 `/` 去 endsWith，否则永远匹配不上（endpoint not found）。
+    const localName = record.id.split('\0').pop() ?? record.id;
     const adapterOk = record.name === adapter
         || record.id === adapter
+        || localName === adapter
         || record.id.endsWith(`/${adapter}`)
         || record.owner === adapter
         || record.owner.endsWith(`/${adapter}`);
@@ -295,12 +314,72 @@ function isUnconfiguredError(error) {
     return (error instanceof TypeError
         && /requires|not configured|missing|未配置|缺少/i.test(error.message));
 }
-async function createEndpointSoft(slot, snapshot) {
+/**
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
+ * 否则按实例 config 创建单个 endpoint（历史行为）。
+ */
+function expandEndpointConfigs(slot, snapshot) {
+    const config = snapshot.config.get(slot.owner);
+    const raw = config?.endpoints;
+    const entries = Array.isArray(raw)
+        ? raw.filter((entry) => !!entry && typeof entry === 'object'
+            && typeof entry.name === 'string'
+            && entry.name.length > 0)
+        : [];
+    if (entries.length === 0) {
+        if (Array.isArray(raw) && raw.length > 0) {
+            logger.warn(formatCompact({
+                op: 'adapter_endpoints_entries_dropped',
+                id: slot.id,
+                reason: 'every endpoints entry is missing a non-empty string name',
+            }));
+        }
+        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+    }
+    // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析
+    const valid = entries.filter((entry) => {
+        if (/[~\0]/u.test(entry.name)) {
+            logger.warn(formatCompact({
+                op: 'adapter_endpoint_name_invalid',
+                id: slot.id,
+                name: entry.name,
+            }));
+            return false;
+        }
+        return true;
+    });
+    // 重名会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
+    const seen = new Set();
+    const deduped = valid.filter((entry) => {
+        if (seen.has(entry.name)) {
+            logger.warn(formatCompact({
+                op: 'adapter_endpoint_name_duplicate',
+                id: slot.id,
+                name: entry.name,
+            }));
+            return false;
+        }
+        seen.add(entry.name);
+        return true;
+    });
+    if (deduped.length === 0) {
+        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+    }
+    const { endpoints: _drop, ...base } = (config ?? {});
+    return Object.freeze(deduped.map((entry) => Object.freeze({
+        id: `${slot.id}~${entry.name}`,
+        name: entry.name,
+        config: Object.freeze({ ...base, ...entry, name: entry.name }),
+    })));
+}
+async function createEndpointSoft(slot, snapshot, expansion) {
     let endpoint;
     try {
         endpoint = await slot.definition.create(Object.freeze({
             ...createCapabilityContext(snapshot, slot.owner),
-            id: slot.id,
+            ...(expansion?.config ? { config: expansion.config } : {}),
+            id: expansion?.id ?? slot.id,
             name: slot.localName,
         }));
     }
@@ -313,8 +392,8 @@ async function createEndpointSoft(slot, snapshot) {
         const log = isUnconfiguredError(error) ? logger.debug.bind(logger) : logger.warn.bind(logger);
         log(formatCompact({
             op: 'adapter_create_soft_fail',
-            id: slot.id,
-            name: slot.localName,
+            id: expansion?.id ?? slot.id,
+            name: expansion?.name ?? slot.localName,
             error: message,
         }));
         return {
@@ -325,7 +404,7 @@ async function createEndpointSoft(slot, snapshot) {
     // Programming errors (create() did not return an Endpoint) must surface:
     // they propagate to AdapterIndex.create's catch, which disposes the records
     // created so far instead of hiding the bug behind an unconfigured stub.
-    assertEndpoint(endpoint, slot.id);
+    assertEndpoint(endpoint, expansion?.id ?? slot.id);
     return { instance: endpoint, unconfigured: false };
 }
 function createUnconfiguredEndpoint(reason) {

package/lib/definition.d.ts

@@ -1,7 +1,12 @@
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 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;
@@ -12,6 +17,8 @@ export interface EndpointSendRequest {
     };
 }
 export interface EndpointInstance<TResult = unknown> {
+    /** Optional platform-neutral Console/Host management surface. */
+    readonly management?: EndpointManagement;
     /** Allocates transport resources but must not admit inbound events yet. */
     start?(): void | Promise<void>;
     /** Opens admission after the candidate generation has committed. */
@@ -26,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>;