koishi-plugin-rolecard 1.0.0

package/lib/core.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 角色卡核心引擎。
+ *
+ * `RolecardEngine` 是与具体角色完全解耦的通用台词引擎。它接收一个已加载的
+ * `Rolecard`（纯数据）和 `Config`（运行时参数），负责：
+ *
+ * 1. 将台词按标签索引，供关键词命中后随机取用
+ * 2. 按优先级匹配消息中的触发词
+ * 3. 未命中关键词时按概率随机触发
+ * 4. 分频道冷却控制（支持白名单豁免）
+ * 5. 按配置决定是否附带插图、插图发送方式
+ * 6. 按配置限定响应范围（群聊 / 私聊 / 两者）
+ *
+ * 任何新角色卡只要提供符合 `types.ts` 契约的数据文件即可被引擎驱动，
+ * 无需修改本模块任何代码。
+ */
+import type { Context } from 'koishi';
+import type { Config, Rolecard } from './types';
+export declare class RolecardEngine {
+    private readonly config;
+    private readonly logger;
+    private readonly quotesByTag;
+    private readonly allQuotes;
+    private readonly groups;
+    private imageBuffer;
+    private readonly lastTrigger;
+    constructor(ctx: Context, rolecard: Rolecard, config: Config);
+    private handle;
+}

package/lib/core.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * 角色卡核心引擎。
+ *
+ * `RolecardEngine` 是与具体角色完全解耦的通用台词引擎。它接收一个已加载的
+ * `Rolecard`（纯数据）和 `Config`（运行时参数），负责：
+ *
+ * 1. 将台词按标签索引，供关键词命中后随机取用
+ * 2. 按优先级匹配消息中的触发词
+ * 3. 未命中关键词时按概率随机触发
+ * 4. 分频道冷却控制（支持白名单豁免）
+ * 5. 按配置决定是否附带插图、插图发送方式
+ * 6. 按配置限定响应范围（群聊 / 私聊 / 两者）
+ *
+ * 任何新角色卡只要提供符合 `types.ts` 契约的数据文件即可被引擎驱动，
+ * 无需修改本模块任何代码。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RolecardEngine = void 0;
+const node_fs_1 = require("node:fs");
+const koishi_1 = require("koishi");
+/** 从数组中随机取一个元素。 */
+function pick(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+class RolecardEngine {
+    config;
+    logger;
+    quotesByTag = new Map();
+    allQuotes;
+    groups;
+    imageBuffer = null;
+    lastTrigger = new Map();
+    constructor(ctx, rolecard, config) {
+        this.config = config;
+        this.logger = ctx.logger(`rolecard:${rolecard.manifest.id}`);
+        // 按标签建立台词索引
+        for (const q of rolecard.words.quotes) {
+            for (const tag of q.tags) {
+                let list = this.quotesByTag.get(tag);
+                if (!list) {
+                    list = [];
+                    this.quotesByTag.set(tag, list);
+                }
+                list.push(q);
+            }
+        }
+        this.allQuotes = rolecard.words.quotes;
+        // 按优先级排序触发词分组（数字越小越优先）
+        this.groups = [...rolecard.triggers.groups].sort((a, b) => a.priority - b.priority);
+        // 预加载插图到内存
+        if (rolecard.imagePath) {
+            try {
+                this.imageBuffer = (0, node_fs_1.readFileSync)(rolecard.imagePath);
+            }
+            catch {
+                this.imageBuffer = null;
+            }
+        }
+        else {
+            this.logger.warn('未找到角色卡插图，将不发送图片');
+        }
+        ctx.on('message', (session) => this.handle(session));
+        this.logger.info(`角色卡已加载：${rolecard.manifest.name}`);
+    }
+    async handle(session) {
+        // 响应范围控制
+        const isGroup = !!session.guildId;
+        if (isGroup && this.config.respondIn === 'private')
+            return;
+        if (!isGroup && this.config.respondIn === 'group')
+            return;
+        // 忽略自身与空用户
+        if (!session.userId || session.userId === session.selfId)
+            return;
+        // 纯文本：剥离 koishi 元素标签（如 <at id="..."/>）
+        const raw = session.content ?? '';
+        const content = raw.replace(/<[^>]+>/g, '');
+        if (!content)
+            return;
+        const channelId = session.channelId ?? session.guildId ?? session.userId;
+        const now = Date.now();
+        // 冷却控制（白名单豁免）
+        if (!this.config.cooldownWhitelist.includes(session.userId)) {
+            const last = this.lastTrigger.get(channelId) ?? 0;
+            if (now - last < this.config.cooldown * 1000)
+                return;
+        }
+        // 1. 按优先级匹配关键词
+        let matchedTag = null;
+        for (const g of this.groups) {
+            if (this.config.disabledTags.includes(g.tag))
+                continue;
+            if (g.matchMode === 'include' && g.keywords.some((k) => content.includes(k))) {
+                matchedTag = g.tag;
+                break;
+            }
+        }
+        // 2. 未命中关键词时按概率随机触发
+        let quote = null;
+        if (matchedTag) {
+            quote = pick(this.quotesByTag.get(matchedTag) ?? this.allQuotes);
+        }
+        else if (this.config.enableRandom &&
+            Math.random() * 100 < this.config.randomProbability) {
+            quote = pick(this.allQuotes);
+        }
+        if (!quote)
+            return;
+        // 标记触发时间
+        this.lastTrigger.set(channelId, now);
+        // 构建并发送消息
+        try {
+            const wantImage = this.config.enableImage &&
+                !!this.imageBuffer &&
+                Math.random() * 100 < this.config.imageProbability;
+            if (wantImage && this.imageBuffer) {
+                if (this.config.imageWithMessage) {
+                    await session.send([
+                        koishi_1.h.text(quote.text),
+                        koishi_1.h.image(this.imageBuffer, 'image/png'),
+                    ]);
+                }
+                else {
+                    await session.send(quote.text);
+                    await session.send(koishi_1.h.image(this.imageBuffer, 'image/png'));
+                }
+            }
+            else {
+                await session.send(quote.text);
+            }
+        }
+        catch (e) {
+            this.logger.warn('发送消息失败', e);
+        }
+    }
+}
+exports.RolecardEngine = RolecardEngine;

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * koishi-plugin-rolecard 插件入口。
+ *
+ * 架构概览：
+ *
+ * - `types.ts`   共享类型契约（角色卡内容 + 运行时配置）
+ * - `loader.ts`  角色卡加载器（扫描并解析 rolecards/ 目录）
+ * - `core.ts`    核心引擎（通用台词引擎，与具体角色解耦）
+ * - `index.ts`   本文件，组装三者并对接 Koishi 生命周期
+ *
+ * 角色卡是纯数据资源，存放在 `rolecards/<id>/` 下。用户通过 Config.rolecard
+ * 选择要激活的角色卡。新增角色卡只需添加数据目录，无需改动任何源码。
+ */
+import type { Context } from 'koishi';
+import { Schema } from 'koishi';
+import type { Config as ConfigType } from './types';
+export declare const name = "rolecard";
+export declare const usage = "\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #4a6ee0;\">\uD83C\uDFAD \u89D2\u8272\u5361\u63D2\u4EF6 \u00B7 Rolecard</h2>\n  <p>\u6570\u636E\u9A71\u52A8\u7684\u89D2\u8272\u53F0\u8BCD\u5F15\u64CE\u3002\u6838\u5FC3\u903B\u8F91\u4E0E\u89D2\u8272\u5361\u5185\u5BB9\u5B8C\u5168\u89E3\u8026\u2014\u2014\u89D2\u8272\u5361\u662F\u7EAF\u6570\u636E\u8D44\u6E90\uFF08\u53F0\u8BCD\u5E93 + \u89E6\u53D1\u8BCD + \u63D2\u56FE\uFF09\uFF0C\u5F15\u64CE\u6839\u636E\u6570\u636E\u81EA\u52A8\u9A71\u52A8\u5BF9\u8BDD\u3002</p>\n  <ul>\n    <li>\u5728 <code>rolecards/</code> \u76EE\u5F55\u4E0B\u653E\u7F6E\u89D2\u8272\u5361\uFF0C\u6BCF\u4E2A\u89D2\u8272\u5361\u4E00\u4E2A\u5B50\u76EE\u5F55</li>\n    <li>\u901A\u8FC7\u914D\u7F6E\u9879 <code>rolecard</code> \u9009\u62E9\u8981\u52A0\u8F7D\u7684\u89D2\u8272\u5361 ID</li>\n    <li>\u652F\u6301\u5173\u952E\u8BCD\u89E6\u53D1\uFF08\u6309\u4F18\u5148\u7EA7\uFF09\u4E0E\u6982\u7387\u968F\u673A\u89E6\u53D1</li>\n    <li>\u51B7\u5374\u9632\u5237\u5C4F\u3001\u63D2\u56FE\u53D1\u9001\u3001\u54CD\u5E94\u8303\u56F4\u5747\u53EF\u914D\u7F6E</li>\n  </ul>\n</div>\n";
+export declare const Config: Schema<ConfigType>;
+export declare function apply(ctx: Context, config: ConfigType): void;

package/lib/index.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * koishi-plugin-rolecard 插件入口。
+ *
+ * 架构概览：
+ *
+ * - `types.ts`   共享类型契约（角色卡内容 + 运行时配置）
+ * - `loader.ts`  角色卡加载器（扫描并解析 rolecards/ 目录）
+ * - `core.ts`    核心引擎（通用台词引擎，与具体角色解耦）
+ * - `index.ts`   本文件，组装三者并对接 Koishi 生命周期
+ *
+ * 角色卡是纯数据资源，存放在 `rolecards/<id>/` 下。用户通过 Config.rolecard
+ * 选择要激活的角色卡。新增角色卡只需添加数据目录，无需改动任何源码。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.usage = exports.name = void 0;
+exports.apply = apply;
+const node_path_1 = require("node:path");
+const koishi_1 = require("koishi");
+const core_1 = require("./core");
+const loader_1 = require("./loader");
+exports.name = 'rolecard';
+exports.usage = `
+<div style="border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);">
+  <h2 style="margin-top: 0; color: #4a6ee0;">🎭 角色卡插件 · Rolecard</h2>
+  <p>数据驱动的角色台词引擎。核心逻辑与角色卡内容完全解耦——角色卡是纯数据资源（台词库 + 触发词 + 插图），引擎根据数据自动驱动对话。</p>
+  <ul>
+    <li>在 <code>rolecards/</code> 目录下放置角色卡，每个角色卡一个子目录</li>
+    <li>通过配置项 <code>rolecard</code> 选择要加载的角色卡 ID</li>
+    <li>支持关键词触发（按优先级）与概率随机触发</li>
+    <li>冷却防刷屏、插图发送、响应范围均可配置</li>
+  </ul>
+</div>
+`;
+exports.Config = koishi_1.Schema.object({
+    rolecard: koishi_1.Schema.string()
+        .default('')
+        .description('要加载的角色卡 ID（留空则自动加载第一个找到的角色卡）。例如：belikov'),
+    cooldown: koishi_1.Schema.number()
+        .default(60)
+        .min(0)
+        .description('冷却时间（秒），同一频道内两次触发的最小间隔，防止刷屏'),
+    cooldownWhitelist: koishi_1.Schema.array(koishi_1.Schema.string())
+        .default([])
+        .description('冷却白名单：填入用户 ID，这些用户的消息不受冷却限制'),
+    disabledTags: koishi_1.Schema.array(koishi_1.Schema.string())
+        .default([])
+        .description('禁用的触发标签（留空表示全部启用）。例如填入 emotional 可关闭「情绪」类触发'),
+    enableRandom: koishi_1.Schema.boolean()
+        .default(true)
+        .description('启用全部消息概率随机触发（神预言效果）'),
+    randomProbability: koishi_1.Schema.number()
+        .default(3)
+        .min(0)
+        .max(100)
+        .description('随机触发概率（0-100，3 表示 3%）'),
+    enableImage: koishi_1.Schema.boolean().default(true).description('启用角色卡插图'),
+    imageWithMessage: koishi_1.Schema.boolean()
+        .default(true)
+        .description('将图片与文字一起发送（关闭则图片作为单独消息发送）'),
+    imageProbability: koishi_1.Schema.number()
+        .default(100)
+        .min(0)
+        .max(100)
+        .description('附带图片的概率（0-100，100 表示每次触发都发图）'),
+    respondIn: koishi_1.Schema.union([
+        koishi_1.Schema.const('group').description('仅群聊'),
+        koishi_1.Schema.const('private').description('仅私聊'),
+        koishi_1.Schema.const('both').description('群聊与私聊'),
+    ])
+        .default('group')
+        .description('响应范围'),
+});
+function apply(ctx, config) {
+    const logger = ctx.logger('rolecard');
+    // 角色卡目录位于插件包根目录下的 rolecards/
+    const rolecardsDir = (0, node_path_1.resolve)(__dirname, '..', 'rolecards');
+    const rolecards = (0, loader_1.loadRolecards)(rolecardsDir);
+    if (rolecards.length === 0) {
+        logger.warn('未找到任何角色卡，请检查 rolecards 目录');
+        return;
+    }
+    const availableIds = rolecards.map((r) => r.manifest.id).join(', ');
+    logger.info(`发现角色卡：${availableIds}`);
+    // 按配置选择角色卡；留空则取第一个
+    const selected = config.rolecard
+        ? rolecards.filter((r) => r.manifest.id === config.rolecard)
+        : [rolecards[0]];
+    if (selected.length === 0) {
+        logger.warn(`未找到角色卡 "${config.rolecard}"，可用：${availableIds}`);
+        return;
+    }
+    for (const rolecard of selected) {
+        new core_1.RolecardEngine(ctx, rolecard, config);
+    }
+}

package/lib/loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 角色卡加载器。
+ *
+ * 负责从磁盘扫描并解析角色卡目录。每个角色卡是一个子目录，包含：
+ *
+ * - `rolecard.json`        清单（必填）
+ * - `words.json`           台词库（必填，文件名可由清单指定）
+ * - `trigger-words.json`   触发词配置（必填，文件名可由清单指定）
+ * - `image.png`            插图（可选，文件名可由清单指定）
+ *
+ * 加载器只做「读取与校验」，不做任何消息处理逻辑，
+ * 因此核心引擎可以专注于运行时行为，二者完全解耦。
+ */
+import type { Rolecard } from './types';
+/**
+ * 加载单个角色卡目录。
+ *
+ * @returns 解析成功返回完整 `Rolecard`；清单缺失/数据无效返回 `null`。
+ */
+export declare function loadRolecard(dir: string): Rolecard | null;
+/**
+ * 扫描目录下的所有角色卡子目录并加载。
+ *
+ * 非目录项与无效的角色卡会被静默跳过。
+ */
+export declare function loadRolecards(baseDir: string): Rolecard[];

package/lib/loader.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * 角色卡加载器。
+ *
+ * 负责从磁盘扫描并解析角色卡目录。每个角色卡是一个子目录，包含：
+ *
+ * - `rolecard.json`        清单（必填）
+ * - `words.json`           台词库（必填，文件名可由清单指定）
+ * - `trigger-words.json`   触发词配置（必填，文件名可由清单指定）
+ * - `image.png`            插图（可选，文件名可由清单指定）
+ *
+ * 加载器只做「读取与校验」，不做任何消息处理逻辑，
+ * 因此核心引擎可以专注于运行时行为，二者完全解耦。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRolecard = loadRolecard;
+exports.loadRolecards = loadRolecards;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** 清单中路径字段的默认值。 */
+const DEFAULT_WORDS_FILE = 'words.json';
+const DEFAULT_TRIGGER_FILE = 'trigger-words.json';
+const DEFAULT_IMAGE_FILE = 'image.png';
+function readJson(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 加载单个角色卡目录。
+ *
+ * @returns 解析成功返回完整 `Rolecard`；清单缺失/数据无效返回 `null`。
+ */
+function loadRolecard(dir) {
+    const manifest = readJson((0, node_path_1.resolve)(dir, 'rolecard.json'));
+    if (!manifest?.id || !manifest?.name)
+        return null;
+    const wordsFile = manifest.wordsFile ?? DEFAULT_WORDS_FILE;
+    const triggerFile = manifest.triggerFile ?? DEFAULT_TRIGGER_FILE;
+    const imageFile = manifest.imageFile ?? DEFAULT_IMAGE_FILE;
+    const words = readJson((0, node_path_1.resolve)(dir, wordsFile));
+    const triggers = readJson((0, node_path_1.resolve)(dir, triggerFile));
+    if (!words || !triggers || !Array.isArray(triggers.groups))
+        return null;
+    const imagePath = (0, node_path_1.resolve)(dir, imageFile);
+    return {
+        manifest,
+        words,
+        triggers,
+        imagePath: (0, node_fs_1.existsSync)(imagePath) ? imagePath : null,
+        dir,
+    };
+}
+/**
+ * 扫描目录下的所有角色卡子目录并加载。
+ *
+ * 非目录项与无效的角色卡会被静默跳过。
+ */
+function loadRolecards(baseDir) {
+    if (!(0, node_fs_1.existsSync)(baseDir))
+        return [];
+    const result = [];
+    for (const entry of (0, node_fs_1.readdirSync)(baseDir)) {
+        const dir = (0, node_path_1.resolve)(baseDir, entry);
+        if (!(0, node_fs_1.statSync)(dir).isDirectory())
+            continue;
+        const card = loadRolecard(dir);
+        if (card)
+            result.push(card);
+    }
+    return result;
+}

package/lib/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 角色卡插件共享类型定义。
+ *
+ * 这些类型同时被核心引擎（core.ts）、加载器（loader.ts）和插件入口（index.ts）使用，
+ * 是「角色卡内容」与「运行时行为」之间唯一的契约。
+ */
+/** 单条台词。一条台词可属于多个标签，按标签过滤随机取用。 */
+export interface Quote {
+    id: string;
+    text: string;
+    tags: string[];
+}
+/** 台词库文件（words.json）的结构。 */
+export interface WordsData {
+    /** 角色名，如「别里科夫」。 */
+    character: string;
+    /** 角色来源，如「契诃夫《套中人》」。 */
+    source: string;
+    desc?: string;
+    /** 标签说明，key 为标签名，value 为该标签的场景描述。 */
+    tags?: Record<string, string>;
+    quotes: Quote[];
+}
+/** 触发词分组。一个分组对应一个标签，包含关键词集合与优先级。 */
+export interface TriggerGroup {
+    /** 标签名，与 WordsData.quotes[].tags 中的值对应。 */
+    tag: string;
+    name: string;
+    desc?: string;
+    matchMode: 'include';
+    /** 优先级，数字越小越优先匹配。 */
+    priority: number;
+    keywords: string[];
+}
+/** 触发词文件（trigger-words.json）的结构。 */
+export interface TriggerData {
+    desc?: string;
+    groups: TriggerGroup[];
+    /** 随机触发配置（仅作角色卡默认值参考，运行时以 Config 为准）。 */
+    random?: {
+        enabled: boolean;
+        probability: number;
+        pool: string;
+        desc?: string;
+    };
+    /** 冷却秒数（仅作角色卡默认值参考，运行时以 Config 为准）。 */
+    cooldown?: number;
+}
+/**
+ * 角色卡清单（rolecard.json）。
+ *
+ * 每个角色卡目录下必须存在此文件，插件启动时由加载器读取。
+ * 路径字段缺省时使用默认文件名。
+ */
+export interface RolecardManifest {
+    /** 角色卡唯一标识，如 `belikov`。用于 Config.rolecard 选中。 */
+    id: string;
+    /** 角色显示名，如「别里科夫」。 */
+    name: string;
+    description: string;
+    source?: string;
+    /** 台词库文件名，默认 `words.json`。 */
+    wordsFile?: string;
+    /** 触发词文件名，默认 `trigger-words.json`。 */
+    triggerFile?: string;
+    /** 插图文件名，默认 `image.png`。 */
+    imageFile?: string;
+}
+/** 已加载的完整角色卡，包含清单与解析后的数据。 */
+export interface Rolecard {
+    manifest: RolecardManifest;
+    words: WordsData;
+    triggers: TriggerData;
+    /** 插图绝对路径，无插图时为 null。 */
+    imagePath: string | null;
+    /** 角色卡目录绝对路径。 */
+    dir: string;
+}
+/** 插件运行时配置。所有行为参数统一由此处控制，与角色卡内容解耦。 */
+export interface Config {
+    /** 要激活的角色卡 ID，留空则自动加载第一个找到的角色卡。 */
+    rolecard: string;
+    /** 冷却时间（秒），同一频道内两次触发的最小间隔。 */
+    cooldown: number;
+    /** 冷却白名单用户 ID，这些用户的消息不受冷却限制。 */
+    cooldownWhitelist: string[];
+    /** 禁用的触发标签，留空表示全部启用。 */
+    disabledTags: string[];
+    /** 是否启用全部消息概率随机触发。 */
+    enableRandom: boolean;
+    /** 随机触发概率（0-100）。 */
+    randomProbability: number;
+    /** 是否启用角色卡插图。 */
+    enableImage: boolean;
+    /** 图片与文字是否作为同一条消息发送。 */
+    imageWithMessage: boolean;
+    /** 附带图片的概率（0-100）。 */
+    imageProbability: number;
+    /** 响应范围：群聊 / 私聊 / 两者。 */
+    respondIn: 'group' | 'private' | 'both';
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * 角色卡插件共享类型定义。
+ *
+ * 这些类型同时被核心引擎（core.ts）、加载器（loader.ts）和插件入口（index.ts）使用，
+ * 是「角色卡内容」与「运行时行为」之间唯一的契约。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "koishi-plugin-rolecard",
+  "version": "1.0.0",
+  "contributors": [
+    "Oppenheymu <oppenheymu@gmail.com>"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "rolecards"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/Oppenheymu/koishi-plugin-rolecard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Oppenheymu/koishi-plugin-rolecard.git"
+  },
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "rolecard"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "peerDependencies": {
+    "koishi": "^4.17.4"
+  },
+  "koishi": {
+    "description": {
+      "en": "Rolecard plugin — data-driven character quote engine",
+      "zh": "身份卡插件 · 数据驱动的角色台词引擎，可选加载不同角色卡"
+    },
+    "service": {}
+  }
+}

package/readme.md

@@ -0,0 +1,122 @@
+# koishi-plugin-rolecard
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-rolecard?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-rolecard)
+
+数据驱动的角色台词引擎 · 角色卡插件。
+
+核心逻辑与角色卡内容**完全解耦**：引擎是通用的，角色卡是纯数据资源。新增角色只需在 `rolecards/` 下添加一个数据目录，无需改动任何源码。
+
+## 架构
+
+```
+src/
+  types.ts    共享类型契约（角色卡内容 + 运行时配置）
+  loader.ts   角色卡加载器（扫描并解析 rolecards/ 目录）
+  core.ts     核心引擎（通用台词引擎，与具体角色解耦）
+  index.ts    插件入口（组装三者，对接 Koishi 生命周期）
+rolecards/
+  belikov/    别里科夫角色卡（数据资源）
+    rolecard.json        清单
+    words.json           台词库
+    trigger-words.json   触发词配置
+    image.png            插图
+```
+
+### 分层职责
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| `types.ts` | 定义角色卡数据结构与运行时配置的契约 | 无 |
+| `loader.ts` | 从磁盘扫描、解析、校验角色卡目录 | `types.ts` |
+| `core.ts` | 通用台词引擎：关键词匹配、概率触发、冷却、插图 | `types.ts` |
+| `index.ts` | 加载角色卡、按配置实例化引擎 | 以上三者 |
+
+角色卡（`rolecards/<id>/`）只包含数据，不含任何可执行逻辑，因此可以自由替换、增删，引擎自动适配。
+
+## 内置角色卡
+
+### 别里科夫 · 套中人
+
+灵感源自契诃夫《套中人》中那位谨小慎微、墨守成规、害怕任何改变的别里科夫。机器人会监听群聊，在合适的时机抛出他那忧心忡忡、生怕"闹出什么乱子"的台词，制造一本正经的喜剧效果。
+
+四类触发场景：
+
+- **proposal** — 提议与搞事（要不、计划、面基……）
+- **emotional** — 情绪波动与违规边缘（笑死、卧槽、节奏……）
+- **rules** — 规章制度与日常通知（通知、公告、群规……）
+- **distancing** — 撇清关系与甩锅（都怪、甩锅、谁的锅……）
+
+## 配置项
+
+| 配置项 | 类型 | 默认 | 说明 |
+|--------|------|------|------|
+| `rolecard` | string | `''` | 要加载的角色卡 ID（留空则自动加载第一个找到的角色卡） |
+| `cooldown` | number | `60` | 冷却时间（秒），同一频道内两次触发的最小间隔 |
+| `cooldownWhitelist` | string[] | `[]` | 冷却白名单，填入用户 ID 后其消息不受冷却限制 |
+| `disabledTags` | string[] | `[]` | 禁用的触发标签（留空表示全部启用） |
+| `enableRandom` | boolean | `true` | 启用全部消息概率随机触发 |
+| `randomProbability` | number | `3` | 随机触发概率（0-100，3 表示 3%） |
+| `enableImage` | boolean | `true` | 启用角色卡插图 |
+| `imageWithMessage` | boolean | `true` | 图片与文字一起发送（关闭则图片作为单独消息发送） |
+| `imageProbability` | number | `100` | 附带图片的概率（0-100） |
+| `respondIn` | string | `group` | 响应范围：`group` / `private` / `both` |
+
+## 添加新角色卡
+
+1. 在 `rolecards/` 下新建目录，如 `rolecards/mycharacter/`
+2. 创建 `rolecard.json` 清单：
+
+   ```json
+   {
+     "id": "mycharacter",
+     "name": "我的角色",
+     "description": "角色简介",
+     "source": "角色来源"
+   }
+   ```
+
+3. 创建 `words.json` 台词库：
+
+   ```json
+   {
+     "character": "我的角色",
+     "source": "来源",
+     "quotes": [
+       { "id": "q1", "text": "台词内容", "tags": ["tag1"] }
+     ]
+   }
+   ```
+
+4. 创建 `trigger-words.json` 触发词配置：
+
+   ```json
+   {
+     "groups": [
+       {
+         "tag": "tag1",
+         "name": "分组名",
+         "matchMode": "include",
+         "priority": 1,
+         "keywords": ["关键词1", "关键词2"]
+       }
+     ]
+   }
+   ```
+
+5. 可选：放入 `image.png` 插图
+
+6. 在插件配置中将 `rolecard` 设为 `mycharacter` 即可加载
+
+`tags` 字段是台词与触发词之间的桥梁——触发词分组的 `tag` 对应台词的 `tags`，引擎据此筛选候选台词。
+
+## 依赖
+
+- [koishi](https://koishi.chat/) ^4.17.4
+
+## 交流与反馈
+
+遇到问题或有建议？欢迎加入 QQ 群 **[1071284605【晓基地插件工坊】](https://qm.qq.com/q/WngX4RQoca)** 进行交流。
+
+## 许可证
+
+MIT

package/rolecards/belikov/rolecard.json

@@ -0,0 +1,6 @@
+{
+  "id": "belikov",
+  "name": "别里科夫",
+  "description": "《套中人》别里科夫，谨小慎微、忧心忡忡的身份卡",
+  "source": "契诃夫《套中人》"
+}

package/rolecards/belikov/trigger-words.json

@@ -0,0 +1,60 @@
+{
+  "desc": "别里科夫触发词配置。matchMode=include 表示消息包含任一关键词即命中；按 group 优先级(priority 越小越优先)匹配，命中后从 words.json 中对应 tag 的语录里随机取一条。random 为概率随机触发，cooldown 为冷却秒数，防止刷屏。注：运行时行为以插件 Config 为准，此处的 random/cooldown 仅作角色卡默认值参考。",
+  "groups": [
+    {
+      "tag": "proposal",
+      "name": "提议与搞事",
+      "desc": "群友提议做新事情时泼冷水，效果最佳",
+      "matchMode": "include",
+      "priority": 1,
+      "keywords": [
+        "要不", "提议", "整一个", "搞个", "计划", "打算", "准备",
+        "去不去", "面基", "一起去", "约", "组织", "活动", "报名",
+        "试试", "能不能", "可以不", "行不行", "凑个", "开个"
+      ]
+    },
+    {
+      "tag": "emotional",
+      "name": "情绪波动与违规边缘",
+      "desc": "群友情绪激昂或聊敏感话题，别里科夫胆小受惊",
+      "matchMode": "include",
+      "priority": 2,
+      "keywords": [
+        "笑死", "哈哈", "卧槽", "牛逼", "狂", "冲", "节奏", "举报",
+        "离谱", "绝了", "破防", "无语", "炸裂", "刺激", "敢说",
+        "牛批", "666", "牛啊", "牛逼啊", "疯了", "逆天", "没绷住", "难绷"
+      ]
+    },
+    {
+      "tag": "rules",
+      "name": "规章制度与日常通知",
+      "desc": "群主发公告或讨论规则时，搬出教条",
+      "matchMode": "include",
+      "priority": 3,
+      "keywords": [
+        "通知", "公告", "群规", "放假", "开会", "新规定", "规定",
+        "规则", "禁", "禁止", "处罚", "踢", "禁言", "管理", "群主",
+        "解散", "迁移", "审核"
+      ]
+    },
+    {
+      "tag": "distancing",
+      "name": "撇清关系与甩锅",
+      "desc": "群里起纷争、互相甩锅或被牵连时，急于划清界限",
+      "matchMode": "include",
+      "priority": 4,
+      "keywords": [
+        "别里科夫", "怪你", "赖你", "都怪", "谁干的", "你弄的",
+        "怪我", "不怪我", "跟我没关系", "你的锅", "谁的锅",
+        "甩锅", "背锅", "怪谁", "赖谁"
+      ]
+    }
+  ],
+  "random": {
+    "enabled": true,
+    "probability": 0.03,
+    "pool": "all",
+    "desc": "任意消息 3% 概率随机触发，pool=all 表示从全部语录中随机取一条"
+  },
+  "cooldown": 60
+}

package/rolecards/belikov/words.json

@@ -0,0 +1,52 @@
+{
+  "character": "别里科夫",
+  "source": "契诃夫《套中人》",
+  "desc": "谨小慎微、墨守成规、害怕任何改变。每条语录带 tags，可与 trigger-words.json 中的 group.tag 对应，按标签过滤随机取用。",
+  "tags": {
+    "proposal": "提议与搞事：群友提议新事情时，勉强附和又忧心忡忡",
+    "emotional": "情绪波动与违规边缘：群友情绪高昂或聊敏感话题时，惊恐劝阻",
+    "rules": "规章制度与日常通知：涉及规则/公告/管理时，搬出教条",
+    "distancing": "撇清关系与甩锅：群里起纷争或被牵连时，急于划清界限"
+  },
+  "quotes": [
+    { "id": "q01", "text": "当然，行是行的", "tags": ["proposal"] },
+    { "id": "q02", "text": "当然，行是行的，这固然很好，可是千万别闹出什么乱子", "tags": ["proposal"] },
+    { "id": "q03", "text": "这固然很好，可是千万别闹出什么乱子", "tags": ["proposal", "rules"] },
+    { "id": "q04", "text": "千万别闹出什么乱子", "tags": ["proposal"] },
+    { "id": "q05", "text": "这个嘛，当然也对，这都很好，但愿不要惹出什么事端！", "tags": ["proposal"] },
+    { "id": "q06", "text": "这都很好，但愿不要惹出什么事端！", "tags": ["proposal", "rules"] },
+    { "id": "q07", "text": "唉，千万别传到当局那里", "tags": ["emotional", "rules"] },
+    { "id": "q08", "text": "唉，千万别传到当局的耳朵里", "tags": ["emotional", "rules"] },
+    { "id": "q09", "text": "哎呀，千万不要惹出什么事端！", "tags": ["emotional", "proposal"] },
+    { "id": "q10", "text": "这一切，你知道吗，来得有点突然", "tags": ["emotional"] },
+    { "id": "q11", "text": "这需要考虑考虑", "tags": ["proposal"] },
+    { "id": "q12", "text": "我们首先应当掂量一下轻重，免得日后惹出什么麻烦", "tags": ["proposal"] },
+    { "id": "q13", "text": "希望日后不惹出什么麻烦", "tags": ["proposal"] },
+    { "id": "q14", "text": "群里竟有这样的人！", "tags": ["emotional"] },
+    { "id": "q15", "text": "这成何体统？", "tags": ["emotional", "rules"] },
+    { "id": "q16", "text": "群友都能这样，这成何体统？", "tags": ["emotional", "rules"] },
+    { "id": "q17", "text": "那怎么行呢？", "tags": ["proposal", "emotional"] },
+    { "id": "q18", "text": "这怎么可以？？", "tags": ["proposal", "emotional"] },
+    { "id": "q19", "text": "这怎么行呢？", "tags": ["proposal", "emotional"] },
+    { "id": "q20", "text": "您这是什么话？！", "tags": ["emotional"] },
+    { "id": "q21", "text": "哎呀，您这是什么话！", "tags": ["emotional"] },
+    { "id": "q22", "text": "现在我的心情非常非常沉重", "tags": ["emotional"] },
+    { "id": "q23", "text": "我认为有责任向您保证，这事与我毫不相干", "tags": ["distancing"] },
+    { "id": "q24", "text": "这事与我毫不相干", "tags": ["distancing"] },
+    { "id": "q25", "text": "等下，这事与我毫不相干！", "tags": ["distancing"] },
+    { "id": "q26", "text": "我认为群友有责任向他提出忠告", "tags": ["rules"] },
+    { "id": "q27", "text": "我并没有给人任何口实，可以招致这种事情", "tags": ["distancing"] },
+    { "id": "q28", "text": "这是有伤大雅的！", "tags": ["emotional", "rules"] },
+    { "id": "q29", "text": "这难道还须要解释吗？", "tags": ["rules"] },
+    { "id": "q30", "text": "您还年轻，前程远大，所以您的举止行为要非常非常小心谨慎", "tags": ["emotional", "rules"] },
+    { "id": "q31", "text": "那会有什么好结果？", "tags": ["proposal"] },
+    { "id": "q32", "text": "这会有什么好结果？？", "tags": ["proposal"] },
+    { "id": "q33", "text": "难道这有什么好结果吗？", "tags": ["proposal"] },
+    { "id": "q34", "text": "对当局您应当尊敬才是", "tags": ["rules"] },
+    { "id": "q35", "text": "对当局您应当尊敬才是。哦！我是指群管理！", "tags": ["rules"] },
+    { "id": "q36", "text": "您尽可以随便说去", "tags": ["distancing"] },
+    { "id": "q37", "text": "我们得避免别人歪曲谈话的内容，惹出什么事端", "tags": ["emotional", "rules"] },
+    { "id": "q38", "text": "我必须这么做", "tags": ["rules"] },
+    { "id": "q39", "text": "我有责任这样做", "tags": ["rules"] }
+  ]
+}