@istuen/pt 0.1.0

package/src/parse/profile.ts

@@ -0,0 +1,139 @@
+// src/parse/profile.ts — profiles/*.md → Profile IR
+//
+// Phase 9.3：v9 新增 — Profile（业务端实例）= 引用 Blueprint + 选 Domains（YAML 全局 + 聚合组追加）。
+//   - YAML frontmatter:
+//     - blueprint: <blueprint-name>
+//     - domains: [d1, d2, ...]   ← 全局 Domain 列表（自动分发到所有聚合组）
+//   - ## <聚合组名> : 聚合组实例化（与 Blueprint 同名）
+//     - ### Domains : 追加到本聚合组的 Domain 名列表
+//
+// Profile asset 格式（v9 + v9.1 modules-to-profile-complete）：
+//   ---
+//   name: <profile-name>
+//   blueprint: <blueprint-name>
+//   domains: [d1, d2, ...]
+//   ---
+//
+//   ## 会话背景
+//   ### Modules
+//   - Scene                  ← 段名（跨所有引用域该段）
+//   - User.user-profile      ← 段.项（跨所有引用域该段下 H3 项）
+//   - Agent.senior-developer
+//   ### Domains
+//   - d3
+
+import { join } from "node:path";
+import { reportWarn } from "../diagnostics.js";
+import { SUFFIX_PROFILE } from "../constants.js";
+import type { ModName, Profile, ProfileGroup } from "../schema.js";
+import type { SourceAdapterContext } from "../schema.js";
+import { extractDomainsList, extractModulesList, readAsset, sArr } from "./shared.js";
+
+/** 已知 H2 段名（段名 = 命名空间）。modName 解析时左段必须是段名。
+ *  扩展新段名 = 加这一行 + registerModuleRenderer 加一行 + 一致性测试。
+ *  v9.1+（modules-to-profile-complete）：加 "User" / "Agent" 专用段（user-info / agent-info 重命名）。
+ *  公开导出（src/asset-health.ts 复用做 unknown-modname 检测——避免重复常量）。 */
+export const KNOWN_SECTION_NAMES: ReadonlySet<string> = new Set([
+  "Scene",
+  "Participant", // 保留兼容——之前 user-info / agent-info 用的段名
+  "Trigger",
+  "Rules",
+  "Flows",
+  "Checklists",
+  "User", // user-info 重命名后专用段
+  "Agent", // agent-info 重命名后专用段
+  "Term", // fallback term 形态
+]);
+
+/** 解析 modName 字符串 → { section, item? }。
+ *  形态 1: "Scene" → { section: "Scene" }（整段）
+ *  形态 2: "User.user-profile" → { section: "User", item: "user-profile" }（单 H3 项）
+ *  解析失败（不含 '.' 但段名未知 / 含 '.' 但段名未知 / 段名已知但项名为空）→ 返 null。
+ *  不跨段匹配 item（"User.user-profile" 不匹配 "Agent" 段下同名 H3）—— 跨段同名由段名命名空间避免。 */
+export function parseModName(raw: string): ModName | null {
+  const modName = raw.trim();
+  if (!modName) return null;
+  if (modName.includes(".")) {
+    const dotIdx = modName.indexOf(".");
+    const section = modName.slice(0, dotIdx);
+    const item = modName.slice(dotIdx + 1);
+    if (KNOWN_SECTION_NAMES.has(section) && item) {
+      return { section, item };
+    }
+    return null;
+  }
+  if (KNOWN_SECTION_NAMES.has(modName)) {
+    return { section: modName };
+  }
+  return null;
+}
+
+/** 读 profiles/<fileName>.md → Profile { name, blueprint, domains, groups }
+ *  v10.x：assetDir 让 fixtures 可指向 tests/fixtures/assets/（默认 .pt/assets）。
+ *  v9.1（modules-to-profile 迁移）：每个 H2 段加读 `### Modules` 填 ProfileGroup.modules。
+ *  v9.1+（modules-to-profile-complete）：modName 字符串解析为 ModName 对象（2 形态）。 */
+export async function parseProfile(
+  absDir: string,
+  fileName: string,
+  adapterCtx?: SourceAdapterContext
+): Promise<Profile> {
+  const asset = await readAsset(join(absDir, fileName));
+
+  const blueprint =
+    typeof asset.frontmatter.blueprint === "string" ? asset.frontmatter.blueprint : "";
+
+  const domains = sArr(asset.frontmatter.domains); // YAML 全局 domains
+
+  // v14.x：tagline 选填，从 frontmatter 读（string 校验，非字符串静默忽略）
+  //   不做长度硬截——展示层（footer / 选择器）按需 truncate；资产可写长描述，
+  //   UI 表现由使用方决定（UI 是显示抽象，资产是数据抽象）。
+  const taglineRaw = asset.frontmatter.tagline;
+  const tagline =
+    typeof taglineRaw === "string" && taglineRaw.trim().length > 0 ? taglineRaw.trim() : undefined;
+
+  // v15.x PR5（§5.1）：use 单继承字段——选填 string，解析阶段只读不展开
+  //   引用解析在 expandProfile（src/compile/resolve-use.ts）做——分离关注点
+  const useRaw = asset.frontmatter.use;
+  const use = typeof useRaw === "string" && useRaw.trim().length > 0 ? useRaw.trim() : undefined;
+
+  // groups：每个 H2 = 聚合组实例化
+  //   - ### Domains → 追加到本聚合组的 Domain 名列表（v9 既有）
+  //   - ### Modules → 本插槽填的聚合模块列表（v9.1+），modName 解析为 ModName 对象
+  const groups: ProfileGroup[] = [];
+  for (const [h2Name, section] of Object.entries(asset.sections)) {
+    const appendDomains = extractDomainsList(section);
+    const rawMods = extractModulesList(section);
+    const modules: ModName[] = [];
+    for (const raw of rawMods) {
+      const parsed = parseModName(raw);
+      if (parsed) {
+        modules.push(parsed);
+      } else {
+        // 解析失败——log warn，skip（与设计文档 §5 "缺填" 一致：可能故意 / 笔误）
+        reportWarn(
+          adapterCtx,
+          `Profile「${asset.name}」聚合组「${h2Name}」的 modName 解析失败：${raw}`,
+          { profile: asset.name, group: h2Name, modName: raw }
+        );
+      }
+    }
+    groups.push({ name: h2Name, domains: appendDomains, modules });
+  }
+
+  return {
+    name:
+      typeof asset.frontmatter.name === "string"
+        ? asset.frontmatter.name
+        : stripProfileSuffix(asset.name),
+    blueprint,
+    domains,
+    groups,
+    tagline,
+    use,
+  };
+}
+
+function stripProfileSuffix(fileBase: string): string {
+  // v9 命名约定：<name>.profile.md → 去 .profile 后缀
+  return fileBase.replace(new RegExp(`${SUFFIX_PROFILE}$`), "");
+}

package/src/parse/ref-resolver.ts

@@ -0,0 +1,198 @@
+// src/parse/ref-resolver.ts — @pack/name 限定语法工具（v15.x PR3）
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §4（@pack/name 限定语法）+ §4.4.2（fingerprint + dedup）
+//
+// 职责：
+// - parseRef：统一解析限定 + 不限定 ref → {pack, name}
+// - fingerprint：sha256(rootDir + content) 截 16 字符
+// - resolveAndDedupRefs：解析 refs + fp dedup（后者覆盖前者，Map.set 语义）
+//
+// 关键纪律：
+// - parseRef 抛异常（不像 parseManifest 容错）—— 畸形 ref 是配置错误
+// - 别名归一：@project/foo → @prj/foo（兼容旧文档，§4.1）
+// - 解析阶段展开为统一形态——IR 不升级（profile.domains 仍 string[]）
+// - fingerprint 用 rootDir + content：保证"同 pack 同内容同 fp" + "不同 pack 偶然同内容不同 fp"
+
+import { createHash } from "node:crypto";
+import type { AssetPack, Blueprint, Profile, WorkingSet } from "../schema.js";
+
+// ==================== §4.2：parseRef ====================
+
+/** reserved pack 名 + 别名（§2.4.1 + §4.1 + §2.4.4 双层语义）。
+ *  v15.x §2.4.4：这些是"位置 alias"——固定指向 3 个物理位置 slot，与 manifest.name 身份层独立。
+ *  精确匹配：别名归一为短名（project → prj 等），非位置 alias 原样保留。 */
+const LOCATION_ALIASES: ReadonlyMap<string, string> = new Map([
+  ["prj", "prj"],
+  ["project", "prj"],
+  ["gbl", "gbl"],
+  ["global", "gbl"],
+  ["pt", "pt"],
+  ["builtin", "pt"],
+]);
+
+/** 解析 ref → {kind, pack, name}。双层语义（§2.4.4）：
+ *  - kind="location"：位置 alias（prj/gbl/pt + project/global/builtin）→ 按 pack name 物理位置查
+ *  - kind="identity"：身份 alias（manifest.name）→ 按 pack.name 身份查
+ *  不限定 ref 自动绑定 selfPack（kind="identity"）。
+ *  畸形输入抛异常（§4.5.1 运行时校验）。 */
+export function parseRef(
+  raw: string,
+  selfPack: string
+): { kind: "location" | "identity"; pack: string; name: string } {
+  if (raw.startsWith("@")) {
+    const rest = raw.slice(1);
+    const slashIdx = rest.indexOf("/");
+    if (slashIdx <= 0) {
+      throw new Error(`malformed @pack/name: "${raw}"（缺 / 或 pack 名为空）`);
+    }
+    const rawPack = rest.slice(0, slashIdx);
+    const name = rest.slice(slashIdx + 1);
+    if (!name) {
+      throw new Error(`malformed @pack/name: "${raw}"（asset 名为空）`);
+    }
+    const locAlias = LOCATION_ALIASES.get(rawPack);
+    if (locAlias) {
+      // 位置 alias：归一为短名（project → prj），kind=location
+      return { kind: "location", pack: locAlias, name };
+    }
+    // 身份 alias：原值（manifest.name 原样保留），kind=identity
+    return { kind: "identity", pack: rawPack, name };
+  }
+  // 不限定 ref：自动绑定 self.sourcePack——selfPack 是 manifest.name（身份），kind=identity
+  if (!selfPack) {
+    throw new Error(
+      `unqualified ref "${raw}" but profile has no sourcePack (load context missing)`
+    );
+  }
+  return { kind: "identity", pack: selfPack, name: raw };
+}
+
+/** 判断 raw 是否限定 ref（以 @ 开头）。诊断用。 */
+export function isQualifiedRef(raw: string): boolean {
+  return raw.startsWith("@");
+}
+
+/** 位置 alias 归一（project → prj 等）。非位置 alias 原样返回。
+ *  与 parseRef 的 kind="location" 分支语义一致——独立暴露便于诊断。 */
+export function normalizePackName(raw: string): string {
+  return LOCATION_ALIASES.get(raw) ?? raw;
+}
+
+// ==================== §4.6：resolveBlueprint ====================
+
+/** v15.x PR6（fix pt-parse-blueprint-warn-misleading）：跨 pack Blueprint 解析。
+ *  v15.x §4.4.2：workingSet 改为双索引 WorkingSet<Blueprint>——按 parseRef 的 kind 分发查询：
+ *    - kind="location"：查 location 索引（位置 alias 短名）
+ *    - kind="identity"：查 identity 索引（manifest.name）
+ *  - 限定 ref（@pack/name）：只在目标 pack 查；查不到返 undefined（精确语义）
+ *  - 不限定 ref（foo）：先在 self.sourcePack 查；查不到按 packNames 顺序 fallback
+ *  - 与 transpile 阶段（§4.6 back-compat）行为等价——parse 阶段不再单独报
+ *    "unknown Blueprint" warn（false positive），统一交给 compile 阶段 throw。
+ *
+ *  设计：parse 和 compile 共用同一份 fallback 逻辑，避免行为漂移。
+ *  packNames 顺序 = [project, ...settings.reverse(), global, builtin]，前者赢。
+ *  fallback 时跳过 selfPack（已查过），按声明顺序查后续 pack（查 identity 索引，因 packNames 都是 pack.name = manifest.name）。 */
+export function resolveBlueprint(
+  profile: { blueprint: string; sourcePack?: string },
+  blueprintWS: WorkingSet<Blueprint>,
+  packNames: readonly string[]
+): { pack: AssetPack; asset: Blueprint } | undefined {
+  if (!profile.blueprint) return undefined;
+  const { kind, pack, name } = parseRef(profile.blueprint, profile.sourcePack ?? "");
+  const ws = kind === "location" ? blueprintWS.location : blueprintWS.identity;
+  const direct = ws.get(`${pack}/${name}`);
+  if (direct) return direct;
+  // 不限定 ref + direct miss → fallback 查找其他 pack（按 packNames 顺序查 identity 索引）
+  if (!profile.blueprint.startsWith("@")) {
+    for (const fb of packNames) {
+      if (fb === pack) continue;
+      const entry = blueprintWS.identity.get(`${fb}/${name}`);
+      if (entry) return entry;
+    }
+  }
+  return undefined;
+}
+
+// ==================== §4.4.2：fingerprint ====================
+
+/** v15.x PR3（§4.4.2）：fingerprint = sha256(rootDir + content)。
+ *  - rootDir 不同 → fp 不同（避免不同 pack 偶然同内容被合并）
+ *  - content 不同 → fp 不同
+ *  用于 resolveAndDedupRefs 的 dedup by fp（后者覆盖前者）。 */
+export function fingerprint<T>(pack: AssetPack, asset: T): string {
+  const input = `${pack.rootDir}\n${stableStringify(asset)}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+
+/** 与 compile/agent-context.ts 同逻辑（PR3 不强制抽公共——YAGNI）。 */
+function stableStringify(obj: unknown): string {
+  if (obj === null || typeof obj !== "object") return JSON.stringify(obj);
+  if (Array.isArray(obj)) return `[${obj.map(stableStringify).join(",")}]`;
+  if (!isRecord(obj)) return JSON.stringify(obj);
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return !!x && typeof x === "object" && !Array.isArray(x);
+}
+
+// ==================== §4.4.2：resolveAndDedupRefs ====================
+
+/** v15.x §4.4.2（双层语义）：解析 refs + fingerprint dedup（后者覆盖前者）。
+ *  workingSet 改为 WorkingSet<T> 双索引——按 parseRef 的 kind 分发查询：
+ *    - kind="location"：查 location 索引（位置 alias 短名）
+ *    - kind="identity"：查 identity 索引（manifest.name）
+ *  fallback 查其他 pack 时查 identity 索引（packNames 是 manifest.name 列表）。
+ *
+ * 阶段 1：所有 ref 解析为 {pack, asset, fp, rawRef}（保留原顺序）
+ * 阶段 2：dedup by fp——Map.set 同 fp 后写覆盖前写 = 后者赢
+ *
+ * 返回值按首次插入顺序，值=最后写入的 ref（同 fp 后者赢）。
+ * 场景 A/B/C（同 fp）→ dedup 后 1 份；场景 D/E/F（不同 fp）→ 保留多份。
+ *
+ * 错误信息含 loadedPackNames 帮用户定位（§4.5.1）。 */
+export function resolveAndDedupRefs<T extends { name: string }>(
+  refs: string[],
+  self: Profile,
+  workingSet: WorkingSet<T>,
+  loadedPackNames: string[],
+  options: { skipOnMissing?: boolean } = {}
+): Array<{ pack: AssetPack; asset: T; fp: string; rawRef: string }> {
+  const resolved: Array<{ pack: AssetPack; asset: T; fp: string; rawRef: string }> = [];
+  for (const raw of refs) {
+    const { kind, pack: packName, name } = parseRef(raw, self.sourcePack ?? "");
+    const ws = kind === "location" ? workingSet.location : workingSet.identity;
+    let entry = ws.get(`${packName}/${name}`);
+    // v15.x PR3（§4.6 back-compat）：显式 @pack/name 查不到 → 抛错（§4.5.1）。
+    // 不限定 ref 在 selfPack 查不到时（§4.6 等价今天 dedupByNameN 语义）：
+    // 按 packs 优先级顺序逐个 fallback 查询（查 identity 索引，packNames 是 manifest.name 列表）。
+    // 例：profile 写在 project pack，不限定 `foo` → identity "pt-internal/foo" 不命中 → fallback "gbl/foo" → "pt/foo"。
+    if (!entry && !raw.startsWith("@")) {
+      for (const fallbackPack of loadedPackNames) {
+        if (fallbackPack === packName) continue;
+        const fallbackEntry = workingSet.identity.get(`${fallbackPack}/${name}`);
+        if (fallbackEntry) {
+          entry = fallbackEntry;
+          break;
+        }
+      }
+    }
+    if (!entry) {
+      // skipOnMissing：scan 场景用——静默跳过不存在的 ref（与 dedupByNameN 旧行为一致）
+      if (options.skipOnMissing) continue;
+      throw new Error(
+        `Profile "${self.name}" references "@${packName}/${name}" but pack "${packName}" has no asset "${name}". ` +
+          `Loaded packs: [${loadedPackNames.join(", ")}]`
+      );
+    }
+    const fp = fingerprint(entry.pack, entry.asset);
+    resolved.push({ pack: entry.pack, asset: entry.asset, fp, rawRef: raw });
+  }
+
+  const byFp = new Map<string, (typeof resolved)[0]>();
+  for (const r of resolved) {
+    byFp.set(r.fp, r); // 同 fp 后写覆盖前写 = 后者赢
+  }
+  return [...byFp.values()]; // 保留首次插入顺序
+}

package/src/parse/shared.ts

@@ -0,0 +1,331 @@
+// src/parse/shared.ts — 通用 MD 词法+语法（domain/blueprint/profile 共享）
+//
+// Phase 7.3：从原 src/parse/{parser,types}.ts 抽公共部分。
+//   - Domain/Blueprint/Profile adapter 都按 H2 段解析，H3 子项 → Item。
+//   - 共享 frontmatter 解析、H2 段切分、H3 项解析、scalar 值解析。
+//   - 共享 Asset/Section/Item 类型。
+//
+// Phase 9.3：v9 适配 — Channel 删除（Channel 留作未来 Connector），inferKind 用 frontmatter 字段。
+//   AssetKind 去除 "channel"——但保留 type 值以防历史资源解析时遗留错误。
+
+import { readFile } from "node:fs/promises";
+
+// ==================== 类型（OXN 中间表示，Pt 核心不见） ====================
+
+/** MD 资产内部 kind（v9 适配）。
+ *  - "domain"    : Content Domain（v7/v9 内容层）
+ *  - "blueprint" : Blueprint（v7 配置层 / v9 结构层）
+ *  - "profile"   : Profile（v9 配置层，新增）
+ *  - "term" / "workflow" / "glossary" : Domain type 标签（frontmatter.type，P9 删 stack 死类型后残留的历史枚举值）
+ *  - "scene" / "manual" : v6 Struct kind 兼容（v7 资产迁移期残留）
+ *
+ *  v9 删除了 "channel"（Channel 留作未来 Connector，本版本不实现）——不再出现在 kind 联合中。
+ *  如解析到历史资源带 channel 段，frontmatter.kind 可 指 配 "channel"（保留为字符串兜底）。 */
+export type AssetKind =
+  | "domain"
+  | "blueprint"
+  | "profile"
+  | "term"
+  | "workflow"
+  | "glossary"
+  | "scene"
+  | "manual"
+  // 兜底：v8 channel 历史资源可能含 frontmatter.kind: "channel"
+  | "channel";
+
+export interface Item {
+  /** H3 标题（如 "文章"、"select-topic"） */
+  name: string;
+  /** "- key: value" / "- key: [a, b]" / "- key: { ... }" 字段。
+   *  值可以是 string / string[] / 嵌套对象（YAML 子集）；consumer 用 typeof 收窄。 */
+  fields: Record<string, unknown>;
+}
+
+export interface Section {
+  /** "## Terms" 原文 */
+  heading: string;
+  /** 段内 markdown（含 H3 子项） */
+  raw: string;
+  /** H3 子项解析结果 */
+  items: Item[];
+}
+
+export interface Asset {
+  kind: AssetKind;
+  /** 文件名去后缀（v7/v8 例："project-dev.channel" / "pt-blueprint"） */
+  name: string;
+  frontmatter: Record<string, unknown>;
+  /** frontmatter 之后的 markdown */
+  body: string;
+  /** H2 段名（首字母大写）→ 段内容 */
+  sections: Record<string, Section>;
+}
+
+// ==================== 词法/语法（共享） ====================
+
+/** 读 asset 文件并解析 frontmatter + H2 段。 */
+export async function readAsset(path: string): Promise<Asset> {
+  const raw = await readFile(path, "utf8");
+  const { fm, body } = parseFrontmatter(raw);
+
+  // 从文件路径末尾推 name（无后缀）
+  const fileName = path.split("/").pop() ?? "";
+  const name = fileName.replace(/\.[^.]+$/, "");
+
+  // Phase term-P9.3：type 字段已删——kind 推断逻辑仅保留为兼容（无 caller 实际使用）。
+  //   资产加载走目录路由（src/parse/index.ts loadAllDomains / loadAllBlueprints / loadAllProfiles），
+  //   不依赖 readAsset 的 kind 字段。
+  const kind: AssetKind = "domain"; // 默认值——保留 AssetKind 联合类型以备未来扩展
+
+  const sectionsArr = splitSections(body);
+  const sections: Record<string, Section> = {};
+  for (const sec of sectionsArr) {
+    const key = sec.heading.replace(/^#+\s*/, "").trim();
+    sections[key] = { heading: sec.heading, raw: sec.raw, items: parseItems(sec.raw) };
+  }
+
+  return { kind, name, frontmatter: fm, body, sections };
+}
+
+/** 解析 frontmatter --- ... --- 块（简易：key: value / key: [a, b] / key: { ... }） */
+export function parseFrontmatter(text: string): {
+  fm: Record<string, unknown>;
+  body: string;
+} {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { fm: {}, body: text };
+  const fm: Record<string, unknown> = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z_][\w-]*)\s*:\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const val = kv[2].trim();
+    fm[key] = parseScalar(val);
+  }
+  return { fm, body: m[2] };
+}
+
+/** 解析 scalar 值：string / string[] / 嵌套对象（YAML 子集）。
+ *  嵌套值通过 parseScalar 递归解析，支持任意深度。 */
+function parseScalar(val: string): unknown {
+  if (!val) return "";
+  // [a, b]
+  const arrMatch = val.match(/^\[(.*)\]$/);
+  if (arrMatch) {
+    return arrMatch[1]
+      .split(",")
+      .map((s) => unquote(s.trim()))
+      .filter((s) => s !== "");
+  }
+  // { key: value, ... }  → 嵌套对象
+  if (/^\{.*\}$/.test(val.trim())) {
+    return parseInlineObject(val.trim());
+  }
+  return unquote(val);
+}
+
+function parseInlineObject(s: string): Record<string, unknown> {
+  const inner = s.slice(1, -1).trim();
+  if (!inner) return {};
+  const out: Record<string, unknown> = {};
+  for (const part of splitTopLevel(inner, ",")) {
+    const kv = part.match(/^\s*([a-zA-Z_][\w-]*)\s*:\s*(.+)$/);
+    if (kv) out[kv[1]] = parseScalar(kv[2].trim());
+  }
+  return out;
+}
+
+function splitTopLevel(s: string, sep: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let buf = "";
+  for (const ch of s) {
+    if (ch === "{" || ch === "[") depth++;
+    else if (ch === "}" || ch === "]") depth--;
+    if (ch === sep && depth === 0) {
+      out.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  if (buf.trim()) out.push(buf);
+  return out;
+}
+
+function unquote(s: string): string {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/** 按 `## ` 切 H2 段。H1 `# ` 不在此处理（asset 一般只有 1 个 H1 当标题） */
+export function splitSections(body: string): Array<{ heading: string; raw: string }> {
+  const lines = body.split(/\r?\n/);
+  const sections: Array<{ heading: string; raw: string }> = [];
+  let cur: { heading: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+)$/);
+    if (h2) {
+      if (cur) sections.push({ heading: cur.heading, raw: cur.lines.join("\n") });
+      cur = { heading: line.trim(), lines: [] };
+    } else if (cur) {
+      cur.lines.push(line);
+    }
+  }
+  if (cur) sections.push({ heading: cur.heading, raw: cur.lines.join("\n") });
+  return sections;
+}
+
+/** 把段内 markdown 解析成 Item[]：
+ *  - 有 H3 (`### name`) → 每个 H3 是一个 item，下属 `- key: value` 是 fields
+ *  - 无 H3，整段就是 list → 顶层 `- key: value` / `- name` 直接作为 items
+ *
+ *  顶层 list 支持两种行形态：
+ *    - `- key: value` → { name: "key", fields: { key: value } }
+ *    - `- name`       → { name: "name", fields: {} }（裸名列表，例 ## Modules 段）
+ */
+export function parseItems(sectionRaw: string): Item[] {
+  const lines = sectionRaw.split(/\r?\n/);
+  const hasH3 = lines.some((l) => /^###\s+/.test(l));
+
+  if (hasH3) {
+    const items: Item[] = [];
+    let cur: Item | null = null;
+    for (const line of lines) {
+      const h3 = line.match(/^###\s+(.+)$/);
+      if (h3) {
+        if (cur) items.push(cur);
+        cur = { name: h3[1].trim(), fields: {} };
+      } else if (cur) {
+        const fv = line.match(/^\s*-\s+([a-zA-Z_][\w-]*)\s*:\s*(.+)$/);
+        if (fv) cur.fields[fv[1]] = parseScalar(fv[2].trim());
+      }
+    }
+    if (cur) items.push(cur);
+    return items;
+  }
+
+  // 无 H3：顶层 list 直接当 items（支持 `- key: value` 和 `- name` 两种行）
+  const items: Item[] = [];
+  for (const line of lines) {
+    const fv = line.match(/^\s*-\s+([a-zA-Z_][\w-]*)\s*:\s*(.+)$/);
+    if (fv) {
+      items.push({
+        name: fv[1],
+        fields: { [fv[1]]: parseScalar(fv[2].trim()) },
+      });
+      continue;
+    }
+    const bare = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (bare) {
+      items.push({ name: bare[1].trim(), fields: {} });
+    }
+  }
+  return items;
+}
+
+// ==================== 字段取值辅助（共享） ====================
+
+/** 把 unknown 收窄为 string（数组则 join）。无值 → ""。 */
+export function s(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string").join(", ");
+  return "";
+}
+
+/** 把 unknown 收窄为 string[]（单值包成 1-数组）。无值 → []。 */
+export function sArr(v: unknown): string[] {
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
+  if (typeof v === "string" && v) return [v];
+  return [];
+}
+
+/** 从一个 H2 段里取某个字段的标量值（兼容裸值 / 顶层 list `- key: value` / H3 项 fields.key）。
+ *  用途：Blueprint 聚合组 H2 下读 inject/mode，Profile 聚合组 H2 下读 ### Domains 追加列表。 */
+export function extractFieldValue(section: Section | undefined, key: string): string {
+  if (!section) return "";
+
+  // 1. 顶层 list 行：`- inject: session`
+  for (const item of section.items) {
+    const v = item.fields[key];
+    if (v !== undefined) {
+      const sv = s(v);
+      if (sv) return sv;
+    }
+  }
+
+  // 2. 裸值段（## H2 后第一行非空文本）—— 取第一个匹配 `key: value` 的行
+  for (const line of section.raw.split(/\r?\n/)) {
+    const m = line.match(new RegExp(`^\\s*${key}\\s*:\\s*(.+?)\\s*$`));
+    if (m) {
+      return s(parseScalar(m[1].trim()));
+    }
+  }
+
+  return "";
+}
+
+/** 同 extractBareListUnderH3(section, "Modules") 的别名（Channel 用）。 */
+export function extractModulesList(section: Section | undefined): string[] {
+  return extractBareListUnderH3(section, "Modules");
+}
+
+/** 同 extractBareListUnderH3(section, "Domains") 的别名（Blueprint 用）。 */
+export function extractDomainsList(section: Section | undefined): string[] {
+  return extractBareListUnderH3(section, "Domains");
+}
+
+/** 从一个 H2 段下取指定 H3 名下的所有裸名列表项（`- name`）。
+ *  用途：Blueprint `## 会话背景` → `### Modules` 列 Domain Schema Name；
+ *        Profile `## 会话背景` → `### Domains` 列参与本聚合组的 Domain 名。
+ *
+ *  行为：扫描 section.raw，找到 `### <h3Name>` 行后收集紧随其后的 `- name` 行
+ *        （无 `key: value`），遇下一个 H3 或段尾终止。
+ *
+ *  兼容：若 H3 项的 fields.modules / fields.refs 是数组（旧写法），也支持。 */
+export function extractBareListUnderH3(section: Section | undefined, h3Name: string): string[] {
+  if (!section) return [];
+
+  // 兼容路径：若 fields 里有数组字段（旧写法 `### Modules` 下用 `- modules: [Scene]` 等）
+  const item = section.items.find((it) => it.name === h3Name);
+  if (item) {
+    const arr = item.fields.modules ?? item.fields.refs;
+    if (Array.isArray(arr)) {
+      const strs = arr.filter((x): x is string => typeof x === "string");
+      if (strs.length > 0) return strs;
+    }
+  }
+
+  // 主路径：扫 raw text 找 H3 + 后随的 `- name` 行
+  const lines = section.raw.split(/\r?\n/);
+  const out: string[] = [];
+  let inTarget = false;
+  for (const line of lines) {
+    const h3 = line.match(/^###\s+(.+)$/);
+    if (h3) {
+      const name = h3[1].trim();
+      inTarget = name === h3Name;
+      continue;
+    }
+    if (!inTarget) continue;
+    // 裸名行：`- Scene` / `- pt-architecture`（无冒号或冒号后无值）
+    const bare = line.match(/^\s*-\s+([^\s:]+)\s*$/);
+    if (bare) {
+      out.push(bare[1].trim());
+      continue;
+    }
+    // H4 段也终止（子嵌套不展开）
+    if (/^#+\s/.test(line)) break;
+  }
+  return out;
+}
+
+// Phase term-P9.5：删除 inferKind / inferKindFromFrontmatter 死代码。
+//   Type 字段删除（P9.3）+ Blueprint 转 YAML（P4.5）后，asset kind 推断链路（frontmatter
+//   type/agent + H2 Slots/Tools/Compilation 识别）全部失去作用——资产加载按目录路由
+//   （src/parse/index.ts loadAllDomains/Blueprints/Profiles），不依赖 readAsset 的 kind 字段。
+//   AssetKind 联合类型保留（供未来扩展），具体推断函数清理。
+//   Channel 已删除，Domain 走通用 term 形态。 */