🎼 Harmonist：186 个 Agent 的机械协议强制框架，零依赖零运行时，让你的 AI 代码审查插翅难飞 / Harmonist: 186-Agent Mechanical Protocol Enforcement, Zero-Runtime Drop-In Framework

一句话秒懂

Harmonist 是第一个对 AI 编码 Agent 实施机械协议强制（mechanical protocol enforcement）的开源框架。1.3k Stars，零运行时依赖（纯 Python stdlib + bash），支持 Cursor/Claude Code/Copilot/Windsurf/Aider 等 11 个 IDE/CLI 工具。核心卖点：不靠提示词"建议"AI 遵守规则，而是用 IDE hook 在物理层面阻止违规代码通过。

终极拷问：为什么提示词工程搞不定代码质量？

用过 AI 写代码的人都有这个体验——你跟它说"改金融代码不能用浮点数"，它满口答应，然后悄悄写了个 float，跑完测试发现钱算错了。这不是模型笨，是提示词没有强制力。

现有的解决方案走两个极端：

• 薄 Agent 框架（LangChain、CrewAI、AutoGen）：提供了编排原语，但强制全靠提示词——模型随时可以"忘记"自己的协议
• 重企业平台：承诺治理但需要额外运行时、数据库、供应商锁定——个人开发者装不起

Harmonist 搞了个中间路线：在 IDE hook 层实现机械协议强制。每次 session 结束时，stop hook 检查：QA 审了没有？安全审了没有？memory 更新了没有？一项没过就不允许 session 完成——模型说啥都没用，这是磁盘上的状态机。

七个让你无法拒绝的特性

1. 机械协议强制（IDE Hook 级别）

# 每次 session 结束时的 stop hook 检查链
# 任一不满足 -> followup_message 拒绝完成
- qa-verifier 是否执行了？
- 安全审查是否过了？
- session-handoff.md 是否更新了？
- loop_limit: 3 次重试，超限记录 incident

2. 供应链完整性验证（SHA256 Manifest）

# upgrade.py 在复制 agent 文件前验证 sha256
# 如果有人篡改了 security-reviewer.md，直接拒绝安装
$ python3 agents/scripts/upgrade.py --apply
! REFUSED agents/review/security-reviewer.md:
  manifest expected 5d731c6b..., actual 4b5c2283...
  -- possible supply-chain tampering

3. 模型无法伪造的 Memory Correlation ID

correlation_id 格式：<unix-seconds><pid4>
# hook 在 session 启动时生成，LLM 只读不写
# 确保 state → decision → pattern 的链路可信

4. Schema 验证 + 密钥扫描

# 唯一写入路径：memory.py append，自动校验 + 防泄密
$ python3 .cursor/memory/memory.py append \
  --file session-handoff --kind state --status done \
  --summary "Integrated Stripe webhook handler" \
  --tags payments,backend \
  --body-file /tmp/handoff-body.md
# 自动扫描 ~30 种密钥模式（AWS/GitHub/Stripe/Slack...）

5. 186 个精选领域专家，不是"一个通用编码器"

6. 集成即提示词（Integration-as-a-Prompt）

# 1. 克隆到项目根目录
$ git clone https://github.com/GammaLabTechnologies/harmonist.git

# 2. 打开 Cursor Agent 模式，粘贴 integration-prompt.md
# 3. AI 自动分析项目、选角色、写 AGENTS.md、装 hook、初始化 memory
# 4. 开始新会话——搞定

# 或者 CLI 一行命令（不需要 Cursor）
$ python3 harmonist/agents/scripts/integrate.py --pack harmonist --project .

7. 零依赖、跨平台

"Pure Python stdlib + bash. No npm, no Docker, no LangChain, no vector database."

430+ 测试断言，POSIX .sh + 纯 Python hook_runner.py 两套实现，双路径 CI 验证。

一句话评价

Harmonist 不是另一个 Agent 框架——它是 Agent 框架的"交通警察"。 在所有人都靠提示词"请求"AI 遵守规则的时候，它直接在物理层面锁死了违规路径。Security-reviewer 被篡改了？安装器直接拒绝。QA 没执行？session 不让你通过。对于把 AI 写代码用到生产环境的团队来说，这不是加分项，是刚需。

Quick Facts

• GitHub: https://github.com/GammaLabTechnologies/harmonist
• Stars: ~1.3k (fresh project, growing fast)
• License: MIT
• Dependencies: Zero (stdlib only)
• Supported Tools: Cursor, Claude Code, Copilot, Windsurf, Aider, Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, Antigravity — 11 platforms
• Agent Count: 186 curated specialists across 16 categories
• Language: Python 3.9+ (stdlib) + Bash 3.2+
• Tests: 430+ assertions in CI