企业官网建设流程全解析

Harmonist贡献指南：如何添加自定义AI智能体并参与协议强制改进

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

Harmonist 是一个可移植的 AI 智能体编排框架，核心特色是用 IDE 钩子实现机械式协议强制（mechanical protocol enforcement）——186+ 个智能体、零运行时依赖。想贡献一个自定义 AI 智能体，或参与协议强制层的改进？本文是一份面向新手的完整贡献指南，带你从阅读规范到提交 PR 一次走完。

1. 开始之前：先读懂三份核心文档

Harmonist 对合并标准刻意严格，因为这里的每一处改动都会影响所有集成它的项目。动代码之前，请先通读这三份文档：

三条入门铁律 📌：

1. 阅读并同意 CODE_OF_CONDUCT.md；
2. 非平凡工作（新智能体、新脚本、行为变更、钩子变更）必须先开 issue描述计划，避免白做；
3. 纯装饰性改动（如批量改措辞、去掉 emoji）会被直接关闭——只做有内容驱动的修改。

2. 最快配置方法：5分钟搭好贡献环境

Harmonist 零依赖，只需 Python 3.9+（纯标准库，无需 pip 安装任何东西）：

git clone https://gitcode.com/gh_mirrors/ha/harmonist cd harmonist

克隆完成后，随手跑两个命令确认环境健康：

python3 agents/scripts/lint_agents.py # 校验全部智能体，要求 0 错误 python3 agents/scripts/check_pack_health.py # 19 项体检检查

两条命令都通过，说明你的工具链与仓库基线一致，可以放心开工。

3. 如何添加自定义AI智能体：5步完整流程

这是最常见的贡献类型。整个流程可以概括为：选目录 → 套模板 → 过 linter → 加标记 → 重建索引。

3.1 选择正确的分类目录

智能体统一放在agents/<category>/<slug>.md。分类是固定枚举（见 agents/SCHEMA.md），共 16 类，例如engineering、review、marketing、game-development、specialized等。除非有充分理由，不要提议新分类。

3.2 从官方轻量模板起步

直接复制 agents/STYLE.md 第 4 节的"轻量 persona 模板"，填写 frontmatter 即可。必选字段一张表看懂：

文件名即slug（身份键）：小写、kebab-case、全库唯一，例如可参考现有的 agents/review/qa-verifier.md。

3.3 运行 linter 校验

写完后第一件事就是过 linter，要求 0 错误：

python3 agents/scripts/lint_agents.py

它会检查：frontmatter 首行是否为---、必选字段齐全、category与目录匹配、slug 命名与唯一性、tags非空、正文不少于 50 词等（完整清单见 agents/SCHEMA.md 的 Linter 一节）。

3.4 长正文加 Deep Reference 标记

如果正文超过约 80 行非空行，必须加## Deep Reference切分标记——--thin精简转换器依赖它来裁剪上下文：

python3 agents/scripts/insert_deep_ref_marker.py agents/<分类>/<slug>.md

3.5 重新生成路由索引与清单

新智能体必须进入路由表和供应链清单才能被编排器发现，也才能通过健康检查：

python3 agents/scripts/build_index.py # 重建 agents/index.json python3 agents/scripts/build_manifest.py # 重建 MANIFEST.sha256

两个生成文件必须随 PR 一起提交。

4. 智能体正文怎么写：风格红线与好范式

STYLE.md 总结了历史审计中发现的高频反模式，新智能体从第一天就要避开：

• ❌ "Personality / Memory / Experience" 人设秀——模型不会跨调用"记忆"，删掉；
• ❌ "world-class"、"senior" 等形容词堆砌——换成可验证的约束，如"按 OWASP Top 10 审查每个 diff"；
• ❌ emoji 标题（如## 🎯 Your Core Mission）——用纯 ASCII 标题：## Core Mission、## Critical Rules；
• ❌ "跨智能体协作清单"——路由由编排器经 index.json 完成，协作关系写在distinguishes_from+disambiguation里。

好的正文只包含：一行身份、可证伪的使命、3–8 条对应真实失败模式的规则、结构化输出契约。正文超过 80 行时把参考资料沉到## Deep Reference之后。

5. 参与协议强制改进：钩子修改的硬性要求

Harmonist 的差异化在于 hooks/ 中的六个钩子阶段（sessionStart、afterFileEdit、subagentStart、subagentStop、beforeShellExecution、stop）——stop钩子是那道"机械闸门"：审核智能体没跑、记忆没更新，就拒绝让这一轮结束。

改进强制层必须遵守：

1. 每次脚本改动都要通过三套测试：

python3 agents/scripts/check_pack_health.py # 19 项检查 bash hooks/tests/run-hook-tests.sh # 30+ 个钩子场景 bash memory/tests/run-memory-tests.sh # 29 个记忆场景

2. 任何新行为都要在对应的test_*.sh（agents/scripts/ 或 hooks/tests/）中补一条匹配的用例；
3. Python 脚本必须保持 3.9+ 版本守卫，且严禁引入第三方依赖——整个包纯标准库是设计原则。

6. 提交前检查：Pull Request 七项清单

来自 CONTRIBUTING.md 的官方清单，逐项打勾再提交：

• lint_agents.py0 错误
• check_pack_health.py19/19 通过
• 相关测试套件全部通过
• 索引与 manifest 已重新生成并提交
• 用户可见行为变化：更新了 CHANGELOG.md
• Schema 变化：版本号递增 + 迁移器同步更新
• PR 描述解释了why（为什么），而不只是 what

7. 维护者会拒绝哪些 PR（避坑清单）

提前知道红线，能省下大量往返时间 🚫：

• 绕过、禁用或削弱强制层（qa-verifier、hooks、memory 校验器）且未先经评审讨论；
• 修改已发布的 agents/review/ 或 agents/orchestration/ 严格行为，除非精确限定在所修问题范围内；
• 提交构建产物（转换后的智能体文件、生成文档）——这些由convert.sh本地生成且被 gitignore；
• 单个 PR 里批量重排整个人设目录——每个分类单独开 PR，并附改前/改后 lint 输出；
• 添加任何第三方 Python 依赖。

另请注意：安全相关 bug 不要在公开 issue 讨论，按 SECURITY.md 提交私有安全通告；普通 bug 则要先能复现、先补失败测试再修。

写在最后

Harmonist 的贡献哲学一句话：先对齐、再动手、用测试说话。无论你是想新增一个垂直领域智能体，还是给stop闸门加一道新检查，只要按本文流程走——先开 issue、遵守 Schema v2 与风格红线、三套测试全绿——你的改动就会是这个"零依赖协议强制"生态里扎实的一块砖。🧱

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