@zhin.js/adapter-napcat 1.0.1 → 1.1.2

package/skills/napcat/SKILL.md

@@ -1,311 +0,0 @@
----
-name: napcat
-platforms:
-  - napcat
-description: >-
-  NapCatQQ 适配器完整能力集。当用户在 QQ 群或私聊中请求群管理（踢人、禁言、设管理、改名片、
-  设头衔）、社交互动（戳一戳、点赞、表情回应）、消息操作（合并转发、单条转发、
-  消息历史回溯）、群运营（精华消息、群公告、群签到、群文件管理）、多媒体能力（AI 语音
-  TTS、图片 OCR 文字识别、小程序卡片）、个人设置（修改资料/头像/签名/在线状态）、
-  或任何 QQ 特有功能时，都应使用此技能。即使用户没有明确提到 NapCat 或 OneBot，
-  只要上下文是 QQ 群聊/私聊场景且涉及上述能力，就应触发。覆盖 OneBot11 标准 +
-  go-cqhttp 扩展 + NapCat 独有 API 共 92 个接口。
-keywords:
-  - napcat
-  - napneko
-  - onebot11
-  - adapter:napcat
-  - qq
-  - 群管理
-  - 头衔
-  - 戳一戳
-  - 表情回应
-  - 合并转发
-  - 群文件
-  - 精华消息
-  - 群公告
-  - AI语音
-  - OCR
-  - 小程序
-  - list_members
-  - 禁言
-  - 踢人
-  - 点赞
-  - 签到
-  - 转发
-  - 语音
-  - 翻译
-  - 头像
-  - 在线状态
-tags:
-  - group
-  - management
-  - im
-  - qq
-  - napcat
-tools:
-  - napcat_kick_member
-  - napcat_mute_member
-  - napcat_mute_all
-  - napcat_set_admin
-  - napcat_set_nickname
-  - napcat_set_group_name
-  - napcat_list_members
-  - napcat_get_group_info
-  - napcat_send_poke
-  - napcat_set_emoji_reaction
-  - napcat_send_forward_msg
-  - napcat_forward_single_msg
-  - napcat_send_like
-  - napcat_set_essence_msg
-  - napcat_delete_essence_msg
-  - napcat_get_essence_list
-  - napcat_send_group_notice
-  - napcat_get_group_notice
-  - napcat_del_group_notice
-  - napcat_upload_group_file
-  - napcat_get_group_file_url
-  - napcat_get_group_root_files
-  - napcat_get_group_shut_list
-  - napcat_set_group_portrait
-  - napcat_set_title
-  - napcat_group_sign
-  - napcat_ai_tts
-  - napcat_get_ai_characters
-  - napcat_ocr_image
-  - napcat_get_mini_app_ark
-  - napcat_get_group_msg_history
-  - napcat_get_friend_msg_history
-  - napcat_get_user_status
-  - napcat_get_group_info_ex
-  - napcat_set_profile
-  - napcat_set_avatar
-  - napcat_set_online_status
-  - napcat_set_signature
-  - napcat_translate
-  - napcat_mark_msg_as_read
-  - napcat_download_file
-  - napcat_delete_friend
----
-
-# NapCat QQ 适配器技能
-
-NapCat 是 OneBot11 协议的超集实现，提供标准群管理之外大量 QQ 特有功能。这份技能帮助你正确选择工具、组合调用、处理边界情况。
-
-## 核心原则
-
-### 先查后操作
-
-用户说「把小明踢了」，但工具需要的是 QQ 号（数字），不是昵称。所有针对具体成员的操作，如果手头只有昵称/名片，第一步永远是 `napcat_list_members` 获取成员列表，从中匹配到 `user_id`，然后再执行后续操作。不要猜测 QQ 号。
-
-**Example:**
-```
-用户: 把群里那个叫"小飞"的禁言10分钟
-步骤1: napcat_list_members → 找到 小飞 的 user_id = 123456
-步骤2: napcat_mute_member(user_id=123456, duration=600)
-```
-
-### 权限意识
-
-工具分三个权限层级，调用前先判断 Endpoint 在群里的身份：
-
-- **user** — 普通成员即可，如查询、点赞、戳一戳
-- **group_admin** — 需要管理员权限，如踢人、禁言、设精华、发公告
-- **group_owner** — 需要群主权限，如设管理员、设专属头衔
-
-如果 Endpoint 权限不足，API 会返回错误。遇到权限不足时，向用户说明需要什么权限，而不是重试。
-
-### 数值单位
-
-- **禁言 duration**：单位是秒。600 = 10 分钟，3600 = 1 小时，86400 = 1 天。设为 **0** 是解除禁言，不是永久禁言。
-- **message_id**：消息收到时自带的数字 ID，用于回应、精华、转发等操作。
-- **group_id / user_id**：QQ 号，纯数字。
-
----
-
-## 工具分类与使用指南
-
-### 群管理（基础）
-
-日常群管理操作。Bot 需要管理员权限（`set_admin` 需群主权限）。
-
-| 工具 | 用途 | 关键参数 |
-|------|------|----------|
-| `napcat_kick_member` | 踢出成员 | `user_id` |
-| `napcat_mute_member` | 禁言/解禁 | `user_id`, `duration`（秒，0=解禁） |
-| `napcat_mute_all` | 全员禁言/解除 | `enable`（true/false） |
-| `napcat_set_admin` | 设/取消管理员 | `user_id`, `enable` |
-| `napcat_set_nickname` | 改群名片 | `user_id`, `nickname` |
-| `napcat_set_group_name` | 改群名称 | `name` |
-| `napcat_set_title` | 设专属头衔 | `user_id`, `title`（需群主） |
-| `napcat_list_members` | 获取成员列表 | — |
-| `napcat_get_group_info` | 获取群基本信息 | — |
-| `napcat_get_group_info_ex` | 获取群详细信息 | — |
-| `napcat_get_group_shut_list` | 获取当前禁言列表 | — |
-
-**批量禁言场景：** 用户说「把最近刷屏的人都禁言」时，先用 `napcat_get_group_msg_history` 分析最近消息，识别刷屏用户，然后逐个 `napcat_mute_member`。
-
-### 社交互动
-
-不需要管理员权限的轻量交互。
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `napcat_send_poke` | 戳一戳 | `group_id` 不传 = 私聊戳 |
-| `napcat_set_emoji_reaction` | 表情回应 | 对某条消息贴表情，需 `message_id` + `emoji_id` |
-| `napcat_send_like` | 给好友点赞 | 每人每天上限 10 次 |
-| `napcat_group_sign` | 群签到/打卡 | 每天一次 |
-
-**Example:**
-```
-用户: 戳一下群里的张三
-步骤1: napcat_list_members → 找到张三 user_id = 789
-步骤2: napcat_send_poke(user_id=789, group_id=当前群号)
-```
-
-### 消息操作
-
-转发、历史查询是 NapCat 超越标准 OneBot11 的核心能力。
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `napcat_send_forward_msg` | 合并转发 | 多条消息打包为一条转发消息 |
-| `napcat_forward_single_msg` | 单条转发 | 把某条消息转到另一个群/好友 |
-| `napcat_get_group_msg_history` | 群消息历史 | 支持指定起始序号和条数 |
-| `napcat_get_friend_msg_history` | 私聊历史 | 同上 |
-| `napcat_mark_msg_as_read` | 标记已读 | — |
-
-**合并转发的 messages 格式：**
-
-`messages` 参数是 JSON 字符串，每个元素是一个 node 节点：
-
-```json
-[
-  {
-    "type": "node",
-    "data": {
-      "name": "发送者昵称",
-      "uin": "10001",
-      "content": [{"type": "text", "data": {"text": "消息内容"}}]
-    }
-  }
-]
-```
-
-也可以用 `id` 引用已有消息：`{"type": "node", "data": {"id": "消息ID"}}`
-
-### 群运营
-
-精华消息、群公告、群文件、群头像 — 让群看起来正规且有序。
-
-| 工具 | 用途 | 权限 |
-|------|------|------|
-| `napcat_set_essence_msg` | 设为精华消息 | admin |
-| `napcat_delete_essence_msg` | 取消精华 | admin |
-| `napcat_get_essence_list` | 精华消息列表 | user |
-| `napcat_send_group_notice` | 发群公告 | admin |
-| `napcat_get_group_notice` | 查看公告 | user |
-| `napcat_del_group_notice` | 删除公告 | admin |
-| `napcat_upload_group_file` | 上传群文件 | user |
-| `napcat_get_group_file_url` | 获取文件下载链接 | user |
-| `napcat_get_group_root_files` | 群文件列表 | user |
-| `napcat_set_group_portrait` | 修改群头像 | admin |
-
-**群公告带图：** `napcat_send_group_notice` 的 `image` 参数支持 URL 或 base64，方便把生成的图片直接发到公告里。
-
-**群文件工作流：** 用户说「帮我把这个文件发到群里」→ 用 `napcat_upload_group_file`，`file` 可以是本地路径或 URL。如果用户问「群里那个文件在哪下载」→ 先 `napcat_get_group_root_files` 列出文件，找到 `file_id` 和 `busid`，再 `napcat_get_group_file_url` 获取下载链接。
-
-### AI 与多媒体
-
-NapCat 独有的多媒体处理能力，标准 OneBot11 不支持这些。
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `napcat_ai_tts` | AI 文字转语音 | 在群里发语音，需指定角色 |
-| `napcat_get_ai_characters` | 语音角色列表 | 配合 ai_tts 使用 |
-| `napcat_ocr_image` | 图片文字识别 | 传入图片的 file 字段 |
-| `napcat_get_mini_app_ark` | 小程序卡片签名 | 生成可分享的小程序卡片 |
-| `napcat_translate` | 英译中翻译 | NapCat 内置翻译 |
-| `napcat_download_file` | 下载文件到缓存 | 返回本地路径 |
-
-**AI 语音工作流：** 用户说「用甜美女声读一段话」→ 先 `napcat_get_ai_characters` 列出可用角色，从中选择匹配的 `character_id`，然后 `napcat_ai_tts(character=所选ID, text=要读的内容)`。角色列表因群不同可能不一样，所以每次都应重新查询。
-
-**OCR 使用：** 当用户发了一张带文字的图片并问「这上面写了什么」，从消息中提取图片的 `file` 字段（通常是 `file://...` 或一个 hash），传给 `napcat_ocr_image`。
-
-### 个人设置
-
-修改 Endpoint 自身的 QQ 资料，通常是用户明确要求时才使用。
-
-| 工具 | 用途 |
-|------|------|
-| `napcat_set_profile` | 修改昵称、公司、邮箱等 |
-| `napcat_set_avatar` | 换头像（URL 或 base64） |
-| `napcat_set_online_status` | 设在线状态 |
-| `napcat_set_signature` | 设个性签名 |
-| `napcat_delete_friend` | 删除好友 |
-| `napcat_get_user_status` | 查看某人在线状态 |
-
-**在线状态码：** 11=在线, 21=离开, 31=隐身, 41=忙碌, 50=请勿打扰, 60=Q我吧。
-
----
-
-## 常见场景决策树
-
-### 用户想管理群成员
-
-```
-用户提供了 QQ 号？
-  ├─ 是 → 直接操作
-  └─ 否（只有昵称/名片）
-      └─ napcat_list_members → 匹配 → 操作
-```
-
-### 用户想查看/操作消息历史
-
-```
-群聊还是私聊？
-  ├─ 群聊 → napcat_get_group_msg_history(group_id)
-  └─ 私聊 → napcat_get_friend_msg_history(user_id)
-
-想转发其中某条？
-  ├─ 转单条 → napcat_forward_single_msg(message_id)
-  └─ 打包多条 → napcat_send_forward_msg(messages=[node...])
-```
-
-### 用户想发语音
-
-```
-napcat_get_ai_characters(group_id) → 列出角色
-选择最匹配的 character_id
-napcat_ai_tts(group_id, character, text)
-```
-
-### 用户想发公告/管理精华
-
-```
-发新公告 → napcat_send_group_notice(content, image?)
-查看公告 → napcat_get_group_notice
-删除公告 → 先 get 拿到 notice_id → napcat_del_group_notice
-
-设精华 → napcat_set_essence_msg(message_id)
-取消精华 → napcat_delete_essence_msg(message_id)
-看精华列表 → napcat_get_essence_list
-```
-
----
-
-## 易错点
-
-1. **禁言 duration=0 是解禁**，不是永久禁言。没有「永久禁言」的概念，最长可以设很大的数（如 2592000 = 30 天）。
-
-2. **合并转发的 messages 必须是 JSON 字符串**，不是对象。工具内部会解析，但传参时要传字符串化的 JSON。
-
-3. **头衔（set_title）只有群主能设**，管理员不行。用户说「给他加个头衔」但 Endpoint 不是群主时，需告知无法操作。
-
-4. **点赞有每日上限**（每人 10 次），用户说「给他点 100 个赞」时要说明限制。
-
-5. **AI 语音只能在群聊用**，私聊不支持。如果用户在私聊请求 AI 语音，建议改用群聊。
-
-6. **群文件操作需要 file_id 和 busid 两个参数**，它们来自 `get_group_root_files` 的返回，不要编造。
-
-7. **OCR 的 image 参数**不是图片 URL，而是消息中图片的 `file` 字段值（形如 `xxxxx.image` 或本地路径）。

package/src/adapter.ts

@@ -1,101 +0,0 @@
-/**
- * NapCat 适配器：支持正向 WS / 反向 WS / HTTP
- */
-import { formatCompact, Adapter, Plugin } from 'zhin.js';
-import type { Router } from '@zhin.js/host-router';
-import { NapCatWsClient } from './endpoint-ws-client.js';
-import { NapCatWsServer } from './endpoint-ws-server.js';
-import { NapCatHttpEndpoint } from './endpoint-http.js';
-import type { NapCatEndpointConfig, NapCatWsClientConfig, NapCatWsServerConfig, NapCatHttpConfig } from './types.js';
-
-export type NapCatEndpoint = NapCatWsClient | NapCatWsServer | NapCatHttpEndpoint;
-
-export class NapCatAdapter extends Adapter<NapCatEndpoint> {
-  static override readonly capabilities = ['inbound', 'outbound'] as const;
-
-  #router?: Router;
-
-  constructor(plugin: Plugin) {
-    super(plugin, 'napcat', []);
-  }
-
-  createEndpoint(config: NapCatEndpointConfig): NapCatEndpoint {
-    const connection = config.connection ?? 'ws';
-    switch (connection) {
-      case 'ws':
-        return new NapCatWsClient(this, config as NapCatWsClientConfig);
-      case 'wss':
-        if (!this.#router) throw new Error('NapCat connection: wss requires router. Enable @zhin.js/host-router first.');
-        return new NapCatWsServer(this, this.#router, config as NapCatWsServerConfig);
-      case 'http':
-        if (!this.#router) throw new Error('NapCat connection: http requires router. Enable @zhin.js/host-router first.');
-        return new NapCatHttpEndpoint(this, this.#router, config as NapCatHttpConfig);
-      default:
-        throw new Error(`Unknown NapCat connection: ${connection}`);
-    }
-  }
-
-  // ── 群管理接口（IGroupManagement 适配）──────────────────────────
-
-  async kickMember(endpointId: string, sceneId: string, userId: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.kickMember(Number(sceneId), Number(userId));
-  }
-
-  async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.muteMember(Number(sceneId), Number(userId), duration);
-  }
-
-  async muteAll(endpointId: string, sceneId: string, enable = true) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.muteAll(Number(sceneId), enable);
-  }
-
-  async setAdmin(endpointId: string, sceneId: string, userId: string, enable = true) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.setAdmin(Number(sceneId), Number(userId), enable);
-  }
-
-  async setMemberNickname(endpointId: string, sceneId: string, userId: string, nickname: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.setCard(Number(sceneId), Number(userId), nickname);
-  }
-
-  async setGroupName(endpointId: string, sceneId: string, name: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.setGroupName(Number(sceneId), name);
-  }
-
-  async listMembers(endpointId: string, sceneId: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    const members = await endpoint.getMemberList(Number(sceneId));
-    return {
-      members: members.map((m: any) => ({
-        user_id: m.user_id, nickname: m.nickname, card: m.card, role: m.role, title: m.title,
-      })),
-      count: members.length,
-    };
-  }
-
-  async getGroupInfo(endpointId: string, sceneId: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} not found`);
-    return endpoint.getGroupInfo(Number(sceneId));
-  }
-
-  async start(): Promise<void> {
-    this.#router = (this.plugin.inject as (key: string) => Router | undefined)('router');
-    (this.plugin.useContext as (key: string, fn: (router: Router) => void) => void)('router', (router: Router) => {
-      this.#router = router;
-    });
-    await super.start();
-  }
-}

package/src/agent-prompt.ts

@@ -1,114 +0,0 @@
-import type {
-  AgentPromptBuildContext,
-  AgentPromptContributor,
-  AgentPromptSection,
-  AgentTool,
-} from 'zhin.js';
-import { filterTools } from 'zhin.js';
-
-function isNapCatDelegatedTask(query: string, goal: string): boolean {
-  const text = `${query} ${goal}`;
-  if (/\bnapcat\b|napcat_|mcp_napcat/i.test(text)) return true;
-  if (/戳一戳|poke|表情回应|emoji.*reaction/i.test(text)) return true;
-  if (/精华消息|essence|群公告|group.*notice/i.test(text)) return true;
-  if (/AI语音|ai.*record|tts|文字转语音/i.test(text)) return true;
-  if (/群文件|upload.*file|群签到|group.*sign/i.test(text)) return true;
-  if (/合并转发|forward.*msg|转发消息/i.test(text)) return true;
-  if (/点赞/.test(text) && /qq|好友|\d{5,}/i.test(text)) return true;
-  return false;
-}
-
-function selectNapCatDeferredTools(
-  query: string,
-  goal: string,
-  deferredCatalog: AgentTool[],
-  maxTools: number,
-): AgentTool[] {
-  const pool = deferredCatalog.filter(
-    t => !t.name.startsWith('mcp_filesystem') && !t.name.startsWith('mcp_memory_'),
-  );
-  const napcatTools = pool.filter(t => t.name.startsWith('napcat_'));
-  const pinned: AgentTool[] = [];
-  const preferOrder = [
-    'napcat_send_poke',
-    'napcat_set_emoji_reaction',
-    'napcat_send_like',
-    'napcat_set_essence_msg',
-    'napcat_send_group_notice',
-    'napcat_ai_tts',
-  ];
-  for (const name of preferOrder) {
-    const t = napcatTools.find(x => x.name === name);
-    if (t) pinned.push(t);
-  }
-  for (const t of napcatTools) {
-    if (pinned.length >= maxTools) break;
-    if (!pinned.some(p => p.name === t.name)) pinned.push(t);
-  }
-
-  const extra = filterTools(query, pool, { maxTools, minScore: 0.08 })
-    .filter(t => !pinned.some(p => p.name === t.name));
-
-  const merged: AgentTool[] = [...pinned];
-  for (const t of extra) {
-    if (merged.length >= maxTools) break;
-    merged.push(t);
-  }
-  return merged.slice(0, maxTools);
-}
-
-const ORCHESTRATOR_NAPCAT = [
-  'On napcat/QQ: use run_deferred_task with tool_query "napcat_send_poke" or "napcat_set_emoji_reaction".',
-  'NapCat supports: poke, emoji reaction, forward msg, essence, group notice, AI TTS, OCR, group files.',
-  'Skip tool_search when the user clearly asks for QQ-specific features like poke, reaction, or group management.',
-].join('\n');
-
-const WORKER_NAPCAT = [
-  '- Use `napcat_send_poke` for poke/戳一戳.',
-  '- Use `napcat_set_emoji_reaction` for emoji reaction/表情回应.',
-  '- Use `napcat_send_like` for friend like/点赞.',
-  '- Use `napcat_ai_tts` for AI voice/AI语音.',
-  '- Use `napcat_set_essence_msg` / `napcat_delete_essence_msg` for essence messages.',
-  '- Use `napcat_send_group_notice` for group announcements.',
-  '- Do NOT use mcp_filesystem_* or explore node_modules for QQ tasks.',
-].join('\n');
-
-export function createNapCatAgentPromptContributor(): AgentPromptContributor {
-  return {
-    platform: 'napcat',
-
-    async buildSections(ctx: AgentPromptBuildContext): Promise<AgentPromptSection[] | null> {
-      if (ctx.slot === 'orchestrator') {
-        return [{
-          id: 'platform.napcat.orchestrator',
-          title: '## napcat / QQ',
-          body: ORCHESTRATOR_NAPCAT,
-          priority: 50,
-        }];
-      }
-      if (ctx.slot === 'deferred_worker') {
-        const query = ctx.deferred?.toolQuery ?? ctx.deferred?.goal ?? '';
-        const goal = ctx.deferred?.goal ?? '';
-        if (!isNapCatDelegatedTask(query, goal)) return null;
-        return [{
-          id: 'platform.napcat.deferred_worker',
-          title: '## napcat / QQ（本任务）',
-          body: WORKER_NAPCAT,
-          priority: 50,
-        }];
-      }
-      return null;
-    },
-
-    matchesDeferredTask(ctx: AgentPromptBuildContext): boolean {
-      const query = ctx.deferred?.toolQuery ?? ctx.deferred?.goal ?? ctx.userMessagePreview ?? '';
-      const goal = ctx.deferred?.goal ?? ctx.userMessagePreview ?? '';
-      return isNapCatDelegatedTask(query, goal);
-    },
-
-    selectDeferredTools(query, goal, catalog, maxTools) {
-      if (!isNapCatDelegatedTask(query, goal)) return null;
-      return selectNapCatDeferredTools(query, goal, catalog, maxTools);
-    },
-  };
-}