贡献指南
欢迎参与 koishi-plugin-kkk 的开发与贡献
贡献指南
感谢你对 koishi-plugin-kkk 感兴趣！我们需要你的帮助来让这个项目变得更好。
无论是修复 Bug、添加新功能，还是改进文档，我们都非常欢迎。
本项目是 karin-plugin-kkk 的 Koishi 移植版：业务代码来自上游仓库，
框架接口由 src/compat/ 提供等价实现。改动前请先分清它属于哪一层，见下文「项目结构」。
准备工作
在开始之前，请确保你的开发环境满足以下要求：
想在本地跑通完整链路，还需要：
- Koishi 的 puppeteer 插件：渲染卡片与长图
- FFmpeg：弹幕烧录、音轨合并（缺失会自动降级）
项目结构
本仓库是单个 Koishi 插件包，不是 monorepo，主要目录如下：
src/karin/: 从上游 karin-plugin-kkk 移植过来的业务代码，分成指令层apps/、平台层platform/、工具层module/，尽量与上游保持同构。src/compat/: 框架兼容层。业务代码依赖的node-karin、@karinjs/template-react等 Karin 侧接口，都在这里用 Koishi 的等价实现补齐。src/ktr/: 卡片模板（template/）与模板路由表（registry.ts）。src/richtext/: 平台无关的富文本中间表示，即@kkk/richtext的移植入口。src/index.ts/src/schema.ts/src/webui.ts: 插件入口、控制台配置表单、/kkk配置面板。scripts/build.mjs: 构建脚本，用 tsc 把src编译到lib/，并把@/、@kkk/richtext、node-karin等路径别名重写成相对路径。scripts/deploy.mjs: 把运行时最小集部署到工作区的node_modules/koishi-plugin-kkk，用于在本地 Koishi 里调试。
改代码前先分清层次：业务逻辑放 src/karin/（与上游保持一致），只有 Koishi 侧确实缺少的接口才在 src/compat/ 里补。
反过来把 Koishi 专有的写法写进业务层，之后就没法和上游对齐了。
各平台的 API 请求与签名由依赖库 @ikenxuan/amagi 负责。如果问题出在签名算法或接口实现上，请到 amagi 仓库 提 Pull Request。
插件仓库里的 docs/ 只放演示图，文档站点不在本仓库内。
架构说明
插件在 Koishi 中的位置
koishi-plugin-kkk 是 Koishi 的一个功能插件，通过 Koishi 的指令与事件系统工作，平台差异交给适配器处理。
消息处理流程
当用户在群聊中发送包含平台链接的消息时，插件的处理流程如下：
核心模块说明
apps 指令层 - 负责注册 Koishi 指令，监听消息并分发到对应的平台处理器。
src/karin/apps/
├── tools.ts # 视频解析指令（抖音/B站/快手/小红书）
├── push.ts # 动态推送任务
├── qrlogin.ts # 扫码登录功能
├── admin.ts # 管理员指令
├── help.ts # 帮助信息
└── statistics.ts # 解析统计platform 平台层 - 每个平台独立封装，包含链接解析、数据获取、评论处理等。
src/karin/platform/
├── douyin/ # 抖音
├── bilibili/ # B站
├── kuaishou/ # 快手
└── xiaohongshu/ # 小红书module 工具层 - 提供数据库操作、API 服务、渲染、网络请求等通用功能。
src/karin/module/
├── db/ # 数据库操作
├── server/ # API 服务
└── utils/ # 工具函数（含渲染模块）数据流向
开发流程
构建与本地调试
构建会用 tsc 把 src 编译到 lib/，并重写路径别名：
node scripts/build.mjs类型检查：npx tsc -p tsconfig.json。
想在本地 Koishi 里实际跑一遍，把插件仓库放在 Koishi 工作区的 plugins/ 下，再执行部署脚本，它会只复制运行需要的文件到 <工作区>/node_modules/koishi-plugin-kkk：
node scripts/deploy.mjs渲染相关的改动还可以先跑一次模板自检，不需要 puppeteer 与外网：
node scripts/smoke-render.cjs提交代码
我们遵循 Conventional Commits 规范。
提交信息的格式如下：
<type>(<scope>): <subject>例如：
feat(compat): 补齐 node-karin 的某个接口fix(template): 修复动态卡片样式错乱docs: 更新贡献指南
提交 Pull Request
- 推送到你的 Fork 仓库：
git push origin feature/amazing-feature - 在 GitHub 上向原仓库提交 Pull Request。
常见问题
上游修了 Bug，怎么同步过来？
业务代码在 src/karin/ 下与上游保持同构，可以对照上游仓库的改动直接移植，移植时尽量不要改动文件路径与函数签名。
如果上游用到了 Koishi 侧还没有的框架接口，先在 src/compat/ 里补上等价实现，再运行类型检查。
遇到 TypeScript 类型错误？
尝试重新构建整个项目或重新安装依赖：
pnpm install
node scripts/build.mjs