@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -1,79 +0,0 @@
-// 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

@@ -1,87 +0,0 @@
-// 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

@@ -1,36 +0,0 @@
-// 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

@@ -1,85 +0,0 @@
-// 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

@@ -1,39 +0,0 @@
-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

@@ -1,120 +0,0 @@
-// 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");
-  });
-});