@oldsuns/opencode-branch-session

OpenCode 的无状态分支守门员。在受保护分支上拦截写文件与危险 git 命令； git merge 由用户驱动的 /finish-branch 收尾命令触发。

简体中文 · English

📖 完整文档： github.com/OldSuns/opencode-branch-session

功能

受保护分支（默认 main / master）上：

• 拒绝 Edit / Write / MultiEdit / Patch / NotebookEdit 工具。
• git 子命令仅允许只读 allowlist（status / log / diff 等）以及 git checkout -b <name> / git switch -c <name>（用于切到工作分支）。

任意分支上：

• 拒绝危险 git 子命令（push / pull / fetch / reset --hard / rebase / cherry-pick / filter-branch / reflog expire/delete / gc / remote add/remove/rename/set-url / clean -fd/fdx）。
• git merge 通过用户输入 /finish-branch 驱动（可选 /finish-branch commit 允许自动提交）。该命令注入一段完整收尾剧本：可选提交、领先检查、合并、可选删除分支。

plugin 完全无状态，每次拦截判定都基于 git 现状。无 plan 文件、无 session、 无持久化。

安装

npm install @oldsuns/opencode-branch-session

在 opencode.json 注册：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["@oldsuns/opencode-branch-session", {
      "protectedBranches": ["main", "master"]
    }]
  ]
}

配置

| 字段 | 类型 | 默认值 | 含义 | |---|---|---|---| | protectedBranches | string[] | ["main", "master"] | 受保护分支模式列表。支持 * 通配（如 release/*）。匹配则视为受保护。 | | blockedGitCommands | string[] | （见源码） | 任意分支共享的 git 禁用列表。支持 * 通配。 | | allowedGitCommands | string[] | [] | 在受保护分支上额外放行的 git 子命令（在内置只读 allowlist 之外）。 |

工具

| 工具 | 用途 | | --- | --- | | branchstatus | 只读诊断：显示当前分支、默认分支、工作区状态、是否受保护。 |

Slash command

| 命令 | 用途 | | --- | --- | | /finish-branch | 驱动分支收尾：可选提交（/finish-branch commit）、领先检查、合并到默认分支、可选删除分支。该流程内的 git merge 凭一次性 token 放行，merge 执行后立即清零，下一次需重新运行 /finish-branch。 |

构建（贡献者）

npm install
npm run build           # 生成 dist/
npx tsc --noEmit        # 仅类型检查

完整的架构、hook 细节与已知限制请见 GitHub 上的完整 README。