Harmonist杀手锏：机械协议强制如何让AI智能体无法跳过质量检查

Harmonist杀手锏机械协议强制如何让AI智能体无法跳过质量检查【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonistHarmonist 是一个可移植的AI 智能体编排框架内置机械协议强制mechanical protocol enforcement它用 IDE 钩子给每一轮代码修改上锁让AI 智能体无法跳过质量检查必须跑完 QA 验证、更新记忆、通过供应链校验后才能收尾。下面带你快速看懂这套质量门如何把口头承诺变成硬约束。为什么口头叮嘱靠不住AI智能体为何会跳过质量检查 任何严肃的工程流程都有一批不可妥协的规则改完代码必须跑 QA、合并前过一遍安全审查、动到鉴权代码先做安全评审……问题在于这些规则通常只写在提示词Prompt里。模型可以答应然后默默跳过它可以自信地宣称已完成其实根本没跑测试好日子你能发现坏日子 bug 就直接上线了。提示词只是建议AI 把它当建议对待——它没有动力也没有机制逼它守规矩。这正是 Harmonist 要解决的痛点。 核心区别别的项目让模型自觉Harmonist 让它不守规矩就交不了差。Harmonist 的杀手锏把协议变成一道机械闸门 Harmonist 的思路是协议强制执行不是提示词里的礼貌请求而是磁盘上的一台状态机。它通过 IDE以 Cursor 为主的钩子系统给智能体的完整生命周期挂上了6 道真实脚本钩子阶段干什么sessionStart初始化任务关联 ID注入最近的记忆快照预警历史事故afterFileEdit记录每一次文件写入供收尾闸门核对subagentStart解析AGENT: slug标记记录调用了哪个审查员subagentStop记录审查结论更新遥测beforeShellExecution危险命令人在环拦截需人工确认stop就是那道闸门校验审查员是否跑过、记忆是否更新完整规则声明见 AGENTS.template.md钩子总览在 hooks/README.md。关键在于stop钩子——当智能体想收工时它会在磁盘上核对会话状态。规则不满足就返回一条followup_message强行把这一轮打回去让 AI 把漏掉的步骤补完。模型没法争辩因为这是一台实实在在的状态机。质量门到底查什么三道硬性检查 ✅如果本轮会话改动了任何非忽略路径下的文件stop闸门会逐一核对三项默认全部开启至少调用了 1 个review类审查员require_any_reviewer特别调用了qa-verifierrequire_qa_verifiersession-handoff.md记忆已更新且其中的correlation_id与当前任务匹配qa-verifier本身是一位独立验证者——它不参与实现专门核对改动是否真的满足需求、测试是否覆盖、边界与迁移是否一致、有没有泄漏密钥。它只验证不吹捧。定义见 agents/review/qa-verifier.md。判断逻辑集中在 hooks/scripts/gate-stop.sh 中钩子注册在 hooks/hooks.json。质量检查没通过AI 会被怎样逼回来 一旦有检查项缺失闸门不会放行而是返回一份结构化回执明确告诉 AI本协议无法收尾。本任务改动了src/...缺失的协议步骤required reviewer qa-verifier was not invokedsession-handoff.md 缺少当前任务的关联条目行动要求用 Task 子智能体补齐缺失的审查员首行必须写AGENT: qa-verifier用memory.py追加一条 state 记忆关联 ID 自动匹配有重大架构决策就追加一条 decision 条目然后再给出最终答复这套逼回来的机制有三重设计重试上限loop_limit: 3避免 AI 无限循环失败关闭fail-closed重试耗尽时不会静默放行而是把任务标记为PROTOCOL-VIOLATED并把事故写入incidents.json下次会话开始时以醒目横幅再次浮现遥测审计闸门放行/拦截/跳过次数都计数滥用行为可被察觉。简言之诚实但健忘的 AI 会被拉回正轨而想磨时间混过去的尝试会被留档记名。什么时候可以放行PROTOCOL-SKIP 安全阀 再严格的闸门也要留后门否则改个错别字也要走全套流程就太演戏了。对于真正琐碎的轮次注释里的错字、Markdown 措辞微调AI 可在最终消息中写一行PROTOCOL-SKIP: 一句话理由闸门会记录这条跳过并放行若跳过率超过阈值默认 25%且至少 5 次下次会话会弹出滥用警告换句话说轻易可选出却很难悄悄滥用。此外只改文档/README 等平凡路径的轮次默认也会走轻量模式直接放行——但只要夹带一个代码文件改动快速通道立即失效没有藏身之处。新手快速上手一键集成 Harmonist 质量门 Harmonist零运行时依赖纯 Python 标准库 bash不需要 npm、Docker 或向量数据库Windows / macOS / Linux 原生可用。集成只需两步把harmonist作为子文件夹放进项目根目录在 Cursor 的 Agent 模式下粘贴 integration-prompt.md 的内容按 AI 的引导选择你的领域与角色。之后 AI 会自动挑选合适的专家、生成项目专属AGENTS.md、安装强制执行钩子并把集成状态写入.cursor/pack-version.json。集成后在 Cursor 的Settings → Hooks里确认6 个钩子均加载无误即可。想自己验证闸门行为可运行纯集成测试无需 Cursorhooks/tests/run-hook-tests.sh。⚠️ 小提示一个项目只在一个 Cursor 窗口里做受控改动两个窗口会互相覆盖会话状态导致闸门判定紊乱。常见问题关于机械协议强制 ❓Q这是 LangChain / CrewAI 的替代品吗不是。那些是在其上构建应用的框架Harmonist 是丢进现有项目里让你的 AI 助手守规矩的包。两者可以共存。Q为什么不用提示词引导偏要做机械强制因为提示词是建议模型会照此看待而一个在 QA 跑完前拒绝收尾的stop钩子是契约。我们选择了契约。Q可以自定义协议吗可以而且应该。项目级AGENTS.md是你领域不变量、技术栈、模块与容错策略的权威来源编排器对它的优先级高于任何专家智能体。Q这些闸门是安全边界吗不是。它们是针对诚实但健忘的智能体的进程级督促并非对蓄意对抗者的防篡改边界——文档在 hooks/README.md 的限制章节讲得很直白。关键文件速查表 文件作用hooks/scripts/gate-stop.shstop闸门核心裁决逻辑hooks/hooks.json6 道钩子的注册与loop_limitagents/review/qa-verifier.md独立 QA 验证者定义AGENTS.template.md协议规则与 stop 闸门说明memory/SCHEMA.md记忆条目结构与校验规则hooks/tests/run-hook-tests.sh无 Cursor 的钩子集成测试一句话总结Harmonist 的杀手锏就是把AI 应该守规矩从一句愿望变成一个交不了差就过不去的机械闸门——质量检查从此无法被悄悄跳过。【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考