@istuen/pt 0.1.0

package/dist/manual-track.js

@@ -0,0 +1,107 @@
+// src/manual-track.ts — pt Manual 实例追踪（纯函数内核）
+//
+// 配套 .pt/docs/designs/pt-injection-status-manual-track.md §2.4 / §2.5：
+//   - parseManualProgress：读文件 → 抽 frontmatter → 正则数 checklist
+//   - renderManualWidgetLines：3 行 string[] 给 setWidget 用
+//   - renderManualFooterSuffix：footer 后缀（"· manual: <procedure> 3/6"）
+//   - isManualActive：文件存在 + status !== completed
+//
+// 边界纪律：
+//   - manual 实例文件不是 Pt 资产（不是 Domain/Blueprint/Profile）→ 不进 parse/ 层
+//   - 进度（stepDone/stepTotal）不存 session——文件是 single source of truth
+//   - 不依赖 ExtensionAPI，可单测
+import { access, readFile } from "node:fs/promises";
+/** 从 manual 实例文件 parse 进度。失败返回 null（容错，不抛）。 */
+export async function parseManualProgress(filePath) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return parseManualProgressFromContent(content);
+    }
+    catch {
+        // 文件不存在 / 权限不足 / 读取失败
+        return null;
+    }
+}
+/** 内部：从字符串内容 parse（便于单测 & 未来内联输入）。
+ *  算法：
+ *   1. frontmatter：取首段 `---` ... `---` 之间的 YAML
+ *   2. procedure / status：从 frontmatter 行解析（`key: value` 形式，宽松）
+ *   3. checklist：全文正则 `/^- \[([ x])\]\s+(.+)$/gm` 数 done / total
+ *   4. nextStep：第一个未完成项的文本（去前缀） */
+export function parseManualProgressFromContent(content) {
+    const fm = extractFrontmatter(content);
+    const procedure = fm?.procedure ?? "(unknown)";
+    const status = fm?.status ?? "unknown";
+    let stepDone = 0;
+    let stepTotal = 0;
+    let nextStep = null;
+    // 多行匹配（m 标志），匹配行首 "- [x]" 或 "- [ ]"
+    const re = /^- \[([ x])\]\s+(.+)$/gm;
+    for (const m of content.matchAll(re)) {
+        const checked = m[1] === "x";
+        const text = m[2]?.trim() ?? "";
+        stepTotal++;
+        if (checked) {
+            stepDone++;
+        }
+        else if (nextStep === null && text) {
+            nextStep = text;
+        }
+    }
+    return { procedure, stepDone, stepTotal, status, nextStep };
+}
+function extractFrontmatter(content) {
+    const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!m?.[1])
+        return null;
+    const out = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([a-zA-Z_-]+)\s*:\s*(.*)$/);
+        if (!kv?.[1])
+            continue;
+        const key = kv[1];
+        const value = (kv[2] ?? "").trim();
+        if (key === "procedure")
+            out.procedure = value;
+        else if (key === "status")
+            out.status = value;
+    }
+    return out;
+}
+/** widget 渲染：3 行 string[]，给 `ui.setWidget("pt-manual", lines, { placement: "aboveEditor" })` 用。
+ *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`）
+ *  - 第 2 行：`  next: <nextStep 文本>`（无 nextStep 时该行省略）
+ *  - 第 3 行：`  file: <filePath>`
+ *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。 */
+export function renderManualWidgetLines(filePath, p) {
+    const statusText = p.status === "completed" ? "✓ done" : `(${p.status})`;
+    const lines = [];
+    lines.push(`pt ▶ ${p.procedure}  step ${p.stepDone}/${p.stepTotal}  ${statusText}`);
+    if (p.nextStep && p.status !== "completed") {
+        lines.push(`  next: ${p.nextStep}`);
+    }
+    lines.push(`  file: ${filePath}`);
+    return lines;
+}
+/** footer 后缀：有 activeManual 时追加。
+ *  - in-progress → `· manual: <procedure> <done>/<total>`
+ *  - completed   → `· manual: <procedure> done` */
+export function renderManualFooterSuffix(p) {
+    if (p.status === "completed") {
+        return `· manual: ${p.procedure} done`;
+    }
+    return `· manual: ${p.procedure} ${p.stepDone}/${p.stepTotal}`;
+}
+/** 文件存在 + status !== completed。配合 widget/footer 决定要不要展示。
+ *  - 用 fs.access 探测存在（轻量，不读全文）
+ *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐） */
+export async function isManualActive(filePath) {
+    try {
+        await access(filePath);
+    }
+    catch {
+        return false;
+    }
+    const p = await parseManualProgress(filePath);
+    return p !== null && p.status !== "completed";
+}

package/dist/parse/blueprint.d.ts

@@ -0,0 +1,5 @@
+import type { Blueprint } from "../schema.js";
+/** 读 blueprints/<fileName>.blueprint.yaml → Blueprint { name, groups }
+ *  v9.1（modules-to-profile 迁移）：BlueprintGroup 不再带 modules——modules 由 ProfileGroup
+ *  通过 H2 `### Modules` 段提供。YAML 中 modules 行（若有）被静默忽略，迁移期兼容。 */
+export declare function parseBlueprint(absDir: string, fileName: string): Promise<Blueprint>;

package/dist/parse/blueprint.js

@@ -0,0 +1,59 @@
+// 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";
+const VALID_MODES = ["byDomain", "byType", "hybrid"];
+/** 读 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, fileName) {
+    const filePath = join(absDir, fileName);
+    const raw = await readFile(filePath, "utf8");
+    const data = parseYaml(raw);
+    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 = 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 = {
+            name: ip.name,
+            inject: ip.inject,
+        };
+        if (ip.mode && isValidMode(ip.mode)) {
+            config.mode = ip.mode;
+        }
+        return config;
+    });
+    return { name: data.name, groups };
+}
+function isValidMode(x) {
+    return VALID_MODES.includes(x);
+}

package/dist/parse/domain-renderers.d.ts

@@ -0,0 +1,8 @@
+import { type Item } from "./shared.js";
+/** 单个 H2 段内容解析器。 */
+export type DomainSectionParser = (items: Item[], sectionRaw: string) => unknown;
+/** 加新 H2 段名 = 调 registerDomainSectionRenderer 加一行注册 + 一个 parser 函数。
+ *  Phase term-P9.3：删 type 参数。 */
+export declare function registerDomainSectionRenderer(h2Name: string, parser: DomainSectionParser): void;
+/** 取 H2段名 的 parser。未注册返 undefined（调用方走 fallback）。Phase term-P9.3：删 type 参数。 */
+export declare function getDomainSectionParser(h2Name: string): DomainSectionParser | undefined;

package/dist/parse/domain-renderers.js

@@ -0,0 +1,115 @@
+// 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 } from "./shared.js";
+/** 注册表：H2段名 → parser。Phase term-P9.3：删 type 维度。 */
+const domainSectionRenderers = {
+    // 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: 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 = {
+            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, parser) {
+    domainSectionRenderers[h2Name] = parser;
+}
+/** 取 H2段名 的 parser。未注册返 undefined（调用方走 fallback）。Phase term-P9.3：删 type 参数。 */
+export function getDomainSectionParser(h2Name) {
+    return domainSectionRenderers[h2Name];
+}
+// ==================== shared 辅助 ====================
+function collectSteps(itemName, sectionRaw) {
+    const lines = sectionRaw.split(/\r?\n/);
+    const steps = [];
+    let inItem = false;
+    let cur = 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/dist/parse/domain.d.ts

@@ -0,0 +1,7 @@
+import type { Domain } from "../schema.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 declare function parseDomain(absDir: string, relPath: string): Promise<Domain>;

package/dist/parse/domain.js

@@ -0,0 +1,69 @@
+// 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 { readAsset, s } 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, relPath) {
+    const asset = await readAsset(join(absDir, relPath));
+    // H2 段名 → 段内容的解析：调注册表 parser，未注册走 fallback (Term[])
+    const modules = {};
+    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) {
+    return relPath.split(/[\\/]/).join("/").replace(/\.md$/, "");
+}
+/** 调注册表 parser（h2Name）解析单个 H2 段。Phase term-P9.3：删 type 参数，二维注册表降一维。
+ *  未注册走 default fallback：term 形态（Term[]）——新 H2 段名加 fallback 即可。 */
+function parseDomainSection(h2Name, items, sectionRaw) {
+    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) {
+    return items.map((it) => ({
+        name: it.name,
+        desc: s(it.fields.desc) || s(it.fields.description),
+    }));
+}

package/dist/parse/index.d.ts

@@ -0,0 +1,9 @@
+import type { SourceAdapter } from "../schema.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 declare const mdAdapter: SourceAdapter;
+export { parseBlueprint, parseDomain, parseProfile };

package/dist/parse/index.js

@@ -0,0 +1,223 @@
+// 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 { 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 = {
+    name: "md",
+    async load(cwd, profileName, adapterCtx) {
+        // 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 = [
+            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 = new Map([
+            ["project", "prj"],
+            ["global", "gbl"],
+            ["builtin", "pt"],
+        ]);
+        const domainLocWS = new Map();
+        const domainIdWS = new Map();
+        const blueprintLocWS = new Map();
+        const blueprintIdWS = new Map();
+        const profileLocWS = new Map();
+        const profileIdWS = new Map();
+        const packProfiles = [];
+        const allDomains = [];
+        const allBlueprints = [];
+        const allProfiles = [];
+        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;
+        let activeProfileOrigin = "exact";
+        let originalProfileName;
+        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, packProfiles, profileRef) {
+    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, packProfiles, profileName) {
+    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, adapterCtx) {
+    const seen = new Map();
+    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 };

package/dist/parse/profile.d.ts

@@ -0,0 +1,18 @@
+import type { ModName, Profile } from "../schema.js";
+import type { SourceAdapterContext } from "../schema.js";
+/** 已知 H2 段名（段名 = 命名空间）。modName 解析时左段必须是段名。
+ *  扩展新段名 = 加这一行 + registerModuleRenderer 加一行 + 一致性测试。
+ *  v9.1+（modules-to-profile-complete）：加 "User" / "Agent" 专用段（user-info / agent-info 重命名）。
+ *  公开导出（src/asset-health.ts 复用做 unknown-modname 检测——避免重复常量）。 */
+export declare const KNOWN_SECTION_NAMES: ReadonlySet<string>;
+/** 解析 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 declare function parseModName(raw: string): ModName | 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 declare function parseProfile(absDir: string, fileName: string, adapterCtx?: SourceAdapterContext): Promise<Profile>;