@zhin.js/adapter-wechat-mp 3.0.2 → 3.0.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @zhin.js/adapter-wechat-mp
 
+## 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/host-http@1.0.1
+  - 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,14 +1,14 @@
 # @zhin.js/adapter-wechat-mp
 
-Zhin.js 微信公众号适配器，支持微信公众号的消息收发。
+Zhin.js 微信公众号适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
 ## 功能特性
 
-- Webhook 事件接收（HTTP 回调）
-- 签名验证
+- Webhook 事件接收（`httpHostToken` GET 验签 + POST 消息）
+- 签名验证与可选 AES 加解密
 - Access Token 自动刷新
 - XML 消息解析
-- 可选消息加密（AES）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -16,28 +16,36 @@ Zhin.js 微信公众号适配器，支持微信公众号的消息收发。
 pnpm add @zhin.js/adapter-wechat-mp
 ```
 
+## Plugin Runtime
+
+- `@zhin.js/adapter` — 约定式 `adapters/wechat-mp.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+
+入站：`gateway.receive({ adapter, target: openid, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
+
 ## 前置条件
 
 | 要求 | 说明 |
 |------|------|
 | **公众号** | 已注册微信公众号，并在 [微信公众平台](https://mp.weixin.qq.com/) 获取 `AppID`、`AppSecret` |
 | **服务器配置** | 配置 Token（与 `token` 字段一致）；服务器 URL 须公网可访问 |
-| **host-router** | **必需** — 适配器在 `path` 上注册 GET/POST Webhook 路由 |
+| **host-http** | **必需** — Runtime Host 提供 HTTP；适配器在 `path` 上注册 GET/POST |
 | **响应时限** | 微信要求 **5 秒内**响应；超时会导致接入失败 |
-| **回复模式** | 默认 `replyMode: passive`（订阅号被动回复，在 webhook 响应里返回 XML）；服务号可设 `customer_service` 走客服 API |
-| **消息加密** | 可选；`encrypt: true` + `encodingAESKey`；`encryptMode: compatible`（默认，被动回复明文）或 `secure`（被动回复也加密） |
+| **回复模式** | 默认 `replyMode: passive`（订阅号被动回复）；服务号可设 `customer_service` |
+| **消息加密** | 可选；`encrypt: true` + `encodingAESKey`；`encryptMode: compatible`（默认）或 `secure` |
 
-必填字段见 `WeChatMPConfig`：`context`、`name`、`appId`、`appSecret`、`token`、`path`。
+必填字段：`appId`、`appSecret`、`token`。
 
 ## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-wechat-mp"
-  - "@zhin.js/host-router"
-
-endpoints:
-  - context: wechat-mp
+  wechat-mp:
     name: my-wechat-bot
     appId: "${WECHAT_APP_ID}"
     appSecret: "${WECHAT_APP_SECRET}"
@@ -45,76 +53,15 @@ endpoints:
     path: /wechat/webhook
 ```
 
-## 依赖
-
-- `@zhin.js/host-router` — HTTP 服务（提供 Webhook 路由）
-
-## 配置
-
-### TypeScript 配置
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-wechat-mp`（`instanceKey: wechat-mp`）。
+Runtime Host（`http`）须已 listen，Webhook 才可达。
 
-完整选项示例（含可选加密字段）：
+### 可选字段
 
-```yaml
-endpoints:
-  - context: wechat-mp
-    name: my-wechat-bot
-    appId: ${WECHAT_APP_ID}
-    appSecret: ${WECHAT_APP_SECRET}
-    token: ${WECHAT_TOKEN}
-    path: /wechat/webhook
-    # encodingAESKey: your-aes-key
-    # encrypt: false
-```
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'wechat-mp',
-      name: 'my-wechat-bot',
-      appId: process.env.WECHAT_APP_ID!,
-      appSecret: process.env.WECHAT_APP_SECRET!,
-      token: process.env.WECHAT_TOKEN!,
-      path: '/wechat/webhook',
-    }
-  ],
-  plugins: ['@zhin.js/adapter-wechat-mp', '@zhin.js/host-router']
-})
-```
-
-## 使用示例
-
-### 注册命令
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand } = usePlugin()
-
-addCommand(
-  new MessageCommand('hello')
-    .desc('微信问候')
-    .action((message) => `你好，${message.$sender.name}！`)
-)
-```
-
-### 消息中间件
-
-```typescript
-import { usePlugin } from 'zhin.js'
-
-const { root } = usePlugin()
-
-root.addMiddleware(async (message, next) => {
-  if (message.$adapter === 'wechat-mp') {
-    console.log('收到微信消息:', message.$content)
-  }
-  await next()
-})
-```
+- `path`：Webhook 路径，默认 `/wechat/webhook`
+- `replyMode`：`passive`（默认）| `customer_service`
+- `passiveReplyTimeoutMs`：被动回复等待上限，默认 `4500`
+- `encrypt` / `encodingAESKey` / `encryptMode`
 
 ## 微信公众号配置
 
@@ -128,16 +75,15 @@ root.addMiddleware(async (message, next) => {
 
 | 现象 | 排查 |
 |------|------|
-| 服务器配置验证失败 | `token` 与公众平台一致；URL 为 `https://<host>/wechat/webhook`；Host 已启动且公网可达 |
-| 收不到用户消息 | 公众号类型是否支持消息接口；用户是否已关注；`path` 与公众平台 URL 一致 |
-| 回复超时 / 无回复 | 默认被动回复须在 **~4.5s** 内完成；AI 过慢会返回 `success` 无正文，可改 `replyMode: customer_service`（需客服接口权限） |
+| 服务器配置验证失败 | `token` 与公众平台一致；URL 为 `https://<host>/wechat/webhook`；Runtime Host 已 listen 且公网可达 |
+| 收不到用户消息 | 公众号类型是否支持消息接口；用户是否已关注；`path` 与公众平台 URL 一致；endpoint 已 `open()` |
+| 回复超时 / 无回复 | 默认被动回复须在 **~4.5s** 内完成；可改 `replyMode: customer_service`（需客服接口权限） |
 | `48001 api unauthorized` | 未认证订阅号无客服 API；保持默认 `replyMode: passive` |
 | 加密模式报错 | `encodingAESKey`、`encrypt` 与公众平台「安全模式」设置一致 |
 
 ## AI 工具
 
-技能说明见 `agent/skills/wechat-mp.md`。群管与平台工具按公众号能力在 `src/index.ts` 注册。
-
+技能说明见 `agent/skills/wechat-mp.md`。
 
 ## 文档链接
 

package/adapters/wechat-mp.ts

@@ -0,0 +1,26 @@
+/**
+ * Convention entry: discover `adapters/wechat-mp.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WeChatMpEndpoint } from '../src/endpoint.js';
+import {
+  resolveWeChatMpConfig,
+  type WeChatMpAdapterConfig,
+} from '../src/protocol.js';
+
+export { WeChatMpEndpoint } from '../src/endpoint.js';
+export type { WeChatMpEndpointOptions, WeChatMpFetch } from '../src/endpoint.js';
+
+export default defineAdapter<WeChatMpAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new WeChatMpEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      http: context.use(httpHostToken),
+      config: resolveWeChatMpConfig(context.config),
+    });
+  },
+});

package/lib/endpoint.d.ts

@@ -1,73 +1,38 @@
-import { EventEmitter } from "events";
-import { Endpoint, Message, MessageSegment, SendOptions } from 'zhin.js';
-import { type Router } from "@zhin.js/host-router/router";
-import type { WeChatMPConfig, WeChatMessage } from "./types.js";
-import type { WeChatMPAdapter } from "./adapter.js";
-export declare class WeChatMPEndpoint extends EventEmitter implements Endpoint<WeChatMPConfig, WeChatMessage> {
-    adapter: WeChatMPAdapter;
-    $config: WeChatMPConfig;
-    $connected: boolean;
-    router: Router;
-    private accessToken;
-    private tokenExpireTime;
-    get logger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: WeChatMPAdapter, router: Router, config: WeChatMPConfig);
-    private setupRoutes;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private handleVerification;
-    private handleMessage;
-    private computeSignatureHash;
-    private verifySignature;
-    private parseXMLMessage;
-    $formatMessage(wechatMsg: WeChatMessage): Message<WeChatMessage>;
-    static parseMessageContent(wechatMsg: WeChatMessage): MessageSegment[];
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
-    private sendCustomerServiceMessage;
-    private formatSendContent;
-    private getReplyMode;
-    private getEncryptMode;
-    private usesPassiveReply;
-    private extractSendText;
-    private collectPassiveReplyXml;
-    private handlePassiveReply;
-    private buildTextReply;
-    private refreshAccessToken;
-    private tokenRefreshTimer?;
-    private startTokenRefreshTimer;
-    getUserInfo(openid: string): Promise<any>;
-    /**
-     * 上传多媒体文件到微信服务器
-     * @param type 媒体类型：image(图片)、voice(语音)、video(视频)、thumb(缩略图)
-     * @param buffer 文件 Buffer
-     * @param filename 文件名（可选，用于确定文件类型）
-     * @returns 微信服务器返回的 media_id
-     */
-    uploadMedia(type: 'image' | 'voice' | 'video' | 'thumb', buffer: Buffer, filename?: string): Promise<string>;
-    /**
-     * 获取文件扩展名
-     */
-    private getFileExtension;
-    /**
-     * 获取 Content-Type
-     */
-    private getContentType;
-    private getAESKey;
-    /** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
-    private isEncryptedEchostr;
-    /**
-     * 解密安全模式 URL 验证中的 echostr
-     */
-    private decryptEchostr;
-    /**
-     * 解密微信推送的加密消息
-     */
-    private decryptMessage;
-    /**
-     * 加密被动回复消息
-     */
-    private encryptMessage;
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
+export type WeChatMpFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+}) => Promise<{
+    readonly data: unknown;
+}>;
+export interface WeChatMpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedWeChatMpConfig;
+    readonly fetch?: WeChatMpFetch;
+}
+export declare class WeChatMpEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: WeChatMpEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedWeChatMpConfig;
+    get id(): CapabilityId;
+    get gateway(): MessageGateway;
+    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 open (non-webhook path). */
+    admit(msg: WeChatMessage): void;
 }
-//# sourceMappingURL=endpoint.d.ts.map