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+ 個	大型重構	需要更詳細的追蹤

驗證流程

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

# 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 範例:

{
  "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 範例:

{
  "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

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 運作

# 測試 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 - 專案開發規範
• ARCHITECTURE_EVALUATION.md - 架構優化評估
• PENDING_ISSUES.md - 待解決問題追蹤
• INSTALL_N8N.md - n8n 安裝指南