@zhin.js/adapter-napcat 1.0.1 → 1.1.0

package/README.md

@@ -1,131 +1,96 @@
 # @zhin.js/adapter-napcat
 
-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）
+- 入站经 `Endpoint.emit(...)`（去重 + 自发过滤）；出站 `send({ conversation, 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` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-所有 Endpoint 使用 **同一 context：`napcat`**，通过 **`connection`** 区分连接方式。
+入站：`gateway.receive({ conversation, message: { conversation, id }, content, sender, metadata })`（`conversation` 为 ConversationRef：私聊 `kind: 'private'`、群聊 `kind: 'group'`，临时会话群容器进 `parent`）  
+出站：`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`
 
-### 正向 WebSocket（connection: ws）
+## 前置条件
+
+1. 安装并登录 NapCatQQ，启用一个与 Zhin 配置匹配的 OneBot 11 连接。
+2. 正向 WS 需 Zhin 可达 NapCat；反向 WS/HTTP 上报需 NapCat 可达 Zhin HTTP Host。
+3. 两端配置相同的 `access_token`，不要把未鉴权端口暴露到公网。
+
+## 最小配置
 
 ```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"
-    access_token: "${NAPCAT_TOKEN}"
     reconnect_interval: 5000
     heartbeat_interval: 30000
+    endpoints:
+      - name: my-bot
+        url: "ws://127.0.0.1:3001"
+        access_token: "${NAPCAT_TOKEN}"
 ```
 
-### 反向 WebSocket（connection: wss）
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-napcat`（`instanceKey: napcat`）。
 
-```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）
+| connection | 状态 |
+|------------|------|
+| `ws` | 已实现（推荐） |
+| `wss` | 已实现：反向 WS（httpHostToken） |
+| `http` | 已实现：POST 入站 + `http_url/{action}` 出站 |
 
-```yaml
-plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-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（处理中提示）
+- **Bearer**：`Authorization: Bearer <access_token>`
+- 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
 
-```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"
-```
+## AI 工具
 
-## NapCat 独有能力
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具 | `agent/tools/*.ts` |
+| 技能说明 | `agent/skills/napcat.md` |
 
-相比标准 OneBot11 适配器，NapCat 额外支持：
+## 迁移说明（Plugin Runtime）
 
-- 戳一戳（群聊 / 私聊）
-- 表情回应（贴表情）
-- 合并 / 单条消息转发
-- 精华消息管理
-- 群公告管理
-- 群文件管理
-- AI 语音 TTS
-- 图片 OCR 文字识别
-- 小程序卡片签名
-- 个人资料 / 头像 / 签名修改
-- 在线状态设置
-- 消息历史查询
-- 英译中翻译
+- **notice / request / meta 侧事件**：经 the unified `Endpoint.emit(...)` ingress 归一后分发到 `handlers`（`notice.receive` / `request.receive` / `system.receive`），请求带 `$approve` / `$reject`。消息仍走 `outboundMessageToken`。
+- **群管工具暂未迁移**：旧 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）判定。
 
-## AI 工具
+## 文档链接
 
-适配器自动注册 41 个 AI 工具（7 个群管理标准工具 + 34 个 NapCat 扩展工具），详见 `skills/napcat/SKILL.md`。
+- [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
+- [适配器概览](https://zhin.js.org/essentials/adapters)
 
-## full-bot L4 参考
+## 故障排查
 
-[`examples/full-bot`](../../../examples/full-bot/) 默认加载本适配器（`endpoints` 段需自行填写 `ONEBOT11_*` 后取消注释）。
+| 现象 | 排查 |
+| --- | --- |
+| WS 连接被拒绝 | 检查 NapCat URL、端口与连接方向 |
+| 401 或握手失败 | 确认两端 token 一致，反向代理保留 Authorization |
+| 重复或自身消息触发 | 检查是否同时启用了多条上报连接 |
+| 请求/通知缺失 | 确认 NapCat 上报 notice/request/meta，并查看 Endpoint 对应分类 |
 
-- 入站 → `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.js

@@ -0,0 +1,47 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/napcat.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { NapCatHttpEndpoint } from "../lib/http-endpoint.js";
+import { resolveNapCatConfig } from "../lib/protocol.js";
+import { NapCatWsEndpoint } from "../lib/ws-endpoint.js";
+import { NapCatWssEndpoint } from "../lib/wss-endpoint.js";
+import { napcatRuntimeStateToken } from "../lib/napcat-runtime-state.js";
+export { NapCatHttpEndpoint, } from "../lib/http-endpoint.js";
+export { NapCatWsEndpoint, } from "../lib/ws-endpoint.js";
+export { NapCatWssEndpoint, } from "../lib/wss-endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // OneBot file 参数原生消费 url / base64:// 媒体，file:// 本地路径由 NapCat 侧读盘；
+    // 无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'base64', 'path'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveNapCatConfig(context.config);
+        // 注册到插件运行时状态（napcat.endpoint list 的"运行中"数据源）
+        context.use(napcatRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.connection,
+        });
+        if (config.connection === 'wss') {
+            return new NapCatWssEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        if (config.connection === 'http') {
+            return new NapCatHttpEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        return new NapCatWsEndpoint({ id: context.id, config });
+    },
+});

package/adapters/napcat.ts

@@ -0,0 +1,64 @@
+/**
+ * Convention entry: discover `adapters/napcat.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+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';
+import { napcatRuntimeStateToken } from '../src/napcat-runtime-state.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';
+
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    napcat: import('../src/ws-endpoint.js').NapCatWsEndpoint;
+  }
+}
+
+export default defineAdapter<NapCatAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // OneBot file 参数原生消费 url / base64:// 媒体，file:// 本地路径由 NapCat 侧读盘；
+  // 无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'base64', 'path'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveNapCatConfig(context.config);
+    // 注册到插件运行时状态（napcat.endpoint list 的"运行中"数据源）
+    context.use(napcatRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.connection,
+    });
+    if (config.connection === 'wss') {
+      return new NapCatWssEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    if (config.connection === 'http') {
+      return new NapCatHttpEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new NapCatWsEndpoint({ id: context.id, config });
+  },
+});

package/{skills/napcat → agent}/PERMITS.md

@@ -13,7 +13,7 @@ OneBot `sender.role` 透传：`owner` · `admin` · `member`。
 
 | `platform(napcat,…)` | 含义 |
 |----------------------|------|
-| `group_owner` | 群主 |
-| `group_admin` | 群管理员（含群主） |
+| `scene_owner` | 群主 |
+| `scene_admin` | 群管理员（含群主） |
 
-使用 core 默认 `createGroupRolePlatformChecker`。
+使用 core 默认 `createSceneRolePlatformChecker`。

package/{skills/napcat/SKILL.md → agent/skills/napcat.md}

@@ -110,8 +110,8 @@ NapCat 是 OneBot11 协议的超集实现，提供标准群管理之外大量 QQ
 工具分三个权限层级，调用前先判断 Endpoint 在群里的身份：
 
 - **user** — 普通成员即可，如查询、点赞、戳一戳
-- **group_admin** — 需要管理员权限，如踢人、禁言、设精华、发公告
-- **group_owner** — 需要群主权限，如设管理员、设专属头衔
+- **scene_admin** — 需要管理员权限，如踢人、禁言、设精华、发公告
+- **scene_owner** — 需要群主权限，如设管理员、设专属头衔
 
 如果 Endpoint 权限不足，API 会返回错误。遇到权限不足时，向用户说明需要什么权限，而不是重试。
 

package/agent/tools/ai_tts.ts

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

package/agent/tools/del_group_notice.ts

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

package/agent/tools/delete_essence_msg.ts

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

package/agent/tools/delete_friend.ts

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

package/agent/tools/download_file.ts

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

package/agent/tools/forward_single_msg.ts

@@ -0,0 +1,28 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{
+  target_type: 'friend' | 'group';
+  target_id: number;
+  message_id: number;
+}>({
+  description: '转发单条消息到指定好友或群。',
+  inputSchema: z.object({
+    target_type: z.enum(['friend', 'group']).describe('friend 或 group'),
+    target_id: z.number().describe('目标好友 QQ 号或群号'),
+    message_id: z.number().describe('要转发的消息 ID'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['转发', 'forward', '单条转发'],
+  async execute({ target_type, target_id, message_id }: {
+    target_type: 'friend' | 'group';
+    target_id: number;
+    message_id: number;
+  }, context) {
+    const endpoint = context.$client;
+    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,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ group_id: number }>({
+  description: '获取 AI 语音角色列表，用于 napcat_ai_tts 的 character 参数。',
+  inputSchema: z.object({
+    group_id: z.number().describe('群号'),
+  }),
+  adapter: 'napcat',
+  tags: ['napcat', 'qq'],
+  keywords: ['AI角色', 'ai characters', '语音角色'],
+  scopes: ['group'],
+  async execute({ group_id }: { group_id: number }, context) {
+    const endpoint = context.$client;
+      return endpoint.getAiCharacters(group_id);
+  },
+});

package/agent/tools/get_essence_list.ts

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

package/agent/tools/get_friend_msg_history.ts

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

package/agent/tools/get_group_file_url.ts

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

package/agent/tools/get_group_info_ex.ts

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

package/agent/tools/get_group_msg_history.ts

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

package/agent/tools/get_group_notice.ts

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

package/agent/tools/get_group_root_files.ts

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

package/agent/tools/get_group_shut_list.ts

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

package/agent/tools/get_mini_app_ark.ts

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