@zhin.js/adapter-lark 1.0.97 → 1.1.2

package/PERMITS.md

@@ -0,0 +1,22 @@
+# 飞书 Lark Platform Permits
+
+## 入站字段
+
+群聊消息经 `getChatInfo`（TTL 60s）比对 `owner_id` / `user_manager_id_list`：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `owner` · `admin` · `member` |
+| `$sender.permissions` | `chat_owner` · `chat_admin` · `manage_managers` |
+
+## Permit 词汇表
+
+| `platform(lark,…)` | 含义 |
+|--------------------|------|
+| `chat_owner` | 群主 |
+| `chat_admin` | 群管理员 |
+| `manage_managers` | 可设/撤管理员 |
+
+## 工厂映射
+
+`scene_admin` → `chat_admin` · `scene_owner` → `chat_owner`

package/README.md

@@ -1,15 +1,15 @@
 # @zhin.js/adapter-lark
 
-Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管理。
+Zhin.js 飞书 / Lark 适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
-## 功能特性
+## 功能
 
-- 支持飞书和 Lark 国际版
-- Webhook 事件接收（HTTP 回调）
-- Bearer Token 自动刷新
-- 消息加密和签名验证（可选）
-- URL 验证自动处理
-- 群管理 AI 工具（通过包内 `skills/lark/SKILL.md` 与 `addTool` 暴露给 AI）
+- Webhook 事件接收（`httpHostToken` POST + 可选 verificationToken / encryptKey 签名）
+- URL 验证挑战（`url_verification`）
+- Tenant Access Token 自动刷新
+- 支持飞书与 Lark 国际版 API 基址
+- canonical `markdown` 段编码为 `interactive` 卡片中的 `lark_md`
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -17,99 +17,85 @@ Zhin.js 飞书 / Lark 适配器，支持飞书机器人的消息收发和群管
 pnpm add @zhin.js/adapter-lark
 ```
 
-## 依赖
+## Plugin Runtime
 
-- `@zhin.js/host-router` — HTTP 服务（提供 Webhook 路由）
+- `@zhin.js/adapter` — 约定式 `adapters/lark/index.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-## 配置
+入站：`gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → `im/v1/messages`
 
-```yaml
-# zhin.config.yml
-bots:
-  - 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({
-  bots: [
-    {
-      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` / `id` 等）不含 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'
+必填字段（`endpoints[i]`）：`id`、`appId`、`appSecret`。
 
-const { addCommand } = usePlugin()
+## 最小配置
 
-addCommand(
-  new MessageCommand('hello')
-    .desc('飞书问候')
-    .action((message) => {
-      return `你好，${message.$sender.name}！`
-    })
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  lark:
+    webhookPath: /lark/webhook          # 可选，默认 /lark/webhook
+    isFeishu: true                      # 可选，默认 true
+    # apiBaseUrl: https://open.feishu.cn/open-apis
+    endpoints:
+      - id: my-lark-bot
+        appId: ${LARK_APP_ID}
+        appSecret: ${LARK_APP_SECRET}
+        # encryptKey: ${LARK_ENCRYPT_KEY}          # 可选
+        # verificationToken: ${LARK_VERIFY_TOKEN}  # 可选
 ```
 
-### 消息处理
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-lark`（`instanceKey: lark`）。
 
-```typescript
-import { usePlugin } from 'zhin.js'
+## 环境变量
 
-const { addMiddleware } = usePlugin()
+| 变量 | 说明 |
+|------|------|
+| `LARK_APP_ID` | 示例中由 YAML `${LARK_APP_ID}` 引用的 App ID；变量名可自行定义 |
+| `LARK_APP_SECRET` | 示例中由 YAML `${LARK_APP_SECRET}` 引用的 App Secret；变量名可自行定义 |
 
-addMiddleware(async (message, next) => {
-  if (message.$adapter === 'lark') {
-    console.log('收到飞书消息:', message.$content)
-  }
-  await next()
-})
-```
+## 消息类型映射
 
-## AI 工具（Skill）
+| 飞书类型 | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | text |
+| markdown | 原文 | interactive（`lark_md`） |
+| image | `[image]` | image（需 `file_key`） |
+| file | `[file: name]` | file |
+| audio / video / sticker | `[audio]` / `[video]` / `[sticker]` | — |
+| card | — | interactive |
 
-适配器内置群管理 Skill，自动注册以下工具供 AI 调用：
+## Agent 工具
 
-- 群聊管理（成员管理、群信息修改等）
+`tools/` 目录提供 get_user、群聊、管理员、上传文件等 Tool。工具声明 `adapter: 'lark'` 后，通过惰性的 `context.$client` 自动取得当前操作的 `LarkClient`；无需把 Endpoint id 暴露给模型。
 
-> 工具使用飞书的 `open_id` 和 `chat_id` 格式标识用户和群聊。
+## 平台权限（platform permit）
 
-## 飞书开发者配置
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
 
-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. 发布应用
+## 测试
+
+```bash
+pnpm --filter @zhin.js/adapter-lark build
+pnpm --filter @zhin.js/adapter-lark test
+```
 
-## 许可证
+## 故障排查
 
-MIT License
+| 现象 | 排查 |
+| --- | --- |
+| URL 验证失败 | 检查公网 HTTPS、`webhookPath`、verification token 与 encrypt key |
+| Tenant Token 获取失败 | 检查 `appId`、`appSecret` 与应用版本是否已发布 |
+| 群里 @机器人不触发 AI | 当前无法可靠判定 bot open_id；使用显式 AI 前缀 |
+| 能收不能发 | 检查机器人消息权限、可见范围与应用是否已加入群聊 |

package/adapters/lark/index.js

@@ -0,0 +1,36 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/lark/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LarkEndpoint } from "../../lib/endpoint.js";
+import { resolveLarkConfig, } from "../../lib/protocol.js";
+import { larkRuntimeStateToken } from "../../lib/lark-runtime-state.js";
+export { LarkEndpoint } from "../../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+    // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+    // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
+    // 卡片交互未接入出站通道，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'upload'],
+        interactive: 'text',
+        markdown: 'native',
+    },
+    create(context) {
+        const config = resolveLarkConfig(context.config);
+        // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
+        context.use(larkRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: 'webhook',
+        });
+        return new LarkEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/lark/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Convention entry: discover `adapters/lark/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LarkEndpoint } from '../../src/endpoint.js';
+import {
+  resolveLarkConfig,
+  type LarkEndpointConfig,
+} from '../../src/protocol.js';
+import { larkRuntimeStateToken } from '../../src/lark-runtime-state.js';
+
+export { LarkEndpoint } from '../../src/endpoint.js';
+export type { LarkEndpointOptions, LarkFetch } from '../../src/endpoint.js';
+
+export default defineAdapter<LarkEndpointConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+  // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
+  // canonical Markdown 由 endpoint codec 转为 lark_md 消息卡片；
+  // 卡片交互未接入出站通道，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'text',
+    markdown: 'native',
+  },
+  create(context) {
+    const config = resolveLarkConfig(context.config);
+    // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
+    context.use(larkRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new LarkEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/agents/lark/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "LARK Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles lark platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "lark",
+      "adapter:lark"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "lark"
+  ]
+}

package/agents/lark/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active lark endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/lark/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/lark/skills/lark/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: lark
+platforms: [lark]
+description: 飞书用户查询、群聊生命周期、管理员和文件上传能力。
+keywords: [lark, 飞书, user, chat, manager, file]
+tags: [adapter, collaboration]
+tools:
+  - get_user
+  - create_chat
+  - update_chat
+  - add_members
+  - set_managers
+  - remove_managers
+  - dissolve_chat
+  - upload_file
+---
+
+# 飞书
+
+涉及成员的操作先用 `get_user` 取得稳定用户 ID。创建群聊后可添加成员、更新群设置和维护管理员；解散群聊属于不可逆操作，应依照 Tool 审批策略执行。文件发送前先用 `upload_file` 获得文件标识。
+
+当前 Agent Tool 不提供当前群成员列表、踢人或独立群详情查询。

package/agents/lark/skills/lark/tools/add_members/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '添加飞书群成员',
+    inputSchema: z.object({
+        chat_id: z.string().describe('群聊 ID'),
+        user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    permissions: [platformPermission('lark', 'chat_admin')],
+    async execute({ chat_id, user_ids }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.addChatMembers(chat_id, user_ids.split(','));
+        return { success, message: success ? '成员添加成功' : '添加失败' };
+    },
+});

package/agents/lark/skills/lark/tools/add_members/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '添加飞书群成员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermission('lark', 'chat_admin')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.addChatMembers(chat_id, user_ids.split(','));
+    return { success, message: success ? '成员添加成功' : '添加失败' };
+  },
+});

package/agents/lark/skills/lark/tools/create_chat/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '创建飞书群聊',
+    inputSchema: z.object({
+        name: z.string().describe('群名'),
+        members: z.string().describe('成员 open_id 列表，逗号分隔'),
+        owner: z.string().optional().describe('群主 open_id（可选）'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    async execute({ name, members, owner }, context) {
+        const endpoint = context.$client;
+        const chatId = await endpoint.createChat(name, members.split(','), owner);
+        return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
+    },
+});

package/agents/lark/skills/lark/tools/create_chat/index.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool<{ name: string; members: string; owner?: string }>({
+  description: '创建飞书群聊',
+  inputSchema: z.object({
+    name: z.string().describe('群名'),
+    members: z.string().describe('成员 open_id 列表，逗号分隔'),
+    owner: z.string().optional().describe('群主 open_id（可选）'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ name, members, owner   }: { name: string; members: string; owner?: string }, context) {
+    const endpoint = context.$client;
+    const chatId = await endpoint.createChat(name, members.split(','), owner);
+    return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
+  },
+});
+

package/agents/lark/skills/lark/tools/dissolve_chat/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '解散飞书群聊（需要群主权限）',
+    inputSchema: z.object({
+        chat_id: z.string().describe('群聊 ID'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    async execute({ chat_id }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.dissolveChat(chat_id);
+        return { success, message: success ? '群聊已解散' : '解散失败' };
+    },
+});

package/agents/lark/skills/lark/tools/dissolve_chat/index.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool<{ chat_id: string }>({
+  description: '解散飞书群聊（需要群主权限）',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ chat_id   }: { chat_id: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.dissolveChat(chat_id);
+    return { success, message: success ? '群聊已解散' : '解散失败' };
+  },
+});
+

package/agents/lark/skills/lark/tools/get_user/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取飞书用户信息',
+    inputSchema: z.object({
+        user_id: z.string().describe('用户 ID (open_id)'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    async execute({ user_id }, context) {
+        const endpoint = context.$client;
+        return await endpoint.getUserInfo(user_id);
+    },
+});

package/agents/lark/skills/lark/tools/get_user/index.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<{ user_id: string }>({
+  description: '获取飞书用户信息',
+  inputSchema: z.object({
+    user_id: z.string().describe('用户 ID (open_id)'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ user_id   }: { user_id: string }, context) {
+    const endpoint = context.$client;
+    return await endpoint.getUserInfo(user_id);
+  },
+});
+

package/agents/lark/skills/lark/tools/remove_managers/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '移除飞书群管理员',
+    inputSchema: z.object({
+        chat_id: z.string().describe('群聊 ID'),
+        user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    permissions: [platformPermission('lark', 'manage_managers')],
+    async execute({ chat_id, user_ids }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.removeChatManagers(chat_id, user_ids.split(','));
+        return { success, message: success ? '管理员移除成功' : '移除失败' };
+    },
+});

package/agents/lark/skills/lark/tools/remove_managers/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '移除飞书群管理员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermission('lark', 'manage_managers')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.removeChatManagers(chat_id, user_ids.split(','));
+    return { success, message: success ? '管理员移除成功' : '移除失败' };
+  },
+});

package/agents/lark/skills/lark/tools/set_managers/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '设置飞书群管理员',
+    inputSchema: z.object({
+        chat_id: z.string().describe('群聊 ID'),
+        user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    permissions: [platformPermission('lark', 'manage_managers')],
+    async execute({ chat_id, user_ids }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.setChatManagers(chat_id, user_ids.split(','));
+        return { success, message: success ? '管理员设置成功' : '设置失败' };
+    },
+});

package/agents/lark/skills/lark/tools/set_managers/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; user_ids: string }>({
+  description: '设置飞书群管理员',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('用户 open_id 列表，逗号分隔'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermission('lark', 'manage_managers')],
+  async execute({ chat_id, user_ids   }: { chat_id: string; user_ids: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.setChatManagers(chat_id, user_ids.split(','));
+    return { success, message: success ? '管理员设置成功' : '设置失败' };
+  },
+});

package/agents/lark/skills/lark/tools/update_chat/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '更新飞书群聊信息（群名、描述）',
+    inputSchema: z.object({
+        chat_id: z.string().describe('群聊 ID'),
+        name: z.string().optional().describe('新群名（可选）'),
+        description: z.string().optional().describe('新描述（可选）'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    permissions: [platformPermission('lark', 'chat_admin')],
+    async execute({ chat_id, name, description }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.updateChatInfo(chat_id, { name, description });
+        return { success, message: success ? '群信息更新成功' : '更新失败' };
+    },
+});

package/agents/lark/skills/lark/tools/update_chat/index.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; name?: string; description?: string }>({
+  description: '更新飞书群聊信息（群名、描述）',
+  inputSchema: z.object({
+    chat_id: z.string().describe('群聊 ID'),
+    name: z.string().optional().describe('新群名（可选）'),
+    description: z.string().optional().describe('新描述（可选）'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  permissions: [platformPermission('lark', 'chat_admin')],
+  async execute({ chat_id, name, description   }: { chat_id: string; name?: string; description?: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.updateChatInfo(chat_id, { name, description });
+    return { success, message: success ? '群信息更新成功' : '更新失败' };
+  },
+});

package/agents/lark/skills/lark/tools/upload_file/index.js

@@ -0,0 +1,17 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '上传文件到飞书（image/file/video/audio）',
+    inputSchema: z.object({
+        file_path: z.string().describe('本地文件路径'),
+        file_type: z.enum(['image', 'file', 'video', 'audio']).default('file').describe('飞书文件类型'),
+    }),
+    adapter: 'lark',
+    tags: ['lark'],
+    async execute({ file_path, file_type }, context) {
+        const endpoint = context.$client;
+        const result = await endpoint.uploadFile(file_path, file_type);
+        return { success: true, file_key: result, message: `文件已上传，file_key: ${result}` };
+    },
+});

package/agents/lark/skills/lark/tools/upload_file/index.ts

@@ -0,0 +1,23 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<{
+  file_path: string;
+  file_type: 'image' | 'file' | 'video' | 'audio';
+}>({
+  description: '上传文件到飞书（image/file/video/audio）',
+  inputSchema: z.object({
+    file_path: z.string().describe('本地文件路径'),
+    file_type: z.enum(['image', 'file', 'video', 'audio']).default('file').describe('飞书文件类型'),
+  }),
+  adapter: 'lark',
+  tags: ['lark'],
+  async execute({ file_path, file_type }: {
+    file_path: string;
+    file_type: 'image' | 'file' | 'video' | 'audio';
+  }, context) {
+    const endpoint = context.$client;
+    const result = await endpoint.uploadFile(file_path, file_type);
+    return { success: true, file_key: result, message: `文件已上传，file_key: ${result}` };
+  },
+});