loop-engineering 统一入口 `@cobusgreyling/loop`：用一条 CLI 打通 loop-init、loop-audit、doctor 与 status 的完整实操指南

人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】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 仓库维护着loop-init、loop-audit、loop-cost、loop-sync等多个职责单一的 CLI对维护者友好却让首次上手的用户和 Agent 难以记忆。cobusgreyling/loop是官方提供的薄伞式统一入口thin umbrella一个可记忆的二进制命令以透传pass-through方式复用既有工具的全部参数并新增doctor/status两个 day-2 巡检命令。读完本文你将掌握该统一 CLI 的完整命令映射、底层透传解析原理、doctor 退出码的判定逻辑、非交互环境的 TTY 保护以及发布与版本策略可直接用于自己项目的 loop 工程化落地。为什么需要一把前门Loop Engineering 是一个以模式 起步套件 CLI 工具为载体的工程实践仓库每个能力点都对应一个独立 npm 包cobusgreyling/loop-init脚手架、cobusgreyling/loop-auditLoop Ready 评分、cobusgreyling/loop-costtoken 成本估算、cobusgreyling/loop-sync状态漂移检测等。这种拆分对维护者来说是清晰的模块边界但对第一次接触的新用户来说需要同时记住多个包名和用法心智负担明显。cobusgreyling/loop源码位于 tools/loop解决的就是这个问题。它在 tools/loop/README.md 中明确声明它不替代任何既有工具而是包装它们并新增 doctor status让第一周激活week-one activation只需要一个心智模型。官方文档在 docs/cli-front-door.md 中用三个特性概括了它的设计目标一个可记忆的二进制npx cobusgreyling/loop …透传pass-throughloop cmd与既有工具完全同参不新增学习成本doctor / status为激活检查activation和 day-2 习惯day-2 habit提供专用命令入口即通最典型的第一周路径只有两条命令npx cobusgreyling/loop init . -p daily-triage -t claude npx cobusgreyling/loop doctor .命令映射表新的门老的命令不变官方文档提供了完整的新门 → 旧包映射。这张表是理解整个前门设计的核心它同时说明了两件事新命令在语义上等价于旧包旧包的调用方式在未来相当长一段时间内都不会失效。前门命令原有包 / 命令loop init …npx cobusgreyling/loop-init …loop audit …npx cobusgreyling/loop-audit …loop cost …npx cobusgreyling/loop-cost …loop sync …npx cobusgreyling/loop-sync …loop context …npx cobusgreyling/loop-context …loop worktree …npx cobusgreyling/loop-worktree …loop gate …npx cobusgreyling/loop-gate …loop mcp …npx cobusgreyling/loop-mcp-server …loop badge .loop-audit . --badgeloop doctor .新增audit sync 文件结构检查loop status .新增run-log 仪表盘其中大部分命令是一对一透传但有三处值得注意的差异loop badge不是调用同名子命令而是把参数改写成loop-audit target --badge后透传见下文源码解析用于在 README 生成 Loop Ready 徽章loop doctor与loop status是伞包的原生能力不是任何旧包的直接别名它们内部组合调用 audit / sync 并对输出做聚合分析实际的 tools/loop/src/cli.ts 还额外暴露了loop sandbox透传到cobusgreyling/loop-sandbox和loop wizard引导式脚手架比文档表格中的九项映射更完整。兼容性承诺旧门永远开着对已经写进 CI、脚本或文档里的旧调用前门不做任何破坏性替换。官方文档Forks contributors一节明确给出两条红线已经调用loop-init/loop-audit的 Fork什么都不用改新增的文档 / skills / Actions优先使用loop。同理skills/install-loop/SKILL.md 里也要求 Agent 不要弃用或删除已经存在的loop-init/loop-audit用法两个门都保持有效新工作优先用loop。这让存量项目可以零成本迁移也让新项目从第一天就只学一条命令。透传pass-through的源码级解析loop cmd之所以能做到与旧工具完全同参是因为它并非在伞包内复制各工具逻辑而是解析出目标工具的真实入口并直接运行。核心实现位于 tools/loop/src/pass-through.ts内置一张TOOLS映射表把init / audit / cost / sync / context / worktree / gate / mcp / sandbox分别绑定到各自的 npm 包名、monorepo 目录、CLI 入口脚本和全局二进制名resolveToolScript()按三条路径依次探测目标脚本是否存在monorepo 内已构建的产物tools/tool/dist/cli.js伞包自身的node_modules内嵌套安装的包仓库根目录 hoisted提升的node_modules包命中本地脚本则用spawn(process.execPath, [script, ...args])直接运行继承 stdio支持交互式透传都没命中才回退到spawn(npx, [--yes, pkg, ...args])动态拉取通过runTool()/runToolCapture()两个封装分别实现透传继承终端和捕获 stdout 供 doctor/status 解析两种模式。这样的设计带来了两个重要工程性质参数零损耗因为是整段args原样透传loop-init支持的所有 flag如--pattern、--tool、--with-foundry在loop init下行为完全一致本地优先、网络兜底monorepo 内开发时直接复用已构建产物不重复下载发布到 npm 后npx场景则按需拉取对应版本的兄弟包这正对应文档版本策略中透传跟随 monorepo dist 或 npx 安装到的兄弟版本的描述。命令分发的总入口在 tools/loop/src/cli.tsmain()按序处理无参数时打印第一周指引--help/--version直接响应PASS_THROUGH集合中的命令走透传doctor/status/badge/wizard走各自的原生处理函数未知命令则报错并回退到帮助页。loop doctor一次命令完成激活体检doctor是前门最核心的新增能力。官方文档对它下了一个准确的定义audit sync 文件结构检查 → 输出 top 3 行动建议。它把原本需要三次独立调用才能获得的信息压缩成一次命令npx cobusgreyling/loop doctor . --json退出码语义与 CI 用法退出码含义CI 建议0健康Healthygreen通过1警告Warningssoft-fail 或留评论2阻塞Blocked若要求脚手架存在则 hard-fail判定逻辑在 tools/loop/src/doctor.ts 中可逐条对上blockedexit 2的充要条件Loop Ready 评分存在且 40或 sync 等级为critical或既没有 STATE 文件也没有 LOOP.md即仓库完全未脚手架化**warningexit 1**的触发面更宽评分 58、sync 等级为warning、sync 存在 issue、缺少loop-budget.md或预算内容不含max tokens/daily limits/kill switch关键词见 tools/loop/src/files.ts 的budgetPresent()、缺少loop-run-log.md等。据此可以设计非常实用的 CI 闸门要求交付物必须完成脚手架时把 exit 2 设为 hard-fail把 exit 1 作为软性提示或 PR 评论不阻塞合并。它到底检查了什么runDoctor()的执行流程对应 doctor.ts包括结构检查探测 STATE 文件STATE.md或各模式的*-state.md候选列表见 files.ts、LOOP.md、loop-budget.md、loop-run-log.md、loop-constraints.md、gate.yaml、AGENTS.md是否就位audit 子调用以loop-audit target --json获取 Loop Ready 评分与等级用宽松 JSON 解析兼容输出前带 banner 的 CLIparseJsonLoose()会截取第一个{或[再解析sync 子调用以loop-sync target --json获取漂移评分与 issue 数量并把前两条建议并入行动清单生成行动建议按优先级排序后取前三条topActions并用按文本去重、保留更优优先级的规则避免重复建议汇总退出码按上面两个判定分支归入healthy / warning / blocked。行动建议的优先级设计非常贴近真实场景空仓库时优先引导脚手架priority 1随后依次是补 STATE 文件、补LOOP.md、修 critical 漂移、把评分提到 40 以上、补预算与运行日志当评分 ≥ 80 时才追加两条可选建议——版本化为 Foundry harness 与生成徽章这正是 skills/install-loop/SKILL.md 中score ≥ 80 且人工明确要求才扩展到 fleet/memory/foundry这一停止条件的具体实现。空仓库的可验证行为tools/loop/test/cli.test.mjs 提供了两条可直接对照的行为验证loop doctor在空临时目录上执行时必然输出severity: blocked、exitCode: 2且进程退出码也是 2测试用例loop doctor on empty temp dir is blocked在仓库根目录上执行时dogfood 测试要求评分 40、action 数 3、退出码 2即本仓库自身必须保持不被阻塞的可用状态。这组测试同时证明doctor的 JSON 输出结构包含target / severity / exitCode / ready / sync / files / actions / notes可直接被 CI 或 Agent 脚本消费。loop statusday-2 运行仪表盘如果说doctor回答的是现在能不能跑status回答的就是跑得怎么样了。它在 tools/loop/src/status.ts 中实现纯读取仓库内已有的 markdown 制品不做任何修改聚合展示检测到的 pattern从LOOP.md内容与###标题中抽取见extractPatternsFromLoop()STATE 文件及其Last run:时间当前 Loop Ready 评分复用loop-audit --json失败时静默降级不影响其余输出loop-run-log.md中最近的 5 条 JSONL 运行记录每条含run_id / pattern / outcome / tokens_estimate账本loop-ledger.json含 pattern、level、attempts 数、预算、gate、constraints 的存在性一条智能nextHint建议未脚手架时引导init有记录但无运行日志时建议安排首次 report-only 运行评分 ≥ 80 时才建议badge。npx cobusgreyling/loop status . --json这正好补齐官方文档映射表中loop statusrun-log 仪表盘的全部细节它的数据来源、字段结构和智能提示逻辑都是文档之外由源码确认的实现事实。loop wizard与交互式 TTY 保护前门还内置了一个非交互式的第一周向导对应 tools/loop/src/wizard.ts。loop无参数运行时打印的正是这份Week-one path8 个痛点 → 模式选项晨间混乱→daily-triage、PR 停滞→pr-babysitter、CI 红→ci-sweeper、CVE/Dependabot 噪音→dependency-sweeper、合并债务→post-merge-cleanup、过期的发布说明→changelog-drafter、Issue 噪音→issue-triage、仅需一个 Action→thin-loop工具选项claude/grok/codex/opencode默认claude支持loop wizard -p daily-triage -t claude .这样的全非交互参数化调用--pattern/-p、--tool/-t、--with-foundry、--yes/-y、--interactive/-i。值得特别指出的是交互式模式的安全阀。在 tools/loop/src/cli.ts 中loop --interactive只有在process.stdin.isTTY为真时才真正进入runInteractiveWizard()否则打印帮助并直接退出。这一保护的来龙去脉记录在测试用例loop --interactive with closed (non-TTY) stdin prints help instead of scaffolding的注释里此前在没有 TTY 的 CI 环境管道输入或 /dev/null下readline.question()会立即以空字符串解析导致向导默默以空回答跑完并生成没人要求的脚手架文件。这条 TTY 守卫保证任何非交互上下文都不会误触发脚手架生成测试还会断言目标目录里没有产生任何新文件。自定义 Provider--with-foundry与 MiniMax 标志官方文档特别提到loop init配合--with-foundry时可以透传自定义 provider 标志例如npx cobusgreyling/loop init . --pattern daily-triage --tool claude \ --with-foundry --model-provider minimax --region global_en --model MiniMax-M3完整的参数说明在 docs/QUICKSTART.md 的 Foundry 一节中--model-provider minimax选择 MiniMax 作为模型提供方--regionglobal_en默认或cn_zh--model例如MiniMax-M3。在 wizard.ts 的executePlan()中可以看到--with-foundry只是作为附加 flag 拼进loop-init的参数列表后透传initArgs.push(--with-foundry)具体 stack 的生成与校验逻辑仍由loop-init/harness-foundry生态完成伞包只负责把门开开。这也再次印证了前门的透传哲学伞包不复制逻辑只负责路由。给 Agent 用的安装技能为了让 Agent而非人类也能完成装一个循环这件事仓库提供了 skills/install-loop/SKILL.md。官方文档建议把它复制到.grok/skills、.claude/skills等 Agent 技能目录或直接把该路径指给 Agent 使用。这个技能把前门的使用固化成一套可执行流程与本文前面所有内容一一对应检测上下文若仓库已有LOOP.md或STATE.md跳过 init 只跑doctor与status选模式默认daily-triage八选一选工具claude/grok/codex/opencode默认claude脚手架loop init . --pattern pattern --tool tool可选--with-foundry体检loop doctor .退出码 0/1/2只执行打印出的 top 3 行动不自行发明额外架构成本检查高频率排程前loop cost -p pattern -l L1 -c 1d第一周铁律只做 report-only不做自动修复、不自动合并评分够强时才建议loop badge .。技能同样内置了停止条件doctor 首次运行指引之后即停除非人工要求进入 L2评分 ≥ 80 且人工明确同意前绝不扩展到 fleet/memory/foundry。这与 docs/cli-front-door.md 及 tools/loop/README.md 的边界完全一致。Forks 与贡献者指南官方文档给仓库生态中的三类角色明确了接入方式已经调用loop-init/loop-audit的 Fork行为不变无需任何改动写新文档 / 新 skills / 新 Actions 的维护者新内容统一引用loop前门新增工具的贡献者保持独立包形态tools/tool若希望它被前门发现就在 tools/loop/src/pass-through.ts 的TOOLS表中补一行映射npm 包名 monorepo 目录 CLI 入口 二进制名并在 tools/loop/src/cli.ts 的PASS_THROUGH集合中登记命令名。这套独立包 一行透传注册的扩展模型既保住了模块的独立发布与独立测试又让用户始终只需记忆一条命令。从源码结构看新增一个可发现工具的改动面被刻意压缩到两个文件、约十行代码。发布流程与版本策略发布伞包通过 git tag 触发 npm 发布官方文档给出的命令是git tag loop-v0.1.0 git push origin loop-v0.1.0对应的 CI 工作流是 .github/workflows/release-loop.yml其关键步骤从源码确认监听loop-v*格式的 tag也支持workflow_dispatch手动指定 tag先依次构建兄弟工具readiness-core、loop-audit、loop-sync、loop-init、loop-cost再构建伞包并运行npm test使用 npmOIDC trusted publishingnpm publish --access public --provenance并在注释中明确不要设置NODE_AUTH_TOKEN否则会覆盖 OIDC。注意当前伞包版本为0.2.0见 tools/loop/package.json 与 cli.ts 中的VERSION因此发布时应使用与 package.json 一致的 tag如loop-v0.2.0。详细的发布规范可参考 docs/RELEASE.md。版本策略官方文档对前门的版本演进给出两条原则伞包处于0.x阶段在整体设计定型前透传行为跟随 monorepo dist 或 npx 安装到的兄弟包版本不锁定也不强推此阶段不弃用任何兄弟包loop-init/loop-audit等继续独立维护与发布直到未来某个带长期弃用窗口的 major 版本再谈收敛。配合前面Forks 什么都不用改的兼容性承诺这条策略保证了生态迁移是自发的、渐进的而不是强制的。用测试固化行为用 dogfood 自证可用cobusgreyling/loop的行为不是只写在文档里tools/loop/test/cli.test.mjs 用node:test固化了七个关键契约可作为你接入时的行为参考loop --help必须同时提到loop doctor、loop-init和 Week-one 路径loop --version输出符合\d\.\d\.\d语义化版本格式无参数运行时打印 init doctor 的第一周指引loop audit --help在 monorepo dist 存在时能透传到loop-audit的帮助文本loop doctor --json在仓库根目录上输出结构化报告且 action 数不超过 3loop status --json必然包含recentRuns数组与nextHint非 TTY 下--interactive不生成任何脚手架文件见上文 TTY 保护空目录上doctor必然 blockedexit 2。其中仓库自身必须通过 doctor 且不被阻塞的 dogfood 测试意味着任何对前门的改动都不能让本仓库回退到未激活状态——这是伞包质量自证的关键一环。小结一条命令进入 Loop Engineeringcobusgreyling/loop用最小的设计代价解决了最大的上手障碍一条可记忆的命令 一张永不关闭的旧门 两个原生健康命令。对首次使用者记忆init→doctor→status三条子命令即可完成从脚手架到 day-2 巡检的完整闭环对存量用户旧包调用原样保留对 Agentinstall-loop 技能 提供了可机械执行的安装流程对贡献者一行透传注册即可让新工具被前门发现。如果你想深入底层可以依次阅读 tools/loop/src/cli.ts命令分发、tools/loop/src/pass-through.ts透传解析、tools/loop/src/doctor.ts体检逻辑与 tools/loop/test/cli.test.mjs行为契约并结合 docs/QUICKSTART.md 与 docs/RELEASE.md 完成自己的落地。赞分享人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】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点击查看免费下载相关推荐GDSDecomp让Godot游戏逆向工程从技术挑战变为开发利器GDSDecomp让Godot游戏逆向工程从技术挑战变为开发利器 当游戏开发者面对一个加密的Godot项目包或是需要从已发布的游戏中提取学习资源时传统方法人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务如何永久保存微信聊天记录WeChatMsg完整备份与AI数据管理指南如何永久保存微信聊天记录WeChatMsg完整备份与AI数据管理指南 你是否曾担心那些珍贵的微信对话会随着时间流逝而消失与亲友的温馨对话、工作群的关键信息、人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务从0到运行loop-engineering快速上手一条npx命令生成STATE.md并获取Loop Ready评分从0到运行loop engineering快速上手一条npx命令生成STATE.md并获取Loop Ready评分 loop engineering 是一个人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务上一篇解决VR游戏卡顿问题VR Performance Toolkit实用案例分享下一篇f8/f8app中的API封装统一请求处理与错误管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考