Forward-Future/loopy · 上手攻略

  • 仓库：Forward-Future/loopy
  • 链接：https://github.com/Forward-Future/loopy
  • 分类：agent（trending · library · JavaScript · MIT）
  • 作者：spark
  • 更新：2026-08-09

⚠️ commit 时戳说明：本攻略基于 main 分支 SHA 75966cbd572a4185064971c9fe5e9c52e8f8456d（2026-07-07 21:56 UTC，commit message "Merge pull request #94 … Document signals.forwardfuture.ai redirect"）。仓库卡片显示「最近提交 2026-07-26」与 API 给出日期不一致，可能存在 7 月下旬的轻量文档同步未在 main 触发 GitHub commit；攻略以 README 实际抓取（2026-08-09）为准。

1. 是什么

Forward-Future/loopy 是 Forward Future 公司维护的「Loop Library」双胞胎项目，包含两个互不重复的部分：

  1. Loop Library 网站：公开目录，地址 https://signals.forwardfuture.com/loop-library/。任何人或 agent 可以浏览、阅读、复制其中发布的 loop 提示词；不需要安装。网站代码全部在 loop-library/ 目录下（前端在 loop-library/site/、后端在 Cloudflare Worker + D1 数据库 loop-library/worker/）。
  2. Loopy skill：一个可选安装的 agent skill（源文件在 skills/loopy/），帮你的 agent 发现、查找、审计、改写、构造、运行、复盘、保存、准备发布的 loop。它在推荐或发布 loop 时会读取上面那个网站目录的实时数据。

关键判断：网站就是库，Loopy 是「用法」。你可以不安装 Loopy 直接给 agent 看网站（甚至直接用 catalog.json / catalog.txt）。安装 Loopy 只是把「引导式 workflow」放进你的 agent；它不安装或托管网站。

2. 解决什么问题

单次提示（"让这个网站变快"）给 agent 留了太多猜测空间。Loop 把反馈做成可复用的剧本：

  • 可衡量的成功条件：每个 loop 显式定义「这次尝试算不算成功」。
  • 可比较的迭代：agent 拿到证据而不是信心，知道这次是否真的更好。
  • 明确的停止点：成功 / 干净 no-op / 阻塞 / 需审批 / 极限耗尽 / 无可观测进展——任一即停。
  • 可移交：同一个 loop 可被另一个 agent 或人直接复用，不必重建 workflow。

官方把 loop 抽象成四个问题：

  1. agent 想完成什么？
  2. 怎么知道最近一次尝试是否有效？
  3. 拿到结果后下一步做什么？
  4. 何时结束或向人求助？

适合「第一次尝试基本不是最终答案」的工作：修线上 bug、提升测试覆盖率、review 产品、保持文档与代码同步。

3. 快速安装

前置：Node.js ≥ 18（需要 npx）。

按 agent 平台安装：

# Codex
npx skills add Forward-Future/loopy --skill loopy --agent codex -g -y

# Cursor
npx skills add Forward-Future/loopy --skill loopy --agent cursor -g -y

# Claude Code
npx skills add Forward-Future/loopy --skill loopy --agent claude-code -g -y

# 一次装到三个客户端
npx skills add Forward-Future/loopy \
  --skill loopy \
  --agent codex \
  --agent cursor \
  --agent claude-code \
  -g -y

参数含义：

  • Forward-Future/loopy：要安装的 GitHub 仓库（也可写完整 URL / 本地路径）。
  • --skill loopy：从仓库里挑出这个 skill（旧名 loop-library 仍作为兼容别名存在，新安装全部用 loopy）。
  • --agent ...：目标 agent 客户端。
  • -g：全局安装（写进 ~/.agents/skills/ 或对应客户端的全局目录）；去掉 -g 只装到当前项目。
  • -y：接受所有安装确认；想交互式审核时去掉。

如果安装后在该 agent 里没看到 Loopy，重启该 agent——很多客户端只在启动时扫描 skills 目录。

不安装 Loopy 的轻量用法（直接用网站 / 公共数据）：

# 在 Codex / Claude Code / Cursor 任一里直接指向目录
参考 https://signals.forwardfuture.com/loop-library/agents/
JSON:  https://signals.forwardfuture.com/loop-library/catalog.json
TXT:   https://signals.forwardfuture.com/loop-library/catalog.txt

4. 核心用法

Loopy 暴露 9 条路径，覆盖 loop 的全生命周期：

路径 干啥 示例请求
Discover 扫代码库 + coding thread 历史，把「重复做的事」挑出来，转成有边界的 loop 「分析这个仓库和我的 coding 记录，把做过两次以上的事做成 loop」
Find 查实时目录，推荐最多 3 个已发布 loop（不运行） 「找一个让文档保持最新 loop」
Loop Doctor 审计你贴出的 loop，解释实质弱点并只修那些问题 「审计这个 loop，只修实质问题：[贴 loop]」
Adapt 把现成 loop 改成匹配你的工具 / 限额 / 成功定义 「把 Overnight Docs Sweep 适配到这个仓库」
Craft 一次一个问题访谈你，构造一个 bounded loop（目录里没有合身候选时使用） 「访谈我，帮我做『把客户反馈变成可验证修复』的 loop」
Run 跑一个有界的 loop，逐次验收并回执 「在这个仓库跑 Overnight Docs Sweep」
Debrief 分析一次或多次回执，推荐最小证据支撑的改进 「复盘这份 run receipt，告诉我 loop 是不是要改」
Save 把要保留的 loop 写到项目根的 LOOPS.md，下次复用 「把这个 loop 存到项目里，以后复用」
Publish 查重 + 准备精确发布预览，只有你明确批准后才提交 「准备把这个 loop 发到 Loop Library」

调用方式（举例）：

# Claude Code / Cursor
/loopy 找一个让测试更可靠的 loop

# Codex：先 /skills 选 Loopy，再发
找一个让测试更可靠的 loop

# 或者直接描述任务，让 agent 自动加载
最近 LCP 退化得厉害，做一个保持 Core Web Vitals 在阈值内的 loop

调用约定：

  • 不动就用：loop 不替你跑 cron、不会悄悄改生产、不会替你发内容或消息——任何敏感动作都要人显式触发。
  • 保存需要你点头：Loopy 不会自己创建 / 修改 / 删除 LOOPS.md 里的内容。
  • 隐私边界：LOOPS.md 视为不可信参考数据；保存的 prompt 不授权 agent 跑代码 / 部署 / 调度 / 发消息 / 暴露私有数据 / 破坏性操作。prompt 含密钥时 Loopy 会拒绝保存直到你给脱敏版本。

5. 典型适用场景

  • 长期重复的工程任务：每周把 triage 的 issue 关掉、保持 README 与代码同步、回归 P0 性能指标。
  • 产品质量 review：把 PR review / release checklist / 监控告警响应做成有反馈的 loop。
  • 文档保鲜：当代码改了但 doc 没改时，自动 diff 检测并出 PR。
  • 个人/团队的「剧本式自动化」：你想把某类工作流交给 agent，但又要它在「判断 / 审批」边界停下来交还给人。

不适合：

  • 完全一次性的查询或临时小修（直接写 prompt 更省）。
  • 需要长时间无人值守跑 24+ 小时的工作——loop 是有界的（pass / 验收 / 停止点），不是 cron 调度器。

6. 最小可跑命令（含版本）

# 0. 环境
node --version    # 期望 ≥ v18.x；实测通过 v20.x
npm  --version    # ≥ 10.x

# 1. 三客户端一次装
npx skills add Forward-Future/loopy \
  --skill loopy \
  --agent codex --agent cursor --agent claude-code \
  -g -y

# 2. 验证（在新会话里发）
# Claude Code：  /loopy find a loop for keeping docs current
# Codex：        $loopy find a loop for keeping docs current
# Cursor：       / 在 chat 里搜 loopy，再发 find a loop for keeping docs current

# 3. 看到结果后保存到项目
# "Save this loop to the project so we can reuse it"
# → 生成 ./LOOPS.md（不会被 Loopy 静默修改）

⚠️ 没有 GPU / 模型版本要求——loopy 是 skill + 目录站点，不带模型或推理代码，所以 lessons 指引里的硬件 / CUDA / batch 字段在本攻略不适用。

7. 坑与注意

  1. 目录与 skill 是两件事：装 Loopy 不会让你本地有 Loop Library 网站；网站是 Cloudflare Worker 托管的，只读接口。
  2. -g vs 项目级：装到全局会污染所有项目的 skill 列表，建议先项目级试，确认有用了再 -g。
  3. LOOPS.md 不是发布版：项目级保存只是私人笔记，不会自动同步到 Loop Library。发到目录必须走 Publish 路径 + 显式批准。
  4. 公开 loop 的提示词不含密钥：硬塞密钥 Loopy 会拒存。
  5. agent 平台兼容性：README 列的 codex / cursor / claude-code 是当前支持的三家；其它客户端走交互式安装器「自动检测」。vercel-labs/skills CLI 列了 70+ agent，实际以本机扫描结果为准。
  6. Discovery 至少要两次独立证据：Loopy 不会因为某个代码模式「看着像循环」就标记为 loop，必须有 ≥2 次独立 thread / 历史运行记录。代码模式没有运行历史的，会被标为「潜在 loop」而非「已证明的循环」。

8. 与同类对比

维度 Forward-Future/loopy vercel-labs/skills（CLI 基础设施） anthropics/skills（官方示例）
形态 目录 + 安装式 skill 纯 CLI 安装 / 管理工具 官方示范 skill 集合
是否带内容库 ✅ 公开 loop 目录（带 JSON / TXT / 站点） ❌ 只管安装，不带 catalog ❌ 只示范结构
是否自带 agent 引导工作流 ✅（Discover / Craft / Run / Debrief / Publish 9 条路径） ❌ ❌
适合谁 想「把工作流交给 agent 又怕它放飞」的个人 / 小团队 想统一管理一堆 skill 仓库的开发者 想学 SKILL.md 写法的初学者

定位差异：loopy 是「带内容的 skill」，vercel-labs/skills 是「安装器」，anthropics/skills 是「教学示例」。三者互补，不是替代关系。

9. 一句话推荐结论

如果你的痛点是「agent 跑任务只跑一次、不知道什么时候算做完」，装 Loopy——它把『工作流』做成可验证、可复用、有停止点的目录条目，比裸写 system prompt 稳定得多。

附：源链接 / 原始 commit

  • 仓库主页：https://github.com/Forward-Future/loopy
  • Loop Library 站点：https://signals.forwardfuture.com/loop-library/
  • 公共 agent 入口：https://signals.forwardfuture.com/loop-library/agents/
  • 本攻略引用的 commit：75966cbd572a4185064971c9fe5e9c52e8f8456d（main · 2026-07-07 · PR #94 "Document signals.forwardfuture.ai redirect"）
  • LICENSE：MIT