@zhin.js/adapter-icqq 1.0.71 → 1.1.0

package/agent/PERMITS.md

@@ -0,0 +1,24 @@
+# ICQQ Platform Permits（QQ 群）
+
+## 入站字段
+
+群成员 `owner` / `admin` / `member` 写入 `$sender.role`（IPC 侧已有）。
+
+## Permit 词汇表
+
+平台范围用工具的 `platforms: ['icqq']`，不要写非法的 `platform(icqq)`（缺 perm 时 PermissionHost 会直接拒绝，工具对模型不可见）。
+
+| `platform(icqq,…)` | 含义 |
+|--------------------|------|
+| `scene_owner` | 群主 |
+| `scene_admin` | 群管理员（含群主） |
+
+## 扩展工具示例
+
+| 工具 | permit |
+|------|--------|
+| `icqq_set_title` | `scene_owner` |
+| `icqq_announce` / `icqq_essence` / `icqq_list_muted` | `scene_admin` |
+| `icqq_set_anonymous` | `scene_owner` |
+
+工厂群管工具使用默认 `scene_admin` / `scene_owner`。

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/commands/endpoint/add/[[id]].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.add;

package/commands/endpoint/add/[[id]].ts

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

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.list;

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/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { icqqEndpointCommands } from "../../../lib/icqq-endpoint-commands.js";
+export default icqqEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

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

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/cq-message.d.ts

@@ -0,0 +1,14 @@
+/** ICQQ 历史文本视图 → canonical MessageSegment。出站只使用原生 Sendable。 */
+import { type MediaRef } from "@zhin.js/core";
+import type { MessageSegment } from "zhin.js";
+/**
+ * CQ 媒体参数 / 入站元素媒体值 → canonical MediaRef：
+ * `base64://` → base64；http(s) → url；本机路径 → path；其余视为平台不透明引用（file）。
+ */
+export declare function icqqMediaRefFromString(value: string): MediaRef;
+/**
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ ICQQ native
+ * element 的 file 参数。base64 使用 ICQQ 原生支持的 `base64://` 前缀。
+ */
+export declare function resolveIcqqMediaFile(data: Record<string, unknown> | undefined): string | undefined;
+export declare function parseCqMessage(raw: string): MessageSegment[];

package/lib/cq-message.js

@@ -0,0 +1,106 @@
+/** ICQQ 历史文本视图 → canonical MessageSegment。出站只使用原生 Sendable。 */
+import { isMediaRef } from "@zhin.js/core";
+const MAX_CQ_PARSE_LEN = 256_000;
+/**
+ * CQ 媒体参数 / 入站元素媒体值 → canonical MediaRef：
+ * `base64://` → base64；http(s) → url；本机路径 → path；其余视为平台不透明引用（file）。
+ */
+export function icqqMediaRefFromString(value) {
+    if (value.startsWith("base64://")) {
+        return { kind: "base64", value: value.slice("base64://".length) };
+    }
+    if (value.startsWith("http://") || value.startsWith("https://")) {
+        return { kind: "url", value };
+    }
+    if (value.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(value)) {
+        return { kind: "path", value };
+    }
+    return { kind: "file", value };
+}
+/**
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ ICQQ native
+ * element 的 file 参数。base64 使用 ICQQ 原生支持的 `base64://` 前缀。
+ */
+export function resolveIcqqMediaFile(data) {
+    const media = data?.media;
+    if (!isMediaRef(media))
+        return undefined;
+    if (media.kind === "base64") {
+        return media.value.startsWith("base64://") ? media.value : `base64://${media.value}`;
+    }
+    return media.value;
+}
+function pushCqSegment(segments, type, arg) {
+    switch (type) {
+        case "face":
+            segments.push({ type: "face", data: { id: Number(arg) } });
+            break;
+        case "image":
+            segments.push({ type: "image", data: { media: icqqMediaRefFromString(arg) } });
+            break;
+        case "at":
+            if (arg === "all") {
+                segments.push({ type: "at", data: { qq: "all" } });
+            }
+            else {
+                segments.push({ type: "at", data: { qq: arg } });
+            }
+            break;
+        case "dice":
+            segments.push({ type: "dice", data: {} });
+            break;
+        case "rps":
+            segments.push({ type: "rps", data: {} });
+            break;
+        case "record":
+        case "audio":
+            segments.push({ type: "audio", data: { media: icqqMediaRefFromString(arg) } });
+            break;
+        case "video":
+            segments.push({ type: "video", data: { media: icqqMediaRefFromString(arg) } });
+            break;
+        case "reply":
+            segments.push({ type: "reply", data: { message_id: arg } });
+            break;
+        case "json":
+            segments.push({ type: "json", data: { text: arg } });
+            break;
+        default:
+            segments.push({ type, data: { text: `[${type}:${arg}]` } });
+            break;
+    }
+}
+export function parseCqMessage(raw) {
+    const text = raw.length > MAX_CQ_PARSE_LEN ? raw.slice(0, MAX_CQ_PARSE_LEN) : raw;
+    const segments = [];
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] !== "[") {
+            const next = text.indexOf("[", i);
+            const chunk = next === -1 ? text.slice(i) : text.slice(i, next);
+            if (chunk)
+                segments.push({ type: "text", data: { text: chunk } });
+            if (next === -1)
+                break;
+            i = next;
+            continue;
+        }
+        const close = text.indexOf("]", i + 1);
+        if (close === -1) {
+            segments.push({ type: "text", data: { text: text.slice(i) } });
+            break;
+        }
+        const inner = text.slice(i + 1, close);
+        const colon = inner.indexOf(":");
+        const type = (colon === -1 ? inner : inner.slice(0, colon)).trim().toLowerCase();
+        const arg = colon === -1 ? "" : inner.slice(colon + 1);
+        if (/^[a-z_]+$/.test(type)) {
+            pushCqSegment(segments, type, arg);
+        }
+        else {
+            segments.push({ type: "text", data: { text: text.slice(i, close + 1) } });
+        }
+        i = close + 1;
+    }
+    return segments.length ? segments : [{ type: "text", data: { text: raw } }];
+}

package/lib/endpoint.d.ts

@@ -0,0 +1,31 @@
+import { Client } from '@icqqjs/icqq';
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import type { EndpointContentPort } from '@zhin.js/adapter';
+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 config: ResolvedIcqqConfig;
+    readonly loginAssist: LoginAssist;
+}
+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;
+    readonly control: EndpointControl;
+    constructor(options: IcqqEndpointOptions);
+    start(signal: AbortSignal): Promise<void>;
+    open(): void;
+    close(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    admit(msg: IcqqInboundMessage): Promise<void>;
+}
+export {};