harmonist
GammaLabTechnologies/harmonist加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
在 AI 编程工具日益普及的今天，一个核心问题始终悬而未决：谁来保证 AI 真的执行了你的要求？ 当 Cursor Agent 或 Claude Code 自信满满地「完成」了一个任务，你很难知道它是否真正遵守了代码规范、是否更新了测试、是否绕过了安全审查。Harmonist（当前版本 1.2.3）正是为了解决这个问题而生——它不是又一个 AI Agent，而是一套机械强制执行的工作流协议。
Harmonist 由 GammaLab Technologies（一家专注 AI 工程工具的阿联酋公司）开发和维护，是一个纯 Python stdlib 构建的 AI 编码助手编排系统。它的核心设计哲学是：与其相信 AI 会自觉遵守规则，不如用代码强制它遵守。即使 AI 模型「自信地」声称已完成所有步骤，Harmonist 的 Hook 机制也会在实际放行前逐一验证。
当团队在生产环境中引入 AI 编码助手后，很快就发现「信任」是最大的幻觉。一个典型的 AI 编码流程可能跳过了这些关键步骤：更新相关测试、记录决策理由、通知代码审查者、甚至确认安全影响。尤其是多智能体协作时，一个 Agent 的输出成为另一个 Agent 的输入，如果上游 Agent 偷工减料，错误会在整个链路中放大。
Harmonist 的作者团队在长期使用 Claude Code 和 Cursor 进行项目开发后，总结出了一套可验证的多智能体协作标准流程，并将其产品化为一套开源工具包。这套流程被设计为「机械可执行」——不依赖 AI 的自我约束，而是通过 Git Hook、验证脚本和 YAML/JSON 配置来强制执行。
Harmonist 维护了一个包含 193 个预定义 Agent 的统一目录，分布在 16 个专业分类下：
每个 Agent 遵循统一的 Schema v2 规范定义，前置元数据（YAML frontmatter）包括：name、description、category、protocol、readonly、is_background、model、tags。Protocol 分为两种模式：
strict（严格协议）：用于编排和审查类 Agent，必须结构化输出，必须经过审查门禁，始终只读（readonly: true）persona（角色协议）：用于专业领域 Agent，灵活调用，按标签匹配触发Harmonist 包含一套完整的 Git Hook 运行时系统，核心是 hooks/hook_runner.py（约 73KB，Python stdlib 实现）。这套 Hook 在每次代码变更前后自动执行，验证以下关键门禁：
gate-shell.sh），确保 AI 发起的系统命令经过人工确认stop）：如果 AI 跳过了强制步骤（如未运行测试、未更新内存），阻止操作完成这套 Hook 机制的关键设计是失败即停止（fail-closed）：如果任何门禁检查失败，操作不会继续，即使 AI 已经「自信地」宣布完成。这意味着 AI 无法通过声称「已经做了」来绕过实际验证。
Harmonist 维护三个 Markdown 记忆文件，位于项目 .cursor/memory/ 目录：
| 文件 | 用途 |
|---|---|
session-handoff.md | 当前项目状态，每个会话开始时读取 |
decisions.md | 架构决策日志，只追加不修改，通过 correlation ID 关联 |
patterns.md | 过往任务的经验教训，供后续参考 |
记忆 CLI（memory/memory.py，约 51KB）自动生成 correlation ID 和时间戳，防止 AI 伪造记录。所有记忆条目必须经过验证脚本检查，确保格式正确后才追加到文件。
Harmonist 最令人印象深刻的技术特点之一是零运行时依赖。整个工具链（linter、index 生成器、集成脚本、Hook 运行时、Memory CLI、仓库地图）全部使用 Python 标准库实现，不依赖任何第三方 pip 包，也不需要 Docker 或 Node.js。
这带来了几个显著优势：
.gitlab-ci.yml 自动化测试套件（550+ 测试用例），确保每个版本的 Hook 和 Agent 定义都经过验证Harmonist 的部署模型与其他开源项目截然不同：它不是一个需要运行的服务器或守护进程，而是一个需要「融合」进项目的工作流定义包。
集成流程（以 Cursor IDE 为例）：
harmonist/）"Read harmonist/integration-prompt.md and integrate"AGENTS.md 文件（从模板 AGENTS.template.md 实例化）harmonist/hooks/ 目录集成完成后，Harmonist 的所有协议规则就成为项目工作流的一部分，所有 AI Agent 操作都必须经过它的门禁验证。这种「融合而非附加」的设计哲学，确保了协议强制不会因为「忘记运行」而失效。
适合场景：
不太适合：
技术要求： 需要使用支持 Agent 模式的 AI IDE（Cursor、Claude Code、Windsurf、Copilot 等），以及 Python 3.9+ 环境（仅 Harmonist 自检工具需要）。
Harmonist 并非银弹，存在几个值得关注的局限：
index.json 和元数据Harmonist 代表了 AI 编程工具发展的一个重要方向：从「相信 AI」到「验证 AI」。随着 Claude 4、GPT-5 等更强模型的出现，AI 生成代码的质量已经相当高，但质量保证的责任边界始终模糊。Harmonist 通过将人类团队的质量管理流程编码为可验证的机械规则，为这个问题提供了一个务实的工程解法。
从 GitHub 数据看，项目获得了 1657 stars、250 forks、0 open issues 的健康指标（issue 全闭合），说明维护质量较高。近期活跃度（2026-06-09 最后推送）保持在较高水平。
# 1. 克隆项目
git clone https://github.com/GammaLabTechnologies/harmonist.git
# 2. 放入你的项目根目录
cp -r harmonist /your/project/root/
# 3. 在 Cursor Agent 模式输入集成指令
# Read harmonist/integration-prompt.md and integrate
# 4. 新建聊天，开始使用
更多使用细节参考项目 GUIDE_EN.md 和 playbooks/QUICKSTART.md。