OpenCode Hooks 指南：安全配置前先做 7 个检查

Hook 适合在固定生命周期点重复执行同一个检查。如果只是复用建议，用 skill；如果是用户主动触发的任务，用 command；如果要接外部服务，用 MCP；如果要限制工具，先用权限配置。只有当行为依赖“执行前/执行后/文件变化后”这样的时机时，hooks 才是正确形态。好的 hook 很小且可观察，例如检查 bash 命令是否触碰受保护路径、编辑大文件前提醒、工具结束后写轻量日志。差的 hook 会隐藏部署、提交、密钥处理或静默改文件。

官方文档把插件描述为返回 hooks object 的 JavaScript/TypeScript 模块。项目规则优先放在 `.opencode/plugins/`，这样团队能审查；个人工作流偏好可以放在全局配置目录；npm 插件只适合有源码、版本和维护记录的通用 hook。团队仓库里，hook 行为应写在配置旁边，说明用途、触发事件和禁用方法。

最重要的决定不是代码，而是事件。官方工具文档提到 `tool.execute.before`、`tool.execute.after` 等 hook 场景，并说明处理 apply_patch 时应检查 `input.tool === "apply_patch"`。写 hook 前先用一句话描述事件：例如“bash 执行前处理命令参数”或“apply_patch 后检查是否改了生成目录”。如果一句话放不下，就拆成多个窄 hook。

安全 hook 只做一个可解释的小改变。可以在工具执行前调整参数、在验证后提醒测试、在触碰敏感目录时提示人工确认。危险 hook 通常隐藏所有权：自动 commit/push、把代码发到远程服务、改写大段 patch、处理密钥或无提示运行部署。这些事情可能需要自动化，但应该放进显式 command、CI workflow、MCP 或可审查应用代码。

把 hook 当作自动化变更来验收。准备一个很小的仓库：一个源码文件、一个生成目录、一个无害命令。触发 hook，检查输出、diff、失败提示和禁用路径。回滚方式必须明确：移走插件文件、删除 `plugin` 配置项或卸载固定版本包。如果禁用方式不清楚，就不要放进真实项目。

OpenCode 行为异常时，按层禁用：项目 hook、npm 插件、全局插件、项目 skill、command 包装、MCP、provider/model 设置。每次用同一个小任务复测。这样可以判断问题来自生命周期代码、提示词、外部工具还是模型行为。记录事件名、输入条件、期望输出和测试命令，升级 OpenCode 后排错会快很多。

OpenCode 的 GitHub workflow 与本地 hooks 是两类东西。Actions 中的 GitHub 事件可以创建分支或 PR；本地 hooks 应服务开发时护栏。不要把 hook 做成隐藏部署系统。CI 需要显式 workflow，构建产物要明确 stage，缓存和 pyc 要忽略，无改动时跳过 commit。Hook 只负责本地窄护栏。