kokkoro-plugin-animetrace 0.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Yuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,39 @@
 # kokkoro-plugin-animetrace
+
+使用 [AnimeTrace](https://www.animetrace.com/) 识别图片中的动漫、游戏角色及所属作品。
+
+## 安装
+
+```shell
+bun add kokkoro-plugin-animetrace
+```
+
+发送「/搜角色」时附带图片，插件会识别消息中的第一张图片，并通过 QQ Markdown 展示结果。发送带图的「搜角色」也可以触发识别。
+
+完整使用说明见 [AnimeTrace 角色识别](https://kokkoro.js.org/plugin/animetrace)。
+
+## 环境变量
+
+在项目根目录的 `.env` 中设置每个人物展示的候选角色数量上限：
+
+```ini
+ANIMETRACE_LIMIT=3
+```
+
+`ANIMETRACE_LIMIT` 必须为正整数，默认值为 `3`。
+
+## API
+
+通过 `service` 入口导入 `fetchCharacters()` 获取完整响应，通过 `util` 入口导入 `createMarkdown()` 生成 QQ Markdown：
+
+```typescript
+import { fetchCharacters } from 'kokkoro-plugin-animetrace/service';
+import { createMarkdown } from 'kokkoro-plugin-animetrace/util';
+
+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,15 +1,32 @@
 {
   "name": "kokkoro-plugin-animetrace",
-  "version": "0.0.0",
-  "exports": "./src/index.ts",
+  "version": "1.0.1",
+  "description": "AnimeTrace 角色识别，查找图片中的动漫、游戏角色及所属作品。",
+  "keywords": [
+    "animetrace",
+    "bot",
+    "kokkoro",
+    "qq"
+  ],
+  "bugs": "https://github.com/kokkorojs/kokkoro/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kokkorojs/kokkoro.git",
+    "directory": "plugins/animetrace"
+  },
+  "license": "MIT",
+  "author": "Yuki <admin@yuki.sh>",
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./service": "./src/service.ts",
+    "./util": "./src/util.ts"
+  },
   "files": [
     "src"
   ],
-  "devDependencies": {
-    "@types/bun": "latest"
-  },
   "peerDependencies": {
-    "typescript": "^7"
+    "@kokkoro/core": "^3.1.4",
+    "typescript": "^6.0.3"
   }
 }

package/src/index.ts

@@ -1 +1,25 @@
-console.log('Ciallo～(∠·ω< )⌒★');
+import { useCommand, useLogger } from '@kokkoro/core';
+
+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/'));
+
+    if (!image?.url) {
+      throw new Error('请在指令中附带需要识别的图片');
+    }
+    const result = await fetchCharacters(image.url, logger);
+    const { data, trace_id } = result;
+
+    logger.info('已识别图片中的角色', { count: data.length, trace_id });
+
+    await context.reply({
+      msg_type: 2,
+      markdown: { content: createMarkdown(data) },
+    });
+  }).shortcut('搜角色');
+};

package/src/service.ts

@@ -0,0 +1,70 @@
+import { type Logger } from '@kokkoro/core';
+
+/** AnimeTrace v1 识别接口的请求地址。 */
+export const ANIMETRACE_API = 'https://api.animetrace.com/v1/search';
+
+/**
+ * AnimeTrace 识别响应。
+ *
+ * @see https://www.animetrace.com/api-docs/
+ */
+export interface AnimeTrace {
+  /** 状态码，`0` 表示成功。 */
+  readonly code: number;
+  /** 是否判定为 AI 生成图片。 */
+  readonly ai: boolean;
+  /** 本次识别的唯一 ID，反馈问题时使用。 */
+  readonly trace_id: string;
+  /** 检测到的每个人物的结果列表。 */
+  readonly data: readonly CharacterResult[];
+}
+
+/** AnimeTrace 返回的单个人物识别结果。 */
+export interface CharacterResult {
+  /** 人物位置 `[x1, y1, x2, y2]`，坐标相对于图片宽高，范围为 0 到 1。 */
+  readonly box: readonly [number, number, number, number];
+  /** 每个检测框的唯一 ID。 */
+  readonly box_id: string;
+  /** 置信度较低，候选较多，需人工确认。 */
+  readonly not_confident: boolean;
+  /** 候选角色列表，越靠前可能性越大。 */
+  readonly character: readonly {
+    /** 作品名称。 */
+    readonly work: string;
+    /** 角色名称。 */
+    readonly character: string;
+  }[];
+}
+
+/** 使用 AnimeTrace 默认模型识别图片中的角色，并返回完整的接口响应。 */
+export async function fetchCharacters(url: string, logger?: Logger): Promise<AnimeTrace> {
+  const payload = { url, is_multi: '1', ai_detect: '0' };
+  const form = new FormData();
+
+  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}`);
+  }
+  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('没有识别到角色');
+  }
+  return result;
+}

package/src/util.ts

@@ -0,0 +1,29 @@
+import { type CharacterResult } from './service';
+
+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[]): string {
+  const lines = ['## AnimeTrace 搜索结果'];
+
+  if (results.some(({ not_confident: isNotConfident }) => isNotConfident)) {
+    lines.push('', '> 带 ＊ 的人物可能识别不准确。');
+  }
+
+  for (const [index, { character: candidates, not_confident: isNotConfident }] of results.entries()) {
+    const prefix = results.length === 1 && isNotConfident ? '＊ ' : '';
+
+    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');
+}