我想贡献代码
当你想给 Mirrai 提一个修复或新功能、准备发 PR 时,读这篇。只想报 Bug 的话,直接看下面「怎么提问题」。
流程
- Fork 仓库到你自己的账号下。
- 建一个分支,名字说清要干什么:
git checkout -b fix/记忆召回分数计算
- 改代码,保持改动小而完整——一个 PR 做一件事。
- 跑检查(见下一节),全绿再推。
- 开 PR,写清楚改了什么、为什么改、怎么验证的。描述里附上相关 Issue 编号(如果有)。
你应该看到:PR 页面上 CI 检查通过;review 意见会在 PR 里回复。
提 PR 之前
三条都要跑,且都以退出码 0 结束:
pnpm check
pnpm test
pnpm fidelity:gate
pnpm check——TypeScript 类型检查。pnpm test——仓库里的 vitest 测试。pnpm fidelity:gate——确定性回归闸门:几秒钟跑完、不花钱、每次结果一样。它守着一些不该被悄悄改掉的底线,退步了会以非零退出码拦下你。
改了接口、schema 或 prompt 相关代码,这三个尤其不能跳。
两个常见的扩展点
加一家新的 LLM 提供商(OpenAI 兼容的服务直接复用现成实现):
- 在
server/llm/providers/下实现LLMProvider接口。 - 在
server/llm/index.ts里注册。
加一种新的情感状态:
drizzle/schema.ts——在枚举里加上新状态。server/_core/persona-utils.ts——补上触发词和状态描述。client/src/pages/Chat.tsx/HomePage.tsx——更新界面上的状态显示。
PR 描述里写什么
三段就够:改了什么、为什么改、怎么验证的(跑过哪些命令、手动试过哪条路径)。带截图或日志的 PR 会快很多,注意脱敏。
代码风格
- TypeScript 严格模式,不绕过类型检查。
- 跟着现有模式走:新表走
drizzle/schema.ts→server/db.ts→server/routers.ts→ 前端 hook 的顺序;新 LLM 提供商在server/llm/providers/实现接口、在server/llm/index.ts注册。 - 不引入不必要的抽象。三行重复的代码好过一个只被用一次的封装。
- 提交信息写「为什么」,不只写「改了什么」。
仓库里还有更细的说明,见 CONTRIBUTING.md(Issue / PR 模板在 .github/ 下)。
怎么提问题
| 情况 | 去哪 |
|---|---|
| 报 Bug、提功能建议 | GitHub Issues |
| 问用法、讨论想法 | GitHub Discussions |
| 安全漏洞 | 私下报告,见仓库里的 SECURITY.md,不要公开开 Issue |
提 Bug 时写清楚四样:版本号、安装方式(Docker / 源码 / 安装包)、复现步骤、现象与预期。能贴日志就贴日志(注意脱敏,别把 API Key 或聊天内容贴出来)。
许可
Mirrai 以 MIT 许可发布。提交 PR 即表示你的贡献同样按 MIT 许可并入项目;具体的贡献者协议要求以 CONTRIBUTING.md 为准。
最后提醒一句:这个项目处理的是真实的人和真实的感情。涉及人设、记忆、毕业机制的改动,请想一想它落在用户身上的样子。