Ncurator/CONTRIBUTING.md

贡献指南

简体中文 · English

讨论与反馈

欢迎通过 Issues 报告问题、提出需求或提问。社区与联系入口统一见 README。

提交前请先搜索已有 Issue，并优先在创建入口选择对应模板：

英文模板	标签	用途
Bug report	bug	缺陷、异常行为
Feature request	enhancement	新功能、需求、功能改进
Question	question	使用咨询、问题讨论

模板名称、说明和字段提示统一使用英文，填写内容允许中文或英文。模板会自动添加对应的英文标签；也可以选择 Blank issue 直接提交，由维护者补充标签。

报告问题时说明应用版本、操作系统、模型服务商、复现步骤、预期与实际结果。截图和日志请移除 API Key、个人资料及其他敏感内容。较大的功能或架构改动，建议先开 Issue 对齐范围。

开发与验证

项目协作规则见 AGENTS.md，文档修改遵循文档准则，系统设计见架构文档。

使用 Node.js 22、pnpm 9.12.2、Python 3.12；原生模块需要本地编译时，安装 macOS Command Line Tools 或 Windows C++ Build Tools。首次启动会准备原生模块，并按需构建网页抓取 sidecar，需要联网。只开发桌面界面时可先使用 pnpm dev:no-sidecar。

克隆自己的 Fork 后，在项目目录安装依赖并启动：

pnpm install --frozen-lockfile
pnpm dev

命令	用途
pnpm dev	启动桌面开发环境，按需准备原生模块和网页抓取 sidecar
pnpm dev:no-sidecar	暂不准备网页抓取 sidecar 的桌面开发入口
pnpm typecheck	Main 与 Renderer 类型检查
pnpm lint	ESLint 检查
pnpm test:unit --suite <suite>	执行受影响的 Unit suite
pnpm test:ai:non-live	AI 非 live backend 回归
pnpm build:unpack	构建并审计本机解包应用
pnpm build:win	在 Windows 构建 Windows x64 安装包
pnpm build:mac:arm64	在 Apple Silicon Mac 构建 macOS arm64 安装包

根据改动执行对应检查，PR 中记录实际运行的命令和结果。测试分层、过滤参数和真实 E2E 规则见测试文档。新增测试文件前先与维护者确认分类；调整产品行为时同步相关 PRD 和测试计划。需要 live 模型的用例由贡献者在本机配置自己的凭证。

.env-example 只放变量名和非敏感示例。生产共享密钥、模型 Key、签名证书、用户数据库及测试日志均不应提交。普通开发不需要 COS / R2 上传权限或官方服务密钥；官方发布流程见发布文档。

提交 Pull Request

flowchart TB
    subgraph contributor["贡献者"]
        direction LR
        A["1. Fork 仓库<br/>同步 main"] --- B["2. 从 main 切分支<br/>feat/xxx 或 bugfix/xxx"]
        B --- C["3. 开发验证<br/>整理为一个 commit"]
        C --- D["4. 向 dev 提 PR"]
    end
    subgraph maintainer["维护者"]
        direction LR
        E["5. 初审并合入 dev"] --- F["6. 在 dev 测试"]
        F --- G["7. 通过后<br/>cherry-pick 到 main"]
    end
    contributor --- maintainer

1. Fork 本仓库，并将自己的 Fork 克隆到本地。
2. 每次开发前，在 GitHub 打开自己的 Fork，切换到 main，点击 Sync fork → Update branch，同步原仓库最新的 main。
3. 在本地更新 main，从最新 main 创建工作分支：新功能使用 feat/xxx，问题修复使用 bugfix/xxx。
4. 一个 PR 聚焦一项改动，完成对应验证并同步相关文档。使用 git commit --signoff 提交，在提交信息中保留 Signed-off-by；提交信息使用 feat: ...、fix: ...、docs: ... 等格式。提交 PR 前尽量将改动整理为一个 commit，方便审核和 cherry-pick。
5. 将工作分支推送到自己的 Fork，向 Yoan98/Ncurator 的 dev 分支提交 PR。填写 PR 模板，说明关联 Issue、解决的问题、最终行为、验证命令与结果及已知限制；界面变化附截图。
6. 维护者初审代码，贡献者按反馈修改。评审期间可以继续提交修改，最终合入 dev 时保持一个完整 commit，并保留作者信息和 Signed-off-by。
7. 维护者在 dev 上进行集成验证和测试，通过后将对应 commit cherry-pick 到 main。

已克隆自己的 Fork 后，每次新建功能分支可执行：

git switch main
git pull --ff-only origin main
git switch -c feat/xxx

问题修复将 feat/xxx 换成 bugfix/xxx。这里的 origin 指自己的 Fork，先完成上述 GitHub 同步，再更新本地 main。GitHub 操作详见同步 Fork。

第三方代码、依赖、图片等材料需注明来源和许可证。

贡献许可

请先阅读项目的 AGPL-3.0-only 许可证。提交贡献时，你确认有权提供相关内容，并同意贡献按该许可证提供；贡献者保留相应版权。通过 commit signoff 留下上述确认。

工作成果涉及雇主或其他权利人时，应先获得所需许可。第三方材料继续遵守原许可证。