@zhin.js/adapter-lark 4.0.2 → 4.0.3

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @zhin.js/adapter-lark
 
+## 4.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
+
 ## 4.0.2
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,14 @@
 # @zhin.js/adapter-lark
 
-Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管理。
+Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
-## 功能特性
+## 功能
 
-- 支持飞书和 Lark 国际版
-- Webhook 事件接收（HTTP 回调）
-- Bearer Token 自动刷新
-- 消息加密和签名验证（可选）
-- URL 验证自动处理
-- 群管理 AI 工具（`agent/tools/` 平台工具 + `agent/skills/lark.md`；群管标准工具由 `createSceneManagementTools` 注册）
+- Webhook 事件接收（`httpHostToken` POST + 可选 verificationToken / encryptKey 签名）
+- URL 验证挑战（`url_verification`）
+- Tenant Access Token 自动刷新
+- 支持飞书与 Lark 国际版 API 基址
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -17,103 +16,75 @@ Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管
 pnpm add @zhin.js/adapter-lark
 ```
 
-## 依赖
+## Plugin Runtime
 
-- `@zhin.js/host-router` — HTTP 服务（提供 Webhook 路由）
+- `@zhin.js/adapter` — 约定式 `adapters/lark.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: chat_id, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → `im/v1/messages`
 
-```yaml
-# zhin.config.yml
-endpoints:
-  - context: lark
-    name: my-lark-bot
-    appId: cli_xxxxxxxxxxxx
-    appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
-    webhookPath: /lark/webhook
-    # 可选配置
-    # encryptKey: your-encrypt-key
-    # verificationToken: your-token
-    # isFeishu: true          # 使用飞书 API（默认）
-    # apiBaseUrl: https://open.feishu.cn/open-apis   # 自定义 API 地址
-
-plugins:
-  - "@zhin.js/adapter-lark"
-  - "@zhin.js/host-router"
-```
-
-或使用 TypeScript 配置：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'lark',
-      name: 'my-lark-bot',
-      appId: process.env.LARK_APP_ID!,
-      appSecret: process.env.LARK_APP_SECRET!,
-      webhookPath: '/lark/webhook',
-    }
-  ],
-  plugins: ['@zhin.js/adapter-lark', '@zhin.js/host-router']
-})
-```
+入站 `metadata.mentioned`：**未接线**。消息事件的 `mentions[]` 元素含 `id.open_id`，但本适配器拿不到 bot 自身的 open_id——配置（`appId` / `appSecret` / `name` 等）不含 bot open_id，代码也未调用 `bot/v3/info` 获取应用信息，故无可靠判据比对 mentions。
 
-## 使用示例
+## 前置条件
 
-### 注册命令
+1. 在 [飞书开放平台](https://open.feishu.cn/)（或 Lark）创建企业自建应用
+2. 获取 **App ID**、**App Secret**
+3. 启用机器人能力并配置事件订阅 URL：`https://your-domain/lark/webhook`
+4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+必填字段：`appId`、`appSecret`。
 
-const { addCommand } = usePlugin()
+## 最小配置
 
-addCommand(
-  new MessageCommand('hello')
-    .desc('飞书问候')
-    .action((message) => {
-      return `你好，${message.$sender.name}！`
-    })
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  lark:
+    name: my-lark-bot
+    appId: ${LARK_APP_ID}
+    appSecret: ${LARK_APP_SECRET}
+    webhookPath: /lark/webhook          # 可选，默认 /lark/webhook
+    encryptKey: ${LARK_ENCRYPT_KEY}     # 可选
+    verificationToken: ${LARK_VERIFY_TOKEN}  # 可选
+    isFeishu: true                      # 可选，默认 true
+    # apiBaseUrl: https://open.feishu.cn/open-apis
 ```
 
-### 消息处理
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-lark`（`instanceKey: lark`）。
 
-```typescript
-import { usePlugin } from 'zhin.js'
+## 环境变量
 
-const { root } = usePlugin()
-
-root.addMiddleware(async (message, next) => {
-  if (message.$adapter === 'lark') {
-    console.log('收到飞书消息:', message.$content)
-  }
-  await next()
-})
-```
+| 变量 | 说明 |
+|------|------|
+| `LARK_APP_ID` | 应用 App ID |
+| `LARK_APP_SECRET` | 应用 App Secret |
+| `LARK_BOT_NAME` | 默认 endpoint 名称（可选） |
 
-## AI 工具（Skill）
+## 消息类型映射
 
-| 类别 | 路径 |
-|------|------|
-| Permit 词汇 | `agent/PERMITS.md` |
-| 平台工具（8 个） | `agent/tools/`（`lark_*`：群聊、成员、文件等） |
-| 技能说明 | `agent/skills/lark.md` |
-| 群管标准工具 | `createSceneManagementTools()` |
+| 飞书类型 | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | text |
+| image | `[image]` | image（需 `file_key`） |
+| file | `[file: name]` | file |
+| audio / video / sticker | `[audio]` / `[video]` / `[sticker]` | — |
+| card | — | interactive |
 
+## Agent 工具
 
-> 工具使用飞书的 `open_id` 和 `chat_id` 格式标识用户和群聊。
+`agent/` 目录保留（get_user、群聊、管理员、上传文件等）。Endpoint 在 `start` 时自注册到 `lark-agent-deps`。
 
-## 飞书开发者配置
+## 平台权限（platform permit）
 
-1. 登录 [飞书开放平台](https://open.feishu.cn/)
-2. 创建应用并获取 `App ID` 和 `App Secret`
-3. 配置事件回调 URL：`http://your-server:8086/api/lark/webhook`
-4. 订阅 `im.message.receive_v1` 事件
-5. 发布应用
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
 
-## 许可证
+## 测试
 
-MIT License
+```bash
+pnpm --filter @zhin.js/adapter-lark build
+pnpm --filter @zhin.js/adapter-lark test
+```

package/adapters/lark.ts

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

package/agent/tools/add_members.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
   description: '添加飞书群成员',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/create_chat.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
-export default defineTool<{ endpoint_id: string; name: string; members: string; owner?: string }>({
+export default defineAgentTool<{ endpoint_id: string; name: string; members: string; owner?: string }>({
   description: '创建飞书群聊',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/dissolve_chat.ts

@@ -1,7 +1,7 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
-export default defineTool<{ endpoint_id: string; chat_id: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string }>({
   description: '解散飞书群聊（需要群主权限）',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/get_user.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-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/remove_managers.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
   description: '移除飞书群管理员',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_managers.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
   description: '设置飞书群管理员',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/update_chat.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 import { platformPermit } from '../../src/platform-permit.js';
 
-export default defineTool<{ endpoint_id: string; chat_id: string; name?: string; description?: string }>({
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; name?: string; description?: string }>({
   description: '更新飞书群聊信息（群名、描述）',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/upload_file.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getLarkAgentDeps } from '../../src/lark-agent-deps.js';
 
-export default defineTool<{
+export default defineAgentTool<{
   endpoint_id: string;
   file_path: string;
   file_type: 'image' | 'file' | 'video' | 'audio';

package/lib/endpoint.d.ts

@@ -0,0 +1,53 @@
+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 LarkMessage, type ResolvedLarkConfig } from './protocol.js';
+export type LarkFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | FormData;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface LarkEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedLarkConfig;
+    readonly fetch?: LarkFetch;
+}
+export declare class LarkEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: LarkEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedLarkConfig;
+    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: LarkMessage): void;
+    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+    updateChatInfo(chatId: string, options: {
+        name?: string;
+        description?: string;
+    }): Promise<boolean>;
+    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    getChatMembers(chatId: string): Promise<unknown[]>;
+    dissolveChat(chatId: string): Promise<boolean>;
+    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}