@zhin.js/adapter-icqq 6.0.3 → 7.0.1

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @zhin.js/adapter-icqq
 
+## 7.0.1
+
+### Patch Changes
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 7.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- e5c84ed: Adapter 多账号：插件实例 config 支持 `endpoints: [{name, ...覆盖}]` 数组，`expandEndpointConfigs` 将一个实例展开为多个 endpoint record（id 为 `<slotId>~<name>`，顶层字段共享、逐项覆盖），替代多 `instanceKey` 方案；Console `/api/plugins` 收敛为一个插件卡片 + 多 endpoint。icqq / qq schema 与 README 补 `endpoints` 配置。
+
+  Plugin Runtime Console Host：补 `/esm/*` React/router ESM 代理路由（legacy `consoleApiRouter` 对齐），TypeScriptClientBuilder 裸导入改写为 `/esm/<enc>.mjs`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - zhin.js@5.0.0
+
 ## 6.0.3
 
 ### Patch Changes

package/README.md

@@ -8,6 +8,7 @@ ICQQ Plugin Runtime 适配器 — 通过 [@icqqjs/cli](https://github.com/icqqjs
 - 入站：`messageGatewayToken`（IPC 事件订阅）
 - 出站：`send({ target, payload })` → `send_group_msg` / `send_private_msg` / …
 - Agent 工具：`agent/tools/`（戳一戳、群管、好友列表等）保留
+- Console Endpoint 管理：`src/endpoint.ts` 显式实现 `EndpointManagement`（好友/群/群成员列表、请求审批、删好友、踢人、禁言、设管理），Console 使用 `endpoint.friends` / `endpoint.groups` / `endpoint.group_members` 等规范 RPC
 
 ## 安装
 
@@ -21,12 +22,28 @@ pnpm add -g @icqqjs/cli   # 或 npx icqq login
 ```yaml
 plugins:
   icqq:
-    name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 一致
+    master: "1659488338"        # 必填，顶层共享（/approve 与 master 角色）
     autoReconnect: true
-    # rpc:                    # 可选远程守护进程
-    #   host: 10.0.0.2
-    #   port: 9527
-    #   token: ${ICQQ_RPC_TOKEN}
+    endpoints:
+      - name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 一致
+      # rpc 为 endpoint 级字段：
+      # - name: "${ICQQ_ACCOUNT_2}"
+      #   rpc:
+      #     host: 10.0.0.2
+      #     port: 9527
+      #     token: ${ICQQ_RPC_TOKEN}
+```
+
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  icqq:
+    master: "1659488338"      # 顶层字段所有 endpoint 共享
+    endpoints:
+      - name: "${ICQQ_ACCOUNT}"
+      - name: "${ICQQ_ACCOUNT_2}"
+      - name: "${ICQQ_ACCOUNT_3}"   # 各账号须分别 icqq login
 ```
 
 先执行 `icqq login`，再启动 Zhin。
@@ -52,6 +69,7 @@ plugins:
 
 - `autoReconnect` 已恢复实现：IPC/RPC 意外断开后按指数退避自动重连（`stop()` 为主动断开，不触发重连）。
 - `outboundMedia: file | base64` 已恢复实现：`file` 模式把 segment base64 落盘为临时文件后发 `[image:path]`；`base64` 模式（配置 `rpc` 时默认）发 `[image:base64://...]` 由守护进程解码。
+- **Console 社交/群管 RPC 已接线**：endpoint 在 Adapter 内把 ICQQ 的 `get_friend_list` / `get_group_list` / `get_group_member_list`、请求审批和群管操作归一化为冻结的 `EndpointManagement` 对象。Host 只消费该语义端口，不再探测方法别名或读取 `friends` / `groups` SDK 缓存。
 - **notice / request 入站事件已移除**：Plugin Runtime 的 `MessageGateway` 仅有 message 通道，没有 `notice.receive` / `request.receive` 事件机制，旧 `icqq-side-events.ts` / `get-msg.ts` / `login-ipc-contract.ts` / `agent-prompt.ts` 随之删除。需要好友/入群请求处理能力时请等待 runtime 提供事件通道后再恢复。
 
 ## License

package/adapters/icqq.ts

@@ -1,9 +1,18 @@
 /**
  * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
  */
-import { defineAdapter } from '@zhin.js/adapter';
+import { defineAdapter, type AdapterContext } from '@zhin.js/adapter';
 import { messageGatewayToken } from '@zhin.js/core/runtime';
-import { IcqqIpcEndpoint } from '../src/endpoint.js';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  databaseHostToken,
+  INBOX_TABLE_NOTICE,
+  INBOX_TABLE_REQUEST,
+  runtimeEventPublisherToken,
+  type Token,
+} from '@zhin.js/plugin-runtime';
+import { IcqqIpcEndpoint, type IcqqInboxHooks } from '../src/endpoint.js';
+import { icqqRuntimeStateToken } from '../src/icqq-runtime-state.js';
 import {
   resolveIcqqConfig,
   type IcqqAdapterConfig,
@@ -16,15 +25,82 @@ export type {
   IcqqIpcTransport,
 } from '../src/endpoint.js';
 
+const logger = getLogger('icqq');
+
 export default defineAdapter<IcqqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 统一消息元素通道（UNI-Channel）：端点可消费 base64 / url / upload 媒体
+  // （path 由出站物化按 file/base64 模式转换，非声明消费形态）；
+  // 卡片/按钮等富交互段无原生承载，降级纯文本。
+  segments: {
+    outboundMedia: ['base64', 'url', 'upload'],
+    interactive: 'text',
+  },
   create(context) {
     // Client-library / IPC daemon path — no httpHostToken.
     // Console loginAssist + host-router routes deferred.
+    const config = resolveIcqqConfig(context.config);
+    // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
+    context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.rpc ? 'rpc' : 'ipc',
+    });
+    const inbox = resolveInboxHooks(context);
     return new IcqqIpcEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
-      config: resolveIcqqConfig(context.config),
+      config,
+      ...(inbox ? { inbox } : {}),
     });
   },
 });
+
+/** 资源可选（轻量 Root 无 DatabaseHost / console hub）：缺失时降级为不写收件箱。 */
+function tryUse<T>(context: AdapterContext<IcqqAdapterConfig>, token: Token<T>): T | undefined {
+  try {
+    return context.use(token);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 收件箱钩子：写 unified_inbox_request/notice（按 platform_*_id 去重，
+ * 推送事件与 GET_SYSTEM_MSG 首拉可能重复同一请求），并经 console hub 广播。
+ */
+function resolveInboxHooks(context: AdapterContext<IcqqAdapterConfig>): IcqqInboxHooks | undefined {
+  const host = tryUse(context, databaseHostToken);
+  const publisher = tryUse(context, runtimeEventPublisherToken);
+  if (!host && !publisher) return undefined;
+  const insertDeduped = async (
+    table: string,
+    idField: 'platform_request_id' | 'platform_notice_id',
+    row: Record<string, unknown>,
+  ): Promise<void> => {
+    const model = host?.models.get(table);
+    if (!model) return;
+    try {
+      const existing = await model.select().where({
+        adapter: row.adapter,
+        endpoint_id: row.endpoint_id,
+        [idField]: row[idField],
+      });
+      if (Array.isArray(existing) && existing.length > 0) return;
+      await model.insert(row);
+    } catch (error) {
+      logger.warn(formatCompact({
+        op: 'inbox_insert',
+        table,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  };
+  const publish = publisher;
+  return {
+    recordRequest: (row) => insertDeduped(INBOX_TABLE_REQUEST, 'platform_request_id', row),
+    recordNotice: (row) => insertDeduped(INBOX_TABLE_NOTICE, 'platform_notice_id', row),
+    ...(publish
+      ? { publish: (type: string, data: unknown): void => publish.publish(type, data) }
+      : {}),
+  };
+}

package/commands/endpoint/add/[name:string=].ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { icqqEndpointCommands } from '../../../src/icqq-endpoint-commands.js';
+
+export default icqqEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,11 +1,11 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type IcqqInboundMessage, type IpcEvent, type IpcResponse, type ResolvedIcqqConfig } from './protocol.js';
-import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+import type { IpcFriendInfo, IpcGroupInfo, IpcMemberInfo } from './types.js';
 /** Minimal IPC surface used by the endpoint (real IpcClient or test mock). */
 export interface IcqqIpcTransport {
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
@@ -16,11 +16,22 @@ export interface IcqqIpcTransport {
     close(): void;
 }
 export type CreateIcqqIpc = (config: ResolvedIcqqConfig) => Promise<IcqqIpcTransport>;
+/**
+ * 收件箱写/推钩子（由装配层注入，见 adapters/icqq.ts）。
+ * record* 写 unified_inbox_request/notice；publish 向 console hub 推送实时事件。
+ */
+export interface IcqqInboxHooks {
+    recordRequest(row: Record<string, unknown>): void | Promise<void>;
+    recordNotice(row: Record<string, unknown>): void | Promise<void>;
+    publish?(type: string, data: unknown): void;
+}
 export interface IcqqEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
     readonly config: ResolvedIcqqConfig;
     readonly createIpc?: CreateIcqqIpc;
+    /** 未注入时 request/notice 事件仅按非消息载荷忽略（不报错）。 */
+    readonly inbox?: IcqqInboxHooks;
 }
 export declare class IcqqIpcEndpoint implements EndpointInstance {
     #private;
@@ -29,6 +40,7 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     ipc: IcqqIpcTransport;
     readonly friends: Map<number, IpcFriendInfo>;
     readonly groups: Map<number, IpcGroupInfo>;
+    readonly management: EndpointManagement;
     constructor(options: IcqqEndpointOptions);
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
     start(): Promise<void>;
@@ -46,6 +58,44 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     removeReaction(messageId: string, reactionId: string): Promise<void>;
     /** Activity-feedback autoRemove / Console recall. */
     recallMessage(messageId: string): Promise<void>;
+    /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
+    getFriendList(): Promise<Array<{
+        user_id: number;
+        nickname: string;
+        remark: string;
+    }>>;
+    /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
+    getGroupList(): Promise<Array<{
+        group_id: number;
+        name: string;
+    }>>;
+    /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
+    getGroupMemberList(groupId: number | string): Promise<IpcMemberInfo[]>;
+    /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
+    listMembers(groupId: number | string): Promise<IpcMemberInfo[]>;
+    getMemberList(groupId: number | string): Promise<IpcMemberInfo[]>;
+    /**
+     * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
+     * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
+     */
+    approveRequest(id: string, remark?: string): Promise<void>;
+    rejectRequest(id: string, reason?: string): Promise<void>;
+    /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
+    deleteFriend(userId: number | string): Promise<void>;
+    /** deleteFriend 别名（console 探测 delete_friend）。 */
+    delete_friend(userId: number | string): Promise<void>;
+    /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
+    removeMember(groupId: number | string, userId: number | string): Promise<void>;
+    kickMember(groupId: number | string, userId: number | string): Promise<void>;
+    setGroupKick(groupId: number | string, userId: number | string): Promise<void>;
+    /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
+    muteMember(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    banMember(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    setGroupMute(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
+    setModerator(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
+    setAdmin(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
+    setGroupAdmin(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
     /** Test / internal: admit when open. */
     admit(msg: IcqqInboundMessage): void;
 }