fable-loop
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFable Loop
Fable Loop
Repeat a check only when repetition can reveal new state, with explicit termination, backoff, error classification, and zero ambiguity about why the loop stopped.
仅当重复检查能够揭示新状态时,才应重复执行检查;必须明确终止机制、退避策略和错误分类,并清楚说明循环为何停止,不留下任何歧义。
Mission
目标
Polling is not "run the same command until it turns green." A good loop models a changing external condition, distinguishes pending from failure, respects rate/cost budgets, and terminates on success, terminal failure, cancellation, or exhausted budget.
If repeated execution cannot produce new information, the task belongs in diagnosis—not a loop.
轮询并不是“不断运行同一条命令,直到它变为成功”。一个好的循环应对不断变化的外部条件建模,区分“等待中”与“失败”,遵守速率/成本预算,并在成功、终止性失败、取消或预算耗尽时结束。
如果重复执行无法产生新信息,则应进行诊断,而不是使用循环。
Activate When
启用条件
- waiting for CI/deployment/build/batch-job state to change;
- monitoring a bounded asynchronous operation;
- checking eventually-consistent external state;
- repeating a safe measurement while a known process progresses;
- running a finite stabilization sample where repetition itself is the measurement.
- 等待 CI、部署、构建或批处理任务的状态发生变化;
- 监控有界的异步操作;
- 检查最终一致的外部状态;
- 在已知进程推进期间重复执行安全的测量;
- 运行有限的稳定性样本,且重复本身就是测量方式。
Do Not Activate When
不应启用的情况
- one command/probe is enough (/
fable-run);fable-verify - the same deterministic failure is repeating with no external state change ();
fable-recover - user expects a future notification/scheduled task rather than an in-session bounded loop;
- polling would create repeated non-idempotent side effects;
- no termination criteria or budget can be defined.
- 执行一次命令或探测已经足够(/
fable-run);fable-verify - 同一种确定性失败在外部状态没有变化时反复出现();
fable-recover - 用户期望在未来收到通知或执行定时任务,而不是在当前会话中运行有界循环;
- 轮询会反复产生非幂等副作用;
- 无法定义终止标准或预算。
Loop Classification
循环分类
| Loop type | Success/terminal semantics |
|---|---|
| CI/build | pending → success or terminal failure/cancelled |
| Deployment | progressing → healthy/rolled back/failed |
| Batch job | queued/running → completed/failed |
| Eventual consistency | old state → expected state within deadline |
| Rate-limited API | pending/retryable → success or terminal auth/schema error |
| Stabilization sampling | N bounded observations → distribution/variance verdict |
| 循环类型 | 成功/终止语义 |
|---|---|
| CI/构建 | 等待中 → 成功,或终止性失败/已取消 |
| 部署 | 进行中 → 健康、已回滚或失败 |
| 批处理任务 | 已排队/运行中 → 已完成/失败 |
| 最终一致性 | 旧状态 → 在截止时间内达到预期状态 |
| 受速率限制的 API | 等待中/可重试 → 成功,或遇到终止性的认证/Schema错误 |
| 稳定性采样 | N 次有界观测 → 得出分布/方差结论 |
Protocol
协议
Stage 1 — Define the state machine
阶段 1 — 定义状态机
Before iteration, enumerate:
- success state;
- pending/retryable states;
- terminal failure states;
- malformed/unknown states;
- cancellation condition.
A loop that treats every non-success as "try again" is unsafe.
迭代前需要枚举:
- 成功状态;
- 等待中/可重试状态;
- 终止性失败状态;
- 格式错误/未知状态;
- 取消条件。
将所有非成功状态都视为“再次尝试”的循环是不安全的。
Stage 2 — Set budgets
阶段 2 — 设置预算
Define at least:
- maximum elapsed time/deadline;
- maximum iterations or request budget where relevant;
- initial interval/backoff policy;
- maximum interval;
- API/cost/rate constraints.
Use the stricter bound when several apply.
至少需要定义:
- 最大经过时间/截止时间;
- 适用时的最大迭代次数或请求预算;
- 初始间隔/退避策略;
- 最大间隔;
- API/成本/速率限制。
若同时适用多个边界,应采用其中最严格者。
Stage 3 — Check idempotency and side effects
阶段 3 — 检查幂等性和副作用
Polling operation should be read-only/idempotent. If the endpoint/command triggers work, separate trigger from status observation and ensure retries cannot duplicate the action.
轮询操作应当是只读且幂等的。如果端点/命令会触发工作,应将触发操作与状态观察分离,并确保重试不会重复执行该操作。
Stage 4 — Execute one iteration and classify result
阶段 4 — 执行一次迭代并分类结果
Record:
- iteration/time;
- observed state/value;
- transport/command result;
- classification: success / pending / retryable error / terminal failure / unknown;
- next delay/reason.
记录:
- 迭代次数/时间;
- 观察到的状态/值;
- 传输/命令执行结果;
- 分类:成功 / 等待中 / 可重试错误 / 终止性失败 / 未知;
- 下次延迟/原因。
Stage 5 — Apply backoff intelligently
阶段 5 — 智能应用退避
Use a fixed interval when the expected update cadence is known and inexpensive; exponential/backoff+jitter when rate limits/transient service errors matter.
Respect explicit /provider guidance where applicable. Do not make sub-second aggressive calls to a slow external job just because tools allow it.
Retry-After当预期更新节奏明确且成本较低时,使用固定间隔;当速率限制或瞬时服务错误成为重要因素时,使用指数退避并加入抖动。
适用时,应遵循明确的 或服务提供方指引。不要仅仅因为工具允许,就对缓慢的外部任务发起过于激进的亚秒级调用。
Retry-AfterStage 6 — Stop early on terminal information
阶段 6 — 遇到终止信息时提前停止
Exit immediately on:
- success;
- explicit failed/cancelled state;
- non-retryable auth/schema/permission error;
- user cancellation;
- budget/deadline exhaustion.
Do not consume remaining iterations after the outcome is already known.
出现以下情况时立即退出:
- 成功;
- 明确失败或取消;
- 不可重试的认证/Schema/权限错误;
- 用户取消;
- 预算/截止时间耗尽。
结果已经确定后,不要继续消耗剩余迭代次数。
Stage 7 — Detect lack of progress
阶段 7 — 检测缺乏进展的情况
When a status includes progress/version/timestamp, compare across iterations. A long unchanged state near/after expected SLA may become a diagnostic signal rather than permission to extend budget automatically.
当状态中包含进度、版本或时间戳时,应跨迭代进行比较。如果状态长时间未变化,且已接近或超过预期 SLA,则应将其视为需要诊断的信号,而不是自动延长预算的依据。
Stage 8 — Produce an honest receipt
阶段 8 — 生成如实回执
Final receipt includes stop reason, elapsed time, iterations, last state, transient errors, and whether the condition was actually satisfied.
Timeout is not success. "Still running" is not failure unless the contract/deadline says so.
最终回执应包含停止原因、经过时间、迭代次数、最后状态、瞬时错误,以及目标条件是否确实得到满足。
超时不代表成功。除非约定或截止时间另有规定,“仍在运行”也不代表失败。
Decision Rules
决策规则
- Deterministic repeated failure with no changing external state → stop loop and recover.
- Retryable transport error may continue within budget; auth/permission/schema errors usually terminate until configuration changes.
- Treat provider or job-recommended poll interval as a lower bound where applicable.
Retry-After - Never repeat a non-idempotent trigger as a status poll.
- If each iteration costs meaningful money/quota, include cost/request budget, not only time.
- If expected completion exceeds the current session/task model, create a scheduled/condition-watch mechanism when available rather than pretending an in-session loop can run indefinitely.
- A loop may end ; do not extend bounds silently just to obtain green.
INCOMPLETE/TIMEOUT - If progress is unchanged and deadline still distant, continue according to policy without noisy user updates; surface only meaningful state changes for long interactive runs.
- 确定性重复失败且外部状态没有变化 → 停止循环并进入恢复流程。
- 可重试的传输错误可以在预算内继续;认证、权限或 Schema 错误通常应终止循环,直至配置发生变化。
- 适用时,将服务提供方的 或任务推荐的轮询间隔视为下限。
Retry-After - 绝不能将非幂等的触发操作作为状态轮询反复执行。
- 如果每次迭代会消耗可观的费用或配额,应设置成本/请求预算,而不只是时间预算。
- 如果预期完成时间超过当前会话或任务模型所能覆盖的时长,应在可用时创建调度/条件监听机制,而不是假装会话内循环可以无限运行。
- 循环可以以 结束;不要为了得到成功结果而静默延长边界。
INCOMPLETE/TIMEOUT - 如果进展未变化但距离截止时间仍较远,应按照既定策略继续运行,不向用户发送冗余更新;对于长时间运行的交互式任务,仅呈现有意义的状态变化。
Invariants
不变量
- Exit criteria and budgets are explicit before looping.
- Each iteration is safe/idempotent or side-effect semantics are explicitly controlled.
- Terminal failures stop immediately.
- Pending and failure are distinct states.
- Backoff/rate limits are respected.
- Receipt records actual stop reason; no timeout-to-pass conversion.
- 开始循环前必须明确退出标准和预算。
- 每次迭代都必须安全、幂等,或明确控制其副作用语义。
- 遇到终止性失败时立即停止。
- 等待中与失败是不同状态。
- 遵守退避策略和速率限制。
- 回执记录实际停止原因;不得将超时转换为通过。
Failure Taxonomy
失败分类
Infinite/implicit loop
无限/隐式循环
No enforceable budget. Reject and define bounds.
没有可执行的预算。应拒绝执行并定义边界。
Retry-all-errors
对所有错误重试
Auth/schema/permission/terminal job failures are treated as transient. Classify and stop appropriately.
将认证、Schema、权限或任务终止性失败视为瞬时错误。应进行分类并适当停止。
Duplicate side effect
重复副作用
Polling call re-triggers work. Separate status endpoint/idempotency key or stop.
轮询调用会重新触发工作。应分离状态端点或使用幂等键,或者停止轮询。
Thundering poll
惊群式轮询(Thundering poll)
Interval too aggressive for service/job cadence. Back off/respect provider guidance.
轮询间隔相对于服务或任务的更新节奏过于激进。应进行退避或遵循服务提供方指引。
False timeout diagnosis
错误的超时诊断
Job still pending within expected SLA but loop labels it broken. Report timeout/incomplete separately from product failure.
任务仍处于等待中且尚未超过预期 SLA,但循环却将其标记为故障。应将超时/未完成与产品故障分开报告。
Stuck progress
进展停滞
State never changes when it should. Hand to recovery/operations diagnosis rather than extending forever.
状态本应发生变化,却始终保持不变。应移交恢复或运维诊断,而不是无限延长循环。
Session mismatch
会话不匹配
Requested monitoring lasts beyond available execution window. Use scheduling/condition-watch capability when supported.
所请求的监控持续时间超过可用执行窗口。在功能支持时应改用调度/条件监听能力。
Anti-Patterns
反模式
- raw /unbounded sleep loops;
while true - retrying every error class;
- polling by repeatedly re-submitting the job;
- extending timeout until success after each miss;
- 1-second polling for a 10-minute deployment;
- declaring failure just because status is pending;
- declaring success because the loop ended cleanly;
- hiding transient errors from the final receipt;
- using loops to avoid diagnosing deterministic repeated failures.
- 使用原生的 /无界休眠循环;
while true - 重试每一种错误类别;
- 通过反复重新提交任务来轮询;
- 每次未成功后就延长超时;
- 对持续 10 分钟的部署进行 1 秒轮询;
- 仅因为状态为等待中就宣告失败;
- 因为循环正常结束就宣告成功;
- 在最终回执中隐藏瞬时错误;
- 使用循环回避对确定性重复失败的诊断。
Loop Receipt
循环回执
text
Condition/state machine:
Success / terminal failure states:
Time + iteration/request budgets:
Interval/backoff policy:
Idempotency/side-effect check:
Iterations: time → observed state → classification
Transient errors:
Stop reason:
Condition satisfied? yes/no
Final state:
Next action if incomplete/failed:text
Condition/state machine:
Success / terminal failure states:
Time + iteration/request budgets:
Interval/backoff policy:
Idempotency/side-effect check:
Iterations: time → observed state → classification
Transient errors:
Stop reason:
Condition satisfied? yes/no
Final state:
Next action if incomplete/failed:Completion Criteria
完成标准
Loop completes when:
- state machine, success/failure semantics, and budgets were explicit;
- polling respected idempotency/rate/cost constraints;
- terminal information stopped the loop early;
- timeout/stuck state is represented honestly;
- final receipt shows exactly why looping ended and what should happen next.
循环在满足以下条件时完成:
- 状态机、成功/失败语义和预算均已明确;
- 轮询遵守了幂等性、速率和成本约束;
- 终止信息使循环提前停止;
- 超时/停滞状态得到了如实表示;
- 最终回执准确说明循环结束的原因以及接下来应采取的操作。
Progressive Resources
进阶资源
- Deep guide:
references/polling-state-machines-and-backoff.md - Existing guidelines:
references/loop-control-guidelines.md - Example:
examples/poll-build-job.md
- 深入指南:
references/polling-state-machines-and-backoff.md - 现有指南:
references/loop-control-guidelines.md - 示例:
examples/poll-build-job.md