参与 · Contribute
参与贡献
无 CLA，无赞助商优先通道，维护者只有一人。小而聚焦的 PR 最容易合并——附上真实测试，以及能告诉审查者你在想什么的文字。
- ①Find a thread
选择切入点
浏览 open issues。good first issue 标签意味着路径清晰。help wanted 标签意味着路径开放但有争议。其他情况请先询问。
查看议题 → - ②Fork & branch
复刻并创建分支
git clone 你的复刻，然后 git checkout -b feat/short-name 或 fix/short-name。使用约定式提交——feat:、fix:、docs:、refactor:、test:、chore:。
GitHub 仓库 → - ③Local checks
通过本地检查
CI 运行 cargo fmt --all -- --check、cargo clippy --workspace --all-targets --all-features --locked -- -D warnings 和 cargo test --workspace --all-features --locked。推送前请先运行。
贡献指南 → - ④Open the PR
提交 PR
PR 描述应说明「为什么」而非「做了什么」（diff 已经展示了做了什么）。关联相关 issue。维护者亲自审查所有 PR——响应时间视情况而定。
PR 模板 →
小补丁提示词 · Small-patch prompt
用 CodeWhale 改进 CodeWhale
好的贡献提示词不是让 Agent 表演勤奋，而是让它留下一个可以合并的事实：一个真实摩擦点、一个小补丁、最小相关检查，以及审查者需要知道的风险。
贡献指南 →你正在 CodeWhale 中运行。 请改进 CodeWhale 本身：只找一个很小、可审查的摩擦点，范围可以是智能体框架、文档、测试或贡献流程。 优先处理 bug 修复、回归测试、文档澄清、错误信息改进，或一个很窄的贡献者体验问题。除非维护者明确要求，否则不要改产品方向、提供商策略、遥测、赞助、品牌、认证、沙箱、发布流程或全局提示词。 工作规则： 1. 编辑前先阅读仓库和当前 open issues。 2. 只选择一个 issue、TODO、失败测试、文档歧义、错误信息或重复出现的小摩擦点。 3. 先说明目标是什么，以及为什么它足够小、适合审查。 4. 尽可能复现问题。 5. 写最小补丁。 6. 先运行最小相关检查。 7. 一个补丁完成后就停止。 输出：发现的问题摘要、修改文件、已运行检查、风险或后续事项，以及建议的 PR 标题。
规约 House rules
简而言之：做实事，别折腾元数据。完整的行为准则是详细版。
- 欢迎附带复现步骤的 bug 报告、说明权衡的重构、修复真实歧义的文档 PR。
- 欢迎能复现 bug 的测试——甚至比修复本身更有价值。
- 欢迎在 Discussions 中提出有深度的问题。带数据更佳。
- 不欢迎不理解 diff 的 AI 生成补丁。
- 不欢迎在代码库或文档中添加托管 SaaS 依赖、遥测或推荐链接。
- 不欢迎按个人偏好跨仓库重命名。
开发循环 · The dev loop
从克隆到合并
完整流程，可直接复制粘贴。仅限 stable Rust——切勿使用 nightly 特性。
# 在 GitHub 上 fork，然后： git clone git@github.com:YOU/CodeWhale cd CodeWhale git checkout -b feat/your-thing # 本地构建运行 cargo build cargo run --bin codewhale # 检查（与 CI 完全一致） cargo fmt --all -- --check cargo clippy --workspace --all-targets --all-features --locked -- -D warnings cargo test --workspace --all-features --locked # 一致性验证 cargo test -p codewhale-protocol --test parity_protocol --locked cargo test -p codewhale-state --test parity_state --locked # 提交 + 推送 + PR git commit -m "feat: short subject in conventional-commit form" git push -u origin feat/your-thing gh pr create --fill