@zhin.js/adapter-icqq 8.0.14 → 9.0.1

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @zhin.js/adapter-icqq
 
+## 9.0.1
+
+### Patch Changes
+
+- 54bfd6b: Introduce Prompt Sections as a generation-owned Plugin Runtime Feature. Projects can declare typed context under `agent/prompt-sections/`, select interactive or scheduled profiles and IM platforms, and govern presentation order separately from required/preferred/opportunistic budget retention. In-flight turns remain pinned to their original generation across hot reloads, required policy fails explicitly when it cannot fit, duplicate identities are rejected, and the previous mutable Agent-local discovery and platform contributor APIs are removed. ICQQ and GitHub platform guidance now use the same Feature instead of a module-global registry.
+
+  Expose a content-free Prompt Section catalog through Console introspection, including owner, source, generation, profiles, and budget policy without disclosing prompt text. New AI projects mount the Feature automatically, and the full-bot example plus Chinese and English product documentation demonstrate the supported configuration.
+
+- e9c6a73: Keep a replacement ICQQ connection alive when configuration hot reload retires the previous endpoint.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/prompt-section@0.0.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - @zhin.js/tool@1.0.13
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
+## 9.0.0
+
+### Patch Changes
+
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
 ## 8.0.14
 
 ### Patch Changes

package/README.md

@@ -5,7 +5,7 @@ ICQQ Plugin Runtime 适配器 — 进程内直接使用 [@icqqjs/icqq](https://g
 ## 功能特性
 
 - 群聊 / 私聊 / 群临时会话 / QQ 频道消息
-- 入站：`messageGatewayToken`，文本与图片 / 语音 / 视频 / 文件统一归一为 canonical `Segment` + `MediaRef`
+- 入站：ICQQ Client 原始事件经 `Endpoint.emit(...)` 唯一入口上送；文本与图片 / 语音 / 视频 / 文件统一归一为 canonical `Segment` + `MediaRef`
 - 出站：canonical Segment 直接投影为 ICQQ 原生 `Sendable`，再由 `sendGroupMsg` / `sendPrivateMsg` / …发送
 - 群聊 reaction：`control.addReaction` / `removeReaction`（协议 ACK 失败不阻塞后续发送）
 - Agent 工具：包根 `tools/`（`@zhin.js/tool` Feature；模型侧名为 `icqq__send_user_like` 等）
@@ -32,6 +32,12 @@ pnpm add @icqqjs/qqsign
 
 签名：未配置 `signApiAddr` 时，若已安装 `@icqqjs/qqsign` 则自动走本地签名。
 
+## 前置条件
+
+1. 准备可登录的 QQ 账号，并选择远程 `signApiAddr` 或安装本地 `@icqqjs/qqsign`。
+2. 确保运行目录可持久化设备与登录状态；容器部署应挂载对应数据目录。
+3. 首次登录可能要求二维码、滑块或设备确认，可在 Console 登录待办或终端完成。
+
 ## 配置（Plugin Runtime）
 
 ```yaml
@@ -65,10 +71,74 @@ plugins:
 | 群临时会话 | `{ kind: 'private', id: uin, parent: { kind: 'group', id: gid } }` |
 | 频道 | `{ kind: 'channel', id: channelId, parent: { kind: 'channel', id: guildId } }` |
 
+## 直接使用完整 ICQQ Client
+
+适配器把 `icqq` 注册为 `@icqqjs/icqq.Client` 与 SDK `EventMap` 的类型判别项。
+所有 Feature 都使用同一个 `adapter` 字段完成类型缩窄与运行时过滤：
+
+```ts
+import { defineHandler } from 'zhin.js/handler'
+import '@zhin.js/adapter-icqq'
+
+export default defineHandler({
+  adapter: 'icqq',
+  event: 'request.group.add',
+  async handle({ client, event }) {
+    await client.setGroupAddRequest(event.flag, true)
+  },
+})
+```
+
+`client` 就是当前账号的真实 ICQQ SDK 实例，不是 Endpoint facade。未知扩展事件可显式使用
+`event: '*'`；此时 Client 类型保持完整，事件 payload 为 `unknown`。普通消息回复仍应走
+`Message.$reply`；群管理、请求审批与 ICQQ 专属查询可直接调用当前事件的 `client`。
+
+Command context 的 `$client` 是按需读取的 getter：
+
+```ts
+export default defineCommand({
+  adapter: 'icqq',
+  async execute(context) {
+    await context.$client.sendLike(Number(context.sender!.id), 10)
+    return 'ok'
+  },
+})
+```
+
+Middleware 使用同一个判别字段；不声明 `adapter` 时 `$client` 的类型是 `unknown`：
+
+```ts
+export default defineMiddleware<Message>({
+  target: 'inbound',
+  adapter: 'icqq',
+  async handle(context, next) {
+    console.log(context.$client.uin, context.input.content)
+    await next()
+  },
+})
+```
+
+Agent tool 的 IM turn 同样直接读取当前 Client：
+
+```ts
+export default defineAgentTool({
+  adapter: 'icqq',
+  description: '获取群列表',
+  async execute(_input, context) {
+    return context.$client.getGroupList()
+  },
+})
+```
+
+`adapter` 缺失时 `$client` 静态类型为 `unknown`；声明后若实际 operation 不属于 ICQQ，
+运行时会在执行前拒绝。Client 只能在当前 operation 内使用。task、schedule 或 Host 等脱离
+IM turn 的场景，才使用 `icqqClient.get(context, endpointId)` 显式选择账号。
+
 ## 架构
 
 - `plugin.ts` + `adapters/icqq.ts`（`defineAdapter`）
-- Endpoint：`src/endpoint.ts`（继承 icqq `Client`，`start()` 内 `login()`）
+- Client token：`src/client.ts`（直接引用 ICQQ `Client` / `EventMap`）
+- Endpoint：`src/endpoint.ts`（组合 ICQQ `Client`，负责账号 transport 与 Zhin lifecycle）
 - 协议常量 / 配置：`src/protocol.ts`
 - Agent 工具：`tools/*.ts`；权限说明见 `agent/PERMITS.md`
 
@@ -80,10 +150,19 @@ plugins:
 - ICQQ 的语音、视频、文件是独立消息元素；它们与其他段混发时适配器会明确拒绝，避免协议栈静默丢段。
 - 入站语音 / 视频在 Endpoint 持有原生 Client 时解析可下载 URL；解析失败则保留真实平台引用，不伪造或丢弃媒体。
 - **Console 社交/群管 RPC 已接线**：endpoint 把好友/群/群成员列表、请求审批和群管操作归一化为冻结的 `EndpointManagement`。Host 只消费该语义端口。
-- 好友/入群请求与通知：经 `sideEventGatewayToken` 分发到 `handlers`（`notice.receive` / `request.receive`）；审批走 `Request.$approve` / `EndpointManagement.approveRequest`。Console `request.list` 优先读 `management.listRequests()`（`getSystemMsg`），不再写入 `unified_inbox_request/notice`。
+- 好友/入群请求与通知：经 the unified `Endpoint.emit(...)` ingress 分发到 `handlers`（`notice.receive` / `request.receive`）；审批走 `Request.$approve` / `EndpointManagement.approveRequest`。Console `request.list` 优先读 `management.listRequests()`（`getSystemMsg`），不再写入 `unified_inbox_request/notice`。
 - `system.*`（登录扫码等）分发到 `system.receive`。
 - **登录辅助**：`system.login.qrcode|slider|device|auth` 经 `loginAssistToken`（`LoginAssist`）挂起待办；刷新后可用 Console `login.list` / `login.submit` 或终端 stdin 继续（对齐 icqq 官方 stdin 流程）。`system.online` / `login.error` 会清理该 endpoint 待办。
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| 一直停在登录中 | 打开 Console 登录待办，完成二维码、滑块或设备确认 |
+| 签名失败 | 检查 `signApiAddr`；本地模式确认 `@icqqjs/qqsign` 已安装且版本匹配 |
+| 重启后重复登录 | 持久化设备与会话数据目录，避免每次生成新设备 |
+| 请求或通知未显示 | 在 Endpoint 详情检查请求视图；ICQQ 优先读取平台请求列表 |
+
 ## License
 
 MIT

package/adapters/icqq.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { loginAssistToken, messageGatewayToken, sideEventGatewayToken, } from '@zhin.js/core/runtime';
+import { loginAssistToken } from '@zhin.js/core/runtime';
 import { IcqqEndpoint } from "../lib/endpoint.js";
 import { icqqRuntimeStateToken } from "../lib/icqq-runtime-state.js";
 import { resolveIcqqConfig, } from "../lib/protocol.js";
@@ -24,8 +24,6 @@ export default defineAdapter({
         });
         return new IcqqEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             loginAssist: context.use(loginAssistToken),
             config,
         });

package/adapters/icqq.ts

@@ -1,12 +1,8 @@
 /**
  * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
  */
-import { defineAdapter, type AdapterContext } from 'zhin.js/adapter';
-import {
-  loginAssistToken,
-  messageGatewayToken,
-  sideEventGatewayToken,
-} from '@zhin.js/core/runtime';
+import { defineAdapter } from 'zhin.js/adapter';
+import { loginAssistToken } from '@zhin.js/core/runtime';
 import { IcqqEndpoint } from '../src/endpoint.js';
 import { icqqRuntimeStateToken } from '../src/icqq-runtime-state.js';
 import {
@@ -39,8 +35,6 @@ export default defineAdapter<IcqqAdapterConfig>({
     });
     return new IcqqEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       loginAssist: context.use(loginAssistToken),
       config,
     });

package/agent/prompt-sections/platform.ts

@@ -0,0 +1,17 @@
+import { defineAgentPromptSection } from '@zhin.js/prompt-section';
+
+export default defineAgentPromptSection({
+  title: 'ICQQ / QQ',
+  content: [
+    'On icqq/QQ: if icqq__send_user_like is in your tool list, call it with { user_id, times }.',
+    'The current IM operation selects the bot Client automatically. user_id is the sender to like. times is 1-20.',
+    'Do not claim the tool is missing until calling it this turn or load_tool("icqq__send_user_like") fails.',
+    'Other social tools include icqq__poke and icqq__friend_list.',
+  ].join('\n'),
+  layer: 'tools',
+  order: 70,
+  retention: 'preferred',
+  maxChars: 1200,
+  profiles: ['interactive'],
+  platforms: ['icqq'],
+});

package/lib/client.d.ts

@@ -0,0 +1,19 @@
+import type { Client, EventMap } from '@icqqjs/icqq';
+type EventPayload<TListener> = TListener extends (event: infer TEvent, ...rest: readonly unknown[]) => unknown ? TEvent : never;
+/** The actual ICQQ SDK instance exposed by every ICQQ Endpoint event. */
+export type IcqqClient = Client;
+/** Native ICQQ event-name → first public event payload, derived from the SDK SSOT. */
+export type IcqqClientEventMap = {
+    readonly [TName in keyof EventMap]: EventPayload<EventMap[TName]>;
+};
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly icqq: {
+            readonly client: IcqqClient;
+            readonly events: IcqqClientEventMap;
+        };
+    }
+}
+/** Typed, generation-checked identity used by handlers, commands, tools and schedules. */
+export declare const icqqClient: import("@zhin.js/adapter").EndpointClientToken<Client, IcqqClientEventMap>;
+export {};

package/lib/client.js

@@ -0,0 +1,3 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Typed, generation-checked identity used by handlers, commands, tools and schedules. */
+export const icqqClient = defineEndpointClient('icqq');

package/lib/endpoint.d.ts

@@ -1,19 +1,21 @@
 import { Client } from '@icqqjs/icqq';
-import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { type LoginAssist } from '@zhin.js/core';
 import type { CapabilityId } from 'zhin.js';
 import { type IcqqInboundMessage, type ResolvedIcqqConfig } from './protocol.js';
 export interface IcqqEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
     readonly config: ResolvedIcqqConfig;
-    readonly sideEvents: SideEventGateway;
     readonly loginAssist: LoginAssist;
 }
-export declare class IcqqEndpoint extends Client implements EndpointInstance {
+declare class ManagedIcqqClient extends Client {
+    cancelReconnect(): void;
+}
+export declare class IcqqEndpoint extends Endpoint<Client> {
     #private;
+    readonly client: ManagedIcqqClient;
     readonly endpointName: string;
     readonly content: EndpointContentPort;
     readonly management: EndpointManagement;
@@ -24,5 +26,6 @@ export declare class IcqqEndpoint extends Client implements EndpointInstance {
     close(): Promise<void>;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    admit(msg: IcqqInboundMessage, admittedBeforeRetire?: boolean): void;
+    admit(msg: IcqqInboundMessage): Promise<void>;
 }
+export {};