gnhf – 开源的 AI Agent 自主编排器，夜间自主迭代

gnhf – 开源的 AI Agent 自主编排器，夜间自主迭代

gnhf，全称为 good night， have fun，是一款开创性的开源 AI Agent 自主编排工具。它的核心理念在于赋予开发者一种全新的工作模式：在夜幕降临前，为 AI 设定一个明确的目标，然后安心休息，让 Agent 在你熟睡期间不间断地进行迭代式工作。每一次迭代都只专注于一项微小的改动，一旦成功，便会自动执行 git commit；若不幸失败，则会立即执行 git reset --hard 进行回滚。当您次日醒来，您的代码仓库分支上将充斥着整洁有序的提交记录以及详尽的工作日志。

gnhf 究竟是何方神圣

gnhf（即 good night， have fun）是一款开源的 AI Agent 自主编排器，其核心理念是让开发者在睡前为 AI 设定一个清晰的目标，使其在您休息期间持续进行迭代式工作。每次仅进行一次微小的改动，成功则自动执行 git commit，失败则通过 git reset --hard 进行回滚。当您醒来时，您的仓库分支上已堆满了干净的提交记录与完整的操作日志。它原生支持 Claude Code、Codex、GitHub Copilot CLI 等主流 AI 编程助手，并具备跨迭代记忆共享、断点续跑、多任务 worktree 并行以及实时 token 监控等强大功能。您可以通过 npm 一键安装，它支持跨平台运行，并根据 MIT 协议在 GitHub 上开源。

gnhf 的卓越功能一览

• 自主夜间迭代：您只需在睡前为 AI 设定一个开发目标，Agent 便会在您休息时自动循环执行任务，每一次仅进行一项细微的改动。醒来时，您便能看到完整的成果。
• Git 严谨驱动：每一次成功的迭代都会自动生成的 git commit 记录，而失败的迭代则会立即执行 git reset --hard 回滚，从而确保您的分支历史干净且可追溯。
• 智能容错与重试机制：Agent 报告的失败会被纳入下一轮迭代，硬性错误会采用指数退避策略，而永久性错误（如 API 余额不足）则会立即中止任务并输出日志路径。连续三次失败后，任务将自动停止。
• 跨迭代记忆共享：Agent 通过 notes.md 文件在多轮迭代之间传递上下文信息和经验教训，从而实现知识的持续积累，而非每次都从零开始。
• Worktree 并行处理：在同一仓库中，您可以同时启动多个 gnhf 任务，每个任务拥有的运行目录和分支，彼此之间互不干扰。这非常适合并行推进多项技术债务的清理工作。
• 断点续跑能力：在已有的 gnhf/ 分支上重新运行命令，工具能够自动恢复之前的任务进度，无需从头开始。
• 实时状态监控：在交互式运行时，终端的标题栏会实时显示当前任务状态、累计的 token 消耗量以及已提交的 commit 数量，方便您随时掌握进展情况。
• 防休眠机制：在运行期间，工具会自动阻止系统进入休眠状态。在 macOS 上使用 caffeinate，在 Linux 上使用 systemd-inhibit，而在 Windows 上则采用 PowerShell 的原生方案。
• 多 Agent 原生支持：该工具开箱即用，支持 Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 等六种主流 AI 编程助手，您可以通过配置文件自定义路径和参数。
• 灵活的运行时控制：支持使用 --max-iterations 参数限制迭代次数，--max-tokens 参数限制 token 总量，以及 --stop-when 参数设定自然语言停止条件。
• 零侵入式集成：所有操作都仅在自动创建的 gnhf/ 分支上进行，您的主分支将完全不受影响。在 worktree 模式下，甚至不会污染原仓库的工作区。

如何驾驭 gnhf

• 安装部署流程：您可以通过 npm install -g gnhf 命令进行全局安装。或者，您可以从 GitHub 仓库克隆源码，然后执行 npm install && npm run build && npm link 进行本地构建。
• 基础启动方式：在目标仓库的根目录下运行 gnhf "您的开发目标"。例如，您可以输入 gnhf "reduce complexity of the codebase without changing functionality"。工具会自动创建一个 gnhf/ 分支并开始迭代。
• 限制迭代规模：使用 --max-iterations 10 来设定最大迭代次数，或使用 --max-tokens 5000000 来设定 token 消耗的上限，以避免资源失控。
• 设定自然语言停止条件：通过 --stop-when "所有测试通过"，您可以让 Agent 在满足特定条件时自动结束任务。
• 断点续跑操作：在已有的 gnhf/ 分支上重新运行 gnhf 命令，并选择继续历史任务，即可恢复之前的进度，无需从头开始。
• 多任务并行执行：使用 gnhf --worktree "任务A" & 和 gnhf --worktree "任务B" & 命令，可以在同一仓库中同时启动多个 Agent，每个 Agent 都拥有的工作目录和分支。
• 自定义 Agent 配置：编辑 ~/.gnhf/config.yml 文件，您可以设置默认的 Agent（例如 claude、codex、copilot 等）、防休眠开关、自定义二进制路径以及额外的 CLI 参数。
• 查看运行日志：所有运行的元数据都保存在 .gnhf/runs/ 目录下，其中包含了每次迭代的完整输入输出信息，便于进行审计和问题排查。
• 安全中止方式：在运行期间，您可以随时按下 Ctrl+C 来停止任务，或者等待其达到配置的上限后自动结束。连续三次失败后，任务也会自动中止并提示日志路径。

gnhf 的官方网站地址

• Github 仓库链接：https://github.com/kunchenguid/gnhf

gnhf 的关键信息与使用前提

• 项目全称：gnhf，即 good night， have fun，由开发者 kunchenguid 倾力打造并开源。
• 技术栈基础：基于 TypeScript / Node.js 开发，并将 Git 作为其核心的版本控制底层支撑。
• 平台兼容性：全面支持 macOS、Linux 和 Windows 这三大主流操作系统。
• 社区反响：上线仅约两周，便已收获超过 550 个 GitHub Star，并吸引了 73 个活跃的 PR 贡献。
• 核心理念阐述：其核心理念在于，开发者只需在睡前向 AI 设定一个开发目标，AI 便能在您休息期间持续进行迭代式工作；每一次仅进行一次微小的改动，成功则自动执行 git commit，失败则执行 git reset --hard 进行回滚。
• 原生支持的 Agent 列表：原生支持 Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 共计六种主流 AI 编程助手。
• 分支隔离机制详述：所有操作均在自动创建的 gnhf/<slug> 分支上执行，确保主分支的原始状态不受任何干扰；同时支持 worktree 模式，为每个任务提供的运行目录。
• 配置与日志存储位置：运行时配置信息保存在 ~/.gnhf/config.yml 文件中，而运行日志及元数据则存储在仓库内的 .gnhf/runs/ 目录下。

• 环境配置要求：您的系统需要预先安装 Node.js 和 npm。此外，目标项目必须是一个 Git 仓库，因为 gnhf 依赖 Git 来执行 commit 和回滚操作。
• Agent 前置条件说明：您需要先在本地环境中安装并配置至少一种支持的 AI 编程助手（例如 Claude Code、Codex 等），并确保其对应的 CLI 命令能够在系统的 PATH 环境变量中被找到和执行。
• API 资源准备建议：如果您使用云端 Agent（如 Claude Code、Codex），请务必确保您的 API 账户拥有足够的余额，否则 Agent 会被识别为永久性错误并立即中止任务。
• 权限要求说明：运行 gnhf 的目录需要当前用户拥有写入权限，以便能够创建 gnhf/ 分支、.gnhf/ 日志目录以及 notes.md 记忆文件。
• 防休眠功能依赖项：在 macOS 系统上，需要支持 caffeinate 命令；在 Linux 系统上，需要 systemd-inhibit；在 Windows 系统上，则依赖 PowerShell。如果缺少对应的工具，防休眠功能将静默失效。
• 配置初始化建议：为了避免每次命令行都手动指定，建议在首次使用前编辑 ~/.gnhf/config.yml 文件，明确指定默认的 Agent 和您偏好的参数设置。
• 运行监控提示：建议通过终端标题栏的实时信息，或使用 --max-tokens / --max-iterations 参数设定资源使用上限，以防止在夜间 token 消耗失控。
• 安全退出指南：在运行过程中，您可以随时按下 Ctrl+C 来中断任务，或者等待其达到设定的阈值后自动结束。此外，连续三次失败也会触发自动中止机制。异常退出后，您可以根据日志路径 .gnhf/runs/ 来排查具体原因。

gnhf 的核心优势所在

• 夜间自主迭代，解放开发者时间：在您入睡前布置好任务，AI 将在您休息时不知疲倦地持续工作。当您醒来时，即可直接验收成果，将“碎片时间”和“睡眠时段”转化为宝贵的开发产能。
• Git 纪律原生集成：每一次成功的代码改动都会被自动 git commit，而任何失败的操作则会被立即 git reset --hard 回滚。这使得在无需人工审查的情况下，您就能保证分支历史的整洁、可审计性，并随时能够回退到之前的状态。
• 零侵入式隔离设计：所有操作都被严格限制在自动创建的 gnhf/ 分支内，您的主分支将保持完全，不受任何影响。而 --worktree 模式更是为每个任务开辟了的运行目录，实现了物理级别的隔离。
• 多 Agent 切换与扩展：原生支持 Claude Code、Codex、GitHub Copilot CLI、Rovo Dev、OpenCode、Pi 这六种主流工具，不与任何单一厂商绑定。您可以通过配置文件无缝切换 Agent，甚至可以自定义扩展支持新的工具。
• 生产级容错与成本控制：连续三次任务失败将自动中止，API 余额不足等永久性错误会立即退出。结合 --max-tokens 和 --max-iterations 等硬性上限设置，有效防止夜间资源消耗失控。
• 断点续跑，进度永不丢失：在已有的 gnhf/ 分支上重新执行命令，即可无缝恢复之前的任务进度，无需从零开始。这对于长周期、复杂目标的持续攻坚尤为重要。
• 跨迭代记忆积累机制：通过 notes.md 文件，Agent 可以在多轮迭代之间传递上下文信息和失败的教训。这使得 Agent 越跑越“聪明”，而非每次都从零开始摸索。
• 同仓库多任务并行处理：--worktree 功能支持在同一项目中同时推进多项技术债务（例如，一个 Agent 负责补充测试，另一个 Agent 负责代码重构），它们互不干扰，从而成倍提升工作效率。
• 自然语言级运行控制能力：--stop-when 参数允许您用日常的语言描述停止条件（如“所有测试通过”），无需编写复杂的脚本即可精确地控制任务的边界。
• 跨平台开箱即用体验：支持 macOS、Linux、Windows 等主流操作系统，并能自动适配各平台的防休眠机制。只需一条 npm install -g gnhf 命令即可完成所有部署工作。

gnhf 的典型应用场景

• 测试覆盖率补齐任务：针对遗留模块或新开发的功能，自动补充单元测试和集成测试。利用夜间时间，将代码覆盖率从 60% 提升到 90%，而无需占用白天宝贵的编码时间。
• 新功能渐进式实现：将大型需求分解为一系列小目标（例如，“实现用户认证中间件”）。让 Agent 在夜间逐步迭代，每一步成功即提交，失败则自动回滚。第二天，您只需验收并合并即可。
• 多模块并行攻坚策略：在同一个项目中，同时启动多个 worktree 任务。例如，一个 Agent 负责补充测试，一个 Agent 负责代码重构，还有一个 Agent 负责升级依赖项。这些任务互不干扰，可以并行推进，大大提高效率。
• 开源项目日常维护工作：自动处理标记为“good first issue”的简单重构、文档更新、依赖版本升级等任务。维护者第二天只需审查和合并 PR 即可。
• API 层重构与迁移操作：在夜间自动完成接口参数调整、废弃方法替换、响应格式统一等低风险但耗时的机械性改动。这可以最大程度地降低对白天业务开发进度的干扰。
• 代码风格与 Lint 治理：批量修复 ESLint/Prettier 的警告信息，统一命名规范，移除未使用的变量。从而长期保持代码库的整洁，而无需占用核心开发精力。