momentry_core/docs/OPENCODE_GUIDE.md

# OpenCode 使用規範

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-21 |
| 文件版本 | V1.1 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-21 | 創建文件 | Warren |
| V1.1 | 2026-03-21 | 新增 MCP 設定章節 | OpenCode |

---

## 概述

本文檔定義使用 OpenCode 進行專案開發的最佳實踐，確保開發效率和程式碼品質。

---

## 任務管理

### 任務批次策略

**原則**: 一次處理 1-2 個功能，完成後驗證，再繼續下一個。

| 批次大小 | 適用場景 | 說明 |
|----------|----------|------|
| 1 個 | 緊急修復、簡單任務 | 快速完成 |
| 2-3 個 | 一般功能開發 | 平衡效率與品質 |
| 3+ 個 | 大型重構 | 需要更詳細的追蹤 |

### 驗證流程

每個任務完成後必須執行：

```bash
# 1. 編譯檢查
cargo check

# 2. Lint 檢查
cargo clippy --lib

# 3. 單元測試
cargo test --lib

# 4. 格式化檢查
cargo fmt -- --check
```

---

## 溝通模式

### 有效的任務描述

**建議格式**:
```
執行 [功能名稱]
- 優先級: 高/中/低
- 驗收標準: [明確的標準]
- 約束: [限制條件]
```

**範例**:
```
實作 monitor_jobs 表
- 優先級: 高
- 驗收標準: CRUD 操作可用，單元測試通過
- 約束: 使用現有架構
```

### 明確的暫停點

在每個階段完成後主動詢問：

```
[任務] 完成。要繼續：
1. 實作功能 A
2. 添加測試
3. 更新文檔
```

### 不建議的溝通

| 模式 | 問題 | 建議 |
|------|------|------|
| 一次指定太多項目 | 增加複雜度，難以追蹤 | 分批處理 |
| 模糊的任務描述 | 難以評估進度 | 使用明確的驗收標準 |
| 從不驗證 | 累積問題 | 每步驟完成後驗證 |

---

## 決策點

### 常見決策點

| 階段 | 問題 | 選項 |
|------|------|------|
| 開始 | 如何開始？ | 先了解現況 / 直接實作 |
| 實作 | 實作方式？ | 保持現有架構 / 重構 |
| 驗證 | 通過了嗎？ | 繼續 / 修復問題 |
| 完成 | 還有什麼？ | 下一個任務 / 結束 |

### 決策準則

1. **安全優先**: 破壞性變更需要明確確認
2. **驗證後繼續**: 每步驟完成後驗證
3. **文檔同步**: 變更後更新文檔

---

## 文檔使用

### 必讀文檔

| 文檔 | 用途 | 查閱時機 |
|------|------|----------|
| `AGENTS.md` | 專案規範 | 每次對話開始 |
| `docs/*.md` | 技術規格 | 功能實作前 |

### 文檔更新時機

| 變更類型 | 需要更新 |
|----------|----------|
| 新功能 | `AGENTS.md` + 相關技術文檔 |
| 架構變更 | `ARCHITECTURE_EVALUATION.md` |
| 問題修復 | `PENDING_ISSUES.md` |
| 環境變更 | `INSTALL_*.md` |

---

## 審查清單

### 實作完成後檢查

- [ ] `cargo clippy --lib` 通過
- [ ] `cargo test --lib` 通過
- [ ] `cargo fmt -- --check` 通過
- [ ] 文檔已更新
- [ ] 新功能有單元測試
- [ ] Pre-commit hook 通過

### 對話結束前

- [ ] 所有變更已驗證
- [ ] 文檔已同步
- [ ] 下一步計劃明確

---

## 範例流程

### 範例 1: 實作新功能

```
用戶: 實作使用者認證功能

OpenCode:
1. 分析現有架構
2. 創建任務清單
3. 實作核心功能
4. 添加單元測試
5. 更新文檔
6. 驗證通過

用戶: 完成，繼續下一個
```

### 範例 2: 修復問題

```
用戶: 修復登入超時問題

OpenCode:
1. 重現問題
2. 分析根因
3. 實作修復
4. 驗證修復
5. 添加測試防止回歸

用戶: 確認修復完成
```

---

## 常見問題

### Q: 如何避免一次處理太多？

**A**: 使用 `/todo` 追蹤任務，分批處理。

### Q: 如何確保文檔同步？

**A**: 每個任務完成後檢查是否需要更新文檔。

### Q: 何時應該結束對話？

**A**: 當主要任務完成，且沒有緊急的後續步驟時。

---

## MCP 設定

### 設定檔案

OpenCode MCP 設定位於 `~/.config/opencode/opencode.json`

### 已啟用的 MCP Servers

| Server | 用途 | 命令 |
|--------|------|------|
| gitea | Gitea API 操作 | `/opt/homebrew/bin/gitea-mcp-server` |
| n8n | n8n Workflow 操作 | `/opt/homebrew/bin/mcp-n8n` |
| postgres | PostgreSQL 資料庫查詢 | `/opt/homebrew/bin/mcp-server-postgres` |
| redis | Redis 快取操作 | `/opt/homebrew/bin/mcp-server-redis` |
| qdrant | Qdrant 向量搜尋 | `/opt/homebrew/bin/mcp-server-qdrant` |
| filesystem | 檔案系統操作 | `/opt/homebrew/bin/mcp-server-filesystem` |

### MCP 設定格式

**Schema 參考**: `https://opencode.ai/config.json`

**必要欄位**:
| 欄位 | 類型 | 說明 |
|------|------|------|
| `type` | string | `"local"` 或 `"remote"` |
| `command` | array | 命令和參數（local 必要） |
| `url` | string | 遠端 URL（remote 必要） |

**可選欄位**:
| 欄位 | 類型 | 說明 |
|------|------|------|
| `environment` | object | 環境變數（local only） |
| `enabled` | boolean | 是否啟用 |
| `timeout` | number | 請求超時（毫秒） |
| `headers` | object | 請求頭（remote only） |

**Local MCP 範例**:
```json
{
  "mcp": {
    "gitea": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/gitea-mcp-server",
        "-token", "<GITEA_TOKEN>",
        "-host", "http://localhost:3000"
      ]
    },
    "n8n": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-n8n"],
      "environment": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "<N8N_API_KEY>"
      }
    },
    "postgres": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-server-postgres"],
      "environment": {
        "DATABASE_URL": "postgresql://accusys:accusys@localhost:5432/momentry"
      }
    },
    "redis": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-server-redis"],
      "environment": {
        "REDIS_URL": "redis://:accusys@localhost:6379"
      }
    },
    "qdrant": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-server-qdrant"],
      "environment": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": ""
      }
    },
    "filesystem": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-server-filesystem"],
      "args": ["/Users/accusys/momentry"]
    }
  }
}
```

**Remote MCP 範例**:
```json
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
```

### n8n MCP 工具 (43 個)

#### Workflows (10)
| 工具 | 說明 |
|------|------|
| `n8n_list_workflows` | 列出所有 workflows |
| `n8n_get_workflow` | 取得 workflow 詳情 |
| `n8n_create_workflow` | 建立新 workflow |
| `n8n_update_workflow` | 更新 workflow |
| `n8n_delete_workflow` | 刪除 workflow |
| `n8n_activate_workflow` | 啟用 workflow |
| `n8n_deactivate_workflow` | 停用 workflow |
| `n8n_execute_workflow` | 執行 workflow |
| `n8n_get_workflow_tags` | 取得 workflow 標籤 |
| `n8n_update_workflow_tags` | 更新 workflow 標籤 |

#### Executions (3)
| 工具 | 說明 |
|------|------|
| `n8n_list_executions` | 列出執行記錄 |
| `n8n_get_execution` | 取得執行詳情 |
| `n8n_delete_execution` | 刪除執行記錄 |

#### Data Tables (8)
| 工具 | 說明 |
|------|------|
| `n8n_list_datatables` | 列出資料表 |
| `n8n_create_datatable` | 建立資料表 |
| `n8n_get_datatable` | 取得資料表結構 |
| `n8n_get_datatable_rows` | 取得資料表列 |
| `n8n_insert_datatable_rows` | 插入資料列 |
| `n8n_update_datatable_rows` | 更新資料列 |
| `n8n_upsert_datatable_row` | 插入或更新資料列 |
| `n8n_delete_datatable_rows` | 刪除資料列 |

#### Tags (5)
| 工具 | 說明 |
|------|------|
| `n8n_list_tags` | 列出所有標籤 |
| `n8n_get_tag` | 取得標籤 |
| `n8n_create_tag` | 建立標籤 |
| `n8n_update_tag` | 更新標籤 |
| `n8n_delete_tag` | 刪除標籤 |

#### Credentials (4)
| 工具 | 說明 |
|------|------|
| `n8n_list_credentials` | 列出憑證 |
| `n8n_create_credential` | 建立憑證 |
| `n8n_delete_credential` | 刪除憑證 |
| `n8n_get_credential_schema` | 取得憑證 schema |

#### Users (3)
| 工具 | 說明 |
|------|------|
| `n8n_list_users` | 列出使用者 |
| `n8n_get_user` | 取得使用者 |
| `n8n_delete_user` | 刪除使用者 |

#### Variables (3)
| 工具 | 說明 |
|------|------|
| `n8n_list_variables` | 列出變數 |
| `n8n_create_variable` | 建立變數 |
| `n8n_delete_variable` | 刪除變數 |

#### 其他 (7)
| 工具 | 說明 |
|------|------|
| `n8n_list_projects` | 列出專案 |
| `n8n_create_project` | 建立專案 |
| `n8n_update_project` | 更新專案 |
| `n8n_delete_project` | 刪除專案 |
| `n8n_generate_audit` | 產生安全審計報告 |
| `n8n_health_check` | 健康檢查 |
| `n8n_trigger_webhook` | 觸發 webhook |

### 安裝 n8n MCP

```bash
npm install -g @nextoolsolutions/mcp-n8n
```

### n8n API Key 設定

1. 開啟 n8n UI (http://localhost:5678)
2. 前往 Settings → API
3. 建立 API Key
4. 將 API Key 加入 `opencode.json` 的 `N8N_API_KEY`

### 驗證 MCP 運作

```bash
# 測試 MCP server
N8N_BASE_URL=https://n8n.momentry.ddns.net \
N8N_API_KEY="your-key" \
mcp-n8n

# 測試工具列表
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | \
N8N_BASE_URL=https://n8n.momentry.ddns.net \
N8N_API_KEY="your-key" \
mcp-n8n
```

---

## 相關文件

- [AGENTS.md](../AGENTS.md) - 專案開發規範
- [ARCHITECTURE_EVALUATION.md](./ARCHITECTURE_EVALUATION.md) - 架構優化評估
- [PENDING_ISSUES.md](./PENDING_ISSUES.md) - 待解決問題追蹤
- [INSTALL_N8N.md](./INSTALL_N8N.md) - n8n 安裝指南