mu-zi-lee / hitl-dev-loop

# hitl-dev-loop
**面向 Claude Code + 编码 Agent（默认 Codex CLI）的人机协作（Human-in-the-Loop）开发循环。**
Claude 担任主 Agent：理解需求、调研、拆解任务，把编码派给在独立 git worktree 中运行的编码 Agent，审查改动、集成、构建，然后提醒你验收。你只需要体验真实的软件，用大白话或截图反馈，并决定产品方向和发布。
v0.2 起，**可靠性由调度脚本保证，而不是靠提示词**：任务有持久化状态和锁；反馈送达有确认；「完成」由调度器独立判定并验证；集成和构建都有绑定到 commit SHA 的门禁；每一步都有超时、熔断和预算。
这不是无人监督的自动编程，而是一个把你的反馈不断变成「已验证的改动」、同时由你掌握方向的开发循环。
## 包含什么
| 路径 | 说明 |
|---|---|
| `skills/hitl-dev-loop/SKILL.md` | Claude 遵循的流程：首次接入、需求分析、派发、审查、集成、授权边界、任务队列、Token 管理。 |
| `skills/hitl-dev-loop/scripts/` | 调度脚本（兼容 macOS 自带的 bash 3.2），见下表。 |
| `skills/hitl-dev-loop/scripts/adapters/codex.sh` | Codex CLI 适配器（`exec --json --output-schema`）。实现同样的接口即可接入其他编码 Agent。 |
| `skills/hitl-dev-loop/templates/` | `AGENTS.md`、`CLAUDE.md`、`TASKS.md`、`DECISIONS.md`、共用规则、任务说明模板、报告 JSON Schema。 |
| `agents/repo-maintainer.md` | 低成本、只读的子 Agent：整理 GitHub Issue / PR，汇报需要决策的事项。 |
| `PROTOCOL.md` | 与具体工具无关的协议：角色、产物、报告格式、状态机、完成规则、门禁、适配器接口。 |
| `tests/` | 用模拟 Codex 的自动化测试（21 个场景），CI 在 ubuntu 和 macOS 上运行。 |
## 工作原理
 [code] 
### 脚本一览
| 脚本 | 作用 |
|---|---|
| `init.sh` | 每个仓库运行一次（可重复运行）：创建 `.agent-loop/`、共用规则、集成分支，检查 Agent 是否可用。 |
| `new-task.sh [--scope 'glob'] [--network] [--base 引用]` | 创建 worktree、分支、任务状态和任务说明。默认**不开网络**。 |
| `dispatch.sh [--detach]` | 检查任务说明、Agent 可用性、并发上限、文件重叠，然后开始/继续运行。 |
| `drive.sh ` | 调度循环本身（dispatch 会调用）。 |
| `feedback.sh "文字"` | 给任务追加反馈；只有在一轮成功后才确认送达，失败会重发。 |
| `verify.sh ` | 调度器自己在任务 worktree 里运行 `AGENT_VERIFY_CMD`，结果绑定当前 commit。 |
| `review.sh approve\|changes "说明"` | 记录审查结论（绑定 SHA）；`changes` 会转成反馈。 |
| `integrate.sh ` | 门禁检查后在集成 worktree 合并，再验证，失败回滚；冲突时停下并说明。 |
| `ship.sh` | 只构建/安装已验证的集成 SHA（运行 `AGENT_SHIP_CMD`）。 |
| `status.sh [--json\|--markdown\|--sync TASKS.md]` | 所有任务的状态、轮数、token、验证、审查、待送达反馈；能识别进程已死的「stalled」任务。 |
| `report.sh ` | 单个任务的 Markdown 报告（改动文件、Agent 报告、验证日志）。 |
| `conflicts.sh [名称]` | 检测任务之间的文件重叠，并用 `git merge-tree` 预测与集成分支的冲突。 |
| `stop.sh ` | 停止任务（整个进程树），保留已改内容和未送达的反馈。 |
| `alert.sh "消息"` | 重复提示音直到你点停止（macOS 需在沙箱外运行；Linux 用 notify-send）。 |
## 安装
需要：Claude Code、Codex CLI（或 Codex 桌面端自带的 CLI）、git ≥ 2.31、bash、python3（或 jq）。可选：`gh`（GitHub 维护）、git ≥ 2.38（冲突预测）。
作为插件安装（技能 + 子 Agent）：
 [code] 
或者只复制技能：
 [code] 
## 使用
在你的项目里启动 Claude Code，直接说：
> 用 hitl-dev-loop 的方式开发这个项目。先检查项目状态，告诉我需要做哪些最小改动。
Claude 会先汇报情况，等你同意后再建立 `AGENTS.md`、`CLAUDE.md`、任务队列和决策记录，运行 `init.sh`，并在 `.agent-loop/config.sh` 里配置验证命令。之后你只要描述问题（「这个页面太窄了」「打开是白屏」+ 截图），Claude 会写任务说明、派发、审查、集成，做完叫你来试。
也可以手动使用：
 [code] 
### 配置（`.agent-loop/config.sh`，自动加入 git 忽略）
| 变量 | 默认 | 作用 |
|---|---|---|
| `AGENT_VERIFY_CMD` | 空 | 调度器独立运行的完整验证。不设置时任务停在 `needs-review`。 |
| `AGENT_SHIP_CMD` | 空 | 构建并安装产品以便你验收（在集成 worktree 中运行，可用 `$SHIP_SHA`）。 |
| `AGENT_COMMITS` | `scheduler` | 由调度器提交（Agent 无法写 git 元数据）；设为 `agent` 则由 Agent 自己提交。 |
| `DEFAULT_NETWORK` | `0` | 新任务的网络权限；单个任务用 `--network` 开启。 |
| `MAX_PARALLEL` / `MAX_ROUNDS` | 3 / 15 | 并行任务数 / 每次运行的最大轮数。 |
| `MAX_FAILS` / `MAX_VERIFY_FAILS` | 3 / 3 | 连续 Agent 失败 / 验证失败的熔断阈值。 |
| `ROUND_TIMEOUT` / `VERIFY_TIMEOUT` | 3600 | 单轮 / 单次验证的超时（秒）。 |
|