Harmonist质量门禁实战如何强制AI智能体先过QA再交付代码【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonistHarmonist 是一个可移植的 AI 智能体编排框架Portable AI agent orchestration内置 186 个专业智能体、零运行时依赖。它的核心卖点是机械式协议强制执行通过 IDE 钩子Hooks把质量门禁QA Gate变成硬性关卡——AI 智能体没跑完 QA 验证就不许结束代码交付。本文用一次完整实战带你配置先过 QA 再交付的强制流程。一、为什么 AI 写代码需要质量门禁AI 编程助手有一个结构性缺陷你可以用提示词Prompt告诉它必须先跑 QA 再交付但没有机制强制它照做。它可能口头答应然后悄悄跳过测试环节自信地说已完成。好的一天你发现了坏的一天bug 直接上线。传统方案只有两个不完美的选择方案问题轻量智能体框架纯 Prompt 编排规则写在提示词里模型可以随时自我豁免重型企业平台需要独立运行时和数据库有供应商锁定Harmonist 的立场很直接协议强制执行必须是磁盘上的状态机不是提示词里的客套请求。它用一组具体的 Shell / Python 脚本挂接 IDE 的钩子事件观察每一次子智能体调度、每一次文件写入、每一次会话结束——规则不满足时stop钩子直接拒绝让本轮对话完成。二、快速上手3 步装好 QA 强制门禁Harmonist 零运行时依赖不需要 npm、Docker、LangChain 或向量数据库纯 Python 标准库3.9即可在 Windows / macOS / Linux 原生运行。第 1 步克隆到你的项目根目录作为子文件夹cd your-project/ git clone https://gitcode.com/gh_mirrors/ha/harmonist.git第 2 步选择集成方式二选一Cursor 用户推荐在 Agent 模式下粘贴 integration-prompt.md 的内容AI 会自动分析你的项目、生成带领域规则的AGENTS.md模板见 AGENTS.template.md并安装全部强制钩子。无 Cursor 用户直接运行 CLI 集成脚本 agents/scripts/integrate.py。第 3 步确认钩子已加载打开 IDE 的Settings → Hooks确认 6 个钩子sessionStart、afterFileEdit、subagentStart、subagentStop、beforeShellExecution、stop全部加载成功。钩子注册表定义在 hooks/hooks.json详细说明见 hooks/README.md。三、stop 门禁到底检查什么stop钩子是整个框架的守门员。只要本会话改过任何文件忽略清单外的路径它会在 AI 试图收尾时执行三项硬检查#检查项不通过的结果1至少调用过一个category: review的审查智能体返回followup_message本轮不许结束2特别地qa-verifier必须被调用过同上AI 会被要求补跑 QA3.cursor/memory/session-handoff.md本会话内已更新同上任何一项失败钩子都会告诉 AI具体缺了什么然后重新打开这一轮让它补齐。loop_limit: 3限制重试次数重试耗尽后事故会被记录并作为醒目的横幅在下一个会话开场展示。 一句话总结模型嘴上说我做完了没用钩子只认磁盘上的证据。四、qa-verifier交付前的独立 QA 角色门禁点名必须运行的qa-verifier是 agents/review/qa-verifier.md 定义的独立验证者。它的设计精髓是**不参与实现不继承实现者的偏见**只做验证✅ 对照原始需求、计划与最终 diff确认变更真正满足请求的行为✅ 每个新增/修改函数是否有对应单测、边界条件空集合、null、极值是否覆盖✅ 检测破坏性变更方法签名、数据库结构、配置格式、被依赖的函数删除✅ 检查迁移顺序、幂等性、API 超时/并发等边缘情况✅ 确认新代码未泄露密钥最后它只返回结构化裁决done / partially_done / blocked外加缺失项清单。它的座右铭是八个字Do not praise. Verify.不吹捧只验证。除qa-verifier外review类别还有 security-reviewer.md安全审查、bg-regression-runner.md回归测试、code-quality-auditor.md代码质量等 6 个只读审查官可按触发条件组合使用。五、细调门禁配置项与逃生舱门禁策略集中在.cursor/hooks/config.json项目级可覆盖默认值默认策略内置于 hooks/scripts/lib.sh常用项包括require_qa_verifier/require_any_reviewer开关必须跑 QA / 必须跑审查官reviewer_slugs指定哪些智能体算合格审查官skip_path_patterns哪些路径改动不触发门禁如node_modules、distmax_concurrent_subagents并发子智能体上限防止内存被拖爆逃生舱对纯注释改字这类琐碎变更AI 可以输出PROTOCOL-SKIP: 原因绕过门禁。钩子会完整记录每一次跳过跳过率超过阈值默认 25%下一个会话开场就会收到滥用警告——可以轻松退出但很难悄悄滥权。六、如何验证门禁真的在生效看状态文件.cursor/hooks/.state/session.json会记录本会话的每次写入、已计数的审查官活动日志在.cursor/hooks/.state/activity.log。跑纯集成测试无需启动 IDE直接向脚本管道灌入模拟事件覆盖 8 个标准场景缺 qa-verifier、PROTOCOL-SKIP、缺 AGENT 标记等bash hooks/tests/run-hook-tests.sh常见坑审查官跑了却没被计入99% 是子智能体提示词首行缺少AGENT: qa-verifier标记——补上标记重新派发即可。七、写在最后门禁 ≠ 安全边界需要诚实说明门禁是流程约束不是防恶意篡改的安全边界官方文档 hooks/README.md 的 Limitations 一节有明确解释。它的价值在于——让诚实但健忘的 AI 智能体无法再跳步。配合MANIFEST.sha256的供应链校验和跨会话的结构化记忆memory/SCHEMA.mdHarmonist 用纯 Markdown 标准库 Python Bash就搭出了一套完整的交付流水线改动必须过 QA审查必须留证据事故必须被记录。这就是机械式协议强制执行的全部含义把质量门禁从一句客气话变成 AI 无法绕过的关卡。【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考