kokkoro-plugin-animetrace 1.0.0 → 1.0.2

package/README.md

@@ -8,10 +8,20 @@
 bun add kokkoro-plugin-animetrace
 ```
 
-发送「/搜角色」时附带图片，插件会识别消息中的第一张图片，并通过 QQ Markdown 展示结果。发送带图的「搜角色」也可以触发识别。
+发送「/搜角色」指令时附带图片，或引用包含图片的消息回复该指令。插件识别首张图片中的角色，并通过 QQ Markdown 返回结果。「搜角色」与「/搜角色」的用法相同。
 
 完整使用说明见 [AnimeTrace 角色识别](https://kokkoro.js.org/plugin/animetrace)。
 
+## 环境变量
+
+在项目根目录的 `.env` 中配置每个人物最多显示的候选角色数量：
+
+```ini
+ANIMETRACE_LIMIT=3
+```
+
+`ANIMETRACE_LIMIT` 必须为正整数，默认值为 `3`。
+
 ## API
 
 通过 `service` 入口导入 `fetchCharacters()` 获取完整响应，通过 `util` 入口导入 `createMarkdown()` 生成 QQ Markdown：
@@ -24,4 +34,6 @@ const { data } = await fetchCharacters('https://kokkoro.js.org/logo.png');
 const markdown = createMarkdown(data);
 ```
 
+`fetchCharacters()` 的第二个参数可传入日志记录器，记录完整请求参数和接口响应。
+
 `service` 入口同时导出 `ANIMETRACE_API`、`AnimeTrace` 和 `CharacterResult`。参数、响应字段和错误行为见 [插件 API 文档](https://kokkoro.js.org/plugin/animetrace#api)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokkoro-plugin-animetrace",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AnimeTrace 角色识别，查找图片中的动漫、游戏角色及所属作品。",
   "keywords": [
     "animetrace",

package/src/index.ts

@@ -1,31 +1,29 @@
 import { useCommand, useLogger } from '@kokkoro/core';
 
-import { ANIMETRACE_API, fetchCharacters } from './service';
+import { fetchCharacters } from './service';
 import { createMarkdown } from './util';
 
 const logger = useLogger();
 
 export default () => {
   useCommand('/搜角色', async context => {
-    const image = context.attachments?.find(attachment => attachment.content_type?.startsWith('image/'));
+    const [reference] = context.msg_elements ?? [];
+    const attachments = context.message_type === 103 ? reference?.attachments : context.attachments;
+    const images = attachments?.filter(attachment => attachment.content_type?.startsWith('image/')) ?? [];
+    const [image] = images;
 
     if (!image?.url) {
-      throw new Error('请在指令中附带需要识别的图片');
+      throw new Error('未检测到图片，请在指令消息中附带图片，或引用包含图片的消息后重试。');
     }
-    logger.debug('发送 AnimeTrace 请求', {
-      method: 'POST',
-      url: ANIMETRACE_API,
-      payload: { url: image.url, is_multi: 1, ai_detect: 0 },
-    });
-
-    const result = await fetchCharacters(image.url);
+    const result = await fetchCharacters(image.url, logger);
+    const { data, trace_id } = result;
+    const notice = images.length > 1 ? '检测到消息中包含多张图片，已选取首张图片进行识别。' : undefined;
 
-    logger.debug('收到 AnimeTrace 响应', result);
-    logger.info('已识别图片中的角色', { count: result.data.length, trace_id: result.trace_id });
+    logger.info('已识别图片中的角色', { count: data.length, trace_id });
 
     await context.reply({
       msg_type: 2,
-      markdown: { content: createMarkdown(result.data) },
+      markdown: { content: createMarkdown(data, notice) },
     });
   }).shortcut('搜角色');
 };

package/src/service.ts

@@ -1,3 +1,5 @@
+import { type Logger } from '@kokkoro/core';
+
 /** AnimeTrace v1 识别接口的请求地址。 */
 export const ANIMETRACE_API = 'https://api.animetrace.com/v1/search';
 
@@ -11,9 +13,9 @@ export interface AnimeTrace {
   readonly code: number;
   /** 是否判定为 AI 生成图片。 */
   readonly ai: boolean;
-  /** 本次识别的唯一 ID。 */
+  /** 本次识别的唯一 ID，反馈问题时使用。 */
   readonly trace_id: string;
-  /** 图片中各个人物的识别结果。 */
+  /** 检测到的每个人物的结果列表。 */
   readonly data: readonly CharacterResult[];
 }
 
@@ -21,11 +23,11 @@ export interface AnimeTrace {
 export interface CharacterResult {
   /** 人物位置 `[x1, y1, x2, y2]`，坐标相对于图片宽高，范围为 0 到 1。 */
   readonly box: readonly [number, number, number, number];
-  /** 检测框的唯一 ID。 */
+  /** 每个检测框的唯一 ID。 */
   readonly box_id: string;
-  /** 是否置信度较低，需要人工确认。 */
+  /** 置信度较低，候选较多，需人工确认。 */
   readonly not_confident: boolean;
-  /** 候选角色，越靠前可能性越大。 */
+  /** 候选角色列表，越靠前可能性越大。 */
   readonly character: readonly {
     /** 作品名称。 */
     readonly work: string;
@@ -35,26 +37,34 @@ export interface CharacterResult {
 }
 
 /** 使用 AnimeTrace 默认模型识别图片中的角色，并返回完整的接口响应。 */
-export async function fetchCharacters(url: string): Promise<AnimeTrace> {
+export async function fetchCharacters(url: string, logger?: Logger): Promise<AnimeTrace> {
+  const payload = { url, is_multi: '1', ai_detect: '0' };
   const form = new FormData();
 
-  form.set('url', url);
-  form.set('is_multi', '1');
-  form.set('ai_detect', '0');
+  for (const [key, value] of Object.entries(payload)) {
+    form.set(key, value);
+  }
+  logger?.debug('发送 AnimeTrace 请求', {
+    method: 'POST',
+    url: ANIMETRACE_API,
+    payload,
+  });
 
   const response = await fetch(ANIMETRACE_API, { method: 'POST', body: form });
 
   if (!response.ok) {
-    throw new Error(`接口请求失败，状态码 ${response.status}`);
+    throw new Error(`AnimeTrace 请求失败，HTTP 状态码 ${response.status}`);
   }
   const result = <AnimeTrace>await response.json();
 
+  logger?.debug('收到 AnimeTrace 响应', result);
+
   if (result.code !== 0) {
     throw new Error(`AnimeTrace 识别失败，状态码 ${result.code}`);
   }
 
   if (result.data.length === 0) {
-    throw new Error('没有识别到角色');
+    throw new Error('未识别到角色');
   }
   return result;
 }

package/src/util.ts

@@ -1,18 +1,33 @@
 import { type CharacterResult } from './service';
 
-/** 将 AnimeTrace 识别结果转换为 QQ Markdown。 */
-export function createMarkdown(results: readonly CharacterResult[]): string {
-  const lines = ['## AnimeTrace 搜索结果'];
+const { ANIMETRACE_LIMIT = '3' } = import.meta.env;
+const limit = Number(ANIMETRACE_LIMIT);
+
+if (!Number.isInteger(limit) || limit <= 0) {
+  throw new Error('ANIMETRACE_LIMIT 必须为正整数');
+}
+
+/** 将 AnimeTrace 识别结果转换为 QQ Markdown，可在标题下方展示提示。 */
+export function createMarkdown(results: readonly CharacterResult[], notice?: string): string {
+  const lines = ['## AnimeTrace 识别结果'];
+
+  if (notice) {
+    lines.push('', `> ${notice}`);
+  }
+
+  if (results.some(({ not_confident: isNotConfident }) => isNotConfident)) {
+    lines.push('', '> 标有 ＊ 的识别结果可能不准确，请注意甄别。');
+  }
 
   for (const [index, { character: candidates, not_confident: isNotConfident }] of results.entries()) {
-    if (results.length > 1) {
-      lines.push(`**人物 ${index + 1}**`);
-    }
-    lines.push(candidates.map(({ character, work }) => `- **${character}**  \n  ${work}`).join('\n'));
+    const prefix = results.length === 1 && isNotConfident ? '＊ ' : '';
 
-    if (isNotConfident) {
-      lines.push('> 识别置信度较低，请结合原图确认。');
+    lines.push('');
+
+    if (results.length > 1) {
+      lines.push(`**${isNotConfident ? '＊ ' : ''}人物 ${index + 1}**`);
     }
+    lines.push(...candidates.slice(0, limit).map(({ character, work }) => `- **${prefix}${character}**  \n  ${work}`));
   }
-  return lines.join('\n\n');
+  return lines.join('\n');
 }