代码风格与代码检查

相关源文件

• frontend/.eslintrc
• frontend/.husky/pre-commit
• frontend/scripts/check-translation-completeness.cjs

本文档介绍了 OpenHands 中的代码质量强制执行机制，包括 linting 配置、pre-commit 钩子和自定义验证脚本，以确保前端和后端代码库之间代码风格的一致性。

有关整体构建系统和开发设置的信息，请参阅 构建系统。有关开发环境设置的详细信息，请参阅 设置与安装。

概述

OpenHands 采用多层方法来强制执行代码质量，将传统的 linting 工具与自定义验证脚本相结合。该系统确保了 React TypeScript 前端和 Python 后端之间代码的一致性，同时也强制执行项目特定的要求，例如翻译的完整性。

Linting 架构

来源： frontend/.husky/pre-commit1-12 frontend/.eslintrc1-76

前端 ESLint 配置

前端使用基于行业标准配置并带有项目特定自定义的综合 ESLint 设置。

基础配置

ESLint 配置扩展了多个已建立的规则集

• airbnb 和 airbnb-typescript，用于全面的 JavaScript/TypeScript 标准
• prettier 用于代码格式化集成
• @typescript-eslint/recommended 用于 TypeScript 特定规则
• react 和 react-hooks 插件，用于 React 最佳实践
• @tanstack/query 用于 React Query 模式

关键规则自定义

规则类别	配置	目的
导入管理	unused-imports/no-unused-imports: "error"	自动删除未使用的导入
文件扩展名	使用 TypeScript 覆盖的 import/extensions	正确处理 TypeScript 文件导入
React Props	react/require-default-props: "off"	允许 TypeScript 可选 prop 而无需默认值
参数重写	带有 Redux 例外的 no-param-reassign	允许在 reducers 中进行状态修改
可访问性	自定义 jsx-a11y 覆盖	平衡的可访问性，不过度限制

TypeScript 特定覆盖

配置通过 overrides 部分对 TypeScript 文件进行特殊处理，该部分应用更严格的类型规则，同时放宽某些不适用于 TypeScript 代码库的、侧重于 JavaScript 的限制。

来源： frontend/.eslintrc6-15 frontend/.eslintrc17-30 frontend/.eslintrc36-74

Pre-Commit 钩子工作流程

来源： frontend/.husky/pre-commit1-12

自定义验证脚本

翻译完整性检查器

check-translation-completeness.cjs 脚本可确保所有翻译键在 OpenHands 国际化系统中为每种支持的语言都有条目。

验证过程

步骤	功能	实现
语言发现	从 AvailableLanguages 中提取支持的语言	对 src/i18n/index.ts 进行正则表达式解析
翻译分析	比较每种键可用的语言与所需的语言	在 translation.json 中进行对象键比较
缺失检测	识别不完整的翻译键	集合差集操作
多余语言检测	查找不支持的语言条目	反向集合差集
错误报告	生成详细的错误消息	控制台输出显示具体的缺失语言

错误处理

脚本实现了全面的错误检测

• 缺失翻译：当翻译键缺少支持语言的条目时
• 多余语言：当翻译键包含不受支持的语言代码时
• 退出代码：返回非零退出代码以在验证失败时阻止提交

来源： frontend/scripts/check-translation-completeness.cjs11-26 frontend/scripts/check-translation-completeness.cjs33-57 frontend/scripts/check-translation-completeness.cjs84-88

与开发工作流程的集成

Linting 系统通过多个强制执行点无缝集成到开发流程中

Pre-Commit 强制执行

• Husky 钩子在提交尝试时自动触发
• 前端和后端检查按顺序运行
• 失败的检查将阻止提交完成，并提供详细的错误消息

文件定位策略

• 前端 linting 通过 lint-staged 专注于 TypeScript/React 文件
• 后端 linting 针对特定的 Python 包：openhands/、evaluation/、tests/
• 翻译检查全局应用于国际化文件

开发者反馈

• ESLint 在开发环境中提供实时反馈
• Pre-commit 钩子在失败时提供详细的 diff 输出
• 自定义脚本生成可读性强的错误消息，并附带具体的修复步骤

来源： frontend/.husky/pre-commit1-12 frontend/scripts/check-translation-completeness.cjs59-88