OpenCode 完全指南：代码质量自动化——格式化与审查

写代码的速度由 AI 决定，代码质量的底线由工具决定。OpenCode 的 Formatters 和 Code Review 系统让质量保障自动化——每次 AI 生成代码后，自动格式化、自动检查、自动修复。

代码格式化（Formatters）

配置

// opencode.json
{
  "formatters": {
    "typescript": {
      "command": "prettier",
      "args": ["--write", "$FILE"]
    },
    "python": {
      "command": "black",
      "args": ["$FILE"]
    },
    "go": {
      "command": "gofmt",
      "args": ["-w", "$FILE"]
    },
    "rust": {
      "command": "rustfmt",
      "args": ["$FILE"]
    }
  }
}

$FILE 是 OpenCode 自动替换为被修改文件路径的变量。

自动触发

配置后，AI 每次修改文件，OpenCode 自动运行对应的格式化工具：

AI 修改了 UserService.ts
    ↓
OpenCode 自动执行: prettier --write UserService.ts
    ↓
格式已统一，无需人工介入

多工具串联

{
  "formatters": {
    "typescript": [
      { "command": "prettier", "args": ["--write", "$FILE"] },
      { "command": "eslint", "args": ["--fix", "$FILE"] }
    ]
  }
}

Prettier 处理格式（缩进、引号、分号），ESLint 处理逻辑问题（未使用变量、代码风格）。两者互补。

按文件类型匹配

{
  "formatters": {
    "typescript": { "command": "prettier", "args": ["--write", "$FILE"], "patterns": ["*.ts", "*.tsx"] },
    "json": { "command": "prettier", "args": ["--write", "$FILE"], "patterns": ["*.json", "*.yaml"] },
    "markdown": { "command": "prettier", "args": ["--write", "$FILE"], "patterns": ["*.md"] }
  }
}

忽略某些操作

{
  "formatters": {
    "enabled": true,
    "on_save": true,
    "on_ai_edit": true,
    "skip_patterns": ["*.generated.*", "package-lock.json"]
  }
}

• on_save：手动保存时格式化
• on_ai_edit：AI 修改时格式化
• skip_patterns：跳过自动生成的文件

代码审查（Code Review）

配置审查规则

// opencode.json
{
  "code_review": {
    "enabled": true,
    "check_on_pr": true,
    "check_on_commit": false,
    "rules": {
      "no_secrets": { "enabled": true, "severity": "error" },
      "no_console_log": { "enabled": true, "severity": "warn" },
      "type_safety": { "enabled": true, "severity": "error" },
      "function_length": { "enabled": true, "max_lines": 80, "severity": "warn" },
      "complexity": { "enabled": true, "max_cyclomatic": 15, "severity": "warn" }
    }
  }
}

审查维度

| 规则 | 说明 | 严重度建议 |
|------|------|-----------|
| no_secrets | 检测硬编码的 API Key、密码 | error |
| no_console_log | 检测调试打印语句 | warn |
| type_safety | 检测 any 类型、缺少类型守卫 | error |
| function_length | 函数行数超过阈值 | warn |
| complexity | 圈复杂度超过阈值 | warn |
| no_dead_code | 未使用的变量/导入 | warn |
| error_handling | 未处理的 Promise、空 catch | error |
| security_patterns | SQL注入、XSS、路径穿越 | error |

自定义规则

规则可以用正则表达式或语义分析：

{
  "code_review": {
    "rules": {
      "custom_naming": {
        "pattern": "interface +[A-Z][a-zA-Z]*",
        "message": "接口名必须以大写字母开头",
        "severity": "warn"
      },
      "no_nested_ternary": {
        "pattern": "\\? .* \\? .* :",
        "message": "禁止嵌套三元表达式",
        "severity": "error"
      }
    }
  }
}

审查报告格式

Code Review 输出结构化的 Markdown 报告：

🔴 严重问题

| 文件 | 行号 | 问题 | 建议 |
|------|------|------|------|
| auth.ts | 42 | API Key 硬编码 | 使用环境变量 |

🟡 改进建议

| 文件 | 行号 | 问题 | 建议 |
|------|------|------|------|
| user.ts | 156 | 函数超过 80 行 | 拆分为 3 个函数 |

在 AGENTS.md 中定义审查标准

## Code Review 标准

本项目采用以下审查标准：
- 所有 API 路由必须有输入验证（zod schema）
- 错误不能空 catch，必须记录日志
- 数据库查询必须有分页（limit）
- 敏感操作必须有审计日志
- 测试覆盖率新代码不低于 85%

违反以上任何一条，标记为 🔴 阻塞。

质量门禁流水线

将 Formatters + Code Review 串联成自动质量门禁：

AI 修改代码
    ↓
Formatters 自动格式化
    ↓
LSP 检查编译错误
    ↓
Code Review 检查规范
    ↓
全部通过 → 允许提交

在 Hooks 中集成：

{
  "hooks": {
    "post_edit": [
      { "run": "formatter", "if": "formatters.enabled" },
      { "run": "code_review", "if": "code_review.enabled" },
      {
        "command": "echo '✅ 质量门禁通过: {{.file}}'"
      }
    ]
  }
}

小结

格式化器消除了"代码风格不一致"的烦恼，代码审查系统堵住了"常见错误混入代码库"的漏洞。两者结合，AI 生成的代码在写入文件的那一刻就被格式化和审查——质量从源头得到保障。