@zhushanwen/pi-subagent-workflow 8.4.0 → 8.5.0

package/src/execution/types.ts

@@ -88,6 +88,15 @@ export type ExecutionMode = "background";
  *
  * 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
  * tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
+ *
+ * ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
+ * 详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
+ *   text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
+ *   tool_start / tool_end      ↔ ACP tool_call / tool_call_update
+ *   turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
+ *   compaction                 ↔ ACP session/compaction
+ * 本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
+ * 与跨引擎 trace 映射的翻译成本最低。
  */
 export type AgentEvent =
   | { type: "tool_start"; toolName: string; args?: unknown }
@@ -384,6 +393,23 @@ export interface ExecutionRecord {
    * 向后兼容：旧 record 无此字段，按默认值处理。
    */
   readonly idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。创建时确定不可变；缺省（存量 record）
+   * = pi 投影（消费方零迁移）。持久化经 subagent-record entry。
+   */
+  readonly engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源；
+   * 缺省 = 无 fallback。持久化经 subagent-record entry。
+   */
+  readonly engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U2：非 pi run resolve 后回填、终态迁移落 entry 前——run 前
+   * 缺省不可用）。sessionRef 整体透传（失败终态 sessionId 缺失时仍回填已有部分，
+   * 读侧①级降②级的防御形态）；journalPath 为 retarget 后实际落盘路径。pi 分支不
+   * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 
   // ── 状态（实时更新）──
   status: ExecutionStatus;
@@ -563,6 +589,16 @@ export interface ExecuteOptions {
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
    */
   idleTimeoutMs?: number;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）：pi 引擎由 PiEngine.run 在还原 opts 时写入；
+   * 缺省（历史调用方不设）= pi 投影。createRecordForMode 读入 record identity。
+   */
+  engine?: string;
+  /**
+   * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎时由路由层写入）。
+   * from = 请求引擎 id，reason 恒 'engine_probe_failed'（GUI 警告条数据源）。
+   */
+  engineFallback?: { from: string; reason: string };
   // 注：fork 深度不从外部传入（曾暴露 parentForkDepth，改用 ALS 后 execute 内部从调用链派生，
   // 公开字段成为死字段误导调用方，已移除）。深度限制检查见 session-runner.ts 内部 RunOptions.parentForkDepth
   // （与历史残留的 types.ts RunOptions 同名不同 interface——后者已删除）。
@@ -731,6 +767,19 @@ export interface SubagentRecord {
   externalInstance?: AliveMarker;
   /** fork 模式下的 worktree handle。 */
   worktreeHandle?: WorktreeHandle;
+  /**
+   * 实际执行引擎 id（P4 路由留痕）。缺省 = pi 投影（存量 record 零迁移）；
+   * GUI 警告条/引擎标记的数据源之一。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：EngineHandleData 的持久化消费面子集，引擎无关——
+   * sessionRef 整体透传不枚举内部键）。read 降级链①②级的数据源（runtime
+   * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
 // ============================================================
@@ -747,6 +796,13 @@ export interface SubagentRecord {
 export interface SubagentsGlobalConfig {
   version: number;
   maxConcurrent: number;
+  /**
+   * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
+   * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
+   */
+  defaultEngine?: string;
+  /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
+  engineRouting?: { strict: boolean };
 }
 
 // ============================================================

package/src/index.ts

@@ -16,7 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
@@ -24,6 +24,15 @@ import { bestEffort } from "./execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
 import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
 import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+// [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
+import { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
+// [U7] 引擎模型段注入（defaultEngine 非 pi 时 system prompt 补 <available_<engine>_models>）
+import { buildEngineModelsPromptAppend } from "./execution/engine/model-prompt.ts";
+// [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
+import { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
+// [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
+// common/data-dir SSOT，见 engines/zcode/registration.ts）
+import { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
 import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
@@ -160,6 +169,22 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // 的 getLogger("subagents") 也能走 appendEntry。
   setPiHandle(pi);
 
+  // [P1 引擎接线] 组合根登记缺省引擎：进程级 SubagentService 单例（session_start 注入）
+  // 经 registry 以 'pi' 暴露——引擎获取从此统一走 getEngine(DEFAULT_ENGINE_ID)，上层
+  // 不再硬编码「spawn pi」。幂等（registerEngine 覆盖语义），工厂惰性解析服务单例。
+  // P4 配置路由（agent frontmatter engine 字段 + 三层优先级）在本登记之上消费。
+  registerPiEngine();
+
+  // [P3 引擎接线] 登记 'zcode'（幂等同上）。惰性工厂：不触发 CLI/凭据探测，引擎被
+  // 实际选用（P4 路由或显式 getEngine('zcode')）才解析 deps。
+  registerZcodeEngine();
+
+  // [U7b] 引擎列表在 extension 模块加载时即同步 engines.json（不等 session_start——
+  // 用户体验拍板 2026-08-25：xyz-agent 打开后激活任意 session 的第一时间（含 TUI 等价
+  // 场景）GUI 引擎选择器就该有数据；session_start 处保留幂等重写兜底 jiti 双路径/
+  // 模块重载场景的刷新）。
+  syncEnginesFile(getAgentDir());
+
   // ════════════════════════════════════════════════════════════
   //  subagents 域：tool + command + messageRenderer
   // ════════════════════════════════════════════════════════════
@@ -332,6 +357,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
+    // [U7] 引擎列表同步 engines.json（幂等零写 + fail-safe；组合根注册已在
+    // extension 工厂体完成，此处 registry 已含全部引擎）
+    syncEnginesFile(agentDir);
+
     // skill 路径两级缓存 session 级失效：pi 同进程可能有多个 session（TUI /new、/fork），
     // 运行中安装的 skill 需对新 session 可见（含曾 miss 缓存的 undefined 条目与 npm 新装
     // 包的候选目录）。session 内复用收益不变（IF8/DM3 消重发生在同 session 的重复调用）。
@@ -559,6 +588,22 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     });
   });
 
+  // ════════════════════════════════════════════════════════════
+  //  [U7] before_agent_start：引擎模型段注入（defaultEngine 非 pi 且引擎实现
+  //  listModels 时追加 <available_<engine>_models>——每 turn 重判 config，改配置
+  //  后下一 turn 即生效；fail-safe 任何异常不注入不阻塞 agent loop）
+  // ════════════════════════════════════════════════════════════
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+    try {
+      const service = getModelConfigService();
+      const append = service === null ? "" : buildEngineModelsPromptAppend(service.getGlobalConfig().defaultEngine);
+      if (append === "" || typeof event.systemPrompt !== "string") return undefined;
+      return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
+    } catch {
+      return undefined;
+    }
+  });
+
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════

package/src/interface/subagent-actions.ts

@@ -81,6 +81,8 @@ export interface StartHandlerInput {
   conversation?: boolean;
   /** 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。 */
   idleTimeoutMs?: number;
+  /** 执行引擎（D4 三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
+  engine?: string;
 }
 
 /** start 领域对象（adapter 包成 bgResponse）。 */
@@ -219,6 +221,7 @@ export async function startHandler(
     cwd: input.cwd,
     conversation: input.conversation,
     idleTimeoutMs: input.idleTimeoutMs,
+    engine: input.engine,
     ctxModel,
     signal,
     // background detached 运行，完成由 notify 驱动新 turn。

package/src/interface/subagent-tool.ts

@@ -127,6 +127,12 @@ const SubagentParams = Type.Object({
       "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
       "Only meaningful with conversation:true; ignored for one-shot subagents.",
   })),
+  engine: Type.Optional(StringEnum(["pi", "zcode"], {
+    description:
+      "Execution engine for this subagent. Omit to inherit the global config. " +
+      "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
+      "Non-pi engines do not support conversation/fork/worktree (rejected before the subagent is created).",
+  })),
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
     includeFinished: Type.Optional(Type.Boolean({

package/src/orchestration/__tests__/__fixtures__/worker-template.snapshot.txt

@@ -12,7 +12,7 @@ const { parentPort: _parentPort, workerData: _workerData } = require("node:worke
 const _workerLogs = [];
 // IF6(#12): known agent() fields — hoisted to module scope, built once per worker
 // (was rebuilt inside agent() on every call; field set is call-invariant).
-const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);
+const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);
 function _pushWorkerLog(level, args) {
   try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }
 }
@@ -153,6 +153,8 @@ function _safePost(msg, context) {
         scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,
         phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,
         thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,
+        // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）
+        engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,
       };
     } else if (typeof firstArg === "object" && firstArg !== null) {
       if (firstArg.prompt) {
@@ -174,6 +176,7 @@ function _safePost(msg, context) {
           worktree: firstArg.worktree,
           returnMeta: firstArg.returnMeta,
           thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,
+          engine: firstArg.engine,
         };
       } else {
         opts = firstArg;
@@ -190,7 +193,7 @@ function _safePost(msg, context) {
     // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)
     const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));
     if (_unknownFields.length > 0) {
-      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);
+      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel, engine"]);
     }
 
     const callId = _callIdCounter;

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -100,11 +100,11 @@ describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", ()
     expect(agentBody).toContain("_KNOWN_FIELDS.has(k)");
   });
 
-  it("字段集合内容逐字段一致（16 known fields 不丢失）", () => {
+  it("字段集合内容逐字段一致（17 known fields 不丢失——P4 增 engine）", () => {
     expect(script).toContain(
-      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
     );
     // unknown-fields 警告文案不变（known 列表仍全量）
-    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel/);
+    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel.*engine/);
   });
 });

package/src/orchestration/models/types.ts

@@ -143,6 +143,13 @@ export interface AgentCallOpts {
   cwd?: string;
   /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
+  /**
+   * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+   * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+   * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+   * agent() → execute-agent-call → SAR 路由层。
+   */
+  engine?: string;
   /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
   worktree?: boolean;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.

package/src/orchestration/worker-script-builder.ts

@@ -66,7 +66,7 @@ const WORKER_TEMPLATE_PRE = [
     'const _workerLogs = [];',
     '// IF6(#12): known agent() fields — hoisted to module scope, built once per worker',
     '// (was rebuilt inside agent() on every call; field set is call-invariant).',
-    'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
+    'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
     'function _pushWorkerLog(level, args) {',
     '  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }',
     '}',
@@ -210,6 +210,8 @@ const WORKER_TEMPLATE_PRE = [
     '        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,\n' +
       '        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,',
       '        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,',
+      '        // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）',
+      '        engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,',
     '      };',
     '    } else if (typeof firstArg === "object" && firstArg !== null) {',
     '      if (firstArg.prompt) {',
@@ -231,6 +233,7 @@ const WORKER_TEMPLATE_PRE = [
     '          worktree: firstArg.worktree,',
     '          returnMeta: firstArg.returnMeta,',
     '          thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,',
+    '          engine: firstArg.engine,',
     '        };',
     '      } else {',
     '        opts = firstArg;',
@@ -247,7 +250,7 @@ const WORKER_TEMPLATE_PRE = [
     '    // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)',
     '    const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));',
     '    if (_unknownFields.length > 0) {',
-    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);',
+    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel, engine"]);',
     '    }',
     '',
     '    const callId = _callIdCounter;',

package/src/shared/meta-parser.ts

@@ -88,7 +88,9 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
 
   if (kind === "workflow") {
     // minor-2：agent 专属字段不可出现在 workflow（串类 reject）
-    if (o.examples !== undefined || o.tools !== undefined || o.model !== undefined) return null;
+    if (o.examples !== undefined || o.tools !== undefined || o.model !== undefined || o.engine !== undefined) {
+      return null;
+    }
     // phases 必填数组，元素为 string | {title:string, detail?:string}
     if (!Array.isArray(o.phases)) return null;
     const phases: WorkflowMeta["phases"] = [];
@@ -156,6 +158,7 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
     }
   }
   const model = isString(o.model) ? o.model : undefined;
+  const engine = isString(o.engine) ? o.engine : undefined;
 
   const meta: AgentMeta = {
     kind: "agent",
@@ -164,6 +167,7 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
     ...(examples !== undefined ? { examples } : {}),
     ...(tools !== undefined ? { tools } : {}),
     ...(model !== undefined ? { model } : {}),
+    ...(engine !== undefined ? { engine } : {}),
     ...(when !== undefined ? { when } : {}),
     ...(notFor !== undefined ? { notFor } : {}),
   };

package/src/shared/resource-meta.ts

@@ -54,6 +54,11 @@ export interface AgentMeta extends ResourceMetaBase {
   /** 供 AgentRegistry 执行侧 spawn 时注入，不进 system prompt 注入段。 */
   tools?: string[];
   model?: string;
+  /**
+   * 执行引擎 id（D9 per-agent 主通道：调用参数 engine > 本字段 > 全局默认）。
+   * 与 model 字段同风格——路由字段（不进 system prompt），执行侧（P4 路由层）消费。
+   */
+  engine?: string;
 }
 
 /** 判别联合（kind 判别）。 */