我想贡献代码

我想贡献代码

当你想给 Mirrai 提一个修复或新功能、准备发 PR 时,读这篇。只想报 Bug 的话,直接看下面「怎么提问题」。

流程

  1. Fork 仓库到你自己的账号下。
  2. 建一个分支,名字说清要干什么:
git checkout -b fix/记忆召回分数计算
  1. 改代码,保持改动小而完整——一个 PR 做一件事。
  2. 跑检查(见下一节),全绿再推。
  3. 开 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 兼容的服务直接复用现成实现):

  1. 在 server/llm/providers/ 下实现 LLMProvider 接口。
  2. 在 server/llm/index.ts 里注册。

加一种新的情感状态:

  1. drizzle/schema.ts——在枚举里加上新状态。
  2. server/_core/persona-utils.ts——补上触发词和状态描述。
  3. 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 为准。

最后提醒一句:这个项目处理的是真实的人和真实的感情。涉及人设、记忆、毕业机制的改动,请想一想它落在用户身上的样子。