Harmonist核心脚本API参考：10分钟掌握integrate/upgrade/install

Harmonist核心脚本API参考：10分钟掌握integrate/upgrade/install_extras/verify完整清单

【免费下载链接】harmonistPortable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.项目地址: https://gitcode.com/gh_mirrors/ha/harmonist

Harmonist 是一个可移植的 AI Agent 编排套件（Portable AI agent orchestration with mechanical protocol enforcement），自带 186 个以上代理定义与机械化的协议强制钩子，且零运行时依赖。如果你想在 Cursor、Claude Code 等 AI 编程助手中落地多智能体协作，绕不开它的 4 个核心脚本：integrate.py、upgrade.py、install_extras.py、verify_integration.py。本文给你一份面向新手的完整清单：每个脚本做什么、常用参数怎么传、退出码如何读，不用啃源码也能用。

需要克隆仓库时可用：git clone https://gitcode.com/gh_mirrors/ha/harmonist

一分钟看懂：四大核心脚本分工总览

Harmonist 的脚本都集中在 agents/scripts/ 目录，全部只依赖 Python 标准库（要求 Python 3.9+）。四个核心脚本各司其职，覆盖了"集成 → 升级 → 增补 → 验收"的完整生命周期：

脚本	一句话职责	源码位置
`integrate.py`	一条命令把整套编排体系集成进你的项目	agents/scripts/integrate.py
`upgrade.py`	把已集成项目平滑升级到新版 pack，支持快照回滚	agents/scripts/upgrade.py
`install_extras.py`	按 slug / 角色 / 标签按需追加专家代理	agents/scripts/install_extras.py
`verify_integration.py`	集成后的客观审计：缺什么、漏改什么一目了然	agents/scripts/verify_integration.py

官方脚本清单也可以对照 README.md 的 "Key scripts" 一节查看。

integrate.py：一键集成，把"判断"留给人

integrate.py的设计哲学是：确定性的工作全部机械化，需要领域判断的部分（选哪些专家、写哪些不可妥协的规则）留给开发者本人。它按顺序执行 9 个步骤，任一步失败都会给出FIX:修复提示，而且整体是幂等的——修完重跑即可。

典型用法（在项目根目录执行）：

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

常用参数清单：

参数	作用
`--project /path`	目标项目根目录（默认当前目录）
`--pack /path`	pack 根目录（含 VERSION + agents/ 的目录）
`--dry-run`	只展示执行计划，不写任何文件
`--skip-smoke`	跳过冒烟测试，调参期间重跑更快
`--json`	输出机器可读的 JSON 结果，方便脚本串联

内部 9 步流水线（对应源码中的step_1~step_9函数）：

健康预检— 调用 check_pack_health.py 做 19 项 pack 体检，不过则中止
写入 pack 文件— 实际执行upgrade.py --apply，落盘钩子、严格代理、内存工具等
回归命令探测— 自动发现项目的 test/lint/build 命令，喂给 bg-regression-runner
AGENTS.md 引导— 缺失时从 AGENTS.template.md 生成
规则文件引导— 落盘 protocol-enforcement 与 project-domain-rules 模板
内存引导— 在.cursor/memory/播种 session-handoff 初始状态
冒烟测试— 执行 smoke_test.py，验证强制层真的生效
客观验证— 调用verify_integration.py出验收报告
仓库地图— 构建 repomap（可选项，失败不阻塞）

退出码速查：0集成干净；1集成完成但有人工待办（比如 5~10 条领域规则还没写）；2预检/环境失败。

💡 集成完成后，脚本会打印"团队下一步清单"：定制 AGENTS.md 的 Invariants、补齐领域规则、从 agents/index.json 目录里挑 3~10 个专家。这些是脚本刻意"不代劳"的判断项。

upgrade.py：带快照的安全版本升级

pack 更新后，用upgrade.py把项目滚动到新版本。它有一条铁律：pack 拥有的文件（钩子、严格代理、内存工具等）可以刷新；项目拥有的文件（你定制的 AGENTS.md 内容、记忆文件等）绝不动。

常用参数清单：

参数	作用
`--apply`	真正执行复制（默认是 dry-run 只预览）
`--diff`	逐个文件展示将要变化的 unified diff
`--rollback`	从最近一次 pre-apply 快照回滚
`--snapshot NAME`	配合`--rollback`指定要恢复的快照
`--list-snapshots`	列出所有可用快照
`--no-snapshot`	跳过快照（不推荐，等于放弃回滚能力）
`--json`	JSON 输出

新手最该知道的三个安全机制：

📸自动快照：每次--apply前自动打快照，后悔了直接--rollback，一行命令回到升级前
⛔拒绝降级：如果 pack 版本低于项目记录的版本（见.cursor/pack-version.json），会直接拒绝执行
🔒供应链校验：所有文件复制前会对照 MANIFEST.sha256 做 sha 校验，被篡改的源文件会被拒装

退出码：0无需变更或 dry-run 成功；1apply 成功且有实际改动；2用户错误（缺 AGENTS.md、版本回退）；3找不到 pack 源。

install_extras.py：按需加装专家代理

集成时默认只装了"严格代理"（编排 + 评审门）。想按业务加装专家，就用install_extras.py——它支持三种选择方式：

选择方式	示例	说明
`--slug`	`--slug design-ux-architect,product-manager`	精确指定（逗号分隔多个）
`--role`	`--role marketing`	按角色捆绑包一次装齐（engineering/design/product/testing/marketing/sales/support/finance/academic 都有默认组合）
`--tag`	`--tag growth,seo`	按标签过滤，代理须同时命中所有标签

其他实用参数：--list先预览可安装清单；--thin只安装精简版（截到## Deep Reference之前的部分，省上下文）；--dry-run只演练；--force强制覆盖；--no-domain-filter关闭项目领域过滤。

退出码：0干净安装；1装成功但有警告；2参数错误、slug 不存在或触发拒装（比如试图覆盖 strict 代理——这类文件归upgrade.py管）。

📌 每次安装都会先对照 MANIFEST.sha256 做 sha256 校验，并把新条目写入.cursor/pack-manifest.json，之后verify_integration.py能持续追踪"装完后有没有漂移"。

verify_integration.py：不信任自述，只信客观审计

集成后最怕"AI 说完成了但实际漏了"。verify_integration.py就是针对这一步的客观审计器，逐项检查集成动作是否真的落地，而不是信任编排器的自我汇报。

典型用法：

python3 harmonist/agents/scripts/verify_integration.py --project /path/to/project --json

加--quiet则只打印失败项，适合放进 CI。

重点检查项（每条失败都附带一行 FIX 提示）：

AGENTS.md是否存在、行数是否 ≥ 150（防止模板被整段裁剪）
模板占位符（[YOUR PROJECT…等哨兵串）是否还残留——残留说明没做定制
严格代理（含 5 个评审门 + wcag-a11y-gate 等）是否齐全
专家代理数量 ≥ 3、领域规则条数 ≥ 5
钩子、内存工具、.gitignore隐私加固是否就位

退出码：0全部 error 级检查通过；1存在失败项；2无法运行（项目根没有 AGENTS.md）。

实战建议：推荐的脚本执行顺序

给新手一条最省心的工作流 🧭：

首次集成：integrate.py --dry-run预览 → 去掉 dry-run 正式执行
验收：verify_integration.py --quiet，按 FIX 提示补齐人工项
加装专家：install_extras.py --list --role engineering预览，确认后正式安装
日常升级：pack 更新后跑upgrade.py --diff预览 →--apply落盘，出问题--rollback

四个脚本都支持--json，可以互相串联成自动化流水线；它们共同的"环境护栏"（Python 版本过低时给出安装指引）也保证了在不同系统上的行为一致。原生 Windows 下把python3换成py -3即可（源码：install.sh 与脚本头部注释均有说明）。

资料	路径
快速上手指南（中文用户也适用）	GUIDE_EN.md
交给 AI 执行的一键集成提示词	integration-prompt.md
代理目录路由表	agents/index.json
代理 Frontmatter 规范	agents/SCHEMA.md
供应链清单	MANIFEST.sha256
集成/升级端到端测试（90+ 断言）	agents/scripts/test_integrate_deintegrate.sh
升级快照与回滚测试	agents/scripts/test_upgrade.sh
脚本完整性体检	agents/scripts/check_pack_health.py

Harmonist核心脚本API参考：10分钟掌握integrate/upgrade/install_extras/verify完整清单