AI 编程助手也能被强制审查?Harmonist 用 Hook 做到了

AI 编程助手有一个结构性的缺陷：你告诉它”每次改完代码要跑测试”，它点点头照做了——然后某次忘了，bug 就上线了。

这不是模型能力的问题。再强的模型也无法被 prompt “强制”做任何事——prompt 是建议，不是契约。在工程领域，建议和契约之间的差距，就是线上事故的温床。

Harmonist^[1] 对这个问题给出了一个不同的答案：把协议执行从 prompt 层搬到 Hook 层。代码改完不跑审查？Hook 直接拦住，turn 无法完成。

项目卡片

• 项目：Harmonist^[2]
• 状态：v1.0.0 / 1,100+ Stars / 10 天内发布并获得快速增长
• 一句话判断：首个将工程协议执行做成机械闸门而非提示词建议的 AI Agent 框架，工程严谨度拉满

薄层 Agent 框架（LangChain、CrewAI、AutoGen）提供了编排原语，但把执行纪律留给 prompt。模型同意遵守规则，也可能在下一轮对话中忘掉。重型平台承诺治理，但需要独立运行时和基础设施——单人开发者用不起。

Harmonist 不替换你的运行时。它装在项目旁边，通过 IDE Hook 观察每一次子 Agent 调度和文件编辑。规则写在 AGENTS.md 里，执行靠 shell 脚本和状态机。

Harmonist 的执行层定义了五个生命周期钩子，每个对应 IDE 事件的一个阶段：

stop 钩子是整个系统的关键。如果当前会话修改了代码文件，闸门检查三个条件：至少一个 review 类别的 Agent 被调用过、qa-verifier 被调用过、session-handoff.md 已更新且 correlation_id 匹配。任何一个条件不满足，钩子返回 followup_message 迫使 AI 补完缺失步骤。loop_limit: 3 设置了重试上限——三次机会用完，事件被记录为 incident，下次会话开始时会看到明确警告。

Prompt 写”请遵守审查流程”，AI 可以口头答应然后跳过。on-disk 的状态机没有这个余地。

Harmonist 内置了 186 个领域专家 Agent，分布在 16 个类别中：46 个工程 Agent（后端、前端、DevOps、数据、AI）、6 个审查 Agent（安全、质量、QA、SRE、回归、a11y）、30 个营销 Agent、20 个游戏开发 Agent，甚至包括 TON 区块链审计、Apple Vision Pro 空间计算、微信小程序和 Roblox 等小众领域。

但数量不是重点。关键在于路由机制：

编排器从不硬编码 Agent 名称。它从任务描述中提取最多 5 个标签（比如”添加支付手续费计算”→ payments, backend, fintech, audit），然后和 agents/index.json 做交集，过滤掉项目不相关的领域 Agent，最后选出标签匹配度最高的专家。当多个候选 Agent 命中时，115 个 Agent 自带的 disambiguation 元数据提供一对一比较说明——”我用 X；如果做 Y 去找另一个”。

大多数项目激活 10-20 个专家，其余 160+ 个通过 domains × roles × tags 过滤自动隐藏。一个 Web SaaS 项目永远不会看到 Solidity 审计 Agent 或微信营销 Agent。

传统方案让 LLM 自己维护记忆——写什么、什么时候写、用什么标识符，全靠模型自觉。Harmonist 把记忆的写入权收归 CLI。

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

ID 和时间戳自动生成，correlation_id 从 hooks 状态文件读取而非 LLM 提供。写入前扫描 body 中 30+ 类密钥模式（AWS Key、GitHub PAT、Stripe Token、数据库连接串等），检测到泄露直接拒绝。

correlation_id 的设计尤其值得关注。格式为 <unix-seconds><pid4>-<task_seq>，PID 后缀防止同一秒内并发会话碰撞。同一个任务产生的状态快照、架构决策和经验教训通过 correlation_id 串联——这些关联关系从 hooks 的角度是密码学有序的，不是信任模型”记得写对”。

Agent 定义文件会被拷贝到项目的 .cursor/agents/ 目录，成为编排器 prompt 上下文的一部分。一个被篡改的 security-reviewer.md（比如改成”全部批准”）会悄悄绕过所有安全审查。

Harmonist 为此做了三层防护：

1. MANIFEST.sha256 覆盖全部 262 个文件。upgrade.py --apply 在拷贝任何文件前逐个验证 hash。不匹配的文件直接拒绝：

   ! REFUSED  agents/review/security-reviewer.md: manifest expected
              5d731c6b..., actual 4b5c2283... -- possible supply-chain tampering
   

2. 安装后锚点 — .cursor/pack-manifest.json 记录每个安装文件的 hash。verify_integration.py 可以检测有人在本地修改了 gate-stop.sh 或审查 Agent 的定义。
3. 提示注入扫描器 — scan_agent_safety.py 对每个 Agent 做 4 类检测：override（越狱指令）、exfil（密钥窃取）、remote exec（curl|bash）、policy subversion（”跳过 qa-verifier”）。CI 中对整个目录扫描，安装后对已安装的 Agent 再次扫描。

Agent 定义文件本质上会成为 prompt 上下文的一部分。对这类文件做供应链校验，不是过度工程，是必要的卫生习惯。

# 1. 克隆到项目根目录
cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git

# 2. 在 Cursor 中打开项目，切换到 Agent mode
# 3. 粘贴 harmonist/integration-prompt.md 的内容
# 4. 跟着 AI 的引导走——它会分析项目、选择合适的专家、生成定制化 AGENTS.md
# 5. 集成完成后，开一个新 chat 开始使用

也提供 CLI 方式，不依赖 Cursor：

python3 harmonist/agents/scripts/integrate.py --pack harmonist --project .

唯一的前提条件：Python 3.9+ 和 Bash。没有 npm、Docker、LangChain 或向量数据库——纯 stdlib Python + bash，跨平台兼容（Windows 用纯 Python 实现的 hook_runner.py 替代 shell 脚本）。

Harmonist 解决的问题是真的存在且重要的。AI 编程助手跳过审查步骤、伪造记忆条目、在 Agent 定义文件中注入恶意指令——这些都是当前生态的实际风险，而 Harmonist 给出了具体的工程解法。

几个值得注意的点：

• 主要绑定 Cursor 生态。虽然声称支持 11 种 IDE，但 Hook 闸门机制依赖 Cursor 的 hooks API。在其他 IDE 中退化为”约定+验证”模式，执行力明显减弱。
• 186 个 Agent 的维护成本。check_pack_health.py 运行 18 项检查，scan_agent_freshness.py 检测过期定义，CI 有 10 个 job——维护这个规模的 Agent 目录不是零成本的。
• 首次发布（v1.0.0），2026-04-23 刚开源。仓库只有 2 个 commit，10 天获得 1100+ Stars，增长速度很快，但实际生产验证案例还不多。
• MIT 许可证，零外部依赖，430+ 测试断言——工程素养和开源诚意是到位的。

如果你在做严肃的 AI 辅助工程项目，并且在意”AI 说它做了审查”和”审查真的被执行了”之间的差距，Harmonist 值得试用。430+ 测试断言、零外部依赖、MIT 许可证——至少工程素养和诚意都在线。

如果这篇对你有用，建议点个关注。我会持续把 GitHub 上值得用的 AI 工具拆成「最短上手闭环 + 坑点清单 + 可复用配置」，让你少走弯路。

引用链接