Harmonist杀手锏：机械协议强制如何让AI智能体无法跳过质量检查
【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist
Harmonist 是一个可移植的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-verifier（require_qa_verifier） session-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 invoked
- session-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 个钩子均加载无误即可。想自己验证闸门行为，可运行纯集成测试（无需 Cursor）：hooks/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.sh | stop闸门：核心裁决逻辑 |
| hooks/hooks.json | 6 道钩子的注册与loop_limit |
| agents/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），仅供参考
