minimal-agent 0.12.0 → 0.14.0

package/plugins/workflow-runner/src/journal.js

@@ -0,0 +1,224 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/journal.ts —— 断点续跑账本
+ * ------------------------------------------------------------
+ *  代码编排里没有「步骤索引」可以定位断点 —— 控制流是 JS 决定的，同一个脚本
+ *  两次运行经过的分支可能都不一样。所以断点按**车道内序号 + 内容指纹**记账：
+ *  每次 agent/llm/skill/tool/verify/ask 调用记一行 jsonl，resume 时按序重放，
+ *  某条车道上首个指纹失配处转实跑并作废该车道其后全部记录。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **车道（lane）解决的是并发下的定位错乱**（这是实测过的降级，不是假想）：
+ *
+ *  序号原本在**拿到并发闸之后**才自增，于是扇出超过并发上限（8）时，第 9 项的
+ *  序号取决于前 8 项谁先返回 —— 也就是取决于 LLM 延迟。同一个脚本两次运行的
+ *  序号分配可能完全不同 → 首个失配 → 后面全部实跑，**resume 静默失效**。
+ *  N ≤ 8 的用例恒绿，所以这个坑不写针对性测试就看不见。
+ *
+ *  修法不是改成内容寻址（那会把下面那条安全属性静默换掉），而是给每条并发链
+ *  一个**确定性的车道名**，车道内序号严格按该链的执行顺序自增 —— 链本身是串行的，
+ *  所以顺序确定。车道名由 `pipeline()` 按 (嵌套路径, 项下标) 生成，与调度无关。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **为什么不是纯内容寻址**（有人会想「按 fp 查表不就顺序无关了」）：
+ *
+ *      run 1: agent 产出 plan v1 → agent('审查 out/plan.md') 得 R2
+ *      run 2: 第一步实跑产出 plan v2 → 那句审查的 fp **一模一样**（路径是常量，
+ *             内容在磁盘上）→ 命中缓存 → 拿到的是对 v1 的审查
+ *
+ *  失配即作废其后记录，正是为了挡住这个。内容寻址挡不住，且是**静默错误**。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **必须现在就认下的语义降级**（别等第一次真实 resume 才发现）：
+ *
+ *  指纹按**内容**算（kind + 参数）。而 `agent()` 的 prompt 常常是用上一次调用的
+ *  产出拼出来的，`runQuery` 又非确定性 —— 于是**重放边界之后的第一次实跑一旦
+ *  产出不同，同车道其后所有调用的指纹全部失配、余下部分整体作废**。
+ *  代价与 Claude Code 官方文档写明的那条一致（"every agent that started after
+ *  that one runs again"），接受。
+ *
+ *  这也是 `scriptGuard` 禁 `Date.now()`/`Math.random()`/无参 `new Date()` 的原因 ——
+ *  脚本里任何不确定性都会让指纹在重放时必然失配，等于 resume 直接失效。
+ *
+ *  ------------------------------------------------------------
+ *  V2 不重放旧执行器留下的账本。每条记录都绑定引擎 API、bundle hash 与根运行，
+ *  只有同一份工作流依赖图产生的调用才能快进。
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 主车道名。脚本顶层的串行调用都走它。 */
+export const MAIN_LANE = 'main';
+/** 计算一次调用的内容指纹。 */
+export function fingerprint(kind, args) {
+    // JSON.stringify 的键序依赖对象构造顺序，同一份逻辑参数可能序列化成两种字符串。
+    // 排序后再序列化，让指纹只取决于内容本身。
+    const stable = stableStringify(args);
+    return createHash('sha256')
+        .update(`${kind} ${stable}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v) ?? 'null';
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const keys = Object.keys(v).sort();
+    return `{${keys
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`)
+        .join(',')}}`;
+}
+export class Journal {
+    identity;
+    path;
+    /** 上次运行留下的记录，按 `lane#idx` 索引。 */
+    loaded = new Map();
+    /** 各车道的游标与分叉状态。 */
+    lanes = new Map();
+    /** 写入序号（跨车道全局单调，仅用于展示与 backoff）。 */
+    writeSeq = 0;
+    /** 实际命中重放的次数 —— 测试要断言这个**具体数字**。 */
+    replayed = 0;
+    /** 本次运行是否真跑过至少一次（`replaying` 据此判定，见下）。 */
+    liveRan = false;
+    constructor(path, identity) {
+        this.identity = identity;
+        this.path = path;
+    }
+    /**
+     * 读入上次的账本。
+     *
+     * @param backoff 额外丢弃末尾 N 条（承接 legacy 的 `self_heal.backoff`）——
+     *                最后一次成功调用可能留下了未完成的副作用，宁可重做。
+     *                按**写入顺序**丢弃，与车道无关。
+     */
+    async load(backoff = 0) {
+        this.loaded.clear();
+        let parsed = [];
+        try {
+            const raw = await readFile(this.path, 'utf8');
+            for (const line of raw.split('\n')) {
+                if (line.trim() === '')
+                    continue;
+                try {
+                    const entry = JSON.parse(line);
+                    if (entry.apiVersion !== 2 ||
+                        entry.bundleHash !== this.identity.bundleHash) {
+                        // V1 或另一份依赖图留下的记录不能混入当前恢复链。rootRunId 只用于
+                        // 追踪原始执行树；恢复天然会获得新的 rootRunId，不能据此拒绝重放。
+                        parsed = [];
+                        break;
+                    }
+                    parsed.push(entry);
+                }
+                catch {
+                    // 单行坏掉（上次被 kill 在写盘中间）→ 从这里截断，前面的仍然可用。
+                    break;
+                }
+            }
+        }
+        catch {
+            return; // 没有账本 = 全新运行
+        }
+        if (backoff > 0)
+            parsed = parsed.slice(0, -backoff);
+        for (const e of parsed) {
+            this.loaded.set(`${e.lane ?? MAIN_LANE}#${e.idx ?? e.seq - 1}`, e);
+        }
+        this.writeSeq = parsed.length;
+    }
+    /** 本次已重放的调用数。 */
+    get replayedCount() {
+        return this.replayed;
+    }
+    /** 上次账本里的记录数。 */
+    get loadedCount() {
+        return this.loaded.size;
+    }
+    /**
+     * 本次运行是否还**一次实跑都没发生**（即：到此为止全是快进）。
+     *
+     * 给**不进账本**的调用判断「这一段是不是在重放」用。典型是 `echo()`：它写进
+     * `ctx.history`，而 resume 时 history 是从会话文件加载的、**上一轮的 echo 已经在
+     * 里面了** —— 快进段再 push 一次就成了重复消息。进账本的调用不需要这个判断，
+     * `step()` 在重放时压根不执行 `run()`。
+     *
+     * ⚠️ 判据是「有没有实跑过」而**不是**「游标有没有走到账本末尾」：车道化之后
+     * 序号不再跨车道单调，「走到哪了」在并发下没有意义，而「还没干过真活」在
+     * 任何调度下都成立。
+     */
+    get replaying() {
+        return this.loaded.size > 0 && !this.liveRan;
+    }
+    /** 下一个写入序号（进度展示用，不改变任何状态）。 */
+    get nextSeq() {
+        return this.writeSeq + 1;
+    }
+    laneState(lane) {
+        let st = this.lanes.get(lane);
+        if (!st) {
+            st = { next: 0, diverged: false };
+            this.lanes.set(lane, st);
+        }
+        return st;
+    }
+    /** 某条车道是否已分叉（`pipeline` 用它把子车道的分叉向上传播）。 */
+    laneDiverged(lane) {
+        return this.laneState(lane).diverged;
+    }
+    /**
+     * 手工把一条车道标记为已分叉。
+     *
+     * `pipeline()` 在子链抛错、或任一子车道分叉时用它污染主车道 —— 下游串行步骤
+     * 依赖扇出的聚合结果，上游变了就不能再拿旧结果冒充。
+     */
+    markDiverged(lane) {
+        this.laneState(lane).diverged = true;
+    }
+    /**
+     * 走一次调用：命中重放就直接返回缓存结果，否则执行 `run` 并记账。
+     *
+     * 这是**唯一**的记账入口 —— 所有需要恢复的 `wf` 能力都必须经过它，否则 resume 时
+     * 车道内序号会对不上（少记一次，该车道后面全错位）。
+     */
+    async step(kind, args, run, lane = MAIN_LANE) {
+        const st = this.laneState(lane);
+        const idx = st.next++;
+        const fp = fingerprint(kind, args);
+        if (!st.diverged) {
+            const prev = this.loaded.get(`${lane}#${idx}`);
+            if (prev && prev.fp === fp) {
+                this.replayed++;
+                return prev.result;
+            }
+            // 该车道首个失配：其后的记录一律作废（控制流可能已经走了另一条分支）。
+            st.diverged = true;
+        }
+        // 在 await 之前翻 —— `replaying` 是给同步的 echo() 看的，晚翻会漏判。
+        this.liveRan = true;
+        const result = await run();
+        await this.append({
+            apiVersion: 2,
+            bundleHash: this.identity.bundleHash,
+            rootRunId: this.identity.rootRunId,
+            seq: ++this.writeSeq,
+            lane,
+            idx,
+            kind,
+            fp,
+            result,
+        });
+        return result;
+    }
+    async append(entry) {
+        try {
+            await mkdir(dirname(this.path), { recursive: true });
+            await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf8');
+        }
+        catch {
+            // 账本写失败不该让任务本身挂掉 —— 代价只是下次 resume 少续一点。
+        }
+    }
+}

package/plugins/workflow-runner/src/journal.ts

@@ -0,0 +1,274 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/journal.ts —— 断点续跑账本
+ * ------------------------------------------------------------
+ *  代码编排里没有「步骤索引」可以定位断点 —— 控制流是 JS 决定的，同一个脚本
+ *  两次运行经过的分支可能都不一样。所以断点按**车道内序号 + 内容指纹**记账：
+ *  每次 agent/llm/skill/tool/verify/ask 调用记一行 jsonl，resume 时按序重放，
+ *  某条车道上首个指纹失配处转实跑并作废该车道其后全部记录。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **车道（lane）解决的是并发下的定位错乱**（这是实测过的降级，不是假想）：
+ *
+ *  序号原本在**拿到并发闸之后**才自增，于是扇出超过并发上限（8）时，第 9 项的
+ *  序号取决于前 8 项谁先返回 —— 也就是取决于 LLM 延迟。同一个脚本两次运行的
+ *  序号分配可能完全不同 → 首个失配 → 后面全部实跑，**resume 静默失效**。
+ *  N ≤ 8 的用例恒绿，所以这个坑不写针对性测试就看不见。
+ *
+ *  修法不是改成内容寻址（那会把下面那条安全属性静默换掉），而是给每条并发链
+ *  一个**确定性的车道名**，车道内序号严格按该链的执行顺序自增 —— 链本身是串行的，
+ *  所以顺序确定。车道名由 `pipeline()` 按 (嵌套路径, 项下标) 生成，与调度无关。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **为什么不是纯内容寻址**（有人会想「按 fp 查表不就顺序无关了」）：
+ *
+ *      run 1: agent 产出 plan v1 → agent('审查 out/plan.md') 得 R2
+ *      run 2: 第一步实跑产出 plan v2 → 那句审查的 fp **一模一样**（路径是常量，
+ *             内容在磁盘上）→ 命中缓存 → 拿到的是对 v1 的审查
+ *
+ *  失配即作废其后记录，正是为了挡住这个。内容寻址挡不住，且是**静默错误**。
+ *
+ *  ------------------------------------------------------------
+ *  ⚠️ **必须现在就认下的语义降级**（别等第一次真实 resume 才发现）：
+ *
+ *  指纹按**内容**算（kind + 参数）。而 `agent()` 的 prompt 常常是用上一次调用的
+ *  产出拼出来的，`runQuery` 又非确定性 —— 于是**重放边界之后的第一次实跑一旦
+ *  产出不同，同车道其后所有调用的指纹全部失配、余下部分整体作废**。
+ *  代价与 Claude Code 官方文档写明的那条一致（"every agent that started after
+ *  that one runs again"），接受。
+ *
+ *  这也是 `scriptGuard` 禁 `Date.now()`/`Math.random()`/无参 `new Date()` 的原因 ——
+ *  脚本里任何不确定性都会让指纹在重放时必然失配，等于 resume 直接失效。
+ *
+ *  ------------------------------------------------------------
+ *  V2 不重放旧执行器留下的账本。每条记录都绑定引擎 API、bundle hash 与根运行，
+ *  只有同一份工作流依赖图产生的调用才能快进。
+ * ============================================================
+ */
+
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/** 主车道名。脚本顶层的串行调用都走它。 */
+export const MAIN_LANE = 'main';
+
+/** 账本里一条已完成调用的记录。 */
+export interface JournalEntry {
+  apiVersion: 2;
+  bundleHash: string;
+  rootRunId: string;
+  /** 写入顺序（1-based）。并发下它**不代表**逻辑顺序，只用于展示与 backoff。 */
+  seq: number;
+  /** 车道名；v1 记录没有这个字段，载入时按 'main' 解释。 */
+  lane?: string;
+  /** 车道内序号（0-based）；v1 记录没有，载入时按 `seq - 1` 解释。 */
+  idx?: number;
+  /** 调用类别：agent / llm / skill / tool / verify / ask …… */
+  kind: string;
+  /** 内容指纹：sha256(kind + 归一化参数) 前 16 位。 */
+  fp: string;
+  /** 该次调用的返回值（JSON 可序列化）。 */
+  result: unknown;
+}
+
+export interface JournalIdentity {
+  bundleHash: string;
+  rootRunId: string;
+}
+
+/** 计算一次调用的内容指纹。 */
+export function fingerprint(kind: string, args: unknown): string {
+  // JSON.stringify 的键序依赖对象构造顺序，同一份逻辑参数可能序列化成两种字符串。
+  // 排序后再序列化，让指纹只取决于内容本身。
+  const stable = stableStringify(args);
+  return createHash('sha256')
+    .update(`${kind} ${stable}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v) ?? 'null';
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(v as Record<string, unknown>).sort();
+  return `{${keys
+    .map(
+      (k) =>
+        `${JSON.stringify(k)}:${stableStringify((v as Record<string, unknown>)[k])}`,
+    )
+    .join(',')}}`;
+}
+
+interface LaneState {
+  /** 该车道下一次调用的序号（0-based）。 */
+  next: number;
+  /** 该车道是否已失配转实跑。 */
+  diverged: boolean;
+}
+
+export class Journal {
+  private readonly path: string;
+  /** 上次运行留下的记录，按 `lane#idx` 索引。 */
+  private loaded = new Map<string, JournalEntry>();
+  /** 各车道的游标与分叉状态。 */
+  private lanes = new Map<string, LaneState>();
+  /** 写入序号（跨车道全局单调，仅用于展示与 backoff）。 */
+  private writeSeq = 0;
+  /** 实际命中重放的次数 —— 测试要断言这个**具体数字**。 */
+  private replayed = 0;
+  /** 本次运行是否真跑过至少一次（`replaying` 据此判定，见下）。 */
+  private liveRan = false;
+
+  constructor(path: string, private readonly identity: JournalIdentity) {
+    this.path = path;
+  }
+
+  /**
+   * 读入上次的账本。
+   *
+   * @param backoff 额外丢弃末尾 N 条（承接 legacy 的 `self_heal.backoff`）——
+   *                最后一次成功调用可能留下了未完成的副作用，宁可重做。
+   *                按**写入顺序**丢弃，与车道无关。
+   */
+  async load(backoff = 0): Promise<void> {
+    this.loaded.clear();
+    let parsed: JournalEntry[] = [];
+    try {
+      const raw = await readFile(this.path, 'utf8');
+      for (const line of raw.split('\n')) {
+        if (line.trim() === '') continue;
+        try {
+          const entry = JSON.parse(line) as Partial<JournalEntry>;
+          if (
+            entry.apiVersion !== 2 ||
+            entry.bundleHash !== this.identity.bundleHash
+          ) {
+            // V1 或另一份依赖图留下的记录不能混入当前恢复链。rootRunId 只用于
+            // 追踪原始执行树；恢复天然会获得新的 rootRunId，不能据此拒绝重放。
+            parsed = [];
+            break;
+          }
+          parsed.push(entry as JournalEntry);
+        } catch {
+          // 单行坏掉（上次被 kill 在写盘中间）→ 从这里截断，前面的仍然可用。
+          break;
+        }
+      }
+    } catch {
+      return; // 没有账本 = 全新运行
+    }
+    if (backoff > 0) parsed = parsed.slice(0, -backoff);
+    for (const e of parsed) {
+      this.loaded.set(`${e.lane ?? MAIN_LANE}#${e.idx ?? e.seq - 1}`, e);
+    }
+    this.writeSeq = parsed.length;
+  }
+
+  /** 本次已重放的调用数。 */
+  get replayedCount(): number {
+    return this.replayed;
+  }
+
+  /** 上次账本里的记录数。 */
+  get loadedCount(): number {
+    return this.loaded.size;
+  }
+
+  /**
+   * 本次运行是否还**一次实跑都没发生**（即：到此为止全是快进）。
+   *
+   * 给**不进账本**的调用判断「这一段是不是在重放」用。典型是 `echo()`：它写进
+   * `ctx.history`，而 resume 时 history 是从会话文件加载的、**上一轮的 echo 已经在
+   * 里面了** —— 快进段再 push 一次就成了重复消息。进账本的调用不需要这个判断，
+   * `step()` 在重放时压根不执行 `run()`。
+   *
+   * ⚠️ 判据是「有没有实跑过」而**不是**「游标有没有走到账本末尾」：车道化之后
+   * 序号不再跨车道单调，「走到哪了」在并发下没有意义，而「还没干过真活」在
+   * 任何调度下都成立。
+   */
+  get replaying(): boolean {
+    return this.loaded.size > 0 && !this.liveRan;
+  }
+
+  /** 下一个写入序号（进度展示用，不改变任何状态）。 */
+  get nextSeq(): number {
+    return this.writeSeq + 1;
+  }
+
+  private laneState(lane: string): LaneState {
+    let st = this.lanes.get(lane);
+    if (!st) {
+      st = { next: 0, diverged: false };
+      this.lanes.set(lane, st);
+    }
+    return st;
+  }
+
+  /** 某条车道是否已分叉（`pipeline` 用它把子车道的分叉向上传播）。 */
+  laneDiverged(lane: string): boolean {
+    return this.laneState(lane).diverged;
+  }
+
+  /**
+   * 手工把一条车道标记为已分叉。
+   *
+   * `pipeline()` 在子链抛错、或任一子车道分叉时用它污染主车道 —— 下游串行步骤
+   * 依赖扇出的聚合结果，上游变了就不能再拿旧结果冒充。
+   */
+  markDiverged(lane: string): void {
+    this.laneState(lane).diverged = true;
+  }
+
+  /**
+   * 走一次调用：命中重放就直接返回缓存结果，否则执行 `run` 并记账。
+   *
+   * 这是**唯一**的记账入口 —— 所有需要恢复的 `wf` 能力都必须经过它，否则 resume 时
+   * 车道内序号会对不上（少记一次，该车道后面全错位）。
+   */
+  async step<T>(
+    kind: string,
+    args: unknown,
+    run: () => Promise<T>,
+    lane: string = MAIN_LANE,
+  ): Promise<T> {
+    const st = this.laneState(lane);
+    const idx = st.next++;
+    const fp = fingerprint(kind, args);
+
+    if (!st.diverged) {
+      const prev = this.loaded.get(`${lane}#${idx}`);
+      if (prev && prev.fp === fp) {
+        this.replayed++;
+        return prev.result as T;
+      }
+      // 该车道首个失配：其后的记录一律作废（控制流可能已经走了另一条分支）。
+      st.diverged = true;
+    }
+
+    // 在 await 之前翻 —— `replaying` 是给同步的 echo() 看的，晚翻会漏判。
+    this.liveRan = true;
+    const result = await run();
+    await this.append({
+      apiVersion: 2,
+      bundleHash: this.identity.bundleHash,
+      rootRunId: this.identity.rootRunId,
+      seq: ++this.writeSeq,
+      lane,
+      idx,
+      kind,
+      fp,
+      result,
+    });
+    return result;
+  }
+
+  private async append(entry: JournalEntry): Promise<void> {
+    try {
+      await mkdir(dirname(this.path), { recursive: true });
+      await appendFile(this.path, `${JSON.stringify(entry)}\n`, 'utf8');
+    } catch {
+      // 账本写失败不该让任务本身挂掉 —— 代价只是下次 resume 少续一点。
+    }
+  }
+}

package/plugins/workflow-runner/src/jsonSchema.js

@@ -0,0 +1,132 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/jsonSchema.ts —— JSON Schema 子集校验
+ * ------------------------------------------------------------
+ *  为什么手写而不是引 ajv：
+ *   ① 工作流的结构化输出契约采用可序列化的 JSON Schema 子集，便于参与 journal
+ *      指纹并跨 provider 使用。
+ *   ② 校验结果要**回喂给模型做修复**，所以错误消息比规范覆盖度重要得多 ——
+ *      「`branches[2].score` 应为 number，实际是 string」比一句
+ *      `must be number` 有用，而通用库的默认文案偏向后者。
+ *   ③ 项目一贯取向：能用基本类型说清就不引第三方（见 CLAUDE.md 设计原则）。
+ *
+ *  支持的关键字：type（含数组联合）/ properties / required / items /
+ *  enum / additionalProperties:false / minItems / maxItems / minimum / maximum /
+ *  nullable。**不支持**的关键字一律**忽略**（宽松），不报错 —— 校验器的职责是
+ *  挡住畸形输出，不是当规范警察；误伤一个合法产出的代价比放过一个边角约束大。
+ * ============================================================
+ */
+function typeOf(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (Number.isInteger(v))
+        return 'integer';
+    return typeof v;
+}
+/** `integer` 也满足 `number`；其余按 typeof 对齐。 */
+function typeMatches(want, v) {
+    const actual = typeOf(v);
+    if (want === actual)
+        return true;
+    if (want === 'number')
+        return actual === 'integer' || actual === 'number';
+    if (want === 'integer')
+        return actual === 'integer';
+    return false;
+}
+function describe(v) {
+    const t = typeOf(v);
+    if (t === 'string')
+        return `string(${JSON.stringify(String(v)).slice(0, 40)})`;
+    if (t === 'array')
+        return `array(长度 ${v.length})`;
+    if (t === 'object')
+        return `object(键 ${Object.keys(v).join('/')})`;
+    return `${t}(${String(v)})`;
+}
+function walk(value, schema, path, out) {
+    if (!schema || typeof schema !== 'object')
+        return;
+    if (value === null && schema.nullable === true)
+        return;
+    if (schema.enum && Array.isArray(schema.enum)) {
+        if (!schema.enum.some((e) => e === value)) {
+            out.push({
+                path,
+                message: `应为 [${schema.enum.map((e) => JSON.stringify(e)).join(', ')}] 之一，实际是 ${describe(value)}`,
+            });
+            return;
+        }
+    }
+    if (schema.type !== undefined) {
+        const wants = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!wants.some((w) => typeMatches(w, value))) {
+            out.push({
+                path,
+                message: `应为 ${wants.join(' 或 ')}，实际是 ${describe(value)}`,
+            });
+            return; // 类型都不对，再查下去只会刷屏
+        }
+    }
+    const t = typeOf(value);
+    if (t === 'object') {
+        const obj = value;
+        for (const key of schema.required ?? []) {
+            if (!(key in obj)) {
+                out.push({ path: path ? `${path}.${key}` : key, message: '缺少必填字段' });
+            }
+        }
+        if (schema.properties) {
+            for (const [key, sub] of Object.entries(schema.properties)) {
+                if (key in obj)
+                    walk(obj[key], sub, path ? `${path}.${key}` : key, out);
+            }
+            if (schema.additionalProperties === false) {
+                for (const key of Object.keys(obj)) {
+                    if (!(key in schema.properties)) {
+                        out.push({
+                            path: path ? `${path}.${key}` : key,
+                            message: '不允许的额外字段',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    if (t === 'array') {
+        const arr = value;
+        if (typeof schema.minItems === 'number' && arr.length < schema.minItems) {
+            out.push({ path, message: `至少要 ${schema.minItems} 项，实际 ${arr.length} 项` });
+        }
+        if (typeof schema.maxItems === 'number' && arr.length > schema.maxItems) {
+            out.push({ path, message: `最多 ${schema.maxItems} 项，实际 ${arr.length} 项` });
+        }
+        if (schema.items) {
+            arr.forEach((el, i) => walk(el, schema.items, `${path}[${i}]`, out));
+        }
+    }
+    if (t === 'number' || t === 'integer') {
+        const n = value;
+        if (typeof schema.minimum === 'number' && n < schema.minimum) {
+            out.push({ path, message: `不得小于 ${schema.minimum}，实际 ${n}` });
+        }
+        if (typeof schema.maximum === 'number' && n > schema.maximum) {
+            out.push({ path, message: `不得大于 ${schema.maximum}，实际 ${n}` });
+        }
+    }
+}
+/** 校验一个值。返回空数组 = 通过。 */
+export function validateAgainstSchema(value, schema) {
+    const out = [];
+    walk(value, schema, '', out);
+    return out;
+}
+/** 把违规列表渲染成给**模型**看的修复指令（不是给人看的报错）。 */
+export function renderViolations(violations) {
+    return violations
+        .slice(0, 20)
+        .map((v) => `  · ${v.path || '(根)'}：${v.message}`)
+        .join('\n');
+}