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

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @zhin.js/adapter-weixin-ilink
 
+## 1.1.2
+
+### Patch Changes
+
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- f68f5dd: Move context tokens, persistence timers, and expired-session cooldowns into endpoint-owned classes. Multiple iLink endpoints no longer share mutable module state, and inbound token updates now produce one persistence side effect.
+- 9c81bf1: Require one canonical expanded Weixin iLink endpoint configuration and make each Endpoint own one account-scoped state directory for credentials, long-poll cursors, context tokens, and media. Remove nested endpoint and environment compatibility and add an explicit `dataDir` boundary.
+- 6582a00: Replace process-global iLink request metadata and logger mutation with immutable endpoint-owned request identity. Every login, polling, typing, upload, and send request now carries the owning endpoint's version and bot agent explicitly, preventing one endpoint from changing another endpoint's wire identity.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [9110ab8]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [73a24b7]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -28,25 +28,30 @@ plugins:
     # botAgent: "Zhin.js/1.0.0"
     # longPollTimeoutMs: 35000
     # baseUrl: https://ilinkai.weixin.qq.com
+    # dataDir: data/weixin-ilink
     endpoints:
-      - name: my-wechat
-        # botToken: "..."                 # 或环境变量 WEIXIN_ILINK_TOKEN
+      - id: my-wechat
+        # botToken: "..."                 # 可选；不填则读取状态文件或扫码
 ```
 
-`botToken` 也可保存在侧车文件（不进 git）：
+`AdapterIndex` 会把实例默认值与 endpoint 覆盖值合并后再调用 adapter。协议层只接受这份
+展开后的 endpoint 配置，不读取环境变量，也不再次解析嵌套 `endpoints`。
+
+Endpoint 通过一个 `WeixinIlinkStateStore` 统一拥有凭据、长轮询 cursor、context token 和媒体文件。
+`botToken` 也可保存在 `dataDir` 下的状态文件（不进 git）：
 
 ```
-data/weixin-ilink/<bot-name>.json
+data/weixin-ilink/<id>/credentials.json
 ```
 
 ## 登录流程
 
 1. 首次启动无凭证时，调用 `get_bot_qrcode` 并在日志中打印二维码内容
 2. 用户用微信扫码确认
-3. 后台轮询 `get_qrcode_status` 直至 `confirmed`，写入 `data/weixin-ilink/<name>.json`
+3. 后台轮询 `get_qrcode_status` 直至 `confirmed`，写入 `dataDir/<id>/credentials.json`
 4. 调用 `notifyStart` 后进入长轮询
 
-> Console 扫码面板（旧 `loginAssist` + host-router）已从生产路径移除；优先用 `botToken` / 侧车凭证。
+> Console 扫码面板（旧 `loginAssist` + host-router）已从生产路径移除；优先用 `botToken` / Endpoint 状态凭证。
 
 ## 出站说明
 

package/adapters/{weixin-ilink.js → weixin-ilink/index.js}

@@ -1,12 +1,12 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/weixin-ilink.ts` → defineAdapter.
+ * Convention entry: discover `adapters/weixin-ilink/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { WeixinIlinkEndpoint } from "../lib/endpoint.js";
-import { resolveWeixinIlinkConfig, } from "../lib/protocol.js";
-import { weixinIlinkRuntimeStateToken } from "../lib/weixin-ilink-runtime-state.js";
-export { WeixinIlinkEndpoint } from "../lib/endpoint.js";
+import { WeixinIlinkEndpoint } from "../../lib/endpoint.js";
+import { resolveWeixinIlinkConfig, } from "../../lib/protocol.js";
+import { weixinIlinkRuntimeStateToken } from "../../lib/weixin-ilink-runtime-state.js";
+export { WeixinIlinkEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['typing'],
@@ -18,7 +18,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveWeixinIlinkConfig(context.config);
-        // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（weixin-ilink endpoint list 的"运行中"数据源）
         context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             // iLink 仅长轮询一种接入方式，无 config.connection 字段

package/adapters/{weixin-ilink.ts → weixin-ilink/index.ts}

@@ -1,24 +1,24 @@
 /**
- * Convention entry: discover `adapters/weixin-ilink.ts` → defineAdapter.
+ * Convention entry: discover `adapters/weixin-ilink/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { WeixinIlinkEndpoint } from '../src/endpoint.js';
+import { WeixinIlinkEndpoint } from '../../src/endpoint.js';
 import {
   resolveWeixinIlinkConfig,
-  type WeixinIlinkAdapterConfig,
-} from '../src/protocol.js';
-import { weixinIlinkRuntimeStateToken } from '../src/weixin-ilink-runtime-state.js';
+  type WeixinIlinkEndpointConfig,
+} from '../../src/protocol.js';
+import { weixinIlinkRuntimeStateToken } from '../../src/weixin-ilink-runtime-state.js';
 
-export { WeixinIlinkEndpoint } from '../src/endpoint.js';
+export { WeixinIlinkEndpoint } from '../../src/endpoint.js';
 export type {
   WeixinIlinkEndpointOptions,
   WeixinIlinkGetUpdates,
   WeixinIlinkNotifyStart,
   WeixinIlinkNotifyStop,
   WeixinIlinkSendText,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 
-export default defineAdapter<WeixinIlinkAdapterConfig>({
+export default defineAdapter<WeixinIlinkEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['typing'],
   // 所有媒体（url 下载 / base64 落盘 / 本地 path）统一物化后走 CDN 上传（sendWeixinMediaFile），
@@ -29,7 +29,7 @@ export default defineAdapter<WeixinIlinkAdapterConfig>({
   },
   create(context) {
     const config = resolveWeixinIlinkConfig(context.config);
-    // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（weixin-ilink endpoint list 的"运行中"数据源）
     context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       // iLink 仅长轮询一种接入方式，无 config.connection 字段

package/commands/{endpoint/add/[id].js → weixin-ilink/endpoint/add/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { weixinIlinkEndpointCommands } from "../../../lib/weixin-ilink-endpoint-commands.js";
+import { weixinIlinkEndpointCommands } from '../../definition.js';
 export default weixinIlinkEndpointCommands.add;

package/commands/weixin-ilink/endpoint/add/[id]/index.ts

@@ -0,0 +1,3 @@
+import { weixinIlinkEndpointCommands } from '../../definition.js';
+
+export default weixinIlinkEndpointCommands.add;

package/{lib/weixin-ilink-endpoint-commands.js → commands/weixin-ilink/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `weixin-ilink.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `weixin-ilink endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/weixin-ilink/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { weixinIlinkRuntimeStateToken } from './weixin-ilink-runtime-state.js';
+import { weixinIlinkRuntimeStateToken } from "../../../lib/weixin-ilink-runtime-state.js";
 export const weixinIlinkEndpointCommands = createEndpointCommands({
     adapterKey: 'weixin-ilink',
     adapterDisplayName: 'Weixin iLink',

package/{src/weixin-ilink-endpoint-commands.ts → commands/weixin-ilink/endpoint/definition.ts}

@@ -1,10 +1,10 @@
 /**
- * `weixin-ilink.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `weixin-ilink endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/weixin-ilink/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { weixinIlinkRuntimeStateToken } from './weixin-ilink-runtime-state.js';
+import { weixinIlinkRuntimeStateToken } from '../../../src/weixin-ilink-runtime-state.js';
 
 export const weixinIlinkEndpointCommands = createEndpointCommands({
   adapterKey: 'weixin-ilink',

package/commands/{endpoint/list.js → weixin-ilink/endpoint/list/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { weixinIlinkEndpointCommands } from "../../lib/weixin-ilink-endpoint-commands.js";
+import { weixinIlinkEndpointCommands } from '../definition.js';
 export default weixinIlinkEndpointCommands.list;

package/commands/weixin-ilink/endpoint/list/index.ts

@@ -0,0 +1,3 @@
+import { weixinIlinkEndpointCommands } from '../definition.js';
+
+export default weixinIlinkEndpointCommands.list;

package/commands/{endpoint/remove/[id].js → weixin-ilink/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { weixinIlinkEndpointCommands } from "../../../lib/weixin-ilink-endpoint-commands.js";
+import { weixinIlinkEndpointCommands } from '../../definition.js';
 export default weixinIlinkEndpointCommands.remove;

package/commands/weixin-ilink/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { weixinIlinkEndpointCommands } from '../../definition.js';
+
+export default weixinIlinkEndpointCommands.remove;

package/lib/client.d.ts

@@ -1,19 +1,20 @@
+import type { WeixinContextTokenStore } from './context-store.js';
 import type { WeixinIlinkCredentials } from './credentials.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';
 /** Direct iLink API client backed by the Endpoint's live authenticated session. */
 export declare class WeixinIlinkClient {
+    #private;
     readonly config: ResolvedWeixinIlinkConfig;
-    private readonly resolveCredentials;
-    private readonly resolveConfigManager;
-    private readonly sendTextImpl;
-    constructor(config: ResolvedWeixinIlinkConfig, resolveCredentials: () => WeixinIlinkCredentials | null, resolveConfigManager: () => WeixinConfigManager | undefined, sendTextImpl: typeof sendMessageWeixin);
+    constructor(config: ResolvedWeixinIlinkConfig, metadata: IlinkClientMetadata, resolveCredentials: () => WeixinIlinkCredentials | null, resolveConfigManager: () => WeixinConfigManager | undefined, sendTextImpl: typeof sendMessageWeixin, contextTokens: WeixinContextTokenStore);
     get credentials(): WeixinIlinkCredentials;
     get authenticated(): boolean;
     get apiBaseUrl(): string;
     get cdnBaseUrl(): string;
     contextToken(userId: string): string | undefined;
+    reachableUserIds(): string[];
     sendText(to: string, text: string): Promise<{
         messageId: string;
     }>;

package/lib/client.js

@@ -1,45 +1,56 @@
-import { getContextToken } from './context-store.js';
 import { sendTyping } from './ilink-api.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 {
     config;
-    resolveCredentials;
-    resolveConfigManager;
-    sendTextImpl;
-    constructor(config, resolveCredentials, resolveConfigManager, sendTextImpl) {
+    #metadata;
+    #resolveCredentials;
+    #resolveConfigManager;
+    #sendTextImpl;
+    #contextTokens;
+    constructor(config, metadata, resolveCredentials, resolveConfigManager, sendTextImpl, contextTokens) {
         this.config = config;
-        this.resolveCredentials = resolveCredentials;
-        this.resolveConfigManager = resolveConfigManager;
-        this.sendTextImpl = sendTextImpl;
+        this.#metadata = metadata;
+        this.#resolveCredentials = resolveCredentials;
+        this.#resolveConfigManager = resolveConfigManager;
+        this.#sendTextImpl = sendTextImpl;
+        this.#contextTokens = contextTokens;
     }
     get credentials() {
-        const credentials = this.resolveCredentials();
+        const credentials = this.#resolveCredentials();
         if (!credentials?.botToken)
             throw new Error('weixin-ilink client not authenticated');
         return credentials;
     }
     get authenticated() {
-        return Boolean(this.resolveCredentials()?.botToken);
+        return Boolean(this.#resolveCredentials()?.botToken);
     }
     get apiBaseUrl() {
-        return this.resolveCredentials()?.baseUrl ?? this.config.baseUrl;
+        return this.#resolveCredentials()?.baseUrl ?? this.config.baseUrl;
     }
     get cdnBaseUrl() {
         return this.config.cdnBaseUrl;
     }
     contextToken(userId) {
-        return getContextToken(this.config.id, userId);
+        return this.#contextTokens.get(userId);
+    }
+    reachableUserIds() {
+        return this.#contextTokens.userIds();
     }
     async sendText(to, text) {
         const contextToken = this.contextToken(to);
         if (!contextToken)
             throw new Error(`missing context_token for peer ${to}`);
-        return this.sendTextImpl({
+        return this.#sendTextImpl({
             to,
             text,
-            opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+            opts: {
+                baseUrl: this.apiBaseUrl,
+                metadata: this.#metadata,
+                token: this.credentials.botToken,
+                contextToken,
+            },
         });
     }
     async sendMedia(to, filePath, text = '') {
@@ -50,12 +61,17 @@ export class WeixinIlinkClient {
             filePath,
             to,
             text,
-            opts: { baseUrl: this.apiBaseUrl, token: this.credentials.botToken, contextToken },
+            opts: {
+                baseUrl: this.apiBaseUrl,
+                metadata: this.#metadata,
+                token: this.credentials.botToken,
+                contextToken,
+            },
             cdnBaseUrl: this.cdnBaseUrl,
         });
     }
     async sendTyping(userId, status) {
-        const manager = this.resolveConfigManager();
+        const manager = this.#resolveConfigManager();
         if (!this.authenticated || !manager)
             return false;
         const cfg = await manager.getForUser(userId, this.contextToken(userId));
@@ -63,6 +79,7 @@ export class WeixinIlinkClient {
             return false;
         await sendTyping({
             baseUrl: this.apiBaseUrl,
+            metadata: this.#metadata,
             token: this.credentials.botToken,
             body: { ilink_user_id: userId, typing_ticket: cfg.typingTicket, status },
         });

package/lib/context-store.d.ts

@@ -1 +1,15 @@
-export { setContextToken, getContextToken, listContextTokenUserIds, restoreContextTokens, clearContextTokensForAccount, flushContextTokenPersist, bodyFromItemList, isMediaItem, } from "./weixin-inbound.js";
+import type { WeixinIlinkStateStore } from './credentials.js';
+/** Endpoint-owned context-token repository with account-scoped persistence. */
+export declare class WeixinContextTokenStore {
+    #private;
+    readonly state: WeixinIlinkStateStore;
+    constructor(state: WeixinIlinkStateStore);
+    get accountId(): string;
+    get(userId: string): string | undefined;
+    set(userId: string, token: string): void;
+    userIds(): string[];
+    restore(): void;
+    flush(): void;
+    clear(): void;
+}
+export { bodyFromItemList, isMediaItem } from './weixin-inbound.js';

package/lib/context-store.js

@@ -1 +1,93 @@
-export { setContextToken, getContextToken, listContextTokenUserIds, restoreContextTokens, clearContextTokensForAccount, flushContextTokenPersist, bodyFromItemList, isMediaItem, } from "./weixin-inbound.js";
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from './ilink-logger.js';
+const PERSIST_DEBOUNCE_MS = 500;
+/** Endpoint-owned context-token repository with account-scoped persistence. */
+export class WeixinContextTokenStore {
+    state;
+    #tokens = new Map();
+    #persistTimer;
+    constructor(state) {
+        this.state = state;
+    }
+    get accountId() {
+        return this.state.endpointId;
+    }
+    get(userId) {
+        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, token) {
+        logger.debug(`contextTokenStore.set: account=${this.accountId} user=${userId}`);
+        this.#tokens.set(userId, token);
+        this.#schedulePersist();
+    }
+    userIds() {
+        return [...this.#tokens.keys()];
+    }
+    restore() {
+        const filePath = this.#filePath();
+        try {
+            if (!fs.existsSync(filePath))
+                return;
+            const tokens = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            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() {
+        if (this.#persistTimer) {
+            clearTimeout(this.#persistTimer);
+            this.#persistTimer = undefined;
+        }
+        this.#persist();
+    }
+    clear() {
+        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() {
+        return this.state.contextTokensPath();
+    }
+    #schedulePersist() {
+        if (this.#persistTimer)
+            clearTimeout(this.#persistTimer);
+        this.#persistTimer = setTimeout(() => {
+            this.#persistTimer = undefined;
+            this.#persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.#persistTimer.unref?.();
+    }
+    #persist() {
+        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/lib/credentials.d.ts

@@ -5,10 +5,18 @@ export interface WeixinIlinkCredentials {
     baseUrl?: string;
     updatedAt?: string;
 }
-export declare function resolveStateDir(): string;
-export declare function credentialsPath(endpointId: string): string;
-export declare function loadCredentials(endpointId: string): WeixinIlinkCredentials | null;
-export declare function saveCredentials(endpointId: string, creds: WeixinIlinkCredentials): void;
-export declare function syncBufPath(endpointId: string): string;
-export declare function loadSyncBuf(endpointId: string): string;
-export declare function saveSyncBuf(endpointId: string, buf: string): void;
+/** Endpoint-owned persistence for credentials, cursors, context tokens, and media. */
+export declare class WeixinIlinkStateStore {
+    readonly endpointId: string;
+    readonly rootDir: string;
+    constructor(endpointId: string, rootDir: string);
+    endpointDirectory(): string;
+    credentialsPath(): string;
+    loadCredentials(): WeixinIlinkCredentials | null;
+    saveCredentials(credentials: WeixinIlinkCredentials): void;
+    syncBufPath(): string;
+    loadSyncBuf(): string;
+    saveSyncBuf(value: string): void;
+    contextTokensPath(): string;
+    mediaDirectory(subdir: string): string;
+}

package/lib/credentials.js

@@ -1,48 +1,65 @@
-import fs from "node:fs";
-import path from "node:path";
-const DEFAULT_DATA_DIR = "./data/weixin-ilink";
-export function resolveStateDir() {
-    return process.env.ZHIN_DATA_DIR
-        ? path.join(process.env.ZHIN_DATA_DIR, "weixin-ilink")
-        : DEFAULT_DATA_DIR;
-}
-export function credentialsPath(endpointId) {
-    return path.join(resolveStateDir(), `${endpointId}.json`);
-}
-export function loadCredentials(endpointId) {
-    const file = credentialsPath(endpointId);
-    try {
-        if (!fs.existsSync(file))
-            return null;
-        const raw = fs.readFileSync(file, "utf-8");
-        const data = JSON.parse(raw);
-        if (!data.botToken?.trim())
+import fs from 'node:fs';
+import path from 'node:path';
+/** Endpoint-owned persistence for credentials, cursors, context tokens, and media. */
+export class WeixinIlinkStateStore {
+    endpointId;
+    rootDir;
+    constructor(endpointId, rootDir) {
+        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;
+    }
+    endpointDirectory() {
+        return path.join(this.rootDir, this.endpointId);
+    }
+    credentialsPath() {
+        return path.join(this.endpointDirectory(), 'credentials.json');
+    }
+    loadCredentials() {
+        const file = this.credentialsPath();
+        try {
+            if (!fs.existsSync(file))
+                return null;
+            const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return data.botToken?.trim() ? data : null;
+        }
+        catch {
             return null;
-        return data;
+        }
     }
-    catch {
-        return null;
+    saveCredentials(credentials) {
+        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 saveCredentials(endpointId, creds) {
-    const file = credentialsPath(endpointId);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify({ ...creds, updatedAt: new Date().toISOString() }, null, 2), "utf-8");
-}
-export function syncBufPath(endpointId) {
-    return path.join(resolveStateDir(), `${endpointId}.sync-buf`);
-}
-export function loadSyncBuf(endpointId) {
-    const file = syncBufPath(endpointId);
-    try {
-        return fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
+    syncBufPath() {
+        return path.join(this.endpointDirectory(), 'sync-buf');
     }
-    catch {
-        return "";
+    loadSyncBuf() {
+        const file = this.syncBufPath();
+        try {
+            return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    saveSyncBuf(value) {
+        const file = this.syncBufPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, value, 'utf-8');
+    }
+    contextTokensPath() {
+        return path.join(this.endpointDirectory(), 'context-tokens.json');
+    }
+    mediaDirectory(subdir) {
+        if (subdir !== 'inbound' && subdir !== 'outbound') {
+            throw new TypeError(`Unsupported Weixin iLink media directory: ${subdir}`);
+        }
+        return path.join(this.endpointDirectory(), 'media', subdir);
     }
-}
-export function saveSyncBuf(endpointId, buf) {
-    const file = syncBufPath(endpointId);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, buf, "utf-8");
 }