minimal-agent 0.9.0 → 0.10.0

package/workflows/ralph-loop.yaml

@@ -2,168 +2,198 @@ name: ralph-loop
 description: |
   Ralph Wiggum 迭代开发循环——通过重复执行同一目标直到完成。
 
-  等价于原 ralph-wiggum 插件的 /ralph-loop 命令，完全用声明式工作流实现。
   核心机制：while 循环 + fresh context（每轮重置 history）+ 哨兵协议 + 验证门。
+  状态机（phase: PLAN→BUILD→VERIFY/HEAL→DONE）全部用 type:set 确定性赋值，
+  prompt 拼装也用 set（曾用 llm 步当赋值/拼串——模型自由回复非确定，是事故源）。
 
-  用法：/workflow ralph-loop "你的目标" --max-iterations 50 --verify "shell:bun test"
+  哨兵协议（精确匹配，防"incomplete 含 complete"类误判）：
+    <promise>DONE</promise>            任务真正完成（过验证门后 break）
+    <promise>NEED_REPLAN</promise>     当前方案走不通，回 PLAN
+    <promise>NEED_GOAL_REVISION</promise> 目标本身有问题，干净终止
+    <learning>一句话</learning>        踩坑记录（存档供后续轮参考，不影响流程）
+
+  用法：/workflow ralph-loop "你的目标" --input max_iterations=50 --input verify_checks="shell:bun test"
 inputs:
   - name: goal
     type: string
     required: true
-    description: "不可变目标描述（如'实现用户认证模块并确保测试通过'）"
+    greedy: true
+    description: "不可变目标描述（可一句话自然语言；命令行 workflow 名后整句进 goal，不被空格拆碎）"
   - name: max_iterations
     type: number
     default: 50
-    description: "最大迭代次数（安全阀，默认 50，硬上限 200）"
+    description: "【高级·用 --input max_iterations=N】最大迭代次数（安全阀，默认 50，硬上限 200）"
   - name: verify_checks
     type: string
     default: ""
-    description: "验证门检查项（逗号分隔，如 'shell:bun test,file_exists:src/index.ts'）。空则跳过验证门。"
+    description: "【高级·用 --input verify_checks=...】验证门检查项（逗号分隔，如 'shell:bun test,file_exists:src/index.ts'）。空则跳过验证门。"
 
-steps:
-  # === 初始化阶段变量 ===
-  - id: init_phase
-    llm: "PLAN"
-    capture:
-      result: phase
+self_heal:
+  max_retries: 1       # 单步瞬态失败（LLM 超时等）重试一次
+  retry_delay_ms: 3000 # 重试退避，给瞬态故障留恢复窗口
 
-  # === 初始化教训记录文件（fresh context 下跨轮存活） ===
-  - id: init_learnings
-    tool: "Write(file_path='.minimal-agent-workflow/learnings.md', content='')"
-    onError: continue
+steps:
+  # === 初始化（确定性 set，零 LLM）。learnings 的权威载体是 VarStack 变量——
+  #     fresh_context 每轮重置的是 history 不是变量栈，变量天然跨轮存活；
+  #     曾用「Write 文件 + 每轮 Read 回读」，Read 输出带行号/空文件标记，
+  #     回写时把格式垃圾逐轮累积进档案。文件仅作存档副本（事后排查用）。 ===
+  - id: init_state
+    title: "初始化状态机"
+    type: set
+    set:
+      phase: PLAN
+      learnings_text: ""
 
   # ============================================================
   #  主迭代循环（while 模式 + fresh_context）
-  #  每轮：构造 prompt → agent 工作 → 哨兵检测 → 阶段推进
+  #  每轮：set 拼 prompt → agent 工作 → 教训累积 → 哨兵检测 → 阶段推进
   # ============================================================
   - type: loop
     id: main_loop
-    max_iterations: "${max_iterations}"
+    title: "迭代开发"
+    max_iterations: "${inputs.max_iterations}"
     fresh_context: true
     do:
-      # --- 1. 读取上轮教训 ---
-      - id: read_learnings
-        tool: "Read(file_path='.minimal-agent-workflow/learnings.md')"
-        capture:
-          text: learnings_text
-        onError: continue
-
-      # --- 2. 构造本轮 prompt（含目标、阶段、通信协议、教训） ---
+      # --- 1. 构造本轮 prompt（确定性字符串拼装，set 步零 LLM） ---
       - id: build_prompt
-        llm: |
-          # 不可变目标 (IMMUTABLE GOAL)
-          ${goal}
-          ⚠️ 你不能修改或扩大上述目标。
-
-          # 当前阶段: ${phase.toUpperCase()}
-          ${phase == 'PLAN' ? '分析任务、拆解步骤、识别风险与未知项；先想清楚再动手。' :
-            phase == 'BUILD' ? '按计划实现，一次只聚焦一个子任务，落到具体文件改动。' :
-            phase == 'VERIFY' ? '运行测试/检查输出/核对验收标准，用证据确认，别凭感觉。' :
-            phase == 'HEAL' ? '已多次验证失败：停止猜测，定位根因再修，避免回归。' :
-            '目标已达成。'}
-
-          # 与循环驱动的通信协议（务必遵守）
-          - 任务**真正完成**时输出 `<promise>DONE</promise>`（驱动会运行验证门）
-          - 当前方案走不通、要换打法时输出 `<PROMISE>NEED_REPLAN</PROMISE>`（回 PLAN）
-          - **目标本身**有问题时输出 `<PROMISE>NEED_GOAL_REVISION</PROMISE>`（干净终止）
-          - 踩到的坑用 `<learning>一句话</learning>` 标记（驱动自动存档供后续参考）
-          ⚠️ 切勿为逃出循环而谎报完成——只有陈述完全为真时才输出完成哨兵。
-
-          ${learnings_text && learnings_text != '' ? '# 关键教训（必须遵守，避免重复踩坑）\n' + learnings_text : ''}
-
-          ---
-          本轮任务 (迭代 ${_iter})
-        capture:
-          result: prompt_text
-
-      # --- 3. 执行 agent 工作（TAOR 引擎，有工具能力） ---
+        title: "拼装本轮指令"
+        type: set
+        set:
+          prompt_text: |
+            # 不可变目标 (IMMUTABLE GOAL)
+            ${inputs.goal}
+            ⚠️ 你不能修改或扩大上述目标。
+
+            # 当前阶段: ${upper(phase)}
+            ${phase == 'PLAN' ? '分析任务、拆解步骤、识别风险与未知项；先想清楚再动手。' :
+              phase == 'BUILD' ? '按计划实现，一次只聚焦一个子任务，落到具体文件改动。' :
+              phase == 'VERIFY' ? '运行测试/检查输出/核对验收标准，用证据确认，别凭感觉。' :
+              phase == 'HEAL' ? '已多次验证失败：停止猜测，定位根因再修，避免回归。' :
+              '目标已达成。'}
+
+            # 与循环驱动的通信协议（务必逐字遵守标签格式）
+            - 任务**真正完成**时输出 `<promise>DONE</promise>`（驱动会运行验证门）
+            - 当前方案走不通、要换打法时输出 `<promise>NEED_REPLAN</promise>`（回 PLAN）
+            - **目标本身**有问题时输出 `<promise>NEED_GOAL_REVISION</promise>`（干净终止）
+            - 踩到的坑用 `<learning>一句话</learning>` 标记（驱动自动存档供后续参考）
+            ⚠️ 切勿为逃出循环而谎报完成——只有陈述完全为真时才输出完成哨兵。
+
+            ${learnings_text != '' ? '# 关键教训（必须遵守，避免重复踩坑）\n' + learnings_text : ''}
+
+            ---
+            本轮任务 (迭代 ${_iter})
+
+      # --- 2. 执行 agent 工作（TAOR 引擎，有工具能力） ---
       - id: work
+        title: "执行本轮工作"
         agent: "${prompt_text}"
         maxTurns: 15
         capture:
           text: output
 
-      # --- 4. 提取 learning 并持久化 ---
+      # --- 3. 提取 learning（确定性正则 extract，零 LLM 零幻觉；
+      #        曾用 llm 步提取——模型可能改写/漏抄/编造，教训档案被污染） ---
       - id: extract_learning
-        llm: |
-          从以下文本中提取所有 <learning>...</learning> 内容，每行一条原样输出。
-          如果没有 learning 标签，输出空字符串。
-          
-          文本：
-          ${output}
-        capture:
-          text: extracted_learning
+        title: "提取本轮教训"
+        type: set
+        set:
+          extracted_learning: "${join(extract(output, '<learning>(.*?)</learning>'), '\n- ')}"
+
+      # 累积到 VarStack（权威载体，跨轮存活、无文件格式污染）。
+      - id: accumulate_learning
+        type: set
+        set:
+          learnings_text: "${learnings_text}- ${extracted_learning}\n"
+        when: "extracted_learning != ''"
 
+      # 存档副本落盘（事后排查用；状态目录随成功归档为 ralph-loop.done）
       - id: save_learning
-        tool: "Bash(command='cat >> .minimal-agent-workflow/learnings.md << EOF\n${extracted_learning}\nEOF')"
+        title: "教训存档落盘"
+        tool: Write
+        args:
+          file_path: .minimal-agent-workflow/ralph-loop/learnings.md
+          content: "${learnings_text}"
         when: "extracted_learning != ''"
         onError: continue
 
-      # --- 5. 哵兵检测与分支处理 ---
+      # --- 5. 哨兵检测（平铺互斥分支，精确匹配；不再有嵌套 then/else 迷宫） ---
 
-      # 5a. 是否包含任何哨兵标签？
-      - id: has_sentinel
+      # 5a. 完成哨兵（精确标签，防 "incomplete" 含 "complete" 类误判）→ 验证门
+      - id: on_done
+        title: "哨兵检测·完成"
         type: branch
-        condition: "includes(output, '<promise>') || includes(output, '<PROMISE>') || includes(output, '<learning>')"
+        condition: "includes(lower(output), '<promise>done</promise>')"
         then:
-          # 有哨兵标签 → 判断具体类型
-
-          # 5a-i. 完成哨兵？
-          - id: check_complete
+          # 验证门：verify_checks 为空时自动通过（verify 空检查列表 = pass）；
+          # 失败时 onError:continue 让 verify_passed 绑占位文本（≠ true）→ 闸门拦下回 BUILD
+          - id: run_verify
+            type: verify
+            checks: "${inputs.verify_checks}"
+            onFail: "验证未通过，回到 BUILD 继续"
+            capture:
+              passed: verify_passed
+            onError: continue
+          - id: verify_gate
             type: branch
-            condition: |
-              includes(lower(output), '<promise>') &&
-              (includes(lower(output), 'done') ||
-               includes(lower(output), 'complete') ||
-               includes(lower(output), 'goal_complete'))
+            condition: "verify_passed == true"
             then:
-              # === DONE 哨兵 → 验证门 ===
-              - id: run_verify
-                type: verify
-                checks: "${verify_checks}"
-                when: "verify_checks != ''"
-                onFail: "验证未通过，回到 BUILD 继续"
-                onError: continue
-              # 验证通过或无验证门 → 设置完成阶段并跳出循环
               - id: set_done
-                llm: "DONE"
-                capture:
-                  result: phase
+                type: set
+                set:
+                  phase: DONE
               - id: exit_success
                 type: break
             else:
-            # 非 DONE 哨兵 → NEED_REPLAN 或 NEED_GOAL_REVISION
-            - id: check_replan
-              type: branch
-              condition: "includes(output, 'NEED_REPLAN')"
-              then:
-                # 回到 PLAN
-                - id: replan
-                  llm: "PLAN"
-                  capture:
-                    result: phase
-              else:
-                # NEED_GOAL_REVISION → 终止循环
-                - id: goal_revision_exit
-                  llm: "DONE"
-                  capture:
-                    result: phase
-                - id: exit_goal_revision
-                  type: break
-
-      # 5b. 无哨兵 → 自动阶段推进
+              # 验证未过：模型谎报/漏测 → 回 BUILD 继续迭代（不 break）
+              - id: back_to_build
+                type: set
+                set:
+                  phase: BUILD
+
+      # 5b. 重新规划哨兵 → 回 PLAN（auto_advance 有 <promise> 守卫，本轮不会被推进吞掉）
+      #     完整标签匹配——裸词 'need_replan' 会被 agent 复述协议说明文本误触
+      - id: on_replan
+        title: "哨兵检测·重新规划"
+        type: branch
+        condition: "includes(lower(output), '<promise>need_replan</promise>')"
+        then:
+          - id: replan
+            type: set
+            set:
+              phase: PLAN
+
+      # 5c. 目标修订哨兵 → 干净终止（仅此哨兵终止；learning-only 输出绝不落到这里）
+      #     完整标签匹配，理由同 5b
+      - id: on_goal_revision
+        title: "哨兵检测·目标修订"
+        type: branch
+        condition: "includes(lower(output), '<promise>need_goal_revision</promise>')"
+        then:
+          - id: set_goal_revision
+            type: set
+            set:
+              phase: GOAL_REVISION
+          - id: exit_goal_revision
+            type: break
+
+      # 5d. 自动阶段推进：仅当本轮没有任何流程哨兵（<promise>…）时才推进。
+      #     learning 标签不是流程哨兵，不阻止推进；NEED_REPLAN 轮被守卫拦住，replan 不被吞。
       - id: auto_advance
+        title: "阶段自动推进"
         type: branch
-        condition: "phase == 'PLAN' && _iter >= 1"
+        condition: "phase == 'PLAN' && !includes(lower(output), '<promise>')"
         then:
           - id: to_build
-            llm: "BUILD"
-            capture:
-              result: phase
+            type: set
+            set:
+              phase: BUILD
 
   # === 循环结束后的收尾 ===
   - id: final_summary
+    title: "完成·执行总结"
     llm: |
-      总结本轮 ralph-loop 的执行结果。如果目标是完成的，列出关键产出物。
-      如果是因达到迭代上限而退出，说明当前进度和下一步建议。
+      总结本轮 ralph-loop 的执行结果（最终阶段：${phase}）。
+      - phase=DONE：目标完成，列出关键产出物。
+      - phase=GOAL_REVISION：目标本身需要修订，说明模型给出的理由。
+      - 其它：因达到迭代上限而退出，说明当前进度和下一步建议。
     maxTurns: 1

package/workflows/schema.json

@@ -30,6 +30,17 @@
       "minItems": 1,
       "items": { "$ref": "#/definitions/step" }
     },
+    "self_heal": {
+      "type": "object",
+      "description": "Workflow-level retry/resume policy.",
+      "properties": {
+        "backoff": { "type": "number", "minimum": 0 },
+        "max_retries": { "type": "number", "minimum": 0 },
+        "retry_delay_ms": { "type": "number", "minimum": 0 },
+        "max_turns_retry_delay_ms": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
     "__meta": { "type": "object" }
   },
   "definitions": {
@@ -38,22 +49,76 @@
       "required": ["id"],
       "properties": {
         "id": { "type": "string", "minLength": 1 },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "任意步可选：人话进度显示名（支持 ${} 插值）。声明后状态行显示这段文案（如「阶段2/6·起草实现计划」），不再显示块内相对序号。"
+        },
         "tool": { "type": "string" },
         "skill": { "type": "string" },
         "llm": { "type": "string" },
         "type": {
-          "enum": ["assert", "branch", "loop", "pause", "parallel", "vote"],
-          "description": "控制流节点类型。⚠ ADR-05 新增 'parallel' 与 'vote'，详见 docs/05-advanced-workflow-integration.md。"
+          "enum": ["assert", "verify", "set", "branch", "loop", "break", "continue", "echo", "pause"],
+          "description": "控制流节点类型。'continue'=跳到（目标）循环下一轮迭代；'echo'=确定性输出插值消息（不烧 LLM）。"
+        },
+        "args": {
+          "type": "object",
+          "description": "tool 步参数（深度 ${} 插值）。⚠️ Bash 命令注意：${} 是引擎插值、发生在 shell 之前——shell 单引号会原样保留插值后的文本，不做算术/变量二次展开（sed -n '$((${i}+1))p' 会把字面 $((0+1))p 喂给 sed）。需要序号让 loop over 直接产出最终值（如 1 基行号）。"
         },
-        "args": { "type": "object" },
         "input": { "type": "string" },
         "capture": {
           "type": "object",
           "additionalProperties": { "type": "string" }
         },
         "when": { "type": "string" },
-        "onError": { "enum": ["halt", "continue"] },
+        "onError": { "enum": ["halt", "continue", "recover"] },
+        "target": {
+          "type": "string",
+          "minLength": 1,
+          "description": "仅 type=break/continue：目标循环 id（标签语义）。缺省=最近一层循环；指定后信号穿透中间层循环直达该 loop。"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "description": "仅 type=echo（必填）：确定性输出给用户的消息，支持 ${} 插值。"
+        },
+        "goal_supplement": {
+          "type": "boolean",
+          "description": "动作步/pause 可选：本步产出作为「用户补充要求」并入贯穿目标锚定，注入后续每一步。"
+        },
         "maxTurns": { "type": "number" },
+        "images": {
+          "type": "array",
+          "description": "仅 llm / agent 节点可选：OpenAI 兼容图片输入。字符串表示路径/URL；对象可设置 detail 与 max_long_side_pixel。",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              {
+                "type": "object",
+                "required": ["source"],
+                "properties": {
+                  "source": { "type": "string", "minLength": 1 },
+                  "detail": { "enum": ["low", "default", "high"] },
+                  "max_long_side_pixel": { "type": "integer", "minimum": 1 }
+                },
+                "additionalProperties": true
+              }
+            ]
+          }
+        },
+        "parse_inline_images": {
+          "type": "boolean",
+          "description": "仅 llm / agent 节点可选：解析 prompt 中的 @./image.png 或图片 URL。"
+        },
+        "image_detail": {
+          "enum": ["low", "default", "high"],
+          "description": "仅 llm / agent 节点可选：本步骤图片 detail 默认值。"
+        },
+        "image_max_long_side_pixel": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "仅 llm / agent 节点可选：本步骤图片最长边默认值。"
+        },
         "condition": { "type": "string" },
         "onFail": { "type": "string" },
         "then": {
@@ -71,29 +136,22 @@
           "items": { "$ref": "#/definitions/step" }
         },
         "prompt": { "type": "string" },
-        "output_schema": {
-          "type": "object",
-          "description": "⚠ ADR-05 新增：LLM 输出 JSON Schema 强约束，走 provider-native structured output。仅 llm 节点生效（skill 节点 loader 拒绝）；详见 docs/workflow-design.md。"
-        },
-        "fork": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/step" },
-          "description": "⚠ ADR-05 新增：type=parallel 时的 fork 子步骤数组，Promise.all 并发执行。详见 docs/05-advanced-workflow-integration.md。"
+        "free_text": {
+          "type": "string",
+          "enum": ["halt", "approve"],
+          "description": "type=pause 时自由输入的处理方式：halt=不放行（默认）；approve=作为补充要求放行，可配 capture.text 传给后续步骤。"
         },
-        "voters_count": {
-          "type": "integer",
-          "minimum": 2,
-          "maximum": 10,
-          "description": "⚠ ADR-05 新增：type=vote 的 voter 数量（2~10）。详见 docs/05-advanced-workflow-integration.md。"
+        "max_iterations": {
+          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "string", "minLength": 1 }]
         },
-        "rules": {
+        "done_when": {
           "type": "string",
-          "description": "⚠ ADR-05 新增：type=vote 给 voter 的审查指令。详见 docs/05-advanced-workflow-integration.md。"
+          "minLength": 1,
+          "description": "仅 agent 步可选：确定性完成条件（白名单表达式，如 fileExists('./out/x.pptx')）。不满足时引擎自动提醒同一 agent 继续执行（上限 2 次），仍不满足按可重试失败处理。弱模型「宣告要干却不调工具就停」的引擎级兜底。"
         },
-        "threshold": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "⚠ ADR-05 新增：type=vote 的多数门阈值，默认 ceil(voters_count/2)。详见 docs/05-advanced-workflow-integration.md。"
+        "output_schema": {
+          "type": "object",
+          "description": "⚠ ADR-05 新增：LLM 输出 JSON Schema 强约束，走 provider-native structured output。仅 llm 节点生效（skill 节点 loader 拒绝）；详见 docs/workflow-design.md。"
         },
         "context_files": {
           "type": "array",