使用 @cobusgreyling/loop 统一 CLI 安装 Loop Engineering：install-loop 技能实战指南

使用 cobusgreyling/loop 统一 CLI 安装 Loop Engineeringinstall-loop 技能实战指南【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering本篇技术指南讲解 loop-engineering 仓库中install-loop技能skills/install-loop/SKILL.md的完整落地方法通过npx cobusgreyling/loop这一统一 CLI 前门在一个项目里完成「脚手架 → 体检 → 成本预估 → 首轮运行指令」的全流程激活并拿到Loop Ready评分与明确的下一步行动。读完本文你将掌握 8 种内置模式的选型逻辑、doctor 退出码的判定规则、loop与旧版loop-init/loop-audit的兼容边界以及 week-one 只读运行的安全红线并理解其背后的源码级实现原理。一、install-loop 是什么一条命令完成激活install-loop是一个面向 AI Agent 的安装技能核心目标非常收敛用单一命令把任意仓库变成带「report-only只读报告」闭环的 Loop Engineering 项目并输出可量化的结果npx cobusgreyling/loop这条命令是 loop-engineering 生态的统一入口unified CLI front doorCLI 版本为v0.2.0见 tools/loop/src/cli.ts 的VERSION常量。它把原本需要分别记忆的多条命令收敛为一个心智模型但不会取代loop-init/loop-audit两者依然是合法入口。install-loop 技能的核心约束有两条不要废弃你在仓库里见到的既有loop-init/loop-audit用法两条旧门保持有效新工作优先用loop。week-one 只读第一周只允许 report-only绝不自动 merge、绝不无人值守修复除非人类明确要求且 doctor 体检健康。二、统一前门与旧 CLI 的兼容关系loop不是一套新工具而是对现有兄弟工具的转发层pass-through。在 tools/loop/src/pass-through.ts 中TOOLS表明确记录了每个子命令对应的 npm 包、monorepo 目录与 CLI 入口loop子命令转发到的包用途loop initcobusgreyling/loop-init脚手架模式 工具loop auditcobusgreyling/loop-auditLoop Ready 评分loop costcobusgreyling/loop-costToken 成本预估loop synccobusgreyling/loop-syncSTATE ↔ LOOP 漂移检测loop contextcobusgreyling/loop-context预算/熔断/内存loop worktreecobusgreyling/loop-worktree隔离修复尝试loop gatecobusgreyling/loop-gate路径黑名单loop mcpcobusgreyling/loop-mcp-serverMCP 服务器loop sandboxcobusgreyling/loop-sandbox沙箱助手此外loop还新增了两个非转发的子命令由cli.ts直接实现loop doctor [path] [--json]audit sync 文件结构检查输出 Top 3 行动与退出码loop status [path] [--json]基于 STATE / run-log 的 day-2 仪表盘loop badge [path]等价于loop-audit --badge生成 README 徽章loop wizard [--yes]引导式脚手架 doctor。转发解析有三层回退优先用 monorepo 内tools/工具/dist/cli.js其次该包 node_modules 内嵌套路径再次仓库根 hoisted 的 node_modules最后才落到npx --yes pkg见 tools/loop/src/pass-through.ts。这意味着在 monorepo 开发环境下loop doctor会直接调用本地构建的loop-audit与loop-sync行为与发布版一致。三、第一步检测上下文决定是初始化还是只做体检install-loop 的第一步不是盲目脚手架而是先探测仓库现状对应 SKILL.md 的 Detect context# 若仓库已存在 LOOP.md 或 STATE.md npx cobusgreyling/loop doctor . --json npx cobusgreyling/loop status .命中已初始化仓库只跑 doctor status跳过 init除非人类明确要求重新脚手架re-scaffold。空仓库 / 未初始化继续执行后续步骤。loop doctor内部会通过 tools/loop/src/files.ts 的findStateFile依次探测STATE.md、pr-babysitter-state.md、ci-sweeper-state.md、post-merge-state.md、dependency-sweeper-state.md、changelog-drafter-state.md、issue-triage-state.md等候选状态文件因此它能识别任意模式生成的状态文件而不仅限于默认的STATE.md。--json标志在cli.ts的cmdDoctor/cmdStatus中处理tools/loop/src/cli.ts输出结构化报告便于 Agent 程序化解析。四、第二步按痛点选择模式8 个内置模式SKILL.md 提供了一张「痛点 → 模式」映射表默认模式为daily-triage。这与 tools/loop/src/wizard.ts 中PAIN_OPTIONS的交互菜单一一对应痛点模式对应痛点选项wizard 交互菜单早晨混乱 / 优先级不清daily-triageMorning chaos — what should I do?PR 卡住pr-babysitterPRs stalling on review/CICI 红 / 抖动ci-sweeperCI red / flaky checksCVE / Dependabot 噪音dependency-sweeperDependabot / CVE noise合并后的 TODOpost-merge-cleanupMerge debt / TODOs piling up发布说明过期changelog-drafterStale release notes / changelogs问题噪音issue-triageNoisy issue backlog / duplicates只需一个 GitHub Action几乎不想要文件thin-loopJust a GitHub Action, no extra files在 tools/loop-init/src/cli.ts 的PATTERN_STARTERS中这 8 个模式被映射到starters/目录下的对应模板minimal-loop、pr-babysitter、ci-sweeper、dependency-sweeper、post-merge-cleanup、changelog-drafter、issue-triage、thin-loop其中daily-triage直接复用最小的minimal-loop骨架。此外每个模式还定义了专属的状态文件名STATE_FILES见 tools/loop-init/src/cli.ts例如pr-babysitter生成pr-babysitter-state.mdthin-loop使用STATE.md。五、第三步选择工具并生成脚手架模式确定后需要选择目标 Agent 工具SKILL.md 第 3 步claude | grok | codex | opencode 默认 claude这四个工具在wizard.ts的TOOLS常量中定义tools/loop/src/wizard.tsloop-init的TOOL_SUFFIX则据此拼接 starter 目录后缀-claude/-codex/-opencodegrok 无后缀唯一例外是thin-loop为工具无关模式TOOL_AGNOSTIC集合。然后执行脚手架命令npx cobusgreyling/loop init . --pattern pattern --tool tool若人类明确想要 Foundry 运行时 harness可追加--with-foundry。loop-init的完整选项见 tools/loop-init/src/cli.ts 的 help 输出包括选项说明默认值-p, --pattern要脚手架的模式daily-triage-t, --tool目标工具claude--with-foundry同时生成.foundry/栈harness-foundry 运行时关--with-memory生成 memory-engineering 分层与预算关--with-fleet生成 fleet-engineering 注册表与收件箱关--model-providerimplementer 接口提供方anthropic可minimax/orcarouter--regionMiniMax 区域global_en可cn_zh--model提供方模型MiniMax-M3/orcarouter/fusion--dry-run只打印动作不复制关脚手架的产物以非thin-loop模式为例loop init会生成对应 tools/loop-init/src/cli.ts 的组装逻辑状态文件如STATE.md/pr-babysitter-state.md从 starter 的.example拷贝LOOP.md记录节奏、闸门与 kill switchAGENTS.md测试命令与 Loop 约定缺失时写模板技能目录按工具写入.claude/skills/、.grok/skills/、.codex/skills/opencode 则写入skills/AGENTS.mdopencode.json可修复模式附加pr-babysitter、ci-sweeper、dependency-sweeper、post-merge-cleanup属PATTERNS_NEEDING_FIXminimal-fix技能 loop-guard熔断技能 预置的loop-ledger.jsonci-sweeper/dependency-sweeperL2 模式额外装配独立验证 agentloop-verifierClaude 为.claude/agents/loop-verifier.mdCodex 为.codex/agents/verifier.tomlissue-triage装配loop-intake技能用于澄清模糊条目或升级而非瞎猜消耗修复次数可观测性文件loop-budget.md含每日限额表、loop-run-log.mdJSONL 运行日志、loop-constraints.md以及loop-budget/loop-constraints技能GitHub Actions若 starter 含.github/workflows/拷贝工作流文件。loop-budget.md的预算来自PATTERN_BUDGET表tools/loop-init/src/cli.ts该表与 patterns/registry.yaml 的成本配置对齐模式每日最大运行次数每日 Token 上限L1/L2 子代理数daily-triage2100k0 / 2pr-babysitter2882M0 / 3ci-sweeper961M0 / 3dependency-sweeper4500k0 / 3post-merge-cleanup1200k0 / 2changelog-drafter1100k0 / 2issue-triage1280k0 / 1thin-loop2420k0 / 0脚手架完成后loop-init会立即对目标目录跑一次loop-audit --json打印Loop Ready: score/100 (level)的评分条与评估摘要。六、第四步Doctor 体检与退出码脚手架之后立即执行体检npx cobusgreyling/loop doctor .退出码约定SKILL.md 与cli.ts的 help 一致退出码含义0健康healthy1有警告warnings分数/同步/预算缺口2阻塞blocked分数 40、严重漂移、未脚手架Agent 的职责是照做打印出来的 Top 3 行动不要自行发明额外架构。doctor的完整判定逻辑位于 tools/loop/src/doctor.ts阻塞条件exit 2readyScore 40或syncLevel critical或「既无状态文件也无 LOOP.md」警告条件exit 1readyScore 58或syncLevel warning或 sync issue 数 0或缺少loop-budget.md或缺少loop-run-log.md分数 ≥ 80doctor追加两条可选行动——loop init . --with-foundry将闭环升级为版本化 harness与loop badge target分享分数徽章。Doctor 检查了什么源码级runDoctortools/loop/src/doctor.ts把三类信号合并成一个报告ReadyLoop Ready 分数调用loop-audit --json解析score/level/assessment/recommendationsSync漂移检查调用loop-sync --json解析score/level/issues/suggestions前 2 条建议进行动列表文件结构探测STATE.md类状态文件、LOOP.md、loop-budget.md、loop-run-log.md、loop-constraints.md、gate.yaml、AGENTS.md是否存在。所有行动项按优先级排序如「脚手架」「补 LOOP.md」「补预算」为高优先级 1~11audit 建议为 50Foundry/badge 为 90按文本去重后只保留 Top 3tools/loop/src/doctor.ts。这解释了 SKILL.md 中「Follow the top 3 printed actions」的出处——不是所有行动都要做而是优先解决最高优先级的 3 项。七、第五步Cost 成本预估在开启高频率调度之前先用成本预估确认预算可行npx cobusgreyling/loop cost -p pattern -l L1 -c 1dloop-cost从 patterns/registry.yaml或随包分发的registry.json读取每个模式的cadence与token_cost元数据再基于 estimator 计算每日 Token 消耗。完整选项见 tools/loop-cost/src/cli.ts选项说明默认值-p, --pattern模式 iddaily-triage-c, --cadence覆盖节奏如15m、1d、5m-15m注册表值-l, --level就绪级别L1/L2/L3L1-o, --orchestration多 Agent 行动成本single/maker-checker/parallel:N/debate:Rsingle--conservative取节奏区间中较慢的一端如15m而非5m关--with-caching显示应用提示缓存的预估要求模式的 cost 块含stable_fraction关--json机器可读输出关--list列出全部模式 id关例如npx cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L2可以预估 CI 清扫器在 L2 级别、15 分钟节奏下的日消耗--json输出可直接交给 Agent 写入loop-budget.md或调度决策。八、第六步Week-one 规则与 Badgeinstall-loop 的安全底线SKILL.md 的 Week-one rule只报告report-only不自动修复、不自动合并把 init 输出的第一条/loop或调度命令告诉人类——这是首轮运行的入口只有当分数足够强时才建议加徽章npx cobusgreyling/loop badge .firstLoopCommandtools/loop-init/src/cli.ts按「模式 × 工具」组合生成首轮指令例如daily-triageclaude/loop 1d $loop-triage — update STATE.md. Report-only week one.pr-babysittercodexAutomation 10m: pr-review-triage → pr-babysitter-state.md. No auto-merge.ci-sweeperopencodeopencode run Run ci-triage on failing CI. Update ci-sweeper-state.md. Report only in week one.thin-loop任意工具Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.badge子命令在 tools/loop/src/cli.ts 中实现直接转发到loop-audit --badge生成可粘贴进 README 的评分徽章。注意 SKILL.md 的措辞是「Suggest badgeonly when score is strong」——分数弱时不应建议这与doctor在分数 ≥ 80 时才推送 badge 行动的逻辑一致。九、兼容性与停止条件旧版入口保持完全支持loop cmd与直接调用子包是同一二进制行为npx cobusgreyling/loop-init . npx cobusgreyling/loop-audit . --suggestloop-init与loop-audit在cli.ts的PASS_THROUGH集合中登记tools/loop/src/cli.ts所以loop init与npx cobusgreyling/loop-init本质等价。README 中的兼容声明tools/loop/README.md进一步确认loop-init、loop-audit、loop-cost、loop-sync都会继续工作除非未来大版本给出长弃用期。停止条件SKILL.md 的 Stop conditionsdoctor 首轮运行说明完成后即停止除非人类要求升级到 L2除非分数 ≥ 80且人类明确选择否则绝不擅自扩展到 fleet / memory / foundry 工程栈。这两条把「Agent 自嗨扩展架构」这个经典失败模式显式写成了硬约束——doctor的 Foundry 建议同样被readyScore 80的闸门条件保护tools/loop/src/doctor.ts。十、源码原理wizard 默认值与 TTY 守卫wizard 的默认计划与输入解析无参运行npx cobusgreyling/loop或loop wizard时非交互帮助由wizard.ts的printNonInteractiveHelp输出若带--interactive且在真实 TTY 上则进入runInteractiveWizard交互问答。defaultPlan()tools/loop/src/wizard.ts给出的默认值是pattern: daily-triage · tool: claude · target: . · withFoundry: falseresolvePattern接受数字 id如3→ci-sweeper、模式名或任意小写[a-z0-9-]标识符resolveTool只接受grok/claude/codex/opencode四个合法值否则回退claude。executePlan则按「先loop init成功后紧跟loop doctor」的顺序执行tools/loop/src/wizard.ts——这正是 SKILL.md 推荐的 week-one 主路径。TTY 守卫非交互环境绝不擅自脚手架cli.ts对--interactive有一个关键守卫tools/loop/src/cli.ts当 stdin不是TTY如 CI 步骤、管道输入、 /dev/null时readline.question()会立即以空字符串解析导致 wizard 以「全空白答案 默认计划」静默运行并生成没人要的文件。因此代码显式判断process.stdin.isTTY非 TTY 一律打印非交互帮助并退出杜绝误脚手架。十一、测试验证仓库为loop统一 CLI 提供了完整的自动化测试tools/loop/test/cli.test.mjs覆盖 install-loop 的核心承诺loop --help退出 0 且文档化doctor/loop-init/ week-one 路径loop --version输出语义化版本号无参运行打印 week-one 路径含loop init/loop doctorloop audit --help通过 pass-through 正常转发到loop-auditloop doctor --json作用于仓库根时返回ready.scoredogfood 测试断言分数 ≥ 40、actions.length 3、退出码 2即参考仓库本身不允许被阻塞loop status --json返回recentRuns数组与nextHint非 TTY 的--interactive运行只打印帮助、不生成任何文件临时目录断言为空loop doctor作用于空临时目录返回blockedseverityblockedexit 2。这些测试直接印证了 SKILL.md 的「report-only」「Top 3 行动」「停止条件」等行为约定是安装流程可被机器验证的底层保障。总结install-loop 技能的价值在于把「安装 Loop Engineering」从多命令拼装收敛为一条npx cobusgreyling/loop前门路径检测上下文 → 选模式 → 选工具 → 脚手架 → doctor 体检 → 成本预估 → week-one 只读运行。其背后由loop统一前门与 doctor/status、loop-init脚手架与预算、loop-cost成本预估、loop-audit评分四个工具协同实现且有 TTY 守卫、Top 3 行动去重、分数闸门等源码级安全机制托底。对 Agent 而言遵守「report-only 第一周 不擅自扩展架构 分数达标才升级」三条红线就能安全、可观测、可追溯地完成任何仓库的闭环激活。【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考