@zhin.js/adapter-weixin-ilink 1.0.1 → 1.1.2

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zhin.js/adapter-weixin-ilink",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "type": "module",
-  "description": "Zhin.js adapter for WeChat personal account via Tencent iLink Endpoint API (ClawBot)",
+  "description": "Zhin.js Weixin iLink (ClawBot) adapter for Plugin Runtime (long-poll)",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "keywords": [
@@ -27,11 +27,12 @@
     "directory": "plugins/adapters/weixin-ilink"
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -46,50 +47,58 @@
       "import": "./lib/index.js"
     }
   },
-  "dependencies": {},
-  "devDependencies": {
-    "@radix-ui/themes": "^3.2.1",
-    "@types/react": "^19.2.15",
-    "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.17.0",
-    "radix-ui": "^1.5.0",
-    "typescript": "^6.0.3",
-    "@zhin.js/agent": "0.2.1",
-    "@zhin.js/cli": "1.0.89",
-    "@zhin.js/client": "2.0.3",
-    "@zhin.js/contract": "1.0.1",
-    "@zhin.js/core": "1.2.1",
-    "@zhin.js/host-api": "1.0.1",
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/agent": "0.2.1",
-    "@zhin.js/contract": "1.0.1",
-    "@zhin.js/client": "2.0.3",
-    "@zhin.js/core": "1.2.1",
-    "@zhin.js/host-router": "1.0.1",
-    "@zhin.js/host-api": "1.0.1",
-    "zhin.js": "2.0.1"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
-      "optional": true
-    },
-    "@zhin.js/client": {
-      "optional": true
-    },
-    "@zhin.js/host-api": {
+    "@zhin.js/command": {
       "optional": true
     },
-    "@zhin.js/host-router": {
+    "zhin.js": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zhin.js": "1.1.2"
+  },
   "ilink_appid": "bot",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "build:node": "tsc",
-    "clean": "rimraf lib dist"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/weixin-ilink/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { weixinIlinkRuntimeStateToken } from "./lib/weixin-ilink-runtime-state.js";
+export default definePlugin({
+    name: 'weixin-ilink',
+    metadata: {
+        displayName: 'Weixin iLink Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（weixin-ilink endpoint list 的"运行中"数据源）
+        context.resources.provide(weixinIlinkRuntimeStateToken, createEndpointRuntimeState());
+    },
+});

package/schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "botAgent": {
+      "type": "string"
+    },
+    "baseUrl": {
+      "type": "string",
+      "default": "https://ilinkai.weixin.qq.com"
+    },
+    "cdnBaseUrl": {
+      "type": "string",
+      "default": "https://novac2c.cdn.weixin.qq.com/c2c"
+    },
+    "longPollTimeoutMs": {
+      "type": "number",
+      "default": 35000
+    },
+    "dataDir": {
+      "type": "string",
+      "minLength": 1,
+      "default": "data/weixin-ilink",
+      "description": "Endpoint state root for credentials, cursors, context tokens, and media"
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（Weixin user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted Weixin user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（Weixin user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted Weixin user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "botToken": {
+            "type": "string",
+            "description": "iLink bot token; omit to load endpoint state or start QR login"
+          },
+          "id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]+$",
+            "description": "Weixin iLink bot name"
+          },
+          "botAgent": {
+            "type": "string"
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "cdnBaseUrl": {
+            "type": "string"
+          },
+          "longPollTimeoutMs": {
+            "type": "number"
+          },
+          "dataDir": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Endpoint state root"
+          },
+          "commandPrefix": {
+            "type": "string",
+            "description": "本 endpoint 的命令前缀"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,117 @@
+import type { WeixinContextTokenStore } from './context-store.js';
+import type { WeixinIlinkCredentials } from './credentials.js';
+import { sendTyping } from './ilink-api.js';
+import type { WeixinConfigManager } from './ilink-config-cache.js';
+import type { IlinkClientMetadata } from './ilink-meta.js';
+import type { ResolvedWeixinIlinkConfig } from './protocol.js';
+import { sendMessageWeixin } from './weixin-send.js';
+import { sendWeixinMediaFile } from './weixin-send-media.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+/** Direct iLink API client backed by the Endpoint's live authenticated session. */
+export class WeixinIlinkClient {
+  readonly config: ResolvedWeixinIlinkConfig;
+  readonly #metadata: IlinkClientMetadata;
+  readonly #resolveCredentials: () => WeixinIlinkCredentials | null;
+  readonly #resolveConfigManager: () => WeixinConfigManager | undefined;
+  readonly #sendTextImpl: typeof sendMessageWeixin;
+  readonly #contextTokens: WeixinContextTokenStore;
+
+  constructor(
+    config: ResolvedWeixinIlinkConfig,
+    metadata: IlinkClientMetadata,
+    resolveCredentials: () => WeixinIlinkCredentials | null,
+    resolveConfigManager: () => WeixinConfigManager | undefined,
+    sendTextImpl: typeof sendMessageWeixin,
+    contextTokens: WeixinContextTokenStore,
+  ) {
+    this.config = config;
+    this.#metadata = metadata;
+    this.#resolveCredentials = resolveCredentials;
+    this.#resolveConfigManager = resolveConfigManager;
+    this.#sendTextImpl = sendTextImpl;
+    this.#contextTokens = contextTokens;
+  }
+
+  get credentials(): WeixinIlinkCredentials {
+    const credentials = this.#resolveCredentials();
+    if (!credentials?.botToken) throw new Error('weixin-ilink client not authenticated');
+    return credentials;
+  }
+
+  get authenticated(): boolean {
+    return Boolean(this.#resolveCredentials()?.botToken);
+  }
+
+  get apiBaseUrl(): string {
+    return this.#resolveCredentials()?.baseUrl ?? this.config.baseUrl;
+  }
+
+  get cdnBaseUrl(): string {
+    return this.config.cdnBaseUrl;
+  }
+
+  contextToken(userId: string): string | undefined {
+    return this.#contextTokens.get(userId);
+  }
+
+  reachableUserIds(): string[] {
+    return this.#contextTokens.userIds();
+  }
+
+  async sendText(to: string, text: string): Promise<{ messageId: string }> {
+    const contextToken = this.contextToken(to);
+    if (!contextToken) throw new Error(`missing context_token for peer ${to}`);
+    return this.#sendTextImpl({
+      to,
+      text,
+      opts: {
+        baseUrl: this.apiBaseUrl,
+        metadata: this.#metadata,
+        token: this.credentials.botToken,
+        contextToken,
+      },
+    });
+  }
+
+  async sendMedia(to: string, filePath: string, text = ''): Promise<{ messageId: string }> {
+    const contextToken = this.contextToken(to);
+    if (!contextToken) throw new Error(`missing context_token for peer ${to}`);
+    return sendWeixinMediaFile({
+      filePath,
+      to,
+      text,
+      opts: {
+        baseUrl: this.apiBaseUrl,
+        metadata: this.#metadata,
+        token: this.credentials.botToken,
+        contextToken,
+      },
+      cdnBaseUrl: this.cdnBaseUrl,
+    });
+  }
+
+  async sendTyping(userId: string, status: number): Promise<boolean> {
+    const manager = this.#resolveConfigManager();
+    if (!this.authenticated || !manager) return false;
+    const cfg = await manager.getForUser(userId, this.contextToken(userId));
+    if (!cfg.typingTicket) return false;
+    await sendTyping({
+      baseUrl: this.apiBaseUrl,
+      metadata: this.#metadata,
+      token: this.credentials.botToken,
+      body: { ilink_user_id: userId, typing_ticket: cfg.typingTicket, status },
+    });
+    return true;
+  }
+}
+
+export type WeixinIlinkClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly 'weixin-ilink': { readonly client: WeixinIlinkClient; readonly events: WeixinIlinkClientEventMap };
+  }
+}
+
+export const weixinIlinkClient = defineEndpointClient<WeixinIlinkClient, WeixinIlinkClientEventMap>('weixin-ilink');

package/src/context-store.ts

@@ -1,8 +1,101 @@
-export {
-  setContextToken,
-  getContextToken,
-  restoreContextTokens,
-  clearContextTokensForAccount,
-  bodyFromItemList,
-  isMediaItem,
-} from "./weixin-inbound.js";
+import fs from 'node:fs';
+import path from 'node:path';
+import type { WeixinIlinkStateStore } from './credentials.js';
+import { logger } from './ilink-logger.js';
+
+const PERSIST_DEBOUNCE_MS = 500;
+
+/** Endpoint-owned context-token repository with account-scoped persistence. */
+export class WeixinContextTokenStore {
+  readonly state: WeixinIlinkStateStore;
+  readonly #tokens = new Map<string, string>();
+  #persistTimer?: ReturnType<typeof setTimeout>;
+
+  constructor(state: WeixinIlinkStateStore) {
+    this.state = state;
+  }
+
+  get accountId(): string {
+    return this.state.endpointId;
+  }
+
+  get(userId: string): string | undefined {
+    const value = this.#tokens.get(userId);
+    logger.debug(`contextTokenStore.get: account=${this.accountId} user=${userId} found=${value !== undefined} storeSize=${this.#tokens.size}`);
+    return value;
+  }
+
+  set(userId: string, token: string): void {
+    logger.debug(`contextTokenStore.set: account=${this.accountId} user=${userId}`);
+    this.#tokens.set(userId, token);
+    this.#schedulePersist();
+  }
+
+  userIds(): string[] {
+    return [...this.#tokens.keys()];
+  }
+
+  restore(): void {
+    const filePath = this.#filePath();
+    try {
+      if (!fs.existsSync(filePath)) return;
+      const tokens = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as Record<string, unknown>;
+      let count = 0;
+      for (const [userId, token] of Object.entries(tokens)) {
+        if (typeof token !== 'string' || !token) continue;
+        this.#tokens.set(userId, token);
+        count += 1;
+      }
+      logger.info(`contextTokenStore.restore: restored ${count} tokens for account=${this.accountId}`);
+    } catch (error) {
+      logger.warn(`contextTokenStore.restore: failed to read ${filePath}: ${String(error)}`);
+    }
+  }
+
+  flush(): void {
+    if (this.#persistTimer) {
+      clearTimeout(this.#persistTimer);
+      this.#persistTimer = undefined;
+    }
+    this.#persist();
+  }
+
+  clear(): void {
+    if (this.#persistTimer) {
+      clearTimeout(this.#persistTimer);
+      this.#persistTimer = undefined;
+    }
+    this.#tokens.clear();
+    const filePath = this.#filePath();
+    try {
+      if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+    } catch (error) {
+      logger.warn(`contextTokenStore.clear: failed to remove ${filePath}: ${String(error)}`);
+    }
+  }
+
+  #filePath(): string {
+    return this.state.contextTokensPath();
+  }
+
+  #schedulePersist(): void {
+    if (this.#persistTimer) clearTimeout(this.#persistTimer);
+    this.#persistTimer = setTimeout(() => {
+      this.#persistTimer = undefined;
+      this.#persist();
+    }, PERSIST_DEBOUNCE_MS);
+    this.#persistTimer.unref?.();
+  }
+
+  #persist(): void {
+    const filePath = this.#filePath();
+    try {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(Object.fromEntries(this.#tokens)), 'utf-8');
+    } catch (error) {
+      logger.warn(`contextTokenStore.persist: failed to write ${filePath}: ${String(error)}`);
+    }
+  }
+}
+
+export { bodyFromItemList, isMediaItem } from './weixin-inbound.js';

package/src/credentials.ts

@@ -1,5 +1,5 @@
-import fs from "node:fs";
-import path from "node:path";
+import fs from 'node:fs';
+import path from 'node:path';
 
 export interface WeixinIlinkCredentials {
   botToken: string;
@@ -9,56 +9,79 @@ export interface WeixinIlinkCredentials {
   updatedAt?: string;
 }
 
-const DEFAULT_DATA_DIR = "./data/weixin-ilink";
+/** Endpoint-owned persistence for credentials, cursors, context tokens, and media. */
+export class WeixinIlinkStateStore {
+  readonly endpointId: string;
+  readonly rootDir: string;
 
-export function resolveStateDir(): string {
-  return process.env.ZHIN_DATA_DIR
-    ? path.join(process.env.ZHIN_DATA_DIR, "weixin-ilink")
-    : DEFAULT_DATA_DIR;
-}
+  constructor(
+    endpointId: string,
+    rootDir: string,
+  ) {
+    if (!/^[A-Za-z0-9_.-]+$/u.test(endpointId)) {
+      throw new TypeError('Weixin iLink state endpoint id is invalid');
+    }
+    if (!rootDir.trim()) throw new TypeError('Weixin iLink state root is required');
+    this.endpointId = endpointId;
+    this.rootDir = rootDir;
+  }
 
-export function credentialsPath(endpointName: string): string {
-  return path.join(resolveStateDir(), `${endpointName}.json`);
-}
+  endpointDirectory(): string {
+    return path.join(this.rootDir, this.endpointId);
+  }
 
-export function loadCredentials(endpointName: string): WeixinIlinkCredentials | null {
-  const file = credentialsPath(endpointName);
-  try {
-    if (!fs.existsSync(file)) return null;
-    const raw = fs.readFileSync(file, "utf-8");
-    const data = JSON.parse(raw) as WeixinIlinkCredentials;
-    if (!data.botToken?.trim()) return null;
-    return data;
-  } catch {
-    return null;
+  credentialsPath(): string {
+    return path.join(this.endpointDirectory(), 'credentials.json');
   }
-}
 
-export function saveCredentials(endpointName: string, creds: WeixinIlinkCredentials): void {
-  const file = credentialsPath(endpointName);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(
-    file,
-    JSON.stringify({ ...creds, updatedAt: new Date().toISOString() }, null, 2),
-    "utf-8",
-  );
-}
+  loadCredentials(): WeixinIlinkCredentials | null {
+    const file = this.credentialsPath();
+    try {
+      if (!fs.existsSync(file)) return null;
+      const data = JSON.parse(fs.readFileSync(file, 'utf-8')) as WeixinIlinkCredentials;
+      return data.botToken?.trim() ? data : null;
+    } catch {
+      return null;
+    }
+  }
 
-export function syncBufPath(endpointName: string): string {
-  return path.join(resolveStateDir(), `${endpointName}.sync-buf`);
-}
+  saveCredentials(credentials: WeixinIlinkCredentials): void {
+    const file = this.credentialsPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      file,
+      JSON.stringify({ ...credentials, updatedAt: new Date().toISOString() }, null, 2),
+      'utf-8',
+    );
+  }
 
-export function loadSyncBuf(endpointName: string): string {
-  const file = syncBufPath(endpointName);
-  try {
-    return fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
-  } catch {
-    return "";
+  syncBufPath(): string {
+    return path.join(this.endpointDirectory(), 'sync-buf');
+  }
+
+  loadSyncBuf(): string {
+    const file = this.syncBufPath();
+    try {
+      return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+    } catch {
+      return '';
+    }
+  }
+
+  saveSyncBuf(value: string): void {
+    const file = this.syncBufPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, value, 'utf-8');
+  }
+
+  contextTokensPath(): string {
+    return path.join(this.endpointDirectory(), 'context-tokens.json');
   }
-}
 
-export function saveSyncBuf(endpointName: string, buf: string): void {
-  const file = syncBufPath(endpointName);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buf, "utf-8");
+  mediaDirectory(subdir: string): string {
+    if (subdir !== 'inbound' && subdir !== 'outbound') {
+      throw new TypeError(`Unsupported Weixin iLink media directory: ${subdir}`);
+    }
+    return path.join(this.endpointDirectory(), 'media', subdir);
+  }
 }