@zhushanwen/pi-subagent-workflow 8.8.0 → 8.8.1

package/src/injectors/subagent-list-injector.ts

@@ -6,21 +6,17 @@
  * 名字而非臆造。注入格式对齐 pi 内置 skill 注入（XML 标签）。
  *
  * 改造点：
- * - P4：发现路径由自实现扫 4 目录改为同包 ADR-031 统一发现 discoverResources
- *   （P4 时点覆盖 7 源；C2 扩源后为统一发现全源 9 值 ResourceSource，含
- *   user-extension-paths/project-pi-tmp/project-host——序见 resource-discovery.ts
- *   模块头注 + 优先级合并）。discoverResources 只返回 DiscoveredResource（path/source/
- *   available），不含 name/description——保留 parseAgentFrontmatter 解析每个 .md 的
- *   frontmatter 提取 name+description。
+ * - D7-②（dual-track convergence）：同构骨架（缓存对/唯一写点/三 handler）收敛到
+ *   同目录 resource-list-injector.ts 工厂，本文件只保留 agent 侧真差异。
  * - P3：注入段引导语含正向触发引导（何时该 delegate）+ 名字约束（文案见
  *   SUBAGENT_LIST_GUIDE）。
  * - C5①（convergence D-3）：formatAgentList/sortByCodepoint 下沉 core，本文件改调
  *   core barrel（渲染骨架与条目模板逐字节同 pi 旧本地实现——CA2 快照验收前提）；
  *   guide 文案是 pi 宿主注入（core 不内嵌平台文案）。
  * - U11（sink 设计）：装配循环（发现→解析→去重→排序 + warn/error 口径）整体改
- *   消费 core discoverAgents（execution/agents-assembly，U2/A6）——壳侧收缩为
- *   「宿主注入根现取 + 委托」，语义等值口径见 agents-assembly.ts 头注（⛔1 探针
- *   对照注入 XML diff 为空验收）。
+ *   消费 core discoverAgents（execution/agents-assembly，U2/A6）——经工厂 assemble
+ *   覆写槽委托，壳侧收缩为「宿主注入根现取 + 委托」，语义等值口径见
+ *   agents-assembly.ts 头注（⛔1 探针对照注入 XML diff 为空验收）。
  *
  * 归位原因：injector 是 subagent-workflow 的内聚功能壳——事件接线与数据获取留
  * 在插件层（before_agent_start / modelRegistry），解析/渲染算法消费 core。
@@ -28,33 +24,15 @@
 
 
 
-import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	ExtensionAPI,
-	ExtensionContext,
-	SessionShutdownEvent,
-	SessionStartEvent,
-} from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { getHostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
-// U11（sink 设计）：agent 装配循环单源 core discoverAgents（U2/A6 装配函数，
-// 深路径消费）；渲染（formatAgentList）与 workspace 根推导（findWorkspaceRoot）
-// 走 barrel，parseResourceMeta 仍服务 parseAgentFrontmatter（严格注入投影语义锚）。
-// 上方 getHostServices 深路径刻意保留：core 服务定位器（core 内模块统一经它取用
-// 宿主端口），barrel 刻意不导出（D5 exports 面即 semver 契约、逐名列出，未列名
-// 的内部件不经 barrel——见 subagent-core src/index.ts 头注），壳侧深路径消费经包
-// `./*` -> src 通配豁免。
 import {
 	type AgentEntry,
-	findWorkspaceRoot,
+	discoverAgents,
 	formatAgentList,
+	getHostServices,
 	parseResourceMeta,
 } from "@zhushanwen/subagent-core";
-import { discoverAgents } from "@zhushanwen/subagent-core/execution/agents-assembly.ts";
 
-const logger = getLogger("injector");
+import { createResourceListInjector } from "./resource-list-injector.ts";
 
 /**
  * pi 版注入引导文案（C5① guide 参数化——core 渲染函数不内嵌平台文案，宿主注入）。
@@ -68,37 +46,15 @@ const logger = getLogger("injector");
 export const SUBAGENT_LIST_GUIDE =
 	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
 
-/**
- * Session 级 agent 列表缓存（per-process = per-session）。
- *
- * xyz-agent session-pool 模型下每 pi 子进程 = 一 session = 独立扩展实例，模块级缓存
- * 天然 per-session 隔离（split mode 多 session 各自独立进程）。session_start（含
- * reload）触发发现覆盖缓存（刷新节奏对齐 pi skill）；session_shutdown 清空；
- * before_agent_start 读缓存，miss（session_start 未触发/缓存被清）则 fallback
- * 重新发现——保证鲁棒。
- */
-let agentCache: AgentEntry[] | null = null;
-
-/**
- * 注入块渲染缓存（与 agentCache 同步更新）：before_agent_start 每个 turn 都要注入，
- * formatAgentList（escapeXml 多趟正则 × 全部字段）在数据不变时输出完全相同——渲染
- * 一次随缓存复用，turn 热路径零重复计算。
- */
-let agentInjectionCache: string | null = null;
-
-/** agentCache 唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
-function setAgentCache(entries: AgentEntry[] | null): void {
-	agentCache = entries;
-	agentInjectionCache =
-		entries !== null ? formatAgentList(entries, { guide: SUBAGENT_LIST_GUIDE }) : null;
-}
-
 /**
  * 解析 markdown 文件的 YAML frontmatter（name + description）。
  *
  * m2 收敛：删本地单行 key:value parser，改调 shared/meta-parser.ts parseResourceMeta
  * （IF1 统一 parser，支持 block scalar）。无有效 frontmatter 或缺 name/description 返 null。
  * 投影 {name, description} 注入用（examples 注入留 m5）。
+ *
+ * U11 后装配循环（含本函数的装配内消费）单源 core discoverAgents；保留导出作为
+ * 严格注入投影语义锚（parseResourceMeta 消费面）。
  */
 export function parseAgentFrontmatter(content: string): AgentEntry | null {
 	const meta = parseResourceMeta(content, "agent");
@@ -108,98 +64,29 @@ export function parseAgentFrontmatter(content: string): AgentEntry | null {
 		description: meta.description,
 		when: meta.when,
 		examples: meta.examples,
-		path: "", // 由 discoverAllAgents 从 DiscoveredResource.path 填充
+		path: "", // 装配时由 core discoverAgents 从 DiscoveredResource.path 填充
 	};
 }
 
 /**
- * 发现所有可用 agent（注入清单装配入口）。
- *
- * U11（sink 设计）：原手写装配循环（discoverResources 逐个 parseAgentFrontmatter
- * 解析 → agent name 去重（高优先级靠后 Map 后写胜）→ name 码点序排序 + warn/error
- * 口径）整体改消费 core `discoverAgents`（U2/A6 装配函数）——解析/去重/排序/warn
- * 口径单源 core，第三宿主免复刻（G3/S5）。等值口径（IF1 严格层可见性、warn 仅限
- * 「有 frontmatter 但解析失败」、KV-cache 码点序契约：注入段进每 turn system
- * prompt，顺序与 readdir 枚举序解耦，目录内容不变时任意重建渲染逐字节一致）登记见
- * core execution/agents-assembly.ts 头注。
- *
- * 壳侧保留职责：签名（workspaceRoot 单参）与宿主注入根现取（pi 壳 discoveryRoots
- * 每次现取 getAgentDir，实例隔离；agentDir 形参已删——其唯一用途就是喂 ScanConfig，
- * u0-data-discovery 偏差 #7）。
- *
- * 永不抛错——发现本身 fail-safe，单个文件读失败仅记日志。
- */
-export async function discoverAllAgents(
-	workspaceRoot: string,
-): Promise<AgentEntry[]> {
-	return discoverAgents(
-		workspaceRoot,
-		getHostServices().discoveryRoots?.()?.agents ?? [],
-	);
-}
-
-/**
- * 注册 session 生命周期 handler，注入 `<available_subagents>` 段。
- *
- * 三 handler 自管缓存生命周期（不耦合 index.ts session 逻辑）：
- * - session_start：发现+缓存赋值（fail-safe，异常不阻断，缓存保持 null）
- * - before_agent_start：读缓存渲染注入；miss 则 fallback 发现+赋值；空列表/空注入不返回
- *   systemPrompt；任何异常被吞掉（记日志），不阻断 agent turn
- * - session_shutdown：清缓存
- *
- * pi 支持 async handler，且同一 event 多 handler 链式（前者返回的 systemPrompt 作
- * 后者输入）。
+ * agent 清单实例：缓存生命周期 / 三 handler 经工厂骨架；装配循环经 assemble 覆写
+ * 委托 core discoverAgents（U11 单源，parse/onParseNull 不参与工厂装配——warn 口径
+ * 内聚 core：仅「有 frontmatter 但严格校验未通过」才 warn，README 等无 frontmatter
+ * 的 .md 静默跳过）。
  */
-export function setupSubagentListInjector(pi: ExtensionAPI): void {
-	pi.on(
-		"session_start",
-		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
-			try {
-				setAgentCache(
-					await discoverAllAgents(
-						findWorkspaceRoot(ctx.cwd),
-					),
-				);
-			} catch (err) {
-				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
-				logger.error("[subagent-list-injector] session_start discover failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
+const injector = createResourceListInjector<AgentEntry>({
+	kind: "agents",
+	logTag: "[subagent-list-injector]",
+	format: (agents) => formatAgentList(agents, { guide: SUBAGENT_LIST_GUIDE }),
+	assemble: (workspaceRoot) =>
+		discoverAgents(
+			workspaceRoot,
+			getHostServices().discoveryRoots?.()?.agents ?? [],
+		),
+});
 
-	pi.on(
-		"before_agent_start",
-		async (
-			event: BeforeAgentStartEvent,
-			ctx: ExtensionContext,
-		): Promise<BeforeAgentStartEventResult | void> => {
-			try {
-				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
-				if (agentCache === null) {
-					setAgentCache(
-						await discoverAllAgents(
-							findWorkspaceRoot(ctx.cwd),
-						),
-					);
-				}
-				// agentInjectionCache 与 agentCache 不变量同步（setAgentCache 保证），直接复用
-				const injection = agentInjectionCache;
-				if (!injection) return;
-				return { systemPrompt: event.systemPrompt + injection };
-			} catch (err) {
-				logger.error("[subagent-list-injector] before_agent_start failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
+/** 发现所有可用 agent（装配骨架见工厂；装配算法单源 core discoverAgents，U11）。 */
+export const discoverAllAgents = injector.discover;
 
-	pi.on(
-		"session_shutdown",
-		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-			setAgentCache(null);
-		},
-	);
-}
+/** 注册 session 生命周期 handler，注入 `<available_subagents>` 段（三 handler 语义见工厂）。 */
+export const setupSubagentListInjector = injector.setup;

package/src/injectors/workflow-list-injector.ts

@@ -8,69 +8,27 @@
  * 与 subagent 不对称。补全后模型可直接 `run` 已列出的 workflow，无需先 list。
  *
  * 实现要点：
- * - 发现走同包 ADR-031 统一发现 discoverResources({kind:"workflows", includeTmp:true})
- *   （includeTmp 覆盖 .pi/workflows/.tmp/，即 workflow-script generate 的产物）
- * - 解析每个 workflow 的 meta 提取 name+description（IF1 parseResourceMeta）
- * - description 截断为 prompt 友好的摘要（builtin 的 review-fix-loop 描述超长，全量
- *   注入每 turn 会膨胀 prompt）——summarizeDescription C5① 起改用 core barrel
- *   （算法逐字同本地旧实现）
- * - C5①（convergence D-3）：formatWorkflowList 下沉 core，本文件改调 core barrel
- *   （渲染骨架与条目模板逐字节同 pi 旧本地实现——CA2 快照验收前提）；guide 文案
- *   是 pi 宿主注入（core 不内嵌平台文案）
+ * - D7-②（dual-track convergence）：同构骨架（缓存对/唯一写点/三 handler）收敛到
+ *   同目录 resource-list-injector.ts 工厂，本文件只保留 workflow 侧真差异：
+ * - parseWorkflowMeta：.js @pi-meta 块 → WorkflowEntry（m2 收敛改调 shared/meta-parser
+ *   parseResourceMeta，仅认 @pi-meta 新格式；description 截断用 core summarizeDescription
+ *   ——builtin 的 review-fix-loop 描述超长，全量注入每 turn 会膨胀 prompt）
+ * - includeTmp：发现覆盖 .pi/workflows/.tmp/（workflow-script generate 的产物）
+ * - C5①（convergence D-3）：formatWorkflowList/summarizeDescription/sortByCodepoint
+ *   下沉 core，本文件经 barrel 消费（渲染骨架与条目模板逐字节同 pi 旧本地实现——
+ *   CA2 快照验收前提）；guide 文案是 pi 宿主注入（core 不内嵌平台文案）
  */
 
 
 
-import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	ExtensionAPI,
-	ExtensionContext,
-	SessionShutdownEvent,
-	SessionStartEvent,
-} from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { getHostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
-// C5①/C5⑦/C5b：发现与渲染统一走 core barrel——发现链辅助
-// （resource-discovery/meta-parser 面：findWorkspaceRoot/getCachedParsed/
-// parseResourceMeta）深路径 import 已归零。上方 getHostServices 深路径刻意
-// 保留：core 服务定位器（core 内模块统一经它取用宿主端口），barrel 刻意不
-// 导出（D5 exports 面即 semver 契约、逐名列出，未列名的内部件不经 barrel——
-// 见 subagent-core src/index.ts 头注），壳侧深路径消费经包 `./*` -> src 通配豁免。
 import {
-	discoverResources,
-	findWorkspaceRoot,
 	formatWorkflowList,
-	getCachedParsed,
 	parseResourceMeta,
 	summarizeDescription,
 	type WorkflowEntry,
 } from "@zhushanwen/subagent-core";
-// U11（sink 设计）：注入清单排序码点序单源——深路径消费 core sortByCodepoint
-// （与 barrel 版同一实现，深路径遵循任务指定消费形态；`./*` -> src 通配豁免）。
-import { sortByCodepoint } from "@zhushanwen/subagent-core/shared/injection-render.ts";
-
-const logger = getLogger("injector");
-
-/**
- * Session 级 workflow 列表缓存（per-process = per-session），与 agentCache 对称。
- * 见 subagent-list-injector.ts 的 agentCache 注释。
- */
-let workflowCache: WorkflowEntry[] | null = null;
 
-/**
- * 注入块渲染缓存（与 workflowCache 同步更新）：before_agent_start 每个 turn 都要注入，
- * formatWorkflowList 在数据不变时输出完全相同——渲染一次随缓存复用。
- */
-let workflowInjectionCache: string | null = null;
-
-/** workflowCache 唯一写点：数据与渲染缓存同步更新（null 清空两者）。 */
-function setWorkflowCache(entries: WorkflowEntry[] | null): void {
-	workflowCache = entries;
-	workflowInjectionCache =
-		entries !== null ? formatWorkflowList(entries, { guide: WORKFLOW_LIST_GUIDE }) : null;
-}
+import { createResourceListInjector } from "./resource-list-injector.ts";
 
 /**
  * pi 版注入引导文案（C5① guide 参数化——core 渲染函数不内嵌平台文案，宿主注入；
@@ -84,111 +42,26 @@ export const WORKFLOW_LIST_GUIDE =
 
 /**
  * 解析 workflow .js 文件的 meta（name + description），经 IF1 parseResourceMeta。
- *
- * m2 收敛：删 extractMetaBlock/extractMetaField（本地 brace-match parser），
- * 改调 shared/meta-parser.ts parseResourceMeta（统一 parser）。仅认 @pi-meta 新格式。
  * 投影到 WorkflowEntry {name, description(summarized)} 注入用。
  */
 export function parseWorkflowMeta(content: string): WorkflowEntry | null {
 	const meta = parseResourceMeta(content, "workflow");
 	if (!meta || meta.kind !== "workflow") return null;
-	// path 由 discoverAllWorkflows 从 DiscoveredResource.path 填充
+	// path 由工厂 discover 从 DiscoveredResource.path 填充
 	return { name: meta.name, description: summarizeDescription(meta.description), path: "" };
 }
 
-/**
- * 用统一资源发现发现所有可用 workflow（includeTmp 覆盖 generate 产物）。
- * 解析经 getCachedParsed mtime 级缓存；输出按 name 码点序排序（KV-cache 契约，
- * 见 subagent-list-injector.ts discoverAllAgents 注释）。
- * 永不抛错——单文件读失败仅记日志。
- */
-export async function discoverAllWorkflows(
-	workspaceRoot: string,
-): Promise<WorkflowEntry[]> {
-	const resources = await discoverResources({
-		kind: "workflows",
-		workspaceRoot,
-		// 宿主注入根现取（pi 壳 discoveryRoots 每次现取 getAgentDir，实例隔离）；
-		// agentDir 形参已删——其唯一用途就是喂 ScanConfig（u0-data-discovery 偏差 #7）
-		hostRoots: getHostServices().discoveryRoots?.()?.workflows ?? [],
-		includeTmp: true,
-	});
+/** workflow 清单实例：缓存生命周期 / 发现 / 三 handler 全部经工厂骨架。 */
+const injector = createResourceListInjector<WorkflowEntry>({
+	kind: "workflows",
+	logTag: "[workflow-list-injector]",
+	parse: parseWorkflowMeta,
+	format: (workflows) => formatWorkflowList(workflows, { guide: WORKFLOW_LIST_GUIDE }),
+	includeTmp: true,
+});
 
-	const map = new Map<string, WorkflowEntry>();
-	for (const resource of resources) {
-		if (!resource.available) continue;
-		try {
-			const wf = getCachedParsed(resource.path, parseWorkflowMeta);
-			if (wf) map.set(wf.name, { ...wf, path: resource.path });
-		} catch (err) {
-			logger.error(
-				`[workflow-list-injector] skip unreadable workflow file ${resource.path}`,
-				{ reason: err instanceof Error ? err.message : String(err) },
-			);
-		}
-	}
-	// U11：内联码点序 sort 折叠为 core sortByCodepoint（实现逐字等价——同比较器
-	// 语义：ka < kb ? -1 : ka > kb ? 1 : 0，非变异副本排序）
-	return sortByCodepoint([...map.values()], (a) => a.name);
-}
+/** 用统一资源发现发现所有可用 workflow（includeTmp 覆盖 generate 产物；骨架与排序契约见工厂）。 */
+export const discoverAllWorkflows = injector.discover;
 
-/**
- * 注册 session 生命周期 handler，注入 `<available_workflows>` 段。
- *
- * 与 setupSubagentListInjector 对称：session_start 发现+缓存，before_agent_start
- * 读缓存（miss fallback）渲染注入，session_shutdown 清缓存。与 subagent 注入
- * handler 链式（pi 串联多 handler 的 systemPrompt 返回值）。
- */
-export function setupWorkflowListInjector(pi: ExtensionAPI): void {
-	pi.on(
-		"session_start",
-		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
-			try {
-				setWorkflowCache(
-					await discoverAllWorkflows(
-						findWorkspaceRoot(ctx.cwd),
-					),
-				);
-			} catch (err) {
-				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
-				logger.error("[workflow-list-injector] session_start discover failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
-
-	pi.on(
-		"before_agent_start",
-		async (
-			event: BeforeAgentStartEvent,
-			ctx: ExtensionContext,
-		): Promise<BeforeAgentStartEventResult | void> => {
-			try {
-				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
-				if (workflowCache === null) {
-					setWorkflowCache(
-						await discoverAllWorkflows(
-							findWorkspaceRoot(ctx.cwd),
-						),
-					);
-				}
-				// workflowInjectionCache 与 workflowCache 不变量同步（setWorkflowCache 保证），直接复用
-				const injection = workflowInjectionCache;
-				if (!injection) return;
-				return { systemPrompt: event.systemPrompt + injection };
-			} catch (err) {
-				logger.error("[workflow-list-injector] before_agent_start failed", {
-					reason: err instanceof Error ? err.message : String(err),
-				});
-			}
-		},
-	);
-
-	pi.on(
-		"session_shutdown",
-		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
-			setWorkflowCache(null);
-		},
-	);
-}
+/** 注册 session 生命周期 handler，注入 `<available_workflows>` 段（与 subagent 注入 handler 链式）。 */
+export const setupWorkflowListInjector = injector.setup;

package/src/interface/__tests__/detectors.test.ts

@@ -24,7 +24,7 @@ import {
   findFlattenedArgKeys,
 } from "@zhushanwen/subagent-core/orchestration/args-meta.ts";
 import { TOOL_TOP_LEVEL } from "../tool-workflow";
-import { parseResourceMeta } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
+import { parseResourceMeta } from "@zhushanwen/subagent-core";
 
 // 宿主 reservedKeys 注入（与 tool-workflow ARGS_META_OPTIONS 等值契约）
 const OPT = { reservedKeys: TOOL_TOP_LEVEL };

package/src/interface/__tests__/subagent-tool-path-guard.test.ts

@@ -12,39 +12,49 @@
 //   2. skillPath / cwd 相对路径 → 同步 reject
 //   3. 合法绝对路径放行 → 参数原样透传 service.execute（守卫零误伤对照）
 //
-// harness 复用 sdk-contract.test.ts 的 mock 链（pi-ai/typebox/subagent-service），
-// registerSubagentTool 后捕获 execute 回调直接调用。
+// harness（[u-5b / A-V3] 改写）：registerSubagentTool 后捕获 execute 回调直接调用。
+// SubagentService 经单例访问器槽注入 fake（setSubagentService，globalThis 槽——
+// executeSubagent 内 getSubagentService() 读同一槽，「守卫拒绝时 service.execute
+// 零触达」的承重断言不依赖整类 mock）；pi-ai/typebox 桩改共享桩
+// （src/__tests__/mocks/runtime-stubs.ts，async 工厂 + 动态 import，消费约定见
+// 桩 module 头注）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 共享桩（./mocks/runtime-stubs.ts 相对本文件 = ../../__tests__/mocks/runtime-stubs.ts）：
+// vi.mock 工厂提升到文件顶部，体内不能引用普通顶层变量，一律经 async 工厂 +
+// 动态 import 取桩。
+vi.mock("@earendil-works/pi-ai", async () => {
+  const { piAiStringEnumStub } = await import("../../__tests__/mocks/runtime-stubs.ts");
+  return piAiStringEnumStub();
+});
+vi.mock("typebox", async () => {
+  const { typeboxStub } = await import("../../__tests__/mocks/runtime-stubs.ts");
+  return typeboxStub;
+});
 
-import { describe, expect, it, vi, beforeEach } from "vitest";
+import { setSubagentService } from "@zhushanwen/subagent-core";
 
-vi.mock("@earendil-works/pi-ai", () => ({
-  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
-}));
-vi.mock("typebox", () => ({
-  Type: {
-    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
-    Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),
-    String: (opts?: Record<string, unknown>) => ({ type: "string", ...opts }),
-    Boolean: () => ({ type: "boolean" }),
-    Number: (opts?: Record<string, unknown>) => ({ type: "number", ...opts }),
-    Array: (items: unknown) => ({ type: "array", items }),
-    Record: (key: unknown, value: unknown) => ({ type: "object", additionalProperties: value, key }),
-    Unknown: () => ({ type: "unknown" }),
-    Union: (members: unknown[]) => ({ type: "union", members }),
-    Literal: (value: unknown) => ({ type: "literal", value }),
-  },
-}));
+import { registerSubagentTool } from "../../interface/subagent-tool.ts";
+import { mockExtensionApi } from "@zhushanwen/subagent-core/testing/execution/__tests__/helpers/mock-extension-api.ts";
+
+// ── 访问器槽注入 helpers ─────────────────────────────────────
 
-// Mock getSubagentService：断言「守卫拒绝时 service.execute 零触达」的承重证据。
+/** fake service：execute 断言面（守卫拒绝 → 零触达）。 */
 const { mockServiceExecute } = vi.hoisted(() => ({
   mockServiceExecute: vi.fn(),
 }));
-vi.mock("@zhushanwen/subagent-core/execution/subagent-service.ts", () => ({
-  getSubagentService: () => ({ execute: mockServiceExecute }),
-}));
 
-import { registerSubagentTool } from "../../interface/subagent-tool.ts";
-import { mockExtensionApi } from "@zhushanwen/subagent-core/execution/__tests__/helpers/mock-extension-api.ts";
+/** 重置进程级 SubagentService 单例槽（setSubagentService 不接受 null，测试清理用
+ *  Symbol 直写；key 与生产 getServiceSlot 的 SERVICE_SLOT_KEY 一致）。 */
+function resetServiceSlot(): void {
+  const slot = Reflect.get(globalThis, Symbol.for("@zhushanwen/pi-subagents.service")) as
+    | { current: unknown }
+    | undefined;
+  if (slot) slot.current = null;
+}
+
+// ── harness ──────────────────────────────────────────────────
 
 type ExecuteCb = (...args: unknown[]) => Promise<unknown>;
 
@@ -82,9 +92,15 @@ describe("subagent tool 路径守卫（skillPath/cwd：绝对路径 + 禁 .. 穿
   beforeEach(() => {
     vi.clearAllMocks();
     mockServiceExecute.mockResolvedValue(stubHandle());
+    // 经真实单例访问器注入 fake service（executeSubagent 内 getSubagentService 读同槽）
+    setSubagentService({ execute: mockServiceExecute } as never);
     execute = captureExecute();
   });
 
+  afterEach(() => {
+    resetServiceSlot();
+  });
+
   // ── `..` 穿越段拒绝 ──
 
   it("skillPath 含 .. 穿越段 → immediate reject，service.execute 零触达", async () => {

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -156,9 +156,17 @@ describe("subagent tool runtime handler — 错误文案含纠正正例", () =>
   // 平铺检测 guard（hasFlattenedStartFields）已删除，源码不应再含此表达式。
   it("startHandler throw 含 Correct 纠正正例（平铺形态）", () => {
     // [D6②] startHandler 内核（含 Correct 文案）已下沉 core subagent-actions-core，
-    // 断言目标跟随文案权威源（resolve 方式同 prompt-quality-batch1 U4 先例）。
+    // 断言目标跟随文案权威源。锚点用 ./workflows/* 子入口（exports 映射包根真实目录，
+    // 随源码走不依赖 dist 构建——relay-env 锚在 require 条件下落 dist/，CI 不构建
+    // workspace 包时 resolve 直接 MODULE_NOT_FOUND）。
+    const coreRoot = join(
+      dirname(
+        createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/workflows/README.md"),
+      ),
+      "..",
+    );
     const actionsSrc = readFileSync(
-      createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/execution/subagent-actions-core.ts"),
+      join(coreRoot, "src/execution/subagent-actions-core.ts"),
       "utf-8",
     );
     // 四处 throw（input 缺失 / task 空白 / slug 空白 / slug 超长）都应含 Correct 正例。

package/src/interface/__tests__/tool-workflow-throw-paths.test.ts

@@ -15,7 +15,7 @@
  */
 import { describe, expect, it, vi } from "vitest";
 
-import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
+import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core";
 import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
 import { registerWorkflowTool } from "../tool-workflow.ts";
 

package/src/interface/bg-notify-render.ts

@@ -22,10 +22,10 @@
 import type { Component } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
-import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
-import { deriveOutcome } from "@zhushanwen/subagent-core/execution/execution-record.ts";
-import { CLOSED_REASONS } from "@zhushanwen/subagent-core/execution/types.ts";
-import type { ClosedReason, ExecutionOutcome } from "@zhushanwen/subagent-core/execution/types.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core";
+import { deriveOutcome } from "@zhushanwen/subagent-core";
+import { CLOSED_REASONS } from "@zhushanwen/subagent-core";
+import type { ClosedReason, ExecutionOutcome } from "@zhushanwen/subagent-core";
 import {
   firstLineSanitized,
   padToVisible,