minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/test/childWorkflow.test.ts

@@ -0,0 +1,304 @@
+import { expect, test } from 'bun:test';
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadWorkflowDir } from '../src/discovery.js';
+import { coerceInputs } from '../src/inputCoercion.js';
+import { runWorkflowScript } from '../src/runner.js';
+import type { RunContext } from '../src/types.js';
+
+async function fixture(parent: string, child: string) {
+  const cwd = await mkdtemp(join(tmpdir(), 'wf-child-'));
+  async function put(name: string, source: string) {
+    const dir = join(cwd, 'workflows', name);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'workflow.mjs'), source);
+  }
+  await put('parent', parent);
+  await put('child', child);
+  let calls = 0;
+  let peak = 0;
+  let active = 0;
+  const ctx = {
+    cwd,
+    provider: { name: 'stub' },
+    history: [{ role: 'system', content: 'sys' }],
+    tools: [],
+    chat: async function* () {
+      calls++;
+      active++;
+      peak = Math.max(peak, active);
+      await new Promise((r) => setTimeout(r, 5));
+      active--;
+      yield { type: 'text_delta', delta: 'child-value' };
+      yield {
+        type: 'done',
+        stopReason: 'stop',
+        promptTokens: 10,
+        outputTokens: 2,
+      };
+    },
+  } as unknown as RunContext;
+  async function run(name = 'parent') {
+    const script = await loadWorkflowDir(join(cwd, 'workflows', name));
+    if (!script.ok) throw Error(script.errors.join(';'));
+    const events = [];
+    for await (const e of runWorkflowScript(script.workflow, {
+      ctx,
+      inputs: {},
+      sessionId: 'test',
+    }))
+      events.push(e);
+    return events;
+  }
+  async function done() {
+    const base = join(cwd, '.minimal-agent-workflow/parent/test');
+    return join(base, (await readdir(base)).find((n) => n.endsWith('.done'))!);
+  }
+  return { cwd, ctx, put, run, done, calls: () => calls, peak: () => peak };
+}
+const parent = `export const meta={description:'parent',dependencies:['child']};
+export default async function run(wf) { const r=await wf.flow.child('child', {}, {label:'child-label'}); wf.output.message(r.result); return r; }`.replace('{description:', '{apiVersion:2,description:');
+const child = `export const meta={apiVersion:2,description:'child'}; export default async function run(wf) { return await wf.model.generate('child', {isolated:true}); }`;
+
+test('root and child use strict typed input coercion', () => {
+  const defs = [{ name: 'n', type: 'number' as const }];
+  expect(coerceInputs({ n: '900' }, defs)).toEqual({ n: 900 });
+  expect(coerceInputs({ n: 900 }, defs)).toEqual({ n: 900 });
+  for (const n of ['3abc', '', Number.POSITIVE_INFINITY, {}])
+    expect(() => coerceInputs({ n }, defs)).toThrow();
+});
+
+test('child JSON return persists; only root completes; completed replay; missing return restarts', async () => {
+  const h = await fixture(parent, child);
+  const events = await h.run();
+  expect(events.filter((e) => e.type === 'error')).toEqual([]);
+  expect(events.filter((e) => e.type === 'turn_done')).toHaveLength(1);
+  expect(h.ctx.resourceLedger?.inputTokens).toBe(10);
+  const dir = await h.done();
+  expect(
+    JSON.parse(await readFile(join(dir, 'return.json'), 'utf8')).result,
+  ).toBe('child-value');
+  await h.run();
+  expect(h.calls()).toBe(1);
+  await unlink(join(dir, 'return.json'));
+  await h.run();
+  expect(h.calls()).toBe(2);
+});
+
+test('parent resume reuses completed child and child bundle change invalidates parent', async () => {
+  const h = await fixture(
+    parent.replace(
+      'wf.output.message(r.result);',
+      `if (!(await wf.fs.exists('continue'))) throw new Error('pause'); wf.output.message(r.result);`,
+    ),
+    child,
+  );
+  expect((await h.run()).some((e) => e.type === 'error')).toBe(true);
+  await writeFile(join(h.cwd, 'continue'), 'go');
+  expect((await h.run()).some((e) => e.type === 'error')).toBe(false);
+  expect(h.calls()).toBe(1);
+  await h.put('child', `${child}\n// changed contract`);
+  await h.run();
+  expect(h.calls()).toBe(2);
+  await h.run('child');
+  expect(h.calls()).toBe(3); // standalone identity differs
+});
+
+test('caught child failure does not send top-level error, undeclared/managed/cyclic dependencies fail', async () => {
+  const h = await fixture(
+    parent.replace(
+      "const r=await wf.flow.child('child', {}, {label:'child-label'}); wf.output.message(r.result); return r;",
+      `try {await wf.flow.child('child');} catch(e) {wf.output.message('caught');} return null;`,
+    ),
+    `export const meta={apiVersion:2,description:'child'};export default async function run(wf){throw new Error('broken');}`,
+  );
+  expect((await h.run()).some((e) => e.type === 'error')).toBe(false);
+  await h.put(
+    'child',
+    `export const meta={apiVersion:2,description:'child',dependencies:['parent']};export default async function run(wf){}`,
+  );
+  expect(
+    (await h.run()).some(
+      (e) => e.type === 'error' && e.error.includes('依赖环'),
+    ),
+  ).toBe(true);
+  await h.put(
+    'child',
+    `export const meta={apiVersion:2,description:'child',managedRuntime:'goal'};export default async function run(wf){}`,
+  );
+  expect(
+    (await h.run()).some(
+      (e) => e.type === 'error' && e.error.includes('managedRuntime'),
+    ),
+  ).toBe(true);
+  await h.put(
+    'parent',
+    `export const meta={apiVersion:2,description:'parent'};export default async function run(wf){await wf.flow.child('child');}`,
+  );
+  const undeclaredEvents = await h.run();
+  expect(
+    undeclaredEvents.some(
+      (e) => e.type === 'error' && e.error.includes('未声明'),
+    ),
+  ).toBe(true);
+});
+
+test('pipeline child instances are isolated, share gate and usage; missing child output invalidates tree', async () => {
+  const h = await fixture(
+    `export const meta={apiVersion:2,description:'parent',dependencies:['child']}; export default async function run(wf){const batch=await wf.flow.pipeline(Array.from({length:12},(_,i)=>i),{label:'children',concurrency:8,errorMode:'fail-fast',stages:[async(i)=>wf.flow.child('child',{i})]});return batch.results.map(r=>r.value);}`,
+    child,
+  );
+  const events = await h.run();
+  expect(events.filter((e) => e.type === 'error')).toEqual([]);
+  expect(h.calls()).toBe(12);
+  expect(h.peak()).toBeLessThanOrEqual(8);
+  expect(h.ctx.resourceLedger?.inputTokens).toBe(120);
+  const results = JSON.parse(
+    await readFile(join(await h.done(), 'return.json'), 'utf8'),
+  );
+  expect(new Set(results.map((r: { runId: string }) => r.runId)).size).toBe(12);
+  await h.run();
+  expect(h.calls()).toBe(12);
+  const childRoot = join(await h.done(), 'children/child');
+  await unlink(join(childRoot, (await readdir(childRoot))[0], 'return.json'));
+  await h.run();
+  expect(h.calls()).toBe(24);
+  // 36 次真实子工作流实例化（各自 mkdir/journal/progress.md/return.json）在较慢的
+  // 文件系统（尤其 Windows）上实测约 5s，超过 bun 默认 5000ms 测试超时——这是真实
+  // 磁盘 IO 耗时，不是卡死或回归，给足预算避免偶发超时。
+}, 15000);
+
+test('parent cancellation remains interrupted even if child exception is caught', async () => {
+  const h = await fixture(parent, child);
+  const controller = new AbortController();
+  h.ctx.signal = controller.signal;
+  h.ctx.chat = async function* () {
+    controller.abort();
+    yield* [];
+    throw Object.assign(new Error('stop'), { name: 'AbortError' });
+  };
+  const events = await h.run();
+  expect(events.some((e) => e.type === 'interrupted')).toBe(true);
+  expect(events.some((e) => e.type === 'turn_done')).toBe(false);
+});
+
+test('explicit child resources use workflow cwd and do not inherit parent attachments/history', async () => {
+  const h = await fixture(
+    parent.replace(
+      "wf.flow.child('child', {}",
+      "wf.flow.child('child', {source:'input.png'}",
+    ),
+    `export const meta={apiVersion:2,description:'child',inputs:[{name:'source',type:'resource',required:true,accepts:['image/*'],attachmentFallback:true}]}; export default async function run(wf){return {source:wf.input.values.source};}`,
+  );
+  await writeFile(
+    join(h.cwd, 'input.png'),
+    Buffer.from(
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a5lsAAAAASUVORK5CYII=',
+      'base64',
+    ),
+  );
+  h.ctx.history.push({ role: 'user', content: 'private-parent-context' });
+  const events = await h.run();
+  expect(events.filter((e) => e.type === 'error')).toEqual([]);
+  const value = JSON.parse(
+    await readFile(join(await h.done(), 'return.json'), 'utf8'),
+  );
+  expect(value.result.source).toBe(join(h.cwd, 'input.png'));
+  await h.put('parent', parent); // No explicit source: must not absorb any parent attachment.
+  const missingResourceEvents = await h.run();
+  expect(
+    missingResourceEvents.some(
+      (e) => e.type === 'error' && /source|输入/.test(e.error),
+    ),
+  ).toBe(true);
+});
+
+test('history isolation preserves system instructions and child uses the same tool authorization ceiling', async () => {
+  const h = await fixture(parent, child);
+  h.ctx.history.push({ role: 'user', content: 'private-parent-context' });
+  h.ctx.chat = async function* (options) {
+    expect(JSON.stringify(options)).not.toContain('private-parent-context');
+    yield { type: 'text_delta', delta: 'ok' };
+    yield { type: 'done', stopReason: 'stop' };
+  } as RunContext['chat'];
+  expect((await h.run()).filter((e) => e.type === 'error')).toEqual([]);
+  await h.put(
+    'child',
+    `export const meta={apiVersion:2,description:'child'}; export default async function run(wf){await wf.tools.call('NotAuthorized',{});}`,
+  );
+  const unauthorizedEvents = await h.run();
+  expect(unauthorizedEvents.some((e) => e.type === 'error')).toBe(true);
+});
+
+test('artifact ownership tree archives once without touching standalone child outputs', async () => {
+  const h = await fixture(
+    parent,
+    `export const meta={apiVersion:2,description:'child'}; export default async function run(wf){const path='artifact-'+wf.runtime.taskId+'.txt';wf.output.artifact(path);await wf.tools.call('Write',{file_path:path,content:'owned'});return {path};}`,
+  );
+  const toolCallIds: string[] = [];
+  h.ctx.executeTool = (async (
+    _name: string,
+    raw: string,
+    _signal: unknown,
+    context: { toolCallId: string },
+  ) => {
+    toolCallIds.push(context.toolCallId);
+    const input = JSON.parse(raw);
+    await writeFile(join(h.cwd, input.file_path), input.content);
+    return { ok: true, content: 'written' };
+  }) as unknown as RunContext['executeTool'];
+  // Match the host's real Write dispatch shape; the tool is deliberately restricted to this fixture.
+  h.ctx.tools = [
+    {
+      name: 'Write',
+      description: 'write fixture',
+      parameters: { type: 'object', properties: {} },
+    },
+  ] as unknown as RunContext['tools'];
+  const first = await h.run();
+  expect(first.filter((e) => e.type === 'error')).toEqual([]);
+  const result = JSON.parse(
+    await readFile(join(await h.done(), 'return.json'), 'utf8'),
+  );
+  expect(result.artifacts).toContain(join(h.cwd, result.result.path));
+  await h.run('child');
+  const before = (await readdir(h.cwd)).filter((n) =>
+    n.startsWith('artifact-'),
+  );
+  expect(before).toHaveLength(2);
+  await unlink(join(h.cwd, result.result.path));
+  expect((await h.run()).some((e) => e.type === 'error')).toBe(false);
+  expect(
+    await readFile(
+      join(h.cwd, before.find((n) => n !== result.result.path)!),
+      'utf8',
+    ),
+  ).toBe('owned');
+  expect(new Set(toolCallIds).size).toBe(toolCallIds.length);
+});
+
+test('dependency depth is bounded and JSON-only return is enforced', async () => {
+  const h = await fixture(parent, child);
+  for (let i = 0; i < 8; i++)
+    await h.put(
+      i === 0 ? 'child' : `level${i}`,
+      `export const meta={apiVersion:2,description:'level',dependencies:['level${i + 1}']};export default async function run(wf){return wf.flow.child('level${i + 1}',{});}`,
+    );
+  await h.put('level8', `export const meta={apiVersion:2,description:'last'};export default async function run(wf){return null;}`);
+  expect(
+    (await h.run()).some((e) => e.type === 'error' && e.error.includes('8层')),
+  ).toBe(true);
+  await h.put(
+    'child',
+    `export const meta={apiVersion:2,description:'child'};export default async function run(wf){return {bad:Infinity};}`,
+  );
+  expect((await h.run()).some((e) => e.type === 'error')).toBe(true);
+});

package/plugins/workflow-runner/test/discovery.test.ts

@@ -0,0 +1,234 @@
+/**
+ * plugins/workflow-runner/test/discovery.test.ts —— 工作流目录发现
+ *
+ * 这里守的重点是**坏工作流的可见性**。
+ *
+ * legacy loader 的做法是「坏 yaml → console.warn 后从列表里消失」，于是用户看到的
+ * 现象是「我的工作流不见了」而不是「我的工作流写错了」——两者的排查成本差一个数量级。
+ * 本项目在别处已经为同一类静默降级付过学费（插件漏注册悄悄退化成 markdown prompt、
+ * 资产目录漏拷导致「未找到说明书」），所以新引擎把失败原因显式带出来。
+ *
+ * 用 discoverWorkflowsIn(roots) 而不是 mock 掉 getResourceSearchPaths：项目惯例是
+ * 依赖注入，`mock.module` 会全局泄漏污染同批其它测试文件。
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  discoverWorkflowsIn,
+  findWorkflowByName,
+  loadWorkflowDir,
+} from '../src/discovery.js';
+
+const created: string[] = [];
+
+afterEach(() => {
+  for (const dir of created.splice(0)) {
+    // Windows 上偶发 EBUSY（杀毒/索引器短暂持有句柄），重试 + 吞掉，
+    // 否则会把上一条**已通过**的测试标成失败，误导排查方向。
+    try {
+      rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+    } catch {
+      /* 清理失败不影响断言结论 */
+    }
+  }
+});
+
+/** 建一个临时的 workflows 根，返回该根路径。 */
+function makeRoot(): string {
+  const base = mkdtempSync(join(tmpdir(), 'wf-discovery-'));
+  created.push(base);
+  const root = join(base, 'workflows');
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+/** 在根下建一个工作流目录，写入给定脚本内容。 */
+function makeWorkflow(root: string, name: string, source: string): string {
+  const dir = join(root, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'workflow.mjs'), source, 'utf8');
+  return dir;
+}
+
+const GOOD = `export const meta = { apiVersion: 2, description: '一个合法工作流' }
+export default async function run(wf) { wf.output.message('hi') }
+`;
+
+describe('工作流目录发现', () => {
+  test('发现合法工作流，name 取目录名而非任何脚本内字段', async () => {
+    const root = makeRoot();
+    makeWorkflow(root, 'my-flow', GOOD);
+
+    const { workflows, failures } = await discoverWorkflowsIn([root]);
+
+    expect(failures).toEqual([]);
+    expect(workflows.map((w) => w.name)).toEqual(['my-flow']);
+    expect(workflows[0].meta.description).toBe('一个合法工作流');
+    expect(workflows[0].scriptPath).toBe(join(root, 'my-flow', 'workflow.mjs'));
+  });
+
+  test('meta 的 inputs / artifacts 被解析出来', async () => {
+    const root = makeRoot();
+    makeWorkflow(
+      root,
+      'with-meta',
+      `export const meta = {
+  apiVersion: 2,
+  description: 'x',
+  inputs: [{ name: 'topic', greedy: true, required: true }],
+  artifacts: ['out/a.md', 'out/b.md'],
+}
+export default async function run(wf) { wf.output.message('ok') }
+`,
+    );
+
+    const { workflows } = await discoverWorkflowsIn([root]);
+    expect(workflows[0].meta.inputs?.[0]).toMatchObject({
+      name: 'topic',
+      greedy: true,
+    });
+    expect(workflows[0].meta.artifacts).toEqual(['out/a.md', 'out/b.md']);
+  });
+
+  test('managedRuntime 只是外层控制器声明，不改变普通工作流脚本形态', async () => {
+    const root = makeRoot();
+    makeWorkflow(
+      root,
+      'managed',
+      `export const meta = { apiVersion: 2, description: 'x', managedRuntime: 'goal' }
+export default async function run(wf) { wf.output.message('ok') }
+`,
+    );
+    const { workflows } = await discoverWorkflowsIn([root]);
+    expect(workflows[0]?.meta.managedRuntime).toBe('goal');
+  });
+
+  test('★ 坏脚本进 failures 并带上原因，不是静默消失', async () => {
+    const root = makeRoot();
+    makeWorkflow(
+      root,
+      'broken',
+      `export const meta = { apiVersion: 2, description: 'x' }\nexport default async function run() { const t = Date.now() }\n`,
+    );
+
+    const { workflows, failures } = await discoverWorkflowsIn([root]);
+
+    expect(workflows).toEqual([]);
+    expect(failures).toHaveLength(1);
+    expect(failures[0].name).toBe('broken');
+    expect(failures[0].errors.join('\n')).toContain('Date.now()');
+  });
+
+  test('★ 一个坏工作流不拖累同目录下的好工作流', async () => {
+    const root = makeRoot();
+    makeWorkflow(
+      root,
+      'broken',
+      `export const meta = { apiVersion: 2, description: 'x' }\nexport default async function run() { Date.now() }\n`,
+    );
+    makeWorkflow(root, 'fine', GOOD);
+
+    const { workflows, failures } = await discoverWorkflowsIn([root]);
+
+    expect(workflows.map((w) => w.name)).toEqual(['fine']);
+    expect(failures.map((f) => f.name)).toEqual(['broken']);
+  });
+
+  test('★ 没有 workflow.mjs 的普通目录既不算工作流也不算失败', async () => {
+    // assets/、模板目录、编辑器的临时目录都会出现在这里。把它们报成
+    // 「加载失败」等于每次 /workflows 都刷一堆假告警，用户很快就不看告警了。
+    const root = makeRoot();
+    mkdirSync(join(root, 'just-a-folder'), { recursive: true });
+    makeWorkflow(root, 'real', GOOD);
+
+    const { workflows, failures } = await discoverWorkflowsIn([root]);
+
+    expect(workflows.map((w) => w.name)).toEqual(['real']);
+    expect(failures).toEqual([]);
+  });
+
+  test('目录里的 *.yaml 不被代码引擎认领（legacy 引擎的地盘）', async () => {
+    const root = makeRoot();
+    writeFileSync(
+      join(root, 'old-style.yaml'),
+      'name: old\nsteps: []\n',
+      'utf8',
+    );
+
+    const { workflows, failures } = await discoverWorkflowsIn([root]);
+    expect(workflows).toEqual([]);
+    expect(failures).toEqual([]);
+  });
+
+  test('搜索根不存在 → 空结果，不抛', async () => {
+    const r = await discoverWorkflowsIn([
+      join(tmpdir(), 'definitely-not-here-xyz'),
+    ]);
+    expect(r).toEqual({ workflows: [], failures: [] });
+  });
+
+  describe('多根优先级', () => {
+    test('★ 前面的根覆盖后面的同名工作流（cwd 覆盖包内自带）', async () => {
+      const high = makeRoot();
+      const low = makeRoot();
+      makeWorkflow(
+        high,
+        'dup',
+        `export const meta = { apiVersion: 2, description: '高优先级' }\nexport default async function run(wf){wf.output.message('a')}\n`,
+      );
+      makeWorkflow(
+        low,
+        'dup',
+        `export const meta = { apiVersion: 2, description: '低优先级' }\nexport default async function run(wf){wf.output.message('b')}\n`,
+      );
+
+      const { workflows } = await discoverWorkflowsIn([high, low]);
+
+      expect(workflows).toHaveLength(1);
+      expect(workflows[0].meta.description).toBe('高优先级');
+    });
+
+    test('★ 高优先级里写错的工作流**占住**这个名字，不被低优先级同名顶替', async () => {
+      // 否则现象是「我改坏了 cwd 里的工作流，跑起来却是包内那个旧版本」——
+      // 静默换了实现体，比直接报错难查得多。
+      const high = makeRoot();
+      const low = makeRoot();
+      makeWorkflow(
+        high,
+        'dup',
+        `export const meta = { apiVersion: 2, description: 'x' }\nexport default async function run(){Date.now()}\n`,
+      );
+      makeWorkflow(
+        low,
+        'dup',
+        `export const meta = { apiVersion: 2, description: '包内版本' }\nexport default async function run(wf){wf.output.message('b')}\n`,
+      );
+
+      const { workflows, failures } = await discoverWorkflowsIn([high, low]);
+
+      expect(workflows).toEqual([]);
+      expect(failures.map((f) => f.name)).toEqual(['dup']);
+    });
+  });
+});
+
+describe('loadWorkflowDir / findWorkflowByName', () => {
+  test('loadWorkflowDir 对缺失脚本给出可读原因', async () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'empty'), { recursive: true });
+    const r = await loadWorkflowDir(join(root, 'empty'));
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.reason).toBe('no-script');
+      expect(r.errors[0]).toContain('workflow.mjs');
+    }
+  });
+
+  test('findWorkflowByName 找不到时返回 null（可能是 legacy yaml，由调用方决定）', async () => {
+    expect(await findWorkflowByName('绝不存在的工作流名-xyz')).toBeNull();
+  });
+});

package/plugins/workflow-runner/test/goalAnchor.test.ts

@@ -0,0 +1,106 @@
+/**
+ * plugins/workflow-runner/test/goalAnchor.test.ts —— 目标锚定与补充要求
+ *
+ * 守两条：
+ *  ① 锚由引擎注入，**对脚本作者透明** —— 作者不写 `${goal}`，每次 agent/llm/skill
+ *    调用都自动带上。多步长跑（尤其压缩之后）模型会忘记原始目标而偏航。
+ *  ② 补充要求与原始目标**同等贯穿**，且在**没有**原始锚时也必须注入 ——
+ *    那种场景下它们就是仅有的约束，漏掉等于用户白说。
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  buildGoalAnchor,
+  effectiveGoalAnchor,
+  withGoalAnchor,
+} from '../src/goalAnchor.js';
+import type { RunContext } from '../src/types.js';
+
+const ctx = (over: Partial<RunContext>): RunContext => over as RunContext;
+
+describe('buildGoalAnchor', () => {
+  test('优先取名为 goal 的输入', () => {
+    const a = buildGoalAnchor({ topic: '别的', goal: '真目标' });
+    expect(a).toContain('真目标');
+    expect(a).not.toContain('别的');
+  });
+
+  test('无 goal 时取第一个 required 字符串输入', () => {
+    const a = buildGoalAnchor({ n: 3, topic: '调研主题' }, [
+      { name: 'n' },
+      { name: 'topic', required: true },
+    ]);
+    expect(a).toContain('调研主题');
+  });
+
+  test('没有 required 声明时退到第一个非空字符串', () => {
+    expect(buildGoalAnchor({ y: '内容' })).toContain('内容');
+  });
+
+  test('★ 两个字的中文目标必须取到（曾被 >2 的长度阈值跳过）', () => {
+    // 那条阈值是照拉丁文本想的（跳过 ab、语言代码），对中文直接失效。
+    expect(buildGoalAnchor({ name: '世界' })).toContain('世界');
+  });
+
+  test('★ 取不到真实文本时不拿 JSON 兜底值当锚', () => {
+    // extractGoal 最后一档会回退成整体 JSON（为了让 taskId 恒有确定值），
+    // 但那种东西绝不能当目标注入给模型 —— 它会朝着一坨 JSON 努力。
+    expect(buildGoalAnchor({ pages: 12 })).toBe('');
+  });
+
+  test('★ 一个字符串输入都没有 → 空串（无锚），不硬凑', () => {
+    // 硬凑一个假目标比没有目标更糟：模型会朝着那个假目标努力。
+    expect(buildGoalAnchor({ pages: 12 })).toBe('');
+    expect(buildGoalAnchor({ goal: '   ' })).toBe('');
+  });
+});
+
+describe('effectiveGoalAnchor', () => {
+  test('只有锚 → 原样返回', () => {
+    expect(effectiveGoalAnchor(ctx({ goalAnchor: '> 🎯 目标：A' }))).toBe(
+      '> 🎯 目标：A',
+    );
+  });
+
+  test('锚 + 补充要求 → 补充逐条跟在锚后面', () => {
+    const out = effectiveGoalAnchor(
+      ctx({
+        goalAnchor: '> 🎯 目标：A',
+        goalSupplements: ['改成 12 页', '要中文'],
+      }),
+    );
+    expect(out).toContain('目标：A');
+    expect(out).toContain('改成 12 页');
+    expect(out).toContain('要中文');
+  });
+
+  test('★ 没有原始锚时补充要求仍要注入，并说明其效力等级', () => {
+    const out = effectiveGoalAnchor(ctx({ goalSupplements: ['只用中文'] }));
+    expect(out).toContain('只用中文');
+    expect(out).toContain('同等约束');
+  });
+
+  test('空白补充要求被过滤', () => {
+    expect(
+      effectiveGoalAnchor(
+        ctx({ goalAnchor: 'A', goalSupplements: ['  ', ''] }),
+      ),
+    ).toBe('A');
+  });
+
+  test('全无 → 空串（调用方据此跳过注入）', () => {
+    expect(effectiveGoalAnchor(ctx({}))).toBe('');
+  });
+});
+
+describe('withGoalAnchor', () => {
+  test('有锚时前置，中间空一行', () => {
+    const out = withGoalAnchor(ctx({ goalAnchor: '锚' }), '干活');
+    expect(out).toBe('锚\n\n干活');
+  });
+
+  test('★ 无锚时原样返回 —— 不留多余空行污染 prompt 开头', () => {
+    expect(withGoalAnchor(ctx({}), '干活')).toBe('干活');
+  });
+});