配置格式化工具

OpenCode 可以在写入或编辑文件后运行语言专用 formatter，让生成代码贴近项目风格。但 formatter 默认禁用，必须在配置里启用后才会运行。

先给结论：formatter 只做机械整理

Formatter 的职责是机械格式化，不是判断代码是否正确。

flowchart LR
    Edit["OpenCode 写入 / 编辑文件"] --> Enabled{"formatter 已启用?"}
    Enabled -->|否| Stop["不运行 formatter"]
    Enabled -->|是| Match["按扩展名匹配 formatter"]
    Match --> Command["运行 formatter command"]
    Command --> Apply["应用格式化结果"]
    Apply --> Review["检查 diff / test / typecheck"]

    style Enabled fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Apply fill:#dcfce7,stroke:#22c55e
    style Review fill:#fee2e2,stroke:#ef4444

正确顺序是先让 agent 做最小逻辑改动，再运行测试或类型检查，最后让 formatter 收尾。不要一开始就全仓库格式化，否则真实逻辑 diff 会被淹没。

1. 启用 formatter

官方当前文档明确说明：如果省略 formatter，所有 formatter 都是禁用状态。

要启用所有内置 formatter：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

要保留内置 formatter，同时覆盖某些配置或添加自定义 formatter，可以写成对象：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {}
}

如果项目 package.json 里有 prettier 依赖，并且 formatter 已启用，OpenCode 会对匹配文件使用 prettier。

2. 内置 formatter 怎么判断

OpenCode 内置了多种 formatter，但前提不一样。不要只看扩展名，还要看项目配置、依赖和本机命令。

这张表不是完整支持矩阵，而是判断方法。完整扩展名和工具列表以官方 Formatters 页面为准。

3. 配置项

每个 formatter configuration 支持：

自定义命令里可以使用 $FILE 占位符，OpenCode 会把它替换成待格式化文件路径。

4. 禁用 formatter

如果上层配置已经启用了 formatter，但当前项目不想运行，可以显式关闭：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": false
}

只禁用某个 formatter：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    }
  }
}

适合禁用的场景：formatter 版本和项目不一致、monorepo 子包规则冲突、生成代码不应该格式化、当前任务只允许最小 diff、或格式化工具会修改大量无关文件。

5. 自定义 formatter

可以覆盖内置 formatter，也可以添加项目专用 formatter。

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    },
    "custom-markdown-formatter": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}

自定义 formatter 进入项目配置前，先在终端里单独验证：

npx prettier --write path/to/file.ts
deno fmt path/to/file.md

6. 推荐改动流程

对真实项目，建议按这个顺序执行：

1. 任务前查看 git status
2. 限定本轮可修改文件
3. 让 OpenCode 完成最小逻辑改动
4. 跑 test / typecheck / lint
5. 运行 formatter 或让启用的 formatter 收尾
6. 检查 diff 是否只在预期范围

如果 formatter 造成大范围 diff，先停下来，不要继续叠加新逻辑。把格式化 diff 单独处理，或者暂时禁用相关 formatter。

7. 验收清单

启用 formatter 前后，检查这几项：

• formatter 明确启用或禁用，不依赖猜测。
• 项目确实有对应 formatter 依赖、命令或配置文件。
• 自定义 command 能独立运行。
• $FILE 占位符位置正确。
• formatter 不会触碰无关语言或生成目录。
• 运行后 diff 没有淹没业务改动。

接下来去哪

官方资料

• OpenCode Formatters：https://opencode.ai/docs/formatters
• OpenCode Configuration：https://opencode.ai/docs/config
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Permissions：https://opencode.ai/docs/permissions