koishi-plugin-kardsman

KARDS 二战卡牌游戏 Koishi 插件。自动识别聊天中的 %% 卡组代码，实时生成精美的卡组预览图。

✨ 功能亮点

• 🃏 卡组代码自动识别 — 聊天中出现 %%14|xx;xx;xx;xx; 格式自动解析渲染
• 🎨 高保真卡组预览 — Sharp 合成，显示完整卡面、稀有度统计、KARDS Logo
• 🔄 智能增量同步 — 启动时自动下载卡面图库，定时检测游戏更新，只拉取新增卡牌
• 🛡️ 按需补全 — 卡面缺失时自动暂停渲染，从 API 补齐后再发送
• 🎯 稀有度田字格 — 右上角显示精英/特殊/限定/标准数量统计
• 🖼️ 21 张可选桌布 — 内置多种桌面背景，支持自定义上传
• 👤 专属总部卡面 — 每个用户可以上传自己的第 40 张定制卡面

📦 安装

在 Koishi 插件市场搜索 koishi-plugin-kardsman 安装即可。

或手动安装：

npm install koishi-plugin-kardsman

🚀 使用

直接把 KARDS 游戏里的卡组代码发到群里就行了，机器人会自动生成预览图。比如有人发：

求卡组 %%14|2S303NgSwCxr;2Z3X4ArK;2V3f4vnloUxoza;ux

插件会立即回复一张卡组预览图。

| 指令 | 功能 | |---|---| | kards | 上传你的专属总部卡面（30 秒内发图片） | | kards 桌面 | 上传自定义桌面背景，上传后在配置页选择 | | kards search 卡名 | 搜索卡牌 | | kards deck 代码 | 手动解析卡组代码 | | kards sync | 手动更新卡牌数据库 | | kards count | 对比 API 与本地卡牌数量 |

⚙️ 配置

在 Koishi 控制台插件配置页面即可修改：

| 配置项 | 默认值 | 说明 | |---|---|---| | 检测间隔 | 24 小时 | 自动检测游戏版本更新的频率 | | 桌面背景 | 默认 | 下拉选择，含 21 张内置桌布 + 自定义上传 |

⚠️ 初次使用或更新插件后需要从 KARDS 服务器下载约 1600 张卡面图，耗时数分钟，请耐心等待。下载期间发卡组代码会提示稍后再试。

🏗️ 开发

git clone https://github.com/yourname/koishi-plugin-kardsman.git
cd koishi-plugin-kardsman
npm install
npm run build      # 编译 TypeScript
npm run sync       # 手动同步卡牌数据

📁 项目结构

src/
├── index.ts          # 插件入口、命令注册、消息监听
├── render.ts         # Sharp 图像合成（卡组网格 + Logo + 稀有度统计）
├── sync.ts           # GraphQL API 同步、图片下载、增量更新
├── sync-runner.ts    # 独立同步脚本
└── types.ts          # TypeScript 类型定义
data/
├── cards.json        # 1613 张卡牌数据
├── kards/            # 素材（Logo、稀有度图标、默认背景等）
├── tablecloths/      # 21 张可选桌面背景
├── customBg/         # 用户上传自定义背景
└── kards_cn/         # 下载的卡面图片（1600+ 张，初次启动生成）

🛠️ 技术栈

• Koishi v4 — 跨平台机器人框架
• Sharp — 高性能图像合成
• KARDS GraphQL API — 卡牌数据源
• TypeScript 严格模式

📄 License

MIT