minimal-agent 0.12.0 → 0.14.0

package/workflows/ralph-loop.yaml

@@ -1,199 +0,0 @@
-name: ralph-loop
-description: |
-  Ralph Wiggum 迭代开发循环——通过重复执行同一目标直到完成。
-
-  核心机制：while 循环 + fresh context（每轮重置 history）+ 哨兵协议 + 验证门。
-  状态机（phase: PLAN→BUILD→VERIFY/HEAL→DONE）全部用 type:set 确定性赋值，
-  prompt 拼装也用 set（曾用 llm 步当赋值/拼串——模型自由回复非确定，是事故源）。
-
-  哨兵协议（精确匹配，防"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
-    greedy: true
-    description: "不可变目标描述（可一句话自然语言；命令行 workflow 名后整句进 goal，不被空格拆碎）"
-  - name: max_iterations
-    type: number
-    default: 50
-    description: "【高级·用 --input max_iterations=N】最大迭代次数（安全阀，默认 50，硬上限 200）"
-  - name: verify_checks
-    type: string
-    default: ""
-    description: "【高级·用 --input verify_checks=...】验证门检查项（逗号分隔，如 'shell:bun test,file_exists:src/index.ts'）。空则跳过验证门。"
-
-self_heal:
-  max_retries: 1       # 单步瞬态失败（LLM 超时等）重试一次
-  retry_delay_ms: 3000 # 重试退避，给瞬态故障留恢复窗口
-
-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）
-  #  每轮：set 拼 prompt → agent 工作 → 教训累积 → 哨兵检测 → 阶段推进
-  # ============================================================
-  - type: loop
-    id: main_loop
-    title: "迭代开发"
-    max_iterations: "${inputs.max_iterations}"
-    fresh_context: true
-    do:
-      # --- 1. 构造本轮 prompt（确定性字符串拼装，set 步零 LLM） ---
-      - id: build_prompt
-        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
-
-      # --- 3. 提取 learning（确定性正则 extract，零 LLM 零幻觉；
-      #        曾用 llm 步提取——模型可能改写/漏抄/编造，教训档案被污染） ---
-      - id: extract_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
-        title: "教训存档落盘"
-        tool: Write
-        args:
-          file_path: .minimal-agent-workflow/ralph-loop/learnings.md
-          content: "${learnings_text}"
-        when: "extracted_learning != ''"
-        onError: continue
-
-      # --- 5. 哨兵检测（平铺互斥分支，精确匹配；不再有嵌套 then/else 迷宫） ---
-
-      # 5a. 完成哨兵（精确标签，防 "incomplete" 含 "complete" 类误判）→ 验证门
-      - id: on_done
-        title: "哨兵检测·完成"
-        type: branch
-        condition: "includes(lower(output), '<promise>done</promise>')"
-        then:
-          # 验证门：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: "verify_passed == true"
-            then:
-              - id: set_done
-                type: set
-                set:
-                  phase: DONE
-              - id: exit_success
-                type: break
-            else:
-              # 验证未过：模型谎报/漏测 → 回 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' && !includes(lower(output), '<promise>')"
-        then:
-          - id: to_build
-            type: set
-            set:
-              phase: BUILD
-
-  # === 循环结束后的收尾 ===
-  - id: final_summary
-    title: "完成·执行总结"
-    llm: |
-      总结本轮 ralph-loop 的执行结果（最终阶段：${phase}）。
-      - phase=DONE：目标完成，列出关键产出物。
-      - phase=GOAL_REVISION：目标本身需要修订，说明模型给出的理由。
-      - 其它：因达到迭代上限而退出，说明当前进度和下一步建议。
-    maxTurns: 1

package/workflows/schema.json

@@ -1,176 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/billsoft/kakadeai/minimal-agent/workflows/schema.json",
-  "title": "minimal-agent workflow",
-  "description": "Workflow YAML schema, v0.1 — see docs/workflow-plugin-plan.md",
-  "type": "object",
-  "required": ["name", "description", "steps"],
-  "additionalProperties": true,
-  "properties": {
-    "name": { "type": "string", "minLength": 1 },
-    "description": { "type": "string", "minLength": 1 },
-    "version": { "type": "string" },
-    "inputs": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["name"],
-        "properties": {
-          "name": { "type": "string", "minLength": 1 },
-          "type": { "enum": ["string", "number", "enum"] },
-          "required": { "type": "boolean" },
-          "default": {},
-          "values": { "type": "array", "items": { "type": "string" } },
-          "description": { "type": "string" }
-        }
-      }
-    },
-    "steps": {
-      "type": "array",
-      "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": {
-    "step": {
-      "type": "object",
-      "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", "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 基行号）。"
-        },
-        "input": { "type": "string" },
-        "capture": {
-          "type": "object",
-          "additionalProperties": { "type": "string" }
-        },
-        "when": { "type": "string" },
-        "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": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/step" }
-        },
-        "else": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/step" }
-        },
-        "over": { "type": "string" },
-        "as": { "type": "string" },
-        "do": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/step" }
-        },
-        "prompt": { "type": "string" },
-        "free_text": {
-          "type": "string",
-          "enum": ["halt", "approve"],
-          "description": "type=pause 时自由输入的处理方式：halt=不放行（默认）；approve=作为补充要求放行，可配 capture.text 传给后续步骤。"
-        },
-        "max_iterations": {
-          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "string", "minLength": 1 }]
-        },
-        "done_when": {
-          "type": "string",
-          "minLength": 1,
-          "description": "仅 agent 步可选：确定性完成条件（白名单表达式，如 fileExists('./out/x.pptx')）。不满足时引擎自动提醒同一 agent 继续执行（上限 2 次），仍不满足按可重试失败处理。弱模型「宣告要干却不调工具就停」的引擎级兜底。"
-        },
-        "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",
-          "items": {
-            "type": "object",
-            "required": ["path"],
-            "properties": {
-              "path": { "type": "string", "minLength": 1 },
-              "hint": { "type": "string" }
-            }
-          },
-          "description": "⚠ ADR-05 新增：仅 llm 节点声明可用的上下文文件清单（path + hint），runner 拼进 prompt 并开放 Read 子循环，不 inline 内容（skill 节点 loader 拒绝）。详见 docs/workflow-design.md。"
-        },
-        "allowed_tools": {
-          "type": "array",
-          "items": { "type": "string", "minLength": 1 },
-          "description": "⚠ ADR-05 新增：与 context_files 配对的 mini ReAct 工具白名单，缺省 ['Read']。详见 docs/05-advanced-workflow-integration.md。"
-        }
-      }
-    }
-  }
-}