@zhin.js/adapter-icqq 6.0.2 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @zhin.js/adapter-icqq
 
+## 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
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
 ## 6.0.2
 
 ### Patch Changes

package/README.md

@@ -1,464 +1,77 @@
 # @zhin.js/adapter-icqq
 
-> **QQ 群助手 + 可选 @AI** — 先在 [demo.zhin.dev](https://demo.zhin.dev) 或 Sandbox 调试逻辑，再接实机 QQ。启用 AI：`npx zhin setup --ai`。接入本适配器：`npx zhin setup --adapters`。
-
-Zhin.js ICQQ 适配器，通过 **[@icqqjs/cli](https://github.com/icqqjs/cli) 守护进程 IPC** 连接已登录的 QQ 账号，支持群聊和私聊消息。协议与登录由 CLI 负责，Zhin 侧只配置 QQ 号并连接本地/远程守护进程。
+ICQQ Plugin Runtime 适配器 — 通过 [@icqqjs/cli](https://github.com/icqqjs/cli) 守护进程 IPC 连接已登录 QQ 账号（无 `httpHostToken`）。
 
 ## 功能特性
 
-- 🤖 支持 QQ 群聊、私聊与**群临时会话**消息处理
-- 🔐 登录由 `icqq login` 完成（短信/二维码/滑块等由 CLI 处理）
-- 🖥️ **Web 控制台登录辅助**：与 `@zhin.js/host-api` 同时启用时，在 **`/icqq`** 页面提供「概览 + 登录辅助」；HTTP 接口为 **`GET /api/login-assist/pending`**、**`POST /api/login-assist/submit`**、**`POST /api/login-assist/cancel`**（由本适配器在路由上下文中注册，依赖核心 `loginAssist` 服务）。
-- 📨 消息发送和接收处理
-- 🔄 消息格式转换和适配
-- 📁 自动数据目录管理
-- 🖼️ 支持图片、语音、视频等多媒体消息
-- 🎯 支持 @ 提及和引用回复
-- 🔧 **群管理工具**：踢人、禁言、设置管理员、群名片、头衔等（AI 可调用）
-- 🔒 **权限控制**：基于群角色的工具权限过滤
+- 群聊 / 私聊 / 群临时会话 / QQ 频道消息
+- 入站：`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
 
 ## 安装
 
 ```bash
 pnpm add @zhin.js/adapter-icqq
+pnpm add -g @icqqjs/cli   # 或 npx icqq login
 ```
 
-登录与守护进程由 **@icqqjs/cli** 提供（与适配器包解耦，可全局安装）：
-
-```bash
-pnpm add -g @icqqjs/cli
-# 或：npx icqq login
-```
-
-## 配置
-
-在 `zhin.config.yml` 中声明 bot（**不在此填写 QQ 密码**）：
+## 配置（Plugin Runtime）
 
 ```yaml
-endpoints:
-  - context: icqq
-    name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 的账号一致
-    autoReconnect: true         # IPC 断开后自动重连，默认 true
-    # 远程 RPC（可选；默认连接 ~/.icqq/<uin>/daemon.sock）
-    # rpc:
-    #   host: 10.0.0.2
-    #   port: 9527
-    #   token: ${ICQQ_RPC_TOKEN}
-    typingIndicator:          # 可选：AI 处理中的群/私聊提示
-      enabled: true
-      defaultEmoji: "⏳"
-
 plugins:
-  - "@zhin.js/adapter-icqq"
-  - "@zhin.js/host-router"     # 可选
-  - "@zhin.js/host-api"        # 可选，Remote Console /icqq 页
-```
-
-TypeScript 配置等价写法：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'icqq',
-      name: process.env.ICQQ_ACCOUNT!,
-    },
-  ],
-  plugins: ['@zhin.js/adapter-icqq'],
-})
-```
-
-## 配置参数说明
-
-### 必需参数
-
-- `context`: 固定为 `'icqq'`
-- `name`: QQ 号（字符串，与守护进程账号一致）
-
-### 可选参数
-
-- `autoReconnect`: IPC/RPC 意外断开时是否指数退避重连（默认 `true`）
-- `rpc`: 远程守护进程连接（`host` / `port` / `token`）；不配置则使用本地 Unix socket `~/.icqq/<uin>/daemon.sock`
-- `typingIndicator`: AI 处理中的 reaction 或临时消息提示（见 `IcqqEndpointConfig` 类型）
-
-## 使用示例
-
-### 基础消息处理
-
-```typescript
-import { addCommand, MessageCommand } from 'zhin.js'
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
-```
-
-### 群聊消息
-
-```typescript
-import { onGroupMessage } from 'zhin.js'
-
-onGroupMessage(async (message) => {
-  console.log(`群 ${message.$channel.id} 收到消息：${message.$raw}`)
-  
-  // 回复群消息
-  await message.$reply('收到消息了！')
-})
-```
-
-### 私聊消息
-
-```typescript
-import { onPrivateMessage } from 'zhin.js'
-
-onPrivateMessage(async (message) => {
-  console.log(`私聊消息来自：${message.$sender.name}`)
-  await message.$reply('你好！')
-})
-```
-
-### 发送图片
-
-```typescript
-addCommand(new MessageCommand('pic <url:text>')
-  .action(async (message, result) => {
-    return [
-      { type: 'image', data: { file: result.params.url } }
-    ]
-  })
-)
+  icqq:
+    master: "1659488338"        # 必填，顶层共享（/approve 与 master 角色）
+    autoReconnect: true
+    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}
 ```
 
-**Zhin 与 icqq 守护进程不在同一台机器时**，请在 `zhin.config.yml` 为该 bot 设置 `outboundMedia: base64`（或配置 `rpc` 时会自动默认 `base64`）。此时 segment 保留 `base64`，经 CQ `[image:base64://...]` 交给守护进程解码，不要使用仅在本机有效的临时文件路径。
-
-Agent **`generate_image` 文生图**出站的大图同样依赖上述配置；同机默认可用本机临时文件路径（`outboundMedia: file`）。详见 [文生图 (generate_image)](https://github.com/zhinjs/zhin/blob/main/docs/advanced/ai.md#文生图-generate_image)。
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
 
 ```yaml
-endpoints:
-  - context: icqq
-    name: "123456"
-    outboundMedia: base64   # 异机 / 远程 RPC
-    # rpc: { host: ..., port: ..., token: ... }  # 配置 rpc 时默认已是 base64
-```
-
-### 发送语音
-
-```typescript
-addCommand(new MessageCommand('voice <file:text>')
-  .action(async (message, result) => {
-    return [
-      { type: 'record', data: { file: result.params.file } }
-    ]
-  })
-)
-```
-
-### @ 提及
-
-```typescript
-addCommand(new MessageCommand('at <user:at>')
-  .action(async (message, result) => {
-    const atUser = result.params.user
-    return [
-      { type: 'at', data: { qq: atUser.data.qq } },
-      { type: 'text', data: { text: ' 你好！' } }
-    ]
-  })
-)
-```
-
-## 登录流程
-
-1. **先登录 QQ**：在终端执行 `icqq login`，按 CLI 提示完成密码/扫码/滑块/设备锁等验证；会话由 `@icqqjs/cli` 守护进程维护。
-2. **再启动 Zhin**：`zhin.config.yml` 中 `endpoints[].name` 与上一步 QQ 号一致，启动 `zhin dev` / `zhin start`；适配器连接守护进程并开始收发消息。
-3. 若守护进程未运行或账号未登录，适配器会保持未连接状态，日志中会提示检查 `icqq` 守护进程。
-
-### Web 控制台登录辅助（可选）
-
-与 **`@zhin.js/host-api`** 同时启用时，Remote Console 的 **ICQQ 管理**（`/icqq`）可提供登录辅助 Tab，对应 API：`GET/POST /api/login-assist/*`（依赖核心 `loginAssist` 服务）。
-
-守护进程在登录/重连时按 **`@icqqjs/cli` IPC 契约**推送 `IpcEvent`（`id: "*"` + `event: "system.login.*"` + `data`）。其中 **`system.login.auth`** 携带 `url` + `device` 设备指纹（形状见 `@icqqjs/icqq` `EventMap`）。适配器将其桥接到 `LoginAssist` 并在控制台展示；用户完成验证后，续传 invoke 与 CLI `LoginFlow` 一致（`login` / `submit_slider` / `submit_sms_code` / `send_sms_code`，见 `login-ipc-contract.ts`）。
-
-## 消息类型支持
-
-### 接收消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ 语音消息
-- ✅ 视频消息
-- ✅ @ 提及
-- ✅ 表情消息
-- ✅ 引用回复
-- ✅ 文件消息
-- ✅ JSON 卡片消息
-- ✅ **群临时会话**（`message_type=private` + `sub_type=group`；`$channel` 为 `private` + `parent.group`）
-
-### 发送消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息（支持本地文件、URL、Base64）
-- ✅ 语音消息
-- ✅ 视频消息
-- ✅ @ 提及
-- ✅ 表情消息
-- ✅ 引用回复
-- ✅ 文件消息
-- ✅ JSON 卡片消息
-- ✅ 戳一戳
-- ✅ 音乐分享
-- ✅ **群临时会话**（`type: private` + `parent: { type: 'group', id }` → IPC `send_temp_msg`）
-
-## 群临时会话
-
-当群成员通过「临时会话」私聊机器人时，新版 `@icqqjs/cli` 会以私聊事件推送（`sub_type: group`，`sender.group_id` 为来源群）。适配器使用 `private` + `parent.group` 表达场景，而非发明新的顶层 `MessageType`。
-
-| 字段 | 值 |
-|------|-----|
-| `$channel.type` | `private`（对端 QQ） |
-| `$channel.parent` | `{ type: 'group', id: 群号 }` |
-
-`message.$reply` 会原样带上 `parent`，出站自动走 `send_temp_msg`。
-
-```typescript
-await adapter.sendMessage({
-  context: 'icqq',
-  endpoint: '你的QQ号',
-  type: 'private',
-  id: '987654321',
-  parent: { type: 'group', id: '123456789' },
-  content: [{ type: 'text', data: { text: '你好' } }],
-})
-```
-
-## API 方法
-
-```typescript
-const endpoint = app.adapters.get('icqq')?.endpoints.get('你的QQ号')
-
-// 发送群消息
-await endpoint.sendGroupMsg(groupId, '消息内容')
-
-// 发送私聊消息
-await endpoint.sendPrivateMsg(userId, '消息内容')
-
-// 撤回消息
-await endpoint.$recallMessage(messageId)
-
-// 获取群列表
-const groupList = endpoint.getGroupList()
-
-// 获取好友列表
-const friendList = endpoint.getFriendList()
-
-// 获取群成员信息
-const memberInfo = endpoint.getGroupMemberInfo(groupId, userId)
-```
-
-## 🔧 群管理工具（AI 可调用）
-
-
-适配器通过覆写 `ISceneManagement` 标准方法自动注册群管理工具，同时保留平台特有工具，这些工具可以被 AI 调用，实现智能化的群管理。
-
-### 标准群管工具（自动生成）
-
-通过覆写 `ISceneManagement` 方法，`start()` 时自动检测并生成对应 Tool：
-
-| 工具 | 覆写方法 | 所需权限 | 说明 |
-|------|---------|----------|------|
-| `icqq_kick_member` | `kickMember` | 管理员 | 踢出群成员 |
-| `icqq_mute_member` | `muteMember` | 管理员 | 禁言群成员 |
-| `icqq_mute_all` | `muteAll` | 管理员 | 全员禁言 |
-| `icqq_set_admin` | `setAdmin` | 群主 | 设置/取消管理员 |
-| `icqq_set_nickname` | `setMemberNickname` | 管理员 | 设置群名片 |
-| `icqq_set_group_name` | `setGroupName` | 管理员 | 修改群名称 |
-| `icqq_list_members` | `listMembers` | 普通用户 | 获取群成员列表 |
-
-### 平台特有工具（手动注册）
-
-| 工具 | 所需权限 | 说明 |
-|------|----------|------|
-| `icqq_set_title` | 群主 | 设置专属头衔 |
-| `icqq_announce` | 管理员 | 发送群公告 |
-| `icqq_poke` | 普通用户 | 戳一戳 |
-| `icqq_list_muted` | 普通用户 | 获取被禁言成员列表 |
-| `icqq_send_user_like` | 普通用户 | 发送用户点赞 |
-| `icqq_set_anonymous` | 管理员 | 开启/关闭匿名聊天 |
-| `icqq_group_files` | 普通用户 | 获取群文件列表 |
-| `icqq_friend_list` | 普通用户 | 获取好友列表 |
-
-### 使用示例
-
-#### 通过 AI 对话管理群
-
-```
-用户（群主）：把 @小明 踢出群并拉黑
-AI：已将 小明 踢出群并拉黑。
-
-用户（管理员）：禁言 @捣蛋鬼 1小时
-AI：已禁言 捣蛋鬼 3600 秒。
-
-用户（管理员）：发个群公告：明天下午3点开会
-AI：群公告已发送。
-
-用户：戳一戳 @朋友
-AI：已戳了戳 朋友。
-```
-
-#### 编程调用
-
-```typescript
-// 获取 ICQQ Endpoint 实例
-const icqqAdapter = app.adapters.get('icqq')
-const endpoint = icqqAdapter?.endpoints.get('你的QQ号')
-
-// 踢出成员
-await endpoint.kickMember(groupId, userId, true) // 第三个参数为是否拉黑
-
-// 禁言成员（单位：秒）
-await endpoint.muteMember(groupId, userId, 600) // 禁言 10 分钟
-await endpoint.muteMember(groupId, userId, 0)   // 解除禁言
-
-// 全员禁言
-await endpoint.muteAll(groupId, true)  // 开启
-await endpoint.muteAll(groupId, false) // 关闭
-
-// 设置管理员
-await endpoint.setAdmin(groupId, userId, true)  // 设为管理员
-await endpoint.setAdmin(groupId, userId, false) // 取消管理员
-
-// 设置群名片
-await endpoint.setCard(groupId, userId, '新名片')
-
-// 设置专属头衔
-await endpoint.setTitle(groupId, userId, '大佬', -1) // -1 表示永久
-
-// 修改群名
-await endpoint.setGroupName(groupId, '新群名')
-
-// 发送群公告
-await endpoint.sendAnnounce(groupId, '公告内容')
-
-// 戳一戳
-await endpoint.pokeMember(groupId, userId)
-
-// 获取群成员列表
-const members = await endpoint.getMemberList(groupId)
-
-// 获取被禁言成员列表
-const mutedList = await endpoint.getMutedMembers(groupId)
-
-// 开启/关闭匿名
-await endpoint.setAnonymous(groupId, true)
-```
-
-### 发送者权限信息
-
-消息中的 `$sender` 包含 ICQQ 特有的权限信息：
-
-```typescript
-interface IcqqSenderInfo {
-  id: string;           // QQ 号
-  name: string;         // 昵称
-  role?: GroupRole;     // 'owner' | 'admin' | 'member'
-  isOwner?: boolean;    // 是否为群主
-  isAdmin?: boolean;    // 是否为管理员
-  card?: string;        // 群名片
-  title?: string;       // 专属头衔
-}
-```
-
-#### 在插件中检查权限
-
-```typescript
-onGroupMessage(async (message) => {
-  const sender = message.$sender as IcqqSenderInfo;
-  
-  if (sender.isOwner) {
-    console.log('这是群主的消息');
-  }
-  
-  if (sender.isAdmin) {
-    console.log('这是管理员的消息');
-  }
-  
-  if (sender.role === 'member') {
-    console.log('这是普通成员的消息');
-  }
-})
+plugins:
+  icqq:
+    master: "1659488338"      # 顶层字段所有 endpoint 共享
+    endpoints:
+      - name: "${ICQQ_ACCOUNT}"
+      - name: "${ICQQ_ACCOUNT_2}"
+      - name: "${ICQQ_ACCOUNT_3}"   # 各账号须分别 icqq login
 ```
 
-## icqq CLI 与 AI bash 安全
-
-
-完整说明与指令表见仓库文档：[docs/advanced/ai.md](../../../docs/advanced/ai.md)（锚点：`#icqq-bash-exec`、`#owner-approve-commands`）。
-
-## 注意事项
-
-### 账号安全
-
-- 建议使用小号测试
-- 避免短时间内发送大量消息
-- 保持 `@icqqjs/cli` 与适配器版本更新
+先执行 `icqq login`，再启动 Zhin。
 
-### 风控与掉线
+## Send target
 
-- 登录设备类型、签名服务等由 **`icqq login` / CLI 配置** 管理，不在 `zhin.config` 的 bot 段配置
-- 掉线时先检查守护进程：`icqq` 是否仍在运行、账号是否被踢下线
-- 可降低发消息频率，并在手机 QQ 完成安全验证后重新 `icqq login`
+| 类型 | target |
+|------|--------|
+| 私聊 | `private:uin` |
+| 群聊 | `group:gid` |
+| 群临时会话 | `temp:gid:uin` |
+| 频道 | `channel:guildId:channelId` |
 
-## 常见问题
+## 架构
 
-### Q: 启动后 bot 一直未连接？
-
-A:
-1. 确认已对该 QQ 号执行过 `icqq login` 且守护进程在运行
-2. 确认 `endpoints[].name` 与登录 QQ 号一致
-3. 远程部署时检查 `rpc.host` / `rpc.port` / `rpc.token`
-
-### Q: 还需要在 zhin.config 里写 password / platform 吗？
-
-A: **不需要**。这些字段属于旧版直连协议，当前适配器仅通过 IPC 连接 CLI 守护进程。
-
-### Q: 无法发送图片？
-
-A:
-1. 检查图片 URL 是否有效
-2. 本地文件需使用绝对路径
-3. 确认图片格式和大小符合要求
-
-### Q: 如何处理滑块/设备锁验证？
-
-A: 在运行 `icqq login` 的终端按提示操作；若启用了 Host API，也可在 Remote Console `/icqq` 登录辅助 Tab 提交验证码。
-
-## 相关链接
-
-- [@icqqjs/cli](https://github.com/icqqjs/cli)
-- [ICQQ 协议库](https://github.com/icqqjs/icqq)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
-- [签名服务器](https://github.com/fuqiuluo/unidbg-fetch-qsign)
-
-## 依赖项
-
-- `@icqqjs/cli` - 登录与守护进程（运行时需已安装并在 PATH 中）
-- `zhin.js` / `@zhin.js/core` - Zhin 框架（peer）
-- `@zhin.js/host-router` / `@zhin.js/host-api` - 可选，Console 与 HTTP 路由
-
-## 开发
-
-```bash
-pnpm build  # 构建
-pnpm clean  # 清理构建文件
-```
+- `plugin.ts` + `adapters/icqq.ts`（`defineAdapter`）
+- 协议常量 / 配置：`src/protocol.ts`
+- IPC 客户端：`src/ipc-client.ts`（无 host-http）
+- Console loginAssist / host-router 延期
+- 旧 `usePlugin` / `extends Adapter` / Endpoint 生产入口已删除
 
-## 许可证
+## Plugin Runtime 迁移说明
 
-MIT License
+- `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
 
-欢迎提交 Issue 和 Pull Request！
+MIT

package/adapters/icqq.ts

@@ -0,0 +1,92 @@
+/**
+ * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
+ */
+import { defineAdapter, type AdapterContext } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+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 {
+  resolveIcqqConfig,
+  type IcqqAdapterConfig,
+} from '../src/protocol.js';
+
+export { IcqqIpcEndpoint } from '../src/endpoint.js';
+export type {
+  CreateIcqqIpc,
+  IcqqEndpointOptions,
+  IcqqIpcTransport,
+} from '../src/endpoint.js';
+
+const logger = getLogger('icqq');
+
+export default defineAdapter<IcqqAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    // Client-library / IPC daemon path — no httpHostToken.
+    // Console loginAssist + host-router routes deferred.
+    const inbox = resolveInboxHooks(context);
+    return new IcqqIpcEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      config: resolveIcqqConfig(context.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) }
+      : {}),
+  };
+}