如何贡献

我们欢迎任何人提交代码、文档、错误报告和反馈，只要表述清晰即可。本页介绍相关流程：如何提交变更、我们在评审时会关注哪些方面，以及在你提交 PR 后会发生什么。

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

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

开始之前

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

1. 检查问题跟踪器。 可能有人已经在处理它或提交了相关讨论。
2. 读取 AGENTS.md。 仓库根目录包含简洁、始终加载的契约。详细的风险、稳定性、事实来源和技能发现参考请使用 Coding agent guidelines。
3. 任何涉及架构、配置、安全、工作流、治理、CI、发布行为或 AI 辅助贡献策略的内容，请使用架构与贡献地图。
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 是综合关卡；所有环节都必须通过。
• 标签：维护者使用标签来确定审查深度。在提交 PR 之前，你无需了解每一类标签。如果标签明显有误而你又无法编辑它们，请在评论中指出这一不匹配；维护者或拥有标签权限的审查者可以直接更正明显的不匹配。
• 审查路由：使范围、关联议题、验证以及风险/回滚上下文足够清晰，以便审查者能够快速选择正确的审查路径。
• 评审：维护者进行评审。评审意见采用 PR 评审分类法：🔴 阻塞、🟡 警告、🔵 建议、🟢 赞赏，以及 ✅ 已解决。必须处理阻塞项；警告应予回应；建议为可选项。

代码风格

• cargo fmt 清理（在 CI 中检查）
• cargo clippy -D warnings 清理（在 CI 中检查）
• 不允许存在未使用的生产代码：删除它、将其接入实际功能，或登记一个后续跟进的 issue。不要用下划线前缀或 #[allow(dead_code)] 来掩盖它；下划线命名仅保留给那些必需但有意不使用的 API、trait 或回调参数。
• 错误处理：在二进制边界使用 anyhow::Result，在库 crate 中使用类型化错误。生产代码路径中不得使用 unwrap() / expect()：应通过 ? 传播错误，或记录说明 panic 不可能发生的不变式。
• 最小化依赖：每个依赖都会增加二进制文件体积；在添加之前请权衡利弊
• 特征优先：在 zeroclaw-api 中定义特征，然后在合适的边缘 crate 中实现
• 默认安全：使用允许列表，而非阻止列表。新的外部接口默认关闭
• 内联单元测试：在文件底部使用 #[cfg(test)] mod tests {} 或同级的 tests.rs
• 不要提交密钥、个人数据或真实用户身份信息：隐私与 PII 规范页面是合并关卡

注释和漂移

注释应说明长期有效的意图、不变条件、风险或源码归属。不要添加仅复述附近控制流、重复 schema 或配置字段列表、照搬枚举变体，或描述代码和测试并未强制保证的运行时行为的注释。这些注释会成为漂移面：未来的贡献者和工具可能会在源代码已经变更后仍相信这些文字。

如果注释需要提及其他地方负责的行为，应指向该负责方，而非复制其内容。优先编写说明某个分支为何安全、哪个契约负责某条规则，或哪个来源必须优先变更的注释。

首选：

• 配置模式负责管理已接受的别名；保持此解析器的通用性。
• 此 panic 不可达，因为解析器会在更早阶段拒绝空的工具名称。

避免：

• 支持的变体包括 A、B 和 C。
• 此标志始终启用向量搜索。

如果每当代码、配置、WIT、schema 或测试发生变化时，都必须手动编辑注释才能让该表述保持为真，请改为让源头更清晰，或添加指向源头的引用。

测试

• 与代码共置的单元测试（mod tests）
• tests/ 中的集成测试以及 crate 本地的单元测试：通过 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 以预览来自所属 CLI/config 源的更改。
• 本地化：英文 markdown 是权威来源。常规英文文档 PR 可以省略大量生成的 .po 变更；请使用 Building the docs locally 中的标准 PR 正文说明。
• 翻译缓存 PR、发布翻译流程以及新增语言环境时，应运行 cargo mdbook sync，提交生成的 .po 文件，并使用 cargo mdbook check 进行校验

发布博客或网站元数据

当你发布博客文章或以其他方式更新公开的博客元数据时，请在同一个 PR 中更新手动维护的订阅源时间戳：

• web/public/blog/rss.xml：将 <lastBuildDate> 设置为最新文章的发布时间，采用 RFC 2822 / GMT 格式
• web/public/blog/atom.xml：将 <updated> 设置为最新文章的发布时间，采用 ISO 8601 UTC 格式
• web/public/sitemap.xml：将 /blog 条目的 <lastmod> 设置为最新的发布日期

将订阅源发现保持在环境本地：

• web/index.html 应将 /blog/rss.xml、/blog/atom.xml 和 /sitemap.xml 保留为根相对链接
• web/public/sitemap.xml 应列出面向用户的 /blog 页面，而非 XML feed 文件

提交信息

常规提交规范：

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 辅助协作，但请勿在 PR 正文或提交消息末尾添加机器人/AI 署名信息或生成工具页脚。当采纳贡献者的工作成果时，符合替代规则和隐私规则的人工 Co-authored-by: 署名信息仍然适用。完整规范请参阅 FND-005（贡献文化）。

拉取请求

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

feat(scope): short description

正文使用 PR 模板。测试部分是必需的：说明此更改是如何被检查的，并贴出与该更改相符的检查项。How you can test 下供审阅者运行的 A/B 方案仅在手动验证能提供有用信号时才需要；对于仅文档、纯重构或没有有意义的审阅者测试路径的琐碎更改，请标记为 N/A。对于仅文档的 PR，请使用 scripts/ci/docs_quality_gate.sh 和 scripts/ci/docs_links_gate.sh，或者说明为何链接检查没有新增链接可供检查。对于 Rust/代码 PR，请使用与变更范围相匹配的证据：必需的 CI 检查、针对性的 crate 或回归测试、手动冒烟测试，或在更广泛覆盖能证明较窄证据会遗漏内容时使用的完整 workspace 检查。当新的必需 CI 已覆盖变更范围时，就足够了；仅为重复相同的分支、目标和特性集，不需要额外的本地 Cargo。若 PR 依赖已知的 CI 覆盖缺口，则补充更多证据：平台特定测试、跨平台 lint、桌面应用覆盖、发布目标构建、过时的 CI，或不可用的 CI。It works on my machine 不是证据。

风险标签描述的是实际变更及其后果，而不是其所属的宽泛路径。请遵循维护者标签指南：risk:low表示文档、测试夹具或不会对生产、兼容性、构建、发布或治理产生影响的机械性元数据；risk:medium表示常规行为变更；risk:high表示具体的信任、凭据、兼容性、治理或发布权限边界。domain:security独立于risk:*，用于标识有效的安全边界。

带有 risk:high 或 domain:security 的 PR 在合并前需要经过深入审查、制定与更改相匹配的回滚计划，并获得两位独立的 Core Team 成员批准。维护者需要冻结未来的自动风险替换时，请使用 risk:manual；它不能降低审查要求。

在 PR 之后

合并策略： 采用 squash-merge（压缩合并），并在正文中保留完整的提交历史。具体格式请参阅 .claude/skills/squash-merge/SKILL.md：简而言之，以 PR 标题 + (#number) 作为主题行，以原始提交的项目符号列表作为正文。

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

需要帮助的区域

行为准则

不要做个混蛋。对事不对人。要接受维护者会关闭他们不愿维护的内容，通常会附上说明，偶尔也可能没有。如果某次关闭让你觉得不合理，可以提出疑问；如果提问没有任何回应，那就放手吧。

另见

• RFC 流程：适用于比补丁更大的任何改动
• 架构与贡献导图：应优先阅读哪些架构、基础和工作流文档
• 通信：如何联系团队
• 维护者 → 概述：维护者的日常工作内容