@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/shared/injection-render.ts

@@ -0,0 +1,279 @@
+// src/shared/injection-render.ts
+//
+// 三段 XML 注入渲染（<available_subagents> / <available_workflows> /
+// <available_provider_models>）——从 pi-sw 插件层下沉的平台无关纯函数
+// （convergence D-3）。渲染骨架 escapeXml/renderXmlSection 见同目录
+// xml-injection.ts。pi 侧原函数曾内嵌于三 injector（基线 5557e109b，C5 起改调
+// 本模块，逐字节等价证据见
+// docs/design/subagent-core-convergence.probe-a2-baseline.md）。
+//
+// 与 pi-sw 原实现的差异（本模块定约）：
+// - guide 文案必填注入：core 不内嵌任何平台文案，宿主（pi-sw / zsw）各自传入；
+// - ModelEntry 并集口径：除 id/name 外全字段 optional（红线 5）——undefined
+//   消费点显式守卫（input 缺席不抛、contextWindow 缺席不渲染该元素、
+//   provider 缺席/空串时 id 裸渲染），不是自然降级；
+// - 分段条目预算：subagents/workflows 可传 maxEntries，超限按排序键码点序
+//   截尾 + 追加宿主注入的兜底指引行（红线 7：内置条目无截断豁免，不做
+//   「内置优先保留」两段式）；models 段无预算参数，完整渲染永不截（设计钉死）；
+// - format 内部先排后截：pi 调用链数据已排时重排幂等，不破坏「pi 现调用
+//   形态下输出逐字节等价」（CA2 快照验收前提）。
+//
+// 设计权威源：docs/design/subagent-core-convergence.md §3.2 D-3 / §3.3 红线 5、7。
+
+import { escapeXml, renderXmlSection } from "./xml-injection.ts";
+
+/** 从 agent .md frontmatter 提取的最小 agent 信息（随 D-3 从 pi-sw 下沉） */
+export interface AgentEntry {
+	name: string;
+	description: string;
+	when?: string;
+	examples?: Array<{ match: string; action: string; positive: boolean }>;
+	/** agentRef：agent .md 文件的绝对路径（注入段 <location>，模型直接引用） */
+	path: string;
+}
+
+/** 解析后的 workflow 条目（name + 摘要后的 description + 脚本路径） */
+export interface WorkflowEntry {
+	name: string;
+	description: string;
+	/** workflowRef：脚本 .js 文件的绝对路径（注入段 <location>，模型直接引用） */
+	path: string;
+}
+
+/** reasoning 对象形态（zsw 投影的档位结构）；渲染面仅按 truthy 消费，字段值不进输出 */
+export interface ModelReasoningInfo {
+	variants?: unknown[];
+	defaultVariant?: unknown;
+}
+
+/**
+ * 注入段的最小模型投影——pi 与 zsw 两侧数据形态的并集（D-3 + 本仓 provider 补充）：
+ * id/name 为条目最小必填（缺则无渲染意义），其余字段 optional（红线 5）。
+ * - pi 投影：provider/reasoning:boolean/input[]/contextWindow 全给；
+ * - zsw 投影：reasoning:{variants} 档位对象、input 缺席；
+ * - label 与 reasoning.variants 进类型并集但渲染面暂不消费（宿主按需再扩）。
+ */
+export interface ModelEntry {
+	id: string;
+	name: string;
+	provider?: string;
+	label?: string;
+	contextWindow?: number;
+	reasoning?: boolean | ModelReasoningInfo;
+	input?: string[];
+}
+
+/** 条目段（subagents/workflows）渲染选项：guide 宿主注入 + 可选条目预算 */
+export interface ListFormatOptions {
+	/** 注入段引导文案——必填，core 不内嵌平台文案（D-3 guide 参数化） */
+	guide: string;
+	/**
+	 * 条目预算上限：超限按排序键码点序截尾（保留靠前条目）。缺省不限制
+	 * （pi 现行为全量）。models 段无此参数（永不截，设计钉死）。
+	 */
+	maxEntries?: number;
+	/** 截断发生时在段末追加的兜底指引行（宿主注入，如查看全量的命令）；未提供则不追加 */
+	truncationNotice?: string;
+}
+
+/** models 段渲染选项：仅 guide——无条目预算（完整渲染永不截，D-3 钉死） */
+export interface ModelListFormatOptions {
+	guide: string;
+}
+
+/**
+ * 码点序排序（显式契约，禁 localeCompare——宿主 locale 差异会破坏跨环境
+ * 字节一致；注入段进每 turn system prompt，顺序必须与枚举序解耦）。
+ * 非变异：返回排序副本，入参数组不动（core 纯函数定位；截尾语义依赖此序）。
+ */
+export function sortByCodepoint<T>(
+  items: readonly T[],
+  key: (item: T) => string,
+): T[] {
+  return [...items].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+
+/** 注入段中单个 workflow 的最大描述长度（控制每 turn prompt 体积） */
+const MAX_DESC_LEN = 160;
+
+/** 断句阈值比例：句末标点位置须 >= maxLen 的 40% 才采用，否则硬截断保留更多信息 */
+const DESC_BOUNDARY_MIN_RATIO = 0.4;
+
+/**
+ * 将 workflow description 截断为 prompt 友好的摘要。
+ * 优先在 limit 内的最后一个句末标点处断句；无合适断点则硬截断 + 省略号。
+ */
+export function summarizeDescription(
+  desc: string,
+  maxLen = MAX_DESC_LEN,
+): string {
+  const trimmed = desc.trim();
+  if (trimmed.length <= maxLen) return trimmed;
+  const slice = trimmed.slice(0, maxLen);
+  const boundary = Math.max(
+    slice.lastIndexOf("。"),
+    slice.lastIndexOf("；"),
+    slice.lastIndexOf(";"),
+    slice.lastIndexOf(". "),
+  );
+  // 断点过靠前（< 阈值比例）时不采用，改硬截断保留更多信息
+  if (boundary > maxLen * DESC_BOUNDARY_MIN_RATIO) return slice.slice(0, boundary + 1);
+  return `${slice}…`;
+}
+
+/**
+ * 排序后应用条目预算：超限截尾（保留码点序靠前条目）。返回保留条目与是否截断。
+ * 红线 7：内置条目无截断豁免——不做「内置优先保留」两段式。
+ */
+function applyEntryBudget<T>(
+  sorted: T[],
+  maxEntries: number | undefined,
+): { kept: T[]; truncated: boolean } {
+  if (maxEntries === undefined || sorted.length <= maxEntries) {
+    return { kept: sorted, truncated: false };
+  }
+  return { kept: sorted.slice(0, maxEntries), truncated: true };
+}
+
+/**
+ * 将 agent 列表格式化为 XML 注入段。
+ *
+ * 内部先按 name 码点序排序再渲染截断（超预算截尾语义依赖码点序；pi 调用链
+ * 数据已排时重排幂等，不破坏与 pi 现输出的逐字节等价）。空列表返回空串
+ * （不注入）；预算截断发生时在段末追加宿主注入的兜底指引行（缺省不追加）。
+ */
+export function formatAgentList(
+  agents: AgentEntry[],
+  opts: ListFormatOptions,
+): string {
+  if (agents.length === 0) return "";
+
+  const sorted = sortByCodepoint(agents, (a) => a.name);
+  const { kept, truncated } = applyEntryBudget(sorted, opts.maxEntries);
+
+  const items = kept.map((agent) => {
+    let block = `  <agent><name>${escapeXml(agent.name)}</name><description>${escapeXml(agent.description)}</description>`;
+    // 路由样本（when + examples 正反原样渲染——negative 的 action 由作者写
+    // 「不调用（原因）」，渲染器不硬编码；全部内容 escapeXml 防 XML 注入段破坏）
+    if (agent.when) {
+      block += `<when>${escapeXml(agent.when)}</when>`;
+    }
+    if (agent.examples && agent.examples.length > 0) {
+      const exampleLines = agent.examples.map(
+        (e) => `      - "${escapeXml(e.match)}" → ${escapeXml(e.action)}`,
+      );
+      block += `\n    <examples>\n${exampleLines.join("\n")}\n    </examples>`;
+    }
+    block += `<location>${escapeXml(agent.path)}</location></agent>`;
+    return block;
+  });
+  if (truncated && opts.truncationNotice !== undefined) {
+    items.push(opts.truncationNotice);
+  }
+  return renderXmlSection({
+    tag: "available_subagents",
+    guide: opts.guide,
+    items,
+  });
+}
+
+/**
+ * 将 workflow 列表格式化为 XML 注入段。
+ *
+ * 与 formatAgentList 同约：先按 name 码点序排序再渲染截尾；空列表返回空串
+ * （不注入）；截断时追加宿主注入的兜底指引行（缺省不追加）。
+ */
+export function formatWorkflowList(
+  workflows: WorkflowEntry[],
+  opts: ListFormatOptions,
+): string {
+  if (workflows.length === 0) return "";
+
+  const sorted = sortByCodepoint(workflows, (w) => w.name);
+  const { kept, truncated } = applyEntryBudget(sorted, opts.maxEntries);
+
+  const items = kept.map((wf) =>
+    `  <workflow><name>${escapeXml(wf.name)}</name><description>${escapeXml(wf.description)}</description><location>${escapeXml(wf.path)}</location></workflow>`,
+  );
+  if (truncated && opts.truncationNotice !== undefined) {
+    items.push(opts.truncationNotice);
+  }
+  return renderXmlSection({
+    tag: "available_workflows",
+    guide: opts.guide,
+    items,
+  });
+}
+
+/** 码点序比较（显式契约，禁 localeCompare——同 sortByCodepoint 注释） */
+function compareByCodepoint(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * models 段排序：provider 归一为非空串参与比较（缺席/空串 → ""）——
+ * pi 投影（provider 全给且非空）下与 pi 现实现 (provider, id) 两段码点序一致；
+ * zsw 投影（provider 缺席）整体退化为 id 码点序；混合形态下无 provider 条目
+ * 排最前（空串码点最小），口径确定可复现。
+ */
+function compareModelEntries(a: ModelEntry, b: ModelEntry): number {
+  const pa = a.provider ?? "";
+  const pb = b.provider ?? "";
+  return pa === pb
+    ? compareByCodepoint(a.id, b.id)
+    : compareByCodepoint(pa, pb);
+}
+
+/**
+ * 能力标记：reasoning truthy（布尔 true 或对象形态——zsw 的 {variants} 投影）
+ * → "reasoning"；input 含 image → "vision"。空则省略 caps 段。
+ * 红线 5 守卫：input 缺席经 optional chaining 不抛（pi 版此处对 undefined 抛
+ * TypeError，本仓 L73 已核实）。
+ */
+function formatCaps(entry: ModelEntry): string {
+  const caps: string[] = [];
+  if (entry.reasoning) caps.push("reasoning");
+  if (entry.input?.includes("image") ?? false) caps.push("vision");
+  return caps.join(",");
+}
+
+/**
+ * 将模型列表格式化为 XML 注入段。
+ *
+ * 输入按归一 (provider, id) 码点序排序（见 compareModelEntries）——同一数据集
+ * 输出字节稳定（KV-cache 契约）。空列表返回空串（不注入）。
+ * models 段无条目预算（完整渲染永不截，D-3 钉死）。
+ * 红线 5 守卫：contextWindow 缺席不渲染该元素（不输出 "undefined" 垃圾）；
+ * provider 缺席/空串时 id 裸渲染。
+ */
+export function formatModelList(
+  models: ModelEntry[],
+  opts: ModelListFormatOptions,
+): string {
+  if (models.length === 0) return "";
+
+  const sorted = [...models].sort(compareModelEntries);
+
+  const items = sorted.map((m) => {
+    const caps = formatCaps(m);
+    const idText = m.provider ? `${m.provider}/${m.id}` : m.id;
+    return (
+      `  <model><id>${escapeXml(idText)}</id>`
+				+ `<name>${escapeXml(m.name)}</name>`
+				+ (caps ? `<caps>${caps}</caps>` : "")
+				+ (m.contextWindow !== undefined
+				  ? `<contextWindow>${m.contextWindow}</contextWindow>`
+				  : "")
+				+ `</model>`
+    );
+  });
+  return renderXmlSection({
+    tag: "available_provider_models",
+    guide: opts.guide,
+    items,
+  });
+}

package/src/shared/meta-parser.ts

@@ -88,7 +88,11 @@ 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 || o.engine !== undefined) {
+    if (
+      o.examples !== undefined || o.tools !== undefined || o.model !== undefined
+      || o.engine !== undefined || o.maxTurns !== undefined
+      || o.disallowedTools !== undefined || o.skills !== undefined
+    ) {
       return null;
     }
     // phases 必填数组，元素为 string | {title:string, detail?:string}
@@ -159,6 +163,18 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
   }
   const model = isString(o.model) ? o.model : undefined;
   const engine = isString(o.engine) ? o.engine : undefined;
+  // D3 可选执行字段（maxTurns/disallowedTools/skills）：与 tools 同风格投影
+  // （空数组 [] 同 tools 保留键——列表字段族空列表语义一致）。严格层对非法类型
+  // reject（minor-2..5 既有精神：不静默丢弃非法字段）——宽容降级是
+  // parseAgentProfile（agent-registry）的职责，不在本严格层。
+  if (o.maxTurns !== undefined && (typeof o.maxTurns !== "number" || !Number.isFinite(o.maxTurns))) {
+    return null;
+  }
+  const maxTurns = typeof o.maxTurns === "number" ? o.maxTurns : undefined;
+  const disallowedTools = parseStringListField(o.disallowedTools);
+  if (disallowedTools === null) return null;
+  const skills = parseStringListField(o.skills);
+  if (skills === null) return null;
 
   const meta: AgentMeta = {
     kind: "agent",
@@ -168,12 +184,36 @@ function typecheckMeta(raw: unknown, kind: ResourceKind): ResourceMeta | null {
     ...(tools !== undefined ? { tools } : {}),
     ...(model !== undefined ? { model } : {}),
     ...(engine !== undefined ? { engine } : {}),
+    ...(maxTurns !== undefined ? { maxTurns } : {}),
+    ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+    ...(skills !== undefined ? { skills } : {}),
     ...(when !== undefined ? { when } : {}),
     ...(notFor !== undefined ? { notFor } : {}),
   };
   return meta;
 }
 
+/**
+ * 字符串列表字段解析（tools 先例的泛化）：数组形态逐元素校验 string，空数组保留
+ * 为 []（键进 meta——与 tools 数组形态 `tools: []` 语义一致，列表字段族同语义）；
+ * 逗号分隔字符串按 `tools: read, bash` 约定拆分 trim，全空串（`skills: ,`）视同
+ * 缺席；字段缺席 → undefined（不进 meta）；非法形态（数字/对象/数组含非字符串）
+ * → null（调用方 reject——minor-2..5 既有精神：非法字段显式拒绝，不静默丢弃）。
+ * 三态返回是为区分「缺席」与「非法」。
+ */
+function parseStringListField(raw: unknown): string[] | null | undefined {
+  if (raw === undefined) return undefined;
+  if (Array.isArray(raw)) {
+    if (!raw.every(isString)) return null;
+    return raw as string[];
+  }
+  if (isString(raw)) {
+    const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+  }
+  return null;
+}
+
 // ── IF1: parseResourceMeta（discovery，fail-safe null）─────────────────
 
 /**

package/src/shared/resource-discovery.ts

@@ -10,10 +10,10 @@
 // 4. manifest 路径存在性校验：声明的路径不存在 → 该包发现失败，不 fallback
 // 5. 废弃 discovery.json：扫描路径完全由代码内推导，无外部依赖
 //
-// 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev → project .pi → project .pi/.tmp(仅workflow) → project .agents
+// 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev → ext-paths(XYZ_EXTENSION_PATHS/dev-link) → project .pi → project .pi/.tmp(仅workflow) → project-host(宿主注入槽) → project .agents
 
 import * as fsSync from "node:fs";
-import { access, readdir, readFile, stat } from "node:fs/promises";
+import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 
@@ -56,7 +56,19 @@ export interface DiscoveredResource {
 }
 
 /** 资源来源层级 */
-export type ResourceSource = "user-pi" | "user-agents" | "npm" | "npm-dev" | "user-extension-paths" | "project-pi" | "project-pi-tmp" | "project-agents";
+export type ResourceSource =
+  | "user-pi"
+  | "user-agents"
+  | "npm"
+  | "npm-dev"
+  | "user-extension-paths"
+  | "project-pi"
+  | "project-pi-tmp"
+  // project-host（W2②）：宿主注入的项目级根（如 zsw 的 <ws>/.zcode/agents）。
+  // 序位刻意压在 project-agents 之下——zsw 现语义项目 .agents > .zcode，
+  // project-host 承接 zcode 项目根，project-agents 仍是项目级最高逃生门。
+  | "project-host"
+  | "project-agents";
 
 /** 扫描配置 */
 export interface ScanConfig {
@@ -65,8 +77,14 @@ export interface ScanConfig {
   /** 项目根目录（findWorkspaceRoot 推导结果） */
   workspaceRoot: string;
   /** 宿主注入的发现根（DiscoveryRoot.dir 已含 kind 末级目录与安装布局，
-   *  source 为宿主语义标签——pi 壳 = user-pi/npm/npm-dev 三根）。buildScanTargets
-   *  按标签查表填充对应槽位，宿主未提供某标签根时该槽位条目整体缺席。 */
+   *  source 为宿主语义标签——pi 壳 = user-pi/npm/npm-dev 三根，zsw 壳可另注入
+   *  project-host 等）。buildScanTargets 按标签填充对应槽位，宿主未提供某标签
+   *  根时该槽位条目整体缺席。
+   *  同标签多根语义（W2④）：同标签多条目依注入序全部保留、同序位依次扫描——
+   *  宿主（zsw）把「目录 symlink 展开目标 + 本体根」按注入序注入同标签，core
+   *  合并 last-writer-wins 下靠后者胜，本体根必须注入在展开目标之后（本体胜，
+   *  红线 2）。user-agents/project-agents 硬编码槽与同标签注入合并时硬编码根
+   *  自动后置（同为「本体在后」语义）。 */
   hostRoots: DiscoveryRoot[];
   /** 是否包含 tmp 源（仅 workflow 用 .pi/workflows/.tmp/） */
   includeTmp?: boolean;
@@ -82,11 +100,12 @@ const MACHINE_SOURCES: ReadonlySet<ResourceSource> = new Set<ResourceSource>([
   "user-extension-paths",
   "project-pi",
   "project-pi-tmp",
+  "project-host",
   "project-agents",
 ]);
 
 /** 判断 source 是否属于机器源（安装拓扑常态，同名重复降 debug）。
- *  导出仅为测试穷举断言用（封闭 8 值枚举 × 分级边界）。 */
+ *  导出仅为测试穷举断言用（封闭 9 值枚举 × 分级边界）。 */
 export function isMachineSource(source: ResourceSource): boolean {
   return MACHINE_SOURCES.has(source);
 }
@@ -518,38 +537,44 @@ function readExtensionPaths(): string[] {
  * 构建所有扫描源（按优先级低→高排列）。
  *
  * agent 和 workflow 共享相同的前缀体系。宿主注入根（config.hostRoots）按 source
- * 标签查表填充三个槽位条目——标签字面是 core 编排的槽位键（同时是 ResourceSource
+ * 标签填充槽位条目——标签字面是 core 编排的槽位键（同时是 ResourceSource
  * 枚举成员，报告输出与历史值逐字一致）；宿主未提供某标签根时该条目跳过（该源在
  * 遮蔽序中自然缺席），其余条目（core 自建：homedir/env/workspaceRoot 推导）留原位
  * 原序，遮蔽优先级语义与注入化前逐字一致。
+ *
+ * 同标签多根（W2④，Map→列表）：同标签多条目依注入序全部保留、同序位依次扫描
+ * （旧实现 Map(source→dir) 同标签靠后者整体覆盖，多根语义缺失）。硬编码槽
+ * （user-agents/project-agents）与 hostRoots 同标签注入合并——硬编码根（本体根）
+ * 排在注入条目之后：core 合并 last-writer-wins 靠后者胜，本体在后 = 本体胜（红线 2
+ * 「注入/合并序语义」）。pi 单条目形态（每标签恰好一条或无注入）下 targets 序与
+ * 旧实现逐项一致（回归红线，见 __tests__ pi 单条目形态快照用例）。
  */
 function buildScanTargets(config: ScanConfig): ScanTarget[] {
   const { kind, workspaceRoot, hostRoots, includeTmp } = config;
   const home = homedir();
 
-  // 同标签多条目时取列表靠后者（hostRoots 按优先级低→高，靠后 = 宿主侧更高优先级）
-  const hostDirBySource = new Map<string, string>(
-    hostRoots.map((root): [string, string] => [root.source, root.dir]),
-  );
+  // 同标签多条目依注入序全部保留（W2④ 列表语义）：宿主把「展开目标 + 本体根」
+  // 按注入序注入同标签，core 同序位依次扫描；本体靠后 → last-writer-wins 本体胜。
+  const hostDirsBySource = new Map<string, string[]>();
+  for (const root of hostRoots) {
+    const list = hostDirsBySource.get(root.source);
+    if (list) list.push(root.dir);
+    else hostDirsBySource.set(root.source, [root.dir]);
+  }
+  const hostTargets = (source: ResourceSource): ScanTarget[] =>
+    (hostDirsBySource.get(source) ?? []).map((dir) => ({ dir, source, enabled: true }));
 
   const targets: ScanTarget[] = [];
   // 1. user .pi/agent/{kind}/（宿主注入，pi 壳 source "user-pi"）
-  const userPiDir = hostDirBySource.get("user-pi");
-  if (userPiDir !== undefined) {
-    targets.push({ dir: userPiDir, source: "user-pi", enabled: true });
-  }
-  // 2. user .agents/{kind}/（core 自建：homedir 推导，非宿主依赖）
+  targets.push(...hostTargets("user-pi"));
+  // 2. user .agents/{kind}/（硬编码根 = homedir 推导 + 宿主可选注入合并，硬编码
+  //    本体根后置 → 注入的展开目标在前、本体在后，last-writer-wins 本体胜）
+  targets.push(...hostTargets("user-agents"));
   targets.push({ dir: join(home, ".agents", kind), source: "user-agents", enabled: true });
   // 3. npm global: <agentDir>/npm/node_modules/*/<pkg>/（宿主注入，pi 壳 source "npm"）
-  const npmDir = hostDirBySource.get("npm");
-  if (npmDir !== undefined) {
-    targets.push({ dir: npmDir, source: "npm", enabled: true });
-  }
+  targets.push(...hostTargets("npm"));
   // 4. npm dev symlink: <agentDir>/extensions/*/<pkg>/（宿主注入，pi 壳 source "npm-dev"）
-  const npmDevDir = hostDirBySource.get("npm-dev");
-  if (npmDevDir !== undefined) {
-    targets.push({ dir: npmDevDir, source: "npm-dev", enabled: true });
-  }
+  targets.push(...hostTargets("npm-dev"));
   // user extension paths (XYZ_EXTENSION_PATHS, dev-link): each path is a package dir,
   // 走 processPackage 读 pi.{kind} manifest 或扫 {kind}/ 目录。优先级高于 npm/npm-dev
   // （dev-link 是开发版 override），低于 project（项目正式资源优先）。
@@ -568,7 +593,13 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
     });
   }
 
-  // 7. project .agents/{kind}/
+  // 6.5 project host 根（宿主注入，W2②）：承接宿主自有项目级布局（如 zsw 的
+  //     <ws>/.zcode/agents）。序位在 project-agents 之下（.agents 是项目级最高
+  //     逃生门）；未注入该标签时槽位缺席（与 user-pi/npm/npm-dev 同语义）。
+  targets.push(...hostTargets("project-host"));
+
+  // 7. project .agents/{kind}/（硬编码根 + 宿主可选注入合并，本体根后置同槽 2）
+  targets.push(...hostTargets("project-agents"));
   targets.push({
     dir: join(workspaceRoot, ".agents", kind),
     source: "project-agents",
@@ -586,6 +617,12 @@ function buildScanTargets(config: ScanConfig): ScanTarget[] {
  * 按优先级低→高扫描所有源，同名资源靠后覆盖靠前（last-writer-wins）。
  * npm/dev 包内：有 manifest 只走 manifest（路径不存在则失败），无 manifest 扫约定目录。
  *
+ * realpath 归一去重（W2①，仅 async 链）：多个不同名 symlink 指向同一物理文件时
+ * （多链同文件），stem 去重防不住——清单按物理文件归一只留一条（首遇者，位置
+ * 固定语义与 stem 合并一致）；同 stem 不同物理文件的遮蔽语义不受影响（仍按
+ * last-writer-wins 覆盖）。realpath 解析失败（扫描后竞态删除/ELOOP 深链）回退
+ * 原 path，属预期失败不抛。
+ *
  * Throws on unrecoverable scan errors——未捕获异常向上抛（Promise.all 首个 reject
  * 即整体拒绝，与串行版 discoverResourcesSync 的传播语义一致，见实现内 [perf] 注释）。
  * 预期失败不抛：目录不存在/不可读返回空列表，manifest 声明路径缺失以 available=false 返回。
@@ -624,13 +661,35 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
     }),
   );
 
+  // [W2①] realpath 归一键（仅 async 链）：与 allBySource 同构的二维数组（源序×
+  // 源内资源序）。源级并行解析（每资源一次 realpath，资源量级为个位/十位数）；
+  // 失败回退原 path——扫描与 realpath 之间竞态删除/ELOOP 属预期失败，不抛
+  // （对齐 scanDirectory 的 stat().catch 吞错面）。
+  const realpathKeys: string[][] = await Promise.all(
+    allBySource.map(async ({ resources }) =>
+      Promise.all(resources.map((r) => realpath(r.path).catch(() => r.path))),
+    ),
+  );
+
   // 按优先级合并：targets 数组顺序即优先级（低→高），高优先级后写覆盖
   // 用文件名 stem 作为去重 key（与旧逻辑一致：同名资源高优先级覆盖）
   const merged = new Map<string, DiscoveredResource>();
-
-  for (const { resources } of allBySource) {
-    for (const r of resources) {
+  // realpath → 已入清单 stem key：多链同文件（不同名 symlink 指向同一物理文件）
+  // 时后到链 skip——清单按物理文件只留一条，不计入遮蔽（同一文件无遮蔽语义）。
+  const realpathOwner = new Map<string, string>();
+
+  for (let si = 0; si < allBySource.length; si++) {
+    const { resources } = allBySource[si]!;
+    for (let ri = 0; ri < resources.length; ri++) {
+      const r = resources[ri]!;
       const key = stem(r.path);
+      const rp = realpathKeys[si]![ri]!;
+      // 同物理文件已以另一 stem 入清单 → 多链重复，跳过（不影响 stem 遮蔽语义：
+      // 同 stem 不同物理文件仍走下方 last-writer-wins）
+      const owner = realpathOwner.get(rp);
+      if (owner !== undefined && owner !== key) {
+        continue;
+      }
       const existing = merged.get(key);
       // available=false 的占位不覆盖已有的 available=true
       if (!r.available && existing) {
@@ -661,6 +720,7 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
         }
       }
       merged.set(key, r);
+      realpathOwner.set(rp, key);
     }
   }
 
@@ -668,10 +728,12 @@ export async function discoverResources(config: ScanConfig): Promise<DiscoveredR
 }
 
 /**
- * 同步版：扫描单个目录下的资源文件路径（供 agent-registry 的 mtime 缓存模式使用）。
+ * 同步版：扫描单个目录下的资源文件路径。
  *
- * agent .md 发现需要 mtime 缓存（hot-reload），不能走 async 全量扫描。
- * 此函数提供目录级同步扫描，npm/dev 包内发现仍需 async（agent-registry 用 builtin 兜底）。
+ * 消费关系（W2⑤ 漂移修正）：当前无非测试调用方——agent-registry 只 import
+ * getCachedFile（mtime 缓存），不消费 sync 扫描。保留作 async scanDirectory 的
+ * 对称 API / 测试用；生产 agent/workflow 发现统一走 async discoverResources
+ * （红线 4：修对生产面）。npm/dev 包内发现仍需 async（scanNpmDir）。
  */
 export function scanDirectorySync(dirPath: string, kind: ResourceKind): string[] {
   try {
@@ -697,7 +759,8 @@ export function scanDirectorySync(dirPath: string, kind: ResourceKind): string[]
 
 /**
  * 同步版：读取 package.json 的 pi.{kind} manifest。
- * 供 agent-registry 同步路径使用。与 async 版共享 manifestCache（双读者同一 Map）。
+ * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。与 async 版
+ * 共享 manifestCache（双读者同一 Map）。
  */
 export function readPackageManifestSync(pkgDir: string, kind: ResourceKind): string[] | undefined {
   const pkgJsonPath = resolve(pkgDir, "package.json");
@@ -725,7 +788,7 @@ export function readPackageManifestSync(pkgDir: string, kind: ResourceKind): str
 
 /**
  * 同步版：处理单个 npm/dev 包。
- * 供 agent-registry 同步路径使用。
+ * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。
  */
 export function processPackageSync(pkgDir: string, kind: ResourceKind): DiscoveredResource[] {
   const manifestPaths = readPackageManifestSync(pkgDir, kind);
@@ -767,7 +830,7 @@ export function processPackageSync(pkgDir: string, kind: ResourceKind): Discover
 
 /**
  * 同步版：扫描 npm node_modules 目录。
- * 供 agent-registry 同步路径使用。
+ * 当前无非测试调用方（W2⑤ 漂移修正，保留作对称 API/测试用）。
  */
 export function scanNpmDirSync(nodeModulesDir: string, kind: ResourceKind): DiscoveredResource[] {
   let entries: string[];
@@ -800,10 +863,14 @@ export function scanNpmDirSync(nodeModulesDir: string, kind: ResourceKind): Disc
 }
 
 /**
- * 同步版：发现所有资源（agent-registry 专用，支持 mtime 缓存的 hot-reload）。
+ * 同步版：发现所有资源。
+ *
+ * 当前无非测试调用方（W2⑤ 漂移修正：agent-registry 只 import getCachedFile，
+ * 不消费本族；保留作 async discoverResources 的对照实现/测试用——两版输出等价
+ * 由既有快照用例锁定）。
  *
- * 与 discoverResources 对应的同步实现，扫描相同的源。
- * 返回所有源的资源（未去重，调用方按需处理优先级）。
+ * 与 discoverResources 对应的同步实现，扫描相同的源，同 stem last-writer-wins
+ * 合并（不含 async 链的 realpath 去重——sync 链无非测试调用方，勿扩面，红线 4）。
  */
 export function discoverResourcesSync(config: ScanConfig): DiscoveredResource[] {
   const targets = buildScanTargets(config);

package/src/shared/resource-meta.ts

@@ -59,6 +59,20 @@ export interface AgentMeta extends ResourceMetaBase {
    * 与 model 字段同风格——路由字段（不进 system prompt），执行侧（P4 路由层）消费。
    */
   engine?: string;
+  /**
+   * 执行预算：turn 上限（sink 设计 D3 新增可选执行字段之一）。
+   * 消费优先级：显式参数 > 本字段 > 缺省——pi 工具参数 maxTurns 语义不变（本字段
+   * 对 pi 是清单元数据），zsw 决策链 timeoutMs > profile.maxTurns > 缺省。
+   */
+  maxTurns?: number;
+  /** tool denylist（D3 可选执行字段）：spawn 侧剔除，与 tools allowlist 正交。 */
+  disallowedTools?: string[];
+  /**
+   * agent 声明依赖的 skill 名清单（D3 可选执行字段）。注意与本文件头注
+   * 「skills 归 pi core」的 skills（资源种类）不同物：此处是 agent frontmatter 的
+   * 执行配置字段，不是 ResourceKind。
+   */
+  skills?: string[];
 }
 
 /** 判别联合（kind 判别）。 */

package/src/shared/xml-injection.ts

@@ -9,12 +9,12 @@
  * XML 结构——全部字段过一遍转义防注入段破碎）。
  */
 export function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
 }
 
 /**
@@ -29,7 +29,7 @@ export function renderXmlSection(section: {
 	guide: string;
 	items: string[];
 }): string {
-	if (section.items.length === 0) return "";
-	const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
-	return lines.join("\n");
+  if (section.items.length === 0) return "";
+  const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
+  return lines.join("\n");
 }