Nb MCP Server

🚀 用於質量保證的Opencode插件

本目錄包含從Claude Code鉤子移植而來的Opencode插件，這些插件可提供質量保證和開發工作流程強制實施功能。

✨ 主要特性

✅ 1. post-edit-linter.js（可用）

• 用途：在文件更新後運行代碼檢查工具。
• 觸發事件：tool.execute.after（針對edit工具）。
• 行為：
  • 檢查hatch命令是否可用。
  • 檢查develop Hatch環境是否存在。
  • 運行hatch --env develop run linters。
  • 如果代碼檢查工具運行失敗，將拋出帶有截斷輸出（最多50行）的錯誤。
  • 如果條件不滿足（如hatch不可用），則提前退出。
  • 注意：使用tool.execute.after而非file.edited（大語言模型發起的編輯不會觸發file.edited）。

⚠️ 2. git-commit-guard.js-disabled（禁用 - Opencode bash工具限制）

• 用途：當代碼檢查工具或測試失敗時，阻止git提交。
• 狀態：禁用 - Opencode的bash工具不會在input.args.command中傳遞命令。
• 問題：插件攔截tool.execute.before，但bash工具的input.args為空。
• 原始意圖：移植自Claude Code鉤子pre-bash-git-commit-check。

⚠️ 3. python-environment-guard.js-disabled（禁用 - Opencode bash工具限制）

• 用途：檢測Bash命令中不當的Python使用。
• 狀態：禁用 - Opencode的bash工具不會在input.args.command中傳遞命令。
• 問題：插件攔截tool.execute.before，但bash工具的input.args為空。
• 原始意圖：移植自Claude Code鉤子pre-bash-python-check。

📦 安裝指南

當將此模板複製到下游項目時：

1. 導航到插件目錄：

cd .auxiliary/configuration/coders/opencode/plugin

2. 安裝依賴項：

npm install

3. 確保符號鏈接存在：

# 從項目根目錄執行
ln -sf .auxiliary/configuration/coders/opencode .opencode

4. 驗證插件加載： Opencode應自動從.opencode/plugin/加載插件。

🔧 技術細節

依賴項

• shlex：用於解析shell命令（移植自Python的shlex模塊） - 在禁用的插件中使用。
• bun：運行時環境（由Opencode提供）。

移植說明

這些插件是從Claude Code鉤子移植而來，移植效果各異：

關鍵發現

• Opencode的bash工具限制：在測試過程中，我們發現Opencode的bash工具不會在input.args.command（或任何input.args字段）中傳遞命令字符串。當調用bash工具時，input.args對象為空{}，這使得插件無法攔截和分析bash命令。
• 可行解決方案：只有post-edit-linter.js可用，因為它針對edit工具使用tool.execute.after，此時文件信息可在output.metadata.filediff.file中獲取。

錯誤消息

所有錯誤消息與原始Claude Code鉤子完全一致，包括：

• 代碼檢查工具輸出截斷為50行。
• 阻止git提交時的“神聖警告”。
• Python使用的警告消息。

💻 使用示例

測試插件

1. 文件編輯測試：編輯一個Python文件並驗證代碼檢查工具是否運行。
2. Git提交測試：嘗試運行git commit -m "test"並驗證檢查是否運行。
3. Python使用測試：嘗試運行python -c "print('test')"並驗證是否顯示警告。

📚 詳細文檔

故障排除

插件未加載

• 驗證.opencode符號鏈接是否指向.auxiliary/configuration/coders/opencode。
• 檢查Opencode版本是否支持插件API。
• 確保已安裝依賴項（npm install）。

命令未找到錯誤

• 驗證hatch是否已安裝並在系統路徑中。
• 檢查develop Hatch環境是否存在：hatch env show。

超時問題

• 超時時間與Python鉤子一致（60秒、120秒、300秒）。
• 由於Bun shell缺乏原生超時功能，使用Promise.race和setTimeout實現超時。

源代碼

原始Claude Code鉤子位於template/.auxiliary/configuration/coders/claude/scripts/目錄下：

• post-edit-linter
• pre-bash-git-commit-check
• pre-bash-python-check