@zhin.js/host-http 1.1.0 → 1.1.1

package/src/console-plugin-rpc.ts

@@ -0,0 +1,142 @@
+import { PLUGIN_RPC } from '@zhin.js/console-protocol';
+import type {
+  RuntimeConsoleRpcContext,
+  RuntimeConsoleRpcMessage,
+  RuntimeConsoleRpcReply,
+} from './console-rpc.js';
+
+/** Dispatches the plugin-management slice; undefined means the type belongs elsewhere. */
+export async function dispatchPluginConsoleRpc(
+  type: string,
+  message: RuntimeConsoleRpcMessage,
+  ctx: RuntimeConsoleRpcContext,
+): Promise<RuntimeConsoleRpcReply | undefined> {
+  const requestId = message.requestId as number | string | undefined;
+  try {
+    switch (type) {
+      case PLUGIN_RPC.SET_ENABLED: {
+        const instanceKey = stringField(message, 'instanceKey');
+        const enabled = message.enabled;
+        if (!instanceKey || typeof enabled !== 'boolean') {
+          return { requestId, error: 'instanceKey and boolean enabled are required' };
+        }
+        if (!ctx.setPluginEnabled) {
+          return { requestId, error: 'Plugin lifecycle management is not configured' };
+        }
+        const lifecycle = await ctx.setPluginEnabled(instanceKey, enabled);
+        ctx.publishEvent?.('plugin:lifecycle-updated', { instanceKey, enabled });
+        if (ctx.requestRestart) {
+          setTimeout(() => void Promise.resolve(ctx.requestRestart?.()).catch(() => undefined), 500);
+        }
+        return {
+          requestId,
+          data: {
+            success: true,
+            instanceKey,
+            enabled,
+            disabled: lifecycle.disabled,
+            restartRequired: true,
+            message: `${instanceKey} 已${enabled ? '启用' : '停用'}，Host 正在重启`,
+          },
+        };
+      }
+      case PLUGIN_RPC.PLAN_INSTALL: {
+        const packageName = stringField(message, 'packageName');
+        if (!packageName) return { requestId, error: 'packageName is required' };
+        if (!ctx.pluginManagement) return { requestId, error: 'Plugin management is not configured' };
+        return { requestId, data: await ctx.pluginManagement.planInstall(packageName) };
+      }
+      case PLUGIN_RPC.INSTALL: {
+        const packageName = stringField(message, 'packageName');
+        if (!packageName) return { requestId, error: 'packageName is required' };
+        if (!ctx.pluginManagement?.install) {
+          return { requestId, error: 'Plugin installation is not configured' };
+        }
+        const result = await ctx.pluginManagement.install(
+          packageName,
+          optionalString(message.expectedRevision),
+        );
+        ctx.publishEvent?.('plugin:installed', { packageName, restartRequired: result.restartRequired });
+        return { requestId, data: { success: true, ...result } };
+      }
+      case PLUGIN_RPC.PLAN_UNINSTALL: {
+        const packageName = stringField(message, 'packageName');
+        if (!packageName) return { requestId, error: 'packageName is required' };
+        if (!ctx.pluginManagement?.planUninstall) {
+          return { requestId, error: 'Plugin uninstall planning is not configured' };
+        }
+        return { requestId, data: await ctx.pluginManagement.planUninstall(packageName) };
+      }
+      case PLUGIN_RPC.UNINSTALL: {
+        const packageName = stringField(message, 'packageName');
+        if (!packageName || stringField(message, 'confirmation') !== packageName) {
+          return { requestId, error: 'confirmation must exactly match packageName' };
+        }
+        if (!ctx.pluginManagement?.uninstall) {
+          return { requestId, error: 'Plugin uninstall is not configured' };
+        }
+        const result = await ctx.pluginManagement.uninstall(
+          packageName,
+          optionalString(message.expectedRevision),
+        );
+        ctx.publishEvent?.('plugin:uninstalled', { packageName, restartRequired: result.restartRequired });
+        return { requestId, data: { success: true, ...result } };
+      }
+      case PLUGIN_RPC.PLAN_UPDATE: {
+        const packageName = stringField(message, 'packageName');
+        const targetVersion = stringField(message, 'targetVersion');
+        if (!packageName || !targetVersion) {
+          return { requestId, error: 'packageName and targetVersion are required' };
+        }
+        if (!ctx.pluginManagement?.planUpdate) {
+          return { requestId, error: 'Plugin update planning is not configured' };
+        }
+        return { requestId, data: await ctx.pluginManagement.planUpdate(packageName, targetVersion) };
+      }
+      case PLUGIN_RPC.UPDATE: {
+        const packageName = stringField(message, 'packageName');
+        const targetVersion = stringField(message, 'targetVersion');
+        if (!packageName || !targetVersion) {
+          return { requestId, error: 'packageName and targetVersion are required' };
+        }
+        if (!ctx.pluginManagement?.update) return { requestId, error: 'Plugin update is not configured' };
+        const result = await ctx.pluginManagement.update(
+          packageName,
+          targetVersion,
+          optionalString(message.expectedRevision),
+        );
+        ctx.publishEvent?.('plugin:updated', {
+          packageName,
+          version: result.installedVersion,
+          restartRequired: result.restartRequired,
+        });
+        return { requestId, data: { success: true, ...result } };
+      }
+      case PLUGIN_RPC.VALIDATE_CONFIG: {
+        const pluginName = stringField(message, 'pluginName');
+        if (!pluginName) return { requestId, error: 'pluginName is required' };
+        if (!ctx.validatePluginConfig) return { requestId, error: 'Config validation is not configured' };
+        return { requestId, data: await ctx.validatePluginConfig(pluginName, message.data) };
+      }
+      case PLUGIN_RPC.DIAGNOSE: {
+        const pluginName = stringField(message, 'pluginName');
+        if (!pluginName) return { requestId, error: 'pluginName is required' };
+        if (!ctx.diagnosePlugin) return { requestId, error: 'Plugin diagnostics are not configured' };
+        return { requestId, data: await ctx.diagnosePlugin(pluginName) };
+      }
+      default:
+        return undefined;
+    }
+  } catch (error) {
+    return { requestId, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function stringField(message: RuntimeConsoleRpcMessage, key: string): string {
+  const value = message[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}

package/src/console-rest-pages.ts

@@ -1,11 +1,7 @@
 /**
  * Console REST pages — logs / marketplace / introspection / agent sessions。
  *
- * 响应形状对齐 legacy `packages/host/api/src/rest/`：
- * - logs-rest-api.ts（SystemLog 模型）
- * - marketplace-rest-api.ts（plugins.json + npmmirror）
- * - introspection-rest-api.ts（分页内省列表）
- * - agent-sessions-rest-api.ts（ADR 0010 D3 session tree）
+ * 统一提供日志、市场、Runtime snapshot 内省和 Agent session tree 页面。
  *
  * 数据源不可用时降级：读操作返回空数组 + `note` 说明，session tree 返回 503；
  * 写操作要求 `ctx.fullScope && authScope === 'full'`，否则 403。
@@ -15,6 +11,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { HttpHost } from './http-host.js';
 import { HttpBodyError, readJsonBody } from './json-body.js';
+import { MarketplaceRegistry } from './marketplace-registry.js';
 import type { AuthScope } from './token-registry.js';
 
 /** 与 basic/cli 接线方对齐的上下文约定。 */
@@ -48,7 +45,7 @@ export interface ConsoleRestCtx {
   ) => boolean | undefined | Promise<boolean | undefined>;
 }
 
-/** 内省数据门面 — 由 basic/cli 用 agent 包 collectIntrospection* 装配。 */
+/** 内省数据门面 — 由 composition root 从当前 Runtime snapshot 装配。 */
 export interface ConsoleAgentIntrospection {
   commands?(): readonly unknown[];
   middlewares?(): readonly unknown[];
@@ -135,7 +132,6 @@ const INTROSPECTION_PAGE_SIZES = {
 
 type IntrospectionKind = keyof typeof INTROSPECTION_PAGE_SIZES;
 
-let pluginsCache: { data: unknown[]; ts: number } | null = null;
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
 
 /**
@@ -342,19 +338,11 @@ function registerMarketplaceRoutes(
   pluginRegistryUrl: string,
   npmRegistryUrl: string,
 ): void {
-  const fetchPluginRegistry = async (): Promise<unknown[]> => {
-    if (pluginsCache && Date.now() - pluginsCache.ts < PLUGINS_CACHE_TTL) {
-      return pluginsCache.data;
-    }
-    const resp = await fetchFn(pluginRegistryUrl, {
-      signal: AbortSignal.timeout(30_000),
-    });
-    if (!resp.ok) throw new Error(`plugins.json fetch failed: ${resp.status}`);
-    const json = (await resp.json()) as { plugins?: unknown[] };
-    const list = json.plugins || [];
-    pluginsCache = { data: list, ts: Date.now() };
-    return list;
-  };
+  const registry = new MarketplaceRegistry({
+    fetchFn,
+    url: pluginRegistryUrl,
+    ttlMs: PLUGINS_CACHE_TTL,
+  });
 
   route('GET', '/pub/marketplace/search', async (_request, response, url) => {
     const q = url.searchParams.get('q') ?? url.searchParams.get('keyword') ?? '';
@@ -368,7 +356,7 @@ function registerMarketplaceRoutes(
     const searchKeyword = q.trim().toLowerCase();
 
     try {
-      const allPlugins = (await fetchPluginRegistry()) as Array<Record<string, unknown>>;
+      const allPlugins = (await registry.list()) as readonly Record<string, unknown>[];
       let plugins = allPlugins.map((p) => ({
         name: p.name,
         displayName: p.displayName || '',
@@ -429,11 +417,11 @@ function registerMarketplaceRoutes(
     try {
       let cachedDownloads = { weekly: 0, monthly: 0 };
       try {
-        const registry = (await fetchPluginRegistry()) as Array<{
+        const registryPlugins = (await registry.list()) as readonly {
           name?: string;
           downloads?: unknown;
-        }>;
-        const cached = registry.find((p) => p.name === pkgName);
+        }[];
+        const cached = registryPlugins.find((p) => p.name === pkgName);
         if (cached?.downloads && typeof cached.downloads === 'object') {
           cachedDownloads = cached.downloads as { weekly: number; monthly: number };
         }
@@ -562,7 +550,7 @@ async function listInstalledPluginPackages(
 }
 
 // ---------------------------------------------------------------------------
-// introspection（legacy introspection-rest-api.ts；分页形状对齐 IntrospectionJsonResponse）
+// Runtime snapshot introspection
 // ---------------------------------------------------------------------------
 
 function registerIntrospectionRoutes(
@@ -1030,7 +1018,7 @@ function parseSessionAction(
 }
 
 // ---------------------------------------------------------------------------
-// 内部分页 / 过滤（语义对齐 agent 包 introspection-pagination.ts）
+// 内部分页 / 过滤
 // ---------------------------------------------------------------------------
 
 function paginateItems<T>(

package/src/console-rpc-extended/contracts.ts

@@ -0,0 +1,155 @@
+export interface ConsoleRpcExtendedCtx {
+  /** full scope 才允许写操作；demo scope 只放行只读 RPC。 */
+  fullScope: boolean;
+  projectRoot: string;
+  /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
+  scheduleHost?: unknown;
+  /** 在固定 generation lease 内执行一次 Endpoint 管理操作。 */
+  withEndpointManagement?: <T>(
+    adapter: string,
+    endpointKey: string,
+    run: (management: EndpointManagementPort) => T | Promise<T>,
+  ) => Promise<T | null>;
+  /** Plugin Runtime DatabaseHost 的 models 视图。 */
+  databaseHost?: { models: { get(name: string): unknown } };
+  /** Narrow generation-bound persistent-job port; null when Assistant is disabled. */
+  resolveScheduleEngine?: () => ConsoleScheduleEngine | null | undefined;
+  /** LoginAssist list/submit/cancel（刷新后仍可消费扫码/滑块待办）。 */
+  loginAssist?: {
+    listPending(): readonly {
+      id: string;
+      adapter: string;
+      endpointKey: string;
+      type: string;
+      payload: Record<string, unknown>;
+      createdAt: number;
+      expiresAt?: number;
+    }[];
+    submit(id: string, value: string | Record<string, unknown>): boolean;
+    cancel(id: string, reason?: string): boolean;
+  };
+  /** Authenticated Root adapter; mutation DTOs deliberately contain no principal/decision fields. */
+  workroomProfileControl?: ConsoleWorkroomProfileControlPort;
+  /** Authenticated HTTP principal; never accepted from the RPC body. */
+  authenticatedPrincipal?: Readonly<{ principalId: string }>;
+  workroomKnowledgeControl?: ConsoleWorkroomKnowledgeControlPort;
+}
+
+export interface ConsoleWorkroomProfileControlPort {
+  getPlanningStatus(projectId: string,
+    authenticatedPrincipal?: Readonly<{ principalId: string }>): Promise<unknown>;
+  bootstrapPlanning(command: Readonly<{
+    operationId: string;
+    projectId: string;
+    expectedRegistryRevision: number;
+    includeTools?: readonly string[];
+    includeSkills?: readonly string[];
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+  publishPack(command: Readonly<{ operationId: string; pack: unknown }>,
+    authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+  publishProfile(command: Readonly<{
+    operationId: string;
+    projectId: string;
+    expectedRegistryRevision: number;
+    overlay: unknown;
+    activate: boolean;
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+  publishRollback(command: Readonly<{
+    operationId: string;
+    projectId: string;
+    expectedRegistryRevision: number;
+    restoredFromRevisionId: string;
+    overlay: unknown;
+    activate: boolean;
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+  publishPlanningPolicy(command: Readonly<{
+    operationId: string;
+    projectId: string;
+    profileRevisionId: string;
+    revision: number;
+    expectedPreviousDigest?: string;
+    policy: unknown;
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+}
+
+export interface ConsoleWorkroomKnowledgeControlPort {
+  read(projectId: string): Promise<unknown>;
+  publish(command: Readonly<{
+    operationId: string; projectId: string; expectedRevision: number; entries: readonly unknown[];
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+  rollback(command: Readonly<{
+    operationId: string; projectId: string; expectedRevision: number; restoreRevision: number;
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
+}
+
+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>[]>;
+}
+
+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 =
+  '收件箱已读标记未接线：unified_inbox_request/notice 表未注册或 DatabaseHost 未启动';
+
+export interface ScheduleJobRow {
+  id: string;
+  cron: string;
+  description?: string;
+}
+
+export interface InboxSelection {
+  where(query: Record<string, unknown>): InboxSelection;
+  /** 可选：DB 侧排序下推（wrapModel 链具备该能力，轻量 fake 可缺失）。 */
+  orderBy?(field: string, direction?: 'ASC' | 'DESC'): InboxSelection;
+  /** 可选：DB 侧 limit 下推。 */
+  limit?(count: number): InboxSelection;
+  /** 可选：DB 侧 offset 下推。 */
+  offset?(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>;
+}
+
+export interface InboxModel {
+  select(): InboxSelection;
+  update?(patch: Record<string, unknown>): {
+    where(query: Record<string, unknown>): Promise<unknown> | unknown;
+  };
+}
+
+export 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[]>;
+  listRequests?(): Promise<readonly {
+    platform_request_id: string;
+    type: string;
+    scene_type?: string | null;
+    scene_id: string;
+    sub_type?: string | null;
+    actor_id: string;
+    actor_name?: string | null;
+    comment?: string | null;
+    created_at: number;
+  }[]>;
+  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>;
+}

package/src/console-rpc-extended/dispatcher.ts

@@ -0,0 +1,114 @@
+import { assertDemoConsoleRpcAllowed } from '@zhin.js/console-protocol';
+import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
+import { addCron, listSchedule, mutateCron } from './schedule-rpc.js';
+import {
+  actOnRequest, listInbox, listInboxMessages, listPendingRequests, listRecentInboxMessages,
+  mapNoticeRow, mapRequestRow, markInboxConsumed, TABLE_NOTICE, TABLE_REQUEST,
+} from './inbox-rpc.js';
+import { cancelLogin, listLoginPending, submitLogin } from './login-rpc.js';
+import {
+  deleteFriend, groupWriteOp, listChannels, listFriends, listGroupMembers, listGroups,
+} from './endpoint-rpc.js';
+import { mutateWorkroomKnowledge, mutateWorkroomProfile } from './workroom-rpc.js';
+
+export async function dispatchExtendedConsoleRpc(
+  type: string,
+  data: Record<string, unknown> | undefined,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult | undefined> {
+  const d = data ?? {};
+
+  if (!ctx.fullScope) {
+    const denied = assertDemoConsoleRpcAllowed(type);
+    if (denied) return { error: denied };
+  }
+
+  switch (type) {
+    case 'schedule:list':
+    case 'cron:list':
+      return listSchedule(ctx);
+
+    case 'cron:add':
+      return addCron(d, ctx);
+    case 'cron:remove':
+    case 'cron:pause':
+    case 'cron:resume':
+      return mutateCron(type, d, ctx);
+
+    case 'request.list':
+      return listPendingRequests(d, ctx);
+    case 'inbox.requests':
+      return listInbox(d, ctx, TABLE_REQUEST, 'requests', mapRequestRow);
+    case 'inbox.notices':
+      return listInbox(d, ctx, TABLE_NOTICE, 'notices', mapNoticeRow);
+    case 'inbox.messages':
+      return listInboxMessages(d, ctx);
+    case 'inbox.recent':
+      return listRecentInboxMessages(d, ctx);
+
+    case 'request.approve':
+    case 'request.reject':
+      return actOnRequest(type, d, ctx);
+
+    case 'login.list':
+      return listLoginPending(ctx);
+    case 'login.submit':
+      return submitLogin(d, ctx);
+    case 'login.cancel':
+      return cancelLogin(d, ctx);
+
+    case 'request.consumed':
+      return markInboxConsumed(d, ctx, TABLE_REQUEST);
+    case 'notice.consumed':
+      return markInboxConsumed(d, ctx, TABLE_NOTICE);
+
+    case 'endpoint.friends':
+      return listFriends(d, ctx);
+    case 'endpoint.groups':
+      return listGroups(d, ctx);
+    case 'endpoint.channels':
+      return listChannels(d, ctx);
+    case 'endpoint.group_members':
+      return listGroupMembers(d, ctx);
+
+    case 'endpoint.group_kick':
+      return groupWriteOp(d, ctx, {
+        method: 'kickGroupMember',
+        buildArgs: (gid, uid) => [gid, uid],
+        requireUser: true,
+        unsupported: '踢出群成员',
+      });
+    case 'endpoint.group_mute':
+      return groupWriteOp(d, ctx, {
+        method: 'muteGroupMember',
+        buildArgs: (gid, uid, extra) => [gid, uid, extra.duration ?? 600],
+        requireUser: true,
+        unsupported: '禁言群成员',
+      });
+    case 'endpoint.group_admin':
+      return groupWriteOp(d, ctx, {
+        method: 'setGroupAdmin',
+        buildArgs: (gid, uid, extra) => [gid, uid, extra.enable !== false],
+        requireUser: true,
+        unsupported: '设置群管理员',
+      });
+    case 'endpoint.delete_friend':
+      return deleteFriend(d, ctx);
+
+    case 'workroom.profile.status':
+    case 'workroom.profile.bootstrap':
+    case 'workroom.profile.pack.publish':
+    case 'workroom.profile.publish':
+    case 'workroom.profile.rollback':
+    case 'workroom.profile.policy.publish':
+      return mutateWorkroomProfile(type, d, ctx);
+
+    case 'workroom.knowledge.get':
+    case 'workroom.knowledge.publish':
+    case 'workroom.knowledge.rollback':
+      return mutateWorkroomKnowledge(type, d, ctx);
+
+    default:
+      return undefined;
+  }
+}

package/src/console-rpc-extended/endpoint-rpc.ts

@@ -0,0 +1,174 @@
+import type { ConsoleRpcExtendedCtx, EndpointManagementPort, ExtendedRpcResult } from './contracts.js';
+import { boolField, numField, strField, withLiveEndpoint } from './rpc-values.js';
+
+export async function listFriends(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
+    if (management.listFriends) {
+      const friends = [...await management.listFriends()];
+      return { data: { friends, count: friends.length } };
+    }
+    return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+  });
+}
+
+export async function listGroups(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
+    if (management.listGroups) {
+      const groups = [...await management.listGroups()];
+      return { data: { groups, count: groups.length } };
+    }
+    return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+  });
+}
+
+export async function listChannels(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
+    if (management.listChannels) {
+      const channels = [...await management.listChannels()];
+      return { data: { channels, count: channels.length } };
+    }
+    return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+  });
+}
+
+export async function listGroupMembers(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const adapter = strField(d, 'adapter');
+  const endpointKey = strField(d, 'endpointKey');
+  const groupId = strField(d, 'groupId');
+  if (!adapter || !endpointKey || !groupId) {
+    return { error: 'adapter, endpointKey, and groupId are required' };
+  }
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const method = management.listGroupMembers;
+    if (!method) {
+      return { error: `当前适配器（${adapter}）不支持群成员列表` };
+    }
+    const members = [...await method(groupId)];
+    return { data: { members, count: members.length } };
+  });
+}
+
+// ---------------------------------------------------------------- 群管/好友写操作
+
+interface GroupWriteSpec {
+  method: 'kickGroupMember' | 'muteGroupMember' | 'setGroupAdmin';
+  buildArgs(groupId: string, userId: string, extra: { duration?: number; enable?: boolean }): unknown[];
+  requireUser: boolean;
+  /** 中文操作名，用于"该平台不支持 xxx"。 */
+  unsupported: string;
+}
+
+export async function groupWriteOp(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+  spec: GroupWriteSpec,
+): Promise<ExtendedRpcResult> {
+  const adapter = strField(d, 'adapter');
+  const endpointKey = strField(d, 'endpointKey');
+  const groupId = strField(d, 'groupId');
+  const userId = strField(d, 'userId');
+  if (!adapter || !endpointKey || !groupId) {
+    return { error: 'adapter, endpointKey, and groupId are required' };
+  }
+  if (spec.requireUser && !userId) {
+    return { error: 'userId is required' };
+  }
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const method = management[spec.method];
+    if (!method) {
+      return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
+    }
+    const durationRaw = d.duration;
+    const enableRaw = d.enable;
+    const args = spec.buildArgs(groupId, userId, {
+      duration: typeof durationRaw === 'number' && Number.isFinite(durationRaw)
+        ? durationRaw
+        : undefined,
+      enable: typeof enableRaw === 'boolean' ? enableRaw : undefined,
+    });
+    await (method as (...args: unknown[]) => Promise<void>).call(management, ...args);
+    return { data: { success: true } };
+  });
+}
+
+export async function deleteFriend(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const adapter = strField(d, 'adapter');
+  const endpointKey = strField(d, 'endpointKey');
+  const userId = strField(d, 'userId');
+  if (!adapter || !endpointKey || !userId) {
+    return { error: 'adapter, endpointKey, and userId are required' };
+  }
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const method = management.deleteFriend;
+    if (!method) {
+      return { error: '当前适配器暂不支持删除好友' };
+    }
+    await method(userId);
+    return { data: { success: true } };
+  });
+}
+
+// ---------------------------------------------------------------- helpers
+
+
+function requireEndpointAddress(
+  d: Record<string, unknown>,
+): { adapter: string; endpointKey: string } | { error: string } {
+  const adapter = strField(d, 'adapter');
+  const endpointKey = strField(d, 'endpointKey');
+  if (!adapter || !endpointKey) return { error: 'adapter and endpointKey are required' };
+  return { adapter, endpointKey };
+}
+
+export 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 };
+  const id = typeof parent.id === 'string' && parent.id.trim() ? parent.id.trim() : undefined;
+  if (!id) return undefined;
+  let type: 'group' | 'guild' | undefined;
+  if (parent.type === 'group' || parent.type === 'guild') type = parent.type;
+  else if (parent.type === 'channel') type = 'guild';
+  if (!type) return undefined;
+  const name = typeof parent.name === 'string' && parent.name.trim() ? parent.name.trim() : undefined;
+  return name ? { type, id, name } : { type, id };
+}
+
+export function channelFromStoredRow(row: Record<string, unknown>): Record<string, unknown> {
+  const parent = parentFromStoredRow(row);
+  return {
+    id: String(row.channel_id ?? ''),
+    type: String(row.channel_type ?? ''),
+    ...(row.channel_name != null ? { name: String(row.channel_name) } : {}),
+    ...(parent ? { parent } : {}),
+  };
+}
+
+function parentFromStoredRow(
+  row: Record<string, unknown>,
+): { type: 'group' | 'guild'; id: string; name?: string } | undefined {
+  return normalizeParent({
+    type: row.channel_parent_type,
+    id: row.channel_parent_id,
+  });
+}