loop-skill：写好 loop，让 agent 夜里无人值守地干活

---

项目地址：handsomestWei/loop-skill

---

loop-skill 是一个可移植的 Agent Skill + 轻量 Python 运行时：把书面推进计划变成 计划驱动、无人值守的多 agent 闭环——按 发现 → 规划 → 执行 → 验收 → 迭代 调度 Claude Code、Codex、OpenCode、Gemini CLI、Trae CLI 等；任务清空后 自动再规划下一阶段，本地 Web 看板实时盯多仓进度。会话可恢复，关机不丢上下文。欢迎 Star ⭐，Issue / PR 也欢迎。

---

从「每轮 prompt」到 loop engineering

很多人用 AI 写代码，仍停留在 一问一答、每轮手动 prompt。当任务变长、多仓库并行时，人会变成瓶颈：反复拆任务、催进度、等 CLI 跑完。

2026 年 6 月，Boris Cherny（Anthropic，Claude Code 负责人）在 Acquired 播客里提出了一种转变：

「我已经不 prompt Claude 了。我写 loop，让 loop 去 prompt Claude、决定做什么。我的工作是写 loop。」

社区把这类做法称为 loop engineering（Addy Osmani 等整理）：开发者从「对话者」变成「循环设计者」——定义发现、规划、执行、验收、迭代的规则，让 agent 在规则内自驱运转。

loop-skill 就是把这套思想做成可安装、可跑的技能包：不是又一个绑死 GitHub Issue 的重型框架，而是 SKILL.md + 几百行 Python 运行时 + 本地看板，放进 Cursor / Claude Code 就能用。

---

它是什么

要点	说明
形态	可移植 SKILL.md + core/ 轻量运行时（标准库为主，可选 PyYAML）
任务来源	书面推进计划（推荐各仓 docs/loop-plan.md），主控通读 README / docs 后写出
工作流	五阶段：发现 → 规划 → 执行 → 验收 → 迭代，默认 无轮数上限 自驱闭环
主控 vs 执行	Cursor / Claude Code 等 当指挥者（写计划、启停 loop）；CLI 当执行者 / 再规划者
多仓	默认并行：每仓同时各跑 1 个 CLI 任务，看板先于 loop 启动
看板	本地 Web（默认 http://127.0.0.1:8765/），多角色头像、任务状态、blocked 高亮
持久化	进度落在 workspace/，聊天结束、关机重启均可 继续 loop-skill 恢复

与客户端无关：把 loop-skill/ 目录放进任何能读 SKILL.md 并执行 shell 的主机 agent 即可。

---

运行效果

和典型多 agent 编排器有何不同

维度	典型编排器	loop-skill
形态	npm 包 / 重型框架	Skill + 轻量 Python 运行时
任务来源	GitHub Issue / PR	推进计划 Markdown
歧义处理	agent 反问、易卡住	references/decisions-guide.md 政策引擎 提前写死答案
验收	CI 全绿	verify_mode（默认 dev-first，可按仓覆盖）
客户端	单一产品	任意支持 Skill 的 agent
Provider	单一 agent	可插拔 CLI 适配层（providers/）
规划闭环	人工反复拆任务	首轮主控写计划 + 之后自动再规划（默认开启）
多仓执行	常串行或单仓	默认并行，fleet_parallel_max=0 表示全仓同时派发
看板	桌面应用或 SaaS	本地实时 Web，读 workspace/state/

---

五阶段循环在干什么

发现（discover / scan）
  → 规划（主控写 docs/loop-plan.md；之后由 planner 自动追加）
  → 执行（loop 派发 CLI 到业务仓改代码）
  → 验收（verify_mode：dev-first / tests / strict）
  → 迭代（任务清空 → 自动再规划 → ingest → 继续）

首轮规划是「开环」：主控 agent 扫描仓库内 Markdown，理解需求后写入推进计划。
之后是「闭环」：loop 后台常驻，按间隔轮询派发；某仓 pending / running 清空后，同一 CLI 担任 planner，把下一阶段任务追加进 docs/loop-plan.md，再 ingest 继续——直到某轮 未新增任何任务（判定无有价值下一步）为止。

已完成任务的 status、session_id 在 re-ingest 时 保留，不会把已验收任务重跑一遍。

---

角色分工：你只说话，主控干活

角色	谁来做	做什么
你	开发者	说意图、审看板、必要时改业务仓设计 / 需求文档
主控	Cursor、Claude Code、Codex CLI 等	discover → scan → 写各仓 docs/loop-plan.md → ingest → up
执行者	claude / codex / opencode 等	loop 自动派发，在业务仓写实现代码
再规划者	默认同 default_provider CLI	某仓任务全部完成后，自动追加下一阶段计划

推进计划里的任务可带 角色 列，推荐混用 architect / coder / verifier / reviewer（见 references/role-guide.md），让不同「人格」分工，而不是清一色 generic worker。

主控协议要点（SKILL.md 约定）：

• 禁止让用户手写 loop.json / loop.yaml 或逐步确认
• 禁止主控代替 CLI 在业务仓写实现（除非用户明确只要主控、不用 loop）
• 禁止用同步 dispatch 对每仓「试跑」——4 仓会阻塞 4 次长等待；应 ingest → up 后台跑

---

推进计划长什么样

主控在各业务仓写入 docs/loop-plan.md（也兼容 docs/推进计划.md 等，ingest 会合并 Markdown 中的任务表）。

推荐表格格式（五列）：

| ID | 任务 | 验收 | 角色 | 状态 |
|----|------|------|------|------|
| P1-01 | 实现用户登录 API | `pytest tests/test_auth.py` 通过 | coder | pending |
| P1-02 | 评审登录模块安全边界 | 无硬编码密钥、有 rate limit | reviewer | pending |

• ID：P1-01 这类可追踪编号
• 验收：写清怎样算完成，供 verify_mode 与 verifier 角色使用
• 状态：loop 运行后会更新为 running / done / blocked 等

你 不需要 事先准备好这份文件——首次启动时主控会通读仓库自动生成；你改设计后说一句「重新扫描并更新推进计划」即可刷新。

---

三分钟上手（自然语言即可）

1. 准备环境

git clone https://github.com/handsomestWei/loop-skill.git
cd loop-skill
python -m core.cli doctor claude    # 检查 PATH 里有哪些 CLI 可用
pip install -r requirements.txt     # 可选，仅 loop.yaml 需要 PyYAML

将 loop-skill/ 作为 Agent Skill 挂载到 Cursor / Claude Code（复制到技能目录或按宿主文档引用 SKILL.md）。

2. 一句话启动

在主机 agent 里说：

用 loop-skill 推进 D:/my-vibe-project 下的项目，Claude 执行，后台常驻。

主控在同一轮内大致会执行：discover → scan → 为每个子仓写 docs/loop-plan.md → ingest → up --interval 300，并回报看板地址。

3. 常用场景提示语

场景	你可以这样说
首次启动	「用 loop-skill 推进某目录下的项目，Claude 执行，后台常驻。」
只看进度	「打开 loop-skill 看板。」 / 「推进看板地址是多少？」
暂停后台	「停掉 loop-skill。」 / 「down 掉 loop。」
关机后继续	「继续 loop-skill，恢复后台 loop。」
计划跑完	默认 无需操作——loop 会自动再规划；要改方向可说「重新扫描各仓、更新推进计划并继续跑」
改了设计	「我更新了 xxx 的需求，请重新扫描、更新推进计划并 ingest，再继续跑。」
新增子仓库	「某目录下新加了 xxx 项目，纳入 loop-skill。」
移除某仓编排	「从 loop-skill 工作区移除 xxx 的推进计划（不删开发仓库）。」需二次确认
任务 blocked	默认 loop 交 planner 补 decision / 拆细任务，自动重试至多 2 次；看板高亮仍须人工项
关闭自动再规划	「loop-skill 关闭自动再规划，跑完当前计划就停。」（--no-auto-replan）
换执行 CLI	「loop-skill 改用 Codex 执行。」

---

支持的 Provider（可插拔 CLI）

providers/ 目录定义各 CLI 的适配规格，运行时通过 doctor 检测本机可用项：

Provider	典型 CLI	说明
Claude	claude	Claude Code CLI
Codex	codex	OpenAI Codex CLI
OpenCode	opencode	OpenCode agent
Gemini	gemini	Gemini CLI
Trae	trae-cli	Trae CLI

Windows 上 npm 全局 CLI 多为 .cmd shim，运行时已做 PATH 解析。至少一个 [ok] 即可启动。

---

验收模式：verify_mode

不同仓库可覆盖默认验收策略：

模式	含义
dev-first	默认，偏开发阶段快速验收
tests	强调测试通过
strict	更严格验收

写在 loop.yaml / loop.json 或按仓覆盖，详见 references/worker-contract.md。

---

状态落在哪（为何能恢复）

文件 / 目录	内容
loop.json	多仓登记与任务定义（自动生成，勿提交 git）
workspace/state/<repo>.json	任务进度、sessions、活动流
workspace/runtime.json	看板端口、后台 PID
workspace/logs/supervisor/	看板与 loop 日志
workspace/prompts/、results/	派发与结果归档

看板与 loop 都读这些文件——IDE 聊天窗口关了，后台 loop 仍在跑；机器重启后说「继续 loop-skill」即可接上。

从工作区 移除某仓编排（remove-plan，二次确认）会删 workspace/ 下该仓状态与 loop.json 登记项，不会删除磁盘上的开发仓库及其 docs/loop-plan.md。

---

本地看板能看什么

up 启动后访问 http://127.0.0.1:8765/（端口以 runtime.json 为准）：

• 多仓库卡片：pending / running / done / blocked 统计
• 任务列表与最近活动流
• 多角色动态界面（与任务 角色 列对应）
• 卡片上可发起「移除编排」（同样二次确认）

适合一边喝咖啡一边扫一眼：哪仓在跑、哪条卡住了、今晚 loop 又推进了多少。

---

目录与文档索引

loop-skill/
├── SKILL.md              # 技能入口（何时用、主控协议）
├── references/           # 方法论、政策、契约、CLI 命令表
│   ├── plan-generation.md    # 主控 planner 协议（必读）
│   ├── role-guide.md         # architect / coder / verifier / reviewer
│   ├── decisions-guide.md    # 政策引擎
│   ├── loop-engineering.md   # 五阶段 + 六原语
│   └── cli-commands.md       # 完整命令分类表
├── providers/            # 各 CLI 适配规格
├── core/                 # 配置、状态、派发、循环、端口
├── dashboard/            # 本地 Web 看板
├── examples/             # 工作区配置示例
└── workspace/            # 全部运行产物（gitignore）

手动调试时可查 references/cli-commands.md，常用子命令：

命令	用途
doctor	检测可用 Provider
discover / scan / ingest	多仓登记、文档清单、导入任务表
up / down	启停后台看板 + loop
status	查看运行状态
remove-plan	从工作区移除某仓编排（二次确认）
loop / dispatch	调试派发（日常由 up 自动完成）

---

适合谁

适合	不太适合
多仓 vibe coding、希望 夜里无人值守 持续推进	只想偶尔问一两个语法问题
已有 Claude Code / Codex 等 CLI，想 计划驱动 而非手工 prompt	强依赖 GitHub Issue 闭环、不愿维护 Markdown 计划
需要 本地看板 盯多 agent、可恢复会话	只要一次性对话、不需要后台 loop
认同 loop engineering，愿意把精力放在「设计循环」上	期望零配置、完全不写验收标准

---

常见问题（简答）

Q：和 Superpowers、Cursor 自带 Agent 有什么区别？
Superpowers 等偏 单次会话内的流程技能（设计、TDD、评审）；loop-skill 偏 跨会话、跨仓库、后台常驻 的推进 loop，二者可叠加——主控用 Superpowers 写计划，loop-skill 负责夜里派发 CLI。

Q：一定要会 Python 吗？
日常 不用记命令，自然语言驱动主控即可；只有调试、脚本集成时才直接调 python -m core.cli。

Q：自动再规划会不会乱加任务？
planner 受仓库现状与 planner-contract 约束；若某轮 未新增任务 即停止。可 --no-auto-replan 跑完当前计划就停。

Q：核心依赖重吗？
运行时 零第三方依赖（标准库）；可选 pip install 仅为 loop.yaml 支持。

---

开源与互动

• 仓库：github.com/handsomestWei/loop-skill
• 许可证：MIT
• 技术栈：Python 60%+，含 dashboard 前端（HTML/CSS/JS）

如果这篇文章对你有用，欢迎去 GitHub 点 Star ⭐ 支持一下——Star 能帮助更多做 agent 编排的朋友发现这个项目。也欢迎 Fork 试用、提 Issue 反馈场景（多仓并行、blocked 自愈、新 Provider），或贡献 providers/ 适配与文档改进。

---

标签：AI AI编程 Agent Skill Claude Code Cursor Codex loop engineering 多智能体 无人值守 开源