kokkoro-plugin-animetrace 0.0.0 → 1.0.0

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,27 @@
 # kokkoro-plugin-animetrace
+
+使用 [AnimeTrace](https://www.animetrace.com/) 识别图片中的动漫、游戏角色及所属作品。
+
+## 安装
+
+```shell
+bun add kokkoro-plugin-animetrace
+```
+
+发送「/搜角色」时附带图片，插件会识别消息中的第一张图片，并通过 QQ Markdown 展示结果。发送带图的「搜角色」也可以触发识别。
+
+完整使用说明见 [AnimeTrace 角色识别](https://kokkoro.js.org/plugin/animetrace)。
+
+## 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);
+```
+
+`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.0",
+  "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,31 @@
-console.log('Ciallo～(∠·ω< )⌒★');
+import { useCommand, useLogger } from '@kokkoro/core';
+
+import { ANIMETRACE_API, 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('请在指令中附带需要识别的图片');
+    }
+    logger.debug('发送 AnimeTrace 请求', {
+      method: 'POST',
+      url: ANIMETRACE_API,
+      payload: { url: image.url, is_multi: 1, ai_detect: 0 },
+    });
+
+    const result = await fetchCharacters(image.url);
+
+    logger.debug('收到 AnimeTrace 响应', result);
+    logger.info('已识别图片中的角色', { count: result.data.length, trace_id: result.trace_id });
+
+    await context.reply({
+      msg_type: 2,
+      markdown: { content: createMarkdown(result.data) },
+    });
+  }).shortcut('搜角色');
+};

package/src/service.ts

@@ -0,0 +1,60 @@
+/** 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): Promise<AnimeTrace> {
+  const form = new FormData();
+
+  form.set('url', url);
+  form.set('is_multi', '1');
+  form.set('ai_detect', '0');
+
+  const response = await fetch(ANIMETRACE_API, { method: 'POST', body: form });
+
+  if (!response.ok) {
+    throw new Error(`接口请求失败，状态码 ${response.status}`);
+  }
+  const result = <AnimeTrace>await response.json();
+
+  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,18 @@
+import { type CharacterResult } from './service';
+
+/** 将 AnimeTrace 识别结果转换为 QQ Markdown。 */
+export function createMarkdown(results: readonly CharacterResult[]): string {
+  const lines = ['## AnimeTrace 搜索结果'];
+
+  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'));
+
+    if (isNotConfident) {
+      lines.push('> 识别置信度较低，请结合原图确认。');
+    }
+  }
+  return lines.join('\n\n');
+}