【开源】写好 loop，让 agent 夜里无人值守地推进多仓项目：loop-skill

摘要

多仓 vibe coding 时，你是不是还在 每轮手动 prompt、盯着 CLI 跑完再拆下一批任务？关机后进度丢、多 agent 各干各的、不知道哪仓卡住了？本文介绍开源仓库 loop-skill（欢迎 Star ⭐）：用 SKILL.md 编排主控协议、core/ 轻量 Python 运行时 + 本地 Web 看板，把书面推进计划变成 计划驱动、无人值守的多 agent 闭环——按 发现 → 规划 → 执行 → 验收 → 迭代 自动派发 Claude Code / Codex / OpenCode / Gemini CLI / Trae CLI；任务清空后 自动再规划下一阶段，会话可恢复、关机不丢上下文。适用于 Cursor、Claude Code、Codex CLI 等支持 Agent Skills 的环境。

一、你是不是也卡在这些问题上？

用 AI 写代码的同学，长任务里常遇到：

  • 文档、设计、代码 都在仓库里，但 没人系统拆成可执行任务，全靠聊天里即兴 prompt；
  • 开了 Claude Code / Codex CLI，却要 人守着：跑完一条再催下一条，夜里没法「走开让它自己推进」；
  • 多个子仓库 并行开发，不知道哪仓在跑、哪条 blocked、今晚推进了多少；
  • 聊完关 IDE，进度没落地；第二天重来，上下文扯皮、不知道昨晚跑到哪；
  • 试过 绑 GitHub Issue 的重型编排器，配置重、和「Markdown 推进计划」工作流不对路；
  • 想让 agent 自己决定下一轮做什么，又怕它乱改、没有验收标准、没有留痕。

纯靠大模型「帮我一口气做完这个项目」往往 结构飘、和仓库事实对不齐、无法后台常驻。更稳的做法是：把 发现 → 规划 → 执行 → 验收 → 迭代 写成固定 loop，主控 agent 写计划、运行时派发 CLI、看板盯进度——这正是 loop engineering + Agent Skills 擅长的事。

从「每轮 prompt」到 loop engineering

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

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

社区把这类做法称为 loop engineering（Addy Osmani、mer.vin 等整理）：开发者从「对话者」变成 循环设计者——定义发现、规划、执行、验收、迭代的规则，让 agent 在规则内自驱运转，而不是你每五分钟敲一次「继续」。

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

二、这个技能是什么？

在这里插入图片描述

loop-skill 是一个完整的 Agent Skill 仓库 + Python 运行时：

组成部分 作用
SKILL.md 触发词、主控协议、五阶段顺序、禁止项（不让用户手写 loop.json 等）
references/ 计划生成、角色分工、政策引擎、planner 契约、loop 方法论、CLI 命令表
providers/ Claude / Codex / OpenCode / Gemini / Trae 等 可插拔 CLI 适配规格
core/ 配置、状态、派发、循环、端口（标准库为主，可选 PyYAML）
dashboard/ 本地实时 Web 看板（多仓、多角色头像、blocked 高亮）
examples/ 工作区配置示例，便于本地跑通
workspace/ 运行产物（状态、日志、会话、派发归档），gitignore，支持恢复

整体链路可以概括成：

发现多仓 → 主控写推进计划 → loop 后台派发 CLI 执行与验收 → 任务清空自动再规划 → 本地看板实时盯进度（无轮数上限，直至 planner 判定无有价值下一步）。

与客户端无关：把 loop-skill/ 目录放进任何能读 SKILL.md 并执行 shell 的主机 agent（Claude Code、Cursor、Codex CLI、Gemini CLI、OpenCode……）即可。主机 agent 是 指挥者；被派发的 CLI 是 执行者 / 再规划者。

设计目标就一句话：你只说话，主控干活——推进计划由主控通读仓库后写入各仓 docs/loop-plan.md；你无需手写 loop.yaml，也不绑定固定需求文件名。

使用效果

  • 本地看板：多仓卡片、任务状态、角色头像与统计
    在这里插入图片描述

三、核心能力一览

能力 说明
多仓发现 discover / scan 登记子仓库，列出 Markdown 文档清单供主控通读
推进计划 主控写入各仓 docs/loop-plan.md（五列：ID / 任务 / 验收 / 角色 / 状态）；兼容 docs/推进计划.md 等，ingest 会合并任务表
无人值守 loop up 后台常驻：按间隔轮询 → 执行 → 验收（verify_mode）→ 继续派发
自动再规划 某仓 pending / running 全部清空后，同一 CLI 担任 planner，追加下一阶段并 ingest（默认开启）
多仓并行 默认每仓同时各跑 1 个 CLI（fleet_parallel_max=0）；看板 先于 loop 启动
政策引擎 references/decisions-guide.md 提前写死歧义答案，减少 agent 反问卡住
多角色任务 推荐 architect / coder / verifier / reviewer 混排；禁止写 worker（会回落为 coder）
blocked 自愈 受阻任务交 planner 补 decision / 拆细，自动重试至多 2 次；仍卡则看板高亮，需人工
会话持久 workspace/state/ 存进度与 sessions；关机后「继续 loop-skill」可恢复
可插拔 Provider doctor 检测本机可用 CLI；Windows npm 全局 .cmd shim 已适配
移除编排 remove-plan 二次确认，只删工作区状态，不删开发仓库及其 docs/loop-plan.md
零重跑已完成任务 re-ingest 时保留已完成任务的 status / session_id，不会把验收过的任务再跑一遍

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

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

四、五阶段循环：开环规划 + 闭环自驱

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

首轮规划是「开环」：主控 agent 扫描仓库内 全部 相关 Markdown（README、docs 等），理解需求后写入推进计划。任务表 ID 用 P1-01 格式；推荐五列 | ID | 任务 | 验收 | 角色 | 状态 |。

之后是「闭环」：loop 后台常驻，按 --interval 轮询派发。某仓任务全部完成时，loop 自动把 default_provider CLI 当作 planner，通读仓库与进度，把 下一阶段 任务 追加 进 docs/loop-plan.md，再 ingest 并继续派发。

  • 不设轮数上限；仅当某轮再规划 未新增任何任务（planner 判定项目已达成、无有价值下一步）时，该仓停止再规划。
  • 手动关闭自动再规划：python -m core.cli loop --no-auto-replan 或 up --no-auto-replan。
  • 详见 references/plan-generation.md 与 references/planner-contract.md。

自驱闭环全景（便于对照看板）

用户一句话启动
       │
       ▼
主控：discover → scan → 各仓写 docs/loop-plan.md → ingest → up
       │
       ▼
loop 后台（各仓并行派发 CLI）
       │
       ├── 单任务：执行 → 验收 → 更新 state
       ├── blocked：交 planner 拆细 / 补 decision → 自动重试（≤2 次）
       └── 某仓全部完成？→ planner 追加下一阶段 → ingest → 继续
       │
       ▼
某轮再规划无新任务 → 该仓停止；你看板验收、合并 PR

五、适合谁用？

  • 多仓 vibe coding 的开发者：希望夜里 无人值守 持续推进，早上打开看板验收昨晚成果；
  • 已有 Claude Code / Codex 等 CLI：想 计划驱动，而非每轮手工 prompt；
  • 玩 Cursor Agent Skills、Claude Code 的同学：想要一个 领域完整、可 fork 改造 的「后台 loop」样例；
  • 认同 loop engineering：愿意把精力放在 设计循环与验收标准，而不是盯着聊天窗口；
  • 需要 本地看板 盯多 agent 进度、且希望 会话可恢复 的小团队。

不太适合：只问语法的一次性短对话；强依赖 GitHub Issue 闭环且不愿维护 Markdown 计划的团队；期望完全零配置、不写任何验收标准。

重要说明：loop 派发的是 coding-agent CLI，会在业务仓 自动改代码。请在隔离分支 / worktree 中使用，并自行审查合并结果。本技能 不构成 任何产品官方支持承诺，也不替代你对代码质量的最终把关。

六、怎么用（对最终用户极简单）

配置好技能路径后，在对话里用 自然语言 即可。建议同时说明：项目根目录路径、希望用的 CLI（claude / codex 等），减少主控猜测。

常用场景与提示语

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

主控会按 SKILL.md 在 同一轮 内完成 discover → scan → 为每个子仓写 docs/loop-plan.md → ingest → up --interval 300，并回报看板 URL（默认 http://127.0.0.1:8765/）。up 成功后 禁止 再反问「是否执行某任务」——loop 会自动派发。

推进计划示例（主控自动生成）

| ID | 任务 | 验收 | 角色 | 状态 |
|----|------|------|------|------|
| P1-01 | 实现用户登录 API | `pytest tests/test_auth.py` 通过 | coder | pending |
| P1-02 | 评审登录模块安全边界 | 无硬编码密钥、有 rate limit | reviewer | pending |
| P1-03 | 补充架构说明与模块边界 | docs/architecture.md 更新 | architect | pending |
  • ID：P1-01 可追踪编号
  • 验收：写清怎样算完成，供 verify_mode 与 verifier 角色使用
  • 状态：loop 运行后更新为 running / done / blocked 等

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

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

  • 禁止让用户手写 loop.json / loop.yaml 或逐步确认
  • 禁止主控代替 CLI 在业务仓写实现（除非用户明确只要主控、不用 loop）
  • 禁止用同步 dispatch 对每仓「试跑」——4 仓会阻塞 4 次长等待；应 ingest → up 后台跑
  • 若 ingest 后任务数为 0，up 会失败——主控应回到写推进计划，勿问用户

七、安装与环境

环境要求

  • Python 3.10+
  • PATH 中至少一个 coding-agent CLI
  • 现代浏览器（看板）

依赖：核心运行时 零第三方依赖（纯标准库）。pip install -r requirements.txt 仅为可选 loop.yaml 支持（PyYAML）；若用等价 loop.json，可不装任何东西。

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     # 可选

Claude Code 示例：

mkdir -p .claude/skills
git clone https://github.com/handsomestWei/loop-skill.git .claude/skills/loop-skill

Cursor：将完整仓库放到 Cursor 约定的 skills 路径，重启后在 Settings → Rules 中确认技能已发现；路径与说明以官方文档及仓库 SKILL.md 为准。

触发语参考（写在 SKILL.md front matter）：「用 loop-skill 推进某目录下的项目」「后台常驻 loop」「自动推进计划」等。

八、支持的 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

doctor 输出中至少一个 [ok] 即视为有可用的执行 CLI（看输出末尾「可用 provider」行）。限制并发：--fleet-parallel-max N；单仓轮询：--serial --fleet-parallel-max 1。

九、验收模式 verify_mode

不同仓库可覆盖默认验收策略（写在 loop.yaml / loop.json 或按仓覆盖）：

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

Worker 输出契约见 references/worker-contract.md。

十、角色分工与状态落盘

角色 谁来做 改什么
你 开发者 说意图、审看板、改业务仓设计 / 需求 / 推进计划
主控 Cursor、Claude Code、Codex CLI 等 loop-skill/、workspace/、各仓 docs/loop-plan.md、启停 loop
执行者 claude / codex / opencode 等 loop 自动派发，在业务仓写 代码实现
再规划者 默认同 default_provider CLI 某仓任务全部完成后，自动追加下一阶段计划
文件 / 目录 内容
loop.json 多仓登记与任务定义（自动生成，勿提交 git）
workspace/state/<repo>.json 任务进度、sessions、活动流
workspace/runtime.json 看板端口、后台 PID
workspace/logs/supervisor/ 看板与 loop 日志
workspace/prompts/、results/ 派发 prompt 与结果归档

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

从工作区移除某仓编排

用户说「移除 xxx 的推进计划」时，主控须 二次确认，并明确：

  • 会删：workspace/ 下该仓 state、prompts、results、logs，以及 loop.json 登记项
  • 不会删：磁盘上的开发仓库及其 docs/loop-plan.md
python -m core.cli remove-plan <repo>           # 获取确认令牌
python -m core.cli remove-plan <repo> --confirm <token>

看板卡片「移除」按钮同样两步确认。

十一、本地看板能看什么

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

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

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

十二、仓库目录与文档索引

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

手动调试时常用子命令：

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

十三、和 Superpowers 等技能怎么搭配？

类型 代表 侧重
会话内流程技能 Superpowers 单次任务内的设计、TDD、评审 门禁
后台推进 loop loop-skill 跨会话、跨仓库、无人值守 派发 CLI

二者可 叠加：主控用 Superpowers 规范「动工前设计、先测后写、完工前核验」，loop-skill 负责夜里后台按 docs/loop-plan.md 持续派发 CLI。一个管 单次会话质量，一个管 长时间推进节奏。

十四、常见问题

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

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

Q：主控会代替 CLI 写代码吗？
SKILL.md 禁止主控在业务仓写实现（除非用户明确只要主控）；实现由派发的 CLI 完成。

Q：和 GitHub Actions / Issue 驱动的 bot 有什么区别？
loop-skill 任务来自 你仓库里的 Markdown 推进计划，不绑 Issue 生命周期；适合个人/小团队 vibe coding，而不是企业级 CI 门禁。

Q：blocked 了怎么办？
默认 loop 自动交给 planner 补 decision、拆细任务并重试（至多 2 次）。看板会高亮仍须人工介入的项；你说一句「处理 blocked 并继续」即可。

Q：核心依赖重吗？
运行时 零第三方依赖；可选 pip install 仅为 loop.yaml。

十五、链接汇总

资源 说明
GitHub 仓库 https://github.com/handsomestWei/loop-skill
技能入口 仓库根目录 SKILL.md
主控 planner 协议 references/plan-generation.md
CLI 命令表 references/cli-commands.md
配置示例 examples/
loop engineering 背景 mer.vin 整理文
Agent Skills 规范 https://agentskills.io

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

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

# AI
Logo
AtomGit AI 社区

AtomGit AI 社区提供模型库、数据集、Agent、Token等资源

更多推荐

世界模型岗年薪250万仍缺人，可你的AI连旋转都算不准——2026下半年最该补的不是框架是这条公理

2026年6月英伟达黄仁勋定调Physical AI及世界模型为下一浪潮，Cosmos 3开源，达沃斯列入十大新兴技术，Agent工程师成最稀缺岗（年薪250万仍缺人）。本文指出当前AI Agent缺乏物理公理致旋转仿真/流体外推失效；《旋生万物》从"退化圆"出发构建旋子代数与螺旋联络统一旋转、平移及物理定律，为世界模型提供几何先验；《圆道与螺旋系列丛书》（22部·300万字·公理I²=-N）覆盖

avatar AtomGit AI 社区
cover

AI时代的知识图谱完全指南：从概念原理到企业落地的实战手册

avatar AtomGit AI 社区
cover

51天一个新版本！ChatGPT和Claude狂飙，谷歌被甩出代差

avatar AtomGit AI 社区