@zhin.js/adapter 1.0.1 → 1.1.1

package/src/adapter-index.ts

@@ -10,9 +10,14 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import type {
   AdapterCapability,
   AdapterDefinition,
+  AdapterSegmentPolicy,
   EndpointInstance,
   EndpointSendRequest,
 } from './definition.js';
+import {
+  listEndpointManagementCapabilities,
+  type EndpointManagementCapability,
+} from './endpoint-management.js';
 
 const logger = getLogger('Adapter');
 
@@ -29,6 +34,7 @@ export interface AdapterEndpointSummary extends AdapterDescriptor {
   readonly connected: boolean;
   readonly status: 'online' | 'offline';
   readonly phase: AdapterEndpointPhase;
+  readonly managementCapabilities: readonly EndpointManagementCapability[];
 }
 
 export type AdapterEndpointPhase =
@@ -36,6 +42,7 @@ export type AdapterEndpointPhase =
 
 interface AdapterRecord extends AdapterDescriptor {
   readonly endpoint: EndpointInstance;
+  readonly segments?: AdapterSegmentPolicy;
   readonly unconfigured: boolean;
   started: boolean;
   open: boolean;
@@ -79,23 +86,28 @@ export class AdapterIndex {
     const unconfigured: string[] = [];
     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({
@@ -118,7 +130,8 @@ export class AdapterIndex {
   list(): readonly AdapterDescriptor[] {
     return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured,
       started: _started, open: _open, stopped: _stopped, failed: _failed,
-      startAttempted: _startAttempted, ...descriptor }) => Object.freeze(descriptor));
+      startAttempted: _startAttempted, segments: _segments,
+      ...descriptor }) => Object.freeze(descriptor));
   }
 
   /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
@@ -133,6 +146,7 @@ export class AdapterIndex {
       connected: record.open && !record.stopped,
       status: record.open && !record.stopped ? 'online' as const : 'offline' as const,
       phase: endpointPhase(record),
+      managementCapabilities: listEndpointManagementCapabilities(record.endpoint),
     })));
   }
 
@@ -165,6 +179,14 @@ export class AdapterIndex {
     return record.owner;
   }
 
+  /**
+   * Endpoint 的消息段能力声明（出站协商降级依据）；
+   * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
+   */
+  segmentPolicy(id: CapabilityId): AdapterSegmentPolicy | undefined {
+    return this.#records.get(id)?.segments;
+  }
+
   async start(): Promise<void> {
     // Soft-start in parallel with a short wait so kitchen-sink Roots do not
     // stall generation. Configured platforms that need longer (QQ auth, Slack
@@ -320,8 +342,13 @@ function matchesEndpoint(
   adapter: string,
   endpointId: string,
 ): boolean {
+  // 消息上的 $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}`);
@@ -366,16 +393,91 @@ function isUnconfiguredError(error: unknown): boolean {
   );
 }
 
+/** 单个实例配置展开的 endpoint 描述（多账号适配器经 `endpoints` 数组声明）。 */
+interface EndpointExpansion {
+  readonly id: CapabilityId;
+  readonly name: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
+ * 否则按实例 config 创建单个 endpoint（历史行为）。
+ */
+function expandEndpointConfigs(
+  slot: Readonly<CapabilitySlot<AdapterDefinition>>,
+  snapshot: RuntimeSnapshot,
+): readonly EndpointExpansion[] {
+  const config = snapshot.config.get(slot.owner) as
+    | { endpoints?: unknown }
+    | undefined;
+  const raw = config?.endpoints;
+  const entries = Array.isArray(raw)
+    ? raw.filter((entry): entry is Record<string, unknown> & { name: string } =>
+      !!entry && typeof entry === 'object'
+      && typeof (entry as { name?: unknown }).name === 'string'
+      && (entry as { name: string }).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<string>();
+  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 ?? {}) as Record<string, unknown>;
+  return Object.freeze(deduped.map((entry) => Object.freeze({
+    id: `${slot.id}~${entry.name}` as CapabilityId,
+    name: entry.name,
+    config: Object.freeze({ ...base, ...entry, name: entry.name }),
+  })));
+}
+
 async function createEndpointSoft(
   slot: Readonly<CapabilitySlot<AdapterDefinition>>,
   snapshot: RuntimeSnapshot,
+  expansion?: EndpointExpansion,
 ): Promise<{ readonly instance: EndpointInstance; readonly unconfigured: boolean }> {
   let endpoint: unknown;
   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,
       }),
     );
@@ -388,8 +490,8 @@ async function createEndpointSoft(
     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 {
@@ -400,7 +502,7 @@ async function createEndpointSoft(
   // 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 };
 }
 

package/src/definition.ts

@@ -1,10 +1,17 @@
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
+import type { EndpointManagement } from './endpoint-management.js';
 
 const adapterBrand = 'zhin.adapter/1' as const;
 
 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 +19,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. */
@@ -28,14 +37,62 @@ export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TCo
   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;
+}
+
+const HTML_OUTBOUND_MODES: readonly HtmlOutboundMode[] = ['direct', 'image', 'text'];
+
+const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
+  'url', 'path', 'base64', 'upload',
+];
+
 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 function defineAdapter<TConfig = unknown, TResult = unknown>(
   definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>,
 ): Readonly<AdapterDefinition<TConfig, TResult>> {
@@ -49,10 +106,58 @@ export function defineAdapter<TConfig = unknown, TResult = unknown>(
   ) {
     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: AdapterSegmentPolicy | undefined,
+): AdapterSegmentPolicy | undefined {
+  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 as AdapterOutboundMedia),
+      ))
+  ) {
+    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 } : {}),
   });
 }
 
@@ -68,6 +173,8 @@ export function parseAdapterDefinition(value: unknown): AdapterDefinition {
       (capability) => capability !== 'inbound' && capability !== 'outbound',
     )
   ) throw invalidAdapter();
+  // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
+  normalizeSegmentPolicy(definition.segments);
   return definition as AdapterDefinition;
 }