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钩子移植而来，移植效果各异： | Claude Code钩子 | Opencode插件 | 状态 | 主要更改 | |-----------------|----------------|--------|-------------| | post-edit-linter | post-edit-linter.js | ✅ 可用 | 从Python转换为JavaScript，subprocess 替换为Bun shell API，使用tool.execute.after而非file.edited | | pre-bash-git-commit-check | git-commit-guard.js-disabled | ⚠️ 禁用 | 工具名称：Bash 改为 bash，使用npm shlex 包。问题：Opencode bash工具不会在input.args.command中传递命令 | | pre-bash-python-check | python-environment-guard.js-disabled | ⚠️ 禁用 | 使用shlex进行相同的解析逻辑，错误消息完全一致。问题：Opencode bash工具不会在input.args.command中传递命令 |

关键发现

• 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