Harmonist

具备机械协议强制执行能力的便携式 AI Agent 编排框架

一款适用于 Cursor、Claude Code、Copilot、Windsurf、Aider 及其他 AI 编码助手的插件式多 Agent 框架。

由 GammaLab 开发并维护 · @GammaLabTechnologies

---

大多数 AI 编码框架依赖语言模型自觉遵守规则。而 Harmonist 拒绝让 AI 跳过这些规则。每一次代码变更回合都由 Hook 严格把关，检查必要的审查流程是否运行、内存是否更新、以及每个已交付文件的供应链是否完整。如果检查未通过，即便模型信誓旦旦地声称已完成，该回合也无法结束。

这是首个将协议强制执行作为机械闸门而非提示词中礼貌请求的开源 Agent 框架。

---

目录

• 为什么需要 Harmonist
• 核心差异
• 环境要求
• 快速入门
• 架构设计
• 186 个 Agent 目录
• 机械强制执行
• 结构化验证内存
• 供应链完整性
• 支持的 IDE 集成
• 关键脚本
• 文档
• 测试
• 常见问题
• 参与贡献
• 安全性
• 许可证
• 关于 GammaLab

---

为什么需要 Harmonist

AI 编码助手存在一个仅靠 Prompt Engineering 无法解决的结构性问题。

问题所在： 每个严谨的工程工作流都有不可逾越的规则——“金额计算禁止使用浮点数”、“合并前运行 QA”、“所有外部调用必须使用幂等键”、“修改鉴权代码前必须经过安全审查”。你可以告知 LLM 遵循这些规则，但没有任何机制能强制它执行。模型可能会同意、继续操作并悄悄跳过这一步。运气好你能发现，运气不好就会导致 Bug 上线。

当前的解决方案分为两类，但都不够完美：

• 轻量级 Agent 框架（如 LangChain、CrewAI、AutoGen、MetaGPT 等）：提供了编排原语，但将执行留给 Prompt。模型总是可以覆盖自己的协议。
• 重型企业级平台：承诺通过独立的运行时、数据库和厂商锁定来管理治理，但它们需要复杂的安装基础设施，无法在个人开发者的笔记本电脑上运行，也无法进行逐文件审计。

Harmonist 采取了不同的立场。 协议强制执行被实现为 IDE 级别的 Hook——即具体的 Shell 和 Python 脚本，用于观察每一个子 Agent 分派、每一次文件编辑和每一次会话终止。当项目声明的规则未得到满足时，stop Hook 会向 AI 返回一条 followup_message 并拒绝完成当前回合。模型无法拒绝这一点；因为这是一个基于磁盘的状态机。

没有运行时，没有数据库，没有厂商锁定。只有 Markdown、标准库 Python 和 Bash——它们静静地驻留在你的代码旁，正确地完成任务。

---

核心差异

Harmonist 提供了七个具体且可验证的特性，每一个都填补了其他开源 Agent 框架留下的空白。

1. 通过 IDE Hook 实现机械协议强制执行

.cursor/hooks/ 中的 stop Hook 会解析会话中的子 Agent 分派标记，检查 qa-verifier 是否运行、是否缺少必要的审核人员、session-handoff.md 是否已更新。如果回合不完整，它会返回一条结构化的 followup_message。loop_limit: 3 限制了重试次数。一旦耗尽，将记录并在一轮会话中上报异常。AI 实际上无法在跳过审查的情况下提交代码变更。

2. Agent 定义的供应链验证

每个发布的文件都在 MANIFEST.sha256 中进行了哈希校验。upgrade.py 在复制到项目之前会对每个源码进行 sha 校验。如果有人篡改了 security-reviewer.md（例如，使其对所有操作返回 approve），系统将拒绝执行。