@zhin.js/host-http 1.0.1 → 1.0.3

package/src/console-rpc-extended.ts

@@ -9,12 +9,18 @@
  * - cron：`ctx.scheduleHost`（Plugin Runtime ScheduleHost，仅 register/list，
  *   无持久化引擎，故 cron:add/remove/pause/resume 报"未接线"）。
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
- *   表不存在或查询失败 → 空数组 + inboxEnabled:false）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，
- *   实例上探测到对应方法才调用，否则报"该平台不支持"。
+ *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
+ *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
+ * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
+ *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
  */
 
-/** 新 Runtime 统一收件箱表名（与 packages/im/zhin/src/setup/register-inbox.ts 一致）。 */
+/** 新 Runtime 统一收件箱表名（SSOT：@zhin.js/plugin-runtime inbox.js）。 */
+import {
+  assertDemoConsoleRpcAllowed,
+  normalizeConsoleRpcType,
+} from '@zhin.js/console-protocol';
+
 const TABLE_MESSAGE = 'unified_inbox_message';
 const TABLE_REQUEST = 'unified_inbox_request';
 const TABLE_NOTICE = 'unified_inbox_notice';
@@ -25,36 +31,35 @@ export interface ConsoleRpcExtendedCtx {
   projectRoot: string;
   /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
   scheduleHost?: unknown;
-  /** 经 ImRuntime / AdapterEndpointIndex 解析 live endpoint 实例。 */
+  /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
+  resolveEndpointManagement?: (
+    adapter: string,
+    endpointId: string,
+  ) => EndpointManagementPort | null | undefined;
+  /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
   resolveEndpoint?: (adapter: string, endpointId: string) => unknown;
   /** Plugin Runtime DatabaseHost 的 models 视图。 */
   databaseHost?: { models: { get(name: string): unknown } };
+  /** Agent Host 持久化调度引擎（@zhin.js/agent getAssistantRuntime().engine），未 init 时返回 null。 */
+  resolveScheduleEngine?: () => ConsoleScheduleEngine | null | undefined;
 }
 
-export type ExtendedRpcResult = { data: unknown } | { error: string };
+export interface ConsoleScheduleEngine {
+  addJob(job: Record<string, unknown>): Promise<Record<string, unknown>>;
+  removeJob(id: string): Promise<boolean>;
+  pauseJob(id: string): Promise<boolean>;
+  resumeJob(id: string): Promise<boolean>;
+  listJobs(): Promise<Record<string, unknown>[]>;
+}
 
-/** demo scope 只读放行清单之外的写操作 type。 */
-const WRITE_TYPES = new Set([
-  'cron:add',
-  'cron:remove',
-  'cron:pause',
-  'cron:resume',
-  'endpoint:requestApprove',
-  'endpoint:requestReject',
-  'endpoint:requestConsumed',
-  'endpoint:noticeConsumed',
-  'endpoint:groupKick',
-  'endpoint:groupMute',
-  'endpoint:groupAdmin',
-  'endpoint:deleteFriend',
-]);
+export type ExtendedRpcResult = { data: unknown } | { error: string };
 
 const CRON_NOT_WIRED =
   '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
   '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
 
 const CONSUMED_NOT_WIRED =
-  '收件箱已读标记未接线：新 Runtime 尚未提供 request/notice 的 consumed 写路径';
+  '收件箱已读标记未接线：unified_inbox_request/notice 表未注册或 DatabaseHost 未启动';
 
 interface ScheduleJobRow {
   id: string;
@@ -62,13 +67,41 @@ interface ScheduleJobRow {
   description?: string;
 }
 
+interface InboxSelection {
+  where(query: Record<string, unknown>): InboxSelection;
+  /** 可选：DB 侧排序下推（wrapModel 链具备该能力，轻量 fake 可缺失）。 */
+  orderBy?(field: string, direction?: 'ASC' | 'DESC'): InboxSelection;
+  /** 可选：DB 侧 limit 下推。 */
+  limit?(count: number): InboxSelection;
+  then<TResult1 = Record<string, unknown>[], TResult2 = never>(
+    onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2>;
+}
+
 interface InboxModel {
-  select(): {
-    where(query: Record<string, unknown>): Promise<Record<string, unknown>[]> | Record<string, unknown>[];
+  select(): InboxSelection;
+  update?(patch: Record<string, unknown>): {
+    where(query: Record<string, unknown>): Promise<unknown> | unknown;
   };
 }
 
-type EndpointAny = Record<string, unknown>;
+interface EndpointManagementPort {
+  listFriends?(): Promise<readonly { user_id: number | string; nickname: string; remark: string }[]>;
+  listGroups?(): Promise<readonly { group_id: number | string; name: string }[]>;
+  listChannels?(): Promise<readonly {
+    id: string;
+    name?: string;
+    parent?: { type: string; id: string; name?: string };
+  }[]>;
+  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 async function dispatchExtendedConsoleRpc(
   type: string,
@@ -76,9 +109,11 @@ export async function dispatchExtendedConsoleRpc(
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult | undefined> {
   const d = data ?? {};
+  type = normalizeConsoleRpcType(type);
 
-  if (WRITE_TYPES.has(type) && !ctx.fullScope) {
-    return { error: `Demo scope: RPC "${type}" is forbidden` };
+  if (!ctx.fullScope) {
+    const denied = assertDemoConsoleRpcAllowed(type);
+    if (denied) return { error: denied };
   }
 
   switch (type) {
@@ -87,59 +122,61 @@ export async function dispatchExtendedConsoleRpc(
       return listSchedule(ctx);
 
     case 'cron:add':
+      return addCron(d, ctx);
     case 'cron:remove':
     case 'cron:pause':
     case 'cron:resume':
-      return { error: CRON_NOT_WIRED };
+      return mutateCron(type, d, ctx);
 
-    case 'endpoint:requests':
+    case 'request.list':
       return listPendingRequests(d, ctx);
-    case 'endpoint:inboxRequests':
+    case 'inbox.requests':
       return listInbox(d, ctx, TABLE_REQUEST, 'requests', mapRequestRow);
-    case 'endpoint:inboxNotices':
+    case 'inbox.notices':
       return listInbox(d, ctx, TABLE_NOTICE, 'notices', mapNoticeRow);
-    case 'endpoint:inboxMessages':
+    case 'inbox.messages':
       return listInboxMessages(d, ctx);
 
-    case 'endpoint:requestApprove':
-    case 'endpoint:requestReject':
+    case 'request.approve':
+    case 'request.reject':
       return actOnRequest(type, d, ctx);
 
-    case 'endpoint:requestConsumed':
-    case 'endpoint:noticeConsumed':
-      return { error: CONSUMED_NOT_WIRED };
+    case 'request.consumed':
+      return markInboxConsumed(d, ctx, TABLE_REQUEST);
+    case 'notice.consumed':
+      return markInboxConsumed(d, ctx, TABLE_NOTICE);
 
-    case 'endpoint:friends':
+    case 'endpoint.friends':
       return listFriends(d, ctx);
-    case 'endpoint:groups':
+    case 'endpoint.groups':
       return listGroups(d, ctx);
-    case 'endpoint:channels':
+    case 'endpoint.channels':
       return listChannels(d, ctx);
-    case 'endpoint:groupMembers':
+    case 'endpoint.group_members':
       return listGroupMembers(d, ctx);
 
-    case 'endpoint:groupKick':
+    case 'endpoint.group_kick':
       return groupWriteOp(d, ctx, {
-        methods: ['removeMember', 'kickMember', 'setGroupKick'],
+        method: 'kickGroupMember',
         buildArgs: (gid, uid) => [gid, uid],
         requireUser: true,
         unsupported: '踢出群成员',
       });
-    case 'endpoint:groupMute':
+    case 'endpoint.group_mute':
       return groupWriteOp(d, ctx, {
-        methods: ['muteMember', 'setGroupBan', 'banMember'],
+        method: 'muteGroupMember',
         buildArgs: (gid, uid, extra) => [gid, uid, extra.duration ?? 600],
         requireUser: true,
         unsupported: '禁言群成员',
       });
-    case 'endpoint:groupAdmin':
+    case 'endpoint.group_admin':
       return groupWriteOp(d, ctx, {
-        methods: ['setModerator', 'setGroupAdmin', 'setAdmin'],
+        method: 'setGroupAdmin',
         buildArgs: (gid, uid, extra) => [gid, uid, extra.enable !== false],
         requireUser: true,
         unsupported: '设置群管理员',
       });
-    case 'endpoint:deleteFriend':
+    case 'endpoint.delete_friend':
       return deleteFriend(d, ctx);
 
     default:
@@ -149,7 +186,7 @@ export async function dispatchExtendedConsoleRpc(
 
 // ---------------------------------------------------------------- cron
 
-function listSchedule(ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
+function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcResult> | ExtendedRpcResult {
   const host = ctx.scheduleHost as { list?: () => unknown } | undefined;
   if (!host || typeof host.list !== 'function') {
     return { error: '调度服务未配置（scheduleHost 未挂载）' };
@@ -165,9 +202,94 @@ function listSchedule(ctx: ConsoleRpcExtendedCtx): ExtendedRpcResult {
         id: job.id,
         cron: job.cron,
         ...(typeof job.description === 'string' ? { description: job.description } : {}),
+        // console cron 页渲染字段（由 schedule host 提供时透传）
+        expression: (job as { expression?: string }).expression ?? job.cron,
+        running: (job as { running?: boolean }).running ?? true,
+        ...((job as { plugin?: string }).plugin ? { plugin: (job as { plugin?: string }).plugin } : {}),
+        ...((job as { nextExecution?: number }).nextExecution
+          ? { nextExecution: (job as { nextExecution?: number }).nextExecution } : {}),
       }));
-    // persistent 引擎未接入新 Runtime，返回空数组保持 legacy 形状。
-    return { data: { memory, persistent: [] } };
+    return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent } }));
+  } catch (error) {
+    return { error: errorMessage(error) };
+  }
+}
+
+type ConsoleScheduleListCtx = ConsoleRpcExtendedCtx;
+
+/** 持久化任务（Agent Host ScheduleJobEngine）→ 前端 PersistentCron 形状。 */
+async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<string, unknown>[]> {
+  const engine = ctx.resolveScheduleEngine?.();
+  if (!engine) return [];
+  try {
+    const jobs = await engine.listJobs();
+    return jobs.map((job) => ({
+      id: job.id,
+      label: job.label ?? job.id,
+      cronExpression: (job.schedule as { cron?: string } | undefined)?.cron ?? '',
+      prompt: (job.action as { prompt?: string } | undefined)?.prompt ?? '',
+      enabled: job.enabled !== false,
+      source: job.source ?? 'manual',
+      createdAt: (job as { createdAt?: number }).createdAt,
+      nextExecution: (job.state as { nextRunAtMs?: number } | undefined)?.nextRunAtMs,
+      ...((job.notify as { target?: unknown } | undefined)?.target
+        ? { context: { target: (job.notify as { target?: unknown }).target } } : {}),
+      lastExecutedAt: (job.state as { lastExecutedAt?: number } | undefined)?.lastExecutedAt,
+      lastStatus: (job.state as { lastStatus?: string } | undefined)?.lastStatus,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+async function addCron(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const engine = ctx.resolveScheduleEngine?.();
+  if (!engine) return { error: CRON_NOT_WIRED };
+  const cronExpression = String(d.cronExpression ?? '').trim();
+  const prompt = String(d.prompt ?? '').trim();
+  if (!cronExpression) return { error: 'cronExpression is required' };
+  if (!prompt) return { error: 'prompt is required' };
+  const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
+  const context = (d.context ?? {}) as Record<string, unknown>;
+  const target = context.target ?? context.channel;
+  const job = {
+    id: `console-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
+    ...(label ? { label } : {}),
+    enabled: true,
+    schedule: { kind: 'solar', cron: cronExpression },
+    action: { kind: 'agent', prompt },
+    notify: target
+      ? { channel: 'im', target }
+      : { channel: 'silent' },
+    source: 'manual',
+  };
+  try {
+    const created = await engine.addJob(job);
+    return { data: { job: created, success: true } };
+  } catch (error) {
+    return { error: errorMessage(error) };
+  }
+}
+
+async function mutateCron(
+  type: 'cron:remove' | 'cron:pause' | 'cron:resume',
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const engine = ctx.resolveScheduleEngine?.();
+  if (!engine) return { error: CRON_NOT_WIRED };
+  const id = String(d.id ?? '').trim();
+  if (!id) return { error: 'id is required' };
+  try {
+    const ok = type === 'cron:remove'
+      ? await engine.removeJob(id)
+      : type === 'cron:pause'
+        ? await engine.pauseJob(id)
+        : await engine.resumeJob(id);
+    return ok ? { data: { success: true } } : { error: `任务不存在: ${id}` };
   } catch (error) {
     return { error: errorMessage(error) };
   }
@@ -185,11 +307,24 @@ async function readInboxRows(
   ctx: ConsoleRpcExtendedCtx,
   table: string,
   where: Record<string, unknown>,
+  options?: {
+    /** DB 侧排序下推（模型不支持时由调用方内存排序兜底）。 */
+    orderBy?: { field: string; direction?: 'ASC' | 'DESC' };
+    /** DB 侧 limit 下推（模型不支持时由调用方内存分页兜底）。 */
+    limit?: number;
+  },
 ): Promise<{ rows: Record<string, unknown>[]; enabled: boolean }> {
   const model = getInboxModel(ctx, table);
   if (!model) return { rows: [], enabled: false };
   try {
-    const rows = await model.select().where(where);
+    let selection: InboxSelection = model.select().where(where);
+    if (options?.orderBy && typeof selection.orderBy === 'function') {
+      selection = selection.orderBy(options.orderBy.field, options.orderBy.direction ?? 'DESC');
+    }
+    if (options?.limit != null && typeof selection.limit === 'function') {
+      selection = selection.limit(options.limit);
+    }
+    const rows = await selection;
     return { rows: Array.isArray(rows) ? rows : [], enabled: true };
   } catch {
     // 表未创建 / 方言未启动等场景降级为空，不向上抛。
@@ -212,6 +347,10 @@ async function listInbox(
   const { rows, enabled } = await readInboxRows(ctx, table, {
     adapter,
     endpoint_id: endpointId,
+  }, {
+    // sort/limit 下推到 DB 侧（内存 sort/slice 保留，作为无下推能力模型的兜底）
+    orderBy: { field: 'created_at', direction: 'DESC' },
+    limit: offset + limit,
   });
   const sorted = rows
     .slice()
@@ -221,7 +360,7 @@ async function listInbox(
   return { data: { [key]: sorted, inboxEnabled: enabled } };
 }
 
-/** endpoint:requests —— 未处理的好友/群请求（unified_inbox_request 中 resolved=0）。 */
+/** request.list —— 未处理的好友/群请求（unified_inbox_request 中 resolved=0）。 */
 async function listPendingRequests(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
@@ -232,6 +371,8 @@ async function listPendingRequests(
   const { rows, enabled } = await readInboxRows(ctx, TABLE_REQUEST, {
     adapter,
     endpoint_id: endpointId,
+  }, {
+    orderBy: { field: 'created_at', direction: 'ASC' },
   });
   const requests = rows
     .filter((row) => Number(row.resolved ?? 0) === 0)
@@ -266,7 +407,10 @@ async function listInboxMessages(
     where.channel_parent_type = parent.type;
     where.channel_parent_id = parent.id;
   }
-  const { rows, enabled } = await readInboxRows(ctx, TABLE_MESSAGE, where);
+  const { rows, enabled } = await readInboxRows(ctx, TABLE_MESSAGE, where, {
+    // before_ts/before_id 过滤保留在内存（涉及双字段比较），排序下推 DB 侧
+    orderBy: { field: 'created_at', direction: 'DESC' },
+  });
   const messages = rows
     .filter((row) => (beforeTs == null || Number(row.created_at ?? 0) < beforeTs)
       && (beforeId == null || Number(row.id ?? 0) < beforeId))
@@ -287,62 +431,113 @@ async function listInboxMessages(
 }
 
 function mapRequestRow(row: Record<string, unknown>): Record<string, unknown> {
+  const actorId = row.actor_id;
+  const actorName = row.actor_name ?? undefined;
+  const sceneId = row.scene_id;
+  const sceneType = row.scene_type ?? undefined;
   return {
     id: row.id,
     platform_request_id: row.platform_request_id,
+    // console endpoint-detail 期望的 camelCase/扁平别名（SSE 推送路径同款形状）
+    platformRequestId: row.platform_request_id,
     type: row.type,
-    scene_type: row.scene_type ?? undefined,
-    scene_id: row.scene_id,
+    scene_type: sceneType,
+    scene_id: sceneId,
+    channel_id: sceneId,
+    channel_type: sceneType,
+    channel: { id: sceneId, type: sceneType },
     sub_type: row.sub_type ?? undefined,
-    actor: { id: row.actor_id, name: row.actor_name ?? undefined },
+    actor: { id: actorId, name: actorName },
+    sender: { id: actorId, name: actorName },
+    sender_id: actorId,
+    sender_name: actorName,
     comment: row.comment ?? undefined,
     created_at: row.created_at,
+    timestamp: row.created_at,
     resolved: row.resolved,
     resolved_at: row.resolved_at ?? undefined,
   };
 }
 
 function mapNoticeRow(row: Record<string, unknown>): Record<string, unknown> {
+  const actorId = row.actor_id ?? undefined;
+  const actorName = row.actor_name ?? undefined;
+  const sceneId = row.scene_id;
+  const sceneType = row.scene_type ?? undefined;
   return {
     id: row.id,
     platform_notice_id: row.platform_notice_id,
     type: row.type,
-    scene_type: row.scene_type ?? undefined,
-    scene_id: row.scene_id,
+    scene_type: sceneType,
+    scene_id: sceneId,
+    channel_id: sceneId,
+    channel_type: sceneType,
     sub_type: row.sub_type ?? undefined,
-    actor_id: row.actor_id ?? undefined,
-    actor_name: row.actor_name ?? undefined,
+    actor_id: actorId,
+    actor_name: actorName,
+    // console endpoint-detail 期望的操作人字段别名
+    operator_id: actorId,
+    operator_name: actorName,
     target_id: row.target_id ?? undefined,
     target_name: row.target_name ?? undefined,
     payload: row.payload,
     created_at: row.created_at,
+    timestamp: row.created_at,
   };
 }
 
+// ---------------------------------------------------------------- consumed 标记
+
+/**
+ * request.consumed / notice.consumed —— 按行 id 置 consumed=1。
+ * 表未注册（或 model 无 update）时保持"未接线"报错。
+ */
+async function markInboxConsumed(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+  table: string,
+): Promise<ExtendedRpcResult> {
+  const ids = numArrayField(d, '$row_ids', 'row_ids', 'rowIds', '$ids', 'ids');
+  // console UI 单条已读发 data:{id}，归一为数组
+  if (ids.length === 0) {
+    const single = Number(d.id ?? d.$id);
+    if (Number.isFinite(single) && single > 0) ids.push(single);
+  }
+  if (ids.length === 0) return { error: '$row_ids required' };
+  const model = getInboxModel(ctx, table);
+  if (!model || typeof model.update !== 'function') return { error: CONSUMED_NOT_WIRED };
+  const now = Date.now();
+  try {
+    for (const id of ids) {
+      await model.update({ consumed: 1, consumed_at: now }).where({ id });
+    }
+    return { data: { success: true, updated: ids.length } };
+  } catch (error) {
+    return { error: errorMessage(error) };
+  }
+}
+
 // ---------------------------------------------------------------- 请求审批
 
 async function actOnRequest(
-  type: 'endpoint:requestApprove' | 'endpoint:requestReject',
+  type: 'request.approve' | 'request.reject',
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
   const adapter = strField(d, '$adapter', 'adapter');
   const endpointId = strField(d, '$endpoint', 'endpointId', 'endpoint');
-  const requestId = strField(d, '$id', 'id', 'platformRequestId', 'platform_request_id');
+  const requestId = strField(d, '$id', 'id', 'platformRequestId', 'platform_request_id', 'requestId');
   if (!adapter || !endpointId || !requestId) {
     return { error: '$adapter, $endpoint, $id required' };
   }
   const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
   if ('error' in resolved) return resolved;
-  const endpoint = resolved.endpoint;
-  const approve = type === 'endpoint:requestApprove';
-  const methodNames = approve
-    ? ['approveRequest', 'approve_request', '$approveRequest']
-    : ['rejectRequest', 'reject_request', '$rejectRequest'];
-  const method = pickMethod(endpoint, methodNames);
+  const management = resolved.management;
+  const approve = type === 'request.approve';
+  const method = approve ? management.approveRequest : management.rejectRequest;
   if (!method) {
     return {
-      error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${methodNames[0]}，` +
+      error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
         '且新 Runtime 尚未挂载 pending request 注册表',
     };
   }
@@ -350,7 +545,7 @@ async function actOnRequest(
     const extra = approve
       ? strField(d, '$remark', 'remark')
       : strField(d, '$reason', 'reason');
-    await method.call(endpoint, requestId, extra || undefined);
+    await method.call(management, requestId, extra || undefined);
     return { data: { success: true } };
   } catch (error) {
     return { error: errorMessage(error) };
@@ -365,25 +560,10 @@ async function listFriends(
 ): Promise<ExtendedRpcResult> {
   const resolved = requireEndpoint(d, ctx);
   if ('error' in resolved) return resolved;
-  const { endpoint, adapter } = resolved;
+  const { management, adapter } = resolved;
   try {
-    const map = (endpoint.friends ?? endpoint.fl) as Map<unknown, Record<string, unknown>> | undefined;
-    if (map && typeof map.values === 'function') {
-      const friends = Array.from(map.values()).map((f) => ({
-        user_id: Number(f.user_id),
-        nickname: String(f.nickname ?? ''),
-        remark: String(f.remark ?? ''),
-      }));
-      return { data: { friends, count: friends.length } };
-    }
-    const getFriendList = pickMethod(endpoint, ['getFriendList', 'getFriends', 'listFriends']);
-    if (getFriendList) {
-      const raw = await getFriendList.call(endpoint);
-      const friends = unwrapList(raw).map((row) => ({
-        user_id: Number(row.user_id ?? row.userId ?? row.id ?? 0),
-        nickname: String(row.nickname ?? row.name ?? row.user_id ?? ''),
-        remark: String(row.remark ?? ''),
-      }));
+    if (management.listFriends) {
+      const friends = [...await management.listFriends()];
       return { data: { friends, count: friends.length } };
     }
     return { error: `当前适配器（${adapter}）不支持好友列表` };
@@ -398,23 +578,10 @@ async function listGroups(
 ): Promise<ExtendedRpcResult> {
   const resolved = requireEndpoint(d, ctx);
   if ('error' in resolved) return resolved;
-  const { endpoint, adapter } = resolved;
+  const { management, adapter } = resolved;
   try {
-    const map = (endpoint.groups ?? endpoint.gl) as Map<unknown, Record<string, unknown>> | undefined;
-    if (map && typeof map.values === 'function') {
-      const groups = Array.from(map.values()).map((g) => ({
-        group_id: Number(g.group_id),
-        name: String(g.group_name ?? g.name ?? g.group_id ?? ''),
-      }));
-      return { data: { groups, count: groups.length } };
-    }
-    const getGroupList = pickMethod(endpoint, ['getGroupList', 'getGroups', 'listGroups']);
-    if (getGroupList) {
-      const raw = await getGroupList.call(endpoint);
-      const groups = unwrapList(raw).map((row) => ({
-        group_id: Number(row.group_id ?? row.groupId ?? row.id ?? 0),
-        name: String(row.name ?? row.group_name ?? row.group_id ?? ''),
-      }));
+    if (management.listGroups) {
+      const groups = [...await management.listGroups()];
       return { data: { groups, count: groups.length } };
     }
     return { error: `当前适配器（${adapter}）不支持群列表` };
@@ -429,43 +596,10 @@ async function listChannels(
 ): Promise<ExtendedRpcResult> {
   const resolved = requireEndpoint(d, ctx);
   if ('error' in resolved) return resolved;
-  const { endpoint, adapter } = resolved;
+  const { management, adapter } = resolved;
   try {
-    const channels: Array<{
-      id: string;
-      name?: string;
-      parent?: { type: string; id: string; name?: string };
-    }> = [];
-    const getGuildChannelList = pickMethod(endpoint, ['getGuildChannelList']);
-    if (getGuildChannelList) {
-      const list = await getGuildChannelList.call(endpoint) as Array<Record<string, unknown>>;
-      for (const item of Array.isArray(list) ? list : []) {
-        const parent = normalizeParent(item.parent);
-        channels.push({
-          id: String(item.id ?? ''),
-          ...(item.name != null ? { name: String(item.name) } : {}),
-          ...(parent ? { parent } : {}),
-        });
-      }
-      return { data: { channels, count: channels.length } };
-    }
-    const getGuilds = pickMethod(endpoint, ['getGuilds', 'listGuilds']);
-    const getChannels = pickMethod(endpoint, ['getChannels', 'listChannels']);
-    if (getGuilds && getChannels) {
-      const guilds = unwrapList(await getGuilds.call(endpoint));
-      for (const g of guilds) {
-        const gid = String(g.id ?? g.guild_id ?? '');
-        if (!gid) continue;
-        const guildName = String(g.name ?? g.guild_name ?? gid);
-        const chs = unwrapList(await getChannels.call(endpoint, gid));
-        for (const c of chs) {
-          channels.push({
-            id: String(c.id ?? c.channel_id ?? ''),
-            name: String(c.name ?? c.channel_name ?? c.id ?? ''),
-            parent: { type: 'guild', id: gid, name: guildName },
-          });
-        }
-      }
+    if (management.listChannels) {
+      const channels = [...await management.listChannels()];
       return { data: { channels, count: channels.length } };
     }
     return { error: `当前适配器（${adapter}）不支持频道列表` };
@@ -486,22 +620,14 @@ async function listGroupMembers(
   }
   const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
   if ('error' in resolved) return resolved;
-  const { endpoint } = resolved;
+  const { management } = resolved;
   try {
-    const method = pickMethod(endpoint, ['getGroupMemberList', 'listMembers', 'getMemberList']);
+    const method = management.listGroupMembers;
     if (!method) {
       return { error: `当前适配器（${adapter}）不支持群成员列表` };
     }
-    const raw = await method.call(endpoint, groupId);
-    if (Array.isArray(raw)) {
-      return { data: { members: raw, count: raw.length } };
-    }
-    // Map（icqq 风格 gml）→ values 数组
-    if (raw && typeof (raw as Map<unknown, unknown>).values === 'function') {
-      const members = Array.from((raw as Map<unknown, unknown>).values());
-      return { data: { members, count: members.length } };
-    }
-    return { data: raw ?? { members: [], count: 0 } };
+    const members = [...await method(groupId)];
+    return { data: { members, count: members.length } };
   } catch (error) {
     return { error: errorMessage(error) };
   }
@@ -510,7 +636,7 @@ async function listGroupMembers(
 // ---------------------------------------------------------------- 群管/好友写操作
 
 interface GroupWriteSpec {
-  methods: string[];
+  method: 'kickGroupMember' | 'muteGroupMember' | 'setGroupAdmin';
   buildArgs(groupId: string, userId: string, extra: { duration?: number; enable?: boolean }): unknown[];
   requireUser: boolean;
   /** 中文操作名，用于"该平台不支持 xxx"。 */
@@ -534,8 +660,8 @@ async function groupWriteOp(
   }
   const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
   if ('error' in resolved) return resolved;
-  const { endpoint } = resolved;
-  const method = pickMethod(endpoint, spec.methods);
+  const { management } = resolved;
+  const method = management[spec.method];
   if (!method) {
     return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
   }
@@ -548,7 +674,7 @@ async function groupWriteOp(
         : undefined,
       enable: typeof enableRaw === 'boolean' ? enableRaw : undefined,
     });
-    await method.call(endpoint, ...args);
+    await (method as (...args: unknown[]) => Promise<void>).call(management, ...args);
     return { data: { success: true } };
   } catch (error) {
     return { error: errorMessage(error) };
@@ -567,14 +693,13 @@ async function deleteFriend(
   }
   const resolved = resolveLiveEndpoint(ctx, adapter, endpointId);
   if ('error' in resolved) return resolved;
-  const { endpoint } = resolved;
-  const method = pickMethod(endpoint, ['deleteFriend', 'delete_friend']);
+  const { management } = resolved;
+  const method = management.deleteFriend;
   if (!method) {
     return { error: '当前适配器暂不支持删除好友' };
   }
   try {
-    const numeric = Number(userId);
-    await method.call(endpoint, Number.isFinite(numeric) && userId.trim() !== '' ? numeric : userId);
+    await method(userId);
     return { data: { success: true } };
   } catch (error) {
     return { error: errorMessage(error) };
@@ -609,24 +734,34 @@ function optionalNum(d: Record<string, unknown>, ...keys: string[]): number | un
   return undefined;
 }
 
-function pickMethod(
-  endpoint: EndpointAny,
-  names: readonly string[],
-): ((...args: unknown[]) => unknown) | undefined {
-  for (const name of names) {
-    const fn = endpoint[name];
-    if (typeof fn === 'function') return fn as (...args: unknown[]) => unknown;
+/** 数字数组字段（$row_ids 等）：取首个数组值，收敛为有限数字。 */
+function numArrayField(d: Record<string, unknown>, ...keys: string[]): number[] {
+  for (const key of keys) {
+    const value = d[key];
+    if (!Array.isArray(value)) continue;
+    return value
+      .map((item) => Number(item))
+      .filter((item) => Number.isFinite(item));
   }
-  return undefined;
+  return [];
 }
 
-type ResolveOk = { endpoint: EndpointAny; adapter: string; endpointId: string };
+type ResolveOk = {
+  management: EndpointManagementPort;
+  adapter: string;
+  endpointId: string;
+};
 
 function resolveLiveEndpoint(
   ctx: ConsoleRpcExtendedCtx,
   adapter: string,
   endpointId: string,
 ): ResolveOk | { error: string } {
+  if (ctx.resolveEndpointManagement) {
+    const management = ctx.resolveEndpointManagement(adapter, endpointId);
+    if (!management) return { error: 'endpoint not found' };
+    return { management, adapter, endpointId };
+  }
   if (!ctx.resolveEndpoint) {
     return { error: 'Endpoint registry is not configured' };
   }
@@ -634,7 +769,14 @@ function resolveLiveEndpoint(
   if (!endpoint || typeof endpoint !== 'object') {
     return { error: 'endpoint not found' };
   }
-  return { endpoint: endpoint as EndpointAny, adapter, endpointId };
+  const management = (endpoint as { management?: unknown }).management;
+  return {
+    management: management && typeof management === 'object'
+      ? management as EndpointManagementPort
+      : {},
+    adapter,
+    endpointId,
+  };
 }
 
 function requireEndpoint(
@@ -647,18 +789,6 @@ function requireEndpoint(
   return resolveLiveEndpoint(ctx, adapter, endpointId);
 }
 
-/** 兼容数组 / `{ data: [...] }` / `{ list: [...] }` 的列表返回。 */
-function unwrapList(raw: unknown): Record<string, unknown>[] {
-  const arr = Array.isArray(raw)
-    ? raw
-    : raw && typeof raw === 'object'
-      ? ((raw as Record<string, unknown>).data ?? (raw as Record<string, unknown>).list)
-      : undefined;
-  return (Array.isArray(arr) ? arr : []).filter(
-    (item): item is Record<string, unknown> => !!item && typeof item === 'object',
-  );
-}
-
 function normalizeParent(raw: unknown): { type: 'group' | 'guild'; id: string; name?: string } | undefined {
   if (!raw || typeof raw !== 'object') return undefined;
   const parent = raw as { type?: unknown; id?: unknown; name?: unknown };