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

企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its 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 工程技巧当 vibeUnified 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 gainAgent 运行时可以直接调用rtk hook vibe来对将要执行的 bash 命令做安全改写。这正是 .agents/hooks/README.md 所要解决的问题的上下文。问题核心工具名不匹配导致命令重写失效rtk hook vibe的工作机制是vibe 在执行每个工具调用前把调用信息以 JSON 形式通过 stdin 传给 hookrtk 收到负载后只对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 认可的工具名bashsys.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 团队如何在容器里运行 vibevibes.sh会构建镜像并以当前目录为工作目录挂载启动容器同时把宿主机的~/.vibe目录绑定挂载进容器--mount typebind,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.tomlrtk-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 工程工具箱中。赞分享企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载相关推荐rtk 的 Rust TDD 工作流Red-Green-Refactor 循环与仓库级测试规范解析rtk 的 Rust TDD 工作流Red Green Refactor 循环与仓库级测试规范解析 本文基于 rtkRust Token Killer仓库CLI开发工具AI 应用DeepSeek Harness 仓库命名契约与重命名台账一文读懂「一词汇一角色」的命名规范DeepSeek Harness 仓库命名契约与重命名台账一文读懂「一词汇一角色」的命名规范 导读 DeepSeek Harness Everything人工智能AI AgentAgent 框架DeepSeekEasy-Vibe 仓库工程指南VitePress 多语言文档站的开发、协作规范与部署实战Easy Vibe 仓库工程指南VitePress 多语言文档站的开发、协作规范与部署实战 本文基于 easy vibe 仓库根目录的 AGENTS.md h教程文档上一篇开源项目HID Remapper指南及问题解决方案下一篇react-native-quick-crypto 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考