#贡献审查

本目录包含贡献审查文档,记录了关于 OpenClaw 代码约定、架构模式和开发实践的真实观察。这些审查基于源代码分析,作为未来贡献者的实用笔记。

#目的

这些文档回答了这个问题:"我们从为 OpenClaw 贡献代码中学到了什么?" 它们提供了以下方面的可操作指导:

• 代码风格约定和 linting 规则
• 测试模式和覆盖率期望
• PR 和提交格式要求
• pre-commit 钩子和质量门控

#审查条目

#代码风格约定

关于 OpenClaw 代码格式化、linting 和 TypeScript 配置的观察。

关键主题:

• Oxlint 和 Oxfmt 配置(不是 ESLint/Prettier)
• TypeScript 严格模式设置
• 类型定义偏好(type vs interface)
• CONTRIBUTING.md 中的关键规则
• 错误处理模式
• Barrel 导出约定

为什么这很重要: 遵循这些约定可确保您的代码通过 CI 检查并与现有代码库保持一致。

#测试模式

关于 OpenClaw 测试框架、文件组织和测试执行模式的观察。

关键主题:

• 使用 V8 覆盖率的 Vitest 配置
• 测试文件模式(colocated、e2e、live)
• 覆盖率阈值(70% 行数,55% 分支)
• 测试结构和模拟模式
• 测试工具和辅助函数
• 在低内存环境中运行测试

为什么这很重要: 理解这些模式可帮助您编写与现有测试套件和 CI 管道无缝集成的测试。

#PR 和提交约定

关于 OpenClaw git 工作流程、PR 模板和 pre-commit 钩子的观察。

关键主题:

• 带作用域的 Conventional Commits 格式
• PR 模板要求(摘要、安全影响、验证)
• Pre-commit 钩子(密钥检测、linting、格式化)
• 人工验证要求
• Changelog 约定

为什么这很重要: 这些约定确保您的 PR 可审查、安全,并为将来参考进行了适当的文档记录。

#交叉引用

#相关架构文档

• 架构概述: 系统设计和组件交互
• 网关架构: 多租户请求处理
• 技能系统 (planned): 技能执行和生命周期

#相关模式文档

• 模式概述: 重复出现的设计模式
• 配置模式: 配置加载和验证
• 错误处理模式 (planned): 错误格式化和脱敏

#相关故障排除

• 故障排除概述: 常见问题和解决方案
• 构建失败 (planned): CI/CD 和依赖问题
• 测试失败 (planned): 测试隔离和超时问题

#如何使用这些文档

1. 开始新功能: 首先阅读代码风格约定和测试模式
2. 在打开 PR 之前: 查看 PR 和提交约定以确保合规性
3. CI 失败: 查看交叉引用的故障排除文档以获取常见解决方案
4. 架构问题: 参考架构文档以获取系统设计上下文

#文档结构

每个审查遵循以下结构:

1. YAML frontmatter: 版本元数据和置信度级别
2. 语言切换: 指向英文/中文版本的链接
3. 介绍: 本审查涵盖的内容
4. 关键观察: 实用、可操作的发现
5. 代码示例: 来自代码库的真实模式(如适用)
6. 为什么这很重要: 为贡献者提供上下文

#维护说明

这些文档基于以下内容的分析:

• src/ 中的源代码
• 配置文件(.oxlintrc.json、vitest.config.ts 等)
• 开发文档(CONTRIBUTING.md、CLAUDE.md)
• Git 历史记录和 PR 模板

最后一次针对提交 aceb17a (2026-02-24) 进行验证。