1k-code-quality

代码质量

OneKey 的 Lint、文档和常规代码质量标准。

Lint 命令

# Agent pre-commit gate (fast, only staged files)
yarn agent:check --profile commit

# Agent PR readiness gate (local staged checks + GitHub CI/review summary)
yarn agent:check --profile pr

# CI only (full project check)
yarn lint        # Comprehensive: TypeScript, oxlint, folder structure, i18n
yarn lint:only   # Oxlint and oxfmt
yarn tsc:only    # Full type check
yarn lint:agent-context # Skill metadata and startup-context budgets

注意： yarn lint 仅用于 CI。对于 Agent 工作流，请始终先使用 yarn agent:check；只有在调试 agent:check 报告的日志路径时，才使用较低级别的命令。

本仓库使用 oxlint 进行主动 Lint 验证，而非 ESLint。不要运行 yarn eslint、npx eslint 或 node_modules/.bin/eslint；这些条目是旧版兼容残留，且 yarn eslint 会对整个仓库执行自动修复。如需只读的定向诊断，请运行：

npx oxlint --tsconfig ./tsconfig.json --type-aware packages/example/src/file.ts --deny-warnings

提交前工作流

快速进行提交前验证：

yarn agent:check --profile commit

常见 Lint 修复

// Unused variable - prefix with underscore
const { used, unused } = obj;     // ❌ Error: 'unused' is defined but never used
const { used, unused: _unused } = obj;  // ✅ OK

// Unused parameter - prefix with underscore
function foo(used: string, unused: number) {}     // ❌ Error
function foo(used: string, _unused: number) {}    // ✅ OK

// Floating promise - add void or await
someAsyncFunction();        // ❌ Error: Promises must be awaited
void someAsyncFunction();   // ✅ OK (fire-and-forget)
await someAsyncFunction();  // ✅ OK (wait for result)

语言要求

所有注释都必须使用英语编写：

// ✅ GOOD: English comment
// Calculate the total balance including pending transactions

// ❌ BAD: Chinese comment
// 计算总余额，包括待处理的交易

// ✅ GOOD: JSDoc in English
/**
 * Fetches user balance from the blockchain.
 * @param address - The wallet address to query
 * @returns The balance in native token units
 */
async function fetchBalance(address: string): Promise<bigint> {
  // ...
}

何时添加注释

// ✅ GOOD: Explain non-obvious logic
// Use 1.5x gas limit to account for estimation variance on this chain
const gasLimit = estimatedGas * 1.5n;

// ✅ GOOD: Explain business logic
// Premium users get 50% discount on transaction fees
const fee = isPremium ? baseFee * 0.5 : baseFee;

// ❌ BAD: Obvious comment
// Set the value to 5
const value = 5;

开发原则

单一职责

每个函数都应只执行一项原子任务：

// ✅ GOOD: Single responsibility
async function fetchUserBalance(userId: string): Promise<Balance> {
  const user = await getUser(userId);
  return await getBalanceForAddress(user.address);
}

// ❌ BAD: Multiple responsibilities
async function fetchUserBalanceAndUpdateUI(userId: string) {
  const user = await getUser(userId);
  const balance = await getBalanceForAddress(user.address);
  setBalanceState(balance);
  showNotification('Balance updated');
  logAnalytics('balance_fetched');
}

避免过度抽象

不要为一次性操作创建辅助函数：

// ❌ BAD: Over-abstracted
const createUserFetcher = (config: Config) => {
  return (userId: string) => {
    return fetchWithConfig(config, `/users/${userId}`);
  };
};
const fetchUser = createUserFetcher(defaultConfig);
const user = await fetchUser(userId);

// ✅ GOOD: Simple and direct
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

详细指南

代码质量标准

请参阅 code-quality.md，了解完整指南：

• Lint 命令和提交前工作流
• 注释和文档标准
• 语言要求（仅限英语）
• 单一职责原则
• 避免过度抽象
• 统一的命名规范
• 代码质量检查清单

修复 Lint 警告

请参阅 fix-lint.md，了解完整的 Lint 修复工作流：

• 分析 Lint 警告
• 对 Lint 错误进行分类
• 按类别划分的常见修复模式
• 拼写检查修复
• 未使用变量/参数的处理
• 自动修复策略
• 修复后的测试

拼写检查

如果技术术语触发拼写检查错误：

# Check if word exists
grep -i "yourword" development/spellCheckerSkipWords.txt

# Add if not present (ask team lead first)
echo "yourword" >> development/spellCheckerSkipWords.txt

Agent 上下文框架

yarn lint:agent-context 会强制执行仓库技能发现和启动上下文预算。配置位于 development/lint/agent-context.config.json。添加或重组技能时，应将详细指南放在 references 中，使用 Codex 显式策略处理操作工作流，并遵守配置的目录和指令预算。

检查清单

提交前

• yarn agent:check --profile commit 通过

代码质量

• 所有注释均使用英语
• 不提交已注释掉的代码
• 函数具有单一职责
• 没有不必要的抽象
• 命名规范统一

相关技能

• /1k-sentry - Sentry 错误分析与修复
• /1k-test-version - 测试版本创建工作流
• /1k-coding-patterns - 通用编码模式