如何贡献

我们接受来自任何愿意清晰提交代码、文档、错误报告和反馈的贡献者。本页面涵盖相关机制——如何提交更改、我们在审查中关注的内容，以及你在提交 PR 后可能遇到的情况。

有关非代码贡献（报告问题、提供反馈、获取帮助），请参阅 通信。

有关需要在实现之前进行设计讨论的重大变更，请参阅 RFC 流程。

开始之前

对于任何超出拼写错误修复的内容：

1. 检查问题跟踪器。 可能有人已经在处理它或提交了相关讨论。
2. 阅读 AGENTS.md。 仓库根目录下的 AGENTS.md 是约定俗成的权威来源——风险等级、PR 规范、反模式以及审查标准均在此定义。
3. Use the Architecture and contribution map for anything that touches architecture, config, security, workflow, governance, CI, release behavior, or AI-assisted contribution policy.
4. 选择一个分支。 PR 的目标分支是 master。请 Fork 仓库并基于该分支创建新分支；无需经过 develop 或 integration 分支。

流程

fork → branch → commit → push → open PR → review → merge (squash)

关键检查点：

• PR 模板 — .github/pull_request_template.md。请填写此模板。摘要、验证证据和兼容性部分为必填项。
• CI — 在每次 PR 上运行。ci.yml 是组合门禁；所有阶段都必须通过。
• Labels — maintainers use labels to route review depth. You do not need to know every label family before opening a PR. If labels look obviously wrong and you cannot edit them, flag the mismatch in a comment; maintainers or reviewers with label permissions can correct obvious mismatches directly.
• Review routing — make the scope, linked issues, validation, and risk/rollback context clear enough that reviewers can choose the right review path quickly.
• Review — maintainers review. Findings use the PR review taxonomy: 🔴 blocking, 🟡 warning, 🔵 suggestion, 🟢 praise, and ✅ resolved. Address blockers; warnings should get a response; suggestions are optional.

代码风格

• cargo fmt 清理（在 CI 中检查）
• cargo clippy -D warnings 清理（在 CI 中检查）
• No unused production code — delete it, wire it into behavior, or track a follow-up issue. Do not silence it with underscore prefixes or #[allow(dead_code)]; reserve underscore names for required but intentionally unused API, trait, or callback parameters.
• Error handling: anyhow::Result at binary boundaries, typed errors in library crates. No unwrap() / expect() in production code paths — propagate with ? or document the invariant that makes panic impossible.
• 最小化依赖——每个依赖项都会增加二进制文件的大小；在添加之前请权衡利弊
• Trait-first —— 在 zeroclaw-api 中定义 trait，然后在正确的 edge crate 中实现
• 默认安全——使用白名单而非黑名单。新的外部表面默认关闭
• 内联单元测试 —— 在文件底部使用 #[cfg(test)] mod tests {} 或一个同级的 tests.rs 文件
• 不要提交密钥、个人数据或真实用户身份——隐私与 PII 规范 页面是合并检查点

测试

• 与代码共置的单元测试（mod tests）
• Integration tests in tests/ and crate-local unit tests — run via cargo nextest run --locked --workspace --exclude zeroclaw-desktop
• 特性门控代码需要特性门控测试
• 不要对涉及模式或 SQL 的测试进行数据库模拟——集成测试必须使用真实的 SQLite。

有关完整的五级分类体系（单元 / 组件 / 集成 / 系统 / 生产环境）、共享的模拟基础设施以及 JSON 追踪夹具格式，请参阅 Testing。

文档更改

• 文档中的文本更改请放在 docs/book/src/**/*.md（即本 mdBook）中。
• Rustdoc (/ /) 在部署时自动更新 API 参考
• 参考页面（docs/book/src/reference/cli.md、config.md）是自动生成的——请勿手动编辑。请运行 cargo mdbook refs 并提交生成的输出。
• Localisation — English markdown is the source of truth. Routine English docs PRs may omit broad generated .po churn; use the standard PR-body note in Building the docs locally.
• Translation-cache PRs, release translation passes, and new locales should run cargo mdbook sync, commit the resulting .po files, and validate them with cargo mdbook check

Publishing blog or website metadata

When you publish a blog post or otherwise update the public blog metadata, update the hand-maintained feed timestamps in the same PR:

• web/public/blog/rss.xml — set <lastBuildDate> to the latest post publish time in RFC 2822 / GMT format
• web/public/blog/atom.xml — set <updated> to the latest post publish time in ISO 8601 UTC format
• web/public/sitemap.xml — set the /blog entry’s <lastmod> to the latest publish date

Keep feed discovery environment-local:

• web/index.html should keep /blog/rss.xml, /blog/atom.xml, and /sitemap.xml as root-relative links
• web/public/sitemap.xml should list the human-facing /blog page, not the XML feed files

提交信息

常规提交规范：

feat(providers): add support for DeepSeek reasoning mode
fix(channels/matrix): prevent duplicate device sessions after verify
docs(getting-started): add YOLO-mode quick-start
refactor(runtime): split agent loop into steps
chore: bump tokio to 1.43

AI-assisted collaboration is welcome, but do not add bot/AI attribution trailers or generated tool footers to PR bodies or commit-message tails. Human Co-authored-by: trailers remain appropriate for incorporated contributor work when they follow the superseding and privacy rules. See FND-005 (Contribution Culture) for the full norm.

拉取请求

标题与压缩提交（squash commit）一致：

feat(scope): short description

Body uses the PR template. The validation-evidence section is required — paste the checks that match the change. For docs-only PRs, use scripts/ci/docs_quality_gate.sh and scripts/ci/docs_links_gate.sh or explain why link checking had no added links to inspect. For Rust/code PRs, include cargo fmt --check, cargo clippy, cargo test, plus whatever manual verification you did. “It works on my machine” is not evidence.

风险标签：

• risk: low — rollback is a revert; no user action needed
• risk: medium — users may need to update config / env / CLI usage; rollback plan required
• risk: high — security-critical, schema changes, breaking behaviour. Rollback plan, feature flag, and observable failure symptoms required

在 PR 之后

合并策略： 使用 squash-merge（压缩合并），并在提交信息正文中保留完整的提交历史。具体格式请参阅 .claude/skills/squash-merge/SKILL.md — 简要说明：以 PR 标题 + (#number) 作为提交信息主题，原始提交列表作为正文。

发布： 代码变更会合并到 master 分支；master 分支不会自动发布。当发布新版本时，维护者会更新版本号并打上 vX.Y.Z 标签。您可以在 CHANGELOG 中看到您的 PR。

需要帮助的区域

行为准则

不要做令人反感的事。对事不对人。接受维护者会关闭他们不想负责的问题——通常会附上解释，偶尔也不会。如果关闭看起来不合理，可以询问；如果询问没有结果，就继续前进。

另见

• RFC 流程 — 适用于比补丁更大的改动
• Architecture and contribution map — which architecture, foundation, and workflow docs to read first
• 通信 — 如何联系团队
• 维护者 → 概述 — 维护者的日常工作