@zhin.js/adapter-napcat 3.0.1 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @zhin.js/adapter-napcat
 
+## 4.0.1
+
+### 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
+
+## 3.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/contract@1.0.3
+  - @zhin.js/host-api@2.0.5
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -1,45 +1,38 @@
 # @zhin.js/adapter-napcat
 
-> **QQ 群助手 + 可选 @AI** — 先在 [demo.zhin.dev](https://demo.zhin.dev) 或 Sandbox 调试，再接 NapCat。启用 AI：`npx zhin setup --ai`。接入本适配器：`npx zhin setup --adapters`。
-
-Zhin.js NapCatQQ 适配器，支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API。
+Zhin.js [NapCatQQ](https://github.com/NapNeko/NapCatQQ) 适配器（Plugin Runtime，OneBot 11 + NapCat 扩展）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **反向 WS** 与 **HTTP POST 上报**（经 `httpHostToken`）。
 
 ## 功能特性
 
-- 完整 OneBot v11 协议兼容 + go-cqhttp 扩展 + NapCat 独有 API（92+ 接口）
-- **单一适配器**：`context: napcat`，通过 `connection` 选择连接方式
-- **正向 WebSocket**（`connection: ws`）：应用连 NapCat 的 WS
-- **反向 WebSocket**（`connection: wss`）：应用开 WS 服务端，NapCat 连上来
-- **HTTP API + POST 上报**（`connection: http`）：出站 HTTP 调用，入站 webhook
-- Access Token 认证支持（Bearer / HMAC 签名）
-- 自动重连机制（WS）与心跳检测
-- 群聊和私聊消息处理
-- 入站消息去重与 bot 自发消息过滤
-- Typing Indicator（处理中提示：群聊表情回应 / 私聊输入状态）
-- 41 个 AI 工具（群管、戳一戳、表情回应、精华消息、群公告、AI 语音等）
-- Console 管理页面（`/console/napcat`）
-- Agent Prompt 贡献器（deferred 任务自动优选 napcat 工具）
+- OneBot 11 + go-cqhttp 扩展 + NapCat 独有 API
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- **正向 WebSocket**（`connection: ws`）：应用连 NapCat WS
+- `access_token` 鉴权（Bearer + query）
+- 入站经 `messageGatewayToken`（去重 + 自发过滤）；出站 `send({ target, payload })`
+- 41 个 AI 工具（`agent/tools/`）
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-napcat ws
+pnpm add @zhin.js/adapter-napcat
 ```
 
-反向 WS / HTTP 模式需同时启用 `@zhin.js/host-router`。
+## Plugin Runtime
 
-## 配置
+- `@zhin.js/adapter` — 约定式 `adapters/napcat.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-所有 Endpoint 使用 **同一 context：`napcat`**，通过 **`connection`** 区分连接方式。
+入站：`gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata })`  
+出站：`send({ target, payload })` → WS `send_private_msg` / `send_group_msg`
 
-### 正向 WebSocket（connection: ws）
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-napcat"
-
-endpoints:
-  - context: napcat
+  napcat:
     connection: ws
     name: my-bot
     url: "ws://127.0.0.1:3001"
@@ -48,86 +41,40 @@ endpoints:
     heartbeat_interval: 30000
 ```
 
-### 反向 WebSocket（connection: wss）
-
-```yaml
-plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-napcat"
-
-endpoints:
-  - context: napcat
-    connection: wss
-    name: my-bot
-    path: "/napcat/ws"
-    access_token: "${NAPCAT_TOKEN}"
-    heartbeat_interval: 30000
-```
-
-### HTTP API + POST 上报（connection: http）
-
-```yaml
-plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-napcat"
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-napcat`（`instanceKey: napcat`）。
 
-endpoints:
-  - context: napcat
-    connection: http
-    name: my-bot
-    http_url: "http://127.0.0.1:3000"
-    post_path: "/napcat/post"
-    access_token: "${NAPCAT_TOKEN}"
-    poll_interval: 30000
-```
+## 连接方式
 
-### Typing Indicator（处理中提示）
+| connection | 状态 |
+|------------|------|
+| `ws` | 已实现（推荐） |
+| `wss` | 已实现：反向 WS（httpHostToken） |
+| `http` | 已实现：POST 入站 + `http_url/{action}` 出站 |
 
-```yaml
-endpoints:
-  - context: napcat
-    connection: ws
-    name: my-bot
-    url: "ws://127.0.0.1:3001"
-    typingIndicator:
-      enabled: true
-      defaultEmoji: "128516"
-      privateConfig:
-        type: "message"
-        message: "正在思考中..."
-      groupConfig:
-        type: "reaction"
-        emoji: "128516"
-```
+## 鉴权
 
-## NapCat 独有能力
+- **Bearer**：`Authorization: Bearer <access_token>`
+- 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
 
-相比标准 OneBot11 适配器，NapCat 额外支持：
+## AI 工具
 
-- 戳一戳（群聊 / 私聊）
-- 表情回应（贴表情）
-- 合并 / 单条消息转发
-- 精华消息管理
-- 群公告管理
-- 群文件管理
-- AI 语音 TTS
-- 图片 OCR 文字识别
-- 小程序卡片签名
-- 个人资料 / 头像 / 签名修改
-- 在线状态设置
-- 消息历史查询
-- 英译中翻译
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具 | `agent/tools/*.ts` |
+| 技能说明 | `agent/skills/napcat.md` |
 
-## AI 工具
+## 迁移说明（Plugin Runtime）
 
-适配器自动注册 41 个 AI 工具（7 个群管理标准工具 + 34 个 NapCat 扩展工具），详见 `skills/napcat/SKILL.md`。
+- **notice / request 侧事件已移除**：旧 Adapter 对 `post_type: notice|request` 构建 `notice.receive` / `request.receive` 事件（含 `$approve` / `$reject`）；新 Plugin Runtime（`messageGatewayToken`）暂无侧事件总线，入站仅处理 `post_type: message`，notice / request 事件静默丢弃。加好友 / 加群请求审批可改用 `callApi('set_friend_add_request' | 'set_group_add_request')`。
+- **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后 `agent/tools/` 仅覆盖 NapCat 扩展 API，其余群管能力可通过 `callApi`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
+- **平台权限门禁**：`plugin.ts` setup 已注册 `registerDefaultScenePlatformPermitChecker('napcat')`，`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`（owner / admin）判定。
 
-## full-bot L4 参考
+## 文档链接
 
-[`examples/full-bot`](../../../examples/full-bot/) 默认加载本适配器（`endpoints` 段需自行填写 `ONEBOT11_*` 后取消注释）。
+- [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
+- [适配器概览](https://zhin.js.org/essentials/adapters)
 
-- 入站 → `ZhinAgent` → 出站走 `Adapter.sendMessage` 统一链路
-- 契约测试：`plugins/adapters/napcat/tests/l4-contract.test.ts` + `integration.test.ts`（adapter-harness）
-- CI：`L4_SKIP_PLATFORM=1` 跳过实机；本地验证不设该变量并可配置 `ONEBOT11_WS_URL`
+## 许可证
 
-详见 [full-bot ACCEPTANCE.md](../../../examples/full-bot/ACCEPTANCE.md)。
+MIT License

package/adapters/napcat.ts

@@ -0,0 +1,39 @@
+/**
+ * Convention entry: discover `adapters/napcat.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { NapCatHttpEndpoint } from '../src/http-endpoint.js';
+import { resolveNapCatConfig, type NapCatAdapterConfig } from '../src/protocol.js';
+import { NapCatWsEndpoint } from '../src/ws-endpoint.js';
+import { NapCatWssEndpoint } from '../src/wss-endpoint.js';
+
+export {
+  NapCatHttpEndpoint,
+  type NapCatHttpEndpointOptions,
+} from '../src/http-endpoint.js';
+export {
+  NapCatWsEndpoint,
+  type NapCatWsEndpointOptions,
+} from '../src/ws-endpoint.js';
+export {
+  NapCatWssEndpoint,
+  type NapCatWssEndpointOptions,
+} from '../src/wss-endpoint.js';
+export type { NapCatWsSocket, NapCatWsCreateOptions } from '../src/ws-types.js';
+
+export default defineAdapter<NapCatAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    const config = resolveNapCatConfig(context.config);
+    const gateway = context.use(messageGatewayToken);
+    if (config.connection === 'wss') {
+      return new NapCatWssEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+    }
+    if (config.connection === 'http') {
+      return new NapCatHttpEndpoint({ id: context.id, gateway, http: context.use(httpHostToken), config });
+    }
+    return new NapCatWsEndpoint({ id: context.id, gateway, config });
+  },
+});

package/agent/tools/ai_tts.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number; character: string; text: string }>({
+  description: 'AI 文字转语音，在群聊中发送 AI 语音消息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    character: z.string().describe('AI 语音角色 ID（可先用 napcat_get_ai_characters 查询）'),
+    text: z.string().describe('要转为语音的文字'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['AI语音', 'TTS', '文字转语音', 'ai record'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, character, text }: { endpoint_id: string; group_id: number; character: string; text: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.sendGroupAiRecord(group_id, character, text);
+  },
+});

package/agent/tools/del_group_notice.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number; notice_id: string }>({
+  description: '删除群公告。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    notice_id: z.string().describe('公告 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['删除公告', 'delete notice'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, notice_id }: { endpoint_id: string; group_id: number; notice_id: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteGroupNotice(group_id, notice_id);
+      return { success: true };
+  },
+});

package/agent/tools/delete_essence_msg.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; message_id: number }>({
+  description: '移除群精华消息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    message_id: z.number().describe('消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['取消精华', '移除精华', 'delete essence'],
+  permissions: ['platform(napcat,scene_admin)'],
+  scopes: ['group'],
+  async execute({ endpoint_id, message_id }: { endpoint_id: string; message_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteEssenceMsg(message_id);
+      return { success: true };
+  },
+});

package/agent/tools/delete_friend.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; user_id: number }>({
+  description: '删除好友。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('好友 QQ 号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['删除好友', 'delete friend', '删好友'],
+  permissions: ['platform(napcat,scene_admin)'],
+  async execute({ endpoint_id, user_id }: { endpoint_id: string; user_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      await endpoint.deleteFriend(user_id);
+      return { success: true };
+  },
+});

package/agent/tools/download_file.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; url: string; thread_count?: number }>({
+  description: '下载文件到 NapCat 缓存目录，返回本地路径。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    url: z.string().describe('文件 URL'),
+    thread_count: z.number().optional().describe('下载线程数（可选，默认 1）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['下载', 'download', '下载文件'],
+  async execute({ endpoint_id, url, thread_count }: { endpoint_id: string; url: string; thread_count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.downloadFile(url, thread_count || 1);
+  },
+});

package/agent/tools/forward_single_msg.ts

@@ -0,0 +1,32 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{
+  endpoint_id: string;
+  target_type: 'friend' | 'group';
+  target_id: number;
+  message_id: number;
+}>({
+  description: '转发单条消息到指定好友或群。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    target_type: z.enum(['friend', 'group']).describe('friend 或 group'),
+    target_id: z.number().describe('目标好友 QQ 号或群号'),
+    message_id: z.number().describe('要转发的消息 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['转发', 'forward', '单条转发'],
+  async execute({ endpoint_id, target_type, target_id, message_id }: {
+    endpoint_id: string;
+    target_type: 'friend' | 'group';
+    target_id: number;
+    message_id: number;
+  }) {
+    const endpoint = getEndpoint(endpoint_id);
+    if (target_type === 'friend') await endpoint.forwardFriendSingleMsg(target_id, message_id);
+    else await endpoint.forwardGroupSingleMsg(target_id, message_id);
+    return { success: true };
+  },
+});

package/agent/tools/get_ai_characters.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取 AI 语音角色列表，用于 napcat_ai_tts 的 character 参数。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['AI角色', 'ai characters', '语音角色'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getAiCharacters(group_id);
+  },
+});

package/agent/tools/get_essence_list.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群精华消息列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['精华列表', 'essence list'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getEssenceMsgList(group_id);
+  },
+});

package/agent/tools/get_friend_msg_history.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; user_id: number; message_seq?: number; count?: number }>({
+  description: '获取私聊消息历史记录。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    user_id: z.number().describe('QQ 号'),
+    message_seq: z.number().optional().describe('起始消息序号（可选）'),
+    count: z.number().optional().describe('获取条数（可选）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['私聊记录', '好友聊天记录', 'friend history'],
+  async execute({ endpoint_id, user_id, message_seq, count }: { endpoint_id: string; user_id: number; message_seq?: number; count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getFriendMsgHistory(user_id, message_seq, count);
+  },
+});

package/agent/tools/get_group_file_url.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number; file_id: string; busid: number }>({
+  description: '获取群文件下载链接。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    file_id: z.string().describe('文件 ID'),
+    busid: z.number().describe('文件类型 ID'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['文件链接', 'file url', '下载文件'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, file_id, busid }: { endpoint_id: string; group_id: number; file_id: string; busid: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupFileUrl(group_id, file_id, busid);
+  },
+});

package/agent/tools/get_group_info_ex.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群组额外详细信息。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群详情', '群额外信息', 'group info ex'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupInfoEx(group_id);
+  },
+});

package/agent/tools/get_group_msg_history.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number; message_seq?: number; count?: number }>({
+  description: '获取群消息历史记录。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+    message_seq: z.number().optional().describe('起始消息序号（可选，不传从最新开始）'),
+    count: z.number().optional().describe('获取条数（可选）'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群消息历史', '聊天记录', 'message history'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id, message_seq, count }: { endpoint_id: string; group_id: number; message_seq?: number; count?: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupMsgHistory(group_id, message_seq, count);
+  },
+});

package/agent/tools/get_group_notice.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群公告列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群公告', '获取公告', 'get notice'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupNotice(group_id);
+  },
+});

package/agent/tools/get_group_root_files.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群根目录文件列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['群文件列表', 'group files'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupRootFiles(group_id);
+  },
+});

package/agent/tools/get_group_shut_list.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; group_id: number }>({
+  description: '获取群禁言列表。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    group_id: z.number().describe('群号'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['禁言列表', 'shut list', '被禁言'],
+  scopes: ['group'],
+  async execute({ endpoint_id, group_id }: { endpoint_id: string; group_id: number }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getGroupShutList(group_id);
+  },
+});

package/agent/tools/get_mini_app_ark.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getEndpoint } from '../../src/napcat-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; type: string; title: string; desc: string; pic_url: string; jump_url: string }>({
+  description: '签名小程序卡片（如 B 站分享卡片等）。',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    type: z.string().describe('卡片类型'),
+    title: z.string().describe('标题'),
+    desc: z.string().describe('描述'),
+    pic_url: z.string().describe('图片 URL'),
+    jump_url: z.string().describe('跳转 URL'),
+  }),
+  platforms: ['napcat'],
+  tags: ['napcat', 'qq'],
+  keywords: ['小程序', 'mini app', '卡片', 'ark'],
+  async execute({ endpoint_id, type, title, desc, pic_url, jump_url }: { endpoint_id: string; type: string; title: string; desc: string; pic_url: string; jump_url: string }) {
+    const endpoint = getEndpoint(endpoint_id);
+      return endpoint.getMiniAppArk(type, title, desc, pic_url, jump_url);
+  },
+});