@zhin.js/adapter-dingtalk 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @zhin.js/adapter-dingtalk
 
+## 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 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- 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
+
+- 872c583: Slack 适配器 Phase 1/2：mrkdwn 出站、长消息切分、斜杠/按钮 ephemeral 反馈、入站 mrkdwn→Markdown、editMessage 对齐 core。
+
+  Logger 表格日志与 string-width 列宽；Agent AI Handler 框线表格与 introspection/MCP 导出；Core side-event 归一化；Schedule 时区规划；多适配器 side-event 与 API surface 更新。
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
 ## 4.0.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,13 @@
 # @zhin.js/adapter-dingtalk
 
-Zhin.js 钉钉适配器，支持企业内部机器人和钉钉开放平台机器人开发。
+Zhin.js 钉钉适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
+
+## 功能
+
+- Webhook 事件接收（`httpHostToken` POST + HMAC-SHA256 签名验证）
+- Access Token 自动刷新
+- Session Webhook 优先回复 / `/robot/send` 主动发送
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -8,357 +15,73 @@ Zhin.js 钉钉适配器，支持企业内部机器人和钉钉开放平台机器
 pnpm add @zhin.js/adapter-dingtalk
 ```
 
-## 配置
-
-### 基础配置
-
-```typescript
-import { DingTalkEndpointConfig } from '@zhin.js/adapter-dingtalk';
-
-const config: DingTalkEndpointConfig = {
-  context: 'dingtalk',
-  name: 'my-dingtalk-bot',
-  appKey: 'YOUR_APP_KEY',           // 钉钉应用 AppKey
-  appSecret: 'YOUR_APP_SECRET',     // 钉钉应用 AppSecret
-  webhookPath: '/dingtalk/webhook', // Webhook 路径
-  robotCode: 'YOUR_ROBOT_CODE'      // 机器人编码（可选）
-}
-```
-
-### 完整配置
-
-```typescript
-const config: DingTalkEndpointConfig = {
-  context: 'dingtalk',
-  name: 'my-dingtalk-bot',
-  appKey: 'YOUR_APP_KEY',
-  appSecret: 'YOUR_APP_SECRET',
-  webhookPath: '/dingtalk/webhook',
-  robotCode: 'YOUR_ROBOT_CODE',
-  
-  // API 配置
-  apiBaseUrl: 'https://oapi.dingtalk.com' // 自定义API地址（可选）
-}
-```
-
-### 配置参数说明
-
-- `appKey` (必需): 钉钉应用的 AppKey，在开发者后台获取
-- `appSecret` (必需): 钉钉应用的 AppSecret，在开发者后台获取
-- `webhookPath` (必需): Webhook 路径，如 `/dingtalk/webhook`
-- `robotCode` (可选): 机器人编码，用于发送消息时识别机器人身份
-- `apiBaseUrl` (可选): 自定义 API 基础地址，默认为 `https://oapi.dingtalk.com`
-
-## 获取配置信息
-
-### 创建钉钉企业内部应用
-
-1. **访问钉钉开放平台**
-   - 登录 [钉钉开放平台](https://open.dingtalk.com/)
-   - 进入「应用开发」→「企业内部开发」
-
-2. **创建应用**
-   - 点击「创建应用」
-   - 选择「企业内部开发」→「机器人」
-   - 填写应用基本信息（应用名称、应用描述、应用图标等）
-
-3. **获取应用凭证**
-   - 在应用详情页面找到「开发管理」
-   - 获取 **AppKey** 和 **AppSecret**
-   - 记录这些信息用于配置
-
-### 配置机器人
-
-1. **配置机器人能力**
-   - 在应用详情页面，进入「机器人配置」
-   - 启用「消息接收」功能
-   - 获取机器人的 **RobotCode**（机器人编码）
-
-2. **配置消息接收地址**
-   - 在「消息接收」设置中配置接收地址
-   - 设置请求 URL：`https://yourdomain.com/dingtalk/webhook`
-   - 钉钉会通过该地址推送消息事件
-
-3. **配置权限**
-   - 在「权限管理」中申请所需权限：
-     - `通讯录只读权限` - 读取通讯录信息
-     - `企业通讯录个人信息读权限` - 获取用户详细信息
-     - `消息通知` - 发送工作通知
-     - 其他业务需要的权限
-
-4. **发布应用**
-   - 完成配置后，发布应用
-   - 在企业工作台添加应用
-   - 员工可在钉钉中找到并使用该机器人
-
-### 创建群机器人（Webhook 机器人）
-
-如果只需要简单的群聊机器人功能：
-
-1. **在群聊中添加机器人**
-   - 进入钉钉群聊
-   - 点击群设置 → 「智能群助手」
-   - 选择「添加机器人」→「自定义机器人」
-
-2. **配置 Webhook**
-   - 输入机器人名称
-   - 获取 Webhook 地址
-   - 配置安全设置（加签或关键词）
-
-3. **使用限制**
-   - 群机器人只能在对应群聊中使用
-   - 功能相对简单，适合轻量级场景
-
-## 使用示例
-
-### 配置文件（zhin.config.ts）
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      name: 'dingtalk-bot',
-      context: 'dingtalk',
-      appKey: 'dingxxxxxxxxxx',
-      appSecret: 'your-app-secret',
-      webhookPath: '/dingtalk/webhook',
-      robotCode: 'dingxxxxxxxxxxxxxxxx'
-    }
-  ],
-  plugins: [
-    '@zhin.js/host-router',
-    '@zhin.js/adapter-dingtalk',
-  ],
-})
-```
-
-### 接收和发送消息
-
-```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(`收到消息：${message.$raw}`)
-  logger.info(`发送者：${message.$sender.name}`)
-  logger.info(`会话类型：${message.$channel.type}`)
-})
-```
-
-### 使用 @ 功能
-
-```typescript
-addCommand(new MessageCommand('notify <...users:at>')
-  .action(async (message, result) => {
-    const users = result.params.users
-    return [
-      { type: 'text', data: { content: '通知以下用户：\n' } },
-      ...users.map(user => ({ 
-        type: 'at', 
-        data: { id: user.data.id, name: user.data.name } 
-      })),
-      { type: 'text', data: { content: '\n请注意查看！' } }
-    ]
-  })
-)
-```
-
-### 发送富文本消息
-
-```typescript
-addCommand(new MessageCommand('info')
-  .action(async (message) => {
-    return [
-      {
-        type: 'markdown',
-        data: {
-          title: '系统信息',
-          content: `
-# 系统信息
-
-## 基本信息
-- **服务器**: 运行正常
-- **版本**: v1.0.0
-- **状态**: ✅ 在线
-
-## 功能列表
-1. 消息接收与发送
-2. 命令解析
-3. @ 提醒功能
-          `
-        }
-      }
-    ]
-  })
-)
-```
-
-## 消息类型支持
+## Plugin Runtime
 
-### 接收消息类型
+- `@zhin.js/adapter` — 约定式薄入口 `adapters/dingtalk.ts`（`defineAdapter`）
+- 实现：`src/endpoint.ts`（生命周期/出站/OpenAPI）、`src/webhook.ts`（验签入站）、`src/protocol.ts`
+- `@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>`
 
-- ✅ **文本消息** (`text`) - 普通文本和 @ 提醒
-- ✅ **图片消息** (`picture`) - 图片文件
-- ✅ **文件消息** (`file`) - 各类文件
-- ✅ **语音消息** (`audio`) - 音频文件
-- ✅ **视频消息** (`video`) - 视频文件
-- ✅ **富文本消息** (`richText`) - 富文本内容
-- ✅ **Markdown 消息** (`markdown`) - Markdown 格式
+入站：`gateway.receive({ adapter, target: conversationId, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → sessionWebhook 或 `/robot/send`
 
-### 发送消息类型
+## 前置条件
 
-- ✅ **文本消息** - 支持 @ 提醒
-- ✅ **图片消息** - 通过 URL 发送
-- ✅ **Markdown 消息** - 富文本展示
-- ✅ **链接消息** - 卡片式链接
-- ❌ **撤回消息** - 钉钉机器人不支持撤回
+1. 在 [钉钉开放平台](https://open.dingtalk.com/) 创建企业内部应用 / 机器人
+2. 获取 **AppKey**、**AppSecret**（可选 RobotCode）
+3. 设置消息接收 URL 为 `https://your-domain/dingtalk/webhook`
+4. Runtime Host（`http`）须已 listen，Webhook 才可达
 
-## API 方法
+必填字段：`appKey`、`appSecret`。
 
-### 获取用户信息
+## 最小配置
 
-```typescript
-const endpoint = app.adapters.get('dingtalk')?.endpoints.get('dingtalk-bot')
-if (bot) {
-  const userInfo = await endpoint.getUserInfo('user-id')
-  console.log(userInfo)
-}
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  dingtalk:
+    name: my-dingtalk-bot
+    appKey: ${DINGTALK_APP_KEY}
+    appSecret: ${DINGTALK_APP_SECRET}
+    robotCode: ${DINGTALK_ROBOT_CODE}   # 可选
+    webhookPath: /dingtalk/webhook       # 可选，默认 /dingtalk/webhook
+    apiBaseUrl: https://oapi.dingtalk.com # 可选
 ```
 
-### 获取部门用户列表
-
-```typescript
-const users = await endpoint.getDepartmentUsers(1) // 部门 ID
-console.log(users)
-```
-
-### 发送工作通知
-
-```typescript
-await endpoint.sendWorkNotice(
-  ['user1', 'user2'], // 用户 ID 列表
-  {
-    msgtype: 'text',
-    text: { content: '这是一条工作通知' }
-  }
-)
-```
-
-## 安全说明
-
-### 签名验证
-
-钉钉会在 Webhook 请求的 Header 中携带签名信息：
-- `timestamp`: 时间戳
-- `sign`: 签名值
-
-适配器会自动验证签名，确保请求来自钉钉服务器。
-
-### Token 管理
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-dingtalk`（`instanceKey: dingtalk`）。
 
-适配器会自动管理 access_token：
-- 首次连接时获取 token
-- Token 过期前 5 分钟自动刷新
-- 所有 API 请求自动携带有效 token
+## 环境变量
 
-## 最佳实践
+| 变量 | 说明 |
+|------|------|
+| `DINGTALK_APP_KEY` | 应用 AppKey |
+| `DINGTALK_APP_SECRET` | 应用 AppSecret |
+| `DINGTALK_BOT_NAME` | 默认 endpoint 名称（可选） |
 
-### 1. 配置环境变量
+## 消息类型映射
 
-不要在代码中硬编码敏感信息：
+| 钉钉类型 | 入站 content（文本摘要） | 出站 wire |
+|----------|--------------------------|-----------|
+| text | 原文 | text |
+| picture | `[image]` | picture（需 `url`） |
+| file | `[file: name]` | — |
+| audio / video | `[audio]` / `[video]` | — |
+| markdown | 原文或 `[markdown]` | markdown |
+| link | — | link |
 
-```typescript
-export default defineConfig({
-  endpoints: [{
-    name: 'dingtalk-bot',
-    context: 'dingtalk',
-    appKey: process.env.DINGTALK_APP_KEY!,
-    appSecret: process.env.DINGTALK_APP_SECRET!,
-    webhookPath: '/dingtalk/webhook',
-    robotCode: process.env.DINGTALK_ROBOT_CODE
-  }]
-})
-```
-
-### 2. 错误处理
-
-处理可能的错误情况：
-
-```typescript
-onMessage(async (message) => {
-  try {
-    // 处理消息逻辑
-  } catch (error) {
-    logger.error('处理消息失败:', error)
-    await message.$reply('抱歉，处理消息时出现错误')
-  }
-})
-```
+## Agent 工具
 
-### 3. 消息限流
+`agent/` 目录保留（get_user、部门、群聊、工作通知等）。Endpoint 在 `start` 时自注册到 `dingtalk-agent-deps`。
 
-注意钉钉的 API 调用频率限制，避免过于频繁的请求。
+## 平台权限（platform permit）
 
-### 4. 日志记录
+`plugin.ts` 在 generation setup 注册 `src/platform-permit.ts` checker，并在 dispose 注销；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具权限。
 
-开启详细日志，便于排查问题：
+## 测试
 
-```typescript
-export default defineConfig({
-  log_level: 'debug', // 开发环境使用 debug
-  // ... 其他配置
-})
+```bash
+pnpm --filter @zhin.js/adapter-dingtalk build
+pnpm --filter @zhin.js/adapter-dingtalk test
 ```
-
-## 常见问题
-
-### Q: Webhook 收不到消息？
-
-A: 检查以下几点：
-1. Webhook URL 是否可以从公网访问
-2. 钉钉后台的消息接收地址是否配置正确
-3. 应用是否已经发布并添加到工作台
-4. 检查服务器日志是否有错误信息
-
-### Q: 发送消息失败？
-
-A: 可能的原因：
-1. AppKey 或 AppSecret 配置错误
-2. access_token 获取失败
-3. 机器人编码（robotCode）配置错误
-4. 网络问题或 API 限流
-
-### Q: @ 功能不生效？
-
-A: 确保：
-1. 使用正确的用户 ID 格式
-2. @ 的用户在当前会话中
-3. 消息格式正确包含 at 字段
-
-## 相关链接
-
-- [钉钉开放平台](https://open.dingtalk.com/)
-- [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/robot-overview)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
-
-## 许可证
-
-MIT License
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！

package/adapters/dingtalk.ts

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

package/agent/tools/add_chat_members.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ endpoint_id: string; chat_id: string; user_ids: string }>({
+  description: '向钉钉群聊添加成员',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    chat_id: z.string().describe('群聊 ID'),
+    user_ids: z.string().describe('要添加的用户 ID 列表，逗号分隔'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  permissions: [platformPermit('chat_admin')],
+  async execute({ endpoint_id, chat_id, user_ids    }: { endpoint_id: string; chat_id: string; user_ids: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    const success = await endpoint.updateChat(chat_id, { add_useridlist: user_ids.split(',') });
+    return { success, message: success ? '成员添加成功' : '添加失败' };
+  },
+});
+

package/agent/tools/create_chat.ts

@@ -0,0 +1,23 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ endpoint_id: string; name: string; owner: string; members: string }>({
+  description: '创建钉钉群聊',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    name: z.string().describe('群名'),
+    owner: z.string().describe('群主用户 ID'),
+    members: z.string().describe('成员用户 ID 列表，逗号分隔'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  permissions: [platformPermit('chat_owner')],
+  async execute({ endpoint_id, name, owner, members    }: { endpoint_id: string; name: string; owner: string; members: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    const chatId = await endpoint.createChat(name, owner, members.split(','));
+    return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
+  },
+});
+

package/agent/tools/dept_info.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; dept_id: string }>({
+  description: '获取钉钉部门详细信息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    dept_id: z.string().describe('部门 ID'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  async execute({ endpoint_id, dept_id    }: { endpoint_id: string; dept_id: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    return await endpoint.getDepartmentInfo(Number(dept_id));
+  },
+});
+

package/agent/tools/get_dept_users.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; dept_id: string }>({
+  description: '获取钉钉部门用户列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    dept_id: z.string().describe('部门 ID'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  async execute({ endpoint_id, dept_id    }: { endpoint_id: string; dept_id: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    const users = await endpoint.getDepartmentUsers(Number(dept_id));
+    return { users, count: users.length };
+  },
+});
+

package/agent/tools/get_user.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; user_id: string }>({
+  description: '获取钉钉用户信息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.string().describe('用户 ID'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  async execute({ endpoint_id, user_id    }: { endpoint_id: string; user_id: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    return await endpoint.getUserInfo(user_id);
+  },
+});
+

package/agent/tools/list_departments.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; dept_id?: string }>({
+  description: '获取钉钉部门列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    dept_id: z.string().optional().describe('父部门 ID，默认 1（根部门）'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  async execute({ endpoint_id, dept_id    }: { endpoint_id: string; dept_id?: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    const departments = await endpoint.getDepartmentList(Number(dept_id || '1'));
+    return { departments, count: departments.length };
+  },
+});
+

package/agent/tools/send_work_notice.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDingtalkAgentDeps } from '../../src/dingtalk-agent-deps.js';
+export default defineAgentTool<{ endpoint_id: string; user_ids: string; content: string }>({
+  description: '向指定用户发送钉钉工作通知',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_ids: z.string().describe('用户 ID 列表，逗号分隔'),
+    content: z.string().describe('通知内容'),
+  }),
+  platforms: ['dingtalk'],
+  tags: ['dingtalk'],
+  async execute({ endpoint_id, user_ids, content    }: { endpoint_id: string; user_ids: string; content: string }) {
+    const endpoint = getDingtalkAgentDeps().getEndpoint(endpoint_id);
+    const msgContent = { msgtype: 'text', text: { content } };
+    const success = await endpoint.sendWorkNotice(user_ids.split(','), msgContent);
+    return { success, message: success ? '工作通知已发送' : '发送失败' };
+  },
+});
+