@zhin.js/adapter-wecom 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @zhin.js/adapter-wecom
 
+## 2.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/agent@1.0.4
+  - @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
+
 ## 2.0.2
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,13 @@
 # @zhin.js/adapter-wecom
 
-Zhin.js 企业微信（WeCom）适配器，支持企业内部应用机器人开发。
+Zhin.js 企业微信（WeCom）适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
+
+## 功能
+
+- Webhook 事件接收（`httpHostToken` GET 验签解密 + POST 消息）
+- AES-256-CBC 消息加解密与 SHA1 签名验证
+- Access Token 自动刷新
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -8,265 +15,111 @@ Zhin.js 企业微信（WeCom）适配器，支持企业内部应用机器人开
 pnpm add @zhin.js/adapter-wecom
 ```
 
-## 前置条件
+## Plugin Runtime
 
-### 企业微信管理后台配置
+- `@zhin.js/adapter` — 约定式 `adapters/wecom.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>`
 
-1. **登录企业微信管理后台**
-   - 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
-   - 使用管理员账号登录
+入站：`gateway.receive({ adapter, target: FromUserName, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → 企业微信 `message/send` API
 
-2. **创建应用**
-   - 进入「应用管理」→「自建」
-   - 点击「创建应用」
-   - 填写应用名称、上传 Logo、选择可见范围
+入站 `metadata.mentioned`：**未接线**。企业微信应用消息回调的 XML 事件不含 mentions/@ 字段，回调里的 `ToUserName` 是 CorpID（企业 ID）而非可比较的 bot 用户 id，配置中也没有 bot id/name 可作可靠判据，故无法可靠识别 @ 机器人。
 
-3. **获取应用凭证**
-   - 在应用详情页面获取：
-     - **CorpId**（企业 ID）：在「我的企业」→「企业信息」中查看
-     - **AgentId**（应用 AgentId）：在应用详情页面
-     - **Secret**（应用 Secret）：在应用详情页面
+## 前置条件
 
-4. **配置接收消息**
-   - 在应用详情页面，进入「接收消息」设置
-   - 设置 **URL**：`https://yourdomain.com/wecom/callback`
-   - 设置 **Token**：自定义字符串（用于签名验证）
-   - 设置 **EncodingAESKey**：点击「随机获取」（用于消息加解密）
-   - 点击「保存」，企业微信会发送验证请求
+### 企业微信管理后台配置
 
-5. **配置权限**
-   - 在「API 权限」中申请所需权限：
-     - `通讯录只读权限` - 读取组织架构和用户信息
-     - `应用消息发送权限` - 向用户发送消息
-     - 其他业务需要的权限
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
+2. 「应用管理」→「自建」→ 创建应用，获取 **CorpId**、**AgentId**、**Secret**
+3. 「接收消息」设置：
+   - **URL**：`https://yourdomain.com/wecom/callback`
+   - **Token** / **EncodingAESKey** 与配置一致
+4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-## 配置
+必填字段：`corpId`、`agentSecret`、`token`、`encodingAESKey`。
 
-### 基础配置（zhin.config.yml）
+## 最小配置
 
 ```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "ww1234567890abcdef"
-    agentSecret: "your-agent-secret"
-    token: "your-verify-token"
-    encodingAESKey: "your-43-char-encoding-aes-key"
-    webhookPath: "/wecom/callback"
-
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-wecom"
-```
-
-### 完整配置
-
-```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "ww1234567890abcdef"
-    agentSecret: "your-agent-secret"
-    token: "your-verify-token"
-    encodingAESKey: "your-43-char-encoding-aes-key"
-    webhookPath: "/wecom/callback"
-    apiBaseUrl: "https://qyapi.weixin.qq.com"  # 可选，默认值
+  wecom:
+    name: wecom-bot
+    corpId: ${WECOM_CORP_ID}
+    agentSecret: ${WECOM_AGENT_SECRET}
+    token: ${WECOM_TOKEN}
+    encodingAESKey: ${WECOM_AES_KEY}
+    webhookPath: /wecom/callback       # 可选，默认 /wecom/callback
+    apiBaseUrl: https://qyapi.weixin.qq.com  # 可选
 ```
 
-### 配置参数说明
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `corpId` | 是 | 企业 ID，在管理后台「我的企业」查看 |
-| `agentSecret` | 是 | 应用 Secret，在应用详情页获取 |
-| `token` | 是 | 用于签名验证，需与管理后台「接收消息」设置中的 Token 一致 |
-| `encodingAESKey` | 是 | 用于消息加解密，需与管理后台一致（43 字符） |
-| `webhookPath` | 否 | Webhook 回调路径，默认 `/wecom/callback` |
-| `apiBaseUrl` | 否 | 企业微信 API 地址，默认 `https://qyapi.weixin.qq.com` |
-
-### 环境变量推荐
-
-```yaml
-endpoints:
-  - name: wecom-bot
-    context: wecom
-    corpId: "${WECOM_CORP_ID}"
-    agentSecret: "${WECOM_AGENT_SECRET}"
-    token: "${WECOM_TOKEN}"
-    encodingAESKey: "${WECOM_AES_KEY}"
-```
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-wecom`（`instanceKey: wecom`）。
 
-## 使用示例
+## 环境变量
 
-### 接收和发送消息
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand, logger } = usePlugin()
-
-// 定义命令
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    logger.info(`收到问候: ${result.params.name}`)
-    return `你好，${result.params.name}！欢迎使用企业微信机器人。`
-  })
-)
-
-// 监听所有消息
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  logger.info(`收到消息：${JSON.stringify(message.$content)}`)
-  logger.info(`发送者：${message.$sender.name}`)
-  logger.info(`会话类型：${message.$channel.type}`)
-})
-```
-
-### 发送富文本消息
-
-```typescript
-addCommand(new MessageCommand('info')
-  .action(async (message) => {
-    return [
-      {
-        type: 'markdown',
-        data: {
-          content: `# 系统信息\n\n- 服务器: 运行正常\n- 版本: v1.0.0\n- 状态: 在线`
-        }
-      }
-    ]
-  })
-)
-```
+| 变量 | 说明 |
+|------|------|
+| `WECOM_CORP_ID` | 企业 ID |
+| `WECOM_AGENT_SECRET` | 应用 Secret |
+| `WECOM_TOKEN` | 回调签名 Token |
+| `WECOM_AES_KEY` | EncodingAESKey（43 字符） |
 
 ## 消息类型支持
 
-### 接收消息类型
-
-| 类型 | 状态 | 说明 |
-|------|------|------|
-| 文本消息 (`text`) | 支持 | 普通文本 |
-| 图片消息 (`image`) | 支持 | 图片文件 |
-| 语音消息 (`voice`) | 支持 | 含语音识别结果 |
-| 视频消息 (`video`) | 支持 | 视频文件 |
-| 位置消息 (`location`) | 支持 | 地理位置 |
-| 链接消息 (`link`) | 支持 | 链接卡片 |
-| 事件消息 (`event`) | 支持 | 关注/取消关注等 |
-
-### 发送消息类型
-
-| 类型 | 状态 | 说明 |
-|------|------|------|
-| 文本消息 | 支持 | 支持 @ 提醒 |
-| 图片消息 | 支持 | 需要 media_id |
-| Markdown 消息 | 支持 | 企业微信原生 Markdown |
-| 图文消息 | 支持 | news 类型 |
-| 撤回消息 | 不支持 | 企业微信机器人不支持撤回 |
+| 入站类型 | content 摘要 |
+|----------|--------------|
+| text | 原文 |
+| image | `[image: url]` |
+| voice | 识别结果或 `[voice]` |
+| video / shortvideo | `[video]` |
+| location | `[位置] …` |
+| link | `[link: …]` |
+| event | `[事件] …` |
+
+| 出站 wire | 说明 |
+|-----------|------|
+| text | 支持 `<@userid>` |
+| image | 需 `media_id` |
+| markdown | 企业微信原生 Markdown |
+| news | link 段映射 |
 
 ## 安全说明
 
-### 消息加解密
-
-企业微信使用 AES-256-CBC 加密算法对回调消息进行加密：
-
-- **签名验证**：SHA1 排序拼接 `[token, timestamp, nonce, encrypt]`
-- **解密流程**：
-  1. Base64 解码加密消息
-  2. AES-256-CBC 解密（Key: `encodingAESKey` + `=` 的 Base64 解码，IV: Key 的前 16 字节）
-  3. PKCS7 去填充
-  4. 提取：16 字节随机数 + 4 字节消息长度 + 消息体 + CorpId
-
-适配器自动处理所有加解密，无需手动处理。
+企业微信回调始终加密：
 
-### Token 管理
+- **签名**：SHA1 排序拼接 `[token, timestamp, nonce, encrypt]`
+- **解密**：AES-256-CBC（Key = `encodingAESKey` + `=` 的 Base64，IV = Key 前 16 字节）
 
-适配器会自动管理 access_token：
-- 首次连接时获取 token
-- Token 过期前 5 分钟自动刷新
-- 所有 API 请求自动携带有效 token
-
-## API 方法
-
-### 获取用户信息
-
-```typescript
-const endpoint = app.adapters.get('wecom')?.endpoints.get('wecom-bot')
-if (endpoint) {
-  const userInfo = await endpoint.getUserInfo('user-id')
-  console.log(userInfo)
-}
-```
-
-### 获取部门用户列表
-
-```typescript
-const users = await endpoint.getDepartmentUsers(1) // 部门 ID
-console.log(users)
-```
-
-### 获取部门列表
-
-```typescript
-const departments = await endpoint.getDepartmentList(1) // 父部门 ID
-console.log(departments)
-```
-
-### 发送文本消息
-
-```typescript
-const success = await endpoint.sendTextMessage('user-id', '这是一条测试消息')
-```
+Access Token 在过期前 5 分钟自动刷新。
 
 ## 故障排查
 
-### Q: Webhook 验证失败？
-
-A: 检查以下几点：
-1. `token` 是否与企业微信管理后台设置的 Token 一致
-2. `encodingAESKey` 是否与管理后台一致（43 字符）
-3. 服务器是否可从公网访问
-4. 服务器是否返回了正确的验证响应（解密后的 echostr）
-
-### Q: 收不到消息回调？
-
-A: 可能的原因：
-1. 应用未启用「接收消息」功能
-2. Webhook URL 配置错误或不可达
-3. 应用可见范围未包含发送消息的用户
-4. 服务器日志中是否有签名验证失败的警告
-
-### Q: 发送消息失败？
-
-A: 可能的原因：
-1. `agentSecret`（应用 Secret）配置错误
-2. access_token 获取失败（检查 CorpId 和 Secret）
-3. 接收者不在应用可见范围内
-4. 应用未开通消息发送权限
-
-### Q: Token 刷新失败？
-
-A: 检查：
-1. CorpId 是否正确
-2. agentSecret 是否是应用 Secret（不是应用的 AgentId 数字）
-3. 企业微信 API 是否可访问
-
-## 相关链接
-
-- [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
-- [企业微信接收消息](https://developer.work.weixin.qq.com/document/path/90930)
-- [企业微信发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
+| 现象 | 排查 |
+|------|------|
+| URL 验证失败 | `token` / `encodingAESKey` / `corpId` 与管理后台一致；Host 已 listen 且公网可达 |
+| 收不到消息 | 应用已启用接收消息；可见范围包含发送者；endpoint 已 `open()` |
+| 发送失败 | `corpId` + `agentSecret` 可换取 token；接收者在可见范围 |
 
 ## AI 工具
 
 | 类别 | 路径 |
 |------|------|
 | Permit 词汇 | `agent/PERMITS.md` |
-| 平台工具（4 个） | `agent/tools/`（`wecom_*`：用户、部门、发消息等） |
+| 平台工具（4 个） | `agent/tools/` |
 | 技能说明 | `agent/skills/wecom.md` |
-| 群管标准工具 | 按平台能力由 `createSceneManagementTools()` 注册 |
 
+## 平台权限（platform permit）
+
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
+
+## 相关链接
+
+- [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
+- [接收消息](https://developer.work.weixin.qq.com/document/path/90930)
+- [发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)
 
 ## 许可证
 

package/adapters/wecom.ts

@@ -0,0 +1,27 @@
+/**
+ * Convention entry: discover `adapters/wecom.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / protocol).
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WecomEndpoint } from '../src/endpoint.js';
+import {
+  resolveWecomConfig,
+  type WecomAdapterConfig,
+} from '../src/protocol.js';
+
+export { WecomEndpoint } from '../src/endpoint.js';
+export type { WecomEndpointOptions, WecomFetch } from '../src/endpoint.js';
+
+export default defineAdapter<WecomAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new WecomEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      http: context.use(httpHostToken),
+      config: resolveWecomConfig(context.config),
+    });
+  },
+});

package/agent/tools/get_dept_users.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineTool<{ endpoint_id: string; dept_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; dept_id: string }>({
   description: '获取企业微信部门用户列表',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/get_user.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineTool<{ endpoint_id: string; user_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; user_id: string }>({
   description: '获取企业微信用户信息',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/list_departments.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineTool<{ endpoint_id: string; dept_id?: string }>({
+export default defineAgentTool<{ endpoint_id: string; dept_id?: string }>({
   description: '获取企业微信部门列表',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/send_text.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getWecomAgentDeps } from '../../src/wecom-agent-deps.js';
-export default defineTool<{ endpoint_id: string; user_id: string; content: string }>({
+export default defineAgentTool<{ endpoint_id: string; user_id: string; content: string }>({
   description: '向指定企业微信用户发送文本消息',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/lib/endpoint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
+ */
+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 ResolvedWecomConfig, type WecomApiResponse, type WecomMessage } from './protocol.js';
+export type WecomFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface WecomEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedWecomConfig;
+    readonly fetch?: WecomFetch;
+}
+export declare class WecomEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: WecomEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedWecomConfig;
+    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: WecomMessage): void;
+    getUserInfo(userId: string): Promise<WecomApiResponse | null>;
+    getDepartmentUsers(deptId: number): Promise<unknown[]>;
+    getDepartmentList(deptId?: number): Promise<unknown[]>;
+    sendTextMessage(userId: string, content: string): Promise<boolean>;
+}