bkd-dotcom/umbra-plugins

# umbra-plugins **通过签名回执，在编辑器和 CI 中管理 coding-agent 的变更。** [umbra-core](https://github.com/bkd-dotcom/umbra-core) 的编辑器与 agent 集成： Umbra 决定 agent 的变更获得了多少权限并进行证明。这些插件将该治理机制*引入到 agent 工作的工具中* —— 由 确定性代码强制执行，而非由模型本身执行（agent 无法批准其自身的变更）。 ## Claude Code 插件（最深度的集成） 一个 **`PreToolUse` hook** 会在每次执行 `Edit`/`Write`/`Bash` 之前运行，并使用 `umbra guard` （确定性，而非模型）**阻止**范围外或被禁止的操作发生。打包了 Umbra **MCP server** 和 一个 **`/umbra:admit`** 技能，用于按需进行完全准入并附带签名回执。 ``` /plugin marketplace add bkd-dotcom/umbra-plugins /plugin install umbra@umbra-plugins ``` 或者进行本地测试：`claude --plugin-dir ./claude-code/umbra` 它的作用： - Agent 尝试编辑 `deploy.yml` / `.env` / 密钥，或运行 `curl … | bash` / `git push` → **被阻止**，并说明原因（在发生之前）。 - Agent 编辑范围内的文件 → 静默允许。 - `/umbra:admit` → 按需提供完整的流水线 + 获得的权限 + 签名回执。 ### Guard 如何工作 ``` Claude Code is about to Edit/Write/run Bash │ ▼ PreToolUse hook ──► hooks/umbra-guard.sh │ │ (passes the tool JSON on stdin) │ ▼ │ umbra guard ── loads .umbra/admission.yaml, │ (umbra-core) checks the path/command deterministically │ │ ▼ ▼ deny? ◄──── permissionDecision: "deny" + reason (forbidden / out-of-scope / dangerous) allow? ◄─── {} (silent → normal permission flow continues) ``` - 该决定由 **`umbra guard` (umbra-core) 做出，而不是模型** —— 因此 agent 无法批准其自身范围外的变更。这就是核心要点：agent 无法 自我管理。 - 在**第一次**工具调用时，一个 `SessionStart` hook 会使用 Python ≥3.11 将 `umbra-core` 配置到一个 插件本地的 venv 中（它会跳过较旧的默认 `python3`）。准备就绪后它会打印出 **`Umbra active: …`**，如果无法运行（例如：没有 Python 3.11+ / 离线），它会打印出醒目的 **`INACTIVE — NOT enforcing`** （未激活 —— 未在执行）行 —— 因此“已安装”永远不会被 误解为“已保护”。 - 如果 umbra-core 确实无法运行，它会**直接放行**（从不阻止），因此它不会 中断 session；`INACTIVE` 通知会告知你何时会发生 这种情况。 ### 无需交互式 session 即可查看 审查者（以及你）可以通过一条命令来验证强制执行情况 —— 它会针对一个临时仓库， 使用 Claude Code 发送的完全相同的工具 JSON 来驱动真实的 hook： ``` bash demos/try-guard.sh ``` 预期输出：`deploy.yml`、`curl | bash`、`cat .env` 以及 `.pem` 写入操作会因特定原因被 **BLOCKED** (阻止)；而范围内的 `src/app.js` 编辑则会被 **ALLOWED** (允许)。需要 `bash`、`git` 以及 Python ≥3.11（hook 会自动配置 umbra-core）。 ## Cursor MCP server + 一条项目规则。请参阅 [`cursor/`](cursor/)。Cursor 没有确定性的 预写入 hook，因此那里强制执行的关卡是 PR 上的 CI 检查；而 MCP 工具 + 规则允许 agent 在编辑器内进行自我检查。 ## Codex MCP server (`~/.codex/config.toml`) + 一个生命周期 hook guard。请参阅 [`codex/`](codex/)。 ## 通用 guard（任何编辑器 / CI / pre-commit） [`universal/umbra-guard.sh`](universal/umbra-guard.sh) —— 根据契约检查单个路径/命令或 所有已暂存的文件。将其接入 git pre-commit hook、CI 步骤或 agent 包装器中。同时也作为 `pre-commit` hook 暴露 (`.pre-commit-hooks.yaml`)。 ## 强制执行的保障在于 CI 编辑器内的 guard 属于尽力而为的纵深防御。*强制执行*的关卡是 **Umbra Admission GitHub Action** —— 将其设为必需的状态检查，没有签名回执就什么也 无法合并： . `auto_merge` 始终为 false —— Umbra 管理 agent；而由人类执行合并。 ## 许可证 [MIT](LICENSE) © 2026 bkd-dotcom.

标签：AI代码助手, Cutter, SOC Prime, Streamlit, 代码规范, 开发工具, 插件, 访问控制, 逆向工具