nav-loop

Navigator Loop 技能

通过结构化信号、停滞检测和双条件退出门，反复执行任务直至完成。

为什么需要它

传统 AI 编码需要手动提示“继续”。Navigator Loop 提供：

• 结构化完成信号（NAVIGATOR_STATUS 块）
• 双条件退出门（启发式规则 + 明确信号）
• 停滞检测（针对卡住循环的断路器）
• 进度可见性（阶段：INIT → RESEARCH → IMPL → VERIFY → COMPLETE）

基于 Ralph 的自主循环创新，并针对 Navigator 的高效上下文架构进行了改编。

何时调用

自动调用条件：

• 用户说“运行直至完成”“继续，直到完成”
• 用户说“迭代直至结束”“自主模式”
• 用户说“循环模式”“完成之前不要停止”
• 任务文档包含 loop_mode: true

请勿调用：

• 单步任务（无需迭代）
• 用户说“只做这一次”
• 已处于循环模式（防止嵌套循环）
• 用户明确禁用了循环模式

配置

.agent/.nav-config.json 中的循环模式设置：

{
  "loop_mode": {
    "enabled": false,
    "max_iterations": 5,
    "stagnation_threshold": 3,
    "exit_requires_explicit_signal": true,
    "show_status_block": true,
    "iteration_approval": "none",
    "periodic_interval": 3,
    "never_pause_on_stagnation": false,
    "stagnation_diversify_strategy": "combine"
  }
}

核心选项：

• enabled：新任务的默认状态
• max_iterations：防止无限循环的硬性上限（1-20）
• stagnation_threshold：暂停前相同状态的次数（2-5）
• exit_requires_explicit_signal：要求启发式规则之外还提供 EXIT_SIGNAL
• show_status_block：每次迭代都渲染 NAVIGATOR_STATUS

自主／通宵运行选项（v6.2.2+）：

• iteration_approval：在迭代之间何时提示用户接受或拒绝。
  • "none"（默认）——从不提示；循环不间断运行
  • "strict"——每次迭代后都提示
  • "periodic"——每 N 次迭代提示一次（其中 N = periodic_interval，默认值为 3）
• periodic_interval：当 iteration_approval == "periodic" 时，提示的间隔。默认值为 3（每第 3 次迭代）。对于漫长的通宵运行，可设置更高的值，以减少定期检查的频率（例如 5 或 10）。
• never_pause_on_stagnation：如果为 true，停滞时会触发自动变换策略，而不是暂停并调用 AskUserQuestion。通宵运行时必须启用。灵感来自 karpathy/autoresearch 的 NEVER STOP 指令。
• stagnation_diversify_strategy：触发 never_pause_on_stagnation 时尝试采用的恢复策略。
  • "combine"——结合先前差一点成功的方法或部分满足的指标
  • "radical"——尝试截然不同的方法（重新设计架构、更换库）
  • "reread"——重新阅读任务或系统范围内的文档，查找遗漏的信号

安全防护：设置 never_pause_on_stagnation: true 时，必须明确设置 max_iterations（默认值 5 即可；关键是不能采用无限默认值）。如果没有上限，自主循环可能会在本质上无法完成的任务上无限运行。

执行步骤

步骤 1：初始化循环状态

加载配置：

python3 functions/phase_detector.py --init

初始化跟踪变量：

iteration = 1
max_iterations = config.loop_mode.max_iterations or 5
stagnation_threshold = config.loop_mode.stagnation_threshold or 3
hash_history = []
phase = "INIT"

显示循环开始信息：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LOOP MODE ACTIVATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_DESCRIPTION}
Max iterations: {max_iterations}
Stagnation threshold: {stagnation_threshold}

Starting iteration 1...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

步骤 2：执行迭代

根据当前阶段执行任务：

阶段	操作
INIT	加载上下文，理解需求
RESEARCH	探索代码库，查找模式
IMPL	编写代码，进行更改
VERIFY	运行测试，验证功能，简化代码
COMPLETE	所有指标均已满足，准备退出

跟踪迭代期间的更改：

• 已读取的文件（用于检测 RESEARCH 阶段）
• 已更改的文件（用于检测 IMPL 阶段）
• 已运行的测试（用于检测 VERIFY 阶段）
• 已创建的提交（用于完成指标）

步骤 3：生成状态块

每次迭代后，生成 NAVIGATOR_STATUS：

python3 functions/status_generator.py \
  --phase "{phase}" \
  --iteration "{iteration}" \
  --max-iterations "{max_iterations}" \
  --indicators "{indicators_json}" \
  --state-hash "{current_hash}" \
  --prev-hash "{previous_hash}" \
  --stagnation-count "{stagnation_count}"

显示状态块：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NAVIGATOR_STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase: {PHASE}
Iteration: {N}/{MAX}
Progress: {PERCENT}%

Completion Indicators:
  [{x or space}] Code changes committed
  [{x or space}] Tests passing
  [{x or space}] Code simplified
  [{x or space}] Documentation updated
  [{x or space}] Ticket closed
  [{x or space}] Marker created

Exit Conditions:
  Heuristics: {MET}/{TOTAL} (need 2+)
  EXIT_SIGNAL: {true/false}

State Hash: {HASH}
Previous Hash: {PREV_HASH}
Stagnation: {COUNT}/{THRESHOLD}

Next Action: {NEXT_ACTION}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第 3.5 步：每轮审批关卡（可选）

如果 config.loop_mode.iteration_approval == "none"（默认值），跳过此步骤。

如果用户希望在迭代之间进行监督（例如针对高风险更改、了解循环行为，或在长时间运行前进行合理性检查），执行此步骤。

设置	行为
"none"	从不提示。循环继续执行第 4 步。
"strict"	每轮迭代后提示。
"periodic"	每 N 轮迭代提示一次。N 默认为 3；可通过 loop_mode.periodic_interval 配置。

提示时，在状态块后立即使用 AskUserQuestion：

Question: "Accept iteration {N} and continue?"
Options:
  1. [Continue] - Iteration accepted, proceed to next
  2. [Adjust]   - Provide feedback, incorporate into next iteration
  3. [Abort]    - End loop, create partial-completion marker

决策处理：

• 继续：正常进入第 4 步。
• 调整：将用户反馈记录为临时备注，不要推进哈希历史记录（这样会将下一轮迭代视为新的进展），然后继续执行第 4 步。
• 中止：跳转到第 8 步（清理），并将 status 设为 "user_aborted"。

此关卡在停滞检测前运行，避免被拒绝的迭代意外累积停滞计数。

第 4 步：检查停滞状态

计算状态哈希：

python3 functions/stagnation_detector.py \
  --phase "{phase}" \
  --indicators "{indicators_json}" \
  --files-changed "{files_json}" \
  --history "{hash_history_json}"

如果检测到停滞（连续 N 轮的哈希相同），则根据 never_pause_on_stagnation 决定如何响应。

默认行为（never_pause_on_stagnation: false）

提示用户：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STAGNATION DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Same state detected for {N} consecutive iterations.

Current State:
  Phase: {PHASE}
  Indicators: {MET}/{TOTAL}
  Last Action: {LAST_ACTION}

Possible causes:
1. Blocked by external dependency
2. Unclear requirements
3. Test failures preventing progress
4. Missing context or permissions

Options:
1. [Continue] - Try one more iteration
2. [Clarify] - Explain what's blocking
3. [Abort] - End loop, manual intervention

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

使用 AskUserQuestion 供用户选择：

• 继续：重置停滞计数器并继续循环
• 澄清：由用户说明阻碍，并纳入考虑后继续
• 中止：退出循环并添加部分完成标记

自主行为（never_pause_on_stagnation: true）

循环正在无人值守地运行（例如隔夜运行、在 CI 中运行等）。不要提示用户，根据 stagnation_diversify_strategy 自动尝试不同方案：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STAGNATION → AUTO-DIVERSIFY ({STRATEGY})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Same state for {N} iterations. Auto-recovery: {STRATEGY}
Stagnation counter reset.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

策略	下一轮迭代尝试的操作
combine	重新审视已部分满足的指标；结合前几轮中两个接近成功的方案
radical	放弃当前方案；尝试截然不同的设计（采用不同的库、架构或算法）
reread	重读任务范围内的任务文档和相关系统文档；寻找遗漏的信号或约束

采用不同方案后：

• 将停滞计数器重置为 0
• 在本轮迭代的备注中记录方案调整（以便下一状态块反映此情况）
• 继续执行第 5 步

强制停止：即使在自主模式下，循环仍会在达到 max_iterations 时终止。如果单次运行中触发方案调整的次数 ≥3 次，则升级为中止流程（创建 loop-aborted 标记并退出）——反复调整方案本身就表明任务从根本上陷入停滞。

此机制受到 karpathy/autoresearch 的 NEVER STOP 指令启发：“如果想不出办法，就再多想想——阅读论文、重新阅读任务范围内的文件以寻找新思路、尝试结合之前差一点成功的方案，或尝试更激进的架构改动。”

第 5 步：检查退出条件

评估双重条件关卡：

python3 functions/exit_gate.py \
  --indicators "{indicators_json}" \
  --exit-signal "{exit_signal}" \
  --require-explicit "{config.exit_requires_explicit_signal}"

退出条件：

1. 启发式条件：至少满足 2 项完成指标
2. EXIT_SIGNAL：明确表示任务已完成的信号

完成指标（映射自自主协议）：

• code_committed：更改已提交到 git
• tests_passing：测试套件通过（退出代码为 0）
• code_simplified：代码已简化以提升清晰度（v5.4.0+）
• docs_updated：文档文件已更改
• ticket_closed：PM 工具中的工单已标记为完成
• marker_created：完成标记已存在

退出决策逻辑：

IF heuristics >= 2 AND exit_signal == true:
  → EXIT: Task complete
ELIF heuristics >= 2 AND exit_signal == false:
  → CONTINUE: Awaiting explicit completion signal
ELIF exit_signal == true AND heuristics < 2:
  → BLOCKED: Cannot exit with insufficient indicators
ELSE:
  → CONTINUE: More work needed

第 6 步：处理最大迭代次数

如果 iteration >= max_iterations：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MAX ITERATIONS REACHED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Completed {MAX} iterations without full completion.

Current State:
  Phase: {PHASE}
  Indicators: {MET}/{TOTAL}
  EXIT_SIGNAL: {true/false}

Progress made:
- {PROGRESS_ITEM_1}
- {PROGRESS_ITEM_2}

Options:
1. [Extend] - Add 3 more iterations
2. [Complete] - Accept current state as done
3. [Abort] - Exit without completion

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第 7 步：完成循环

满足退出条件时，以 JSON 格式发出退出信号并显示完成状态：

{"v":2,"type":"exit","success":true,"reason":"All criteria met"}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LOOP COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_DESCRIPTION}
Iterations: {FINAL_COUNT}/{MAX}
Final Phase: COMPLETE

Completion Indicators:
  [x] Code changes committed
  [x] Tests passing
  [x] Code simplified
  [x] Documentation updated
  [ ] Ticket closed (skipped - no PM tool)
  [x] Marker created

Exit Conditions:
  Heuristics: 4/5 (passed)
  EXIT_SIGNAL: true (passed)

Summary:
- {KEY_CHANGE_1}
- {KEY_CHANGE_2}
- {KEY_CHANGE_3}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

执行自主完成协议：

1. 提交更改（如尚未提交）
2. 归档任务文档
3. 关闭工单（如已配置 PM）
4. 创建完成标记（包含循环状态）
5. 建议 compact

---

设置 EXIT_SIGNAL

EXIT_SIGNAL 由 Claude 显式设置，条件如下：

• 已满足所有主要任务要求
• 代码可正常运行且已通过测试
• 没有明显的待办事项

完成信号的发送方式（v2 JSON 格式）：

{"v":2,"type":"exit","success":true,"reason":"All requirements met"}

使用 pilot-signal 代码块中的 JSON 格式，确保 Pilot 自动化能够明确检测到信号。reason 字段应简要说明任务已完成的原因。

信号字段：

• v：版本（始终为 2）
• type：信号类型（完成时始终为 "exit"）
• success：任务是否成功完成（true/false）
• reason：对完成状态的简要说明

这项显式声明可以避免在满足启发式条件但仍有工作未完成时提前退出。

---

阶段检测

根据上下文自动检测阶段：

def detect_phase(context):
    # COMPLETE: Exit conditions met
    if indicators_met >= 4 and exit_signal:
        return "COMPLETE"

    # VERIFY: Tests running or recently run
    if context.tests_running or context.test_exit_code is not None:
        return "VERIFY"

    # IMPL: Files being modified
    if context.files_changed:
        return "IMPL"

    # RESEARCH: Reading files, searching
    if context.files_read and not context.files_changed:
        return "RESEARCH"

    # INIT: Default starting state
    return "INIT"

---

与 Navigator 集成

与自主完成集成

循环模式增强（而非取代）自主协议：

• 完成指标映射到自主步骤
• EXIT_SIGNAL 触发自主完成
• 标记包含循环状态，以便恢复

与 nav-simplify（v5.4.0+）集成

在 VERIFY 阶段进行简化：

• 测试通过后、提交前
• 通过 .nav-config.json 中的 simplification.enabled 配置
• 添加 code_simplified 完成指标
• 如果代码没有变化，则跳过（仅文档任务）

与 nav-diagnose 集成

停滞时触发 nav-diagnose 质量检查：

• 连续 3 次处于相同状态的循环 = 潜在质量问题
• nav-diagnose 可帮助找出根本原因
• 重新锚定可以解决卡住的循环

与 nav-marker 集成

标记会记录循环状态：

• 当前迭代次数和最大迭代次数
• 创建标记时所处的阶段
• 用于保持连续性的状态哈希
• 完成指标状态

与 ToM 功能集成

循环模式遵循 ToM 配置：

• VERIFY 阶段仍会执行验证检查点
• 配置文件偏好会影响沟通风格
• 信念锚点有助于澄清卡住的状态

---

预定义函数

functions/status_generator.py

生成格式化的 NAVIGATOR_STATUS 块。

functions/exit_gate.py

评估双重退出条件（启发式条件 + 显式信号）。

functions/stagnation_detector.py

计算状态哈希并检测连续的相同状态。

functions/phase_detector.py

根据上下文自动检测当前任务阶段。

---

错误处理

找不到配置：

Loop mode config not found in .nav-config.json.
Using defaults: max_iterations=5, stagnation_threshold=3

函数执行失败：

• 回退到手动评估
• 记录错误，但不中断循环
• 尽力继续检测阶段

用户在循环中途取消：

• 创建部分完成标记
• 记录已取得的进展
• 列出剩余工作

---

成功标准

循环模式在满足以下条件时成功：

• 任务在 max_iterations 内完成
• 没有停滞暂停（或已迅速解决）
• EXIT_SIGNAL 和启发式条件均已满足
• 完成标记包含循环状态
• 用户每次迭代都能清楚地看到进展

---

示例

示例 1：简单功能

User: "Run until done: add isPrime function with tests"

Iteration 1 (INIT → RESEARCH):
  - Read existing math utils
  - Found test patterns

Iteration 2 (IMPL):
  - Created isPrime function
  - Created test file

Iteration 3 (VERIFY):
  - Ran tests: PASS
  - Committed changes

{"v":2,"type":"exit","success":true,"reason":"isPrime function implemented and tests passing"}

→ Loop complete in 3 iterations

示例 2：停滞恢复

User: "Run until done: fix authentication bug"

Iteration 1-3 (IMPL):
  - Same changes attempted
  - Tests still failing
  - State hash unchanged

→ STAGNATION DETECTED

User: "The test needs a mock for the auth service"

Iteration 4 (IMPL):
  - Added mock
  - Tests pass

{"v":2,"type":"exit","success":true,"reason":"Auth bug fixed with mock service"}

→ Loop complete in 4 iterations

---

局限性

无法处理：

• 外部阻碍因素（等待 API、权限）
• 主观的完成标准（“让它看起来更美观”）
• 需要在循环过程中由人工判断的任务

不适用于：

• 快速修复（一次迭代即可完成）
• 探索性工作（没有明确的完成状态）
• 涉及安全影响的任务（需要人工审核）

---

这项技能提供了 Ralph 风格的“持续运行直至完成”能力，同时保持 Navigator 的上下文效率并集成 ToM。