Loop Library 0.1.1 中文教程：选择、安装与验证 Agent 循环

Loop Library是可重复 Agent 工作流目录，不是后台调度器。它收录工程、评估、运维、内容和设计循环，并提供 CLI 来推荐、搜索、查看和适配。2026 年 9 月 23 日核对时，npm 最新版为 0.1.1，发布于 6 月 22 日；GitHub 没有 release，仓库 package.json 仍可能显示 0.1.0。

路径一：用一次性 CLI 选择循环

node --version
npx loop-library@0.1.1 recommend "修复一个有回归测试的 CLI bug" --json
npx loop-library@0.1.1 search "verification" --json
npx loop-library@0.1.1 show LOOP_SLUG --text
npx loop-library@0.1.1 adapt LOOP_SLUG "只允许修改 src/，最多三轮"

CLI 需要 Node.js 20 以上，包本身零运行依赖。recommend 的 JSON 预期包含候选 slug、useWhen、prompt、matchedFields 和 scores；字段存在只证明目录查询成功，不代表推荐一定适合。打开候选全文，确认每轮产生什么、怎样验证、失败后做什么、何时停止。adapt 输出是草案，尤其要人工补足允许目录、命令白名单、轮数、金额或 token 上限，以及需要人工接管的状态。

路径二：安装成 Agent Skill

npx skills add khoantd/loop-library --skill loop-library -g

全局 Skill 让多个项目中的兼容 Agent 读取推荐流程。安装前先审读仓库中的 SKILL.md；安装后在临时仓库提出“推荐一个 loop，不执行”，确认宿主只返回候选和理由。全局安装扩大了可见范围，但不会赋予新的工具权限。若团队需要可重复构建，记录 0.1.1、来源仓库和已采用的 loop slug；不要让全局 skill 自动替换项目中已经审阅的版本。

离线、在线和执行边界

CLI 带内置 catalog，默认可离线查询。--online 会尝试获取实时目录，失败时回退内置数据；严格离线环境不要加该选项，并单独限制宿主 Agent 网络。循环文本可能要求调用测试、浏览器、Git 或第三方 API，这些动作的风险来自执行阶段。用于内容更新时，可把循环限定为读取已有草稿、检查来源和输出补丁；发布、部署和对外发送保留人工步骤。

排错、验证和升级

npx 找不到包时先检查 Node 版本和 npm registry；查不到 loop 时运行 list，确认 slug 拼写，并比较默认与 --online 的目录来源；JSON 被终端说明污染时明确加 --json，供脚本解析前先用 jq 验证。实际循环验收要记录初始输入、每轮变更、验证命令、失败状态和停止原因。升级前保存输出，固定安装 0.1.1 或目标版本，针对同一任务重跑 recommend/show 和一个小样本；不要因为推荐分数变化直接替换已验证流程。

与 GSD Pi 的实际区别

GSD Pi 是可运行的终端开发 Agent 与项目工作流，维护 .gsd/ 状态、计划、验证证据和 worktree 自动化。Loop Library 是跨领域循环目录，重点是“选哪种反复工作法”，本身不保存项目状态也不执行任务。需要完整的软件项目推进与 Git 隔离时，GSD Pi 更接近成品；已经有 Agent，只想给研究、内容、运维或设计任务补上验证和停止条件时，Loop Library 更轻。

常见问题