@zhin.js/adapter-weixin-ilink 3.0.2 → 3.0.3

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-weixin-ilink
 
+## 3.0.3
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
 ## 3.0.2
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @zhin.js/adapter-weixin-ilink
 
-通过微信 **iLink Endpoint API**（ClawBot 灰度入口）接入**个人微信**，支持文本与全量媒体收发、输入状态提示。
+通过微信 **iLink Endpoint API**（ClawBot 灰度入口）接入**个人微信**，支持文本与全量媒体收发。Plugin Runtime 约定式 `defineAdapter`（长轮询入站，无 host-router / Koa）。
 
 协议实现移植自 [Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin)（MIT），已去除 OpenClaw 耦合，`bot_agent` 默认为 `Zhin.js/<version>`。
 
@@ -9,8 +9,8 @@
 | 项 | weixin-ilink | wechat-mp |
 |---|---|---|
 | 账号类型 | 个人微信（ClawBot） | 微信公众号 |
-| 入站 | 长轮询 `getupdates` | Webhook 被动回复 |
-| 登录 | 扫码 + 侧车凭证文件 | AppId/Secret/Token |
+| 入站 | 长轮询 `getupdates` → `messageGatewayToken` | Webhook（`httpHostToken`） |
+| 登录 | 扫码 / 侧车凭证 / `botToken` | AppId/Secret/Token |
 | 群聊 | 不支持（仅私聊） | 支持 |
 
 可与 `@zhin.js/adapter-wechat-mp` **同时启用**。
@@ -19,78 +19,55 @@
 
 - 微信客户端需已灰度 **ClawBot** 入口（最新版微信 + 灰度资格）
 - Node.js ^20.19.0 或 >=22.12.0
-- 可选：`@zhin.js/host-router` + `@zhin.js/host-api` 用于 Web 控制台扫码登录
 
 ## 最小配置
 
 ```yaml
-endpoints:
-  - context: weixin-ilink
+plugins:
+  weixin-ilink:
     name: my-wechat
-    # botAgent: "Zhin.js/1.0.0"      # 可选，观测用
-    # longPollTimeoutMs: 35000       # 可选
+    # botToken: "..."                 # 或环境变量 WEIXIN_ILINK_TOKEN
+    # botAgent: "Zhin.js/1.0.0"
+    # longPollTimeoutMs: 35000
     # baseUrl: https://ilinkai.weixin.qq.com
-
-plugins:
-  - "@zhin.js/adapter-weixin-ilink"
-  - "@zhin.js/host-router"   # 可选，Console + login-assist API
-  - "@zhin.js/host-api"      # 可选
 ```
 
-`zhin.config.yml` **只写 bot `name`**；`botToken` 保存在侧车文件（不进 git）：
+`botToken` 也可保存在侧车文件（不进 git）：
 
 ```
 data/weixin-ilink/<bot-name>.json
 ```
 
-也可通过环境变量 `WEIXIN_ILINK_TOKEN` 或配置项 `botToken` 覆盖（CI 场景）。
-
 ## 登录流程
 
-1. 首次启动无凭证时，bot 调用 `get_bot_qrcode` 并在控制台展示二维码（`loginAssist`）
+1. 首次启动无凭证时，调用 `get_bot_qrcode` 并在日志中打印二维码内容
 2. 用户用微信扫码确认
 3. 后台轮询 `get_qrcode_status` 直至 `confirmed`，写入 `data/weixin-ilink/<name>.json`
 4. 调用 `notifyStart` 后进入长轮询
 
-与 Host 同时启用时：
-
-- Console 页面：`/weixin-ilink`（概览 + 登录辅助）
-- HTTP API：`GET /api/login-assist/pending`、`POST /api/login-assist/submit`、`POST /api/login-assist/cancel`
-- Endpoint 状态：`GET /api/weixin-ilink/endpoints`
-
-## Typing Indicator
-
-私聊使用 iLink `sendTyping` API，在微信侧显示**正在输入**（非文本消息、非 reaction）。长任务期间每 5s 保活一次（`keepaliveIntervalMs` 可配）。
-
-```yaml
-typingIndicator:
-  enabled: true
-  keepaliveIntervalMs: 5000
-  privateConfig:
-    type: typing
-```
+> Console 扫码面板（旧 `loginAssist` + host-router）已从生产路径移除；优先用 `botToken` / 侧车凭证。
 
 ## 出站说明
 
 回复必须携带入站时缓存的 `context_token`（按 `endpointId + peerUserId`）。若用户久未发消息导致 token 缺失，出站会拒绝并打 warn。
 
-所有出站走标准链路：`Message.$reply` / `Adapter.sendMessage` → `before.sendMessage` → `endpoint.$sendMessage`。
+出站经 Runtime：`MessageGateway` → `endpoint.send({ target, payload })`。
 
 **图文限制**：微信单条消息不支持图文混排。适配器会自动：
+
 - **出站**：先单独发文本，再发纯媒体（不带 caption）
-- **入站**：若同一条 iLink 消息同时含文字与媒体，拆成两条 `message.receive` 事件
+- **入站**：文字与媒体路径写入同一条 gateway `content` 文本
 
 ## 故障排查
 
 | 现象 | 可能原因 |
 |---|---|
 | 无法扫码 / 无 ClawBot 入口 | 未灰度；需最新微信 + 灰度资格 |
-| 二维码过期 | 重启 Endpoint 重新获取 |
+| 二维码过期 | 重启适配器重新获取 |
 | 发不出消息 | 缺少 `context_token`；让用户先发一条消息 |
 | `errcode -14` | 会话过期，适配器自动暂停 1 小时后重试 |
-| Console 无待办 | 确认 `host-router` 已加载且访问 `/weixin-ilink` |
 
 ## 文档
 
-- 架构与计划：仓库内 weixin-ilink 实现计划
 - 适配器索引：[`plugins/adapters/README.md`](../README.md)
+- 原位迁移：[`docs/architecture/target-implementation/in-place-migration.md`](../../../docs/architecture/target-implementation/in-place-migration.md)

package/adapters/weixin-ilink.ts

@@ -0,0 +1,30 @@
+/**
+ * Convention entry: discover `adapters/weixin-ilink.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { WeixinIlinkEndpoint } from '../src/endpoint.js';
+import {
+  resolveWeixinIlinkConfig,
+  type WeixinIlinkAdapterConfig,
+} from '../src/protocol.js';
+
+export { WeixinIlinkEndpoint } from '../src/endpoint.js';
+export type {
+  WeixinIlinkEndpointOptions,
+  WeixinIlinkGetUpdates,
+  WeixinIlinkNotifyStart,
+  WeixinIlinkNotifyStop,
+  WeixinIlinkSendText,
+} from '../src/endpoint.js';
+
+export default defineAdapter<WeixinIlinkAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new WeixinIlinkEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      config: resolveWeixinIlinkConfig(context.config),
+    });
+  },
+});

package/lib/aes-ecb.d.ts

@@ -4,4 +4,3 @@ export declare function encryptAesEcb(plaintext: Buffer, key: Buffer): Buffer;
 export declare function decryptAesEcb(ciphertext: Buffer, key: Buffer): Buffer;
 /** Compute AES-128-ECB ciphertext size (PKCS7 padding to 16-byte boundary). */
 export declare function aesEcbPaddedSize(plaintextSize: number): number;
-//# sourceMappingURL=aes-ecb.d.ts.map

package/lib/aes-ecb.js

@@ -16,4 +16,3 @@ export function decryptAesEcb(ciphertext, key) {
 export function aesEcbPaddedSize(plaintextSize) {
     return Math.ceil((plaintextSize + 1) / 16) * 16;
 }
-//# sourceMappingURL=aes-ecb.js.map

package/lib/cdn-upload.d.ts

@@ -15,4 +15,3 @@ export declare function uploadBufferToCdn(params: {
 }): Promise<{
     downloadParam: string;
 }>;
-//# sourceMappingURL=cdn-upload.d.ts.map

package/lib/cdn-upload.js

@@ -70,4 +70,3 @@ export async function uploadBufferToCdn(params) {
     }
     return { downloadParam };
 }
-//# sourceMappingURL=cdn-upload.js.map

package/lib/cdn-url.d.ts

@@ -11,4 +11,3 @@ export declare function buildCdnUploadUrl(params: {
     uploadParam: string;
     filekey: string;
 }): string;
-//# sourceMappingURL=cdn-url.d.ts.map

package/lib/cdn-url.js

@@ -11,4 +11,3 @@ export function buildCdnDownloadUrl(encryptedQueryParam, cdnBaseUrl) {
 export function buildCdnUploadUrl(params) {
     return `${params.cdnBaseUrl}/upload?encrypted_query_param=${encodeURIComponent(params.uploadParam)}&filekey=${encodeURIComponent(params.filekey)}`;
 }
-//# sourceMappingURL=cdn-url.js.map

package/lib/context-store.d.ts

@@ -1,2 +1 @@
 export { setContextToken, getContextToken, restoreContextTokens, clearContextTokensForAccount, bodyFromItemList, isMediaItem, } from "./weixin-inbound.js";
-//# sourceMappingURL=context-store.d.ts.map

package/lib/context-store.js

@@ -1,2 +1 @@
 export { setContextToken, getContextToken, restoreContextTokens, clearContextTokensForAccount, bodyFromItemList, isMediaItem, } from "./weixin-inbound.js";
-//# sourceMappingURL=context-store.js.map

package/lib/credentials.d.ts

@@ -12,4 +12,3 @@ export declare function saveCredentials(endpointName: string, creds: WeixinIlink
 export declare function syncBufPath(endpointName: string): string;
 export declare function loadSyncBuf(endpointName: string): string;
 export declare function saveSyncBuf(endpointName: string, buf: string): void;
-//# sourceMappingURL=credentials.d.ts.map

package/lib/credentials.js

@@ -46,4 +46,3 @@ export function saveSyncBuf(endpointName, buf) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, buf, "utf-8");
 }
-//# sourceMappingURL=credentials.js.map

package/lib/endpoint.d.ts

@@ -1,35 +1,40 @@
-import { Endpoint, Message, type SendOptions } from 'zhin.js';
-import { type WeixinMessage } from './ilink-types.js';
-import type { WeixinInboundMediaOpts } from "./weixin-inbound.js";
-import type { WeixinIlinkEndpointConfig } from "./types.js";
-import type { WeixinIlinkAdapter } from "./adapter.js";
-export type WeixinMessageWithMedia = WeixinMessage & {
-    _media?: WeixinInboundMediaOpts;
-};
-export declare class WeixinIlinkEndpoint implements Endpoint<WeixinIlinkEndpointConfig, WeixinMessage> {
-    adapter: WeixinIlinkAdapter;
-    $config: WeixinIlinkEndpointConfig;
-    $connected: boolean;
-    private creds;
-    private pollAbort?;
-    private pollPromise?;
-    private configManager?;
-    get $id(): string;
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
+import { type WeixinIlinkCredentials } from './credentials.js';
+import { sendMessageWeixin } from './weixin-send.js';
+import { type ResolvedWeixinIlinkConfig, type WeixinMessageWithMedia } from './protocol.js';
+export type WeixinIlinkSendText = typeof sendMessageWeixin;
+export type WeixinIlinkNotifyStart = typeof notifyStart;
+export type WeixinIlinkNotifyStop = typeof notifyStop;
+export type WeixinIlinkGetUpdates = typeof getUpdates;
+export interface WeixinIlinkEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: ResolvedWeixinIlinkConfig;
+    readonly resolveCredentials?: (config: ResolvedWeixinIlinkConfig) => Promise<WeixinIlinkCredentials>;
+    /** Test / internal: override network side effects. */
+    readonly notifyStart?: WeixinIlinkNotifyStart;
+    readonly notifyStop?: WeixinIlinkNotifyStop;
+    readonly getUpdates?: WeixinIlinkGetUpdates;
+    readonly sendText?: WeixinIlinkSendText;
+}
+export declare class WeixinIlinkEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: WeixinIlinkEndpointOptions);
     get hasCredentials(): boolean;
-    get pluginLogger(): import("zhin.js").Logger;
-    constructor(adapter: WeixinIlinkAdapter, $config: WeixinIlinkEndpointConfig);
     apiBaseUrl(): string;
     cdnBaseUrl(): string;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a parsed message when the endpoint is open. */
+    admit(msg: WeixinMessageWithMedia): void;
     sendTypingToUser(userId: string, status: number): Promise<void>;
-    $recallMessage(_id: string): Promise<void>;
-    $formatMessage(msg: WeixinMessageWithMedia): Message<WeixinMessage>;
-    private buildInboundContent;
-    $sendMessage(options: SendOptions): Promise<string>;
-    private pollLoop;
-    private handleInboundMessage;
-    private downloadInboundMedia;
-    private saveInboundMedia;
 }
-//# sourceMappingURL=endpoint.d.ts.map