@zhin.js/adapter-icqq 6.0.1 → 6.0.3

package/src/forward-msg.ts

@@ -1,8 +1,8 @@
 /**
  * 合并转发（聊天记录）解析：从 json/xml 提取 resid，经 IPC get_forward_msg 拉取正文。
  */
-import type { MessageSegment, QuotedMessagePayload } from "zhin.js";
-import { segment } from "zhin.js";
+import { segment, type MessageSegment, type QuotedMessagePayload } from 'zhin.js';
+
 import { Actions } from "./protocol.js";
 import type { IpcClient } from "./ipc-client.js";
 import {

package/src/icqq-agent-deps.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent tool deps for icqq.
+ * Endpoints register themselves on start; tools look up by config name / QQ uin.
+ */
+
+import type { IpcClient } from './ipc-client.js';
+import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+import type { IpcResponse } from './protocol.js';
+
+export interface IcqqAgentEndpoint {
+  readonly name: string;
+  readonly ipc: {
+    request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
+  };
+  readonly friends: Map<number, IpcFriendInfo>;
+  readonly groups: Map<number, IpcGroupInfo>;
+  request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
+}
+
+export interface IcqqAgentDeps {
+  getEndpoint: (endpointId: string) => IcqqAgentEndpoint;
+  getAdapter?: () => { getEndpoint: (id: string) => IcqqAgentEndpoint };
+}
+
+const endpoints = new Map<string, IcqqAgentEndpoint>();
+let override: IcqqAgentDeps | null = null;
+
+export function registerIcqqAgentEndpoint(
+  endpointId: string,
+  endpoint: IcqqAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
+
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setIcqqAgentDeps(deps: IcqqAgentDeps | null): void {
+  override = deps;
+}
+
+function lookup(endpointId: string): IcqqAgentEndpoint {
+  const registered = endpoints.get(endpointId);
+  if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+  return registered;
+}
+
+export function getIcqqAgentDeps(): IcqqAgentDeps {
+  if (override) return override;
+  return {
+    getEndpoint: lookup,
+    getAdapter: () => ({ getEndpoint: lookup }),
+  };
+}

package/src/icqq-guild.ts

@@ -1,11 +1,10 @@
 /**
  * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
  */
-import type { MessageSegment } from "zhin.js";
+import { toCanonicalSegments, type MessageSegment } from "zhin.js";
 import { Actions, type IpcGuildMessageEventData } from "./protocol.js";
 import type { IpcClient } from "./ipc-client.js";
 import { parseCqMessage } from "./cq-message.js";
-import { toCanonicalSegments } from "./segment-mapper.js";
 
 export interface IcqqGuildChannelEntry {
   channel_id: string;

package/src/icqq-inbound.ts

@@ -1,9 +1,8 @@
 /**
  * icqq 守护进程 IPC 入站事件归一化（post_type / message_type / message 段）
  */
-import { Message, type MessageSegment, type QuotedMessagePayload } from "zhin.js";
+import { Message, toCanonicalSegments, type MessageSegment, type QuotedMessagePayload } from "zhin.js";
 import { parseCqMessage } from "./cq-message.js";
-import { toCanonicalSegments } from "./segment-mapper.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 import type { GroupRole } from "./types.js";
 
@@ -110,6 +109,36 @@ export function parseIcqqSenderGroupRole(
   return ICQQ_GROUP_ROLES.has(role) ? role : undefined;
 }
 
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export function isIcqqBotMentioned(input: {
+  readonly uin: string;
+  readonly content?: readonly MessageSegment[] | null;
+  readonly rawMessage?: string;
+}): boolean {
+  const uin = String(input.uin ?? "").trim();
+  if (!uin) return false;
+  for (const seg of input.content ?? []) {
+    if (!seg || (seg.type !== "at" && seg.type !== "mention")) continue;
+    const data = (seg.data ?? {}) as Record<string, unknown>;
+    const target = String(
+      data.qq ?? data.user_id ?? data.id ?? data.target ?? "",
+    ).trim();
+    if (target && target !== "all" && Number(target) === Number(uin)) {
+      return true;
+    }
+  }
+  const raw = input.rawMessage ?? "";
+  if (!raw) return false;
+  const escaped = uin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // OneBot CQ 码 `[CQ:at,qq=uin]`；QQ 频道 markdown `<@!uin>`
+  return new RegExp(`\\[CQ:at,qq=${escaped}\\]`, "u").test(raw)
+    || new RegExp(`<@!?${escaped}>`, "u").test(raw);
+}
+
 const MESSAGE_POST_TYPES = new Set(["message"]);
 
 function isMessagePostType(postType: unknown): boolean {

package/src/index.ts

@@ -1,73 +1,39 @@
-/**
- * ICQQ 适配器入口：类型扩展、导出、注册
- */
-import path from "path";
-import {
-  usePlugin,
-  type Plugin,
-  type ToolFeature,
-} from "zhin.js";
-import { registerAgentPromptContributor, unregisterAgentPromptContributor } from "zhin.js/agent";
-import { createIcqqAgentPromptContributor } from "./agent-prompt.js";
-import type { Router } from "@zhin.js/host-router";
-import { PageManager } from "@zhin.js/host-api";
-import { IcqqAdapter } from "./adapter.js";
-import { registerTools } from "./tools/index.js";
-import { registerRoutes } from "./routes.js";
-import { registerLoginAssistRoutes } from "./login-assist-routes.js";
+export {
+  Actions,
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundBody,
+  parseSendTarget,
+  resolveIcqqConfig,
+  type IcqqAdapterConfig,
+  type IcqqInboundMessage,
+  type IcqqWireSegment,
+  type IpcEvent,
+  type IpcMessage,
+  type IpcRequest,
+  type IpcResponse,
+  type ParsedIcqqSendTarget,
+  type ResolvedIcqqConfig,
+} from './protocol.js';
 
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-      router: Router;
-    }
-  }
-  interface Adapters {
-    icqq: IcqqAdapter;
-  }
-}
+export {
+  IcqqIpcEndpoint,
+  type CreateIcqqIpc,
+  type IcqqEndpointOptions,
+  type IcqqIpcTransport,
+} from './endpoint.js';
 
-export * from "./types.js";
-export { IcqqEndpoint } from "./endpoint.js";
-export { IcqqAdapter } from "./adapter.js";
+export * from './types.js';
 
-const plugin = usePlugin();
-const { provide, useContext, addCommand, root } = plugin;
+export {
+  getIcqqAgentDeps,
+  registerIcqqAgentEndpoint,
+  setIcqqAgentDeps,
+  type IcqqAgentDeps,
+  type IcqqAgentEndpoint,
+} from './icqq-agent-deps.js';
 
-// ── 适配器注册 ─────────────────────────────────────────────────────
-provide({
-  name: "icqq",
-  description: "ICQQ Adapter",
-  mounted: async (p: Plugin) => {
-    registerAgentPromptContributor(createIcqqAgentPromptContributor());
-    const adapter = new IcqqAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: IcqqAdapter) => {
-    unregisterAgentPromptContributor("icqq");
-    await adapter.stop();
-  },
-} as any);
-
-// ── AI 工具注册 ────────────────────────────────────────────────────
-useContext("tool", "icqq", (toolService: ToolFeature, icqq: IcqqAdapter) => {
-  return registerTools(toolService, icqq, plugin.name);
-});
-
-// ── Web 控制台入口 ─────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "icqq",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "ICQQ" },
-  });
-});
-
-// ── HTTP 路由 ──────────────────────────────────────────────────────
-useContext("router", "icqq", async (router: Router, icqq: IcqqAdapter) => {
-  registerRoutes(router, icqq, root);
-  registerLoginAssistRoutes(router, root);
-});
+export { IpcClient } from './ipc-client.js';
+export {
+  resolveIcqqInboundMessageId,
+} from './icqq-inbound.js';

package/src/protocol.ts

@@ -9,9 +9,11 @@
  * 2. 认证通过后发送 IpcRequest → 等待 IpcResponse
  * 3. 认证通过后自动接收 icqq 事件推送（IpcEvent），断开连接自动停止
  *
- * 登录相关：**推送**走 IpcEvent（`system.login.*`），续传 invoke 见 `login-ipc-contract.ts`。
+ * 登录相关：**推送**走 IpcEvent（`system.login.*`）。
  */
 
+import { pickCredential } from '@zhin.js/adapter';
+
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
   id: string;
@@ -265,3 +267,191 @@ export const Actions = {
   SET_NOTIFY: "set_notify",
   GET_NOTIFY: "get_notify",
 } as const;
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface IcqqAdapterConfig {
+  readonly name?: string;
+  readonly autoReconnect?: boolean;
+  readonly outboundMedia?: 'file' | 'base64';
+  readonly rpc?: {
+    readonly host?: string;
+    readonly port?: number;
+    readonly token?: string;
+  };
+  /** Transitional: legacy root `endpoints[]` with `context: icqq`. */
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly name?: string;
+    readonly autoReconnect?: boolean;
+    readonly outboundMedia?: 'file' | 'base64';
+    readonly rpc?: {
+      readonly host?: string;
+      readonly port?: number;
+      readonly token?: string;
+    };
+  }>;
+}
+
+export interface ResolvedIcqqConfig {
+  readonly context: 'icqq';
+  readonly name: string;
+  readonly autoReconnect: boolean;
+  readonly outboundMedia?: 'file' | 'base64';
+  readonly rpc?: {
+    readonly host: string;
+    readonly port: number;
+    readonly token: string;
+  };
+}
+
+export interface IcqqWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface IcqqInboundMessage {
+  readonly id: string;
+  readonly target: string;
+  readonly content: string;
+  readonly sender: string;
+  readonly channelType: 'private' | 'group' | 'channel';
+  readonly metadata?: Record<string, unknown>;
+}
+
+export type ParsedIcqqSendTarget =
+  | { readonly kind: 'private'; readonly userId: number }
+  | { readonly kind: 'group'; readonly groupId: number }
+  | { readonly kind: 'temp'; readonly groupId: number; readonly userId: number }
+  | { readonly kind: 'channel'; readonly guildId: string; readonly channelId: string };
+
+export function resolveIcqqConfig(config: IcqqAdapterConfig = {}): ResolvedIcqqConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'icqq');
+  const name = pickCredential(config.name, entry?.name, process.env.ICQQ_ACCOUNT);
+  if (!/^\d+$/.test(name)) {
+    throw new TypeError(
+      'ICQQ adapter requires numeric name (QQ uin) via plugins.<key>.name or ICQQ_ACCOUNT',
+    );
+  }
+  const autoReconnect = config.autoReconnect ?? entry?.autoReconnect ?? true;
+  const outboundMedia = config.outboundMedia ?? entry?.outboundMedia;
+  const rpcRaw = config.rpc ?? entry?.rpc;
+  const rpc = rpcRaw?.host && rpcRaw.port != null && rpcRaw.token
+    ? { host: rpcRaw.host, port: Number(rpcRaw.port), token: rpcRaw.token }
+    : undefined;
+  return {
+    context: 'icqq',
+    name,
+    autoReconnect,
+    ...(outboundMedia ? { outboundMedia } : {}),
+    ...(rpc ? { rpc } : {}),
+  };
+}
+
+/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
+export function formatInboundTarget(input: {
+  readonly channelType: 'private' | 'group' | 'channel';
+  readonly channelId: string;
+  readonly channelParentGroupId?: string;
+  readonly guildId?: string;
+}): string {
+  if (input.channelType === 'private' && input.channelParentGroupId) {
+    return `temp:${input.channelParentGroupId}:${input.channelId}`;
+  }
+  if (input.channelType === 'channel' && input.guildId) {
+    return `channel:${input.guildId}:${input.channelId}`;
+  }
+  return `${input.channelType}:${input.channelId}`;
+}
+
+export function parseSendTarget(target: string): ParsedIcqqSendTarget {
+  const trimmed = target.trim();
+  if (trimmed.startsWith('temp:')) {
+    const rest = trimmed.slice(5);
+    const [groupId, userId] = rest.split(':');
+    if (!groupId || !userId) throw new TypeError(`Invalid icqq temp target: ${target}`);
+    return { kind: 'temp', groupId: Number(groupId), userId: Number(userId) };
+  }
+  if (trimmed.startsWith('channel:')) {
+    const rest = trimmed.slice(8);
+    const idx = rest.indexOf(':');
+    if (idx <= 0) throw new TypeError(`Invalid icqq channel target: ${target}`);
+    return {
+      kind: 'channel',
+      guildId: rest.slice(0, idx),
+      channelId: rest.slice(idx + 1),
+    };
+  }
+  if (trimmed.startsWith('private:')) {
+    return { kind: 'private', userId: Number(trimmed.slice(8)) };
+  }
+  if (trimmed.startsWith('group:')) {
+    return { kind: 'group', groupId: Number(trimmed.slice(6)) };
+  }
+  // Bare numeric id → private (common reply path)
+  if (/^\d+$/.test(trimmed)) {
+    return { kind: 'private', userId: Number(trimmed) };
+  }
+  throw new TypeError(`Invalid icqq send target: ${target}`);
+}
+
+export function formatOutboundBody(payload: unknown): string {
+  if (typeof payload === 'string') {
+    const text = payload.trim();
+    return text || '\u200b';
+  }
+  if (payload == null) return '\u200b';
+  if (!Array.isArray(payload)) {
+    // 单个段对象（非数组）按单元素数组处理，杜绝 String(object) → '[object Object]'
+    if (isWireSegment(payload)) {
+      return formatOutboundBody([payload]);
+    }
+    if (typeof payload === 'object' && payload !== null && 'text' in payload) {
+      const text = String((payload as { text?: unknown }).text ?? '').trim();
+      return text || '\u200b';
+    }
+    const text = String(payload).trim();
+    return text || '\u200b';
+  }
+  const joined = payload.map((seg) => {
+    if (typeof seg === 'string') return seg;
+    const item = seg as IcqqWireSegment;
+    switch (item.type) {
+      case 'text':
+        return String(item.data?.text ?? '');
+      case 'at':
+      case 'mention':
+        return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
+      case 'image':
+        return `[image:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+      case 'face':
+        return `[face:${item.data?.id ?? ''}]`;
+      case 'reply':
+        return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
+      case 'record':
+      case 'audio':
+        return `[record:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+      case 'video':
+        return `[video:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+      default:
+        return String(item.data?.text ?? '');
+    }
+  }).join('').trim();
+  return joined || '\u200b';
+}
+
+export function formatInboundContent(rawMessage: string): string {
+  return rawMessage;
+}
+
+/** base64 媒体回退：CQ `base64://` 由守护进程解码（异机 RPC 场景）。 */
+function base64Media(data: Record<string, unknown> | undefined): string | undefined {
+  const b64 = data?.base64;
+  return typeof b64 === 'string' && b64 ? `base64://${b64}` : undefined;
+}
+
+/** 段对象判定：`{ type: string, data? }`（非数组 payload 的防御入口）。 */
+function isWireSegment(value: unknown): value is IcqqWireSegment {
+  return typeof value === 'object'
+    && value !== null
+    && typeof (value as { type?: unknown }).type === 'string';
+}

package/client/ICQQManagement.tsx

@@ -1,147 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-import { Activity, Bot, Endpoint, LogIn, Users, RefreshCw, Wifi, WifiOff, Loader2 } from "lucide-react";
-import LoginAssistPanel from "./LoginAssistPanel";
-import { apiFetch } from "./utils/api";
-
-interface EndpointRow {
-  name: string;
-  connected: boolean;
-  groupCount: number;
-  friendCount: number;
-  loginMode: string;
-  status: string;
-}
-
-type Tab = "overview" | "login";
-
-export default function ICQQManagement() {
-  const [tab, setTab] = useState<Tab>("overview");
-  const [endpoints, setEndpoints] = useState<EndpointRow[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [err, setErr] = useState<string | null>(null);
-
-  const loadBots = useCallback(async () => {
-    setLoading(true);
-    setErr(null);
-    try {
-      const res = await apiFetch("/api/icqq/endpoints");
-      const json = (await res.json()) as { success?: boolean; data?: EndpointRow[]; message?: string };
-      if (!res.ok || !json.success) throw new Error(json.message || "加载失败");
-      setEndpoints(Array.isArray(json.data) ? json.data : []);
-    } catch (e) {
-      setErr((e as Error).message);
-      setEndpoints([]);
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    if (tab === "overview") void loadBots();
-  }, [tab, loadBots]);
-
-  return (
-    <div className="p-6 max-w-5xl mx-auto space-y-5">
-      {/* Header */}
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold flex items-center gap-2">
-            <Bot className="w-6 h-6" /> ICQQ 管理
-          </h1>
-          <p className="text-sm text-muted-foreground mt-1">
-            机器人概览与登录辅助（扫码 / 验证码 / 滑块）
-          </p>
-        </div>
-        {tab === "overview" && (
-          <button
-            onClick={loadBots}
-            disabled={loading}
-            className="flex items-center gap-1 px-3 py-1.5 rounded bg-blue-500 text-white hover:bg-blue-600 disabled:opacity-50 text-sm"
-          >
-            <RefreshCw className={`w-4 h-4 ${loading ? "animate-spin" : ""}`} /> 刷新
-          </button>
-        )}
-      </div>
-
-      {/* Tabs */}
-      <div className="flex gap-1 border-b">
-        <button
-          onClick={() => setTab("overview")}
-          className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${
-            tab === "overview"
-              ? "border-blue-500 text-blue-600"
-              : "border-transparent text-gray-500 hover:text-gray-700"
-          }`}
-        >
-          <span className="flex items-center gap-1.5">
-            <Bot className="w-4 h-4" /> 概览
-          </span>
-        </button>
-        <button
-          onClick={() => setTab("login")}
-          className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${
-            tab === "login"
-              ? "border-blue-500 text-blue-600"
-              : "border-transparent text-gray-500 hover:text-gray-700"
-          }`}
-        >
-          <span className="flex items-center gap-1.5">
-            <LogIn className="w-4 h-4" /> 登录辅助
-          </span>
-        </button>
-      </div>
-
-      {/* Overview Tab */}
-      {tab === "overview" && (
-        <>
-          {err && (
-            <div className="p-3 bg-red-50 text-red-600 rounded border border-red-200 text-sm dark:bg-red-900/20 dark:text-red-400 dark:border-red-800">
-              {err}
-            </div>
-          )}
-          {loading ? (
-            <div className="flex justify-center py-12">
-              <Loader2 className="w-6 h-6 animate-spin text-blue-500" />
-            </div>
-          ) : endpoints.length === 0 ? (
-            <div className="text-center text-muted-foreground py-12">
-              暂无 ICQQ Endpoint 实例
-            </div>
-          ) : (
-            <div className="grid gap-4 md:grid-cols-2">
-              {endpoints.map((endpoint) => (
-                <div key={endpoint.name} className="border rounded-lg p-4 bg-card shadow-sm">
-                  <div className="flex items-center justify-between mb-3">
-                    <span className="font-medium text-lg">{endpoint.name}</span>
-                    {endpoint.connected ? (
-                      <span className="flex items-center gap-1 text-green-600 text-sm">
-                        <Wifi className="w-4 h-4" /> 在线
-                      </span>
-                    ) : (
-                      <span className="flex items-center gap-1 text-gray-400 text-sm">
-                        <WifiOff className="w-4 h-4" /> 离线
-                      </span>
-                    )}
-                  </div>
-                  <div className="space-y-2 text-sm text-muted-foreground">
-                    <div className="flex items-center gap-1.5">
-                      <Users className="w-3.5 h-3.5" />
-                      群 {endpoint.groupCount} · 好友 {endpoint.friendCount}
-                    </div>
-                    <div className="flex items-center gap-1.5">
-                      <Activity className="w-3.5 h-3.5" />
-                      登录方式 {endpoint.loginMode} · {endpoint.status}
-                    </div>
-                  </div>
-                </div>
-              ))}
-            </div>
-          )}
-        </>
-      )}
-
-      {/* Login Tab */}
-      {tab === "login" && <LoginAssistPanel />}
-    </div>
-  );
-}