@zhin.js/adapter 1.1.5 → 1.1.8

package/src/endpoint-commands.ts

@@ -16,7 +16,7 @@
  * 接入步骤（以 telegram 为例）：
  * 1. plugin.ts setup 里 `context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState())`，
  *    token 由 `defineEndpointRuntimeStateToken('telegram')` 创建。
- * 2. adapters/telegram.ts create() 里 `context.use(token).endpoints.set(config.name, { name, mode })`。
+ * 2. adapters/telegram.ts create() 里 `context.use(token).endpoints.set(config.id, { id, mode })`。
  * 3. src 下 `export const telegramEndpointCommands = createEndpointCommands({ adapterKey: 'telegram', ... }, defineCommand)`
  *    （defineCommand 由调用方从 @zhin.js/command 传入——provider 包之间禁止互相 import，
  *    见 scripts/check-architecture-layers.mjs，故 defineCommand 走依赖注入）。
@@ -28,7 +28,13 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { createToken, type Token } from '@zhin.js/plugin-runtime';
+import {
+  createToken,
+  outboundHostToken,
+  type OutboundHost,
+  type OutboundSendInput,
+  type Token,
+} from '@zhin.js/plugin-runtime';
 import { isMap, isSeq, parseDocument, type YAMLSeq } from 'yaml';
 
 // ---------------------------------------------------------------------------
@@ -54,8 +60,9 @@ export function isEndpointOperator(config: unknown, input: unknown): boolean {
     }
   }
   if (masters.size === 0) return true;
-  const sender = String((input as { sender?: unknown } | null | undefined)?.sender ?? '').trim();
-  return !!sender && masters.has(sender);
+  const senderRaw = (input as { sender?: { id?: string } | null } | null | undefined)?.sender;
+  const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? senderRaw.id.trim() : '';
+  return !!senderId && masters.has(senderId);
 }
 
 /** add/remove 的拒绝文案（list 只读，不校验）。 */
@@ -80,18 +87,83 @@ export function extractEndpointCommandReply(input: unknown): EndpointCommandRepl
   return async () => undefined;
 }
 
+/**
+ * bindFlow 后续状态推送：优先走 OutboundHost（不受 inbound Message reply scope 限制）。
+ * 扫码绑定等长流程会在命令结果已送达、`$reply` 已冻结后继续 notify，必须用 durable 出站。
+ */
+export function createDurableEndpointCommandReply(
+  input: unknown,
+  use: EndpointCommandUse,
+): EndpointCommandReply {
+  const scoped = extractEndpointCommandReply(input);
+  const target = readOutboundSendTarget(input);
+  if (!target) return scoped;
+
+  return async (text) => {
+    let outbound: OutboundHost | undefined;
+    try {
+      outbound = use(outboundHostToken);
+    } catch {
+      outbound = undefined;
+    }
+    if (outbound) {
+      await outbound.send({ ...target, content: text });
+      return;
+    }
+    await scoped(text);
+  };
+}
+
+function readOutboundSendTarget(input: unknown): Omit<OutboundSendInput, 'content'> | undefined {
+  const message = input as {
+    conversation?: {
+      endpoint?: { id?: unknown; adapter?: unknown };
+      kind?: unknown;
+      id?: unknown;
+      parent?: OutboundSendInput['conversation']['parent'];
+      threadId?: unknown;
+    };
+    metadata?: Readonly<Record<string, unknown>>;
+  } | null | undefined;
+  const conversation = message?.conversation;
+  const endpointKeyRaw = conversation?.endpoint?.id;
+  const adapterRaw = conversation?.endpoint?.adapter;
+  const kind = conversation?.kind;
+  const id = conversation?.id;
+  if (
+    endpointKeyRaw == null
+    || adapterRaw == null
+    || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
+    || typeof id !== 'string'
+    || !id
+  ) {
+    return undefined;
+  }
+  const live = String(message?.metadata?.endpoint ?? message?.metadata?.endpointKey ?? '').trim();
+  return {
+    adapter: String(adapterRaw),
+    endpointKey: live || String(endpointKeyRaw),
+    conversation: {
+      kind,
+      id,
+      parent: conversation.parent,
+      threadId: typeof conversation.threadId === 'string' ? conversation.threadId : undefined,
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // 运行时状态：adapter create() 注册的 running endpoints
 // ---------------------------------------------------------------------------
 
 export interface EndpointRunningInfo {
-  readonly name: string;
+  readonly id: string;
   /** 连接模式（ws / wss / polling / socket-mode …），仅用于 list 展示。 */
   readonly mode?: string;
 }
 
 export interface EndpointRuntimeState {
-  /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+  /** 当前 generation 已成功创建的 endpoint（id → 描述） */
   readonly endpoints: Map<string, EndpointRunningInfo>;
 }
 
@@ -127,10 +199,10 @@ function envSlug(text: string): string {
 /** 派生 endpoint 凭据的 env 键：`${ADAPTER}_${NAME}_${FIELD}`（如 `TELEGRAM_MY_BOT_TOKEN`） */
 export function buildEndpointEnvKey(
   adapterKey: string,
-  endpointName: string,
+  endpointId: string,
   fieldKey: string,
 ): string {
-  return `${envSlug(adapterKey)}_${envSlug(endpointName)}_${envSlug(fieldKey)}`;
+  return `${envSlug(adapterKey)}_${envSlug(endpointId)}_${envSlug(fieldKey)}`;
 }
 
 function escapeRegExp(text: string): string {
@@ -170,7 +242,7 @@ export function persistEndpointEnvValues(
 // ---------------------------------------------------------------------------
 
 export interface ConfiguredEndpointEntry {
-  name: string;
+  id: string;
   [key: string]: unknown;
 }
 
@@ -223,14 +295,14 @@ export function listConfiguredEndpoints(
   if (!Array.isArray(endpoints)) return [];
   return endpoints.filter(
     (entry): entry is ConfiguredEndpointEntry =>
-      !!entry && typeof entry === 'object' && typeof (entry as { name?: unknown }).name === 'string',
+      !!entry && typeof entry === 'object' && typeof (entry as { id?: unknown }).id === 'string',
   );
 }
 
-function entryName(item: unknown): string | undefined {
+function entryId(item: unknown): string | undefined {
   if (!isMap(item)) return undefined;
-  const name = item.get('name');
-  return typeof name === 'string' && name ? name : undefined;
+  const id = item.get('id');
+  return typeof id === 'string' && id ? id : undefined;
 }
 
 /**
@@ -269,7 +341,7 @@ function ensureEndpointsSeq(
   return doc.getIn(['plugins', adapterKey, 'endpoints']) as YAMLSeq;
 }
 
-/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；name 已存在时报错 */
+/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；id 已存在时报错 */
 export function addEndpointToConfig(
   adapterKey: string,
   entry: ConfiguredEndpointEntry,
@@ -277,23 +349,23 @@ export function addEndpointToConfig(
 ): string {
   const document = readConfigDocument(adapterKey, projectRoot);
   const seq = ensureEndpointsSeq(document.doc, adapterKey);
-  if (seq.items.some((item) => entryName(item) === entry.name)) {
-    throw new Error(`配置中已存在 ${adapterKey} endpoint「${entry.name}」，可先 ${adapterKey}.endpoint remove ${entry.name} 再重新添加`);
+  if (seq.items.some((item) => entryId(item) === entry.id)) {
+    throw new Error(`配置中已存在 ${adapterKey} endpoint「${entry.id}」，可先 ${adapterKey}.endpoint remove ${entry.id} 再重新添加`);
   }
   seq.items.push(document.doc.createNode(entry));
   writeConfigDocument(document);
   return document.filePath;
 }
 
-/** 按 name 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
+/** 按 id 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
 export function removeEndpointFromConfig(
   adapterKey: string,
-  name: string,
+  id: string,
   projectRoot?: string,
 ): { removed: boolean; filePath: string } {
   const document = readConfigDocument(adapterKey, projectRoot);
   const seq = ensureEndpointsSeq(document.doc, adapterKey);
-  const next = seq.items.filter((item) => entryName(item) !== name);
+  const next = seq.items.filter((item) => entryId(item) !== id);
   if (next.length === seq.items.length) {
     return { removed: false, filePath: document.filePath };
   }
@@ -322,9 +394,9 @@ export type EndpointCommandUse = <T>(token: Token<T>) => T;
 
 /** bindFlow 钩子上下文：接管 add 命令的自定义绑定流程（如 QQ 扫码）。 */
 export interface EndpointBindFlowContext {
-  /** 命令参数 name（未指定时为 undefined，流程可自行决定终名） */
-  readonly name?: string;
-  /** 向当前会话推送后续状态（二维码刷新 / 成功 / 失败） */
+  /** 命令参数 id（未指定时为 undefined，流程可自行决定终名） */
+  readonly id?: string;
+  /** 向当前会话推送后续状态（二维码刷新 / 成功 / 失败；走 durable OutboundHost，可在命令 reply scope 结束后调用） */
   readonly reply: EndpointCommandReply;
   readonly config: unknown;
   readonly input: unknown;
@@ -406,9 +478,9 @@ export interface EndpointCommands<TCommand = EndpointCommandDefinition> {
   readonly remove: TCommand;
 }
 
-function endpointNameParam(params: Readonly<Record<string, unknown>>): string | undefined {
-  const name = params.name;
-  return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+function endpointIdParam(params: Readonly<Record<string, unknown>>): string | undefined {
+  const id = params.id;
+  return typeof id === 'string' && id.trim() ? id.trim() : undefined;
 }
 
 /** list 文案：运行中 + 配置中两段，footer 可选。 */
@@ -427,7 +499,7 @@ export function formatEndpointList(
     lines.push('  （无）');
   } else {
     for (const endpoint of running) {
-      lines.push(endpoint.mode ? `  - ${endpoint.name}（${endpoint.mode}）` : `  - ${endpoint.name}`);
+      lines.push(endpoint.mode ? `  - ${endpoint.id}（${endpoint.mode}）` : `  - ${endpoint.id}`);
     }
   }
   lines.push(`【配置中的 ${spec.adapterDisplayName} endpoints】（zhin.config.yml → plugins.${spec.adapterKey}.endpoints）`);
@@ -436,7 +508,7 @@ export function formatEndpointList(
   } else {
     for (const entry of source.configured) {
       const detail = spec.describeEntry?.(entry);
-      lines.push(detail ? `  - ${entry.name}（${detail}）` : `  - ${entry.name}`);
+      lines.push(detail ? `  - ${entry.id}（${detail}）` : `  - ${entry.id}`);
     }
   }
   if (source.footer) lines.push(source.footer);
@@ -455,13 +527,13 @@ function addUsage(spec: EndpointCommandsSpec): string {
       ].filter(Boolean).join('，');
       return marks ? `${field.key}（${marks}）` : field.key;
     }).join('、')}`;
-  return `用法：${spec.adapterKey}.endpoint add <name> <key=value...>${fieldText}`;
+  return `用法：${spec.adapterKey}.endpoint add <id> <key=value...>${fieldText}`;
 }
 
 /** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
 export function addEndpointFromKeyValues(
   spec: EndpointCommandsSpec,
-  name: string,
+  id: string,
   args: readonly string[],
   projectRoot?: string,
 ): string {
@@ -484,13 +556,13 @@ export function addEndpointFromKeyValues(
   if (missing.length > 0) {
     return `缺少必填字段：${missing.map((field) => field.key).join('、')}。${addUsage(spec)}`;
   }
-  const entry: ConfiguredEndpointEntry = { name };
+  const entry: ConfiguredEndpointEntry = { id };
   const envValues: Record<string, string> = {};
   for (const field of fields) {
     const value = values.get(field.key);
     if (value === undefined) continue;
     if (field.env) {
-      const envKey = buildEndpointEnvKey(spec.adapterKey, name, field.key);
+      const envKey = buildEndpointEnvKey(spec.adapterKey, id, field.key);
       envValues[envKey] = value;
       entry[field.key] = `\${${envKey}}`;
     } else {
@@ -498,11 +570,10 @@ export function addEndpointFromKeyValues(
     }
   }
   try {
-    // 先写配置（重名等校验失败时不留孤儿 .env 键），再落 .env 凭据
     const filePath = addEndpointToConfig(spec.adapterKey, entry, projectRoot);
     if (Object.keys(envValues).length > 0) persistEndpointEnvValues(envValues, projectRoot);
     return (
-      `✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.${spec.adapterKey}.endpoints` +
+      `✅ endpoint「${id}」已追加到 ${filePath} 的 plugins.${spec.adapterKey}.endpoints` +
       `${Object.keys(envValues).length > 0 ? '（凭据已写入 .env）' : ''}。\n` +
       '⚠️ 需重启 zhin 后新 endpoint 才会生效。'
     );
@@ -512,13 +583,13 @@ export function addEndpointFromKeyValues(
 }
 
 /** remove 的完整业务逻辑：从 yaml 移除；返回回复文本。 */
-export function removeEndpointByName(
+export function removeEndpointById(
   spec: Pick<EndpointCommandsSpec, 'adapterKey'>,
-  name: string,
+  id: string,
   projectRoot?: string,
 ): string {
-  const trimmed = name.trim();
-  if (!trimmed) return `用法：${spec.adapterKey}.endpoint remove <name>`;
+  const trimmed = id.trim();
+  if (!trimmed) return `用法：${spec.adapterKey}.endpoint remove <id>`;
   try {
     const { removed, filePath } = removeEndpointFromConfig(spec.adapterKey, trimmed, projectRoot);
     if (!removed) {
@@ -553,29 +624,29 @@ export function createEndpointCommands<TCommand>(
     add: defineCommand({
       description: spec.addDescription
         ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
-      params: { name: { type: 'string', description: 'endpoint 名称' } },
+      params: { id: { type: 'string', description: 'endpoint ID' } },
       execute({ config, input, params, args, use }) {
         if (!isEndpointOperator(config, input)) return forbidden;
-        const name = endpointNameParam(params);
+        const id = endpointIdParam(params);
         if (spec.bindFlow) {
           return spec.bindFlow({
-            name,
-            reply: extractEndpointCommandReply(input),
+            id,
+            reply: createDurableEndpointCommandReply(input, use),
             config,
             input,
             use,
           });
         }
-        if (!name) return addUsage(spec);
-        return addEndpointFromKeyValues(spec, name, args);
+        if (!id) return addUsage(spec);
+        return addEndpointFromKeyValues(spec, id, args);
       },
     }),
     remove: defineCommand({
       description: `从 zhin.config.yml 的 plugins.${spec.adapterKey}.endpoints 移除指定 endpoint（重启生效）`,
-      params: { name: { type: 'string', description: 'endpoint 名称' } },
+      params: { id: { type: 'string', description: 'endpoint ID' } },
       execute({ config, input, params }) {
         if (!isEndpointOperator(config, input)) return forbidden;
-        return removeEndpointByName(spec, String(params.name ?? ''));
+        return removeEndpointById(spec, String(params.id ?? ''));
       },
     }),
   });

package/src/endpoint-control.ts

@@ -1,9 +1,4 @@
-import {
-  formatLegacyConversationRef,
-  formatLegacyMessageRef,
-  type ConversationTarget,
-  type MessageTarget,
-} from '@zhin.js/im-contract';
+import type { ConversationRef, MessageRef } from '@zhin.js/im-contract';
 
 /**
  * Transport-neutral control plane for a live endpoint.
@@ -13,100 +8,26 @@ import {
  * to know a protocol's method names or identifier layout.
  */
 export interface EndpointControl {
-  recall?(message: MessageTarget): Promise<void>;
-  edit?(message: MessageTarget, content: unknown): Promise<string | null>;
+  recall?(message: MessageRef): Promise<void>;
+  edit?(message: MessageRef, content: unknown): Promise<string | null>;
   addReaction?(
-    message: MessageTarget,
+    message: MessageRef,
     emoji: string,
     hint?: { readonly sceneType?: string; readonly channelId?: string },
   ): Promise<string | null>;
-  removeReaction?(message: MessageTarget, reactionId: string): Promise<void>;
-  typing?(conversation: ConversationTarget, active?: boolean): Promise<void>;
+  removeReaction?(message: MessageRef, reactionId: string): Promise<void>;
+  typing?(conversation: ConversationRef, active?: boolean): Promise<void>;
 }
 
 export interface EndpointWithControl {
   readonly control?: EndpointControl;
 }
 
-interface LegacyEndpointControlSurface {
-  recallMessage?(messageId: string): Promise<void>;
-  $recallMessage?(messageId: string): Promise<void>;
-  editMessage?(messageId: string, content: unknown): Promise<string | null>;
-  $editMessage?(messageId: string, content: unknown): Promise<string | null>;
-  addReaction?(
-    messageId: string,
-    emoji: string,
-    hint?: { readonly sceneType?: string; readonly channelId?: string },
-  ): Promise<string | null>;
-  $addReaction?(
-    messageId: string,
-    emoji: string,
-    hint?: { readonly sceneType?: string; readonly channelId?: string },
-  ): Promise<string | null>;
-  removeReaction?(messageId: string, reactionId: string): Promise<void>;
-  $removeReaction?(messageId: string, reactionId: string): Promise<void>;
-  typing?(target: string, active?: boolean): Promise<void>;
-  $typing?(target: string, active?: boolean): Promise<void>;
-}
-
-/**
- * Resolves the public control port. The legacy branch is deliberately kept in
- * Adapter only: it is a migration bridge for existing protocol endpoints, not
- * an IM Core extension point. New adapters must expose `control` directly.
- */
-export function resolveEndpointControl(endpoint: unknown): EndpointControl | undefined {
+/** Reads the canonical control port without probing protocol-specific methods. */
+export function endpointControlOf(endpoint: unknown): EndpointControl | undefined {
   if (!endpoint || typeof endpoint !== 'object') return undefined;
   const explicit = (endpoint as EndpointWithControl).control;
-  if (explicit && typeof explicit === 'object') return explicit;
-
-  const legacy = endpoint as LegacyEndpointControlSurface;
-  const recall = legacy.recallMessage ?? legacy.$recallMessage;
-  const edit = legacy.editMessage ?? legacy.$editMessage;
-  const addReaction = legacy.addReaction ?? legacy.$addReaction;
-  const removeReaction = legacy.removeReaction ?? legacy.$removeReaction;
-  const typing = legacy.typing ?? legacy.$typing;
-  if (!recall && !edit && !addReaction && !removeReaction && !typing) return undefined;
-
-  return Object.freeze({
-    ...(recall
-      ? { recall: (message: MessageTarget) => recall.call(endpoint, legacyMessageId(message)) }
-      : {}),
-    ...(edit
-      ? {
-        edit: (message: MessageTarget, content: unknown) =>
-          edit.call(endpoint, legacyMessageId(message), content),
-      }
-      : {}),
-    ...(addReaction
-      ? {
-        addReaction: (
-          message: MessageTarget,
-          emoji: string,
-          hint?: { readonly sceneType?: string; readonly channelId?: string },
-        ) => addReaction.call(endpoint, legacyMessageId(message), emoji, hint),
-      }
-      : {}),
-    ...(removeReaction
-      ? {
-        removeReaction: (message: MessageTarget, reactionId: string) =>
-          removeReaction.call(endpoint, legacyMessageId(message), reactionId),
-      }
-      : {}),
-    ...(typing
-      ? {
-        typing: (conversation: ConversationTarget, active?: boolean) =>
-          typing.call(endpoint, legacyConversationTarget(conversation), active),
-      }
-      : {}),
-  });
-}
-
-function legacyMessageId(message: MessageTarget): string {
-  return typeof message === 'string' ? message : formatLegacyMessageRef(message);
-}
-
-function legacyConversationTarget(conversation: ConversationTarget): string {
-  return typeof conversation === 'string' ? conversation : formatLegacyConversationRef(conversation);
+  return explicit && typeof explicit === 'object' ? explicit : undefined;
 }
 
 /** Checks only an Endpoint's explicit `control` port, never the legacy bridge. */

package/src/endpoint-lifecycle.ts

@@ -19,7 +19,7 @@
  *
  * 迁移指引（以 napcat/milky/onebot WS endpoint 为例）：
  * 1. 删除 #started / #stopping / #reconnectTimer / #heartbeatTimer / opened 旗标，
- *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.name, reconnect, heartbeat })`。
+ *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.id, reconnect, heartbeat })`。
  * 2. `start()` 改为：
  *    ```ts
  *    this.#unregisterAgent = registerXxxAgentEndpoint(name, this); // agent 注册仍在适配器侧

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { featureId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { featureId } from '@zhin.js/plugin-runtime';
 import { defineFeatureProvider, typeScriptModules } from '@zhin.js/feature-kit';
 import { AdapterIndex } from './adapter-index.js';
 import { parseAdapterDefinition } from './definition.js';
@@ -18,31 +18,18 @@ const adapterFeature = defineFeatureProvider({
   },
   runtime: {
     async project(slots, context) {
-      const index = await AdapterIndex.create(slots, context.snapshot);
-      let previousIndex: AdapterIndex | undefined;
+      const index = await AdapterIndex.create(slots, context.snapshot, context.signal);
       return {
         value: index,
         dispose: () => index.stop(),
         handoff: {
-          quiescePrevious(previous) {
-            previousIndex = previousAdapterIndex(previous);
-            return previousIndex?.close();
-          },
-          activateNext: () => index.start(),
+          activateNext: (signal) => index.activate(signal),
           deactivateNext: () => index.stop(),
-          resumePrevious() {
-            previousIndex?.open();
-          },
-          openNext: () => index.open(),
         },
       };
     },
   },
 });
 
-function previousAdapterIndex(snapshot: RuntimeSnapshot): AdapterIndex | undefined {
-  return snapshot.projections.get(adapterFeatureId) as AdapterIndex | undefined;
-}
-
 export { adapterFeature };
 export default adapterFeature;