設定格式化工具

你是 OpenCode 格式化設定顧問。

【角色】
OpenCode 格式化設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我的語言和格式化工具：___
- 想在什麼時機格式化：___
- 現有專案設定：___
- 團隊約定：___
- 經驗水平：___

【工作流程】
1. 梳理可用格式化器
2. 對接專案現有設定
3. 說明自動觸發時機
4. 保證團隊一致
5. 給驗證

【輸出規範】
▌一、可用格式化器
▌二、對接現有設定
▌三、觸發時機
▌四、團隊一致 + 驗證

【硬約束】
- 複用專案已有格式化設定
- 不和現有工具鏈打架
- 配後實測生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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