minimal-agent 0.12.0 → 0.14.0

package/workflows/goal/README.md

@@ -0,0 +1,166 @@
+# goal —— 目标驱动的自主循环
+
+`/workflow goal` 现在是文件式 **Goal Runtime** 的唯一命令入口。Goal Runtime 管长期目标、契约版本、
+Attempt、暂停恢复和人类验收；本工作流只负责一次 Attempt 内的“执行 → 确定性硬门 → 独立审计”。
+Agent 自检成功只会进入 `ready_for_acceptance`，不会替人完成最终验收。
+
+这里坚持“轻引擎、重工作流”：`workflow-runner` 不含 Goal 状态机、契约字段或群业务分支，只提供
+通用 managed-execution 租约、journal、工具/Agent 调用和验证能力。`managedRuntime: 'goal'` 只声明
+本工作流受外层 Goal Runtime 管理；如何拟定契约、分阶段循环、检测停滞、审计和生成报告仍全部位于
+本目录的 `workflow.mjs` 与配套脚本中。
+
+对标 OpenAI Codex 的 `/goal`（其内部叫 Ralph Loop），但有三处刻意的不同 —— 见下。
+
+## 用法
+
+```bash
+# 完整路径：自己拟契约，开头确认一次，之后全程自主
+minimal-agent -p "/workflow goal 把 src/parser.ts 的错误处理补全，所有现有测试保持通过"
+
+# 已经想好退出条件 —— 跳过契约拟定与确认，直接开跑（Codex 推荐的用法）
+minimal-agent -p "/workflow goal 修复 #1234 --input checks=\"shell:bun test test/bug.test.ts,file_exists:src/fix.ts\""
+
+# 无人值守（跳过确认闸门）
+minimal-agent -p "/workflow goal <目标> --input interactive=false --input max_iterations=12"
+```
+
+`objective` 是贪婪首参（整句自然语言不会被空格拆碎），其余参数**必须**走 `--input k=v`。
+
+```bash
+# 查看、暂停、继续
+/workflow goal --input action=status
+/workflow goal --input action=pause
+/workflow goal --input action=resume
+
+# 显式改变目标（产生新契约版本和 Attempt）
+/workflow goal "修订后的目标" --input action=update
+
+# 人类验收或发回同一个 Goal 返工
+/workflow goal --input action=accept
+/workflow goal --input action=rework --input reason="补充 Windows 绿色版说明"
+
+# 取消后才能创建另一个 Goal；历史不会删除
+/workflow goal --input action=cancel
+```
+
+同一个 Session 同时只能有一个未完成 Goal。输入不同目标不会隐式覆盖当前 Goal，必须明确 `update`
+或 `cancel`；这取代了旧的 LLM 语义仲裁和“换目标就自动清除”行为。
+
+### ⚠️ 含空格的 `--input` 值一定要加引号（自测时真踩到了）
+
+```bash
+# ❌ 值被静默截断成 `shell:bun`，剩下的词跑去拼进目标文本，全程无警告
+--input checks=shell:bun test test/x.ts
+
+# ✅ 引号包住整个 k=v（引号在 token 任意位置都认）
+--input "checks=shell:bun test test/x.ts"
+--input checks="shell:bun test test/x.ts"
+```
+
+`shell:` 检查几乎必然含空格，所以这条基本每次都会遇到。
+
+**为什么没有警告**：引擎对「值被拆碎」有自动拼回 + 告警的机制，但它只在贪婪首参
+**已经走了 `--input`** 时才触发；本工作流的 `objective` 通常走位置参数，命中的是另一条
+分支，于是散落的词被静默拼进目标末尾。截断后的检查串往往**仍然合法**
+（`shell:exit 1` 截成 `shell:exit`，而不带参数的 `exit` 退出码是 0）——
+于是硬门反而"通过"了。这是自测时真实发生的一幕。
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `checks` | 空 | 逗号分隔的退出条件。给了就跳过契约拟定与确认 |
+| `max_iterations` | 8 | 最大轮数（硬顶 50） |
+| `stall_rounds` | 3 | 连续几轮「失败项及归一化失败证据完全相同」判定卡死 |
+| `interactive` | `true` | `false` 跳过契约确认闸门 |
+| `action` | 空 | `status/pause/resume/update/cancel/accept/rework` |
+| `reason` | 空 | 暂停、取消或返工原因 |
+
+## 退出条件只能写这四种
+
+契约里的 `hard_checks` 由引擎的 `verify()` 真跑，格式必须是：
+
+| 格式 | 例子 |
+|---|---|
+| `shell:<命令>` | `shell:bun test test/parser.test.ts` |
+| `file_exists:<路径>` | `file_exists:src/parser.ts` |
+| `file_contains:<路径>:<字符串>` | `file_contains:README.md:## 安装` |
+| `test_count:<数字>` | `test_count:12` |
+
+⚠️ **`shell:` 有 30 秒超时**（引擎写死）。跑不完的全量测试套件要缩到具体文件或加过滤。
+
+⚠️ **`node --test <目录>` 与 `node --test <文件>` 行为不同**（Node v22 上跑目录会把目录本身
+当一个 subtest，目录里的非测试文件会让它失败）。写检查时用你**真正想跑的那条命令**，
+别想当然 —— 这条是自测时踩到的。
+
+## 三处与 Codex `/goal` 刻意的不同
+
+**① 我们做目标澄清，Codex 不做。**
+Codex 官方明确「finish line 模糊时就别用 Goals」，只肯在你要求时帮你起草。
+社区反复吐槽的坑正是弱目标 → 循环不收敛 → 烧 token。我们有 `ask()`，所以在阶段 0 把目标
+**契约化**：拟不出可验证判据时把缺的信息问出来。
+⚠️ 但**只在开头问一次**，确认后全程自主 —— 循环体里绝不停下来问。
+
+**② 完成判定是两道独立的关，不是让干活的模型自己打分。**
+先过引擎跑命令的确定性硬门，再过一个 `isolated: true` 的审计 agent ——
+它**看不见执行者的对话**，只能自己去查文件系统。Codex 的 completion audit 是同一思路，
+而社区吐槽「有时仍不够严格，需要额外的独立 critic」—— 隔离上下文就是为这个。
+
+审计除了判达成与否，还专门查两件硬门查不出来的事：
+- **为通过检查而削弱检查**（改松断言、`|| true`、`--passWithNoTests`、把关键字塞进注释）
+- **检查覆盖不全**（目标要三种格式，检查只测了实现的那一种）
+
+**③ 质量评估只报告、不阻塞。**
+功能达成做门；性能 / 易用性 / 鲁棒性做报告。把开放式质量判断放进停止条件，
+循环永远不收敛（总能再挑出一条可优化的）。本仓库有过真实教训：PPT 视觉门一度把对比度、
+字号做成硬 ERROR，结果是卡死重试；后来改成质量类一律 WARNING、硬 ERROR 只留确定性缺陷。
+
+## 两层状态
+
+Goal Runtime 是事实源，状态为：
+
+`active / paused / blocked / usage_limited / budget_limited / ready_for_acceptance / accepted / cancelled`
+
+除 `accepted/cancelled` 外都属于未完成。只有指定人类能把 `ready_for_acceptance` 变成 `accepted`。
+`STATUS.json` 只是一次 Attempt 的兼容投影：
+
+| 状态 | 含义 |
+|---|---|
+| `achieved` | 硬门全过且独立审计确认；对应 Goal `ready_for_acceptance`，不是最终完成 |
+| `stalled` | 连续 N 轮失败项和证据都不变 —— 空转，Goal 转为 `blocked` |
+| `max_iterations` | 轮数耗尽仍未达成 |
+| `budget_limited` | 用户设定的 Token 预算已用尽；对应 Goal `budget_limited`，加预算后可从断点续跑 |
+
+工作流可以通过 Goal 契约的 `tokenBudget` 使用 `budget_limited`：引擎在每轮结束后
+持久化 provider 用量，并在下一轮开始前停止；工作流通过 `workflowOutcome` 把这个
+Attempt 结局传回 Goal Runtime。除此之外，轮数上限和无进展检测仍然负责防止空转。
+这两类限制不能混为一谈：预算耗尽可以加预算后续跑，轮数/无进展失败则需要先处理
+具体阻塞原因。
+
+**未达成时工作流会抛错**（落盘之后才抛），让 `-p --output-format json` 的
+`ok`/`stop_reason` 如实反映"没做成"。产物在抛错前已全部写好。
+
+## 断点续跑 / 暂停恢复
+
+Goal Runtime 为每个 Attempt 分配 UUID 状态目录，不再用规范化目标哈希判断是否完成：
+
+- **暂停** = `ESC` 或 `action=pause`，Attempt journal 与现场保留；
+- **恢复** = `action=resume`，复用被停止/失败 Attempt 的 journal；
+- **返工** = `action=rework`，保持同一 Goal，建立新 Attempt；
+- **更新契约** = `action=update`，旧 Attempt 标记 superseded，新契约和 Attempt 接管；
+- **取消** = `action=cancel`，只结束当前 Goal，不删除事件、报告或产物。
+
+⚠️ 每轮开头会 `resetContext()`，契约每轮重新拼进 prompt，所以截断上下文不会丢关键信息。
+
+## 产物
+
+```
+out/goal/<session>/<attemptId>/
+├── CONTRACT.md    完成契约（目标复述、产出物、确定性检查、质量维度）
+├── STATUS.json    结局状态 + 四维分数 + 阻塞原因（给宿主程序读）
+└── REPORT.md      人看的报告：结果、审计证据、未达成原因、质量评估
+```
+
+## 什么时候**不该**用它
+
+- 一行修改、一个解释、一次简短 review —— 循环的开销远大于收益（Codex 官方同款建议）。
+- **给不出任何可机器验证判据的目标**。阶段 0 会尝试问你，但如果连问完都拟不出
+  `hard_checks`，说明这件事还不适合跑自主循环 —— 先用 `/workflow plan` 把它想清楚。

package/workflows/goal/prompts/audit.md

@@ -0,0 +1,57 @@
+你是**独立验收审计员**。
+
+⚠️ **你没有参与前面的执行，也看不到执行者说过什么** —— 这是刻意的。
+你唯一的信息来源是**文件系统的当前状态**和**你自己跑命令得到的输出**。
+不要脑补执行者做了什么，去看。
+
+## 被审计的目标
+
+{{restated_goal}}
+
+## 完成契约
+
+**应当存在的产出物**：
+{{deliverables}}
+
+**确定性检查**（这些已经由引擎跑过，全部通过了 —— 你要查的是它们**是否真的意味着目标达成**）：
+{{hard_checks}}
+
+**质量维度**（无法用命令验证，需要你判断）：
+{{soft_criteria}}
+
+{{supplements}}
+
+## 你要做的事
+
+### 1. 逐条核实产出物真实存在且有实质内容
+用 `Read` / `Glob` / `Bash` 亲自查。**空文件、只有 TODO 的文件、只有函数签名没有实现的文件
+都不算数** —— 这是最常见的"检查通过但目标没达成"。
+
+### 2. 警惕「为了通过检查而削弱检查」
+确定性检查全过了，但要确认它们**没有被做手脚**：
+- 测试断言是不是被改松了 / 被删了 / 被 `skip` 了？
+- 命令是不是被加了 `|| true`、`--passWithNoTests` 之类？
+- `file_contains` 要求的字符串是不是被塞在注释里凑数？
+
+发现这类情况 → `achieved: false`，并在 `blocking_reason` 里指名道姓说清楚。
+
+### 3. 判断检查是否**充分覆盖**目标
+契约里的检查是一开始拟的，可能不完整。如果所有检查都过了但目标显然还没达成
+（例如目标要「支持三种格式」而只实现了一种，恰好检查只测了那一种）——
+`achieved: false`，把缺口写进 `blocking_reason`。
+
+### 4. 给质量评分（这部分**不影响** achieved 判定）
+四个维度各给 0-10 分，并在 `notes` 里写清楚扣分点和最值得做的优化。
+- `functionality` 功能完整度（目标要的事做到了几成）
+- `performance` 性能（有明显低效/阻塞/重复计算吗；没依据就按中位数给分并在 notes 说明）
+- `usability` 易用性（API/CLI/文档对使用者是否清楚）
+- `robustness` 鲁棒性（错误处理、边界情况、失败时的表现）
+
+**这四个分数只用于生成报告，不会阻塞循环。** 所以请诚实打分，
+不要因为「打低分会不会导致又跑一轮」而虚高 —— 不会。
+
+## 输出
+
+只输出 JSON 对象本身，不要 markdown 代码围栏、不要解释。
+`evidence` 数组里每一条写成「我做了什么 → 看到了什么」，必须是你**本轮真实执行**的结果，
+不得转述、不得推测。

package/workflows/goal/prompts/contract.md

@@ -0,0 +1,56 @@
+你的任务是把一个自然语言目标，转成一份**可机器验证的完成契约**。
+
+## 目标原文
+
+{{objective}}
+
+## 为什么这一步决定成败
+
+后面会有一个自主循环反复执行、反复检查，直到契约被满足才停。所以：
+
+- 契约写得**可验证**，循环就能自己收敛，跑完就是真做完了。
+- 契约写得含糊（「代码更好」「性能优化」「体验提升」），循环**永远判断不了何时结束** ——
+  要么早早误判完成，要么一直空转烧钱。
+
+**你现在写的东西就是那个停止条件本身。**
+
+## 输出字段
+
+### `restated_goal`
+用一句话复述目标。如果原文有歧义，按最合理的解释复述，并把你的解释写明确
+（例如原文说「加个测试」，你复述成「为 X 模块新增单元测试并使其通过」）。
+
+### `deliverables`
+具体的产出物清单。**要写路径或可指认的东西**，不要写动作。
+- ✅ `src/parser.ts`、`README 的「安装」一节`、`test/parser.test.ts`
+- ❌ `重构代码`、`改进文档`
+
+### `hard_checks` —— 最重要的字段
+可以被**机器确定性验证**的退出条件。每一条必须是下面四种格式之一：
+
+| 格式 | 含义 | 例子 |
+|---|---|---|
+| `shell:<命令>` | 命令退出码为 0 算通过 | `shell:bun test test/parser.test.ts` |
+| `file_exists:<路径>` | 文件存在 | `file_exists:src/parser.ts` |
+| `file_contains:<路径>:<字符串>` | 文件含某内容 | `file_contains:README.md:## 安装` |
+| `test_count:<数字>` | 测试数不少于 N | `test_count:12` |
+
+**硬性约束（写错会导致整条工作流启动即失败）**：
+- 冒号前的类型名必须**逐字**是上表四个之一，不要自创 `command:` / `exists:` / `assert:`。
+- `shell:` 的命令有 **30 秒超时**。跑不完的全量测试套件要缩到具体文件或用 `--filter`。
+- `shell:` 命令必须**不需要人交互**、不依赖只有你这次会话才有的临时状态。
+- 至少给 1 条。给不出任何可验证判据的目标，说明它还不适合跑自主循环 ——
+  这种情况把缺的信息写进 `clarifications`。
+
+### `soft_criteria`
+需要**人或模型判断**、无法用命令验证的质量要求（可读性、API 是否好用、边界情况覆盖…）。
+
+⚠️ 它们**不会**被用作停止条件 —— 只会在收尾时作为评估报告输出。
+这是刻意的：把开放式质量判断放进停止条件，循环永远不会收敛（总能再挑出一条可优化的）。
+所以别把「必须做到的事」写进这里，那种要写进 `hard_checks`。
+
+### `clarifications`
+目标里**缺失且影响验收口径**的关键信息，最多 3 条，每条写成一个可以直接问用户的问题。
+没有就给空数组。**不要为了凑数而问**——能自己合理推断的就推断，写进 `restated_goal`。
+
+## 只输出 JSON 对象本身，不要 markdown 代码围栏、不要解释。

package/workflows/goal/prompts/iterate.md

@@ -0,0 +1,37 @@
+你正在一个**目标驱动的自主循环**里工作。这是第 {{iter}}/{{max}} 轮。
+
+## 目标
+
+{{restated_goal}}
+
+## 完成契约（这是验收标准，不是建议）
+
+**产出物**：
+{{deliverables}}
+
+**必须通过的确定性检查**（循环会真的跑这些命令，你说做完了不算）：
+{{hard_checks}}
+
+{{supplements}}
+
+## 上一轮的情况
+
+{{last_status}}
+
+## 这一轮要做什么
+
+**动手做，不要只描述计划。** 你有工具，用它们真实地修改文件、跑命令、看结果。
+
+具体要求：
+1. 先弄清现状 —— 该读的文件读、该跑的命令跑，别在假设上动手。
+2. 针对上面列出的**未通过的检查**做实际修改。上一轮卡在哪，这一轮就攻哪。
+3. 改完**自己先跑一遍**对应的检查命令，确认真的过了再结束这一轮。
+4. 如果发现契约里的某条检查本身写错了（命令不存在、路径拼错），
+   **不要绕过它去改别的** —— 明确说出来，并说明你认为正确的写法是什么。
+
+## 不要做的事
+
+- ❌ 不要为了让检查通过而**削弱检查本身**（改测试断言、删测试、给命令加 `|| true`）。
+  循环下一轮会用同样的命令重新验证，而最后还有一道独立审计会看你到底改了什么。
+- ❌ 不要宣称完成。完成与否由循环跑命令决定，不由你的自述决定。
+- ❌ 不要一次改一大片不相关的东西。这一轮只推进契约里还没满足的部分。