@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/engine/__tests__/conformance/golden-replay.zcode.test.ts

@@ -0,0 +1,79 @@
+// golden-replay.zcode.test.ts —— zcode 引擎 golden 回放层（conformance 免 LLM 默认 CI
+// 层）。数据源 = P3 验收前置门的真机实录（engines/zcode/__tests__/__fixtures__/
+// zcode-golden-spawn.json 的 stdoutRaw）——parser 对实录样本回归 + coarse 事件合成
+// 不变量断言 + 双副本 diff 校验（fixture 与 golden-sample.ts 内嵌副本一致，防漂移：
+// 更新样本必须同步两处，探针的干跑校验消费内嵌副本，两处不一致 = 探针在测旧契约）。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import {
+  mapZcodeOutcomeUsage,
+  parseZcodeTerminal,
+  synthesizeCoarseEvents,
+} from "../../engines/zcode/parser.ts";
+import { assertAgentEventInvariants } from "./agent-event-invariants.ts";
+
+// conformance 目录（engine/__tests__/conformance）→ engine 根的相对定位
+const fixturePath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..", "..", // conformance → __tests__ → engine
+  "engines", "zcode", "__tests__", "__fixtures__", "zcode-golden-spawn.json",
+);
+
+interface ZcodeGoldenFile {
+  _meta: { engineVersion: string; exitCode: number };
+  stdoutRaw: string;
+}
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as ZcodeGoldenFile;
+
+describe("zcode golden 回放（conformance C3，免 LLM/免二进制）", () => {
+  it("双副本 diff：golden-sample.ts 内嵌副本 === fixture stdoutRaw（防漂移，A12）", () => {
+    expect(ZCODE_GOLDEN_STDOUT).toBe(fixture.stdoutRaw);
+  });
+
+  it("parser 对实录样本回归：sessionId/response/usage 形状完整（探针干跑同源断言）", () => {
+    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
+    expect(terminal.ok).toBe(true);
+    if (!terminal.ok) return;
+    expect(terminal.payload.sessionId).toMatch(/^sess_/);
+    expect(terminal.payload.response).toBe("ok");
+    expect(terminal.payload.usage).toEqual({ input: 12599, output: 17, cacheRead: 512, cacheWrite: 0 });
+    // 终态层 usage（orchestration 版）：cost 显式 0（无来源不给残缺）、contextTokens 取 projection
+    expect(terminal.payload.outcomeUsage).toEqual({
+      input: 12599,
+      output: 17,
+      cacheRead: 512,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 12616,
+      turns: 1,
+    });
+  });
+
+  it("coarse 事件合成满足产出不变量（turn_end 最后、其前必有 message_end、usage 完整）", () => {
+    const terminal = parseZcodeTerminal(fixture.stdoutRaw);
+    if (!terminal.ok) throw new Error("golden 样本解析失败（上一用例应已转红）");
+    const events = synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
+    assertAgentEventInvariants(events, { granularity: "coarse" });
+    expect(events.map((e) => e.type)).toEqual(["message_end", "turn_end"]);
+  });
+
+  it("usage 无来源样本：mapZcodeOutcomeUsage 显式缺省（不给残缺对象，不变量 2 的输入面）", () => {
+    expect(mapZcodeOutcomeUsage(undefined, undefined)).toBeUndefined();
+    expect(mapZcodeOutcomeUsage({ inputTokens: 1 }, undefined)).toEqual({
+      input: 1,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 0,
+      turns: 1,
+    });
+  });
+});

package/src/execution/engine/__tests__/engine-discovery.test.ts

@@ -0,0 +1,87 @@
+// engine-discovery.test.ts —— [U7] registry → engines.json 同步（幂等/原子/兜底）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { SubagentEnginesFile } from "@xyz-agent/extension-protocol";
+
+import { getEnginesFilePath, syncEnginesFile } from "../engine-discovery.ts";
+import type { EnginePort } from "../port.ts";
+import { clearEngines, registerEngine } from "../registry.ts";
+
+function stubEngine(id: string): EnginePort {
+  return {
+    id,
+    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
+    probe: async () => ({ ok: true, engineVersion: "test" }),
+    run: async () => {
+      throw new Error("unused");
+    },
+    interact: async () => {
+      throw new Error("unused");
+    },
+    read: async () => ({ engineId: id, turns: [], source: "outcome-only" }),
+  };
+}
+
+let tmpRoot: string;
+let agentDir: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "engine-discovery-"));
+  agentDir = path.join(tmpRoot, "agent");
+  clearEngines();
+});
+
+afterEach(() => {
+  clearEngines();
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("syncEnginesFile", () => {
+  it("注册表引擎列表落盘（v=1 + 注册序）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    registerEngine("zcode", () => stubEngine("zcode"));
+    syncEnginesFile(agentDir);
+    const file = JSON.parse(fs.readFileSync(getEnginesFilePath(agentDir), "utf8")) as SubagentEnginesFile;
+    expect(file.v).toBe(1);
+    expect(file.engines).toEqual(["pi", "zcode"]);
+    expect(typeof file.updatedAt).toBe("number");
+  });
+
+  it("幂等：引擎清单未变时第二次零写（mtime 不动）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    syncEnginesFile(agentDir);
+    const p = getEnginesFilePath(agentDir);
+    const statAfterFirst = fs.statSync(p);
+    syncEnginesFile(agentDir);
+    expect(fs.statSync(p).mtimeMs).toBe(statAfterFirst.mtimeMs);
+  });
+
+  it("新增引擎注册后内容变化触发重写", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    syncEnginesFile(agentDir);
+    registerEngine("acp", () => stubEngine("acp"));
+    syncEnginesFile(agentDir);
+    const file = JSON.parse(fs.readFileSync(getEnginesFilePath(agentDir), "utf8")) as SubagentEnginesFile;
+    expect(file.engines).toEqual(["pi", "acp"]);
+  });
+
+  it("现文件损坏（torn write 形态）时重建", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    const p = getEnginesFilePath(agentDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, "{ torn", "utf8");
+    syncEnginesFile(agentDir);
+    expect(() => JSON.parse(fs.readFileSync(p, "utf8"))).not.toThrow();
+  });
+
+  it("agentDir 不存在时建目录写入；IO 异常吞掉不抛（fail-safe）", () => {
+    registerEngine("pi", () => stubEngine("pi"));
+    expect(() => syncEnginesFile(agentDir)).not.toThrow();
+    expect(fs.existsSync(getEnginesFilePath(agentDir))).toBe(true);
+  });
+});

package/src/execution/engine/__tests__/engines-declaration.test.ts

@@ -0,0 +1,36 @@
+// engines-declaration.test.ts —— [U7b] 双源一致性守护：package.json 的
+// xyz-agent.subagentEngines 静态声明（runtime 冷启动回退源）必须与代码注册表一致。
+// 新增引擎时改注册点 + 声明两处；漏改声明会被本测试拦截（冷启动 GUI 将少列引擎）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+// package.json 与 src/ 的相对位置（本文件在 src/execution/engine/__tests__/ 下，四级上溯）
+const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../../package.json");
+
+describe("package.json xyz-agent.subagentEngines 静态声明一致性（U7b 冷启动回退源）", () => {
+  it("声明存在、非空、全为字符串", () => {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
+      "xyz-agent"?: { subagentEngines?: unknown };
+    };
+    const declared = pkg["xyz-agent"]?.subagentEngines;
+    expect(Array.isArray(declared)).toBe(true);
+    expect((declared as string[]).length).toBeGreaterThan(0);
+    expect((declared as unknown[]).every((e) => typeof e === "string")).toBe(true);
+  });
+
+  it("与组合根注册的引擎一致（registerPiEngine/registerZcodeEngine 后 listEngines 等值）", async () => {
+    // 直接 import 组合根注册模块（工厂体同款调用），再对 listEngines——不 import index.ts
+    // 全量工厂（避免拉起 ExtensionAPI 依赖面），注册点即一致性的代码侧事实源。
+    await import("../engines/pi/registration.ts").then((m) => m.registerPiEngine());
+    await import("../engines/zcode/registration.ts").then((m) => m.registerZcodeEngine());
+    const { listEngines } = await import("../registry.ts");
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as { "xyz-agent"?: { subagentEngines?: string[] } };
+    const declared = pkg["xyz-agent"]?.subagentEngines ?? [];
+    expect([...declared].sort()).toEqual([...listEngines()].sort());
+  });
+});

package/src/execution/engine/__tests__/model-prompt.test.ts

@@ -0,0 +1,85 @@
+// model-prompt.test.ts —— [U7] 引擎模型段注入的开关语义（defaultEngine）与段格式。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { EnginePort } from "../port.ts";
+import { clearEngines, registerEngine } from "../registry.ts";
+import { buildEngineModelsPromptAppend } from "../model-prompt.ts";
+
+/** 最小 fake 引擎：仅 id + 可选 listModels（其余面 run/read 走不到，测试只触碰注入链）。 */
+function fakeEngine(id: string, models: Array<{ id: string; name?: string }> | null): EnginePort {
+  return {
+    id,
+    capabilities: () => ({ conversation: "unsupported", steer: "unsupported", sandbox: "none" }),
+    probe: async () => ({ ok: true, engineVersion: "test" }),
+    run: async () => {
+      throw new Error("not used in this test");
+    },
+    interact: async () => {
+      throw new Error("not used in this test");
+    },
+    read: async () => ({ engineId: id, turns: [], source: "outcome-only" }),
+    ...(models !== null ? { listModels: () => models } : {}),
+  };
+}
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "model-prompt-"));
+  clearEngines();
+});
+
+afterEach(() => {
+  clearEngines();
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("buildEngineModelsPromptAppend（defaultEngine 开关语义）", () => {
+  it("defaultEngine 缺省 / 'pi' → 不注入（pi 段由核心提供）", () => {
+    registerEngine("zcode", () => fakeEngine("zcode", [{ id: "p/m1" }]));
+    expect(buildEngineModelsPromptAppend(undefined)).toBe("");
+    expect(buildEngineModelsPromptAppend("pi")).toBe("");
+    expect(buildEngineModelsPromptAppend("  ")).toBe("");
+  });
+
+  it("defaultEngine=zcode 且引擎实现 listModels → 注入段（含分界说明与模型 id）", () => {
+    registerEngine("zcode", () =>
+      fakeEngine("zcode", [
+        { id: "builtin:bigmodel-coding-plan/GLM-5.3", name: "Z.ai - Coding Plan · GLM-5.3" },
+        { id: "e512/mimo-v2.5-pro" },
+      ]),
+    );
+    const append = buildEngineModelsPromptAppend("zcode");
+    expect(append).toContain("<available_zcode_models>");
+    expect(append).toContain("</available_zcode_models>");
+    expect(append).toContain("<id>builtin:bigmodel-coding-plan/GLM-5.3</id>");
+    expect(append).toContain("<name>Z.ai - Coding Plan · GLM-5.3</name>");
+    expect(append).toContain("<id>e512/mimo-v2.5-pro</id>");
+    // 分界语义：pi 段的 id 不适用于本引擎
+    expect(append).toContain("do NOT apply to engine 'zcode'");
+  });
+
+  it("引擎未实现 listModels / 清单为空 / 未注册引擎 → 不注入（可发现性降级）", () => {
+    registerEngine("bare", () => fakeEngine("bare", null));
+    expect(buildEngineModelsPromptAppend("bare")).toBe("");
+    registerEngine("empty", () => fakeEngine("empty", []));
+    expect(buildEngineModelsPromptAppend("empty")).toBe("");
+    expect(buildEngineModelsPromptAppend("ghost")).toBe("");
+  });
+
+  it("listModels 抛异常 → fail-safe 不注入", () => {
+    const throwing: EnginePort = {
+      ...fakeEngine("boom", null),
+      listModels: () => {
+        throw new Error("v2 config broken");
+      },
+    };
+    registerEngine("boom", () => throwing);
+    expect(buildEngineModelsPromptAppend("boom")).toBe("");
+  });
+});

package/src/execution/engine/__tests__/paths.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  resolveEngineDir,
+  resolveEnginesRoot,
+  resolveJournalPath,
+  resolvePoolDir,
+  sanitizeSeg,
+} from '../paths.js';
+
+describe('engine paths SSOT', () => {
+  it('engines 根锚定 dataDir 顶层', () => {
+    expect(resolveEnginesRoot('/data')).toBe('/data/engines');
+  });
+
+  it('池目录 = engines/<engineId>/<poolKey>', () => {
+    expect(resolvePoolDir('/data', 'zcode', 'home-reviewer')).toBe('/data/engines/zcode/home-reviewer');
+    expect(resolveEngineDir('/data', 'zcode')).toBe('/data/engines/zcode');
+  });
+
+  it('journal 路径带 taskId 文件名', () => {
+    expect(resolveJournalPath('/data', 'zcode', 'pool1', 'sa-123')).toBe(
+      '/data/engines/zcode/pool1/journal-sa-123.jsonl',
+    );
+  });
+
+  it('路径段安全编码：穿越/分隔符/空白折叠为连字符', () => {
+    expect(sanitizeSeg('a/b\\c')).toBe('a-b-c');
+    expect(sanitizeSeg('..')).toBe('default');
+    expect(sanitizeSeg('  ')).toBe('default');
+    expect(sanitizeSeg('home-reviewer')).toBe('home-reviewer');
+    expect(sanitizeSeg('中文名')).toBe('default');
+    expect(sanitizeSeg('x'.repeat(200))).toHaveLength(80);
+  });
+
+  it('engineId 也走安全编码，防注入路径段', () => {
+    expect(resolvePoolDir('/data', '../../etc', 'p')).toBe('/data/engines/etc/p');
+  });
+});

package/src/execution/engine/__tests__/registry.test.ts

@@ -0,0 +1,120 @@
+// src/execution/engine/__tests__/registry.test.ts
+//
+// registry 专属测试（P1 验收 4）：注册/获取/listEngines/hasEngine/
+// 未注册 id 报 engine_not_found（错误文案含已注册清单——错误规格表第 1 行契约）。
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import type { EnginePort, RunContext } from "../port.ts";
+import {
+  clearEngines,
+  DEFAULT_ENGINE_ID,
+  EngineNotFoundError,
+  getEngine,
+  hasEngine,
+  listEngines,
+  registerEngine,
+} from "../registry.ts";
+import type { AgentTaskSpec, SessionView } from "../types.ts";
+
+/** 最小可运行假引擎（完整实现 EnginePort 五面——不 cast，防接口漂移失检）。 */
+function makeFakeEngine(id: string): EnginePort {
+  return {
+    id,
+    capabilities: () => ({
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "unsupported",
+      interrupt: "kill-only",
+      permissionMode: "fixed",
+    }),
+    probe: () =>
+      Promise.resolve({ ok: true, engineVersion: "0.0.0-test", checks: [{ name: "stub", ok: true }] }),
+    run: (_task: AgentTaskSpec, _ctx: RunContext) =>
+      Promise.reject(new Error("fake engine: run not implemented")),
+    interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
+    read: (_handle: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>
+      Promise.resolve({ engineId: id, turns: [], source: "outcome-only" }),
+  };
+}
+
+describe("engine registry", () => {
+  beforeEach(() => {
+    // 测试隔离：registry 是进程级全局状态，防用例间工厂/单例泄漏串扰
+    clearEngines();
+  });
+
+  it("registerEngine + getEngine：按 id 取回引擎实例", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    const engine = getEngine("fake");
+    expect(engine.id).toBe("fake");
+  });
+
+  it("getEngine 惰性单例：同一 id 重复获取返回同一实例（§3.3.1 registry 持 per-engine 单例）", () => {
+    let created = 0;
+    registerEngine("fake", () => {
+      created++;
+      return makeFakeEngine("fake");
+    });
+    const a = getEngine("fake");
+    const b = getEngine("fake");
+    expect(a).toBe(b);
+    expect(created).toBe(1);
+  });
+
+  it("registerEngine 覆盖同 id：丢弃旧单例，下次 getEngine 用新工厂重建（幂等重注册）", () => {
+    registerEngine("fake", () => makeFakeEngine("fake"));
+    const first = getEngine("fake");
+    registerEngine("fake", () => makeFakeEngine("fake-v2"));
+    const second = getEngine("fake");
+    expect(second).not.toBe(first);
+    expect(second.id).toBe("fake-v2");
+  });
+
+  it("listEngines 返回注册序清单，hasEngine 判注册态（不触发工厂副作用）", () => {
+    let created = 0;
+    registerEngine("alpha", () => {
+      created++;
+      return makeFakeEngine("alpha");
+    });
+    registerEngine("beta", () => makeFakeEngine("beta"));
+    expect(listEngines()).toEqual(["alpha", "beta"]);
+    expect(hasEngine("alpha")).toBe(true);
+    expect(hasEngine("gamma")).toBe(false);
+    // hasEngine 不取实例——工厂未执行
+    expect(created).toBe(0);
+  });
+
+  it("未注册 id → EngineNotFoundError（code=engine_not_found，文案含已注册清单）", () => {
+    registerEngine("pi", () => makeFakeEngine("pi"));
+    let caught: unknown;
+    try {
+      getEngine("zcode");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(EngineNotFoundError);
+    if (!(caught instanceof EngineNotFoundError)) throw new Error("unreachable");
+    expect(caught.code).toBe("engine_not_found");
+    expect(caught.engineId).toBe("zcode");
+    // 错误规格表第 1 行契约：指向注册表清单 + 配置文件路径
+    expect(caught.message).toContain("engine_not_found");
+    expect(caught.message).toContain("'zcode'");
+    expect(caught.message).toContain("pi");
+    expect(caught.message).toContain("frontmatter");
+  });
+
+  it("空注册表时未注册 id 错误不崩（清单为 none）", () => {
+    expect(() => getEngine("anything")).toThrow(EngineNotFoundError);
+    expect(() => getEngine("anything")).toThrow(/\(none\)/);
+  });
+
+  it("DEFAULT_ENGINE_ID 缺省为 'pi'（D9：回填期零风险默认）", () => {
+    expect(DEFAULT_ENGINE_ID).toBe("pi");
+  });
+});