## 任務：設計交易核心引擎

### 背景
我們正在開發金融交易平台，需要一個高可靠的交易核心引擎。

### 需求
1. 支援多幣別交易（TWD, USD, EUR, JPY）
2. ACID 交易保證
3. 雙重記帳法（Double-entry bookkeeping）
4. 交易限額控制（每日、每筆、每月）
5. 防重複提交（Idempotency）
6. 完整審計軌跡

### 技術約束
- Java 21 + Spring Boot 3.2
- PostgreSQL 16
- Redis 7（分散式鎖）

### 要求
1. 先用 Plan 模式設計架構（類別圖、序列圖）
2. 再用 Build 模式實作核心類別
3. 包含完整單元測試
4. 符合 OWASP 安全規範

## Plan 模式 Prompt

分析目前的 Spring Boot 專案，設計多租戶改造方案：
1. 租戶識別策略（Header / Subdomain / JWT Claim）
2. 資料隔離策略（Schema-per-tenant）
3. 動態 DataSource 路由
4. 租戶管理 API
5. 資料遷移腳本
6. 需要修改的所有檔案清單

// TenantContext.java - 租戶上下文管理
@Component
public class TenantContext {
    private static final ThreadLocal<String> currentTenant = new ThreadLocal<>();

    public static void set(String tenantId) {
        currentTenant.set(tenantId);
    }

    public static String get() {
        return currentTenant.get();
    }

    public static void clear() {
        currentTenant.remove();
    }
}

// TenantFilter.java - 租戶攔截器
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TenantFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain chain)
            throws ServletException, IOException {
        String tenantId = extractTenantId(request);
        if (tenantId == null) {
            response.sendError(HttpServletResponse.SC_BAD_REQUEST,
                "Missing tenant identification");
            return;
        }
        try {
            TenantContext.set(tenantId);
            chain.doFilter(request, response);
        } finally {
            TenantContext.clear();
        }
    }

    private String extractTenantId(HttpServletRequest request) {
        // 優先順序：Header > JWT Claim > Subdomain
        String tenantId = request.getHeader("X-Tenant-Id");
        if (tenantId != null) return tenantId;

        // 從 JWT 提取
        String token = request.getHeader("Authorization");
        if (token != null && token.startsWith("Bearer ")) {
            return extractFromJwt(token.substring(7));
        }

        // 從 Subdomain 提取
        String host = request.getServerName();
        if (host != null && host.contains(".")) {
            return host.split("\\.")[0];
        }
        return null;
    }
}

// TenantRoutingDataSource.java - 動態 DataSource 路由
public class TenantRoutingDataSource extends AbstractRoutingDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        return TenantContext.get();
    }
}

# 使用 OpenCode + GitHub MCP 處理 Issues
> 請分析 #234 Issue 的內容，判斷是 bug、feature request 還是 question，
  並建議處理優先順序和可能的解決方案

# 使用唯讀 code-reviewer 代理
> use skill code-reviewer
> 請審查 PR #567 的所有變更，重點關注：
  1. 破壞性變更（Breaking Changes）
  2. 效能影響
  3. 類型安全
  4. 測試覆蓋
  5. 文件更新

# 啟動 OpenCode Server（供其他客戶端連線）
opencode serve --hostname 127.0.0.1 --port 3000

# 從另一個終端機連線
opencode connect --url http://127.0.0.1:3000

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "security-reviewer": {
      "description": "Security-focused code reviewer",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a security expert. Review code for vulnerabilities following OWASP Top 10.",
      "temperature": 0.2,
      "steps": 50,
      "mode": "subagent",
      "tools": {
        "bash": false,
        "edit": false,
        "write": false,
        "websearch": true,
        "webfetch": true
      },
      "permission": {
        "read": "allow",
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

---
description: Frontend development specialist
model: anthropic/claude-sonnet-4-5
temperature: 0.5
steps: 100
mode: primary
tools:
  websearch: true
  bash: true
permission:
  edit: allow
  bash: ask
color: "#42b883"
---

You are a frontend development specialist working with Vue 3 and TypeScript.
Follow the Composition API style and use Tailwind CSS for styling.

# 使用互動式命令建立代理
opencode agent create

{
  "agent": {
    "deep-thinker": {
      "model": "anthropic/claude-sonnet-4-5",
      "options": {
        "reasoningEffort": "high",
        "textVerbosity": "verbose"
      }
    }
  }
}

# 1. 啟動 OpenCode
opencode

# 2. 按 Tab 切換到 Plan 模式（右下角顯示模式指示器）
<TAB>

# 3. 描述需求
> When a user deletes a note, we'd like to flag it as deleted in the database.
> Then create a screen that shows all the recently deleted notes.
> From this screen, the user can undelete a note or permanently delete it.

# 4. AI 回傳計畫，開發者審視並提供回饋
> We'd like to design this new screen using a design I've used before.
> [Image #1] Take a look at this image and use it as a reference.

# 5. 滿意後，按 Tab 切換回 Build 模式
<TAB>

# 6. 開始實作
> Sounds good! Go ahead and make the changes.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "websearch": "deny",
    "webfetch": "allow"
  },
  "agent": {
    "safe-coder": {
      "tools": {
        "bash": false,
        "websearch": false,
        "mymcp_*": false
      },
      "permission": {
        "bash": "deny"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "POSTGRES_CONNECTION_STRING": "{env:DATABASE_URL}"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-openagent", "opencode-wakatime"]
}

---
name: api-designer
description: Design RESTful APIs following best practices
tools:
  webfetch: true
  websearch: true
mcp:
  context7:
    type: remote
    url: https://mcp.context7.com/mcp
permission:
  edit: allow
  bash: ask
---

You are an API design specialist. Follow these principles:
1. RESTful conventions
2. Proper HTTP status codes
3. HATEOAS when applicable
4. OpenAPI 3.0 specification
5. Pagination for list endpoints

# 進入前端專案目錄
cd /path/to/vue-project

# 啟動 OpenCode
opencode

# 初始化專案（產生 AGENTS.md）
/init

# AGENTS.md

## 專案說明
這是一個 Vue 3 + TypeScript + Tailwind CSS 專案。

## 技術堆疊
- Vue 3 Composition API
- TypeScript 5.x
- Tailwind CSS 4.x
- Vite 6.x
- Pinia（狀態管理）
- Vue Router（路由）

## 編碼規範
- 元件使用 `<script setup lang="ts">` 語法
- 樣式使用 Tailwind utility classes
- 狀態管理使用 Pinia store
- 命名慣例：PascalCase（元件）、camelCase（函式/變數）

## 目錄結構
- src/components/ - 共用元件
- src/views/ - 頁面元件
- src/stores/ - Pinia stores
- src/composables/ - 組合式函式
- src/types/ - TypeScript 型別定義

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}
```text

```text
建立一個 Vue 3 元件，實作使用者清單的 CRUD 功能。
use context7 查詢 Vue 3 Composition API 最新用法。

# AGENTS.md

## 專案說明
Spring Boot 3.x + Java 21 微服務專案

## 技術堆疊
- Spring Boot 3.4
- Java 21
- Spring Data JPA
- Spring Security
- MapStruct
- Lombok
- OpenAPI 3.0

## 編碼規範
- 使用 Clean Architecture
- Controller → Service → Repository 分層
- DTO 使用 Record 類別
- 日誌使用 SLF4J
- 例外處理使用 @ControllerAdvice

# Node.js
# opencode 進入專案後使用 /init，會自動識別 package.json 並產生對應的 AGENTS.md

# FastAPI
# opencode 進入專案後使用 /init，會自動識別 pyproject.toml 並產生對應的 AGENTS.md

# AGENTS.md

## 專案說明
FastAPI + Python 3.12 RESTful API 專案

## 技術堆疊
- FastAPI 0.115+
- Python 3.12
- SQLAlchemy 2.0（ORM）
- Alembic（資料庫遷移）
- Pydantic V2（資料驗證）
- pytest（測試）

## 編碼規範
- 使用 async/await 非同步程式設計
- 路由使用 APIRouter 分組
- 依賴注入使用 Depends()
- 回應模型明確定義
- 使用 typing 完整型別標註

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

# 在 OpenCode TUI 中
/connect
# 選擇 Anthropic → Claude Pro/Max 或手動輸入 API Key

/models
# 選擇模型，如 claude-sonnet-4-5

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "company-llm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "公司內部 LLM",
      "options": {
        "baseURL": "https://llm-gateway.internal.company.com/v1",
        "apiKey": "{env:COMPANY_LLM_API_KEY}",
        "headers": {
          "X-Team-ID": "engineering"
        }
      },
      "models": {
        "company-model-v2": {
          "name": "Company Model v2",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

# 安裝 Chocolatey（若未安裝）
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安裝 OpenCode
choco install opencode

# 驗證安裝
opencode --version

# 安裝 Scoop（若未安裝）
irm get.scoop.sh | iex

# 安裝 OpenCode
scoop install opencode

# 驗證安裝
opencode --version

# 透過 npm 全域安裝
npm install -g opencode-ai@latest

# 驗證安裝
opencode --version

# 使用 mise 安裝
mise use -g github:anomalyco/opencode

docker run -it --rm ghcr.io/anomalyco/opencode

# 在 WSL 中使用安裝腳本
curl -fsSL https://opencode.ai/install | bash

# 驗證安裝
opencode --version

# 使用 OpenCode 官方 tap（最新版本，推薦）
brew install anomalyco/tap/opencode

# 或使用官方 brew formula（更新較慢）
brew install opencode

# 驗證安裝
opencode --version

curl -fsSL https://opencode.ai/install | bash
opencode --version

npm install -g opencode-ai@latest
# 或 bun install -g opencode-ai@latest
# 或 pnpm install -g opencode-ai@latest
# 或 yarn global add opencode-ai@latest

nix run nixpkgs#opencode           # 穩定版
nix run github:anomalyco/opencode  # 最新 dev 分支

curl -fsSL https://opencode.ai/install | bash

# 自訂安裝路徑
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 使用 XDG 路徑
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

# 穩定版
sudo pacman -S opencode

# 最新 AUR 版本
paru -S opencode-bin

brew install anomalyco/tap/opencode

# macOS（Homebrew）
brew install --cask opencode-desktop

# Windows（Scoop）
scoop bucket add extras
scoop install extras/opencode-desktop

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "keybinds": {},
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto"
}

# 啟動 OpenCode
opencode

# 新增供應商（互動式選擇）
/connect

# 推薦入門：OpenCode Zen
# 選擇 opencode → 前往 opencode.ai/auth → 取得 API Key

# 選擇模型
/models

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000
      }
    }
  }
}

# === 供應商認證 ===
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export AWS_PROFILE="my-dev-profile"
export AWS_REGION="us-east-1"
export AZURE_RESOURCE_NAME="my-azure-resource"
export GOOGLE_CLOUD_PROJECT="my-gcp-project"

# === OpenCode 設定 ===
export OPENCODE_CONFIG="/path/to/custom-config.json"
export OPENCODE_CONFIG_DIR="/path/to/config-directory"
export OPENCODE_CONFIG_CONTENT='{"model":"anthropic/claude-sonnet-4-5"}'  # 行內設定覆蓋（最高優先級）
export OPENCODE_INSTALL_DIR="/usr/local/bin"

# === Claude Code 相容性控制 ===
export OPENCODE_DISABLE_CLAUDE_CODE=true       # 停用所有 Claude Code 相容性（CLAUDE.md 等）
export OPENCODE_DISABLE_CLAUDE_CODE_RULES=true  # 僅停用 CLAUDE.md 規則讀取
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true  # 僅停用 .claude/skills/ 讀取

# === Proxy 設定 ===
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"

# === 實驗性功能 ===
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true
export OPENCODE_ENABLE_EXA=1

# 系統級 Proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# npm Proxy（用於安裝 MCP 套件）
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://ai-gateway.internal.company.com/anthropic/v1"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "production",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

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

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "amazon-bedrock"],
  "disabled_providers": ["openai", "openrouter"]
}

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

# 建立專案目錄
mkdir my-new-project && cd my-new-project

# 初始化 Git
git init

# 使用 Plan 模式以 OpenCode 建立專案
opencode

# 在 OpenCode TUI 中
/init

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "permission": {
    "websearch": "allow",
    "webfetch": "allow"
  },
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

# 建立專案層級規則
mkdir -p .opencode/rules

# 專案開發規則

## 語言與框架
- 使用 TypeScript strict mode
- 專案框架：Next.js 15

## 編碼規範
- 使用 ESLint + Prettier
- 命名慣例：camelCase（變數/函式）、PascalCase（元件/型別）
- 檔案命名：kebab-case

## 安全規範
- 所有使用者輸入必須驗證
- SQL 操作必須使用參數化查詢
- 敏感資料使用環境變數，禁止硬編碼

# OpenCode 工作目錄（排除會話資料）
.opencode/sessions/
.opencode/share/

# 保留設定檔（提交到版本控制）
# .opencode/rules/       ← 保留
# .opencode/skills/      ← 保留
# .opencode/agents/      ← 保留
# opencode.json          ← 保留
# AGENTS.md              ← 保留

# AGENTS.md

## 專案說明
這是一個執行超過 5 年的遺留系統，正在進行漸進式現代化。

## 技術堆疊
- 後端：Java 8 → 目標 Java 21
- 框架：Spring MVC → 目標 Spring Boot 3.x
- 前端：jQuery + JSP → 目標 Vue 3
- 資料庫：Oracle → 目標 PostgreSQL

## 模組結構
- core/ - 核心業務邏輯（穩定，勿大幅修改）
- web/ - Web 層（優先重構）
- batch/ - 批次處理（延後重構）
- integration/ - 外部系統整合

## 注意事項
- 保留向後相容性
- 新程式碼使用 Java 21 語法
- 新元件使用 Spring Boot 3.x
- 禁止修改 core/ 下的 PaymentService 和 AccountService（正在其他分支重構）
- 所有修改必須通過現有測試套件

# 在 OpenCode TUI 中直接執行 Git 操作
> 建立一個新的 feature branch 叫 feature/user-management 並切換過去

# 或使用 / 指令
> 分析當前 branch 的所有修改，整理成規範的 commit message

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

# 步驟 1: 完成開發後
> 提交所有修改，commit message 遵循 Conventional Commits 規範

# 步驟 2: 建立 PR
> 使用 GitHub MCP 建立 Pull Request，標題包含 JIRA ticket 編號，
> 描述包含：修改摘要、影響範圍、測試結果、截圖（如適用）

# 步驟 3: 使用 Plan 模式做 Code Review
> 切換到 Plan 模式，審查 PR 中的所有修改，
> 檢查：安全性、效能、可讀性、測試覆蓋率

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Code Review 專家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一位嚴謹的 Code Reviewer。請依照以下標準審查程式碼：\n1. OWASP Top 10 安全性\n2. 效能瓶頸\n3. 可讀性和可維護性\n4. 測試完整性\n5. 錯誤處理\n6. 命名規範",
      "mode": "primary",
      "tools": {
        "bash": false,
        "edit": false,
        "write": false
      },
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

# 分享當前對話
/share

# 匯出 Markdown
/share --format markdown

# 分享到線上
/share --provider opencode

# 安全編碼規則

## 必須遵守
1. 所有使用者輸入必須經過驗證和消毒（sanitization）
2. SQL 操作必須使用參數化查詢或 ORM
3. 密碼必須使用 bcrypt/argon2 雜湊儲存
4. API 端點必須實作適當的認證和授權
5. 敏感資料（API Key、密碼）禁止硬編碼
6. CORS 設定必須明確指定允許的來源
7. 檔案上傳必須驗證類型和大小
8. 日誌中禁止記錄敏感資訊

## OWASP Top 10 檢查項目
- [ ] A01: Broken Access Control
- [ ] A02: Cryptographic Failures
- [ ] A03: Injection
- [ ] A04: Insecure Design
- [ ] A05: Security Misconfiguration
- [ ] A06: Vulnerable Components
- [ ] A07: Authentication Failures
- [ ] A08: Software Integrity Failures
- [ ] A09: Logging Failures
- [ ] A10: SSRF

# 啟動 OpenCode 並切換到 Plan 模式
opencode
<TAB>  # 切換到 Plan 模式

# 提出需求
> 我需要設計一個電商系統的微服務架構。
> 需要以下服務：
> 1. 使用者服務（認證、個人資料）
> 2. 商品服務（CRUD、搜尋）
> 3. 訂單服務（建立、付款、狀態追蹤）
> 4. 通知服務（Email、簡訊）
>
> 技術堆疊：
> - Spring Boot 3.4 + Java 21
> - PostgreSQL（使用者、訂單）
> - MongoDB（商品目錄）
> - Redis（快取）
> - Kafka（事件驅動）
> - Docker + Kubernetes
>
> 請設計完整架構，包含：
> - 服務間通訊方式
> - 資料庫設計
> - API 端點設計
> - 部署架構

> 我有一些調整：
> 1. 商品搜尋需要使用 Elasticsearch
> 2. 訂單服務需要加入 Saga Pattern 處理分散式交易
> 3. 增加 API Gateway 使用 Spring Cloud Gateway

<TAB>  # 切換回 Build 模式
> 按照剛才的計畫，先實作使用者服務。
> 建立 Spring Boot 專案結構，包含：
> 1. Entity、Repository、Service、Controller 各層
> 2. JWT 認證
> 3. 單元測試和整合測試
> 4. Dockerfile
> 5. docker-compose.yml（含 PostgreSQL）

# 在 Build 模式中
> 在 src/controllers/ 下建立一個 ProductController.ts
> 技術需求：
> - Express.js + TypeScript
> - 實作完整 CRUD（GET/POST/PUT/DELETE）
> - 使用 Zod 做輸入驗證
> - 回應格式使用統一的 ApiResponse<T> 包裝
> - 錯誤處理使用自訂 AppError 類別
> - 加入 JSDoc 註解

# 單元測試
> 為 src/services/UserService.ts 產生完整的單元測試。
> 使用 Vitest + testing-library。
> 需要覆蓋所有 public 方法。
> 使用 vi.mock() 模擬外部依賴。
> 邊界條件也要測試。

# 整合測試
> 為 UserController 產生整合測試。
> 使用 supertest + testcontainers（PostgreSQL）。
> 測試完整的 HTTP 請求/回應流程。

# E2E 測試
> 為使用者登入流程產生 Playwright E2E 測試。
> 包含：
> 1. 正常登入
> 2. 錯誤密碼
> 3. 帳號鎖定
> 4. 記住我功能

# Plan 模式：分析重構範圍
<TAB>
> 分析 src/services/ 目錄下的所有 Service 類別。
> 識別以下問題：
> 1. 重複的程式碼
> 2. 過大的函式（超過 50 行）
> 3. 缺乏介面抽象
> 4. 硬編碼的設定值
> 5. 缺乏錯誤處理
> 提供重構計畫和優先順序。

# Build 模式：執行重構
<TAB>
> 根據剛才的分析，從高優先順序開始重構：
> 1. 先抽取共用邏輯到 BaseService
> 2. 將硬編碼的設定搬到 config
> 3. 添加統一的錯誤處理
> 4. 確保所有現有測試仍通過

# 提供錯誤訊息
> 執行 npm test 時出現以下錯誤：
> TypeError: Cannot read property 'find' of undefined
>   at UserService.findById (/src/services/UserService.ts:42:30)
>   at UserController.getUser (/src/controllers/UserController.ts:18:28)
> 請分析原因並修正。

# AI 會自動：
# 1. 讀取 UserService.ts 第 42 行附近
# 2. 讀取 UserController.ts 第 18 行附近
# 3. 搜尋相關的依賴注入設定
# 4. 識別問題（可能是 Repository 未正確注入）
# 5. 提供修正方案
# 6. 修正後重新執行測試驗證

# 批次添加日誌功能
> 找出 src/controllers/ 下所有 Controller 檔案。
> 在每個公開 API 方法的開頭加入日誌記錄：
> - 記錄方法名稱
> - 記錄請求參數（排除敏感欄位）
> - 記錄響應狀態碼
> - 記錄執行時間

# 批次更新 import
> 將專案中所有 import moment from 'moment'
> 更改為 import dayjs from 'dayjs'
> 並更新所有相關的 API 呼叫

# 批次修正 lint 錯誤
> 執行 eslint 檢查所有 src/ 下的檔案。
> 自動修正所有可以安全修正的錯誤。
> 對於需要手動判斷的錯誤，列出清單讓我決定。

# 產生 README
> 分析本專案的結構和功能，產生一份完整的 README.md。
> 包含：
> 1. 專案說明
> 2. 技術堆疊
> 3. 快速開始（安裝、設定、執行）
> 4. 專案結構
> 5. API 文件連結
> 6. 貢獻指南
> 7. 授權

# 產生 API 文件
> 分析 src/controllers/ 和 src/routes/ 下的所有端點。
> 產生 OpenAPI 3.0 規格書（YAML 格式）。
> 包含：請求/回應範例、錯誤碼、認證方式。

# 產生架構文件
> 使用 Mermaid 語法產生以下架構圖：
> 1. 系統架構圖（C4 Model - Context Level）
> 2. 容器圖（Container Level）
> 3. 元件圖（Component Level）
> 4. 部署圖（Deployment Diagram）
> 5. 資料流圖

# 直接呼叫 Explore SubAgent
@general 這個專案的認證機制是如何實作的？

# 深度探索
@general 分析本專案所有使用到 Redis 的地方，
包含快取策略、過期時間設定、Key 命名規則

# 追蹤呼叫鏈
@general 追蹤 UserService.processPayment() 的完整呼叫鏈，
從 Controller 入口到 Repository 層，
列出每一層的參數轉換和驗證邏輯

# 分析設計模式
@general 分析本專案使用了哪些設計模式？
對於每個模式：
1. 在哪些檔案中使用
2. 如何實作
3. 是否有改進空間

# 依賴關係分析
@general 分析 src/services/ 目錄下所有 Service 之間的依賴關係，
畫出依賴圖（Mermaid 語法），
標記是否有循環依賴

# 查詢套件相容性
請幫我確認 react-query v5 和 next.js 15 的相容性，
包含 breaking changes 和遷移指南

# 外部 API 文件研究
研究 Stripe API v2025 的 Payment Intents 新欄位，
列出所有新增與移除的參數

{
  "$schema": "https://opencode.ai/config.json",
  "commands": {
    "review": {
      "description": "程式碼審查",
      "prompt": "請審查 {file} 中的程式碼變更，重點關注安全性和效能。{file:.opencode/rules/review-checklist.md}"
    },
    "test-gen": {
      "description": "測試生成",
      "prompt": "為 {file} 產生完整的測試套件。使用 {file:.opencode/rules/testing.md} 中的測試規範。"
    },
    "api-doc": {
      "description": "API 文件生成",
      "prompt": "分析 {file} 中的 API 端點，產生 OpenAPI 3.0 規格。"
    },
    "security-check": {
      "description": "安全檢查",
      "prompt": "對 {file} 執行安全檢查，依據 {file:.opencode/rules/security.md}。"
    },
    "refactor": {
      "description": "智慧重構",
      "prompt": "分析 {file} 並建議重構方案。遵循 Clean Code 原則和 SOLID 原則。"
    },
    "migration": {
      "description": "資料庫遷移",
      "prompt": "根據目前的 Entity 變更，產生對應的資料庫遷移腳本（Flyway SQL 格式）。"
    }
  }
}

# 使用自訂指令
> /review src/controllers/PaymentController.ts
> /test-gen src/services/OrderService.ts
> /security-check src/auth/
> /migration

# 搜尋最新的技術資料
> 搜尋 Spring Boot 3.4 的新功能
> 搜尋 PostgreSQL 17 的效能改進
> 搜尋 Vite 6 相容性問題

# AI 會使用 websearch 工具搜尋，
# 並整合結果提供摘要

# 擷取技術文件
> 請到 https://docs.spring.io/spring-boot/docs/3.4.0/reference/html/
> 擷取關於 Actuator 的設定方式

# 擷取 API 規格
> 請擷取 https://api.example.com/openapi.yaml 的內容，
> 並根據這份 API 規格實作 Client SDK

# 查詢 + 實作
> 搜尋 NestJS Guard 的最新最佳實踐，
> 然後根據搜尋結果為本專案實作一個 RolesGuard。

# Context7 MCP（取代手動 webfetch）
> 使用 Context7 查詢 React Query v5 的 useSuspenseQuery 用法，
> 然後為本專案的 UserList 元件實作 Suspense 查詢。

# 使用 lsp 工具取得型別和定義資訊
> 使用 lsp 工具找出 UserService 介面的所有實作類別
> 使用 lsp 找出所有呼叫 processPayment 方法的地方
> 使用 lsp 取得 OrderDTO 的完整型別定義

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "lsp": "allow"
  }
}

<TAB>  # 切換到 Plan 模式
> 我需要建立一個「課程管理系統」的 REST API。
> 技術棧：NestJS + TypeScript + PostgreSQL + Prisma
>
> 業務實體：
> - Course（課程）：id, title, description, price, duration, instructor, category, status
> - Student（學生）：id, name, email, enrolledCourses
> - Enrollment（報名）：id, studentId, courseId, enrolledAt, status
>
> 需要：
> 1. 所有實體的 CRUD API
> 2. 多對多關係（學生 ↔ 課程 透過 Enrollment）
> 3. 分頁查詢
> 4. 篩選與排序
> 5. API 認證（JWT）
> 6. 請求驗證（class-validator）
> 7. Swagger 文件
>
> 請先設計 API 規格（端點、HTTP 方法、Request/Response 格式）。

# API 端點設計
POST   /api/v1/auth/login       # 登入
POST   /api/v1/auth/register    # 註冊
GET    /api/v1/courses           # 課程列表（分頁、篩選）
GET    /api/v1/courses/:id       # 課程詳情
POST   /api/v1/courses           # 建立課程
PUT    /api/v1/courses/:id       # 更新課程
DELETE /api/v1/courses/:id       # 刪除課程
GET    /api/v1/students          # 學生列表
GET    /api/v1/students/:id      # 學生詳情
POST   /api/v1/enrollments       # 報名
DELETE /api/v1/enrollments/:id   # 取消報名
GET    /api/v1/courses/:id/students  # 查詢課程學生
GET    /api/v1/students/:id/courses  # 查詢學生課程

<TAB>  # 切換到 Build 模式
> 根據剛才的設計，先建立 Prisma Schema。
> 包含完整的關聯定義和索引設計。

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Course {
  id          String       @id @default(uuid())
  title       String       @db.VarChar(200)
  description String       @db.Text
  price       Decimal      @db.Decimal(10, 2)
  duration    Int          // 分鐘
  instructor  String       @db.VarChar(100)
  category    String       @db.VarChar(50)
  status      CourseStatus @default(DRAFT)
  createdAt   DateTime     @default(now()) @map("created_at")
  updatedAt   DateTime     @updatedAt @map("updated_at")
  enrollments Enrollment[]

  @@index([category])
  @@index([status])
  @@index([instructor])
  @@map("courses")
}

model Student {
  id          String       @id @default(uuid())
  name        String       @db.VarChar(100)
  email       String       @unique @db.VarChar(255)
  password    String       @db.VarChar(255)
  createdAt   DateTime     @default(now()) @map("created_at")
  updatedAt   DateTime     @updatedAt @map("updated_at")
  enrollments Enrollment[]

  @@map("students")
}

model Enrollment {
  id         String           @id @default(uuid())
  studentId  String           @map("student_id")
  courseId   String           @map("course_id")
  enrolledAt DateTime         @default(now()) @map("enrolled_at")
  status     EnrollmentStatus @default(ACTIVE)
  student    Student          @relation(fields: [studentId], references: [id])
  course     Course           @relation(fields: [courseId], references: [id])

  @@unique([studentId, courseId])
  @@index([studentId])
  @@index([courseId])
  @@map("enrollments")
}

enum CourseStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

enum EnrollmentStatus {
  ACTIVE
  COMPLETED
  CANCELLED
}

> 現在產生 Course 模組的完整程式碼：
> 1. DTO（CreateCourseDto, UpdateCourseDto, CourseResponseDto, PaginationQueryDto）
> 2. Service（CourseService）
> 3. Controller（CourseController）
> 4. Module（CourseModule）
> 5. Guard（JwtAuthGuard）
> 6. 完整的 Swagger 裝飾器

// src/courses/course.controller.ts
import {
  Controller, Get, Post, Put, Delete,
  Body, Param, Query, UseGuards, HttpCode, HttpStatus,
  ParseUUIDPipe
} from '@nestjs/common';
import {
  ApiTags, ApiOperation, ApiResponse, ApiBearerAuth,
  ApiQuery, ApiParam
} from '@nestjs/swagger';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
import { CourseService } from './course.service';
import { CreateCourseDto } from './dto/create-course.dto';
import { UpdateCourseDto } from './dto/update-course.dto';
import { PaginationQueryDto } from '../common/dto/pagination-query.dto';
import { CourseResponseDto } from './dto/course-response.dto';

@ApiTags('Courses')
@Controller('api/v1/courses')
export class CourseController {
  constructor(private readonly courseService: CourseService) {}

  @Get()
  @ApiOperation({ summary: '查詢課程列表（分頁）' })
  @ApiResponse({ status: 200, description: '成功', type: [CourseResponseDto] })
  @ApiQuery({ name: 'category', required: false })
  @ApiQuery({ name: 'status', required: false, enum: ['DRAFT', 'PUBLISHED', 'ARCHIVED'] })
  async findAll(@Query() query: PaginationQueryDto) {
    return this.courseService.findAll(query);
  }

  @Get(':id')
  @ApiOperation({ summary: '查詢課程詳情' })
  @ApiParam({ name: 'id', description: '課程 ID（UUID）' })
  @ApiResponse({ status: 200, description: '成功', type: CourseResponseDto })
  @ApiResponse({ status: 404, description: '課程不存在' })
  async findOne(@Param('id', ParseUUIDPipe) id: string) {
    return this.courseService.findOne(id);
  }

  @Post()
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth()
  @ApiOperation({ summary: '建立課程' })
  @ApiResponse({ status: 201, description: '建立成功', type: CourseResponseDto })
  @ApiResponse({ status: 401, description: '未認證' })
  async create(@Body() createCourseDto: CreateCourseDto) {
    return this.courseService.create(createCourseDto);
  }

  @Put(':id')
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth()
  @ApiOperation({ summary: '更新課程' })
  @ApiResponse({ status: 200, description: '更新成功', type: CourseResponseDto })
  @ApiResponse({ status: 404, description: '課程不存在' })
  async update(
    @Param('id', ParseUUIDPipe) id: string,
    @Body() updateCourseDto: UpdateCourseDto,
  ) {
    return this.courseService.update(id, updateCourseDto);
  }

  @Delete(':id')
  @UseGuards(JwtAuthGuard)
  @ApiBearerAuth()
  @HttpCode(HttpStatus.NO_CONTENT)
  @ApiOperation({ summary: '刪除課程' })
  @ApiResponse({ status: 204, description: '刪除成功' })
  @ApiResponse({ status: 404, description: '課程不存在' })
  async remove(@Param('id', ParseUUIDPipe) id: string) {
    return this.courseService.remove(id);
  }

  @Get(':id/students')
  @ApiOperation({ summary: '查詢課程的學生名單' })
  async findStudentsByCourse(@Param('id', ParseUUIDPipe) id: string) {
    return this.courseService.findStudentsByCourse(id);
  }
}

> 為 CourseService 和 CourseController 產生完整測試。
> 使用 Jest + @nestjs/testing。
> 覆蓋所有 CRUD 操作和邊界情況。

// src/courses/course.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { CourseService } from './course.service';
import { PrismaService } from '../prisma/prisma.service';
import { NotFoundException } from '@nestjs/common';

describe('CourseService', () => {
  let service: CourseService;
  let prisma: PrismaService;

  const mockCourse = {
    id: '550e8400-e29b-41d4-a716-446655440000',
    title: 'TypeScript 進階教學',
    description: '深入解析 TypeScript 型別系統',
    price: 2999,
    duration: 480,
    instructor: 'John Doe',
    category: '程式語言',
    status: 'PUBLISHED',
    createdAt: new Date(),
    updatedAt: new Date(),
  };

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        CourseService,
        {
          provide: PrismaService,
          useValue: {
            course: {
              findMany: jest.fn(),
              findUnique: jest.fn(),
              create: jest.fn(),
              update: jest.fn(),
              delete: jest.fn(),
              count: jest.fn(),
            },
          },
        },
      ],
    }).compile();

    service = module.get<CourseService>(CourseService);
    prisma = module.get<PrismaService>(PrismaService);
  });

  describe('findOne', () => {
    it('應該回傳指定的課程', async () => {
      (prisma.course.findUnique as jest.Mock).mockResolvedValue(mockCourse);
      const result = await service.findOne(mockCourse.id);
      expect(result).toEqual(mockCourse);
      expect(prisma.course.findUnique).toHaveBeenCalledWith({
        where: { id: mockCourse.id },
        include: { enrollments: true },
      });
    });

    it('課程不存在時應拋出 NotFoundException', async () => {
      (prisma.course.findUnique as jest.Mock).mockResolvedValue(null);
      await expect(service.findOne('non-existent-id'))
        .rejects.toThrow(NotFoundException);
    });
  });

  describe('create', () => {
    it('應該建立並回傳新課程', async () => {
      const createDto = {
        title: 'TypeScript 進階教學',
        description: '深入解析 TypeScript 型別系統',
        price: 2999,
        duration: 480,
        instructor: 'John Doe',
        category: '程式語言',
      };
      (prisma.course.create as jest.Mock).mockResolvedValue(mockCourse);
      const result = await service.create(createDto);
      expect(result).toEqual(mockCourse);
      expect(prisma.course.create).toHaveBeenCalledWith({
        data: createDto,
      });
    });
  });

  describe('findAll', () => {
    it('應該回傳分頁結果', async () => {
      const courses = [mockCourse];
      (prisma.course.findMany as jest.Mock).mockResolvedValue(courses);
      (prisma.course.count as jest.Mock).mockResolvedValue(1);
      const result = await service.findAll({ page: 1, limit: 10 });
      expect(result.data).toEqual(courses);
      expect(result.total).toBe(1);
      expect(result.page).toBe(1);
    });
  });
});

> 產生以下部署相關檔案：
> 1. Dockerfile（多階段建置）
> 2. docker-compose.yml（含 PostgreSQL）
> 3. .dockerignore
> 4. GitHub Actions CI/CD workflow

# Explore SubAgent 會被 Build/Plan Agent 自動呼叫
# 也可以透過建立 read-only 自訂代理達到類似效果

# 常見使用場景：
> 找出所有使用 Redis 的檔案和用法
> 分析 src/utils/ 目錄下每個工具函式的功能
> 列出所有 API 端點和對應的 Controller、Service
> 找出哪些模組依賴 AuthService

# ❌ 不好的 Prompt
> 幫我寫一個登入功能

# ✅ 好的 Prompt
> 在 src/controllers/AuthController.ts 中實作登入 API。
> 技術需求：
> - Express.js + TypeScript
> - JWT Token（access token 15分鐘、refresh token 7天）
> - 使用 bcrypt 驗證密碼
> - 登入失敗 5 次鎖定帳號 30 分鐘
> - 回傳格式參考 src/types/ApiResponse.ts
> - 錯誤處理使用 src/utils/AppError.ts
> - 產生對應的單元測試

# .opencode/rules/anti-hallucination.md

## 防幻覺規則

1. 修改程式碼前必須先讀取原始檔案
2. 使用外部函式庫 API 時，必須先查詢文件確認
3. 不確定的資訊標記為 [需確認]
4. 生成的程式碼必須能通過編譯
5. 產生測試案例必須實際可執行

# 在 OpenCode 中執行驗證流程
> 請依序執行以下驗證：
> 1. tsc --noEmit（TypeScript 編譯檢查）
> 2. eslint src/（lint 檢查）
> 3. npm test（測試）
> 4. npm run build（確認可建置）
> 如果有錯誤，請修正後重新驗證。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sonarqube": {
      "type": "local",
      "command": ["npx", "-y", "@sonarsource/sonarqube-mcp-server"],
      "environment": {
        "SONARQUBE_URL": "{env:SONARQUBE_URL}",
        "SONARQUBE_TOKEN": "{env:SONARQUBE_TOKEN}"
      }
    }
  }
}

# 使用 SonarQube 分析
> 使用 SonarQube MCP 分析當前專案的程式碼品質。
> 重點關注：
> 1. 安全漏洞（Vulnerabilities）
> 2. 臭味程式碼（Code Smells）
> 3. 重複程式碼（Duplications）
> 4. 技術債務（Technical Debt）

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "frontend-dev": {
      "description": "前端開發專家",
      "prompt": "你是前端開發專家，專注在 packages/frontend/ 目錄。{file:./packages/frontend/AGENTS.md}"
    },
    "backend-dev": {
      "description": "後端開發專家",
      "prompt": "你是後端開發專家，專注在 packages/backend/ 目錄。{file:./packages/backend/AGENTS.md}"
    },
    "shared-lib": {
      "description": "共用模組開發者",
      "prompt": "你負責 packages/shared/ 共用模組，確保前後端相容性。"
    }
  }
}

# 使用 treefmt（推薦）
opencode install treefmt

# OpenCode 偵測到的格式化器：
# - Prettier（JavaScript/TypeScript）
# - Black（Python）
# - rustfmt（Rust）
# - gofmt（Go）
# - treefmt（多語言）

# AGENTS.md（多語言專案）

## 專案概覽
全端電商平台，包含三個主要模組。

## 模組結構
- `backend/` — Java 21 + Spring Boot 3.2 + PostgreSQL
- `frontend/` — React 18 + TypeScript + Vite
- `data-pipeline/` — Python 3.12 + Apache Airflow + Pandas

## 通用規則
- 所有 API 使用 JSON 格式
- 日期格式統一使用 ISO 8601
- ID 使用 UUID v4
- 所有模組共用 `shared/openapi.yaml` 定義的 API 契約

## Java 模組規範
- 使用 Gradle 8.x 建置
- 測試框架：JUnit 5 + Mockito
- 遵循 DDD 分層架構（domain/application/infrastructure/presentation）
- 使用 Flyway 資料庫遷移
- 不使用 Lombok

## React 模組規範
- 使用 pnpm 管理依賴
- 狀態管理：Zustand
- 樣式：Tailwind CSS
- 測試框架：Vitest + Testing Library
- 使用 React Hook Form + Zod 驗證
- 國際化：react-i18next

## Python 模組規範
- 使用 Poetry 管理依賴
- 遵循 PEP 8 + type hints
- 測試框架：pytest
- 使用 Pydantic v2 資料驗證

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "java-dev": {
      "description": "Java 後端開發專家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是 Java 21 + Spring Boot 3 專家。{file:./backend/AGENTS.md}",
      "tools": { "bash": true, "edit": true }
    },
    "react-dev": {
      "description": "React 前端開發專家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是 React 18 + TypeScript 專家。{file:./frontend/AGENTS.md}",
      "tools": { "bash": true, "edit": true }
    },
    "python-dev": {
      "description": "Python 資料管線專家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是 Python 3.12 + Airflow 專家。{file:./data-pipeline/AGENTS.md}",
      "tools": { "bash": true, "edit": true }
    },
    "api-contract": {
      "description": "API 契約管理",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你負責維護 shared/openapi.yaml 的 API 契約，確保前後端一致。",
      "tools": { "edit": true, "bash": false }
    }
  }
}

{
  "agent": {
    "code-reviewer": {
      "description": "嚴格的程式碼審查員",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.2,
      "prompt": "你是一位資深的程式碼審查員。請依照以下檢查清單審查程式碼：\n\n## 架構層面\n- 是否遵循現有的架構模式\n- 是否有不必要的複雜度\n- 模組間的耦合度是否合適\n\n## 程式碼品質\n- 命名是否清晰\n- 函式是否過長（建議不超過 30 行）\n- 是否有重複邏輯\n- 錯誤處理是否完善\n\n## 安全性\n- 使用者輸入是否有驗證\n- 是否有注入攻擊風險\n- 敏感資訊是否正確處理\n- 是否有適當的授權檢查\n\n## 效能\n- 是否有 N+1 查詢\n- 是否有不必要的記憶體分配\n- 是否有可能的記憶體洩漏\n\n## 測試\n- 是否有對應的測試\n- 邊界條件是否覆蓋\n- 測試是否有意義（不是為了湊覆蓋率）",
      "tools": {
        "bash": false,
        "edit": false,
        "write": false
      },
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

# Step 1：寫測試（紅燈）
> 我要實作一個 PriceCalculator 類別。
> 先只寫測試，不要寫實作。
> 測試案例：
> 1. 一般商品原價計算
> 2. 會員 9 折優惠
> 3. 滿 1000 元打 85 折
> 4. 折扣不能低於成本價
> 5. 多重折扣只取最惠

# Step 2：最小實作（綠燈）
> 現在實作 PriceCalculator，讓所有測試通過。
> 只寫最小可行的實作，不要提前優化。

# Step 3：重構
> 所有測試都通過了。
> 現在重構 PriceCalculator：
> 1. 將折扣策略抽取為策略模式
> 2. 使用 Chain of Responsibility 處理折扣優先順序
> 3. 確保所有測試仍然通過

# 從 Gherkin 規格產生測試
> 根據以下 Gherkin 規格產生 Cucumber 測試：
>
> Feature: 購物車結帳
>   Scenario: 一般使用者購買單一商品
>     Given 購物車中有一件價格 500 元的商品
>     When 使用者點擊「結帳」
>     Then 訂單總額應為 500 元
>     And 訂單狀態應為「待付款」
>
>   Scenario: VIP 使用者享有折扣
>     Given 購物車中有一件價格 1000 元的商品
>     And 使用者身份為 VIP
>     When 使用者點擊「結帳」
>     Then 訂單總額應為 900 元
>     And 折扣金額應為 100 元
>
>   Scenario: 庫存不足
>     Given 購物車中有一件商品，庫存為 0
>     When 使用者點擊「結帳」
>     Then 應顯示「庫存不足」錯誤
>     And 訂單不應被建立

# 企業安全編碼規範

## 輸入驗證
- 所有使用者輸入必須在入口點驗證（Controller/Handler 層）
- 使用白名單策略而非黑名單
- 數值型態做範圍檢查
- 字串長度限制
- 使用 parameterized query，禁止字串拼接 SQL
- 檔案上傳：檢查 MIME type、檔案大小、副檔名白名單

## 認證與授權
- 密碼：bcrypt（work factor ≥ 12）或 argon2id
- JWT：使用 RS256 或 ES256，禁止 HS256（用於內部服務間除外）
- Token 過期：Access Token ≤ 15 分鐘，Refresh Token ≤ 7 天
- 登入失敗鎖定：5 次失敗鎖定 30 分鐘
- 敏感操作需要二次驗證（2FA / 再次輸入密碼）

## 資料保護
- 敏感資料加密儲存（AES-256-GCM）
- 傳輸一律使用 TLS 1.3
- 日誌中遮罩敏感資訊（PII、信用卡號、密碼）
- API Response 不回傳多餘欄位（DTO 投影）

## Session 管理
- 使用 Secure + HttpOnly + SameSite Cookie
- Session ID 使用密碼學安全的隨機產生器
- 登出時銷毀 Session

## 錯誤處理
- 不向使用者暴露內部錯誤訊息
- 記錄完整錯誤到內部日誌
- 統一錯誤回應格式

## 依賴管理
- 定期執行 npm audit / OWASP Dependency Check
- 使用 lockfile 固定版本
- 禁止使用已知有 CVE 的套件版本

> 請實作使用者註冊 API。
> 必須遵循 {file:.opencode/rules/security-enterprise.md} 中的所有安全規範。
> 特別注意：
> 1. 密碼強度驗證（至少 8 字元、包含大小寫、數字、特殊符號）
> 2. Email 格式驗證
> 3. 防止重複註冊
> 4. Rate Limiting

# 分析效能瓶頸
> 分析 src/services/OrderService.ts 的效能問題。
> 重點關注：
> 1. N+1 查詢問題
> 2. 不必要的資料載入
> 3. 可以快取的查詢
> 4. 缺乏分頁的大量查詢
> 5. 同步操作可以改為非同步的

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "agent": {
    "plan": {
      "model": "anthropic/claude-opus-4-6"
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

# OpenCode 預設會自動更新到最新版本
# 可透過設定停用

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

# Homebrew
brew upgrade opencode

# npm
npm install -g opencode-ai@latest

# Scoop
scoop update opencode

# 安裝腳本
curl -fsSL https://opencode.ai/install | bash

# 啟用除錯日誌
opencode --debug

# 日誌存放位置
# Linux/macOS: ~/.local/share/opencode/logs/
# Windows: %APPDATA%/opencode/logs/
# 或使用 XDG 規範路徑

# 日誌內容包含：
# - API 請求/回應（脫敏）
# - 工具執行紀錄
# - 錯誤和警告
# - 效能指標

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    },
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny"
        }
      }
    },
    "code-reviewer": {
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny"
      }
    }
  }
}

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

---
name: database-migration
description: 產生和管理資料庫遷移腳本
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: database
---

你是一位資料庫遷移專家。

## 職責
1. 根據實體變更產生遷移腳本
2. 確保遷移的可逆性（支援 up/down）
3. 驗證遷移腳本的安全性
4. 處理資料遷移（不只是結構遷移）

## 規則
- 每個遷移腳本必須有 rollback 方案
- 大表修改必須使用 online DDL
- 禁止在遷移中使用 DROP TABLE（改用 rename + 新建）
- 索引建立使用 CONCURRENTLY

.opencode/skills/<name>/SKILL.md    # 專案層級
~/.config/opencode/skills/<name>/SKILL.md  # 全域層級
.claude/skills/<name>/SKILL.md       # Claude Code 相容（若未停用）
~/.claude/skills/<name>/SKILL.md     # 全域 Claude 相容
.agents/skills/<name>/SKILL.md       # Agent 相容
~/.agents/skills/<name>/SKILL.md     # 全域 Agent 相容

{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

// .opencode/tools/check-coverage.ts
import { tool } from "opencode/tool";

export default tool({
  name: "check_coverage",
  description: "檢查指定模組的測試覆蓋率",
  parameters: {
    module: {
      type: "string",
      description: "要檢查的模組路徑"
    },
    threshold: {
      type: "number",
      description: "最低覆蓋率門檻（百分比）",
      default: 80
    }
  },
  async execute({ module, threshold }) {
    const { execSync } = await import("child_process");
    const result = execSync(
      `npx vitest --coverage --reporter=json ${module}`,
      { encoding: "utf-8" }
    );
    const coverage = JSON.parse(result);
    const totalCoverage = coverage.total.lines.pct;

    if (totalCoverage < threshold) {
      return `⚠️ 覆蓋率 ${totalCoverage}% 低於門檻 ${threshold}%`;
    }
    return `✅ 覆蓋率 ${totalCoverage}%，通過門檻 ${threshold}%`;
  }
});

// .opencode/tools/project-utils.ts
import { tool } from "opencode/tool";

export const listEndpoints = tool({
  name: "list_endpoints",
  description: "列出所有 API 端點",
  parameters: {},
  async execute() {
    // ...
  }
});

export const checkDeps = tool({
  name: "check_deps",
  description: "檢查依賴更新",
  parameters: {},
  async execute() {
    // ...
  }
});

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

export OPENCODE_DISABLE_CLAUDE_CODE=1        # 停用所有 .claude 支援
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # 僅停用 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # 僅停用 .claude/skills

# 編碼標準

## TypeScript 規範
- 使用 strict mode
- 使用 interface 而非 type（除非需要 union type）
- 避免 any，使用 unknown + type guard
- 非同步操作使用 async/await，避免 .then()

## 測試規範
- 每個 Service 至少 80% 覆蓋率
- 測試檔案命名：*.test.ts 或 *.spec.ts
- 使用 describe/it 結構
- 每個 it 只測試一件事

# 步驟 1: 在測試環境安裝新版本
npm install -g opencode-ai@1.2.21

# 步驟 2: 驗證 CLI
opencode --version

# 步驟 3: 驗證設定檔
opencode config validate

# 步驟 4: 驗證 MCP 伺服器
opencode mcp status

# 步驟 5: 驗證外掛
opencode plugin list
opencode plugin check-compatibility

# 步驟 6: 在測試專案中執行基本操作
#   - 開啟對話
#   - 切換 Plan/Build
#   - 執行工具（edit、bash、grep）
#   - 測試 MCP 伺服器呼叫
#   - 測試自訂工具
#   - 測試技能

# 方法一：安裝指定版本
npm install -g opencode-ai@1.2.16

# 方法二：Homebrew 回滾
brew uninstall opencode
brew install anomalyco/tap/opencode@1.2.16

# 方法三：使用 docker 固定版本
docker run -it ghcr.io/anomalyco/opencode:1.2.16

# .github/workflows/opencode-verify.yml
name: OpenCode Upgrade Verification

on:
  pull_request:
    paths:
      - 'opencode.json'
      - '.opencode/**'

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install OpenCode
        run: |
          curl -fsSL https://opencode.ai/install | bash
          opencode --version

      - name: Validate Config
        run: opencode config validate

      - name: Check MCP Servers
        run: opencode mcp status

      - name: Run Basic Smoke Test
        run: |
          echo "測試基本 CLI 功能"
          opencode --help

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "autoupdate": false,

  "permission": {
    "read": "allow",
    "edit": "allow",
    "bash": "ask",
    "webfetch": "allow",
    "websearch": "allow",
    "external_directory": "deny"
  },

  "security": {
    "audit_log": true,
    "audit_log_path": "/var/log/opencode/audit.log",
    "sensitive_patterns": [
      "password",
      "secret",
      "api_key",
      "token",
      "credit_card"
    ],
    "blocked_domains": [
      "pastebin.com",
      "transfer.sh"
    ]
  },

  "enabled_providers": ["anthropic", "amazon-bedrock"],
  "disabled_providers": ["openai", "openrouter", "google"]
}

{
  "$schema": "https://opencode.ai/config.json",
  "_comment": "企業基礎設定 — 所有團隊繼承",
  "share": "disabled",
  "autoupdate": false,
  "enabled_providers": ["anthropic", "amazon-bedrock"],
  "permission": {
    "bash": "ask",
    "admin": "deny"
  },
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    },
    "sonarqube": {
      "type": "local",
      "command": ["npx", "-y", "@sonarsource/sonarqube-mcp-server"],
      "environment": {
        "SONARQUBE_URL": "https://sonarqube.internal.company.com",
        "SONARQUBE_TOKEN": "{env:SONARQUBE_TOKEN}"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "_extends": "base",
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "build": { "model": "anthropic/claude-sonnet-4-5" },
    "plan": { "model": "anthropic/claude-opus-4-6" }
  },
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira-mcp.internal.company.com/mcp",
      "environment": {
        "JIRA_TOKEN": "{env:JIRA_TOKEN}"
      }
    }
  }
}

任務類型 → 自動選擇最適模型
├── 複雜程式碼實作 → Hephaestus（gpt-5.4）
├── 架構設計與規劃 → Prometheus（claude-opus-4-6 / kimi-k2.5 / glm-5）
├── 架構除錯 → Oracle（按需）
├── 文件搜尋 → Librarian（快速模型）
├── 程式碼探索 → Explore（快速模型，唯讀）
└── 協調與編排 → Sisyphus 自身（claude-opus-4-6）

# 一鍵啟動 OmO + OpenCode
ultrawork

# 或簡寫
ulw

# 等效於手動啟動 OpenCode + 載入 OmO 外掛 + 初始化所有 Discipline Agents

問題：AI 在 Line 42 插入程式碼後，
      原本 Line 50 的程式碼變成了 Line 53。
      如果 AI 接著要修改原 Line 50，就會改錯地方。

每一行程式碼都有一個唯一的 Hash ID（LINE#ID）
修改時使用 Hash ID 定位，而非行號。
即使行號漂移，Hash ID 仍然正確指向目標行。

# 在 OpenCode TUI 中
/init-deep

project-root/
├── AGENTS.md                          # 專案級（全域規則）
├── src/
│   ├── AGENTS.md                      # src 級規則
│   ├── controllers/
│   │   └── AGENTS.md                  # Controller 層規則
│   ├── services/
│   │   └── AGENTS.md                  # Service 層規則
│   └── models/
│       └── AGENTS.md                  # Model 層規則
├── tests/
│   └── AGENTS.md                      # 測試規則
└── infra/
    └── AGENTS.md                      # 基建規則

# AGENTS.md (Root)

## 專案概覽
這是一個 Next.js 15 + TypeScript 全端應用程式。

## 架構決策紀錄
- ADR-001: 使用 App Router（非 Pages Router）
- ADR-002: 使用 Server Components 為預設
- ADR-003: 使用 tRPC 進行類型安全的 API 呼叫

## 全域規則
- 所有檔案使用 UTF-8 編碼
- 所有 commit 遵循 Conventional Commits
- 禁止使用 var，使用 const/let
- 所有 async 函式必須有 error handling

# AGENTS.md (src/controllers/)

## Controller 層規則
- 每個路由一個 Controller 檔案
- Controller 不含業務邏輯，只做路由和入參驗證
- 使用 Zod schema 驗證請求
- 統一使用 ApiResponse<T> 包裝回應
- 錯誤一律拋出 AppError，由全域 middleware 處理

# Prometheus 由 Sisyphus 自動調用
# 也可以手動請求：
> 我需要 Prometheus 分析一下把 REST API 遷移到 GraphQL 的可行性。
> 請提供至少 3 種遷移策略，各自的優缺點和風險。

## 策略分析報告

### 策略 A: Big Bang 遷移
- 優點: 一步到位，避免維護兩套系統
- 缺點: 風險高，測試範圍大
- 風險等級: 🔴 高
- 預估工期: 4 週

### 策略 B: 漸進式遷移（Strangler Fig Pattern）
- 優點: 低風險，可隨時回滾
- 缺點: 需要維護兩套系統
- 風險等級: 🟢 低
- 預估工期: 8 週

### 策略 C: 並行運行
- 優點: 完全不影響現有系統
- 缺點: 資源消耗較大
- 風險等級: 🟡 中
- 預估工期: 6 週

### 建議
推薦策略 B（漸進式遷移），原因...

# 大規模重構（並行執行）
> 我需要對以下模組進行並行重構：
> 1. UserService - 改用 Repository Pattern
> 2. ProductService - 加入快取層
> 3. OrderService - 加入 Saga Pattern
> 4. 同時為以上三個 Service 產生單元測試
> 5. 更新相關文件
>
> 請使用背景代理並行處理。

---
name: k8s-ops
description: Kubernetes 運維技能
mcp:
  k8s:
    type: local
    command: ["npx", "-y", "@mcp/kubernetes-server"]
    environment:
      KUBECONFIG: "{env:KUBECONFIG}"
---

你是 Kubernetes 運維專家。使用 k8s MCP 伺服器管理叢集。

# Todo Enforcer 會：
# 1. 要求代理在任務開始時建立 TODO 清單
# 2. 追蹤每個 TODO 的完成狀態
# 3. 任務結束時驗證所有 TODO 已完成
# 4. 未完成的 TODO 會被報告

# Comment Checker 會偵測：
# - // TODO: ... （未完成的事項）
# - // FIXME: ... （已知問題）
# - // HACK: ... （臨時解法）
# - // XXX: ... （需要注意）
# 並要求代理完成或移除這些臨時註解

# OmO 自動偵測並連接專案的 LSP Server
# 支援：TypeScript、Python、Java、Go、Rust 等

# 提供的功能：
# - 精確的符號解析
# - 型別推導
# - 參照搜尋
# - 重構支援

# AST-Grep 提供結構化程式碼搜尋
# 比 grep 更精確，因為它理解程式碼的 AST 結構

# 範例：找出所有未 await 的 async 函式呼叫
# AST-Grep 可以精確匹配語法結構，而非簡單的文字匹配

# OmO 可以在 Tmux session 中管理多個代理窗格
# 每個背景代理在獨立的 Tmux pane 中運行
# 主視窗顯示 Sisyphus 的協調狀態

# Tmux 整合設定（在 OmO 設定檔中）
# tmux:
#   enabled: true
#   layout: "tiled"
#   auto_split: true

# 方法一：直接替換（CLAUDE.md 自動識別）
# 1. 安裝 OpenCode + OmO
# 2. 執行 ultrawork
# 3. OmO 自動讀取現有的 CLAUDE.md 和 .claude/skills/

# 方法二：產生 AGENTS.md（推薦）
# 1. 執行 /init-deep
# 2. 手動整合 CLAUDE.md 中的規則到 AGENTS.md
# 3. 設定 OPENCODE_DISABLE_CLAUDE_CODE=true（可選）

{
  "model_routing": {
    "default": "claude-opus-4-6",
    "rules": [
      {
        "task_type": "deep",
        "model": "gpt-5.4",
        "reason": "深度程式碼實作需要長上下文和精確編輯"
      },
      {
        "task_type": "ultrabrain",
        "model": "gpt-5.4",
        "options": { "reasoningEffort": "high" },
        "reason": "高難度架構決策使用 xhigh 推理"
      },
      {
        "task_type": "quick",
        "model": "claude-haiku-4-5",
        "reason": "簡單任務用輕量模型即可"
      },
      {
        "task_type": "visual-engineering",
        "model": "kimi-k2.5",
        "reason": "前端 UI 任務"
      }
    ]
  }
}

# 前置需求：Bun 1.3.9+
curl -fsSL https://bun.sh/install | bash

# 方法一：使用 Bun（推薦）
bun install -g oh-my-openagent

# 方法二：使用 npm
npm install -g oh-my-openagent

# 方法三：在 opencode.json 中設定為外掛
# 見下方設定

# 驗證安裝
ultrawork --version
# 或
ulw --version

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-openagent"]
}

# OmO 全域設定
version: "3.13"

# Discipline Agents 設定
agents:
  sisyphus:
    model: claude-opus-4-6
    max_steps: 200
    temperature: 0.3
  hephaestus:
    model: gpt-5.4
    max_steps: 500
    temperature: 0.2
  prometheus:
    model: claude-opus-4-6
    max_steps: 100
    temperature: 0.5

# 背景代理設定
background_agents:
  max_concurrent: 5
  timeout_minutes: 30

# Hash-Anchored Edit 設定
hash_edit:
  enabled: true
  validation: strict

# IntentGate 設定
intent_gate:
  enabled: true
  complexity_threshold: medium  # low/medium/high

# Ralph Loop 設定
ralph_loop:
  enabled: true
  max_retries: 3
  checks:
    - compile
    - test
    - lint

# Todo Enforcer 設定
todo_enforcer:
  enabled: true
  strict: true

# Comment Checker 設定
comment_checker:
  enabled: true
  patterns:
    - "TODO:"
    - "FIXME:"
    - "HACK:"
    - "XXX:"

# 專案特定 OmO 設定
extends: global  # 繼承全域設定

agents:
  hephaestus:
    model: gpt-5.4
    context_files:
      - "src/**/*.ts"
      - "tests/**/*.ts"

# 專案特定規則
rules:
  - "所有 API 端點必須有 OpenAPI 文件"
  - "所有 Service 必須有單元測試"

$ ulw
# 啟動 OmO + OpenCode

> /init-deep
# OmO Librarian 掃描專案，產生階層式 AGENTS.md

# AGENTS.md（自動產生）

## 專案概覽
Spring Boot 2.7 單體應用，包含使用者、訂單、商品、支付、通知五大領域。

## 架構決策紀錄
- ADR-001: 目前為單體架構，所有模組共用資料庫
- ADR-002: 使用者認證使用 Spring Security + JWT
- ADR-003: 所有 Repository 使用 Spring Data JPA

## 模組依賴分析（自動檢測）
- user-module → 無依賴
- product-module → 無依賴
- order-module → 依賴 user-module, product-module
- payment-module → 依賴 order-module
- notification-module → 依賴 user-module, order-module

## 潛在問題
- ⚠️ 發現 15 處循環依賴
- ⚠️ Service 層存在跨模組直接呼叫（45 處）
- ⚠️ 共用資料庫耦合嚴重

> 使用 Prometheus 分析這個專案，產生微服務拆分策略。
> 目標：拆分為 5 個微服務（user/product/order/payment/notification）。
> 考慮：
> 1. 資料庫拆分策略
> 2. 服務間通訊方式（REST vs 事件驅動）
> 3. 共用程式碼處理
> 4. 遷移順序和風險

## 微服務拆分策略分析報告

### 策略 A：漸進式拆分（Strangler Fig）— 推薦

**遷移順序（依耦合度由低到高）：**

1. notification-service（最低耦合 → 最先拆分）
   - 風險：低
   - 預估工時：2 天
   - 通訊方式：事件驅動（RabbitMQ/Kafka）

2. user-service（基礎服務）
   - 風險：中
   - 預估工時：3 天
   - 通訊方式：REST（gRPC 可選）

3. product-service（獨立領域）
   - 風險：低
   - 預估工時：2 天
   - 通訊方式：REST

4. payment-service（外部整合多）
   - 風險：高
   - 預估工時：4 天
   - 通訊方式：Saga Pattern

5. order-service（核心業務，依賴最多 → 最後拆分）
   - 風險：高
   - 預估工時：5 天
   - 通訊方式：REST + Event

### 資料庫拆分建議
- 第一步：Schema per Service（同一個 DB，不同 Schema）
- 第二步：Database per Service（獨立 DB 實例）

### 共用程式碼處理
- 抽取 common-lib（DTO、工具類別、常數）
- 使用 Maven 多模組管理

> 按照 Prometheus 的建議，開始執行拆分。
> 先處理 notification-service 和 product-service（無依賴，可並行）。
> 
> 背景代理 #1：拆分 notification-service
> - 建立新的 Spring Boot 專案結構
> - 遷移相關的 Controller/Service/Repository
> - 設定 RabbitMQ 事件消費
> - 產生 API 文件
> - 產生單元測試和整合測試
>
> 背景代理 #2：拆分 product-service
> - 建立新的 Spring Boot 專案結構
> - 遷移商品相關的所有程式碼
> - 設定獨立的 PostgreSQL Schema
> - 產生 REST API
> - 產生測試
>
> 主代理：同時修改原單體應用
> - 替換直接呼叫為 REST Client / Event Publisher
> - 保持原有功能不中斷

# OmO Ralph Loop 自動執行：
# ✅ notification-service 編譯通過
# ✅ notification-service 18 個測試全部通過
# ✅ product-service 編譯通過
# ✅ product-service 25 個測試全部通過
# ✅ 原單體應用 regression test 通過
# ✅ 整合測試（跨服務呼叫）通過

# Todo Enforcer 報告：
# ✅ [完成] 建立 notification-service 專案結構
# ✅ [完成] 遷移 NotificationController
# ✅ [完成] 遷移 NotificationService
# ✅ [完成] 設定 RabbitMQ consumer
# ✅ [完成] 產生 API 文件
# ✅ [完成] 產生測試程式碼
# ✅ [完成] 建立 product-service 專案結構
# ✅ [完成] 遷移所有商品相關程式碼
# ⚠️ [未完成] 更新部署腳本 → 尚需處理

# omo.config.yaml 效能優化
background_agents:
  max_concurrent: 3
  idle_timeout: 300  # 閒置 5 分鐘回收

intent_gate:
  complexity_threshold: medium  # 避免簡單任務啟動完整編排

ralph_loop:
  max_retries: 2  # 減少重試次數
  checks:
    - compile  # 只檢查編譯
    - test     # 只檢查測試

model_routing:
  default: claude-sonnet-4-5  # 預設使用中階模型
  rules:
    - task_type: search
      model: claude-haiku-4-5  # 搜尋用小模型
    - task_type: planning
      model: claude-opus-4-6   # 規劃用大模型

# 方法一：拖曳截圖到 TUI（支援 iTerm2 / Kitty / WezTerm）
> 請根據這個截圖實作登入頁面

# 方法二：指定圖片路徑
> /looker ./designs/login-page.png --framework react --responsive

# 方法三：Figma URL
> /looker https://figma.com/file/... --component LoginForm

# Metis 由 IntentGate 在偵測到複雜需求時自動調用
# 也可以手動請求：
> /consult 我想把現有的 monolith 拆成微服務，但團隊只有 3 人
> Metis 會先分析可行性、提出風險和替代方案
> 再由 Prometheus 制定詳細執行計畫

# omo.config.yaml
model_routing:
  rules:
    - task_type: ultrabrain
      model: gpt-5.4-xhigh
      fallback: claude-opus-4-6
      budget_limit: 50.00  # 單次任務 Token 預算上限（美元）
      confirmation: true   # 超過預算時要求使用者確認

## Session 分析報告（最近 30 天）

### 統計
- 總 Session 數：47
- 平均 Session 時長：23 分鐘
- 最常使用的代理：Hephaestus（38%）、Sisyphus（25%）
- 最常處理的任務類型：功能開發（45%）、除錯（28%）

### Token 消耗
- 總消耗：$127.50
- 最高單次 Session：$12.30（微服務遷移規劃）
- 平均每 Session：$2.71

### 效率指標
- Ralph Loop 首次通過率：72%
- 背景代理平均使用率：3.2 個/session
- Hash-Anchored Edit 衝突率：0.3%

# 啟用 Think Mode
> /think on

# 代理回應時會顯示思考過程：
🧠 Think Mode:
├── 分析需求：使用者要求重構 UserService
├── 評估方案 A：Repository Pattern（適合，解耦資料層）
├── 評估方案 B：CQRS（過度設計，目前規模不需要）
├── 決策：選擇 Repository Pattern
├── 風險：現有 20+ Controller 依賴 UserService，需逐一更新
└── 執行計畫：分 3 步驟，先建抽象層再遷移

📝 執行：
# 開始實作...

.omx/
├── session.json          # 當前 Session 狀態
├── agents/
│   ├── sisyphus.json     # Sisyphus 狀態
│   ├── hephaestus.json   # Hephaestus 任務佇列
│   └── bg-agents/        # 背景代理狀態
├── todos.json            # Todo Enforcer 記錄
└── ralph-reports/        # Ralph Loop 報告

// oh-my-openagent.jsonc（推薦新名稱）
// 舊名稱 oh-my-opencode.jsonc 仍可使用
{
  // 版本
  "$schema": "https://ohmyopenagent.com/config-schema.json",
  "version": "3.17",

  // Agent 設定
  "agents": {
    "sisyphus": {
      "model": "claude-opus-4-6",
      "steps": 200
    },
    "hephaestus": {
      "model": "gpt-5.4"
    },
    "looker": {
      "enabled": true,
      "defaultFramework": "react"
    },
    "metis": {
      "enabled": true,
      "autoConsult": true  // 複雜需求自動啟動諮詢
    }
  },

  // ultrabrain 預算控制
  "ultrabrain": {
    "budgetPerTask": 50.00,
    "requireConfirmation": true
  },

  // Model Fallbacks（v3.17 支援混合格式）
  "fallback_models": [
    "claude-opus-4-6",
    { "model": "kimi-k2.5", "temperature": 0.3 },
    "gpt-5.4"
  ]
}

# 停用遙測方式一
export OMO_SEND_ANONYMOUS_TELEMETRY=0

# 停用遙測方式二
export OMO_DISABLE_POSTHOG=1

# 執行 OmO 環境診斷
bunx oh-my-openagent doctor

# 檢查項目：
# ✅ Plugin 註冊狀態
# ✅ 設定檔格式
# ✅ 模型可用性
# ✅ OpenCode 版本相容性（≥ v1.4.0）
# ✅ Bun 版本（≥ 1.3.9）
# ✅ 環境變數

{
  "agents": {
    "my-agent": {
      "prompt": "file://./prompts/my-agent-system.md"
    }
  }
}

// .opencode/oh-my-openagent.jsonc
{
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,
    "tmux_visualization": true
  }
}

# 安裝 Orchestrator CLI
npm install -g openwork-orchestrator

# 基本用法
openwork-orchestrator run --task "重構所有 Service 類別" --project ./my-project

# 批次任務
openwork-orchestrator batch --tasks tasks.yaml --concurrency 3

# 排程任務
openwork-orchestrator schedule --cron "0 2 * * *" --task "每日安全掃描"

tasks:
  - name: "重構 UserService"
    type: refactor
    target: src/services/UserService.ts
    skills:
      - clean-code
      - testing
    agent: build

  - name: "更新 API 文件"
    type: documentation
    target: src/controllers/
    skills:
      - api-docs
    agent: plan

  - name: "安全掃描"
    type: security
    target: src/
    skills:
      - security-audit
    agent: code-reviewer

{
  "router": {
    "whatsapp": {
      "enabled": true,
      "webhook_url": "https://your-server.com/webhook/whatsapp"
    },
    "slack": {
      "enabled": true,
      "bot_token": "{env:SLACK_BOT_TOKEN}",
      "signing_secret": "{env:SLACK_SIGNING_SECRET}"
    },
    "telegram": {
      "enabled": true,
      "bot_token": "{env:TELEGRAM_BOT_TOKEN}"
    }
  }
}

# 搜尋技能套件
opkg search "api design"

# 安裝技能套件
opkg install @openwork/skill-api-designer
opkg install @openwork/skill-terraform
opkg install @openwork/skill-k8s-ops

# 列出已安裝套件
opkg list

# 更新套件
opkg update @openwork/skill-api-designer

# 發佈自訂套件
opkg publish ./my-skill

# macOS 和 Linux：直接下載安裝
# Windows：透過付費支援計畫取得（openworklabs.com/pricing#windows-support）

# 或使用 npm（Orchestrator CLI）
npm install -g openwork-orchestrator

# Arch Linux
sudo pacman -S --needed webkit2gtk-4.1
# 安裝 pinned OpenCode 版本
curl -fsSL https://opencode.ai/install | bash -s -- --version "$(node -e \
  "process.stdout.write(JSON.parse(require('fs').readFileSync('constants.json','utf8')).opencodeVersion.trim().replace(/^v/,''))")" \
  --no-modify-path

# 啟動 Dev Mode（使用環境變數）
OPENWORK_DEV_MODE=1 openwork

# 或在設定檔中啟用
# settings.json:
# { "devMode": true }

# templates/api-scaffold.yaml
name: "API 腳手架"
description: "建立完整的 REST API 專案結構"
version: "1.2"
parameters:
  - name: project_name
    type: string
    required: true
  - name: database
    type: enum
    values: [postgresql, mysql, mongodb]
    default: postgresql
steps:
  - type: prompt
    content: "建立 ${project_name} 專案，使用 ${database} 資料庫"
    agent: build
  - type: prompt
    content: "產生 API 文件和 Swagger UI"
    agent: plan
  - type: prompt
    content: "產生單元測試和整合測試"
    agent: build

# 使用快捷鍵 Ctrl+Shift+W 開啟 Workspace Switch Overlay
# 或透過 CLI：
openwork start --workspace /path/to/project --approval auto

# 啟動 Den（Docker 開發環境）
openwork den start --template fullstack-ts

# Den 會自動：
# 1. 拉取 Docker Image
# 2. 設定開發環境（Node.js、資料庫等）
# 3. 啟動 OpenCode Server
# 4. 連接 OpenWork Desktop

// opencode.json（OpenWork 使用相同格式）
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder (local)"
        }
      }
    }
  }
}

# 使用內部 OpenPackage Registry
opkg config set registry https://opkg.internal.company.com

# 團隊 A 發佈技能
opkg publish --scope @team-a ./skills/api-designer

# 團隊 B 安裝技能
opkg install @team-a/skill-api-designer

# 停用所有 Claude Code 相容性
export OPENCODE_DISABLE_CLAUDE_CODE=true

# 僅停用 CLAUDE.md 規則讀取
export OPENCODE_DISABLE_CLAUDE_CODE_RULES=true

# 僅停用 .claude/skills/ 讀取
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gitlab": {
      "type": "remote",
      "url": "https://gitlab-mcp.company.com/mcp",
      "environment": {
        "GITLAB_TOKEN": "{env:GITLAB_TOKEN}"
      }
    }
  }
}

# .github/workflows/ai-code-review.yml
name: AI Code Review Pipeline
on:
  pull_request:
    branches: [main, develop]
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  ai-code-review:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install OpenCode
        run: npm install -g opencode-ai@latest

      - name: Get Changed Files
        id: changed
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(ts|js|py|java|go|rs)$' || true)
          echo "files=$CHANGED" >> $GITHUB_OUTPUT
          echo "Changed files: $CHANGED"

      - name: AI Security Review
        if: steps.changed.outputs.files != ''
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode --model anthropic/claude-sonnet-4-5 \
            --agent code-reviewer \
            --print \
            --prompt "審查以下變更檔案的安全性，依照 OWASP Top 10 標準：
          ${{ steps.changed.outputs.files }}
          
          請以 Markdown 格式輸出報告，包含：
          1. 嚴重性分級（Critical/High/Medium/Low）
          2. 問題描述
          3. 修復建議
          4. 受影響的程式碼行號" \
            > review-report.md

      - name: AI Architecture Check
        if: steps.changed.outputs.files != ''
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode --model anthropic/claude-sonnet-4-5 \
            --agent plan \
            --print \
            --prompt "分析此次變更是否符合專案的架構設計原則：
          1. 是否遵循 Clean Architecture 分層
          2. 是否有循環依賴
          3. 是否符合 SOLID 原則
          4. API 介面是否向後相容" \
            >> review-report.md

      - name: Post Review Comment
        if: steps.changed.outputs.files != ''
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('review-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 AI Code Review Report\n\n${report}`
            });

  ai-test-generation:
    runs-on: ubuntu-latest
    needs: ai-code-review
    if: github.event.pull_request.labels.*.name == 'auto-test'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Dependencies
        run: |
          npm install -g opencode-ai@latest
          npm install

      - name: Generate Missing Tests
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode --model anthropic/claude-sonnet-4-5 \
            --agent build \
            --prompt "分析專案中缺少測試覆蓋的模組，為每個模組產生對應的單元測試。
          使用專案現有的測試框架和風格。
          確保新測試可以通過 npm test。"

      - name: Run Tests
        run: npm test

      - name: Commit Generated Tests
        if: success()
        run: |
          git config --local user.email "ai-bot@company.com"
          git config --local user.name "AI Test Bot"
          git add -A
          git diff --staged --quiet || git commit -m "test: AI 自動產生的單元測試"
          git push

# .gitlab-ci.yml
stages:
  - review
  - test
  - deploy

variables:
  OPENCODE_SHARE: "disabled"
  OPENCODE_AUTOUPDATE: "false"

ai-review:
  stage: review
  image: node:20-slim
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - npm install -g opencode-ai@latest
  script:
    - |
      CHANGED_FILES=$(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD)
      opencode --model anthropic/claude-sonnet-4-5 \
        --agent code-reviewer \
        --print \
        --prompt "審查以下變更：$CHANGED_FILES" \
        > review.md
    - cat review.md
  artifacts:
    paths:
      - review.md
    expire_in: 7 days

ai-test-coverage:
  stage: test
  image: node:20-slim
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - npm install -g opencode-ai@latest
    - npm install
  script:
    - npm test -- --coverage --coverageReporters=json-summary
    - |
      COVERAGE=$(cat coverage/coverage-summary.json)
      opencode --model anthropic/claude-haiku-4-5 \
        --print \
        --prompt "分析以下測試覆蓋率報告，找出覆蓋率低於 80% 的模組：
      $COVERAGE
      輸出建議需要補充測試的具體函式。" \
        > coverage-analysis.md
  artifacts:
    paths:
      - coverage-analysis.md
    expire_in: 7 days

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
    }
    
    stages {
        stage('AI Code Review') {
            when {
                changeRequest()
            }
            steps {
                sh 'npm install -g opencode-ai@latest'
                sh '''
                    opencode --model anthropic/claude-sonnet-4-5 \
                        --agent code-reviewer \
                        --print \
                        --prompt "審查此次 PR 的所有變更，重點關注：
                    1. 安全漏洞
                    2. 效能問題
                    3. 程式碼品質
                    4. API 向後相容性" \
                        > ai-review.md
                '''
                archiveArtifacts artifacts: 'ai-review.md'
            }
        }
        
        stage('AI Assisted Fix') {
            when {
                expression { 
                    return currentBuild.previousBuild?.result == 'FAILURE' 
                }
            }
            steps {
                sh '''
                    opencode --model anthropic/claude-sonnet-4-5 \
                        --agent build \
                        --prompt "上一次建置失敗，請分析錯誤日誌並嘗試修復：
                    $(cat previous-build.log | tail -100)"
                '''
            }
        }
    }
    
    post {
        failure {
            sh 'cat build.log | tail -100 > previous-build.log'
        }
    }
}

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  
  "agent": {
    "monorepo-planner": {
      "description": "Monorepo 跨服務架構規劃師",
      "model": "anthropic/claude-opus-4-6",
      "prompt": "你是 Monorepo 架構專家。分析需求對各個 package 的影響，產生跨服務實作計畫。\n\nWorkspace 結構：\n- packages/order-service/\n- packages/payment-service/\n- packages/notification-service/\n- packages/api-gateway/\n- packages/shared-types/\n\n{file:./AGENTS.md}",
      "mode": "primary",
      "tools": {
        "edit": false,
        "bash": false
      }
    },
    "contract-tester": {
      "description": "跨服務契約測試生成器",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是契約測試專家。根據各服務的 API 定義，產生 Pact 契約測試。確保所有服務間的介面相容。",
      "mode": "primary"
    }
  },

  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", 
                  "./packages/order-service",
                  "./packages/payment-service",
                  "./packages/notification-service",
                  "./packages/api-gateway",
                  "./packages/shared-types"]
    }
  }
}

# 步驟 1：使用 Prometheus 分析影響範圍
> 分析「新增訂單退款功能」對所有微服務的影響

# Prometheus 回覆：
# 影響 5 個服務，建議修改順序：
# 1. shared-types（先定義型別）
# 2. payment-service（核心退款邏輯）
# 3. order-service（訂單狀態更新）
# 4. notification-service（退款通知）
# 5. api-gateway（路由設定）

# 步驟 2：OmO 背景代理並行開發
# Sisyphus 自動分派 5 個背景代理

# 步驟 3：Ralph Loop 跨服務驗證
# 自動執行契約測試確認介面相容

# 步驟 4：統一建立 PR（每個服務一個 PR，關聯 Issue）
> 為所有修改建立 PR，關聯 Issue #1234，並在描述中說明跨服務依賴關係

// 使用 OpenCode 自動產生的遷移腳本

// Step 1: OpenCode 分析需求，產生 Schema 變更
// schema.prisma
model Order {
  id          String       @id @default(cuid())
  status      OrderStatus
  totalAmount Decimal      @db.Decimal(10, 2)
  refundedAt  DateTime?    // 新增：退款時間
  refundAmount Decimal?    @db.Decimal(10, 2) // 新增：退款金額
  refundReason String?     // 新增：退款原因
  refundStatus RefundStatus? // 新增：退款狀態
  createdAt   DateTime     @default(now())
  updatedAt   DateTime     @updatedAt

  items       OrderItem[]
  payments    Payment[]
  refunds     Refund[]    // 新增：退款記錄關聯

  @@index([status, createdAt])
  @@index([refundStatus])  // 新增索引
}

// 新增模型
model Refund {
  id            String       @id @default(cuid())
  orderId       String
  order         Order        @relation(fields: [orderId], references: [id])
  amount        Decimal      @db.Decimal(10, 2)
  reason        String
  status        RefundStatus @default(PENDING)
  processedBy   String?
  processedAt   DateTime?
  gatewayRefId  String?      // 金流閘道退款參考號
  createdAt     DateTime     @default(now())
  updatedAt     DateTime     @updatedAt

  @@index([orderId])
  @@index([status])
  @@index([gatewayRefId])
}

enum RefundStatus {
  PENDING
  APPROVED
  PROCESSING
  COMPLETED
  REJECTED
  FAILED
}

# Step 2: OpenCode 自動化遷移流程
> 為退款功能的 Schema 變更建立資料庫遷移

# OpenCode 執行：
npx prisma migrate dev --name add-refund-feature

# Step 3: 產生遷移前後驗證腳本
> 產生遷移驗證腳本，確保：
> 1. 新欄位有正確的預設值
> 2. 索引已建立
> 3. 外鍵約束正確
> 4. 舊資料不受影響

-- migration-verification.sql
-- 驗證 Refund 表已建立
SELECT EXISTS (
  SELECT FROM information_schema.tables 
  WHERE table_name = 'Refund'
) AS refund_table_exists;

-- 驗證新欄位存在
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'Order' 
  AND column_name IN ('refundedAt', 'refundAmount', 'refundReason', 'refundStatus');

-- 驗證索引已建立
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename IN ('Order', 'Refund')
  AND indexname LIKE '%refund%';

-- 驗證外鍵約束
SELECT conname, conrelid::regclass, confrelid::regclass
FROM pg_constraint
WHERE conrelid = 'Refund'::regclass 
  AND contype = 'f';

-- 驗證舊資料完整性
SELECT COUNT(*) AS total_orders, 
       COUNT(CASE WHEN "refundStatus" IS NULL THEN 1 END) AS null_refund_status
FROM "Order";
-- 預期：null_refund_status = total_orders（所有舊訂單的退款狀態為 NULL）

# opencode-metrics.yml
# OpenCode 使用量監控指標

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: 'opencode-server'
    static_configs:
      - targets: ['opencode-server:9090']
    metrics_path: /metrics

# 關鍵指標：
# opencode_requests_total - 總請求數
# opencode_tokens_consumed_total - 總 Token 消耗
# opencode_session_duration_seconds - 工作階段持續時間
# opencode_tool_calls_total - 工具呼叫次數
# opencode_errors_total - 錯誤次數
# opencode_model_latency_seconds - 模型回應延遲

{
  "dashboard": {
    "title": "OpenCode Enterprise Dashboard",
    "panels": [
      {
        "title": "每日 Token 消耗趨勢",
        "type": "timeseries",
        "targets": [{
          "expr": "sum(rate(opencode_tokens_consumed_total[24h])) by (team, model)",
          "legendFormat": "{{team}} - {{model}}"
        }]
      },
      {
        "title": "各團隊使用量",
        "type": "piechart",
        "targets": [{
          "expr": "sum(opencode_requests_total) by (team)",
          "legendFormat": "{{team}}"
        }]
      },
      {
        "title": "模型回應延遲 P95",
        "type": "gauge",
        "targets": [{
          "expr": "histogram_quantile(0.95, sum(rate(opencode_model_latency_seconds_bucket[5m])) by (le, model))",
          "legendFormat": "{{model}}"
        }],
        "fieldConfig": {
          "defaults": {
            "thresholds": {
              "steps": [
                {"color": "green", "value": 0},
                {"color": "yellow", "value": 5},
                {"color": "red", "value": 15}
              ]
            },
            "unit": "s"
          }
        }
      },
      {
        "title": "工具呼叫熱力圖",
        "type": "heatmap",
        "targets": [{
          "expr": "sum(rate(opencode_tool_calls_total[1h])) by (tool_name)",
          "legendFormat": "{{tool_name}}"
        }]
      },
      {
        "title": "錯誤率告警",
        "type": "stat",
        "targets": [{
          "expr": "sum(rate(opencode_errors_total[5m])) / sum(rate(opencode_requests_total[5m])) * 100",
          "legendFormat": "Error Rate %"
        }],
        "fieldConfig": {
          "defaults": {
            "thresholds": {
              "steps": [
                {"color": "green", "value": 0},
                {"color": "yellow", "value": 2},
                {"color": "red", "value": 5}
              ]
            },
            "unit": "percent"
          }
        }
      }
    ]
  }
}

# alerting-rules.yml
groups:
  - name: opencode_alerts
    rules:
      - alert: HighTokenConsumption
        expr: sum(rate(opencode_tokens_consumed_total[1h])) > 1000000
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Token 消耗超過閾值"
          description: "過去 30 分鐘每小時 Token 消耗率超過 100 萬"

      - alert: HighErrorRate
        expr: |
          sum(rate(opencode_errors_total[5m])) 
          / sum(rate(opencode_requests_total[5m])) > 0.05
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "OpenCode 錯誤率超過 5%"
          description: "過去 10 分鐘錯誤率持續超過 5%"

      - alert: ModelLatencyHigh
        expr: |
          histogram_quantile(0.95, 
            sum(rate(opencode_model_latency_seconds_bucket[5m])) by (le)
          ) > 30
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "模型回應延遲 P95 超過 30 秒"

      - alert: ServerDown
        expr: up{job="opencode-server"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "OpenCode Server 不可用"

# main.tf — OpenCode 協助產生的 Kubernetes 叢集設定

terraform {
  required_version = ">= 1.5"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 2.25"
    }
  }
  
  backend "s3" {
    bucket = "company-terraform-state"
    key    = "opencode-infra/terraform.tfstate"
    region = "ap-northeast-1"
  }
}

# OpenCode Server 叢集
resource "aws_eks_cluster" "opencode" {
  name     = "opencode-cluster"
  role_arn = aws_iam_role.eks_role.arn
  version  = "1.29"

  vpc_config {
    subnet_ids         = var.private_subnet_ids
    security_group_ids = [aws_security_group.opencode_sg.id]
  }
}

resource "aws_eks_node_group" "opencode_nodes" {
  cluster_name    = aws_eks_cluster.opencode.name
  node_group_name = "opencode-workers"
  node_role_arn   = aws_iam_role.node_role.arn
  subnet_ids      = var.private_subnet_ids

  scaling_config {
    desired_size = 3
    max_size     = 10
    min_size     = 2
  }

  instance_types = ["m6i.xlarge"]
  
  tags = {
    Environment = "production"
    Service     = "opencode"
    ManagedBy   = "terraform"
  }
}

# Ollama 本地模型服務（GPU 節點）
resource "aws_eks_node_group" "gpu_nodes" {
  cluster_name    = aws_eks_cluster.opencode.name
  node_group_name = "ollama-gpu"
  node_role_arn   = aws_iam_role.node_role.arn
  subnet_ids      = var.private_subnet_ids

  scaling_config {
    desired_size = 2
    max_size     = 5
    min_size     = 1
  }

  instance_types = ["g5.2xlarge"]
  ami_type       = "AL2_x86_64_GPU"

  labels = {
    "nvidia.com/gpu" = "true"
    workload         = "ollama"
  }

  taint {
    key    = "nvidia.com/gpu"
    value  = "true"
    effect = "NO_SCHEDULE"
  }
}

# k8s/opencode-server.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: opencode-server
  namespace: opencode
  labels:
    app: opencode-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: opencode-server
  template:
    metadata:
      labels:
        app: opencode-server
    spec:
      containers:
        - name: opencode
          image: opencode/server:1.2.21
          ports:
            - containerPort: 3000
          env:
            - name: ANTHROPIC_API_KEY
              valueFrom:
                secretKeyRef:
                  name: opencode-secrets
                  key: anthropic-api-key
            - name: OPENCODE_SHARE
              value: "disabled"
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              cpu: "2"
              memory: "4Gi"
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: opencode-server
  namespace: opencode
spec:
  selector:
    app: opencode-server
  ports:
    - port: 3000
      targetPort: 3000
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: opencode-ingress
  namespace: opencode
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - opencode.company.com
      secretName: opencode-tls
  rules:
    - host: opencode.company.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: opencode-server
                port:
                  number: 3000

{
  "$schema": "https://opencode.ai/config.json",
  "logging": {
    "level": "info",
    "format": "json",
    "output": "file",
    "path": "/var/log/opencode/",
    "rotation": {
      "maxSize": "100MB",
      "maxAge": "90d",
      "compress": true
    }
  }
}

{
  "timestamp": "2026-03-08T14:32:15.678Z",
  "level": "info",
  "service": "opencode-server",
  "event": "tool_call",
  "data": {
    "session_id": "sess_abc123",
    "user": "developer@company.com",
    "team": "backend",
    "agent": "build",
    "model": "anthropic/claude-sonnet-4-5",
    "tool": "edit",
    "target_file": "src/services/OrderService.ts",
    "action": "modify",
    "lines_changed": 45,
    "tokens_input": 12500,
    "tokens_output": 3200,
    "latency_ms": 4520,
    "success": true
  }
}

// Kibana 查詢：追蹤特定使用者的所有檔案修改
{
  "query": {
    "bool": {
      "must": [
        { "term": { "data.user": "developer@company.com" }},
        { "term": { "data.tool": "edit" }},
        { "range": { "timestamp": { "gte": "now-7d" }}}
      ]
    }
  },
  "sort": [{ "timestamp": "desc" }],
  "size": 100,
  "_source": ["timestamp", "data.target_file", "data.action", "data.lines_changed"]
}

# monthly-compliance-report.sh
#!/bin/bash

MONTH=$(date -d "last month" +%Y-%m)
REPORT_FILE="compliance-report-${MONTH}.md"

echo "# OpenCode 合規月報 - ${MONTH}" > $REPORT_FILE
echo "" >> $REPORT_FILE

# 使用量統計
echo "## 1. 使用量統計" >> $REPORT_FILE
curl -s "http://elasticsearch:9200/opencode-logs-*/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 0,
    "query": {
      "range": { "timestamp": { "gte": "'${MONTH}'-01", "lt": "'${MONTH}'-01||+1M" }}
    },
    "aggs": {
      "by_team": {
        "terms": { "field": "data.team.keyword" },
        "aggs": {
          "total_tokens": { "sum": { "field": "data.tokens_input" }},
          "unique_users": { "cardinality": { "field": "data.user.keyword" }},
          "total_sessions": { "cardinality": { "field": "data.session_id.keyword" }}
        }
      }
    }
  }' | jq -r '.aggregations.by_team.buckets[] | "| \(.key) | \(.unique_users.value) | \(.total_sessions.value) | \(.total_tokens.value) |"' >> $REPORT_FILE

# 安全事件
echo "" >> $REPORT_FILE
echo "## 2. 安全事件" >> $REPORT_FILE
curl -s "http://elasticsearch:9200/opencode-logs-*/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 0,
    "query": {
      "bool": {
        "must": [
          { "range": { "timestamp": { "gte": "'${MONTH}'-01", "lt": "'${MONTH}'-01||+1M" }}},
          { "terms": { "data.tool": ["bash", "admin"] }},
          { "term": { "data.success": false }}
        ]
      }
    },
    "aggs": {
      "by_event": { "terms": { "field": "data.tool.keyword" }}
    }
  }' >> $REPORT_FILE

echo "報告已產生：${REPORT_FILE}"

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": ["claude-sonnet-4-5", "claude-haiku-4-5"],
      "priority": 1
    },
    "openai": {
      "models": ["gpt-5"],
      "priority": 2
    },
    "ollama": {
      "models": ["qwen3-coder:14b"],
      "baseURL": "http://ollama-cluster.internal:11434",
      "priority": 3
    }
  },
  "fallback": {
    "enabled": true,
    "strategy": "priority",
    "retryCount": 2,
    "retryDelay": 5000
  }
}

# 檢查安裝路徑是否在 PATH 中
echo $PATH

# 常見解決方式
# Bash
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Fish
fish_add_path ~/.opencode/bin

# 確認 Node.js 版本
node --version  # 需要 18.x+

# 確認 npm 權限
# 使用管理員權限執行 PowerShell
npm install -g opencode-ai@latest

# 或使用 Scoop（不需要管理員權限）
scoop install opencode

# 清除 npm 快取
npm cache clean --force

# 重新安裝
npm install -g opencode-ai@latest

# 驗證 API Key
opencode config check

# 重新設定
/connect
# 選擇供應商重新輸入 API Key

# 設定 Proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# 排除本地服務
export NO_PROXY="localhost,127.0.0.1"

# 降低請求頻率
# 在 opencode.json 中設定
{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000
      }
    }
  }
}

# 在 .opencode/rules/ 中加入
## 防幻覺規則
- 使用外部 API 前必須先查詢 Context7 或 websearch 確認
- 不確定的 API 呼叫必須標記 [需確認]

# 檢查當前權限設定
# 可能原因：
# 1. 使用 Plan Agent（edit 預設 deny）→ 切換到 Build Agent
# 2. 檔案在 .gitignore 中 → 確認 OpenCode 的檔案存取範圍
# 3. 權限設定為 deny → 修改 opencode.json 中的 permission

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": "allow"
  }
}

# 確認 OpenCode CLI 已安裝
opencode --version

# 確認 Server 可以啟動
opencode serve --port 3000

# 檢查 VS Code Extension 設定
# Settings → OpenCode → Server URL

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 120000
      }
    }
  }
}

# 確認 Bun 版本
bun --version  # 需要 1.3.9+

# 確認 OmO 安裝
bun pm ls -g | grep oh-my-openagent

# 重新安裝
bun install -g oh-my-openagent@latest

# 可能原因：檔案被外部修改
# 解決方案：重新讀取檔案讓 OmO 重新計算 hash
> 請重新讀取 src/services/UserService.ts 的內容

# 減少並行代理數
# 在 omo config 中設定
background_agents:
  max_concurrent: 3  # 降低並行數

# macOS：檢查安全設定
# System Preferences → Security & Privacy → Allow openwork

# Windows：檢查防火牆
# 允許 OpenWork 通過防火牆

# Linux：AppImage 權限
chmod +x openwork-linux-x86_64.AppImage

# 確認 Router 服務正在執行
curl http://localhost:3001/health

# 確認 Webhook URL 正確設定
# 確認 Bot Token 有效

# 清除快取
opkg cache clean

# 使用指定 Registry
opkg install --registry https://opkg.openwork.software @openwork/skill-name

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

  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",

  "autoupdate": false,
  "share": "disabled",

  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    },
    "webfetch": "allow",
    "websearch": "allow",
    "external_directory": "deny",
    "lsp": "allow"
  },

  "agent": {
    "plan": {
      "model": "anthropic/claude-opus-4-6",
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-5",
      "steps": 200,
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "code-reviewer": {
      "description": "安全導向的 Code Reviewer",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一位安全專家。請依照 OWASP Top 10 和公司安全規範審查程式碼。{file:./.opencode/rules/security.md}",
      "mode": "primary",
      "temperature": 0.2,
      "tools": {
        "bash": false,
        "edit": false,
        "write": false
      },
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  },

  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "sonarqube": {
      "type": "local",
      "command": ["npx", "-y", "@sonarsource/sonarqube-mcp-server"],
      "environment": {
        "SONARQUBE_URL": "{env:SONARQUBE_URL}",
        "SONARQUBE_TOKEN": "{env:SONARQUBE_TOKEN}"
      }
    }
  },

  "plugin": ["oh-my-openagent"]
}

# AGENTS.md — 企業標準 AI 代理設定

## 專案概述
本專案為企業級電商平台後端服務。
- 語言：TypeScript
- Runtime：Node.js 20 LTS
- Framework：NestJS 10.x
- ORM：Prisma 5.x
- Database：PostgreSQL 16
- Cache：Redis 7
- Queue：BullMQ
- 測試：Jest + Supertest

## 架構原則
1. 遵循 Clean Architecture（Controller → Service → Repository）
2. 所有 Service 透過介面注入（DI）
3. 每個模組獨立一個資料夾
4. API 遵循 RESTful 規範 + OpenAPI 3.0
5. 所有公開 API 必須有 DTO 驗證（class-validator）

## 程式碼風格
- 使用 ESLint + Prettier（設定在 .eslintrc.js）
- 變數命名：camelCase
- 類別命名：PascalCase
- 檔案命名：kebab-case
- 每個函式不超過 30 行
- 每個檔案不超過 300 行

## 安全規範
- 所有使用者輸入必須驗證和消毒
- SQL 查詢只能透過 Prisma ORM
- 禁止直接使用 eval()、Function()、child_process
- API 認證使用 JWT + Refresh Token
- 敏感資料必須加密儲存
- 密碼使用 bcrypt（cost factor >= 12）

## 測試規範
- 每個 Service 必須有對應的 .spec.ts
- 測試覆蓋率目標 >= 80%
- 使用 describe/it 結構
- Mock 外部依賴
- E2E 測試使用 Supertest

## Git 規範
- Commit Message 格式：`type(scope): description`
- type: feat, fix, docs, style, refactor, test, chore
- 每個 commit 只做一件事
- PR 描述必須包含：變更原因、影響範圍、測試方式

## 禁止事項
- 不要修改 prisma/migrations/ 下的已有遷移檔案
- 不要直接修改 package-lock.json
- 不要在程式碼中硬編碼 API Key 或密碼
- 不要使用 any 型別（除非有充分理由並加註釋）
- 不要繞過 ESLint 規則（no eslint-disable）

# 安全規則

## 輸入驗證
- 所有外部輸入必須使用 class-validator 驗證
- 使用 ValidationPipe 的 whitelist: true 和 forbidNonWhitelisted: true
- 檔案上傳必須檢查：型別、大小、內容（不只副檔名）

## 認證與授權
- API 使用 JWT Bearer Token 認證
- Refresh Token 存放在 httpOnly cookie
- 實作 Role-Based Access Control (RBAC)
- 管理員操作必須記錄稽核日誌

## 資料保護
- PII（個人識別資訊）在日誌中必須遮罩
- 密碼使用 bcrypt 雜湊（salt rounds >= 12）
- 敏感設定使用環境變數，不寫入程式碼
- 資料庫連線使用 SSL

## API 安全
- 實作 Rate Limiting（預設 100 req/min）
- 啟用 CORS 並限制允許的來源
- 使用 Helmet 中介軟體
- 禁用不必要的 HTTP 方法

# 程式碼風格規則

## 命名規範
- 變數/函式：camelCase
- 類別/介面/型別：PascalCase
- 常數：UPPER_SNAKE_CASE
- 檔案：kebab-case.ts
- 測試檔案：kebab-case.spec.ts

## 函式設計
- 單一職責：每個函式只做一件事
- 參數不超過 3 個（超過使用物件）
- 使用 early return 減少巢狀
- 避免副作用

## 型別使用
- 優先使用 interface 而非 type（除非需要 union/intersection）
- 禁止使用 any（使用 unknown 替代）
- 使用 Enum 替代魔術數字/字串
- DTO 和 Entity 必須有完整的型別定義

## 錯誤處理
- 使用 NestJS 內建的 Exception Filters
- 自訂例外繼承 HttpException
- 業務邏輯錯誤使用自訂 BusinessException
- 所有 catch 區塊必須記錄日誌

# API 設計規則

## RESTful 規範
- GET：查詢（不修改資料）
- POST：建立
- PUT：完整更新
- PATCH：部分更新
- DELETE：刪除

## URL 設計
- 使用複數名詞：/users, /orders
- 巢狀資源最多兩層：/users/:id/orders
- 查詢參數用於過濾、排序、分頁
- 避免 URL 中出現動詞

## 回應格式
- 成功：{ data: T, meta?: { page, limit, total } }
- 錯誤：{ error: { code, message, details? } }
- HTTP 狀態碼：200, 201, 204, 400, 401, 403, 404, 409, 422, 500

## 分頁
- 查詢參數：?page=1&limit=20
- 預設 limit: 20, 最大 limit: 100
- 回應包含 meta：{ page, limit, total, totalPages }

## 版本控制
- URL 路徑版本：/api/v1/users
- 主要版本變更才升版
- 舊版 API 維護至少 6 個月

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "DATABASE_URL": "{env:DATABASE_URL}"
      }
    },
    "sonarqube": {
      "type": "local",
      "command": ["npx", "-y", "@sonarsource/sonarqube-mcp-server"],
      "environment": {
        "SONARQUBE_URL": "{env:SONARQUBE_URL}",
        "SONARQUBE_TOKEN": "{env:SONARQUBE_TOKEN}"
      }
    },
    "brave-search": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "environment": {
        "BRAVE_API_KEY": "{env:BRAVE_API_KEY}"
      }
    },
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/sse",
      "environment": {
        "SENTRY_AUTH_TOKEN": "{env:SENTRY_AUTH_TOKEN}"
      }
    },
    "internal-docs": {
      "type": "remote",
      "url": "https://mcp-docs.internal.company.com/mcp",
      "environment": {
        "AUTH_TOKEN": "{env:INTERNAL_DOCS_TOKEN}"
      }
    }
  }
}

// custom-mcp-server.ts
// 自建企業內部 MCP 伺服器 — 查詢公司知識庫

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "company-knowledge-base",
  version: "1.0.0",
});

// 工具：搜尋公司知識庫
server.tool(
  "search_knowledge",
  "搜尋公司內部知識庫文件",
  {
    query: z.string().describe("搜尋關鍵字"),
    category: z
      .enum(["api-docs", "architecture", "runbook", "policy"])
      .optional()
      .describe("文件類別"),
    limit: z.number().default(10).describe("回傳筆數上限"),
  },
  async ({ query, category, limit }) => {
    // 呼叫內部 Elasticsearch
    const results = await searchInternalDocs(query, category, limit);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }
);

// 工具：查詢 API 文件
server.tool(
  "get_api_spec",
  "取得指定服務的 OpenAPI 規格",
  {
    serviceName: z.string().describe("服務名稱"),
    version: z.string().optional().describe("API 版本"),
  },
  async ({ serviceName, version }) => {
    const spec = await fetchApiSpec(serviceName, version || "latest");
    return {
      content: [{ type: "text", text: JSON.stringify(spec, null, 2) }],
    };
  }
);

// 工具：查詢服務健康狀態
server.tool(
  "check_service_health",
  "檢查指定微服務的健康狀態",
  {
    serviceName: z.string().describe("服務名稱"),
    environment: z
      .enum(["dev", "staging", "production"])
      .describe("環境"),
  },
  async ({ serviceName, environment }) => {
    const health = await checkHealth(serviceName, environment);
    return {
      content: [{ type: "text", text: JSON.stringify(health, null, 2) }],
    };
  }
);

// 啟動伺服器
const transport = new StdioServerTransport();
await server.connect(transport);