@istuen/pt 0.1.0

package/src/parse/blueprint.ts

@@ -0,0 +1,82 @@
+// src/parse/blueprint.ts — blueprints/*.blueprint.yaml → Blueprint IR
+//
+// Phase term-P4.5：载体从 MD 转 YAML。
+//   Blueprint 是纯结构化无叙事（target + mode + modules），MD 的 H2/H3 是用叙事格式装非叙事数据。
+//   YAML 直接表达嵌套结构，parser 简化为 yaml.load() + 校验，与 frontmatter 同构。
+//
+// Blueprint asset 格式（v9.5）：
+//   name: <blueprint-name>
+//   groups:
+//     - name: 会话背景              ← 聚合组（人类自定义语义名）
+//       inject: session              ← 注入位置（session / turn，Agent-agnostic）
+//       mode: hybrid                 ← 可选
+//       modules: [Scene, Participant]   ← 聚合点（Domain Schema Name 列表）
+//     - name: 触发索引
+//       inject: session
+//       modules: [Trigger]
+//     - name: 参考手册
+//       inject: turn
+//       modules: [Rules, Flows, Checklists]
+//
+// Tech Debt T6: 用 constants + type guard（pt-quality #1/#4/#5）
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { Blueprint, BlueprintGroup, InjectTarget, StructureLayout } from "../schema.js";
+
+const VALID_MODES: ReadonlyArray<StructureLayout["mode"]> = ["byDomain", "byType", "hybrid"];
+
+interface RawBlueprintGroup {
+  name: string;
+  inject: string;
+  mode?: string;
+  // v9.1（modules-to-profile 迁移）：modules 已迁到 ProfileGroup，本接口字段保留注释说明。
+  // 旧 YAML 中 modules: [..] 行 parse 后被忽略——迁移期内联文件用。
+  modules?: string[];
+}
+
+interface RawBlueprint {
+  name: string;
+  groups: RawBlueprintGroup[];
+}
+
+/** 读 blueprints/<fileName>.blueprint.yaml → Blueprint { name, groups }
+ *  v9.1（modules-to-profile 迁移）：BlueprintGroup 不再带 modules——modules 由 ProfileGroup
+ *  通过 H2 `### Modules` 段提供。YAML 中 modules 行（若有）被静默忽略，迁移期兼容。 */
+export async function parseBlueprint(absDir: string, fileName: string): Promise<Blueprint> {
+  const filePath = join(absDir, fileName);
+  const raw = await readFile(filePath, "utf8");
+  const data = parseYaml(raw) as RawBlueprint;
+
+  if (!data || typeof data.name !== "string") {
+    throw new Error(`parseBlueprint: ${fileName} 缺少顶层 name 字段`);
+  }
+  if (!Array.isArray(data.groups)) {
+    throw new Error(`parseBlueprint: ${fileName} 缺少 groups 数组`);
+  }
+
+  const groups: BlueprintGroup[] = data.groups.map((ip) => {
+    if (typeof ip.name !== "string") {
+      throw new Error(`parseBlueprint: ${fileName} 聚合组缺 name 字段`);
+    }
+    if (typeof ip.inject !== "string") {
+      throw new Error(`parseBlueprint: ${fileName} 聚合组 ${ip.name} 缺 inject 字段`);
+    }
+
+    const config: BlueprintGroup = {
+      name: ip.name,
+      inject: ip.inject as InjectTarget,
+    };
+    if (ip.mode && isValidMode(ip.mode)) {
+      config.mode = ip.mode;
+    }
+    return config;
+  });
+
+  return { name: data.name, groups };
+}
+
+function isValidMode(x: string): x is StructureLayout["mode"] {
+  return (VALID_MODES as readonly string[]).includes(x);
+}

package/src/parse/domain-renderers.ts

@@ -0,0 +1,120 @@
+// src/parse/domain-renderers.ts — Domain H2 段解析注册表（pt-quality #3）
+//
+// Phase term-P9.3：注册表从二维（h2Name × type）降为一维（h2Name）。
+//   - Type 字段已删除——H2 段名 = schema 选择器（一个 H2 段一个 schema）
+//   - 加新 H2 段名 = 调 registerDomainSectionRenderer 加一行 + parser 函数
+//
+// 替换 parse/domain.ts 中的 switch-case 主逻辑。switch-case 仅留兜底 default fallback。
+
+import { s, sArr, type Item } from "./shared.js";
+import type { FlowStep } from "../schema.js";
+
+/** 单个 H2 段内容解析器。 */
+export type DomainSectionParser = (items: Item[], sectionRaw: string) => unknown;
+
+/** 注册表：H2段名 → parser。Phase term-P9.3：删 type 维度。 */
+const domainSectionRenderers: Record<string, DomainSectionParser> = {
+  // H2="Scene"（Phase term-P9.1：统一为 Term[]）
+  Scene: (items) =>
+    items.map((it) => {
+      const desc = s(it.fields.desc) || s(it.fields.description) || s(it.fields.role) || "";
+      const path = s(it.fields.path);
+      const fields = sArr(it.fields.fields);
+      const note = s(it.fields.purpose) || s(it.fields.rule);
+      const term: { name: string; desc?: string; fields?: string[]; note?: string; path?: string } =
+        {
+          name: it.name,
+        };
+      if (desc) term.desc = desc;
+      if (path) term.path = path;
+      if (fields.length > 0) term.fields = fields;
+      if (note) term.note = note;
+      return term;
+    }),
+  // H2="Rules"（Phase term-P9.2：从 Manual.term 拆出）—— Rule[]
+  Rules: (items) =>
+    items.map((it) => {
+      const itemsArr = sArr(it.fields.items);
+      const check =
+        s(it.fields.check) ||
+        s(it.fields.desc) ||
+        s(it.fields.value) ||
+        s(it.fields.description) ||
+        "";
+      if (itemsArr.length > 0) {
+        return { name: it.name, slot: "global", type: "ban", check, items: itemsArr };
+      }
+      return { name: it.name, slot: "global", type: "invariant", check };
+    }),
+  // H2="Flows"（Phase term-P9.2：从 Manual.workflow 拆出）—— FlowTemplate[]
+  Flows: (items, sectionRaw) =>
+    items.map((item) => {
+      const tpl: Record<string, unknown> = {
+        name: item.name,
+        argumentHint: s(item.fields["argument-hint"]) || undefined,
+        intent: s(item.fields.intent),
+        steps: collectSteps(item.name, sectionRaw),
+        externals: [],
+      };
+      const vars = sArr(item.fields.vars);
+      if (vars.length > 0) tpl._vars = vars;
+      return tpl;
+    }),
+  // H2="Checklists"（Phase term-P9.2：新增）—— Checklist[]
+  Checklists: (items) =>
+    items.map((it) => ({
+      name: it.name,
+      items: sArr(it.fields.items),
+    })),
+};
+
+/** 加新 H2 段名 = 调 registerDomainSectionRenderer 加一行注册 + 一个 parser 函数。
+ *  Phase term-P9.3：删 type 参数。 */
+export function registerDomainSectionRenderer(h2Name: string, parser: DomainSectionParser): void {
+  domainSectionRenderers[h2Name] = parser;
+}
+
+/** 取 H2段名 的 parser。未注册返 undefined（调用方走 fallback）。Phase term-P9.3：删 type 参数。 */
+export function getDomainSectionParser(h2Name: string): DomainSectionParser | undefined {
+  return domainSectionRenderers[h2Name];
+}
+
+// ==================== shared 辅助 ====================
+
+function collectSteps(itemName: string, sectionRaw: string): FlowStep[] {
+  const lines = sectionRaw.split(/\r?\n/);
+  const steps: FlowStep[] = [];
+  let inItem = false;
+  let cur: FlowStep | null = null;
+  for (const line of lines) {
+    const h3 = line.match(/^###\s+(.+)$/);
+    if (h3) {
+      if (inItem) break;
+      if (h3[1].trim() === itemName) inItem = true;
+      continue;
+    }
+    if (!inItem) continue;
+    const stepMatch = line.match(/^\s*-\s+step\s*:\s*(.+)$/);
+    if (stepMatch) {
+      if (cur) steps.push(cur);
+      cur = { desc: stepMatch[1].trim() };
+      continue;
+    }
+    const observeMatch = line.match(/^\s*-\s+observe\s*:\s*(.+)$/);
+    if (observeMatch && cur) {
+      const val = observeMatch[1].trim();
+      // 支持 [a, b] 数组格式 和 单值格式
+      const arrMatch = val.match(/^\[(.*)\]$/);
+      if (arrMatch) {
+        cur.observe = arrMatch[1]
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s) => s !== "");
+      } else {
+        cur.observe = [val];
+      }
+    }
+  }
+  if (cur) steps.push(cur);
+  return steps;
+}

package/src/parse/domain.ts

@@ -0,0 +1,78 @@
+// src/parse/domain.ts — domains/*.md → Domain IR
+//
+// Phase term-P9.3：删除 type 字段（Phase term-P9.2 时已先保留 type 键做过渡）。
+//   parser 注册表从二维（h2Name × type）降为一维（h2Name）。
+//   加新 H2 段名 = 调 registerDomainSectionRenderer 加一行注册 + parser 函数。
+//
+// Domain asset 格式（v9.3）：
+//   ---
+//   name: <domain-name>
+//   ---
+//
+//   ## Scene          ← H2 段名 = 上下文模块类型（schema 由段名决定）
+//     ...（Term[] 形态，含 path/fields/note/desc）
+//
+//   ## Rules          ← Rule[]（pt-quality）
+//     ...
+//
+//   ## Flows          ← FlowTemplate[]（dev-workflow 等）
+//     ...
+//
+//   ## Checklists     ← Checklist[]（pt-collab）
+//     ...
+//
+//   ## Trigger         ← 索引段（H3 + desc/hint）
+//     ...
+
+import { join } from "node:path";
+import type { Domain, Term } from "../schema.js";
+import { readAsset, s, type Item } from "./shared.js";
+import { getDomainSectionParser } from "./domain-renderers.js";
+
+/** 读 domains/<relPath>.md → Domain { name, modules: Record<H2名, 内容> }
+ *  Phase term-P9.3：Domain 不再有 type 字段——H2 段名直接决定 schema。
+ *  v10.x：assetDir 让 fixtures 可指向 tests/fixtures/assets/（默认 .pt/assets）。
+ *  v9.1+（modules-to-profile-complete）：relPath 是 POSIX 相对路径（如 "user-info.md" /
+ *  "workflow/dev-workflow.md"），用于支持多级目录。Domain.name 默认用 POSIX 相对路径去后缀。 */
+export async function parseDomain(absDir: string, relPath: string): Promise<Domain> {
+  const asset = await readAsset(join(absDir, relPath));
+
+  // H2 段名 → 段内容的解析：调注册表 parser，未注册走 fallback (Term[])
+  const modules: Record<string, unknown> = {};
+  for (const [h2Name, section] of Object.entries(asset.sections)) {
+    modules[h2Name] = parseDomainSection(h2Name, section.items, section.raw);
+  }
+
+  return {
+    name:
+      typeof asset.frontmatter.name === "string"
+        ? asset.frontmatter.name
+        : normalizeDomainName(relPath),
+    modules,
+  };
+}
+
+/** 从 POSIX 相对路径生成 Domain.name（去 .md 后缀，'/' 保留以支持多级目录）。
+ *  Node.js readdir({ recursive: true }) 跨平台统一返回 '/' 分隔路径——Windows 也用 '/'。 */
+function normalizeDomainName(relPath: string): string {
+  return relPath.split(/[\\/]/).join("/").replace(/\.md$/, "");
+}
+
+/** 调注册表 parser（h2Name）解析单个 H2 段。Phase term-P9.3：删 type 参数，二维注册表降一维。
+ *  未注册走 default fallback：term 形态（Term[]）——新 H2 段名加 fallback 即可。 */
+function parseDomainSection(h2Name: string, items: Item[], sectionRaw: string): unknown {
+  const parser = getDomainSectionParser(h2Name);
+  if (parser) return parser(items, sectionRaw);
+
+  // 未知 H2 段名：fallback 形态（term 的 Term[]）
+  // ——新增 H2 段名（如 "Glossary"）会自动走 fallback 输出 Term[]，无需注册
+  return fallbackTerms(items);
+}
+
+/** Default fallback：把 H3 项数组转 Term[]（用于未注册的 H2 段名，如 ## Term / ## Glossary）。 */
+function fallbackTerms(items: Item[]): Term[] {
+  return items.map((it) => ({
+    name: it.name,
+    desc: s(it.fields.desc) || s(it.fields.description),
+  }));
+}

package/src/parse/index.ts

@@ -0,0 +1,266 @@
+// src/parse/index.ts — Parse 前端入口
+//
+// Phase 9.3：v9 适配 — 枚举 profiles/（用户面是 Profile，不是 Blueprint）；
+//   channels/ 删除（v9 Channel 留作未来 Connector，不实现）。
+// 按目录位置分发载体（domains/ → domain adapter / blueprints/ → blueprint adapter / profiles/ → profile adapter）。
+//
+// v15.x PR1（§3.1）：mdAdapter.load 改为构造 AssetPack[] → 加载 → N 元 dedupByNameN。
+//   - 加载顺序：project → settings → global → builtin（settings PR1 stub 返空）
+//   - settings 数组内部 reverse（§3.3.1 后者赢）
+//   - 删除 loadAllDomains/loadAllBlueprints/loadAllProfiles/loadAllBuiltin* 旧函数
+//     ——它们的逻辑已迁入 src/asset-pack/md-file-pack.ts
+//   - back-compat：settingsPacks=[] 时，dedupByNameN([project, global, builtin])
+//     退化等价于今天的 dedupByName(project, builtin)（project 前者赢，builtin 补充）。
+
+import type {
+  AssetPack,
+  Blueprint,
+  Domain,
+  Profile,
+  SchemaBundle,
+  SourceAdapter,
+  SourceAdapterContext,
+  WorkingSet,
+} from "../schema.js";
+import {
+  loadBuiltinPack,
+  loadGlobalPack,
+  loadProjectPack,
+  loadSettingsPacks,
+} from "../asset-pack/loader.js";
+import { reportWarn } from "../diagnostics.js";
+import { parseRef, resolveBlueprint } from "./ref-resolver.js";
+import { parseBlueprint } from "./blueprint.js";
+import { parseDomain } from "./domain.js";
+import { parseProfile } from "./profile.js";
+
+/** MD adapter：按目录位置分发到 domain/blueprint/profile adapter，组装 SchemaBundle。
+ *  v9 命名约定：适配的是 MD 文件格式（不再叫 OXN——OXN 是历史名）。
+ *  v15.x PR1（§3.1）：内部构造 4 类 AssetPack → loadXxx → N 元 dedupByNameN。 */
+export const mdAdapter: SourceAdapter = {
+  name: "md",
+
+  async load(cwd, profileName, adapterCtx): Promise<SchemaBundle> {
+    // 1. 构造 4 类 pack（§3.1 顺序：project → settings → global → builtin）
+    const projectPack = await loadProjectPack(cwd, adapterCtx);
+    const settingsPacks = await loadSettingsPacks(cwd); // PR4 接通：读 .pi/settings.json pt.asset-packs
+    const globalPack = await loadGlobalPack(adapterCtx);
+    const builtinPack = await loadBuiltinPack(adapterCtx);
+
+    // v15.x PR4（§3.3.1）：settings 倒序——后者赢（npm 风格）
+    // packs 顺序 = [project, ...settings.reverse(), global, builtin]
+    // findActiveProfile 不限定 ref 按此顺序前者赢 → project > 后声明 settings > 先声明 settings > global > builtin
+    const packs: AssetPack[] = [
+      projectPack,
+      ...settingsPacks.slice().reverse(),
+      globalPack,
+      builtinPack,
+    ];
+
+    // v15.x PR4（§3.4）：pack name 全局唯一性校验——settings pack 之间同名报错
+    checkPackNameConflicts(packs, adapterCtx);
+
+    // 2. v15.x §4.4.2（双层语义）：构建双索引 working set——location（位置 alias）+ identity（manifest.name）
+    //    reserved pack（project/global/builtin）才进 location 索引；settings pack 不进 location（无位置别名）
+    //    所有 pack 都进 identity 索引
+    //    back-compat（缺口 1-b）：reserved pack 无 manifest 时 pack.name=位置别名，identity 与 location 索引 key 重合——双入口命中同一 asset
+    const LOC_ALIAS: ReadonlyMap<string, string> = new Map([
+      ["project", "prj"],
+      ["global", "gbl"],
+      ["builtin", "pt"],
+    ]);
+    const domainLocWS = new Map<string, { pack: AssetPack; asset: Domain }>();
+    const domainIdWS = new Map<string, { pack: AssetPack; asset: Domain }>();
+    const blueprintLocWS = new Map<string, { pack: AssetPack; asset: Blueprint }>();
+    const blueprintIdWS = new Map<string, { pack: AssetPack; asset: Blueprint }>();
+    const profileLocWS = new Map<string, { pack: AssetPack; asset: Profile }>();
+    const profileIdWS = new Map<string, { pack: AssetPack; asset: Profile }>();
+    const packProfiles: Profile[][] = [];
+    const allDomains: Domain[] = [];
+    const allBlueprints: Blueprint[] = [];
+    const allProfiles: Profile[] = [];
+
+    for (const pack of packs) {
+      const locAlias = LOC_ALIAS.get(pack.source); // settings → undefined
+      const packDoms = await pack.loadDomains();
+      for (const d of packDoms) {
+        domainIdWS.set(`${pack.name}/${d.name}`, { pack, asset: d });
+        if (locAlias) domainLocWS.set(`${locAlias}/${d.name}`, { pack, asset: d });
+        allDomains.push(d);
+      }
+      const packBps = await pack.loadBlueprints();
+      for (const b of packBps) {
+        blueprintIdWS.set(`${pack.name}/${b.name}`, { pack, asset: b });
+        if (locAlias) blueprintLocWS.set(`${locAlias}/${b.name}`, { pack, asset: b });
+        allBlueprints.push(b);
+      }
+      const packProfs = await pack.loadProfiles();
+      for (const p of packProfs) {
+        profileIdWS.set(`${pack.name}/${p.name}`, { pack, asset: p });
+        if (locAlias) profileLocWS.set(`${locAlias}/${p.name}`, { pack, asset: p });
+        allProfiles.push(p);
+      }
+      packProfiles.push(packProfs);
+    }
+
+    // 3. 找 active profile（PR3：支持 "foo" 和 "@pack/foo" 两种）
+    let active: Profile;
+    let activeProfileOrigin: "exact" | "fallback" = "exact";
+    let originalProfileName: string | undefined;
+    try {
+      active = findActiveProfile(packs, packProfiles, profileName);
+    } catch (e) {
+      // active 没找到时 fallback 到第一个 profile（与今天行为一致）
+      const fallback = allProfiles[0];
+      if (!fallback) {
+        throw e; // 真的没 profile——抛错
+      }
+      active = fallback;
+      // v15.x PR6（fix pt-active-profile-fallback-mismatch）：记录 fallback 由来
+      // 让 caller（transpile.ts + index.ts）能感知并同步 s.activeProfile / loadedFrom / notify
+      activeProfileOrigin = "fallback";
+      originalProfileName = profileName;
+    }
+
+    // 4. 校验 active 引用的 Blueprint 存在（用 working set）
+    // v15.x PR6（fix pt-parse-blueprint-warn-misleading）：改用 resolveBlueprint helper
+    // 与 compile 阶段（transpile.ts:145）共用 fallback 逻辑——避免 parse 层单方面
+    // 报 "unknown Blueprint" warn 但 compile 层能 fallback 成功的 false positive。
+    // 行为：
+    //   - 不限定 ref + 跨 pack fallback 命中 → 静默（compile 阶段会复用同一 fallback）
+    //   - 限定 ref 找不到 / 不限定 ref fallback 全部 miss → warn（compile 阶段会 throw）
+    // v15.x §4.4.2：resolveBlueprint 接双索引 WorkingSet，按 parseRef 的 kind 分发查 location/identity
+    const blueprintWS = {
+      location: blueprintLocWS,
+      identity: blueprintIdWS,
+    };
+    const bpResolved = resolveBlueprint(
+      active,
+      blueprintWS,
+      packs.map((p) => p.name)
+    );
+    if (!bpResolved && active.blueprint) {
+      const { pack: bpPack, name: bpName } = parseRef(active.blueprint, active.sourcePack ?? "");
+      reportWarn(
+        adapterCtx,
+        `Profile "${active.name}" 引用了未知 Blueprint "${active.blueprint}"`,
+        {
+          profileName: active.name,
+          referencedBlueprint: active.blueprint,
+          resolvedBlueprint: `@${bpPack}/${bpName}`,
+          availableBlueprints: [...blueprintIdWS.keys()],
+        }
+      );
+    }
+
+    return {
+      domains: allDomains,
+      blueprints: allBlueprints,
+      profiles: allProfiles,
+      activeProfile: active.name,
+      // v15.x PR6（fix pt-active-profile-fallback-mismatch）：暴露 fallback 由来
+      activeProfileOrigin,
+      originalProfileName,
+      packs,
+      activeProfilePack: findProfilePack(packs, packProfiles, active.name),
+      // v15.x §4.4.2：working set 双索引
+      workingSet: {
+        domains: { location: domainLocWS, identity: domainIdWS },
+        blueprints: blueprintWS,
+        profiles: { location: profileLocWS, identity: profileIdWS },
+      },
+    };
+  },
+};
+
+/** v15.x PR3：找 active profile——支持 "foo" 和 "@pack/foo" 两种。
+ *  限定 ref 直接查目标 pack；不限定按 packs 顺序前者赢（project > settings 倒序 > global > builtin）。
+ *  v15.x PR4：settings 倒序逻辑由 mdAdapter.load 构造 packs 时已处理，findActiveProfile 不变。 */
+function findActiveProfile(
+  packs: AssetPack[],
+  packProfiles: Profile[][],
+  profileRef: string
+): Profile {
+  if (profileRef.startsWith("@")) {
+    const { pack, name } = parseRef(profileRef, ""); // 限定 ref 不需要 selfPack
+    const packIdx = packs.findIndex((p) => p.name === pack);
+    if (packIdx < 0) {
+      throw new Error(`active profile "@${pack}/${name}" references unknown pack "${pack}"`);
+    }
+    const found = packProfiles[packIdx]?.find((p) => p.name === name);
+    if (!found) {
+      throw new Error(`active profile "@${pack}/${name}" not found in pack "${pack}"`);
+    }
+    return found;
+  }
+  for (let i = 0; i < packs.length; i++) {
+    const found = packProfiles[i]?.find((p) => p.name === profileRef);
+    if (found) return found;
+  }
+  throw new Error(`active profile "${profileRef}" not found in any pack`);
+}
+
+/** v15.x PR2（§8.3）：找 profile 所属 pack——按 dedup 前顺序，
+ *  第一个含该 profile name 的 pack 赢（PR3 后 working set 取代 dedup，但 cache 文件名仍用 pack name）。
+ *  fallback "prj"（不应到达——active profile 必来自某 pack）。 */
+function findProfilePack(
+  packs: AssetPack[],
+  packProfiles: Profile[][],
+  profileName: string
+): string {
+  for (let i = 0; i < packs.length; i++) {
+    if (packProfiles[i]?.some((p) => p.name === profileName)) {
+      return packs[i].name;
+    }
+  }
+  return "prj";
+}
+
+/** v15.x PR4（§3.4）+ §3.4 缺口 2（升级 throw）：pack name 全局唯一性校验。
+ *  reserved pack 读 manifest 后，project + settings 同 manifest.name 可能撞名。
+ *  3 个场景区分：
+ *    - 场景 A（路径重叠）：settings pack rootDir 与 project pack 一致 → throw + "路径重叠"
+ *    - 场景 B（不同路径同名）：多个 settings pack 同 manifest.name 但 rootDir 不同 → throw + "不同路径同 name"
+ *    - back-compat：project/settings 覆盖 global/builtin 是合理优先级 → 不 throw，静默（§3.4 表）
+ *  错误从 session_start catch 透出到 ctx.ui.notify("error")——用户能直接看到场景区分。
+ *
+ *  reserved 名（prj/gbl/pt）只 1 份，不会冲突。settings pack manifest.name 不能是 reserved 名
+ *  （PR2 manifest 校验已挡），所以不会与 reserved 重名。 */
+function checkPackNameConflicts(packs: AssetPack[], adapterCtx?: SourceAdapterContext): void {
+  const seen = new Map<string, AssetPack[]>();
+  for (const pack of packs) {
+    const arr = seen.get(pack.name) ?? [];
+    arr.push(pack);
+    seen.set(pack.name, arr);
+  }
+  for (const [name, group] of seen) {
+    if (group.length <= 1) continue;
+    // 同 name 多份——按是否含 settings source 分类处理
+    const hasSettings = group.some((p) => p.source === "settings");
+    if (!hasSettings) {
+      // 没有 settings 来源：project+global/builtin 同名 = 合理优先级（§3.4 表），静默
+      // 不可能发生（manifest 校验挡 reserved name）；保留分支以防未来加新 source
+      continue;
+    }
+    // 有 settings 来源——按 rootDir 是否一致区分场景 A/B
+    const rootDirs = new Set(group.map((p) => p.rootDir));
+    const sources = group.map((p) => `${p.source}(${p.rootDir})`).join(" + ");
+    if (rootDirs.size === 1) {
+      // 场景 A：路径重叠（settings pack 与 project pack 指向同一目录）—— 重复加载同一份
+      throw new Error(
+        `§3.4 路径重叠：settings pack "@${name}" 与 project pack 指向同一目录 ${[...rootDirs][0]}。` +
+          `修复：从 pt.asset-packs 移除重复 path，或从 pt.project-pack-dir / assetDir 切到别处。`
+      );
+    }
+    // 场景 B：不同路径同名——多份 manifest.name 相同但指向不同目录
+    const pathsList = group.map((p) => `  - ${p.source}: ${p.rootDir}`).join("\n");
+    throw new Error(
+      `§3.4 不同路径同 name：pack "${name}" 在多个不同路径被声明为同一身份：\n${pathsList}\n` +
+        `修复：删掉重复的 pt.asset-packs 条目，或给同名 pack 加唯一 manifest.name 区分。`
+    );
+  }
+}
+
+// 保留 parseX 函数的导出（其他模块 / 测试可能 import）。PR1 阶段 MdFilePack 已复用，
+// 但 parseX 仍作为底层 parser 公开——加新 adapter 类型时可直接 import。
+export { parseBlueprint, parseDomain, parseProfile };