@zhin.js/adapter-icqq 6.0.1 → 6.0.3

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @zhin.js/adapter-icqq
 
+## 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
+
+- 872c583: Slack 适配器 Phase 1/2：mrkdwn 出站、长消息切分、斜杠/按钮 ephemeral 反馈、入站 mrkdwn→Markdown、editMessage 对齐 core。
+
+  Logger 表格日志与 string-width 列宽；Agent AI Handler 框线表格与 introspection/MCP 导出；Core side-event 归一化；Schedule 时区规划；多适配器 side-event 与 API surface 更新。
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/client@2.0.5
+  - @zhin.js/contract@1.0.3
+  - @zhin.js/core@1.3.4
+  - @zhin.js/host-api@2.0.5
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
 ## 6.0.1
 
 ### Patch Changes

package/README.md

@@ -1,464 +1,59 @@
 # @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/`（戳一戳、群管、好友列表等）保留
 
 ## 安装
 
 ```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:
+plugins:
+  icqq:
+    name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 一致
+    autoReconnect: true
+    # 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 } }
-    ]
-  })
-)
-```
-
-**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)。
-
-```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, '消息内容')
+先执行 `icqq login`，再启动 Zhin。
 
-// 撤回消息
-await endpoint.$recallMessage(messageId)
+## Send target
 
-// 获取群列表
-const groupList = endpoint.getGroupList()
+| 类型 | target |
+|------|--------|
+| 私聊 | `private:uin` |
+| 群聊 | `group:gid` |
+| 群临时会话 | `temp:gid:uin` |
+| 频道 | `channel:guildId:channelId` |
 
-// 获取好友列表
-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('这是普通成员的消息');
-  }
-})
-```
-
-## icqq CLI 与 AI bash 安全
-
-启用 **icqq 技能**（`skills/icqq`）时，模型通常会通过 **`bash`** 调用 `icqq …` 命令行。此时由框架 **`execSecurity` / `execApprovalMode`** 与 **Owner 私聊指令**（`approve always bash`、`approve rule <正则>` 等）共同约束：在 `allowlist` 下，**非敏感**子命令多数可直接执行；**敏感**子命令（踢人、禁言、解散、支付等）在 `execApprovalMode: ask` 时需 Owner 确认，并可用 **正则匹配整条子命令** 做持久化放行（不必把 QQ 号写进配置）。持久化文件为数据目录下的 `owner-approve-always.json`。
-
-完整说明与指令表见仓库文档：[docs/advanced/ai.md](../../../docs/advanced/ai.md)（锚点：`#icqq-bash-exec`、`#owner-approve-commands`）。
-
-## 注意事项
-
-### 账号安全
-
-- 建议使用小号测试
-- 避免短时间内发送大量消息
-- 保持 `@icqqjs/cli` 与适配器版本更新
-
-### 风控与掉线
-
-- 登录设备类型、签名服务等由 **`icqq login` / CLI 配置** 管理，不在 `zhin.config` 的 bot 段配置
-- 掉线时先检查守护进程：`icqq` 是否仍在运行、账号是否被踢下线
-- 可降低发消息频率，并在手机 QQ 完成安全验证后重新 `icqq login`
-
-## 常见问题
-
-### 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://...]` 由守护进程解码。
+- **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,30 @@
+/**
+ * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { IcqqIpcEndpoint } 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';
+
+export default defineAdapter<IcqqAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    // Client-library / IPC daemon path — no httpHostToken.
+    // Console loginAssist + host-router routes deferred.
+    return new IcqqIpcEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      config: resolveIcqqConfig(context.config),
+    });
+  },
+});

package/agent/tools/announce.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getIcqqAgentDeps } from '../../src/icqq-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; group_id: number; content: string }>({
+  description: '发送 QQ 群公告（需要管理员权限）',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint QQ号'),
+    group_id: z.number().describe('目标群号'),
+    content: z.string().describe('公告内容'),
+  }),
+  platforms: ['icqq'],
+  tags: ['icqq'],
+  permissions: ['platform(icqq,scene_admin)'],
+  async execute({ endpoint_id, group_id, content    }: { endpoint_id: string; group_id: number; content: string }) {
+    const { Actions } = await import('../../src/protocol.js');
+    const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
+    const resp = await endpoint.ipc.request(Actions.GROUP_ANNOUNCE, { group_id, content });
+    return { success: resp.ok, message: resp.ok ? '群公告已发送' : (resp.error ?? '发送失败') };
+  },
+});
+

package/agent/tools/essence.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getIcqqAgentDeps } from '../../src/icqq-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; message_id: string; action: 'add' | 'remove' }>({
+  description: '设置或移除 QQ 群精华消息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint QQ号'),
+    message_id: z.string().describe('消息 ID'),
+    action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
+  }),
+  platforms: ['icqq'],
+  tags: ['icqq'],
+  permissions: ['platform(icqq,scene_admin)'],
+  async execute({ endpoint_id, message_id, action }: { endpoint_id: string; message_id: string; action: 'add' | 'remove' }) {
+    const { Actions } = await import('../../src/protocol.js');
+    const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
+    const act = action === 'add' ? Actions.GROUP_ESSENCE_ADD : Actions.GROUP_ESSENCE_REMOVE;
+    const resp = await endpoint.ipc.request(act, { message_id });
+    return { success: resp.ok, message: resp.ok ? (action === 'add' ? '已设为精华' : '已移除精华') : (resp.error ?? '操作失败') };
+  },
+});
+

package/agent/tools/friend_list.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getIcqqAgentDeps } from '../../src/icqq-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string }>({
+  description: '获取 QQ 好友列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+  }),
+  platforms: ['icqq'],
+  tags: ['icqq'],
+  async execute({ endpoint_id    }: { endpoint_id: string }) {
+    const endpoint = getIcqqAgentDeps().getEndpoint(endpoint_id);
+    const friends = Array.from(endpoint.friends.values()).map((f) => ({
+      user_id: f.user_id, nickname: f.nickname, remark: f.remark,
+    }));
+    return { friends: friends.slice(0, 50), count: endpoint.friends.size };
+  },
+});
+