loop-graph

loop-graph — 由 Agent 节点构成的图，而非不断漂移的循环

模块边界

这是共享编译器，而非针对特定目标的工作流。它负责图的结构、五种运行时工件架构、通用访谈机制和宿主交接。专用预设只负责自己的 North Star、证明、访谈问题、建议的工作形式、方法约束、参数和 slug；它绝不分叉模板，也不添加运行时节点。

代码清理请使用 ../loop-converge/SKILL.md，需求交付请使用 ../loop-deliver/SKILL.md，基于证据选择解决方案请使用 ../loop-research/SKILL.md。只有确实需要自定义包时，才直接使用此技能。具体约定见 docs/preset-contract.md。

功能与原因

将模糊的长期请求（“达到生产就绪”“准确率超过基线”“完成迁移”）转化为一个小型的Agent 节点图，让它在多轮执行中始终不偏离规范：

• 一个执行器节点——围绕单一计分板逐轮推进工作；
• 一个监督器节点——从执行器上下文之外审查工作（依据共享标准重新验证声称已完成的内容），并在偏差累积之前纠正方向。

为什么是图，而不是循环：持续攻坚长期任务的 Agent 身处已经发生偏移的上下文中，因此会合理化范围蔓延，并把只完成一半的工作称为“完成”。节点只通过持久、可检查的状态（台账、git 树、指令文件）通信——绝不共享受污染的上下文。

每个节点都有自己的计时器，节点之间绝不会相互唤醒。 执行器触发后，在温热的上下文中完成若干轮已验证的工作，然后结束。监督器按更慢的周期触发，进行审查、追加纠正内容，然后结束。执行器下次触发时会读取纠正内容。两个独立时钟和一条文件边——无需调度、恢复提示或存活协议，因此也不会出现运行等待一个永远不会到来的唤醒信号的情况。

构建的图

        ┌─────────────┐   reads / rewrites   ┌──────────────┐
        │  EXECUTOR    │ ───────────────────▶ │              │
        │  node        │ ◀─────────────────── │  ledger.md   │  ← single scoreboard
        │ (own timer)  │                      │ (shared state)│
        └─────────────┘                      └──────────────┘
              ▲                                      ▲
              │ reads each round                     │ reads only (never writes it)
              │                                      │
        ┌───────────────┐   appends corrections ┌──────────────────┐
        │ directives.md │ ◀──────────────────── │   SUPERVISOR     │  ← separate context,
        └───────────────┘                       │ node (own timer) │     slower cadence
                                                 └──────────────────┘
                                                     │ checkpoint-commits clean work
                                                     │ escalates human-only calls
                                                     ▼
                                                   git / you

通过简短访谈生成五种实时工件：

1. executor.md — 执行器提示词：一本任务手册、一种节奏、反膨胀规则、停止条件和红线。
2. ledger.md — 两个节点共同读取的唯一计分板；执行器每轮都会重写。
3. directives.md — 有界的单向纠正队列：当前的 STANDING 锁定项 + 尚未纳入的编号纠正；已纳入的纠正会轮换到冷归档。
4. ops.md — 每个冷启动节点都遵循的精确上下文索引和关卡， 以及适用时当前环境／数据／宿主的生命周期事实；原位更新事实， 绝不将其写成时间线。
5. supervisor.md（可选）— 按计划运行的监督器提示词；它会独立重新验证声称已完成的工作，为通过的工作创建检查点提交，判定待处理事项，并通过指令文件纠正偏差／引导计划。

运行目录——固定，每次运行一个。 上述所有内容都放入仓库根目录（多仓库运行时为工作区根目录）下的 .longgraph/<YYYY-MM-DD-slug>/，另加一个用于运行期间轮换的 archive/ 子目录。新运行始终根据模板创建 .longgraph/…——绝不将目标改向或编辑之前运行的文件：修补过时的提示词会浪费 token，还会留下引导新运行追随旧目标的残余文本。旧目录保持不变（它本身就是归档）；将仍然适用的内容提炼到新台账的起始快照中，并复制仍然有效的 STANDING 指令。除非数据政策禁止，否则请提交运行目录——图所依赖的持久状态就在其中。

运行时契约 ID 为 longgraph.loop-graph.*。

不变量：台账 = 唯一计分板；每轮处理一个可独立验证的工作项 （可以是一个连贯的工作集）→ 验证 → 更新台账；监督器只能通过 directives.md 引导（单向边）——绝不编辑台账，也不共享执行器的上下文。

适用场景

• 任务需要多轮执行；用户不会逐轮盯着进度。
• “完成”可以验证（测试、门禁、指标）——图需要一个可自行检查的完成定义。
• 存在真实的范围蔓延风险、工作“看起来已完成”，或悄悄更改约定／降低标准的风险。

不适用于一次性编辑，或每次都需要人工判断是否成功的情况——请说明原因，并建议使用普通任务。

语言

使用用户的语言进行访谈，并在产物中的文字（目标、备注、红线）里保持一致。模板中的结构关键词、标题和字段名称应保持原样，以确保文件便于工具处理。

从预设技能调用时

同级的创作技能（例如 loop-converge）可能会绑定一个 预设包，然后移交至此处。预设包遵循 预设约定；以下内容视为已回答：

• 北极星和证明——除非预设包未说明可检查的结果，否则跳过该访谈问题。
• 监督者——预设包要求时必须提供；不要询问是否省略。
• 方法约束——将预设包的约束附加为 PROJECT_SPECIFIC_METHOD_GUARDS。
• 参数覆盖——使用预设包中的数值，而非默认值。
• 推荐结构——将预设包的拆解方案（里程碑，或大范围执行时的轮换方案）作为 A 方案提出，除非检查发现存在实质性不同的方案。
• 产物重点——将预设包要求的事实整理到共享的 ledger.md、ops.md、directives.md、执行器和监督者部分；不要另建运行时模板或记分板。

仍需探索工作区。仍然最多向负责人提问三个问题；绑定预设包时，通常询问范围、权限和启动模式。仍需从此技能的 templates/ 生成——绝不使用第二套模板，也绝不添加第三个运行时节点。预设技能不会执行生成的节点。

运行方式

步骤 1 — 探索，然后访谈。 提问之前，先检查工作区以及当前系统／工具上下文。推断当前创作宿主、项目根目录、代码仓库、分支、未提交状态、仓库说明、可能的门禁，以及任何明确目标／约束。如果系统上下文已经标明当前客户端或宿主，绝不要再询问用户。 在本次会话进行任何更改前，记录未提交状态基线——之后你移动、归档、生成或删除的任何内容，都会与所有者未提交的工作无法区分，除非你自己的路径已列入账本的起始快照。创作探查必须不产生副作用：将临时输出直接写入新运行的证据目录，尽可能禁用工具缓存，并在移交前删除本次会话创建的已知产物。创作运行不得留下伪装成所有者工作的产品路径缓存。

提出一组简短问题，最多三个，只包含尚未解决且需要负责人决定的事项。先提出建议答案；不要让负责人来设计方案。如果剩余事项超过三个，优先询问目标／证明、安全权限和启动模式；其余事项自行推断或暂缓处理。只有在不追问就会导致运行不安全或无法验证时，才提出后续问题：

1. 北极星目标与证明，仅当请求尚未明确可验证的结果时提出。给出一个简洁的推荐表述。
2. 权限，仅在尚未说明时提出。建议默认值：允许本地编辑和验证；禁止推送、破坏性 Git 操作、生产环境或远程环境变更、暴露机密或真实数据、无上限支出，以及降低验收门槛。仅当运行需要提交时，才询问是否允许提交。当运行涉及按量计费或高成本工作时，将具体数字写入 ops.md——“超出预算”属于仅限所有者决定的触发条件，而未声明预算则无法执行这一约束。说明每项门槛的实际成本：金钱、耗时或风险。仅耗时的门槛应批量处理，而非限额——如果上限导致整个工作领域都无法触及，那就是伪装成预算的范围决策，应在范围答复中处理。
3. 里程碑，仅当存在两种实质不同的拆分方案时提出。将推荐的阶段拆分和退出检查列为 A；只有当 B 会改变结果或风险时才提供 B。单一目标不需要询问里程碑。按以下顺序安排：先完成能打通主线的最小切片；若在交付里程碑前安排大型的铺垫性重构，就会集中风险，并延后其后的所有验证。应将这类里程碑拆成范围狭窄的打通部分，以及与主线并行而非先行的剩余部分。
4. 启动模式，除非用户已选定：A（推荐）— 在检测到的 Codex 或 Claude Code 主机上创建两个运行时节点；B — 仅打印可直接复制的提示词。仅当用户选择 B 或明确要求跨主机运行时，才询问目标主机。

如果仓库路径、分支、主机、测试命令、红线或执行频率可以通过检查发现，就不要询问。若检查后仍缺少或无法明确某项门槛，提出最窄且可信的命令，并让用户在 A/B 中选择。长周期循环图运行默认包含监督器；仅当其价值确实存疑时，才询问是否省略。

对于每个受监督的里程碑边界，明确列出其精确的晋级审核范围和退出检查。预期运行会频繁阻塞——所有者决策、缺失输入、未满足的依赖项、正在审核的里程碑：用足够多真实且相互独立的工作项填充“债务与缺口登记表”，确保执行器始终有合法的下一项工作，而不是过早结束任务。

必须通过发现来确定工作内容时，预先安排方法，而非清单。 对于需要发现工作项的运行（死代码、重复内容、覆盖率缺口、过时配置），你看到的只是运行将反复遍历的树的一个上下文窗口，因此手写候选清单会成为运行的上限：执行器完成清单后就会报告结束。将检测器、补充配额（完成 N 项 → 至少发现 N 项）和覆盖整个范围的轮换机制写入 ops.md 和台账，并用方法和测得的基线填充登记表。将终止条件设为产出检查——连续两次完整扫描中，新的检测器运行产出都低于阈值；绝不能以队列为空为终止条件。为每轮任务配套设置最低产出要求，让生产力而非轮数决定何时结束。固定仅限所有者决定的事项清单（通常包括：DDL/模式、凭据 / 远程环境 / 真实数据暴露、超出预算的支出、降低指标门槛、冻结的契约、推送）——清单之外的事项由监督器自行决定。

• 立即预先裁定关键路径上的调用。 研究项目并自行拟定证据门槛；不要要求所有者来设计。请提供：A（推荐） 接受拟定的常设授权，B 保持该操作处于所有者阻塞状态；只有确有必要时，才提供 C 明确不同的安全替代方案。用通俗语言说明每种结果，并接受一个字母作为回复。将获批的门槛写成 STANDING 指令。只有确实需要逐案由人工判断的决策，才应保持阻塞状态。
• 所有者决策 UX 是运行时契约。 之后每次向所有者升级请求，都必须使用下方的决策卡格式。所有者不应需要理解内部符号、重建历史或提出解决方案。

Decision needed: <one plain-language sentence>
Why now: <what is blocked and what happens if we wait>
Recommendation: A — <choice> (<one-sentence reason>)
A (Recommended) — <outcome and main tradeoff>
B — <outcome and main tradeoff>
C — <only when genuinely distinct; otherwise omit>
Reply with: A / B / C

最多提供三个互斥选项。除非证据明确支持其他选项，否则将最安全且可逆的选项放在首位。将技术证据转化为后果；路径、命令和术语放在选项之后的可选 Technical note 中。结尾绝不要问“你怎么看？”，也不要让所有者自行编出选项 D。如果没有收到回复，则运行停留在安全且不作更改的状态。

主机与频率。 根据系统上下文和可调用工具推断当前创作主机。Codex 和 Claude Code 是受支持的直接启动规划器。选择 A 时，将两个运行时节点都放在检测到的主机上，并且只读取该主机的参考资料；不要询问或打印其他主机的语法。选择 B 或明确要求跨主机时，为每个选定节点读取一份参考资料：

• Claude Code
• Codex
• Grok Build
• Cursor
• shell / cron

不要加载无关的主机参考资料。所选参考资料规定能力检查、节点创建，以及每个节点如何启动和停止自己的计时器。其他主机可以执行准备好的提示词，但只有 Codex 和 Claude Code 支持直接创建。

设置两个频率。计时器确保节点会再次运行，但不会控制其节奏。EXEC_INTERVAL 表示一次执行结束后，执行器多久返回；该间隔应较短，因为决定工作量的是执行本身，而非间隔。SUP_INTERVAL 设为它的 3–4 倍，并错开相位，使监督器能在一次长时间执行期间多次审计。

按执行时长确定里程碑规模，而不是按轮数确定执行时长。 一轮仍是一个可独立验证的工作项；该项可以是共享同一行为声明、写入集和门禁的最大相关工作集。每次执行边界都会产生一次冷启动重新推导，因此一次执行应覆盖完整里程碑，并在一个衔接点结束——里程碑出口，或已闭合的收敛轮次。这样一来，里程碑粒度就成为真正影响上下文成本的杠杆：如果执行器不太可能在一次预热执行中完成某个里程碑，就应将其拆分；FIRE_ROUND_CAP 只会结束当前执行，绝不会结束整个运行。

编译上下文，不要叙述上下文。 主机提示词应是指向运行时 Markdown 的单行指针。在创作时，构建 ops.md 上下文索引，列出精确的文件、符号／标题、证据路径和精简门禁。每个 Current 切片和修正都应引用这些 ID。运行时节点只读取热状态及所引用的条目；不得扫描工作区、重新打开完整的权威文档或复述源文本。监督器审计自其持久水位标记以来的增量，并且只在晋级／检查点时，或精简门禁不足时运行完整门禁。

根据上下文决定合理范围内的事项，并说明所依据的假设；任何确实应由用户决定的事项（数据政策、数据库访问权限、降低门槛）都应成为红线、常设授权（将你拟定的建议作为选项提供），或 owner-blocked 项（仅限确实无法预先裁定的情况）。绝不要把没有结构的问题直接交给所有者。

步骤 2 — 生成一个全新的 .longgraph/<YYYY-MM-DD-slug>/，内容来自 templates/：

• 始终包含：executor.md、ledger.md、directives.md、ops.md 和 archive/。 仅在选中监督器时添加 supervisor.md。
• 替换所有占位符并删除指导性注释。路径必须位于运行目录内。
• 主机启动提示词只保留一个指向文件的说明和主机原语。行为写入 executor.md/supervisor.md，绝不能在交接提示词中重复。每条启动提示词都必须注意两点：要求读取并遵循，绝不使用创作类动词（“设置”“创建”“撰写”“规划”会被理解为允许构建某些内容，而新节点会通过创建第二个运行实例来响应）；以及**“不要加载任何技能”**，因为按名称或路径匹配技能的主机，可能会在节点打开自己的文件前注入创作技能。
• 在支持 /loop 的每种主机上，面向用户的粘贴内容都必须是一行 /loop 命令。 格式： /loop {{INTERVAL}} Execute the existing runtime node at {{PATH}}. Do not load any skill. 执行频率、计时器 ID 记录、自行停止和新鲜度要求都应放在 TIMER_STEP 或节点文件中——绝不能将它们作为额外的用户操作（例如“将此 ID 写入 ops.md”“然后创建计划任务”）。Codex 不支持 /loop：用户粘贴的内容应是一行简洁的读取并遵循指令。只有当用户明确提出要求时，才提及创建计划任务或自动化；编译后的 TIMER_STEP 负责为 Codex 启用计时器。
• 在写入第一条 ledger 记录前，先编写 ops.md 中的上下文索引。每行都应注明何时读取、精确的来源指针和精确的验证方式。ledger 的当前切片和每条指令都必须引用这些行。
• 调整各项参数；否则使用 FIRE_ROUND_CAP=8、CONVERGE_EVERY=5、NET_LINE_CAP=400、KEEP_ROUNDS=5、OPEN_DIRECTIVE_CAP=8、STANDING_CAP=12、GAP_CAP=12 和 FILE_LINE_CAP=200。开放式运行还要设置 FIRE_OUTPUT_FLOOR（一次 fire 必须完成的项目或净增行数，达到后才可结束）和 YIELD_FLOOR（每轮扫描的发现数低于此值时，运行才可进入终止状态）。
• 每个持久化章节都必须有上限，并按确实会触发的规则轮换。 按数量上限轮换——超出 KEEP_ROUNDS 的轮次和序号小于或等于已折叠水位的更正内容移至 archive/；STANDING 和差距登记表必须设上限并原地重写；任何活动文件不得超过 FILE_LINE_CAP 行。依赖可能永远不会达到的边界（固定分片大小、可能延后的里程碑）的规则等同于没有规则：文件会持续增长，直到节点读取时被截断，悄然漏掉最新条目。每轮都会重新读取且只能不断增长的内容属于缺陷，而非风格选择。
• 根据选定的参考资料填写 TIMER_STEP。仅当节点无需启用、记录或停止任何事项时，才删除它。如果节点仍须写入自己的计时器 ID 或删除自己的任务，即使启动行已有 /loop 间隔，也不能因此删除 TIMER_STEP。绝不能要求用户将任务、会话或自动化 ID 输入 ops.md。与主机相关的事实应放在参考资料中，而非通用模板中。
• 如果执行器可能启动只读子任务，则在 ops.md 中将主机的低成本模型档位命名为 FANOUT_TIER；如果主机没有低成本并发档位，则删除此章节。只读调查任务使用低成本模型；执行器本身不使用。
• 仅将 templates/handoff.md 渲染为聊天回复。它是展示模板，不是运行时文件：绝不能将 handoff.md 保存到运行目录中。如果未选择监督器，则删除其中的监督器章节和 To steer 行。
• 保持热文件精简：仅保留当前状态、未解决条目、近期轮次和尚未消费的指令。

步骤 3 — 交付时，不要让用户自行摸索工作流。 仅在用户尚未选择时提供以下选项：

• A（推荐）——在此处创建两个节点，适用于检测到的主机为 Codex 或 Claude Code。
• B——仅提供提示词，适用于用户将在其他位置启动节点的情况。

绝不要以“文件已生成”作为结束。明确说明下一步操作，并提供可直接复制的提示词。

• 在此创建这两个节点： 将用户的 A 选项视为创建两个范围内运行时会话的授权。遵循所选参考中的有序能力检查和创建协议。使用当前项目／检出；不要创建跨主机提示词，也不要悄悄切换到工作树。验证两个节点均已启动，并报告它们的 ID、各自的周期，以及如何停止它们。无需再次请求确认。
• 仅提供提示词： 在聊天中呈现完整的 templates/handoff.md，但不要持久化。必须说明需要打开多少个会话／任务／进程、每条提示词应放在哪里、哪些内容会自动继续、如何停止，以及如何调整方向。绝不要要求负责人填写主机 ID，或创建已由编译后节点负责的计时器。
• 绝不要留下 {{PLACEHOLDER}} 文本，也不要只告诉负责人“启动循环”。执行器和监督器须在不同上下文中运行；有条件时，使用低成本／快速的执行器和能力强的监督器。

让它奏效的规则（已编码在模板中）

• ledger.md 是唯一且有界的计分板；由执行器写入，监督器绝不写入。
• 每轮只处理一个可独立验证的工作项：实现、验证、记录。 相关工作集共享一个行为声明、一组写入内容和一道门禁；无关工作 则分开处理。将旁支差距登记下来，留待之后处理。
• 每个节点负责一个计时器，且只唤醒自身；受阻工作应转入已登记的工作通道，而不是结束本次触发。
• 根据监督器审计的持久状态推动收敛；对成本高昂的批次先进行试点；在扩展新功能面之前，必须有真实使用者。
• 只统计在声明的真实集合上可复现的证据。
• 预先授权可核查的负责人决策；将真正的例外作为建议的 A／B／C 选项提出。
• 保持监督器的上下文独立；它负责重新验证，只通过指令引导，并在达到终止状态时停止自己的计时器。

此技能中的文件

• templates/ — 与主机无关的运行时工件，以及仅用于聊天的启动提示词模板。
• references/ — 每个主机对应一个小型、独立加载的文件。
• methodology.md — 深入说明（每条规则的由来，以及它防止的故障模式）。
• examples/add-tests-to-cli/ — 一个完整的通用示例。
• examples/migrate-blob-storage/ — 一个更完整的示例：里程碑、试点批次、监督器指令的实际应用，以及不可跳过的里程碑门禁；在监督器完成审计并放行之前，该门禁会阻止继续。