@zhin.js/adapter 1.1.2 → 1.1.3

package/README.md

@@ -19,6 +19,30 @@ export default defineAdapter({
 单文件插件可用 `setup({ addAdapter })` 注册 `defineAdapter(...)`；Endpoint 仍由同一个
 AdapterIndex 和 generation handoff 管理。
 
+## Transport Contract
+
+Adapter definitions declare `capabilities` for inbound/outbound admission and
+`operations` for optional actions such as `recall`, `edit`, `reaction`, and
+`typing`. Runtime callers should query the resulting `EndpointCapabilities`
+instead of probing optional endpoint methods. The zero-dependency types live in
+[`@zhin.js/im-contract`](../im-contract/README.md).
+
+New framework-facing outbound code should carry a structured `ConversationRef`.
+`EndpointSendRequest.target` remains temporarily for platform codecs that still
+need their legacy target string; it is not a general-purpose message identity.
+
+## Endpoint Control Port
+
+`EndpointInstance.control` owns actions addressed to an existing message:
+`recall`, `addReaction`, and `removeReaction`. IM Core consumes only this port;
+adapter-specific method names and compound message ids stay at the protocol
+boundary.
+
+New adapters should provide `control` directly and declare matching
+`operations`. During the 4.x migration, `resolveEndpointControl()` can adapt
+legacy `recallMessage` / `$recallMessage` / reaction methods, but that bridge
+exists only in this package and is not a public extension pattern.
+
 ## Endpoint 生命周期基座（createEndpointLifecycle）
 
 WS/SSE 类端点的 start/stop/重连/心跳统一走 `createEndpointLifecycle`

package/lib/adapter-index.js

@@ -2,6 +2,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';
+import { assertDeclaredEndpointOperations } from './endpoint-control.js';
 const logger = getLogger('Adapter');
 export class AdapterIndex {
     $projection = 'zhin.adapter-index/1';
@@ -405,6 +406,7 @@ async function createEndpointSoft(slot, snapshot, expansion) {
     // 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, expansion?.id ?? slot.id);
+    assertDeclaredEndpointOperations(endpoint, slot.definition.operations, String(expansion?.id ?? slot.id));
     return { instance: endpoint, unconfigured: false };
 }
 function createUnconfiguredEndpoint(reason) {

package/lib/definition.d.ts

@@ -1,13 +1,23 @@
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
+import type { ConversationRef, EndpointCapabilities, EndpointOperation } from '@zhin.js/im-contract';
 import type { EndpointManagement } from './endpoint-management.js';
+import type { EndpointControl } from './endpoint-control.js';
 declare const adapterBrand: "zhin.adapter/1";
 export type AdapterCapability = 'inbound' | 'outbound';
+/** Operations beyond sending, declared by an Adapter definition. */
+export type AdapterOperation = Exclude<EndpointOperation, 'send'>;
 /** 端点可消费的出站媒体来源形式。 */
 export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 /** 交互段（卡片/按钮等富交互）的端点消费方式。 */
 export type AdapterInteractiveMode = 'native' | 'text';
 export interface EndpointSendRequest {
+    /**
+     * Structured identity for new callers. The target remains until every
+     * platform adapter has migrated its native boundary codec.
+     */
+    readonly conversation?: ConversationRef;
+    /** @deprecated Use conversation for framework-facing code. */
     readonly target: string;
     readonly payload: unknown;
     readonly parent?: {
@@ -19,6 +29,8 @@ export interface EndpointSendRequest {
 export interface EndpointInstance<TResult = unknown> {
     /** Optional platform-neutral Console/Host management surface. */
     readonly management?: EndpointManagement;
+    /** Optional platform-neutral control surface for existing messages. */
+    readonly control?: EndpointControl;
     /** Allocates transport resources but must not admit inbound events yet. */
     start?(): void | Promise<void>;
     /** Opens admission after the candidate generation has committed. */
@@ -65,6 +77,12 @@ export interface AdapterSegmentPolicy {
 export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
     readonly $feature: typeof adapterBrand;
     readonly capabilities: readonly AdapterCapability[];
+    /**
+     * Explicit support for operations other than send. `send` is derived from
+     * `capabilities: ['outbound']`; a method existing on an endpoint is not a
+     * capability declaration.
+     */
+    readonly operations?: readonly AdapterOperation[];
     /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
     readonly segments?: AdapterSegmentPolicy;
     create(context: AdapterContext<TConfig>): EndpointInstance<TResult> | Promise<EndpointInstance<TResult>>;
@@ -75,5 +93,7 @@ declare module '@zhin.js/plugin-runtime' {
     }
 }
 export declare function defineAdapter<TConfig = unknown, TResult = unknown>(definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>): Readonly<AdapterDefinition<TConfig, TResult>>;
+/** Converts the definition's compact authoring form into the public contract. */
+export declare function endpointCapabilitiesOf(definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>): EndpointCapabilities;
 export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
 export {};

package/lib/definition.js

@@ -3,6 +3,7 @@ const HTML_OUTBOUND_MODES = ['direct', 'image', 'text'];
 const OUTBOUND_MEDIA_FORMS = [
     'url', 'path', 'base64', 'upload',
 ];
+const ADAPTER_OPERATIONS = ['recall', 'edit', 'reaction', 'typing'];
 export function defineAdapter(definition) {
     if (typeof definition.create !== 'function') {
         throw new TypeError('Adapter create must be a function');
@@ -13,13 +14,33 @@ export function defineAdapter(definition) {
         throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
     }
     const segments = normalizeSegmentPolicy(definition.segments);
+    const operations = normalizeOperations(definition.operations);
     return Object.freeze({
         ...definition,
         $feature: adapterBrand,
         capabilities: Object.freeze(capabilities),
+        ...(operations ? { operations } : {}),
         ...(segments ? { segments } : {}),
     });
 }
+/** Converts the definition's compact authoring form into the public contract. */
+export function endpointCapabilitiesOf(definition) {
+    const operations = definition.operations?.reduce((result, operation) => ({ ...result, [operation]: true }), {});
+    return Object.freeze({
+        inbound: definition.capabilities.includes('inbound'),
+        outbound: definition.capabilities.includes('outbound'),
+        ...(operations && Object.keys(operations).length > 0 ? { operations: Object.freeze(operations) } : {}),
+    });
+}
+function normalizeOperations(operations) {
+    if (operations === undefined)
+        return undefined;
+    if (!Array.isArray(operations)
+        || operations.some((operation) => !ADAPTER_OPERATIONS.includes(operation))) {
+        throw new TypeError('Adapter operations must be recall, edit, reaction and/or typing');
+    }
+    return Object.freeze([...new Set(operations)]);
+}
 function normalizeSegmentPolicy(policy) {
     if (policy === undefined)
         return undefined;
@@ -66,6 +87,7 @@ export function parseAdapterDefinition(value) {
         throw invalidAdapter();
     // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
     normalizeSegmentPolicy(definition.segments);
+    normalizeOperations(definition.operations);
     return definition;
 }
 function invalidAdapter() {

package/lib/endpoint-commands.js

@@ -1,14 +1,14 @@
 /**
  * createEndpointCommands — 适配器 endpoint 管理命令套件（list / add / remove）。
  *
- * 把 QQ 适配器独有的 `qq endpoint` 命令族泛化为任意适配器可复用的套件：
+ * 把 QQ 适配器独有的 `qq.endpoint` 命令族泛化为任意适配器可复用的套件：
  *
- * - `<adapter> endpoint list`：运行中的 endpoints（adapter create 注册的 runtime state）
+ * - `<adapter>.endpoint list`：运行中的 endpoints（adapter create 注册的 runtime state）
  *   + zhin.config.yml 配置里的 `plugins.<adapterKey>.endpoints`。
- * - `<adapter> endpoint add <name> <key=value...>`：手动录入字段，
+ * - `<adapter>.endpoint add <name> <key=value...>`：手动录入字段，
  *   凭据类字段（env: true）值写入 .env（`<ADAPTER>_<NAME>_<FIELD>` 大写键），
  *   yaml 中保存 `${REF}` 引用；其余字段内联写入。yaml 用 Document 节点级操作保留注释。
- * - `<adapter> endpoint remove <name>`：从 `plugins.<adapterKey>.endpoints` 移除（重启生效）。
+ * - `<adapter>.endpoint remove <name>`：从 `plugins.<adapterKey>.endpoints` 移除（重启生效）。
  * - 权限：实例 config 声明了 master（顶层或 endpoints[i]）时仅 master 可用 add/remove，
  *   未配置放行（isEndpointOperator）。
  * - 特殊 add 流程（如 QQ 扫码绑定）经 spec.bindFlow 钩子接管 add 命令。
@@ -207,7 +207,7 @@ export function addEndpointToConfig(adapterKey, entry, projectRoot) {
     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} 再重新添加`);
+        throw new Error(`配置中已存在 ${adapterKey} endpoint「${entry.name}」，可先 ${adapterKey}.endpoint remove ${entry.name} 再重新添加`);
     }
     seq.items.push(document.doc.createNode(entry));
     writeConfigDocument(document);
@@ -268,7 +268,7 @@ function addUsage(spec) {
             ].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 <name> <key=value...>${fieldText}`;
 }
 /** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
 export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
@@ -325,7 +325,7 @@ export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
 export function removeEndpointByName(spec, name, projectRoot) {
     const trimmed = name.trim();
     if (!trimmed)
-        return `用法：${spec.adapterKey} endpoint remove <name>`;
+        return `用法：${spec.adapterKey}.endpoint remove <name>`;
     try {
         const { removed, filePath } = removeEndpointFromConfig(spec.adapterKey, trimmed, projectRoot);
         if (!removed) {

package/lib/endpoint-control.d.ts

@@ -0,0 +1,31 @@
+import { type ConversationTarget, type MessageTarget } from '@zhin.js/im-contract';
+/**
+ * Transport-neutral control plane for a live endpoint.
+ *
+ * Sending belongs to EndpointInstance.send(). This port intentionally owns
+ * operations that address an existing platform message, so Core never needs
+ * 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>;
+    addReaction?(message: MessageTarget, 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>;
+}
+export interface EndpointWithControl {
+    readonly control?: EndpointControl;
+}
+/**
+ * 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 declare function resolveEndpointControl(endpoint: unknown): EndpointControl | undefined;
+/** Checks only an Endpoint's explicit `control` port, never the legacy bridge. */
+export declare function hasExplicitEndpointOperation(endpoint: unknown, operation: 'recall' | 'edit' | 'reaction' | 'typing'): boolean;
+/** Rejects a declaration that cannot be fulfilled by the explicit control port. */
+export declare function assertDeclaredEndpointOperations(endpoint: unknown, operations: readonly ('recall' | 'edit' | 'reaction' | 'typing')[] | undefined, id: string): void;

package/lib/endpoint-control.js

@@ -0,0 +1,77 @@
+import { formatLegacyConversationRef, formatLegacyMessageRef, } from '@zhin.js/im-contract';
+/**
+ * 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) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return undefined;
+    const explicit = endpoint.control;
+    if (explicit && typeof explicit === 'object')
+        return explicit;
+    const legacy = endpoint;
+    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) => recall.call(endpoint, legacyMessageId(message)) }
+            : {}),
+        ...(edit
+            ? {
+                edit: (message, content) => edit.call(endpoint, legacyMessageId(message), content),
+            }
+            : {}),
+        ...(addReaction
+            ? {
+                addReaction: (message, emoji, hint) => addReaction.call(endpoint, legacyMessageId(message), emoji, hint),
+            }
+            : {}),
+        ...(removeReaction
+            ? {
+                removeReaction: (message, reactionId) => removeReaction.call(endpoint, legacyMessageId(message), reactionId),
+            }
+            : {}),
+        ...(typing
+            ? {
+                typing: (conversation, active) => typing.call(endpoint, legacyConversationTarget(conversation), active),
+            }
+            : {}),
+    });
+}
+function legacyMessageId(message) {
+    return typeof message === 'string' ? message : formatLegacyMessageRef(message);
+}
+function legacyConversationTarget(conversation) {
+    return typeof conversation === 'string' ? conversation : formatLegacyConversationRef(conversation);
+}
+/** Checks only an Endpoint's explicit `control` port, never the legacy bridge. */
+export function hasExplicitEndpointOperation(endpoint, operation) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return false;
+    const control = endpoint.control;
+    if (!control || typeof control !== 'object')
+        return false;
+    switch (operation) {
+        case 'recall': return typeof control.recall === 'function';
+        case 'edit': return typeof control.edit === 'function';
+        case 'reaction': return typeof control.addReaction === 'function';
+        case 'typing': return typeof control.typing === 'function';
+    }
+}
+/** Rejects a declaration that cannot be fulfilled by the explicit control port. */
+export function assertDeclaredEndpointOperations(endpoint, operations, id) {
+    for (const operation of operations ?? []) {
+        if (!hasExplicitEndpointOperation(endpoint, operation)) {
+            throw new TypeError(`Adapter Endpoint ${id} declares ${operation} but control.${controlMethodName(operation)} is missing`);
+        }
+    }
+}
+function controlMethodName(operation) {
+    return operation === 'reaction' ? 'addReaction' : operation;
+}

package/lib/index.d.ts

@@ -6,5 +6,6 @@ export * from './definition.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
+export * from './endpoint-control.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -6,5 +6,6 @@ export * from './definition.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
+export * from './endpoint-control.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,13 +19,14 @@
   "dependencies": {
     "yaml": "^2.9.0",
     "@zhin.js/feature-kit": "1.0.4",
+    "@zhin.js/im-contract": "1.0.0",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.4"
+    "@zhin.js/command": "1.0.5"
   },
   "zhin": {
     "protocol": 1,

package/src/adapter-index.ts

@@ -18,6 +18,7 @@ import {
   listEndpointManagementCapabilities,
   type EndpointManagementCapability,
 } from './endpoint-management.js';
+import { assertDeclaredEndpointOperations } from './endpoint-control.js';
 
 const logger = getLogger('Adapter');
 
@@ -503,6 +504,11 @@ async function createEndpointSoft(
   // 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, expansion?.id ?? slot.id);
+  assertDeclaredEndpointOperations(
+    endpoint,
+    slot.definition.operations,
+    String(expansion?.id ?? slot.id),
+  );
   return { instance: endpoint, unconfigured: false };
 }
 

package/src/definition.ts

@@ -1,11 +1,20 @@
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
+import type {
+  ConversationRef,
+  EndpointCapabilities,
+  EndpointOperation,
+} from '@zhin.js/im-contract';
 import type { EndpointManagement } from './endpoint-management.js';
+import type { EndpointControl } from './endpoint-control.js';
 
 const adapterBrand = 'zhin.adapter/1' as const;
 
 export type AdapterCapability = 'inbound' | 'outbound';
 
+/** Operations beyond sending, declared by an Adapter definition. */
+export type AdapterOperation = Exclude<EndpointOperation, 'send'>;
+
 /** 端点可消费的出站媒体来源形式。 */
 export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 
@@ -13,6 +22,12 @@ export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 export type AdapterInteractiveMode = 'native' | 'text';
 
 export interface EndpointSendRequest {
+  /**
+   * Structured identity for new callers. The target remains until every
+   * platform adapter has migrated its native boundary codec.
+   */
+  readonly conversation?: ConversationRef;
+  /** @deprecated Use conversation for framework-facing code. */
   readonly target: string;
   readonly payload: unknown;
   readonly parent?: { readonly type?: string; readonly id?: string; readonly name?: string };
@@ -21,6 +36,8 @@ export interface EndpointSendRequest {
 export interface EndpointInstance<TResult = unknown> {
   /** Optional platform-neutral Console/Host management surface. */
   readonly management?: EndpointManagement;
+  /** Optional platform-neutral control surface for existing messages. */
+  readonly control?: EndpointControl;
   /** Allocates transport resources but must not admit inbound events yet. */
   start?(): void | Promise<void>;
   /** Opens admission after the candidate generation has committed. */
@@ -74,9 +91,17 @@ const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
   'url', 'path', 'base64', 'upload',
 ];
 
+const ADAPTER_OPERATIONS: readonly AdapterOperation[] = ['recall', 'edit', 'reaction', 'typing'];
+
 export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
   readonly $feature: typeof adapterBrand;
   readonly capabilities: readonly AdapterCapability[];
+  /**
+   * Explicit support for operations other than send. `send` is derived from
+   * `capabilities: ['outbound']`; a method existing on an endpoint is not a
+   * capability declaration.
+   */
+  readonly operations?: readonly AdapterOperation[];
   /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
   readonly segments?: AdapterSegmentPolicy;
   create(
@@ -107,14 +132,44 @@ export function defineAdapter<TConfig = unknown, TResult = unknown>(
     throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
   }
   const segments = normalizeSegmentPolicy(definition.segments);
+  const operations = normalizeOperations(definition.operations);
   return Object.freeze({
     ...definition,
     $feature: adapterBrand,
     capabilities: Object.freeze(capabilities),
+    ...(operations ? { operations } : {}),
     ...(segments ? { segments } : {}),
   });
 }
 
+/** Converts the definition's compact authoring form into the public contract. */
+export function endpointCapabilitiesOf(
+  definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>,
+): EndpointCapabilities {
+  const operations = definition.operations?.reduce<Partial<Record<AdapterOperation, true>>>(
+    (result, operation) => ({ ...result, [operation]: true }),
+    {},
+  );
+  return Object.freeze({
+    inbound: definition.capabilities.includes('inbound'),
+    outbound: definition.capabilities.includes('outbound'),
+    ...(operations && Object.keys(operations).length > 0 ? { operations: Object.freeze(operations) } : {}),
+  });
+}
+
+function normalizeOperations(
+  operations: readonly AdapterOperation[] | undefined,
+): readonly AdapterOperation[] | undefined {
+  if (operations === undefined) return undefined;
+  if (
+    !Array.isArray(operations)
+    || operations.some((operation) => !ADAPTER_OPERATIONS.includes(operation))
+  ) {
+    throw new TypeError('Adapter operations must be recall, edit, reaction and/or typing');
+  }
+  return Object.freeze([...new Set(operations)]);
+}
+
 function normalizeSegmentPolicy(
   policy: AdapterSegmentPolicy | undefined,
 ): AdapterSegmentPolicy | undefined {
@@ -175,6 +230,7 @@ export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   ) throw invalidAdapter();
   // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
   normalizeSegmentPolicy(definition.segments);
+  normalizeOperations(definition.operations);
   return definition as AdapterDefinition;
 }
 

package/src/endpoint-commands.ts

@@ -1,14 +1,14 @@
 /**
  * createEndpointCommands — 适配器 endpoint 管理命令套件（list / add / remove）。
  *
- * 把 QQ 适配器独有的 `qq endpoint` 命令族泛化为任意适配器可复用的套件：
+ * 把 QQ 适配器独有的 `qq.endpoint` 命令族泛化为任意适配器可复用的套件：
  *
- * - `<adapter> endpoint list`：运行中的 endpoints（adapter create 注册的 runtime state）
+ * - `<adapter>.endpoint list`：运行中的 endpoints（adapter create 注册的 runtime state）
  *   + zhin.config.yml 配置里的 `plugins.<adapterKey>.endpoints`。
- * - `<adapter> endpoint add <name> <key=value...>`：手动录入字段，
+ * - `<adapter>.endpoint add <name> <key=value...>`：手动录入字段，
  *   凭据类字段（env: true）值写入 .env（`<ADAPTER>_<NAME>_<FIELD>` 大写键），
  *   yaml 中保存 `${REF}` 引用；其余字段内联写入。yaml 用 Document 节点级操作保留注释。
- * - `<adapter> endpoint remove <name>`：从 `plugins.<adapterKey>.endpoints` 移除（重启生效）。
+ * - `<adapter>.endpoint remove <name>`：从 `plugins.<adapterKey>.endpoints` 移除（重启生效）。
  * - 权限：实例 config 声明了 master（顶层或 endpoints[i]）时仅 master 可用 add/remove，
  *   未配置放行（isEndpointOperator）。
  * - 特殊 add 流程（如 QQ 扫码绑定）经 spec.bindFlow 钩子接管 add 命令。
@@ -278,7 +278,7 @@ export function addEndpointToConfig(
   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} 再重新添加`);
+    throw new Error(`配置中已存在 ${adapterKey} endpoint「${entry.name}」，可先 ${adapterKey}.endpoint remove ${entry.name} 再重新添加`);
   }
   seq.items.push(document.doc.createNode(entry));
   writeConfigDocument(document);
@@ -434,7 +434,7 @@ 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 <name> <key=value...>${fieldText}`;
 }
 
 /** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
@@ -497,7 +497,7 @@ export function removeEndpointByName(
   projectRoot?: string,
 ): string {
   const trimmed = name.trim();
-  if (!trimmed) return `用法：${spec.adapterKey} endpoint remove <name>`;
+  if (!trimmed) return `用法：${spec.adapterKey}.endpoint remove <name>`;
   try {
     const { removed, filePath } = removeEndpointFromConfig(spec.adapterKey, trimmed, projectRoot);
     if (!removed) {

package/src/endpoint-control.ts

@@ -0,0 +1,145 @@
+import {
+  formatLegacyConversationRef,
+  formatLegacyMessageRef,
+  type ConversationTarget,
+  type MessageTarget,
+} from '@zhin.js/im-contract';
+
+/**
+ * Transport-neutral control plane for a live endpoint.
+ *
+ * Sending belongs to EndpointInstance.send(). This port intentionally owns
+ * operations that address an existing platform message, so Core never needs
+ * 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>;
+  addReaction?(
+    message: MessageTarget,
+    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>;
+}
+
+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 {
+  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);
+}
+
+/** Checks only an Endpoint's explicit `control` port, never the legacy bridge. */
+export function hasExplicitEndpointOperation(
+  endpoint: unknown,
+  operation: 'recall' | 'edit' | 'reaction' | 'typing',
+): boolean {
+  if (!endpoint || typeof endpoint !== 'object') return false;
+  const control = (endpoint as EndpointWithControl).control;
+  if (!control || typeof control !== 'object') return false;
+  switch (operation) {
+    case 'recall': return typeof control.recall === 'function';
+    case 'edit': return typeof control.edit === 'function';
+    case 'reaction': return typeof control.addReaction === 'function';
+    case 'typing': return typeof control.typing === 'function';
+  }
+}
+
+/** Rejects a declaration that cannot be fulfilled by the explicit control port. */
+export function assertDeclaredEndpointOperations(
+  endpoint: unknown,
+  operations: readonly ('recall' | 'edit' | 'reaction' | 'typing')[] | undefined,
+  id: string,
+): void {
+  for (const operation of operations ?? []) {
+    if (!hasExplicitEndpointOperation(endpoint, operation)) {
+      throw new TypeError(
+        `Adapter Endpoint ${id} declares ${operation} but control.${controlMethodName(operation)} is missing`,
+      );
+    }
+  }
+}
+
+function controlMethodName(operation: 'recall' | 'edit' | 'reaction' | 'typing'): string {
+  return operation === 'reaction' ? 'addReaction' : operation;
+}

package/src/index.ts

@@ -6,5 +6,6 @@ export * from './definition.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
+export * from './endpoint-control.js';
 export * from './provider.js';
 export { default } from './provider.js';