以下是该技能的中文翻译内容，保持原有格式不变：

---

name: nav-loop description: 运行任务直到完成，具有结构化完成信号。当用户说“运行直到完成”、“继续进行直到完成”、“迭代直到结束”、“循环模式”、“自主模式”时自动调用。 allowed-tools: 阅读、写作、编辑、Bash、Grep、Glob、AskUserQuestion version: 1.0.0

导航器循环技能

迭代执行任务直到完成，具有结构化信号、停滞检测和双条件退出门。

为什么存在

传统的AI编码需要手动“继续进行”提示。导航器循环提供：

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

基于Ralph的自主循环创新，适应导航器的上下文高效架构。

何时调用

自动调用时：

• 用户说“运行直到完成”、“继续进行直到完成”
• 用户说“迭代直到结束”、“自主模式”
• 用户说“循环模式”、“不要停止直到完成”
• 任务文档有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
  }
}

选项：

• enabled: 新任务的默认状态
• max_iterations: 防止无限循环的硬上限（1-20）
• stagnation_threshold: 同一状态计数前暂停（2-5）
• exit_requires_explicit_signal: 需要EXIT_SIGNAL以及启发式

执行步骤

第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"

显示循环开始：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
循环模式激活
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

任务：{TASK_DESCRIPTION}
最大迭代次数：{max_iterations}
停滞阈值：{stagnation_threshold}

开始第1次迭代...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第2步：执行迭代

根据当前阶段执行任务工作：

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

跟踪迭代期间的变化：

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

第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}
迭代：{N}/{MAX}
进度：{PERCENT}%

完成指标：
  [{x或空格}] 代码更改已提交
  [{x或空格}] 测试通过
  [{x或空格}] 代码简化
  [{x或空格}] 文档更新
  [{x或空格}] 工单关闭
  [{x或空格}] 创建标记

退出条件：
  启发式：{MET}/{TOTAL}（需要2+）
  EXIT_SIGNAL：{true/false}

状态哈希：{HASH}
上一个哈希：{PREV_HASH}
停滞：{COUNT}/{THRESHOLD}

下一个行动：{NEXT_ACTION}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第4步：检查停滞

计算状态哈希：

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

如果检测到停滞（连续N次迭代相同哈希）：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
检测到停滞
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

连续{N}次迭代检测到相同状态。

当前状态：
  阶段：{PHASE}
  指标：{MET}/{TOTAL}
  上次行动：{LAST_ACTION}

可能的原因：
1. 被外部依赖阻塞
2. 需求不明确
3. 测试失败阻止进度
4. 缺少上下文或权限

选项：
1. [继续] - 再试一次迭代
2. [澄清] - 用户解释阻塞点，纳入并继续
3. [中止] - 手动干预，结束循环

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

使用AskUserQuestion进行选择：

• 继续：重置停滞计数器，继续循环
• 澄清：用户解释阻塞点，纳入并继续
• 中止：退出循环，部分完成标记

第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: 存在完成标记

退出决策逻辑：

如果启发式 >= 2 AND exit_signal == true:
  → 退出：任务完成
或者如果启发式 >= 2 AND exit_signal == false:
  → 继续：等待明确的完成信号
或者如果exit_signal == true AND 启发式 < 2:
  → 阻塞：不能在指标不足的情况下退出
否则：
  → 继续：需要更多工作

第6步：处理最大迭代

如果迭代 >= max_iterations：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
达到最大迭代次数
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

在没有完全完成的情况下完成了{MAX}次迭代。

当前状态：
  阶段：{PHASE}
  指标：{MET}/{TOTAL}
  EXIT_SIGNAL：{true/false}

取得的进展：
- {PROGRESS_ITEM_1}
- {PROGRESS_ITEM_2}

选项：
1. [扩展] - 增加3次迭代
2. [完成] - 接受当前状态作为完成
3. [中止] - 未完成退出

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

第7步：完成循环

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

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
循环完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

任务：{TASK_DESCRIPTION}
迭代次数：{FINAL_COUNT}/{MAX}
最终阶段：COMPLETE

完成指标：
  [x] 代码更改已提交
  [x] 测试通过
  [x] 代码简化
  [x] 文档更新
  [ ] 工单关闭（跳过 - 无PM工具）
  [x] 创建标记

退出条件：
  启发式：4/5（通过）
  EXIT_SIGNAL：true（通过）

摘要：
- {KEY_CHANGE_1}
- {KEY_CHANGE_2}
- {KEY_CHANGE_3}

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

执行自主完成协议：

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

---

设置EXIT_SIGNAL

EXIT_SIGNAL由Claude明确设置，当：

• 所有主要任务需求都满足
• 代码功能正常且已测试
• 没有明显的剩余工作

如何发出完成信号（v2 JSON格式）：

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

JSON格式在pilot-signal代码块中确保Pilot自动化明确检测。reason字段应简要描述为什么任务完成。

信号字段：

• v: 版本（总是2）
• type: 信号类型（总是"exit"表示完成）
• success: 任务是否成功完成（true/false）
• reason: 完成状态的简要解释

这种明确的声明防止了在工作尚未完成时，由于启发式满足而过早退出。

---

阶段检测

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

def detect_phase(context):
    # COMPLETE: 满足退出条件
    if indicators_met >= 4 and exit_signal:
        return "COMPLETE"

    # VERIFY: 测试运行或最近运行
    if context.tests_running or context.test_exit_code is not None:
        return "VERIFY"

    # IMPL: 文件被修改
    if context.files_changed:
        return "IMPL"

    # RESEARCH: 读取文件，搜索
    if context.files_read and not context.files_changed:
        return "RESEARCH"

    # INIT: 默认起始状态
    return "INIT"

---

与导航器集成

与自主完成集成

循环模式增强（不替代）自主协议：

• 完成指标映射到自主步骤
• 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

从上下文中自动检测当前任务阶段。

---

错误处理

配置未找到：

在.nav-config.json中未找到循环模式配置。
使用默认值：max_iterations=5, stagnation_threshold=3

函数执行失败：

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

用户在循环中途中止：

• 创建部分完成标记
• 文档记录已完成的工作
• 列出剩余工作

---

成功标准

循环模式成功时：

• [ ] 任务在max_iterations内完成
• [ ] 没有停滞暂停（或迅速解决）
• [ ] EXIT_SIGNAL+启发式都满足
• [ ] 完成标记包括循环状态
• [ ] 用户每次迭代都看到清晰的进度

---

示例

示例1：简单特性

用户：“运行直到完成：添加isPrime函数及测试”

第1次迭代（INIT → RESEARCH）：
  - 阅读现有的数学工具
  - 发现测试模式

第2次迭代（IMPL）：
  - 创建isPrime函数
  - 创建测试文件

第3次迭代（VERIFY）：
  - 运行测试：通过
  - 提交更改

{"v":2,"type":"exit","success":true,"reason":"isPrime函数实现且测试通过"}

→ 3次迭代完成循环

示例2：停滞恢复

用户：“运行直到完成：修复认证错误”

第1-3次迭代（IMPL）：
  - 尝试相同的更改
  - 测试仍然失败
  - 状态哈希未改变
  
→ 检测到停滞

用户：“测试需要auth服务的模拟”

第4次迭代（IMPL）：
  - 添加模拟
  - 测试通过

{"v":2,"type":"exit","success":true,"reason":"认证错误修复及模拟服务"}

→ 4次迭代完成循环

---

限制

无法处理：

• 外部阻塞（等待API，权限）
• 主观完成标准（“看起来不错”）
• 循环中需要人类判断的任务

不应使用于：

• 快速修复（单次迭代足够）
• 探索性工作（没有明确的完成状态）
• 涉及安全问题的任务（需要人类审查）

---

这项技能提供了Ralph风格的“运行直到完成”能力，同时保持导航器的上下文效率和ToM集成。