@zhin.js/adapter 1.1.4 → 1.1.7

package/README.md

@@ -27,9 +27,9 @@ Adapter definitions declare `capabilities` for inbound/outbound admission and
 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.
+Framework-facing outbound code carries a structured `ConversationRef`.
+`EndpointSendRequest` is `{ conversation, payload }`; platform adapters derive
+their native target from `conversation` at the endpoint boundary.
 
 ## Endpoint Control Port
 

package/lib/adapter-index.d.ts

@@ -31,11 +31,11 @@ export declare class AdapterIndex {
      * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
      * Matches local name, capability id, or owner path segments.
      */
-    resolve(adapter: string, endpointId: string): CapabilityId | undefined;
+    resolve(adapter: string, endpointKey: string): CapabilityId | undefined;
     /**
      * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
      */
-    instance(adapter: string, endpointId: string): EndpointInstance | undefined;
+    instance(adapter: string, endpointKey: string): EndpointInstance | undefined;
     owner(id: CapabilityId): PluginId;
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；

package/lib/adapter-index.js

@@ -28,13 +28,13 @@ export class AdapterIndex {
                 for (const expansion of expandEndpointConfigs(slot, snapshot)) {
                     const endpoint = await createEndpointSoft(slot, snapshot, expansion);
                     if (endpoint.unconfigured)
-                        unconfigured.push(expansion.name);
+                        unconfigured.push(expansion.endpointId);
                     records.push({
                         id: expansion.id,
                         owner: slot.owner,
-                        // 展开模式下 record name 即 endpoint 名（entry.name），
-                        // 保证 Console 展示与 resolve/instance 按 entry name 命中唯一 record
-                        name: expansion.name,
+                        // 展开模式下 record name 即 endpoint id（entry.id），
+                        // 保证 Console 展示与 resolve/instance 按 entry id 命中唯一 record
+                        name: expansion.endpointId,
                         source: slot.source,
                         capabilities: slot.definition.capabilities,
                         endpoint: endpoint.instance,
@@ -85,21 +85,21 @@ export class AdapterIndex {
      * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
      * Matches local name, capability id, or owner path segments.
      */
-    resolve(adapter, endpointId) {
-        const matches = this.#order.filter((record) => matchesEndpoint(record, adapter, endpointId));
+    resolve(adapter, endpointKey) {
+        const matches = this.#order.filter((record) => matchesEndpoint(record, adapter, endpointKey));
         if (matches.length === 1)
             return matches[0]?.id;
         if (matches.length === 0)
             return undefined;
-        // Prefer exact localName === endpointId when ambiguous.
-        const exact = matches.find((record) => record.name === endpointId);
+        // Prefer exact localName === endpointKey when ambiguous.
+        const exact = matches.find((record) => record.name === endpointKey);
         return exact?.id ?? matches[0]?.id;
     }
     /**
      * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
      */
-    instance(adapter, endpointId) {
-        const id = this.resolve(adapter, endpointId);
+    instance(adapter, endpointKey) {
+        const id = this.resolve(adapter, endpointKey);
         if (!id)
             return undefined;
         return this.#records.get(id)?.endpoint;
@@ -266,7 +266,7 @@ export function isAdapterIndex(value) {
     return !!value && typeof value === 'object'
         && value.$projection === 'zhin.adapter-index/1';
 }
-function matchesEndpoint(record, adapter, endpointId) {
+function matchesEndpoint(record, adapter, endpointKey) {
     // 消息上的 $adapter 是 CapabilityId 的 localName 段（多 endpoint 展开后形如
     // `icqq~8596238`）。CapabilityId 段分隔符是 \0（owner\0feature\0localName），
     // 不能用 `/` 去 endsWith，否则永远匹配不上（endpoint not found）。
@@ -281,10 +281,10 @@ function matchesEndpoint(record, adapter, endpointId) {
     // activity-feedback resolve with that id; slot.localName alone is not enough
     // when multiple plugin instances share localName "icqq".
     const liveName = endpointLiveName(record.endpoint);
-    const endpointOk = record.name === endpointId
-        || record.id === endpointId
-        || record.id.endsWith(`/${endpointId}`)
-        || (liveName !== undefined && liveName === endpointId);
+    const endpointOk = record.name === endpointKey
+        || record.id === endpointKey
+        || record.id.endsWith(`/${endpointKey}`)
+        || (liveName !== undefined && liveName === endpointKey);
     return adapterOk && endpointOk;
 }
 function endpointLiveName(endpoint) {
@@ -316,7 +316,7 @@ function isUnconfiguredError(error) {
         && /requires|not configured|missing|未配置|缺少/i.test(error.message));
 }
 /**
- * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{id, ...覆盖}]` 时
  * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
  * 否则按实例 config 创建单个 endpoint（历史行为）。
  */
@@ -325,53 +325,53 @@ function expandEndpointConfigs(slot, snapshot) {
     const raw = config?.endpoints;
     const entries = Array.isArray(raw)
         ? raw.filter((entry) => !!entry && typeof entry === 'object'
-            && typeof entry.name === 'string'
-            && entry.name.length > 0)
+            && typeof entry.id === 'string'
+            && entry.id.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',
+                reason: 'every endpoints entry is missing a non-empty string id',
             }));
         }
-        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+        return Object.freeze([{ id: slot.id, endpointId: slot.localName }]);
     }
     // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析
     const valid = entries.filter((entry) => {
-        if (/[~\0]/u.test(entry.name)) {
+        if (/[~\0]/u.test(entry.id)) {
             logger.warn(formatCompact({
-                op: 'adapter_endpoint_name_invalid',
+                op: 'adapter_endpoint_id_invalid',
                 id: slot.id,
-                name: entry.name,
+                endpointId: entry.id,
             }));
             return false;
         }
         return true;
     });
-    // 重名会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
+    // 重 id 会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
     const seen = new Set();
     const deduped = valid.filter((entry) => {
-        if (seen.has(entry.name)) {
+        if (seen.has(entry.id)) {
             logger.warn(formatCompact({
-                op: 'adapter_endpoint_name_duplicate',
+                op: 'adapter_endpoint_id_duplicate',
                 id: slot.id,
-                name: entry.name,
+                endpointId: entry.id,
             }));
             return false;
         }
-        seen.add(entry.name);
+        seen.add(entry.id);
         return true;
     });
     if (deduped.length === 0) {
-        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+        return Object.freeze([{ id: slot.id, endpointId: 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 }),
+        id: `${slot.id}~${entry.id}`,
+        endpointId: entry.id,
+        config: Object.freeze({ ...base, ...entry, id: entry.id }),
     })));
 }
 async function createEndpointSoft(slot, snapshot, expansion) {
@@ -394,7 +394,7 @@ async function createEndpointSoft(slot, snapshot, expansion) {
         log(formatCompact({
             op: 'adapter_create_soft_fail',
             id: expansion?.id ?? slot.id,
-            name: expansion?.name ?? slot.localName,
+            name: expansion?.endpointId ?? slot.localName,
             error: message,
         }));
         return {

package/lib/definition.d.ts

@@ -12,19 +12,9 @@ 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;
+    /** 结构化会话寻址；端点在平台边界自行派生原生 target。 */
+    readonly conversation: ConversationRef;
     readonly payload: unknown;
-    readonly parent?: {
-        readonly type?: string;
-        readonly id?: string;
-        readonly name?: string;
-    };
 }
 export interface EndpointInstance<TResult = unknown> {
     /** Optional platform-neutral Console/Host management surface. */

package/lib/endpoint-commands.d.ts

@@ -11,13 +11,18 @@ export type EndpointCommandReply = (text: string) => Promise<unknown>;
  * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
  */
 export declare function extractEndpointCommandReply(input: unknown): EndpointCommandReply;
+/**
+ * bindFlow 后续状态推送：优先走 OutboundHost（不受 inbound Message reply scope 限制）。
+ * 扫码绑定等长流程会在命令结果已送达、`$reply` 已冻结后继续 notify，必须用 durable 出站。
+ */
+export declare function createDurableEndpointCommandReply(input: unknown, use: EndpointCommandUse): EndpointCommandReply;
 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>;
 }
 export declare function createEndpointRuntimeState(): EndpointRuntimeState;
@@ -26,21 +31,21 @@ export declare function defineEndpointRuntimeStateToken(adapterKey: string): Tok
 /** 项目根：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;
+export declare function buildEndpointEnvKey(adapterKey: string, endpointId: string, fieldKey: string): string;
 /** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
 export declare function persistEndpointEnvValues(values: Readonly<Record<string, string>>, projectRoot?: string): void;
 export interface ConfiguredEndpointEntry {
-    name: string;
+    id: 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 已存在时报错 */
+/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；id 已存在时报错 */
 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): {
+/** 按 id 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
+export declare function removeEndpointFromConfig(adapterKey: string, id: string, projectRoot?: string): {
     removed: boolean;
     filePath: string;
 };
@@ -58,9 +63,9 @@ export interface EndpointFieldSpec {
 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;
@@ -89,8 +94,9 @@ export interface EndpointCommandsSpec {
  * provider 层不允许 import @zhin.js/command，故 defineCommand 由调用方注入，
  * 这里只描述结构；适配器侧传入 defineCommand 后 TCommand 即 Readonly<CommandDefinition>。
  *
- * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象），
- * 否则注入的 defineCommand 会因 TS 逆变检查失败（TS2345）。
+ * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象 / rest 段的
+ * `ReadonlyArray<string | number | boolean>`），否则注入的 defineCommand 会因
+ * TS 逆变检查失败（TS2345）。
  */
 export interface EndpointCommandContext {
     readonly config: unknown;
@@ -101,11 +107,16 @@ export interface EndpointCommandContext {
      */
     readonly input?: unknown;
     readonly args: readonly string[];
-    readonly params: Readonly<Record<string, string | number | boolean | Readonly<Record<string, unknown>> | null>>;
+    readonly params: Readonly<Record<string, string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null>>;
     readonly use: EndpointCommandUse;
 }
 export interface EndpointCommandDefinition {
     readonly description?: string;
+    readonly params?: Readonly<Record<string, {
+        readonly type: 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
+        readonly default?: string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+        readonly description?: string;
+    }>>;
     execute(context: EndpointCommandContext): unknown;
 }
 export interface EndpointCommands<TCommand = EndpointCommandDefinition> {
@@ -120,8 +131,8 @@ export declare function formatEndpointList(spec: Pick<EndpointCommandsSpec, 'ada
     readonly footer?: string;
 }): string;
 /** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
-export declare function addEndpointFromKeyValues(spec: EndpointCommandsSpec, name: string, args: readonly string[], projectRoot?: string): string;
+export declare function addEndpointFromKeyValues(spec: EndpointCommandsSpec, id: string, args: readonly string[], projectRoot?: string): string;
 /** remove 的完整业务逻辑：从 yaml 移除；返回回复文本。 */
-export declare function removeEndpointByName(spec: Pick<EndpointCommandsSpec, 'adapterKey'>, name: string, projectRoot?: string): string;
+export declare function removeEndpointById(spec: Pick<EndpointCommandsSpec, 'adapterKey'>, id: string, projectRoot?: string): string;
 /** 生成 `<adapter> endpoint` 的 list / add / remove 三个命令定义（见文件头接入步骤）。 */
 export declare function createEndpointCommands<TCommand>(spec: EndpointCommandsSpec, defineCommand: (definition: EndpointCommandDefinition) => TCommand): EndpointCommands<TCommand>;

package/lib/endpoint-commands.js

@@ -16,11 +16,11 @@
  * 接入步骤（以 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 走依赖注入）。
- * 4. commands/endpoint/{list.ts, add/[name:string].ts, remove/[name:string].ts} 分别
+ * 4. commands/endpoint/{list.ts, add/[name].ts, remove/[name].ts} 分别
  *    `export default telegramEndpointCommands.list|add|remove`。
  *
  * 注意：adapterKey 即实例 key（zhin.config.yml 的 plugins.<key>）；多实例自定义 key 时
@@ -28,7 +28,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { createToken } from '@zhin.js/plugin-runtime';
+import { createToken, outboundHostToken, } from '@zhin.js/plugin-runtime';
 import { isMap, isSeq, parseDocument } from 'yaml';
 // ---------------------------------------------------------------------------
 // 权限：master 判定
@@ -55,8 +55,9 @@ export function isEndpointOperator(config, input) {
     }
     if (masters.size === 0)
         return true;
-    const sender = String(input?.sender ?? '').trim();
-    return !!sender && masters.has(sender);
+    const senderRaw = input?.sender;
+    const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? senderRaw.id.trim() : '';
+    return !!senderId && masters.has(senderId);
 }
 /** add/remove 的拒绝文案（list 只读，不校验）。 */
 export function endpointCommandForbidden(adapterDisplayName) {
@@ -72,6 +73,56 @@ export function extractEndpointCommandReply(input) {
     }
     return async () => undefined;
 }
+/**
+ * bindFlow 后续状态推送：优先走 OutboundHost（不受 inbound Message reply scope 限制）。
+ * 扫码绑定等长流程会在命令结果已送达、`$reply` 已冻结后继续 notify，必须用 durable 出站。
+ */
+export function createDurableEndpointCommandReply(input, use) {
+    const scoped = extractEndpointCommandReply(input);
+    const target = readOutboundSendTarget(input);
+    if (!target)
+        return scoped;
+    return async (text) => {
+        let outbound;
+        try {
+            outbound = use(outboundHostToken);
+        }
+        catch {
+            outbound = undefined;
+        }
+        if (outbound) {
+            await outbound.send({ ...target, content: text });
+            return;
+        }
+        await scoped(text);
+    };
+}
+function readOutboundSendTarget(input) {
+    const message = input;
+    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,
+        },
+    };
+}
 export function createEndpointRuntimeState() {
     return { endpoints: new Map() };
 }
@@ -94,8 +145,8 @@ function envSlug(text) {
         .toUpperCase();
 }
 /** 派生 endpoint 凭据的 env 键：`${ADAPTER}_${NAME}_${FIELD}`（如 `TELEGRAM_MY_BOT_TOKEN`） */
-export function buildEndpointEnvKey(adapterKey, endpointName, fieldKey) {
-    return `${envSlug(adapterKey)}_${envSlug(endpointName)}_${envSlug(fieldKey)}`;
+export function buildEndpointEnvKey(adapterKey, endpointId, fieldKey) {
+    return `${envSlug(adapterKey)}_${envSlug(endpointId)}_${envSlug(fieldKey)}`;
 }
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -162,13 +213,13 @@ export function listConfiguredEndpoints(adapterKey, projectRoot) {
     const endpoints = plugins[adapterKey]?.endpoints;
     if (!Array.isArray(endpoints))
         return [];
-    return endpoints.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.name === 'string');
+    return endpoints.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.id === 'string');
 }
-function entryName(item) {
+function entryId(item) {
     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;
 }
 /**
  * 确保 plugins.<adapterKey>.endpoints 存在并返回其 YAMLSeq（节点级操作，保留既有条目与注释）。
@@ -202,22 +253,22 @@ function ensureEndpointsSeq(doc, adapterKey) {
     }
     return doc.getIn(['plugins', adapterKey, 'endpoints']);
 }
-/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；name 已存在时报错 */
+/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；id 已存在时报错 */
 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} 再重新添加`);
+    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 */
-export function removeEndpointFromConfig(adapterKey, name, projectRoot) {
+/** 按 id 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
+export function removeEndpointFromConfig(adapterKey, id, projectRoot) {
     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 };
     }
@@ -225,9 +276,9 @@ export function removeEndpointFromConfig(adapterKey, name, projectRoot) {
     writeConfigDocument(document);
     return { removed: true, filePath: document.filePath };
 }
-function endpointNameParam(params) {
-    const name = params.name;
-    return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+function endpointIdParam(params) {
+    const id = params.id;
+    return typeof id === 'string' && id.trim() ? id.trim() : undefined;
 }
 /** list 文案：运行中 + 配置中两段，footer 可选。 */
 export function formatEndpointList(spec, source) {
@@ -239,7 +290,7 @@ export function formatEndpointList(spec, source) {
     }
     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）`);
@@ -249,7 +300,7 @@ export function formatEndpointList(spec, source) {
     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)
@@ -268,10 +319,10 @@ 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 <id> <key=value...>${fieldText}`;
 }
 /** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
-export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
+export function addEndpointFromKeyValues(spec, id, args, projectRoot) {
     const fields = spec.fields ?? [];
     const known = new Map(fields.map((field) => [field.key, field]));
     const values = new Map();
@@ -293,14 +344,14 @@ export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
     if (missing.length > 0) {
         return `缺少必填字段：${missing.map((field) => field.key).join('、')}。${addUsage(spec)}`;
     }
-    const entry = { name };
+    const entry = { id };
     const envValues = {};
     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}}`;
         }
@@ -309,11 +360,10 @@ export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
         }
     }
     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` +
+        return (`✅ endpoint「${id}」已追加到 ${filePath} 的 plugins.${spec.adapterKey}.endpoints` +
             `${Object.keys(envValues).length > 0 ? '（凭据已写入 .env）' : ''}。\n` +
             '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
     }
@@ -322,10 +372,10 @@ export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
     }
 }
 /** remove 的完整业务逻辑：从 yaml 移除；返回回复文本。 */
-export function removeEndpointByName(spec, name, projectRoot) {
-    const trimmed = name.trim();
+export function removeEndpointById(spec, id, projectRoot) {
+    const trimmed = id.trim();
     if (!trimmed)
-        return `用法：${spec.adapterKey}.endpoint remove <name>`;
+        return `用法：${spec.adapterKey}.endpoint remove <id>`;
     try {
         const { removed, filePath } = removeEndpointFromConfig(spec.adapterKey, trimmed, projectRoot);
         if (!removed) {
@@ -355,30 +405,32 @@ export function createEndpointCommands(spec, defineCommand) {
         add: defineCommand({
             description: spec.addDescription
                 ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
+            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)
+                if (!id)
                     return addUsage(spec);
-                return addEndpointFromKeyValues(spec, name, args);
+                return addEndpointFromKeyValues(spec, id, args);
             },
         }),
         remove: defineCommand({
             description: `从 zhin.config.yml 的 plugins.${spec.adapterKey}.endpoints 移除指定 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/lib/endpoint-control.d.ts

@@ -1,4 +1,5 @@
 import { type ConversationTarget, type MessageTarget } from '@zhin.js/im-contract';
+export type { LegacyEndpointControlSurface } from '@zhin.js/im-contract';
 /**
  * Transport-neutral control plane for a live endpoint.
  *
@@ -21,8 +22,11 @@ export interface EndpointWithControl {
 }
 /**
  * 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.
+ * Adapter only: it is a migration bridge for existing classic protocol
+ * endpoints (`LegacyEndpointControlSurface` lives in `@zhin.js/im-contract`),
+ * not an IM Core extension point. New adapters must expose `control` directly.
+ * 下线条件：classic Plugin 轨下线后，legacy 分支与 LegacyEndpointControlSurface
+ * 一并删除。
  */
 export declare function resolveEndpointControl(endpoint: unknown): EndpointControl | undefined;
 /** Checks only an Endpoint's explicit `control` port, never the legacy bridge. */

package/lib/endpoint-control.js

@@ -1,8 +1,11 @@
 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.
+ * Adapter only: it is a migration bridge for existing classic protocol
+ * endpoints (`LegacyEndpointControlSurface` lives in `@zhin.js/im-contract`),
+ * not an IM Core extension point. New adapters must expose `control` directly.
+ * 下线条件：classic Plugin 轨下线后，legacy 分支与 LegacyEndpointControlSurface
+ * 一并删除。
  */
 export function resolveEndpointControl(endpoint) {
     if (!endpoint || typeof endpoint !== 'object')

package/lib/endpoint-lifecycle.js

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.1.4",
+  "version": "1.1.7",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,15 +18,15 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@zhin.js/feature-kit": "1.0.5",
-    "@zhin.js/im-contract": "1.0.0",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/feature-kit": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.6"
+    "@zhin.js/command": "1.0.9"
   },
   "zhin": {
     "protocol": 1,

package/src/adapter-index.ts

@@ -89,13 +89,13 @@ export class AdapterIndex {
       for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
         for (const expansion of expandEndpointConfigs(slot, snapshot)) {
           const endpoint = await createEndpointSoft(slot, snapshot, expansion);
-          if (endpoint.unconfigured) unconfigured.push(expansion.name);
+          if (endpoint.unconfigured) unconfigured.push(expansion.endpointId);
           records.push({
             id: expansion.id,
             owner: slot.owner,
-            // 展开模式下 record name 即 endpoint 名（entry.name），
-            // 保证 Console 展示与 resolve/instance 按 entry name 命中唯一 record
-            name: expansion.name,
+            // 展开模式下 record name 即 endpoint id（entry.id），
+            // 保证 Console 展示与 resolve/instance 按 entry id 命中唯一 record
+            name: expansion.endpointId,
             source: slot.source,
             capabilities: slot.definition.capabilities,
             endpoint: endpoint.instance,
@@ -155,21 +155,21 @@ export class AdapterIndex {
    * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
    * Matches local name, capability id, or owner path segments.
    */
-  resolve(adapter: string, endpointId: string): CapabilityId | undefined {
+  resolve(adapter: string, endpointKey: string): CapabilityId | undefined {
     const matches = this.#order.filter((record) =>
-      matchesEndpoint(record, adapter, endpointId));
+      matchesEndpoint(record, adapter, endpointKey));
     if (matches.length === 1) return matches[0]?.id;
     if (matches.length === 0) return undefined;
-    // Prefer exact localName === endpointId when ambiguous.
-    const exact = matches.find((record) => record.name === endpointId);
+    // Prefer exact localName === endpointKey when ambiguous.
+    const exact = matches.find((record) => record.name === endpointKey);
     return exact?.id ?? matches[0]?.id;
   }
 
   /**
    * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
    */
-  instance(adapter: string, endpointId: string): EndpointInstance | undefined {
-    const id = this.resolve(adapter, endpointId);
+  instance(adapter: string, endpointKey: string): EndpointInstance | undefined {
+    const id = this.resolve(adapter, endpointKey);
     if (!id) return undefined;
     return this.#records.get(id)?.endpoint;
   }
@@ -341,7 +341,7 @@ export function isAdapterIndex(value: unknown): value is AdapterIndex {
 function matchesEndpoint(
   record: AdapterRecord,
   adapter: string,
-  endpointId: string,
+  endpointKey: string,
 ): boolean {
   // 消息上的 $adapter 是 CapabilityId 的 localName 段（多 endpoint 展开后形如
   // `icqq~8596238`）。CapabilityId 段分隔符是 \0（owner\0feature\0localName），
@@ -357,10 +357,10 @@ function matchesEndpoint(
   // activity-feedback resolve with that id; slot.localName alone is not enough
   // when multiple plugin instances share localName "icqq".
   const liveName = endpointLiveName(record.endpoint);
-  const endpointOk = record.name === endpointId
-    || record.id === endpointId
-    || record.id.endsWith(`/${endpointId}`)
-    || (liveName !== undefined && liveName === endpointId);
+  const endpointOk = record.name === endpointKey
+    || record.id === endpointKey
+    || record.id.endsWith(`/${endpointKey}`)
+    || (liveName !== undefined && liveName === endpointKey);
   return adapterOk && endpointOk;
 }
 
@@ -397,12 +397,12 @@ function isUnconfiguredError(error: unknown): boolean {
 /** 单个实例配置展开的 endpoint 描述（多账号适配器经 `endpoints` 数组声明）。 */
 interface EndpointExpansion {
   readonly id: CapabilityId;
-  readonly name: string;
+  readonly endpointId: string;
   readonly config?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{id, ...覆盖}]` 时
  * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
  * 否则按实例 config 创建单个 endpoint（历史行为）。
  */
@@ -415,55 +415,55 @@ function expandEndpointConfigs(
     | undefined;
   const raw = config?.endpoints;
   const entries = Array.isArray(raw)
-    ? raw.filter((entry): entry is Record<string, unknown> & { name: string } =>
+    ? raw.filter((entry): entry is Record<string, unknown> & { id: string } =>
       !!entry && typeof entry === 'object'
-      && typeof (entry as { name?: unknown }).name === 'string'
-      && (entry as { name: string }).name.length > 0)
+      && typeof (entry as { id?: unknown }).id === 'string'
+      && (entry as { id: string }).id.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',
+        reason: 'every endpoints entry is missing a non-empty string id',
       }));
     }
-    return Object.freeze([{ id: slot.id, name: slot.localName }]);
+    return Object.freeze([{ id: slot.id, endpointId: slot.localName }]);
   }
   // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析
   const valid = entries.filter((entry) => {
-    if (/[~\0]/u.test(entry.name)) {
+    if (/[~\0]/u.test(entry.id)) {
       logger.warn(formatCompact({
-        op: 'adapter_endpoint_name_invalid',
+        op: 'adapter_endpoint_id_invalid',
         id: slot.id,
-        name: entry.name,
+        endpointId: entry.id,
       }));
       return false;
     }
     return true;
   });
-  // 重名会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
+  // 重 id 会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
   const seen = new Set<string>();
   const deduped = valid.filter((entry) => {
-    if (seen.has(entry.name)) {
+    if (seen.has(entry.id)) {
       logger.warn(formatCompact({
-        op: 'adapter_endpoint_name_duplicate',
+        op: 'adapter_endpoint_id_duplicate',
         id: slot.id,
-        name: entry.name,
+        endpointId: entry.id,
       }));
       return false;
     }
-    seen.add(entry.name);
+    seen.add(entry.id);
     return true;
   });
   if (deduped.length === 0) {
-    return Object.freeze([{ id: slot.id, name: slot.localName }]);
+    return Object.freeze([{ id: slot.id, endpointId: 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 }),
+    id: `${slot.id}~${entry.id}` as CapabilityId,
+    endpointId: entry.id,
+    config: Object.freeze({ ...base, ...entry, id: entry.id }),
   })));
 }
 
@@ -492,7 +492,7 @@ async function createEndpointSoft(
     log(formatCompact({
       op: 'adapter_create_soft_fail',
       id: expansion?.id ?? slot.id,
-      name: expansion?.name ?? slot.localName,
+      name: expansion?.endpointId ?? slot.localName,
       error: message,
     }));
     return {

package/src/definition.ts

@@ -22,15 +22,9 @@ 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;
+  /** 结构化会话寻址；端点在平台边界自行派生原生 target。 */
+  readonly conversation: ConversationRef;
   readonly payload: unknown;
-  readonly parent?: { readonly type?: string; readonly id?: string; readonly name?: string };
 }
 
 export interface EndpointInstance<TResult = unknown> {

package/src/endpoint-commands.ts

@@ -16,11 +16,11 @@
  * 接入步骤（以 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 走依赖注入）。
- * 4. commands/endpoint/{list.ts, add/[name:string].ts, remove/[name:string].ts} 分别
+ * 4. commands/endpoint/{list.ts, add/[name].ts, remove/[name].ts} 分别
  *    `export default telegramEndpointCommands.list|add|remove`。
  *
  * 注意：adapterKey 即实例 key（zhin.config.yml 的 plugins.<key>）；多实例自定义 key 时
@@ -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;
@@ -355,8 +427,9 @@ export interface EndpointCommandsSpec {
  * provider 层不允许 import @zhin.js/command，故 defineCommand 由调用方注入，
  * 这里只描述结构；适配器侧传入 defineCommand 后 TCommand 即 Readonly<CommandDefinition>。
  *
- * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象），
- * 否则注入的 defineCommand 会因 TS 逆变检查失败（TS2345）。
+ * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象 / rest 段的
+ * `ReadonlyArray<string | number | boolean>`），否则注入的 defineCommand 会因
+ * TS 逆变检查失败（TS2345）。
  */
 export interface EndpointCommandContext {
   readonly config: unknown;
@@ -369,13 +442,33 @@ export interface EndpointCommandContext {
   readonly args: readonly string[];
   readonly params: Readonly<Record<
     string,
-    string | number | boolean | Readonly<Record<string, unknown>> | null
+    | string
+    | number
+    | boolean
+    | ReadonlyArray<string | number | boolean>
+    | Readonly<Record<string, unknown>>
+    | null
   >>;
   readonly use: EndpointCommandUse;
 }
 
 export interface EndpointCommandDefinition {
   readonly description?: string;
+  // 与 @zhin.js/command 的 CommandParamSchema 结构对齐（provider 层不能 import
+  // command，字面量联合在此镜像声明；新增参数类型须两侧同步）。
+  readonly params?: Readonly<Record<string, {
+    readonly type:
+      | 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text'
+      | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
+    readonly default?:
+      | string
+      | number
+      | boolean
+      | ReadonlyArray<string | number | boolean>
+      | Readonly<Record<string, unknown>>
+      | null;
+    readonly description?: string;
+  }>>;
   execute(context: EndpointCommandContext): unknown;
 }
 
@@ -385,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 可选。 */
@@ -406,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）`);
@@ -415,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);
@@ -434,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 {
@@ -463,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 {
@@ -477,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 才会生效。'
     );
@@ -491,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) {
@@ -532,27 +624,29 @@ export function createEndpointCommands<TCommand>(
     add: defineCommand({
       description: spec.addDescription
         ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
+      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: { 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

@@ -2,9 +2,12 @@ import {
   formatLegacyConversationRef,
   formatLegacyMessageRef,
   type ConversationTarget,
+  type LegacyEndpointControlSurface,
   type MessageTarget,
 } from '@zhin.js/im-contract';
 
+export type { LegacyEndpointControlSurface } from '@zhin.js/im-contract';
+
 /**
  * Transport-neutral control plane for a live endpoint.
  *
@@ -28,31 +31,13 @@ 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.
+ * Adapter only: it is a migration bridge for existing classic protocol
+ * endpoints (`LegacyEndpointControlSurface` lives in `@zhin.js/im-contract`),
+ * not an IM Core extension point. New adapters must expose `control` directly.
+ * 下线条件：classic Plugin 轨下线后，legacy 分支与 LegacyEndpointControlSurface
+ * 一并删除。
  */
 export function resolveEndpointControl(endpoint: unknown): EndpointControl | undefined {
   if (!endpoint || typeof endpoint !== 'object') return undefined;

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 注册仍在适配器侧