Dolibarr 仓库 vibe Hook 实战：用 rtk-rewrite.sh 规范化 Unified Harness 工具名-育师

企业应用
后端

【免费下载链接】dolibarr

Dolibarr ERP CRM is a modern software package to manage your company or foundation's activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). it's an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.

项目地址：https://gitcode.com/gh_mirrors/do/dolibarr

点击查看免费下载

导读

本文讲解 Dolibarr 仓库中 .agents/hooks/README.md 记载的一个小而关键的 Agent 工程技巧：当 vibe（Unified Harness）把 bash 工具暴露为file_system.bash时，rtk hook vibe默认只改写tool_name == "bash"的命令，导致命令重写（command rewriting）静默失效。解决方案是编写一个rtk-rewrite.sh包装脚本，在把 hook 负载转发给 rtk 之前将工具名归一化。读完本文，你将掌握 vibe hooks 的配置方式、该包装脚本的逐行原理，以及如何在 Dolibarr 的 Agent 工作流（.agents/与dev/build/docker-vibe/）中落地这套机制。

背景：Dolibarr 仓库中的 Agent 基础设施

Dolibarr 仓库的根目录下维护着一整套面向 AI Agent 的工程配置，其中与本文直接相关的包括：

.agents/AGENTS.md：定义 Agent 在修改 Dolibarr 时必须遵守的规则（模块化架构、PHP 最佳实践、数据库、安全、Git 工作流等），并明确要求"Read this file before any modification"。
.agents/agents/agent-power.toml：一个名为 "Agent Power" 的 vibe 代理配置，描述为 "Auto-approves bash and write files, asks for everything else."，其中[tools.bash]的 allowlist 里明确包含了rtk命令（并禁止bash -i、sudo *等危险用法）。
dev/build/docker-vibe/：把 vibe 及其依赖封装进 Docker 容器的整套脚本（Dockerfile、docker-entrypoint.sh、vibes.sh、README.md）。

在 dev/build/docker-vibe/Dockerfile 中可以看到 rtk 的安装方式：

RUN curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh \ && cp /root/.local/bin/rtk /usr/local/bin/rtk \ && chmod +x /usr/local/bin/rtk \ && rtk --version \ && rtk gain

也就是说，在这个容器化的开发环境里，rtk是预先安装并完成授权的（rtk gain），Agent 运行时可以直接调用rtk hook vibe来对将要执行的 bash 命令做安全改写。这正是 .agents/hooks/README.md 所要解决的问题的上下文。

问题核心：工具名不匹配导致命令重写失效

rtk hook vibe的工作机制是：vibe 在执行每个工具调用前，把调用信息以 JSON 形式通过 stdin 传给 hook；rtk 收到负载后，只对tool_name == "bash"的命令执行重写逻辑（例如把rm -rf之类危险命令改写为安全版本，或注入白名单检查）。

但 Unified Harness 暴露 bash 工具时使用的名字是file_system.bash，而不是bash。结果就是：rtk 收到的 JSON 里tool_name为file_system.bash，条件判断tool_name == "bash"不成立，命令重写被静默跳过——hook 看似挂上了，实际上什么也没做。

.agents/agents/agent-power.toml 中[tools.bash]一节也从侧面印证了这一点：vibe 的 bash 工具确实带有命名空间前缀（file_system.bash属于file_system域），并且该配置特意用allowlist/denylist对 bash 命令做了双重约束。

解决方案：rtk-rewrite.sh 包装脚本

.agents/hooks/README.md 给出的完整方案是：不再让 hooks.toml 直接指向rtk hook vibe，而是指向一个包装脚本rtk-rewrite.sh，由脚本先把tool_name归一化，再转发给 rtk。

第一步：创建包装脚本

将以下内容保存为~/.vibe/hooks/rtk-rewrite.sh（路径可按个人环境调整，README 中示例使用/home/mylogin/.vibe/hooks/rtk-rewrite.sh）：

#!/usr/bin/env bash # Wrapper for "rtk hook vibe": rtk only rewrites commands when # tool_name == "bash". The Unified Harness exposes the bash tool as # "file_system.bash", so normalize the tool name before forwarding # the hook payload. python3 -c ' import json, sys d = json.load(sys.stdin) if d.get("tool_name") == "file_system.bash": d["tool_name"] = "bash" sys.stdout.write(json.dumps(d)) ' | rtk hook vibe

创建后需要赋予执行权限（在 Linux/macOS 环境下）：

chmod +x ~/.vibe/hooks/rtk-rewrite.sh

第二步：修改 hooks.toml

把~/.vibe/hooks.toml中原有的这一行：

command = "rtk hook vibe"

替换为指向包装脚本的绝对路径：

command = "/home/mylogin/.vibe/hooks/rtk-rewrite.sh"

注意必须是绝对路径，因为 hook 的执行环境不保证包含用户目录解析上下文。

逐行拆解：包装脚本为什么这样写

脚本本身只有寥寥数行，但每一行都承担着明确职责，值得拆开讲清楚：

代码	作用
`#!/usr/bin/env bash`	声明解释器，保证脚本可被直接执行
`python3 -c '...'`	调用 Python 一次性脚本做 JSON 解析与改写，避免引入额外的 jq 依赖
`d = json.load(sys.stdin)`	从 stdin 读取 vibe 传来的 hook 负载（JSON 对象）
`if d.get("tool_name") == "file_system.bash":`	仅当工具名为`file_system.bash`时才改写；其他工具名（如`write_file`、`edit`等）原样透传
`d["tool_name"] = "bash"`	归一化为 rtk 认可的工具名`bash`
`sys.stdout.write(json.dumps(d))`	把改写后的 JSON 重新序列化，写入 stdout
`\\| rtk hook vibe`	将归一化后的负载通过管道转发给 rtk 完成真正的命令重写

这里的关键设计是最小改写（minimal mutation）：只修改tool_name一个字段，负载中的其余字段（命令内容、参数、目录等）全部原样保留，确保 rtk 拿到的上下文与真实调用完全一致。

这种"stdin 读入 → 字段归一化 → stdout 输出 → 管道转发"的模式还可以很方便地扩展。例如，如果 Unified Harness 未来把其他工具也加了命名空间前缀（如file_system.read_file），只需在if判断中追加对应分支即可，例如：

d = json.load(sys.stdin) if d.get("tool_name") == "file_system.bash": d["tool_name"] = "bash" elif d.get("tool_name") == "file_system.read_file": d["tool_name"] = "read_file" sys.stdout.write(json.dumps(d))

在 Dolibarr 的 vibe 容器环境中如何配合使用

dev/build/docker-vibe/README.md 描述了 Dolibarr 团队如何在容器里运行 vibe：vibes.sh会构建镜像并以当前目录为工作目录挂载启动容器，同时把宿主机的~/.vibe目录绑定挂载进容器：

--mount "type=bind,src=$HOME/.vibe,dst=/home/$(id -un)/.vibe"

这意味着本文的 hook 配置（~/.vibe/hooks/rtk-rewrite.sh与~/.vibe/hooks.toml）写一次即可在宿主机与容器间共享——包装脚本在容器内依然可用，无需重复配置。

同时，dev/build/docker-vibe/docker-entrypoint.sh 展示了容器启动时对仓库内 Agent 配置的衔接方式：它会把仓库内的.agents目录软链为.vibe、把.agentsignore软链为.vibeignore，并以vibe --agent agent-power启动（可加--yolo跳过确认）。这与.agents/hooks/README.md的 hook 机制共同构成了完整的"仓库级 Agent 策略 + 用户级 hook 安全改写"体系：

仓库级：.agents/AGENTS.md规定"做什么"（编码规范、Git 纪律、安全边界）；
用户级：~/.vibe/hooks.toml+rtk-rewrite.sh规定"命令怎么被安全改写"（工具名归一化后交给 rtk 做危险命令防护）。

验证与排错建议

完成配置后，可以从以下几个角度验证 hook 是否生效：

直接喂 JSON 测试脚本：把一条模拟的 hook 负载通过管道输入包装脚本，观察输出中tool_name是否被改写：
```
echo '{"tool_name": "file_system.bash", "command": "ls"}' | ~/.vibe/hooks/rtk-rewrite.sh
```
预期输出（假设 rtk 对ls不做改写）中tool_name应为"bash"。若输出仍是file_system.bash，则说明脚本未被执行或权限不足。
检查脚本可执行权限：chmod +x未执行时，直接以command = "..."方式调用会报 Permission denied。
确认 hooks.toml 使用的是绝对路径：相对路径或~/写法在 hook 进程的工作目录不确定时容易解析失败。
确认容器镜像中已安装 rtk：参照 dev/build/docker-vibe/Dockerfile，镜像构建时应包含rtk --version与rtk gain的安装与授权步骤；若自建环境缺失，rtk hook vibe本身会直接报错，问题将不在工具名归一化层面。

小结

.agents/hooks/README.md 用极短的篇幅记录了一个极易被忽视、但影响 Agent 安全性的关键细节：hook 负载中的工具名必须与 rtk 的期望严格一致。借助rtk-rewrite.sh包装脚本，将 Unified Harness 的file_system.bash归一化为bash，即可让rtk hook vibe的命令重写能力在 Dolibarr 的 Agent 工作流（.agents/、dev/build/docker-vibe/）中真正生效。这一模式同样适用于其他存在工具名前缀差异的 Agent 框架，值得作为通用参考保留在你的 Agent 工程工具箱中。