looper

Looper

将 Looper 用作循环设计教练和脚手架工具。在设计过程中进行访谈、评审、验证并编写文件。生成文件后，询问用户是否要在当前会话中使用 RUN_IN_SESSION.md 运行循环；将 run-loop.py 保留为高级外部运行器。

工作流

1. 从 /looper 参数中解析目标路径和可选的 --template <name>。如果未指定目标，使用 ./looper-output。如果目标中已有 loop.yaml，则将任务视为编辑／续接，而不是从头搭建脚手架。如果指定了模板，则按下文的“模板模式”操作，跳过第 3 步中的空白起步访谈。
2. 仅在进入相应阶段时加载相关评估标准：
   • 目标阶段：references/goal-rubric.md。
   • 验证阶段：references/verification-rubric.md。
   • 评审团阶段：references/council-rubric.md。
   • 控制阶段：references/control-rubric.md。
   • 模型检测或隐私详情：references/model-detection.md。
3. 分七个阶段进行访谈：目标、验证、宿主模型、评审团、门控／控制、确认流程预览、生成／运行选项。在控制阶段，说明执行边界、隔离、无进展信号、状态和运行日志。
4. 在接受每个阶段的内容前先进行评审。优先给出具体替代方案，而不是含糊的警告。推动不完善的目标明确结果、范围、上下文和完成状态。验证方面优先采用程序化检查，其次是评审标准，最后是人工签核。
5. 区分评审者和裁判的职责。评审者撰写备注。裁判返回结构化判定。revise_until_clean 必须将某个裁判成员或 human 指定为 verdict_source。
6. 要求设置多个终止防护措施：max_iterations、每个门控的修订上限、无进展时停止，以及预算上限或明确的人工停止点。
7. 在选择任何跨厂商评审团成员前，说明哪些上下文会离开用户的设备、哪个 CLI 会接收这些内容、适用哪些脱敏 glob，以及两种执行路径都需要在首次发送前取得同意。
8. 展示计划循环的 ASCII 流程预览，并在最终生成前征求确认。优化内容以便在 Claude Code CLI 中阅读。
9. 在目标目录中生成以下文件：
   • loop.yaml
   • loop.resolved.json
   • LOOP.md
   • RUN_IN_SESSION.md
   • run-loop.py
   • loop-workspace/
   • README.md
10. 写入 loop.yaml 后，解析辅助 Python（见下文“辅助 Python”），并运行： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md 然后运行： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml 并转达检查结果：继续前先修复所有 error[...]（否则规范的实际行为会与描述不符），并向用户展示 warning[...] 行，作为可接受或处理的设计建议。
11. 询问用户是否要现在在当前会话中运行循环。如果是，直接按照 RUN_IN_SESSION.md 执行当前任务。如果否，则说明该文件也是便捷的重启入口，并且 run-loop.py 可用于高级外部执行。

模板模式

模式库位于 ${CLAUDE_SKILL_DIR}/templates/loops/ — 每个模板对应一个目录，其中包含完整且可编译的 loop.yaml（使用 {{PLACEHOLDER}} 标记项目专属的插槽）、README.md（使用场景、占位符表、自定义说明），以及可选的辅助检查脚本目录 scripts/。模板目录索引为 templates/loops/README.md。

模板是预先回答问题的访谈流程，而不是绕过设计审查的捷径：

0. 如果目标目录已包含 loop.yaml，则以第 1 步中的编辑／恢复规则为准：不要用模板覆盖它。告知用户该目录已有 loop，并请用户选择一个空目标目录，或确认要替换后再继续。
1. 如果 --template 未指定名称、名称未知，或用户询问有哪些可用模板，则显示目录表格（模板 + 使用场景），让用户选择。
2. 阅读模板的 loop.yaml 和 README.md。以模板为起点，而不是使用空白规格。
3. 用精简访谈替代七个从零开始的阶段：询问模板 README 中列出的每个 {{PLACEHOLDER}} 插槽；针对检测到的 CLI 运行主机模型阶段（detect-models），并将 host／council 调用替换为实际已安装且已通过身份验证的工具；然后确认目标路径和工作区路径。
4. 访谈后的所有步骤仍照常适用：根据对应准则审查每个预填阶段（第 4 步）、结构规则（第 5–8 步，包括跨供应商出口声明）、ASCII 流程预览、确认、生成和编译。
5. 只要 loop.yaml 中仍有任何 {{ 标记，就绝不生成。此时编译器会打印 looper: warning: unresolved template placeholders remain ... — 将此警告视为阻断项，而非建议。
6. 生成时，如果模板包含 scripts/ 目录，则将其复制到 <target>/scripts/，与标准生成文件放在一起，然后再运行编译。

文件规则

• 所有模型和检查调用都必须使用 argv 数组，绝不要使用 shell 命令字符串。
• 不要将 API 密钥、访问令牌、密码或 CLI 身份验证凭据写入 loop.yaml、loop.resolved.json 或模型注册表。
• 默认脱敏 glob 为 .env、.env.*、secrets/** 和 **/*.key。
• 保持 loop.yaml 易于阅读，并在适当位置添加注释。生成的运行器只读取 loop.resolved.json。
• 将 RUN_IN_SESSION.md 作为默认／简易执行交接文档。它面向当前 LLM 会话，或供未来粘贴使用的提示词。
• 除非用户明确要求修改外部运行器契约，否则请原样复制 templates/run-loop.py。

辅助 Python

安装程序会在技能目录中创建一个私有 venv。在 macOS/Linux 上，其 Python 位于 .venv/bin/python；在 Windows 上，位于 .venv/Scripts/python.exe。命令之间的 Shell 状态不会保留，因此请在以下每次辅助调用前添加此解析步骤（适用于 POSIX shell 和 Windows 上的 Git Bash）：

LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/bin/python"; [ -x "$LOOPER_PYTHON" ] || LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/Scripts/python.exe"; [ -x "$LOOPER_PYTHON" ] || { LOOPER_PYTHON=python3; "$LOOPER_PYTHON" -c "" >/dev/null 2>&1 || LOOPER_PYTHON=python; }

最后的回退方式会实际执行候选程序，而不只是定位它：在 Windows 上，PATH 中的 python3 通常是 Microsoft Store 的别名存根；它虽然存在，却无法运行脚本。如果没有候选程序能够执行 -c ""，请告知用户重新运行 Looper 安装程序（它会创建 venv）。

辅助脚本

以下每条命令都假设在同一次 Shell 调用中添加了 Helper Python 解析器前缀：

• 检测模型 CLI： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py detect-models --write
• 注册自定义 CLI（如果调用包含标志，请将整个调用用引号括起来）： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py register-model <id> --invoke "<cmd> [args...]"
• 编译并渲染： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md
• 根据设计准则中的反模式进行检查（添加 --strict 可在出现警告时失败；添加 --json 可供工具使用）： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml
• 仅渲染会话内交接内容： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py session-prompt <target>/loop.resolved.json --out <target>/RUN_IN_SESSION.md

确认流程预览

使用此结构并自定义标签：

+--------------------------------+
| 1. Goal + context              |
| read sources                   |
+--------------------------------+
               |
               v
+--------------------------------+
| 2. Draft plan.md               |
| state -> state.json            |
+--------------------------------+
               |
               v
+--------------------------------+
| 3. Plan gate                   |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 2
               | pass
               v
+--------------------------------+
| 4. Write delivery-N.md         |
| log -> run-log.md              |
+--------------------------------+
               |
               v
+--------------------------------+
| 5. Delivery gate               |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 4
               | pass
               v
+--------------------------------+
| 6. Final output                |
| all gates clean                |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens

输出检查清单

• 目标有明确的结果、范围边界、上下文来源和完成状态。
• 验证标准的类型为 programmatic、judge 或 human。
• 至少有一项标准并非完全基于主观感受，除非用户明确接受此风险。
• 每个 revise_until_clean 门禁都有有效的 verdict_source。
• 每次外部调用都使用 argv 数组，并设置超时。
• 跨供应商的外传范围明确、经过脱敏，并以用户同意为前提。
• loop_control 设置了迭代、修订、无进展以及墙钟时间或预算上限。
• 明确说明执行边界和隔离方式，即使选择的是当前工作区也不例外。
• 可观测性部分列出 run-log.md 和 state.json 的路径。
• 交接前，loop.resolved.json、LOOP.md 和 RUN_IN_SESSION.md 均可成功编译。