HelloAGENTS是一款为 AI 编程 CLI（Claude Code、Gemini CLI、Codex CLI）添加智能工作流层的自主高级智能伙伴。它不仅能分析问题，更能持续工作直到完成实现与验证。本文带你完整了解 HelloAGENTS 的测试体系与开发指南：数十个测试文件如何覆盖install、update、cleanup、uninstall、doctor等安装生命周期的每一步，如何一键运行全部测试，以及如何上手参与贡献。

一、为什么"安装生命周期"需要大量测试

HelloAGENTS 会向多个宿主 CLI 写入受管理的配置文件（如CLAUDE.md、settings.json、config.toml、hooks.json），并支持standby/global两种模式、分支切换、更新与卸载。任何一步写错，都可能污染用户本机的配置。

因此项目在 tests/ 目录下构建了一套分层测试体系，用 Node 内置测试运行器node --test驱动，目标非常明确：

• ✅ 安装、更新、清理、卸载全流程可重复、可回滚
• ✅ 宿主配置写入后能被doctor正确体检
• ✅ 运行时门禁（guard / delivery gate / stop gate）行为稳定
• ✅ macOS / Linux / Windows PowerShell 多平台行为一致

下图直观对比了"没有 HelloAGENTS"与"加持后"的差异——Agent 从"给完建议就停下"，变成"持续工作直到完成"：

而这套"持续工作直到完成"的端到端体验，正是安装生命周期 + 运行时门禁测试所要守护的核心承诺。

二、一键运行全部测试：npm test

在 package.json 中，测试入口只有一行：

"test": "node --test"

在项目根目录执行即可全量运行：

npm test

得益于node --test的约定式发现机制（自动匹配*.test.mjs），你无需引入额外测试框架。

2.1 测试如何做到"干净隔离"

测试不会污染真实用户目录。脚手架 tests/helpers/test-env.mjs 提供了关键能力：

• createPackageFixture()：把包文件拷贝到临时目录，模拟"已安装的包"
• createHomeFixture()：创建包含.claude/.gemini/.codex的伪 HOME
• 进程退出时自动清理所有临时目录

配合 tests/helpers/cli-test-helpers.mjs 的seedHostConfigs()，测试会先注入用户自定义配置，再验证 HelloAGENTS 写入后不破坏这些配置——这正是安装生命周期最核心的稳定性诉求。

三、安装生命周期测试：三大支柱

3.1 全链路安装生命周期

install-lifecycle-all.test.mjs 覆盖standby → global → update → cleanup完整链路，验证：

• postinstall正确初始化~/.helloagents/helloagents.json
• install --all --standby正确写入CLAUDE.md、settings.json与符号链接
• --global模式切换后宿主 symlink 被正确移除
• 受管理标记（HELLOAGENTS_START）与时间戳备份（*.bak）行为正确

针对单个宿主，还有 install-lifecycle-scoped.test.mjs 与 install-lifecycle-codex.test.mjs 做更细粒度的断言。

3.2 doctor 健康体检

doctor.test.mjs 验证helloagents doctor codex --json能正确报告ok/standby状态、检测配置漂移（drift），并输出干净的 JSON，且不产生 NodeDEP0190弃用警告。

3.3 一键脚本与跨平台

install-wrapper-shell.test.mjs 与 install-wrapper-powershell.test.mjs 分别验证 install.sh 和 install.ps1 对HELLOAGENTS=target[:mode]的路由规则，确保 shell 与 PowerShell 两条一次性脚本路径行为一致。

四、运行时与门禁测试：让"完成"有据可依

安装只是起点，HelloAGENTS 真正的价值在于运行时交付门禁，对应 scripts/ 下的一众运行时脚本：

这些测试通过 tests/helpers/runtime-test-helpers.mjs 构造运行时上下文，断言每个门禁在"通过 / 拦截"两种路径下都给出可操作的动作指引。

五、开发指南：如何上手贡献

5.1 仓库关键入口速查

5.2 提交信息规范

遵循 CONTRIBUTING.md 中的 Conventional Commits 约定：

feat: 新功能 fix: 修复 bug docs: 仅文档 refactor: 代码重构 test: 新增 / 修改测试

5.3 本地开发三步走

1. 执行npm test，确认基线全绿
2. 修改 scripts/ 或 cli.mjs 后，优先补充 tests/ 中对应的测试
3. 遵循"跟随现有代码风格 + 为复杂逻辑加注释 + 必要时更新文档"的原则

💡 提示：测试全程在临时目录中运行，不会修改你真实的~/.claude/~/.codex/~/.gemini，可放心反复执行。

六、小结：测试即承诺

HelloAGENTS 用一套分层测试把"安装生命周期 + 运行时门禁 + 跨平台脚本"三件事钉死：

• 🧪npm test一键全量运行
• 🧱 脚手架保证隔离、可重复
• 📋 生命周期 / doctor / 运行时三大支柱各司其职

理解这套测试体系，就是你从"使用 HelloAGENTS"走向"贡献 HelloAGENTS"的最短路径。