@zhin.js/adapter 1.0.1 → 1.1.0

package/README.md

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

package/lib/adapter-index.d.ts

@@ -1,5 +1,6 @@
 import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { AdapterCapability, AdapterDefinition, EndpointInstance, EndpointSendRequest } from './definition.js';
+import { type EndpointManagementCapability } from './endpoint-management.js';
 export interface AdapterDescriptor {
     readonly id: CapabilityId;
     readonly owner: PluginId;
@@ -12,6 +13,7 @@ export interface AdapterEndpointSummary extends AdapterDescriptor {
     readonly connected: boolean;
     readonly status: 'online' | 'offline';
     readonly phase: AdapterEndpointPhase;
+    readonly managementCapabilities: readonly EndpointManagementCapability[];
 }
 export type AdapterEndpointPhase = 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
 export declare class AdapterIndex {

package/lib/adapter-index.js

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

package/lib/definition.d.ts

@@ -1,5 +1,6 @@
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
+import type { EndpointManagement } from './endpoint-management.js';
 declare const adapterBrand: "zhin.adapter/1";
 export type AdapterCapability = 'inbound' | 'outbound';
 export interface EndpointSendRequest {
@@ -12,6 +13,8 @@ export interface EndpointSendRequest {
     };
 }
 export interface EndpointInstance<TResult = unknown> {
+    /** Optional platform-neutral Console/Host management surface. */
+    readonly management?: EndpointManagement;
     /** Allocates transport resources but must not admit inbound events yet. */
     start?(): void | Promise<void>;
     /** Opens admission after the candidate generation has committed. */

package/lib/endpoint-management.d.ts

@@ -0,0 +1,51 @@
+export interface EndpointFriend {
+    readonly user_id: number;
+    readonly nickname: string;
+    readonly remark: string;
+}
+export interface EndpointGroup {
+    readonly group_id: number;
+    readonly name: string;
+}
+export interface EndpointChannelParent {
+    readonly type: string;
+    readonly id: string;
+    readonly name?: string;
+}
+export interface EndpointChannel {
+    readonly id: string;
+    readonly name?: string;
+    readonly parent?: EndpointChannelParent;
+}
+/**
+ * Optional, platform-neutral management surface exposed by an Endpoint.
+ *
+ * Platform adapters own SDK aliases, identifier coercion, and response
+ * normalization. Hosts consume this interface without inspecting adapter
+ * names or transport-specific fields.
+ */
+export interface EndpointManagement {
+    listFriends?(): Promise<readonly EndpointFriend[]>;
+    listGroups?(): Promise<readonly EndpointGroup[]>;
+    listChannels?(): Promise<readonly EndpointChannel[]>;
+    listGroupMembers?(groupId: string): Promise<readonly unknown[]>;
+    approveRequest?(requestId: string, remark?: string): Promise<void>;
+    rejectRequest?(requestId: string, reason?: string): Promise<void>;
+    kickGroupMember?(groupId: string, userId: string): Promise<void>;
+    muteGroupMember?(groupId: string, userId: string, durationSeconds: number): Promise<void>;
+    setGroupAdmin?(groupId: string, userId: string, enabled: boolean): Promise<void>;
+    deleteFriend?(userId: string): Promise<void>;
+}
+export interface EndpointWithManagement {
+    readonly management?: EndpointManagement;
+}
+/**
+ * Stable, transport-neutral capability ids exposed to Host/Console clients.
+ * Values intentionally mirror EndpointManagement method names so adapters only
+ * need to implement the semantic port; no second capability declaration exists.
+ */
+export declare const endpointManagementCapabilityIds: readonly ["listFriends", "listGroups", "listChannels", "listGroupMembers", "approveRequest", "rejectRequest", "kickGroupMember", "muteGroupMember", "setGroupAdmin", "deleteFriend"];
+export type EndpointManagementCapability = (typeof endpointManagementCapabilityIds)[number];
+export declare function resolveEndpointManagement(endpoint: unknown): EndpointManagement | undefined;
+/** Derive advertised capabilities from the live semantic port implementation. */
+export declare function listEndpointManagementCapabilities(endpoint: unknown): readonly EndpointManagementCapability[];

package/lib/endpoint-management.js

@@ -0,0 +1,30 @@
+/**
+ * Stable, transport-neutral capability ids exposed to Host/Console clients.
+ * Values intentionally mirror EndpointManagement method names so adapters only
+ * need to implement the semantic port; no second capability declaration exists.
+ */
+export const endpointManagementCapabilityIds = [
+    'listFriends',
+    'listGroups',
+    'listChannels',
+    'listGroupMembers',
+    'approveRequest',
+    'rejectRequest',
+    'kickGroupMember',
+    'muteGroupMember',
+    'setGroupAdmin',
+    'deleteFriend',
+];
+export function resolveEndpointManagement(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return undefined;
+    const management = endpoint.management;
+    return management && typeof management === 'object' ? management : undefined;
+}
+/** Derive advertised capabilities from the live semantic port implementation. */
+export function listEndpointManagementCapabilities(endpoint) {
+    const management = resolveEndpointManagement(endpoint);
+    if (!management)
+        return Object.freeze([]);
+    return Object.freeze(endpointManagementCapabilityIds.filter((capability) => typeof management[capability] === 'function'));
+}

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 export * from './adapter-index.js';
 export * from './credentials.js';
 export * from './definition.js';
+export * from './endpoint-management.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,5 +1,6 @@
 export * from './adapter-index.js';
 export * from './credentials.js';
 export * from './definition.js';
+export * from './endpoint-management.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,9 +17,9 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "@zhin.js/logger": "1.0.75"
+    "@zhin.js/feature-kit": "1.0.2",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",

package/src/adapter-index.ts

@@ -13,6 +13,10 @@ import type {
   EndpointInstance,
   EndpointSendRequest,
 } from './definition.js';
+import {
+  listEndpointManagementCapabilities,
+  type EndpointManagementCapability,
+} from './endpoint-management.js';
 
 const logger = getLogger('Adapter');
 
@@ -29,6 +33,7 @@ export interface AdapterEndpointSummary extends AdapterDescriptor {
   readonly connected: boolean;
   readonly status: 'online' | 'offline';
   readonly phase: AdapterEndpointPhase;
+  readonly managementCapabilities: readonly EndpointManagementCapability[];
 }
 
 export type AdapterEndpointPhase =
@@ -79,23 +84,27 @@ export class AdapterIndex {
     const unconfigured: string[] = [];
     try {
       for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
-        const endpoint = await createEndpointSoft(slot, snapshot);
-        if (endpoint.unconfigured) unconfigured.push(slot.localName);
-        records.push({
-          id: slot.id,
-          owner: slot.owner,
-          name: slot.localName,
-          source: slot.source,
-          capabilities: slot.definition.capabilities,
-          endpoint: endpoint.instance,
-          unconfigured: endpoint.unconfigured,
-          started: false,
-          open: false,
-          failed: false,
-          startAttempted: false,
-          // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
-          stopped: endpoint.unconfigured,
-        });
+        for (const expansion of expandEndpointConfigs(slot, snapshot)) {
+          const endpoint = await createEndpointSoft(slot, snapshot, expansion);
+          if (endpoint.unconfigured) unconfigured.push(expansion.name);
+          records.push({
+            id: expansion.id,
+            owner: slot.owner,
+            // 展开模式下 record name 即 endpoint 名（entry.name），
+            // 保证 Console 展示与 resolve/instance 按 entry name 命中唯一 record
+            name: expansion.name,
+            source: slot.source,
+            capabilities: slot.definition.capabilities,
+            endpoint: endpoint.instance,
+            unconfigured: endpoint.unconfigured,
+            started: false,
+            open: false,
+            failed: false,
+            startAttempted: false,
+            // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
+            stopped: endpoint.unconfigured,
+          });
+        }
       }
       if (unconfigured.length > 0) {
         logger.info(formatCompact({
@@ -133,6 +142,7 @@ export class AdapterIndex {
       connected: record.open && !record.stopped,
       status: record.open && !record.stopped ? 'online' as const : 'offline' as const,
       phase: endpointPhase(record),
+      managementCapabilities: listEndpointManagementCapabilities(record.endpoint),
     })));
   }
 
@@ -320,8 +330,13 @@ function matchesEndpoint(
   adapter: string,
   endpointId: string,
 ): boolean {
+  // 消息上的 $adapter 是 CapabilityId 的 localName 段（多 endpoint 展开后形如
+  // `icqq~8596238`）。CapabilityId 段分隔符是 \0（owner\0feature\0localName），
+  // 不能用 `/` 去 endsWith，否则永远匹配不上（endpoint not found）。
+  const localName = record.id.split('\0').pop() ?? record.id;
   const adapterOk = record.name === adapter
     || record.id === adapter
+    || localName === adapter
     || record.id.endsWith(`/${adapter}`)
     || record.owner === adapter
     || record.owner.endsWith(`/${adapter}`);
@@ -366,16 +381,91 @@ function isUnconfiguredError(error: unknown): boolean {
   );
 }
 
+/** 单个实例配置展开的 endpoint 描述（多账号适配器经 `endpoints` 数组声明）。 */
+interface EndpointExpansion {
+  readonly id: CapabilityId;
+  readonly name: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
+ * 否则按实例 config 创建单个 endpoint（历史行为）。
+ */
+function expandEndpointConfigs(
+  slot: Readonly<CapabilitySlot<AdapterDefinition>>,
+  snapshot: RuntimeSnapshot,
+): readonly EndpointExpansion[] {
+  const config = snapshot.config.get(slot.owner) as
+    | { endpoints?: unknown }
+    | undefined;
+  const raw = config?.endpoints;
+  const entries = Array.isArray(raw)
+    ? raw.filter((entry): entry is Record<string, unknown> & { name: string } =>
+      !!entry && typeof entry === 'object'
+      && typeof (entry as { name?: unknown }).name === 'string'
+      && (entry as { name: string }).name.length > 0)
+    : [];
+  if (entries.length === 0) {
+    if (Array.isArray(raw) && raw.length > 0) {
+      logger.warn(formatCompact({
+        op: 'adapter_endpoints_entries_dropped',
+        id: slot.id,
+        reason: 'every endpoints entry is missing a non-empty string name',
+      }));
+    }
+    return Object.freeze([{ id: slot.id, name: slot.localName }]);
+  }
+  // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析
+  const valid = entries.filter((entry) => {
+    if (/[~\0]/u.test(entry.name)) {
+      logger.warn(formatCompact({
+        op: 'adapter_endpoint_name_invalid',
+        id: slot.id,
+        name: entry.name,
+      }));
+      return false;
+    }
+    return true;
+  });
+  // 重名会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
+  const seen = new Set<string>();
+  const deduped = valid.filter((entry) => {
+    if (seen.has(entry.name)) {
+      logger.warn(formatCompact({
+        op: 'adapter_endpoint_name_duplicate',
+        id: slot.id,
+        name: entry.name,
+      }));
+      return false;
+    }
+    seen.add(entry.name);
+    return true;
+  });
+  if (deduped.length === 0) {
+    return Object.freeze([{ id: slot.id, name: slot.localName }]);
+  }
+  const { endpoints: _drop, ...base } = (config ?? {}) as Record<string, unknown>;
+  return Object.freeze(deduped.map((entry) => Object.freeze({
+    id: `${slot.id}~${entry.name}` as CapabilityId,
+    name: entry.name,
+    config: Object.freeze({ ...base, ...entry, name: entry.name }),
+  })));
+}
+
 async function createEndpointSoft(
   slot: Readonly<CapabilitySlot<AdapterDefinition>>,
   snapshot: RuntimeSnapshot,
+  expansion?: EndpointExpansion,
 ): Promise<{ readonly instance: EndpointInstance; readonly unconfigured: boolean }> {
   let endpoint: unknown;
   try {
     endpoint = await slot.definition.create(
       Object.freeze({
         ...createCapabilityContext(snapshot, slot.owner),
-        id: slot.id,
+        ...(expansion?.config ? { config: expansion.config } : {}),
+        id: expansion?.id ?? slot.id,
         name: slot.localName,
       }),
     );
@@ -388,8 +478,8 @@ async function createEndpointSoft(
     const log = isUnconfiguredError(error) ? logger.debug.bind(logger) : logger.warn.bind(logger);
     log(formatCompact({
       op: 'adapter_create_soft_fail',
-      id: slot.id,
-      name: slot.localName,
+      id: expansion?.id ?? slot.id,
+      name: expansion?.name ?? slot.localName,
       error: message,
     }));
     return {
@@ -400,7 +490,7 @@ async function createEndpointSoft(
   // Programming errors (create() did not return an Endpoint) must surface:
   // they propagate to AdapterIndex.create's catch, which disposes the records
   // created so far instead of hiding the bug behind an unconfigured stub.
-  assertEndpoint(endpoint, slot.id);
+  assertEndpoint(endpoint, expansion?.id ?? slot.id);
   return { instance: endpoint, unconfigured: false };
 }
 

package/src/definition.ts

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

package/src/endpoint-management.ts

@@ -0,0 +1,84 @@
+export interface EndpointFriend {
+  readonly user_id: number;
+  readonly nickname: string;
+  readonly remark: string;
+}
+
+export interface EndpointGroup {
+  readonly group_id: number;
+  readonly name: string;
+}
+
+export interface EndpointChannelParent {
+  readonly type: string;
+  readonly id: string;
+  readonly name?: string;
+}
+
+export interface EndpointChannel {
+  readonly id: string;
+  readonly name?: string;
+  readonly parent?: EndpointChannelParent;
+}
+
+/**
+ * Optional, platform-neutral management surface exposed by an Endpoint.
+ *
+ * Platform adapters own SDK aliases, identifier coercion, and response
+ * normalization. Hosts consume this interface without inspecting adapter
+ * names or transport-specific fields.
+ */
+export interface EndpointManagement {
+  listFriends?(): Promise<readonly EndpointFriend[]>;
+  listGroups?(): Promise<readonly EndpointGroup[]>;
+  listChannels?(): Promise<readonly EndpointChannel[]>;
+  listGroupMembers?(groupId: string): Promise<readonly unknown[]>;
+  approveRequest?(requestId: string, remark?: string): Promise<void>;
+  rejectRequest?(requestId: string, reason?: string): Promise<void>;
+  kickGroupMember?(groupId: string, userId: string): Promise<void>;
+  muteGroupMember?(groupId: string, userId: string, durationSeconds: number): Promise<void>;
+  setGroupAdmin?(groupId: string, userId: string, enabled: boolean): Promise<void>;
+  deleteFriend?(userId: string): Promise<void>;
+}
+
+export interface EndpointWithManagement {
+  readonly management?: EndpointManagement;
+}
+
+/**
+ * Stable, transport-neutral capability ids exposed to Host/Console clients.
+ * Values intentionally mirror EndpointManagement method names so adapters only
+ * need to implement the semantic port; no second capability declaration exists.
+ */
+export const endpointManagementCapabilityIds = [
+  'listFriends',
+  'listGroups',
+  'listChannels',
+  'listGroupMembers',
+  'approveRequest',
+  'rejectRequest',
+  'kickGroupMember',
+  'muteGroupMember',
+  'setGroupAdmin',
+  'deleteFriend',
+] as const;
+
+export type EndpointManagementCapability =
+  (typeof endpointManagementCapabilityIds)[number];
+
+export function resolveEndpointManagement(endpoint: unknown): EndpointManagement | undefined {
+  if (!endpoint || typeof endpoint !== 'object') return undefined;
+  const management = (endpoint as EndpointWithManagement).management;
+  return management && typeof management === 'object' ? management : undefined;
+}
+
+/** Derive advertised capabilities from the live semantic port implementation. */
+export function listEndpointManagementCapabilities(
+  endpoint: unknown,
+): readonly EndpointManagementCapability[] {
+  const management = resolveEndpointManagement(endpoint);
+  if (!management) return Object.freeze([]);
+  return Object.freeze(endpointManagementCapabilityIds.filter(
+    (capability) => typeof management[capability] === 'function',
+  ));
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './adapter-index.js';
 export * from './credentials.js';
 export * from './definition.js';
+export * from './endpoint-management.js';
 export * from './provider.js';
 export { default } from './provider.js';