@istuen/pt 0.1.0

package/dist/agent/registry.js

@@ -0,0 +1,40 @@
+// src/agent/registry.ts — AgentAdapter 注册表
+//
+// Phase 9.6：v9 新增 — 按 Agent 名取 Adapter 实例。
+// 加新 Agent（如 Codex / OpenCode）只在这里加一行注册 + 实现 Adapter。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 原设计 `agentAdapters: Record<string, AgentAdapter>` 是 module-level 单例
+//     → 所有 session 共享同一个 PiAdapter 实例 → 单例 `this.segment / this.ctx /
+//       this.blueprint / this.domains / this.injectedApi` 跨 session 被覆盖
+//     → tab B 调 setContext 覆盖 this.segment → tab A 的 before_agent_start handler
+//       读到 tab B 的 segment → LLM 拿到错业务上下文（业务上下文级污染）
+//   - 改造为 `WeakMap<ExtensionAPI, Record<string, AgentAdapter>>`：
+//     - 每 session 一份 `Record<name, Adapter>` 缓存
+//     - pi 实例销毁时（pi-web session 退出）WeakMap 自动 GC
+//     - TUI 模式只有一个 pi 实例，行为等同 module-level 单例
+//   - getAgentAdapter 签名改成 `(pi, name)`：调用方传 pi 作 key
+//     - `src/index.ts:105` `transpileActive` 改 `getAgentAdapter(pi, ...)`
+//     - `src/index.ts:70-77` `registerInjectionIfReady` 调 `adapter.registerInject(...)`
+//       时拿到的 adapter 已是 per-pi 实例，handler 闭包持 this（per-pi），this.segment
+//       不被其他 session 覆盖
+import { PiAdapter } from "./pi-adapter.js";
+/** v12.x：per-pi Adapter 缓存（弱引用，pi 实例销毁后自动 GC）。 */
+const adapterCache = new WeakMap();
+/** 取指定 pi + name 的 AgentAdapter。未找到返 pi 的 per-pi 实例（fallback）。 */
+export function getAgentAdapter(pi, name) {
+    let cache = adapterCache.get(pi);
+    if (!cache) {
+        cache = {};
+        adapterCache.set(pi, cache);
+    }
+    let adapter = cache[name];
+    if (!adapter) {
+        // 当前只支持 pi；未来 codex/opencode 在这里 switch name
+        adapter = new PiAdapter();
+        cache[name] = adapter;
+        if (!cache.pi)
+            cache.pi = adapter; // 把 fallback 也指到同一实例
+    }
+    return adapter;
+}

package/dist/asset-health.d.ts

@@ -0,0 +1,50 @@
+import type { AssetPack } from "./schema.js";
+import type { Blueprint, Domain, Profile, SourceAdapterContext } from "./schema.js";
+/** 问题严重程度。error 必须修；warning 可延后。 */
+export type IssueSeverity = "error" | "warning";
+/** 问题归属：profile / blueprint / domain。本 issue v1 范围只产 profile 类。 */
+export type IssueScope = "profile" | "blueprint" | "domain";
+/** 单条问题。issue-doc-structure 类似——结构化便于测试断言 + UI 格式化 + 自动 fix。 */
+export interface AssetHealthIssue {
+    severity: IssueSeverity;
+    scope: IssueScope;
+    /** 问题所在资产名（profile.name / blueprint.name / domain.name）。 */
+    name: string;
+    /** 可选字段路径（如 "groups.会话背景.modules"），便于精确指向。 */
+    field?: string;
+    /** 人类可读问题描述。 */
+    msg: string;
+    /** 修复建议（hint）。 */
+    hint?: string;
+    /** 自动 fix 命令（v2 `--fix` 用，本 issue v1 不实现执行）。 */
+    fix?: string;
+}
+/** 规则 id。issue §Layer 2 5 条规则 → 5 个 id。 */
+export type HealthRuleId = "missing-modules" | "dangling-blueprint-ref" | "orphan-h2" | "empty-segment" | "unknown-modname";
+/** 资产健康扫描结果（按 profile 聚合）。 */
+export interface AssetHealthReport {
+    issues: AssetHealthIssue[];
+    errors: number;
+    warnings: number;
+}
+/** 扫描整个项目的资产配置（issue §Layer 2 主入口）。
+ *
+ * 检测 5 类反模式：
+ *   1. missing-modules        ProfileGroup.modules 为空
+ *   2. dangling-blueprint-ref profile.blueprint 不存在
+ *   3. orphan-h2              ProfileGroup.name 不在 Blueprint.groups
+ *   4. empty-segment          compileAgentContext 产出为空段
+ *   5. unknown-modname        `### Modules` 项不在 KNOWN_SECTION_NAMES（需重读文件）
+ *
+ * 参数：
+ *   - cwd：项目根目录（unknown-modname 重读 profile 文件需要）
+ *   - profiles / blueprints / domains：从 SchemaBundle 取的全集
+ *   - adapterCtx：可选。log writer 用于 trace（warn 不走 notify——会刷屏）
+ *
+ * 调用方：session_start / /pt check / pt_check tool。
+ *
+ * 不抛错——任何内层异常降级为 log warn + 不阻止结果。体检失败不该阻塞 session 启动。
+ */
+export declare function scanProjectHealth(cwd: string, profiles: Profile[], blueprints: Blueprint[], domains: Domain[], packs: AssetPack[], // v15.x PR2：compileAgentContext 需要 packs 进 sourceHash
+profilePack: string, // v15.x PR2：scan 时用 default "prj"——不真正读 pack 信息
+adapterCtx?: SourceAdapterContext): Promise<AssetHealthReport>;

package/dist/asset-health.js

@@ -0,0 +1,267 @@
+// src/asset-health.ts — 资产配置体检（issue pt-asset-migration-visibility Layer 2）
+//
+// 设计动机：存量项目升级 Pt 后无迁移可见性。
+//   - v9.1 modules-to-profile 迁移后，旧 profile 缺 `### Modules` → 空 segment
+//   - 单 profile 运行时检测（issue pt-status-no-injection-state 修复 2/3）只在切换时触发
+//   - session_start 批量体检：主动告知"项目有 N 个配置问题"，不踩坑
+//
+// 5 条规则（issue §Layer 2 表）：
+//   1. missing-modules        (error)   ProfileGroup.modules 为空
+//   2. dangling-blueprint-ref (error)   profile.blueprint 不存在
+//   3. orphan-h2              (warning) ProfileGroup.name 不在 Blueprint.groups
+//   4. empty-segment          (error)   compileAgentContext 产出为空段
+//   5. unknown-modname        (warning) `### Modules` 项不在 KNOWN_SECTION_NAMES
+//
+// 边界纪律：
+//   - 不替代运行时检测（transpile 内的 reportWarn）——两层互补：运行时按 profile 切，scan 按全集
+//   - 不写资产——只检测 + 报告；修复走 `/pt check --fix`（v2 范围，本 issue 不实现）
+//   - 不引入新依赖——只用 node:fs/promises + 已有 compile 层
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { compileAgentContext } from "./compile/agent-context.js";
+import { PROFILES_DIR } from "./constants.js";
+import { KNOWN_SECTION_NAMES } from "./parse/profile.js";
+// ==================== 主入口 ====================
+/** 扫描整个项目的资产配置（issue §Layer 2 主入口）。
+ *
+ * 检测 5 类反模式：
+ *   1. missing-modules        ProfileGroup.modules 为空
+ *   2. dangling-blueprint-ref profile.blueprint 不存在
+ *   3. orphan-h2              ProfileGroup.name 不在 Blueprint.groups
+ *   4. empty-segment          compileAgentContext 产出为空段
+ *   5. unknown-modname        `### Modules` 项不在 KNOWN_SECTION_NAMES（需重读文件）
+ *
+ * 参数：
+ *   - cwd：项目根目录（unknown-modname 重读 profile 文件需要）
+ *   - profiles / blueprints / domains：从 SchemaBundle 取的全集
+ *   - adapterCtx：可选。log writer 用于 trace（warn 不走 notify——会刷屏）
+ *
+ * 调用方：session_start / /pt check / pt_check tool。
+ *
+ * 不抛错——任何内层异常降级为 log warn + 不阻止结果。体检失败不该阻塞 session 启动。
+ */
+export async function scanProjectHealth(cwd, profiles, blueprints, domains, packs, // v15.x PR2：compileAgentContext 需要 packs 进 sourceHash
+profilePack, // v15.x PR2：scan 时用 default "prj"——不真正读 pack 信息
+adapterCtx) {
+    const issues = [];
+    const blueprintNames = new Set(blueprints.map((b) => b.name));
+    const _domainByName = new Map(domains.map((d) => [d.name, d]));
+    // ===== IR-only 规则（1-3）=====
+    for (const profile of profiles) {
+        // 2. dangling-blueprint-ref
+        if (!blueprintNames.has(profile.blueprint)) {
+            issues.push({
+                severity: "error",
+                scope: "profile",
+                name: profile.name,
+                field: "blueprint",
+                msg: `Profile「${profile.name}」引用 Blueprint「${profile.blueprint}」不存在`,
+                hint: `检查拼写 / 项目 .pt/assets/blueprints/ 是否漏文件 / 备选内建 blueprint`,
+            });
+            continue; // 无 Blueprint 引用，下面的 group 检查无意义
+        }
+        const blueprint = blueprints.find((b) => b.name === profile.blueprint);
+        if (!blueprint)
+            continue; // 上一步已 guard（type guard 收窄需要）
+        const bpGroupNames = new Set(blueprint.groups.map((g) => g.name));
+        for (const group of profile.groups) {
+            // 3. orphan-h2
+            if (!bpGroupNames.has(group.name)) {
+                issues.push({
+                    severity: "warning",
+                    scope: "profile",
+                    name: profile.name,
+                    field: `groups.${group.name}`,
+                    msg: `Profile「${profile.name}」的 H2「${group.name}」不在 Blueprint「${blueprint.name}」聚合组中`,
+                    hint: `删除该 H2，或加到 Blueprint ${blueprint.name} 的 groups 项`,
+                });
+            }
+            // 1. missing-modules
+            if (group.modules.length === 0) {
+                issues.push({
+                    severity: "error",
+                    scope: "profile",
+                    name: profile.name,
+                    field: `groups.${group.name}.modules`,
+                    msg: `Profile「${profile.name}」聚合组「${group.name}」缺 ### Modules`,
+                    hint: `在 H2 段下加 \`### Modules\` 列出 modName（段名 Scene/Trigger/Rules/Flows/Checklists/User/Agent 等）`,
+                    fix: `/pt check --fix ${profile.name}`,
+                });
+            }
+        }
+    }
+    // 4. empty-segment：对每个 profile 跑 compileAgentContext 检查产物
+    //   - compile 失败已通过 agent-context.ts 的 reportWarn 报告；scan 跳过避免重复
+    //   - 缺 Blueprint 引用已在 dangling-blueprint-ref 报过，跳过
+    for (const profile of profiles) {
+        const blueprint = blueprints.find((b) => b.name === profile.blueprint);
+        if (!blueprint)
+            continue;
+        try {
+            // v15.x PR3：scanProjectHealth 内部构造 working set（从 profiles/blueprints/domains + packs）
+            // scan 默认把 domain/blueprint 归到 prj pack，模拟项目 pack 加载行为。
+            // packs 为空时（如测试场景）用 profilePack 作 fallback key，配 mock AssetPack
+            const effectivePackName = profilePack || "prj";
+            const targetPack = packs.find((p) => p.source === "project") ??
+                packs[0] ?? {
+                name: effectivePackName,
+                version: "0.0.0",
+                rootDir: "/test",
+                source: "project",
+                loadDomains: () => Promise.resolve([]),
+                loadBlueprints: () => Promise.resolve([]),
+                loadProfiles: () => Promise.resolve([]),
+            };
+            // v15.x §4.4.2：scan 临时构造双索引 workingSet——location（按位置 alias）+ identity（按 pack.name）
+            // scan 场景 targetPack 是 project source → locAlias = "prj"
+            const domainLocWS = new Map();
+            const domainIdWS = new Map();
+            for (const d of domains) {
+                domainIdWS.set(`${targetPack.name}/${d.name}`, { pack: targetPack, asset: d });
+                domainLocWS.set(`prj/${d.name}`, { pack: targetPack, asset: d });
+            }
+            const blueprintLocWS = new Map();
+            const blueprintIdWS = new Map();
+            for (const b of blueprints) {
+                blueprintIdWS.set(`${targetPack.name}/${b.name}`, { pack: targetPack, asset: b });
+                blueprintLocWS.set(`prj/${b.name}`, { pack: targetPack, asset: b });
+            }
+            // scan 临时给 profile 打 sourcePack（如未设）——不修改原 profile（仅本调用范围）
+            const profileForCompile = profile.sourcePack
+                ? profile
+                : { ...profile, sourcePack: effectivePackName };
+            const ctx = compileAgentContext(profileForCompile, blueprint, domains, packs, profilePack, {
+                domains: { location: domainLocWS, identity: domainIdWS },
+                blueprints: { location: blueprintLocWS, identity: blueprintIdWS },
+                profiles: { location: new Map(), identity: new Map() },
+            });
+            const totalLen = Object.values(ctx.modules).reduce((acc, s) => acc + s.length, 0);
+            if (totalLen === 0) {
+                issues.push({
+                    severity: "error",
+                    scope: "profile",
+                    name: profile.name,
+                    msg: `Profile「${profile.name}」编译产出全聚合组空字符串`,
+                    hint: `检查 Profile 的 \`### Modules\` 配置、Blueprint groups 名匹配、Domain H2 段名`,
+                });
+            }
+        }
+        catch (e) {
+            adapterCtx?.log?.debug("scanProjectHealth:compile failed", {
+                profile: profile.name,
+                err: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    // 5. unknown-modname：重读 profile 文件的 `### Modules` 原始行 vs KNOWN_SECTION_NAMES
+    //   原因：parseProfile 已过滤失败 modname（reportWarn 一次）。scan 重读可检测存量项目
+    //   未切过的 profile，避免"切一个 warn 一个"的渐进发现。
+    for (const profile of profiles) {
+        try {
+            const rawMods = await readRawModNames(cwd, profile);
+            for (const raw of rawMods) {
+                if (!isKnownModName(raw)) {
+                    issues.push({
+                        severity: "warning",
+                        scope: "profile",
+                        name: profile.name,
+                        field: "groups.*.modules",
+                        msg: `Profile「${profile.name}」的 modName「${raw}」段名不在已知集合`,
+                        hint: `检查段名拼写 / KNOWN_SECTION_NAMES：Scene/Trigger/Rules/Flows/Checklists/User/Agent/Participant/Term`,
+                    });
+                }
+            }
+        }
+        catch (e) {
+            adapterCtx?.log?.debug("scanProjectHealth:readRawModNames failed", {
+                profile: profile.name,
+                err: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+    adapterCtx?.log?.info("scanProjectHealth:done", {
+        profileCount: profiles.length,
+        issueCount: issues.length,
+        errors,
+        warnings,
+    });
+    return { issues, errors, warnings };
+}
+// ==================== unknown-modname 规则辅助 ====================
+/** 重读 profile 文件的 `### Modules` 段原始 modname 列表（unknown-modname 规则专用）。
+ *  builtin profile / 文件不存在 → 返空数组（不报错）。 */
+async function readRawModNames(cwd, profile) {
+    const file = join(cwd, PROFILES_DIR, `${profile.name}.profile.md`);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        return []; // 文件不存在（builtin profile）跳过
+    }
+    // 简易 section 切分（不复用 parse/shared 的 splitSections——避免 import 链路拖长）
+    const sections = splitSectionsLight(raw);
+    const out = [];
+    for (const sec of sections) {
+        out.push(...extractModulesListFromRaw(sec));
+    }
+    return out;
+}
+/** 按 `## ` 切 H2 段（不计 H1）。空段过滤。 */
+function splitSectionsLight(body) {
+    const lines = body.split(/\r?\n/);
+    const out = [];
+    let cur = null;
+    for (const line of lines) {
+        const h2 = line.match(/^##\s+(.+)$/);
+        if (h2) {
+            if (cur)
+                out.push(cur.join("\n"));
+            cur = [];
+        }
+        if (cur)
+            cur.push(line);
+    }
+    if (cur)
+        out.push(cur.join("\n"));
+    return out;
+}
+/** 从段文本取 `### Modules` 下的 `- xxx` 行（裸名，不含 "key: value"）。 */
+function extractModulesListFromRaw(sectionRaw) {
+    const lines = sectionRaw.split(/\r?\n/);
+    const out = [];
+    let inModules = false;
+    for (const line of lines) {
+        const h3 = line.match(/^###\s+(.+)$/);
+        if (h3) {
+            inModules = h3[1].trim() === "Modules";
+            continue;
+        }
+        if (!inModules)
+            continue;
+        const bare = line.match(/^\s*-\s+([^\s:]+)\s*$/);
+        if (bare) {
+            out.push(bare[1].trim());
+            continue;
+        }
+        // H4 段也终止（子嵌套不展开）
+        if (/^#+\s/.test(line))
+            break;
+    }
+    return out;
+}
+/** 判断 modName 字符串是否合法（KNOWN_SECTION_NAMES 段名 + 可选 段.项）。 */
+function isKnownModName(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed.includes(".")) {
+        const dotIdx = trimmed.indexOf(".");
+        const section = trimmed.slice(0, dotIdx);
+        const item = trimmed.slice(dotIdx + 1);
+        return KNOWN_SECTION_NAMES.has(section) && item.length > 0;
+    }
+    return KNOWN_SECTION_NAMES.has(trimmed);
+}

package/dist/asset-pack/loader.d.ts

@@ -0,0 +1,47 @@
+import type { AssetPack, PackSource, SourceAdapterContext } from "../schema.js";
+/** v15.x PR4（§6.2）：路径解析——支持 ~ / 绝对 / 相对 cwd。
+ *  ~ 开头 → home dir（join 后自然处理 ~user/foo / ~/foo / ~foo）；绝对路径原样；相对路径 resolve(cwd, raw)。 */
+export declare function resolvePackPath(raw: string, cwd: string): string;
+/** 全局 Pack 默认路径（§6.4）。优先级：adapterCtx.globalPackDir > env > 默认 ~/.pt/assets。
+ *  返回值永远是绝对路径或可被 resolve 的相对路径。 */
+export declare function getGlobalPackDir(adapterCtx?: SourceAdapterContext): string;
+/**
+ * 尝试加载 pack：目录不存在返空 Pack（不报错，§6.4）。
+ * v15.x §2.4.2 双层语义：所有 pack 都走 MdFilePack.create 读 manifest，
+ * reserved pack 无 manifest 时 name 退化到位置别名（back-compat）。
+ *
+ * 不预加载——目录不存在时 loadDomains() 等返空数组，与"空 Pack"等价。
+ * 这样调用方可以无差别调 loadXxx，不用关心目录是否存在。
+ *
+ * PR2：构造从 sync 改 async——走 MdFilePack.create 读 manifest。
+ * adapterCtx 透传给 MdFilePack：parse 失败时调 reportError 上抛（PR1 补丁 S2）。
+ */
+export declare function tryLoadPack(rootDir: string, source: PackSource, adapterCtx?: SourceAdapterContext): Promise<AssetPack>;
+/** 构造 project pack（§6.5：路径可配，默认 .pt/assets）。
+ *  v15.x PR4：优先读 settings 的 pt.project-pack-dir，fallback adapterCtx.assetDir / ASSETS_DIR。
+ *  project pack 身份由 manifest.name 决定（无 manifest 时退化到 "prj"，back-compat）。
+ *  指向项目外路径合法（../shared / 绝对），文档提示慎用。 */
+export declare function loadProjectPack(cwd: string, adapterCtx?: SourceAdapterContext): Promise<AssetPack>;
+/** 构造 global pack（§6.4）：无 manifest 时退化到 "gbl"（back-compat）。 */
+export declare function loadGlobalPack(adapterCtx?: SourceAdapterContext): Promise<AssetPack>;
+/** 构造 builtin pack（src/builtin/assets/，随 npm 包发布）：无 manifest 时退化到 "pt"。 */
+export declare function loadBuiltinPack(adapterCtx?: SourceAdapterContext): Promise<AssetPack>;
+/** v15.x PR4（§6.1 + §6.3）：settings pack 加载。
+ *  读 .pi/settings.json 的 pt.asset-packs[]（只 path 字段，§6.2 单一事实源），构造 AssetPack[]。
+ *  - pack name 从 manifest 读（MdFilePack.create 内部走 §2.4.2 逻辑）
+ *  - 路径解析 resolvePackPath（~ / 绝对 / 相对 cwd）
+ *  - path 无效 / 目录不存在 / parse 失败 → 跳过该 pack（§6.7.5 不阻断）
+ *  - 返回顺序 = settings 声明顺序（mdAdapter.load 负责 .reverse() 实现后者赢）
+ *  - settings pack 无 manifest 时 name=basename 兜底（非 reserved，走 §2.4.2 路径 3） */
+export declare function loadSettingsPacks(cwd: string): Promise<AssetPack[]>;
+/**
+ * 调试 / 测试用：判断给定路径是否"看起来像 Pack"——是目录 + 至少含一个 asset 子目录。
+ * PR1 阶段主要用于测试断言，prod 路径不调。
+ */
+export declare function looksLikePackDir(rootDir: string): boolean;
+/**
+ * v15.x PR1（§6.7.3）：project pack 降级时强制覆盖 profileName 为 "guide"。
+ * 抽为 pure helper 便于单元测试——transpileActive 调一下，逻辑集中。
+ * back-compat：degraded=false 或 requested="guide" 时返 requested 原值。
+ */
+export declare function applyProjectPackDegrade(projectPackDegraded: boolean, requested: string): string;

package/dist/asset-pack/loader.js

@@ -0,0 +1,121 @@
+// src/asset-pack/loader.ts — Pack 构造工厂（v15.x PR1）
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §3.1（加载顺序）/ §6.4（全局 Pack）/ §6.5（project-pack-dir）
+//
+// 职责：把"目录路径 + 来源类型"封装成 AssetPack 实例（PR1 走 MdFilePack）。
+// mdAdapter.load 调用这些函数构造 4 类 pack 数组。
+//
+// PR1 范围：
+//   - reserved pack（project/global/builtin）name 固定（"prj"/"gbl"/"pt"）——跳过 basename
+//   - project pack 路径走 adapterCtx.assetDir / 默认 ASSETS_DIR（PR4 接通 pt.project-pack-dir 后改读 settings）
+//   - global pack 路径走 adapterCtx.globalPackDir / env / 默认 ~/.pt/assets
+//   - settings pack 加载 stub：loadSettingsPacks() 返空数组（PR4 接通 .pi/settings.json pt.asset-packs）
+//   - directory 不存在不报错——tryLoadPack 内部不预加载，loadXxx 返空数组（"空 Pack" 等价）
+//
+// 不做的：manifest 解析（PR2）、@pack/name 限定语法（PR3）、settings 加载（PR4）。
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { ASSETS_DIR, BUILTIN_ASSETS_DIR } from "../constants.js";
+import { readProjectSetting } from "../config.js";
+import { MdFilePack } from "./md-file-pack.js";
+/** v15.x PR4（§6.2）：路径解析——支持 ~ / 绝对 / 相对 cwd。
+ *  ~ 开头 → home dir（join 后自然处理 ~user/foo / ~/foo / ~foo）；绝对路径原样；相对路径 resolve(cwd, raw)。 */
+export function resolvePackPath(raw, cwd) {
+    if (raw.startsWith("~")) {
+        return join(homedir(), raw.slice(1));
+    }
+    if (isAbsolute(raw)) {
+        return raw;
+    }
+    return resolve(cwd, raw);
+}
+/** 全局 Pack 默认路径（§6.4）。优先级：adapterCtx.globalPackDir > env > 默认 ~/.pt/assets。
+ *  返回值永远是绝对路径或可被 resolve 的相对路径。 */
+export function getGlobalPackDir(adapterCtx) {
+    return (adapterCtx?.globalPackDir ?? process.env.PT_GLOBAL_PACK_DIR ?? join(homedir(), ".pt", "assets"));
+}
+/**
+ * 尝试加载 pack：目录不存在返空 Pack（不报错，§6.4）。
+ * v15.x §2.4.2 双层语义：所有 pack 都走 MdFilePack.create 读 manifest，
+ * reserved pack 无 manifest 时 name 退化到位置别名（back-compat）。
+ *
+ * 不预加载——目录不存在时 loadDomains() 等返空数组，与"空 Pack"等价。
+ * 这样调用方可以无差别调 loadXxx，不用关心目录是否存在。
+ *
+ * PR2：构造从 sync 改 async——走 MdFilePack.create 读 manifest。
+ * adapterCtx 透传给 MdFilePack：parse 失败时调 reportError 上抛（PR1 补丁 S2）。
+ */
+export async function tryLoadPack(rootDir, source, adapterCtx) {
+    return MdFilePack.create({ rootDir, source, adapterCtx });
+}
+/** 构造 project pack（§6.5：路径可配，默认 .pt/assets）。
+ *  v15.x PR4：优先读 settings 的 pt.project-pack-dir，fallback adapterCtx.assetDir / ASSETS_DIR。
+ *  project pack 身份由 manifest.name 决定（无 manifest 时退化到 "prj"，back-compat）。
+ *  指向项目外路径合法（../shared / 绝对），文档提示慎用。 */
+export async function loadProjectPack(cwd, adapterCtx) {
+    // 优先级：pt.project-pack-dir > adapterCtx.assetDir > ASSETS_DIR（默认 .pt/assets）
+    const configured = await readProjectSetting(cwd, "pt.project-pack-dir");
+    const rawDir = configured ?? adapterCtx?.assetDir ?? ASSETS_DIR;
+    const dir = resolvePackPath(rawDir, cwd);
+    return tryLoadPack(dir, "project", adapterCtx);
+}
+/** 构造 global pack（§6.4）：无 manifest 时退化到 "gbl"（back-compat）。 */
+export async function loadGlobalPack(adapterCtx) {
+    return tryLoadPack(getGlobalPackDir(adapterCtx), "global", adapterCtx);
+}
+/** 构造 builtin pack（src/builtin/assets/，随 npm 包发布）：无 manifest 时退化到 "pt"。 */
+export async function loadBuiltinPack(adapterCtx) {
+    return tryLoadPack(BUILTIN_ASSETS_DIR, "builtin", adapterCtx);
+}
+/** v15.x PR4（§6.1 + §6.3）：settings pack 加载。
+ *  读 .pi/settings.json 的 pt.asset-packs[]（只 path 字段，§6.2 单一事实源），构造 AssetPack[]。
+ *  - pack name 从 manifest 读（MdFilePack.create 内部走 §2.4.2 逻辑）
+ *  - 路径解析 resolvePackPath（~ / 绝对 / 相对 cwd）
+ *  - path 无效 / 目录不存在 / parse 失败 → 跳过该 pack（§6.7.5 不阻断）
+ *  - 返回顺序 = settings 声明顺序（mdAdapter.load 负责 .reverse() 实现后者赢）
+ *  - settings pack 无 manifest 时 name=basename 兜底（非 reserved，走 §2.4.2 路径 3） */
+export async function loadSettingsPacks(cwd) {
+    const entries = await readProjectSetting(cwd, "pt.asset-packs");
+    if (!Array.isArray(entries) || entries.length === 0) {
+        return [];
+    }
+    const packs = [];
+    for (const entry of entries) {
+        // 只 path 字段——name 从 manifest 读（§6.2 单一事实源）
+        if (!entry || typeof entry.path !== "string" || !entry.path.trim()) {
+            // 无效条目跳过（loader 不调 ui，预警由 session_start 的 validatePack 兜底）
+            continue;
+        }
+        const rootDir = resolvePackPath(entry.path.trim(), cwd);
+        try {
+            const pack = await tryLoadPack(rootDir, "settings");
+            packs.push(pack);
+        }
+        catch {
+            // MdFilePack.create 内部已容错，catch 仅防御意外抛错——不阻断其他 pack
+        }
+    }
+    return packs;
+}
+/**
+ * 调试 / 测试用：判断给定路径是否"看起来像 Pack"——是目录 + 至少含一个 asset 子目录。
+ * PR1 阶段主要用于测试断言，prod 路径不调。
+ */
+export function looksLikePackDir(rootDir) {
+    if (!existsSync(rootDir))
+        return false;
+    return (existsSync(join(rootDir, "domains")) ||
+        existsSync(join(rootDir, "blueprints")) ||
+        existsSync(join(rootDir, "profiles")));
+}
+/**
+ * v15.x PR1（§6.7.3）：project pack 降级时强制覆盖 profileName 为 "guide"。
+ * 抽为 pure helper 便于单元测试——transpileActive 调一下，逻辑集中。
+ * back-compat：degraded=false 或 requested="guide" 时返 requested 原值。
+ */
+export function applyProjectPackDegrade(projectPackDegraded, requested) {
+    if (projectPackDegraded && requested !== "guide")
+        return "guide";
+    return requested;
+}

package/dist/asset-pack/manifest.d.ts

@@ -0,0 +1,23 @@
+/** manifest 解析结果。ok=false 表示文件不存在/解析失败/校验不过——调用方走默认值。 */
+export interface ParsedManifest {
+    /** 文件存在且 YAML 解析成功（name/version/description 校验失败仍 ok=true，错误进 warnings）。 */
+    ok: boolean;
+    /** 合法 kebab-case name（ok=true 且 manifest 有 name 且校验通过时） */
+    name?: string;
+    /** 合法 semver（ok=true 且 manifest 有 version 且校验通过时） */
+    version?: string;
+    /** 原样保留（仅诊断用） */
+    description?: string;
+    /** 非致命问题（name 非 kebab / version 非 semver / 保留名冲突 / top-level 不是 mapping） */
+    warnings: string[];
+}
+/**
+ * 解析 <rootDir>/pt-asset-pack.yaml（可选）。
+ * - 文件不存在 → { ok: false, warnings: [] }（隐式 pack，走 basename 兜底）
+ * - 文件存在但解析失败 → { ok: false, warnings: ["manifest parse failed: ..."] }
+ * - name 非 kebab-case / 保留名冲突 → warnings + name 丢弃（走 basename）
+ * - version 非 semver → warnings + version 丢弃（走 "0.0.0"）
+ *
+ * 永远不抛异常（§2.2 校验规则：解析失败当无 manifest 处理，不阻断加载）。
+ */
+export declare function parseManifest(rootDir: string): Promise<ParsedManifest>;

package/dist/asset-pack/manifest.js

@@ -0,0 +1,96 @@
+// src/asset-pack/manifest.ts — pt-asset-pack.yaml manifest 解析（v15.x PR2）
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §2.2（manifest 格式）+ §2.4.1（命名约束）
+//
+// 职责：解析 <rootDir>/pt-asset-pack.yaml（可选），提取 name/version/description。
+// 所有问题收集到 warnings——不抛异常，调用方走默认值（§2.2 校验规则）。
+//
+// PR2 阶段保留名 reserved pack（source=project/global/builtin）跳过 manifest，
+//  用固定名 prj/gbl/pt——见 md-file-pack.ts create()。
+//
+// semver 正则按设计文档 §2.2 固定（不引 semver 包）。
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { errMsg } from "../diagnostics.js";
+/** reserved pack 名（§2.4.1 精确匹配禁用）+ 别名兼容。
+ *  精确匹配，不是前缀禁用——`pt-internal` 合法；只有完全等于集合内值才触发冲突。 */
+const RESERVED_NAMES = new Set([
+    "gbl",
+    "prj",
+    "pt",
+    "project",
+    "global",
+    "builtin",
+]);
+/** semver 正则（§2.2 实现备注）。
+ *  格式：<major>.<minor>.<patch>[-<pre-release>][+<build>]
+ *  pre-release / build 标识符字符集：[0-9A-Za-z.-] */
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+/** kebab-case 正则（§2.4.1：[a-z0-9-]+，1-64 字符）。 */
+const KEBAB_RE = /^[a-z0-9-]{1,64}$/;
+/**
+ * 解析 <rootDir>/pt-asset-pack.yaml（可选）。
+ * - 文件不存在 → { ok: false, warnings: [] }（隐式 pack，走 basename 兜底）
+ * - 文件存在但解析失败 → { ok: false, warnings: ["manifest parse failed: ..."] }
+ * - name 非 kebab-case / 保留名冲突 → warnings + name 丢弃（走 basename）
+ * - version 非 semver → warnings + version 丢弃（走 "0.0.0"）
+ *
+ * 永远不抛异常（§2.2 校验规则：解析失败当无 manifest 处理，不阻断加载）。
+ */
+export async function parseManifest(rootDir) {
+    const file = join(rootDir, "pt-asset-pack.yaml");
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        // 文件不存在 → 隐式 pack
+        return { ok: false, warnings: [] };
+    }
+    let data;
+    try {
+        data = parseYaml(raw);
+    }
+    catch (e) {
+        return { ok: false, warnings: [`manifest parse failed: ${errMsg(e)}`] };
+    }
+    if (!isRecord(data)) {
+        return { ok: false, warnings: ["manifest top-level not a mapping"] };
+    }
+    const warnings = [];
+    let name;
+    let version;
+    let description;
+    // name 校验
+    if (typeof data.name === "string" && data.name.trim()) {
+        const n = data.name.trim();
+        if (!KEBAB_RE.test(n)) {
+            warnings.push(`manifest.name "${n}" not kebab-case, falling back to basename`);
+        }
+        else if (RESERVED_NAMES.has(n)) {
+            warnings.push(`manifest.name "${n}" is reserved, falling back to basename`);
+        }
+        else {
+            name = n;
+        }
+    }
+    // version 校验
+    if (typeof data.version === "string" && data.version.trim()) {
+        const v = data.version.trim();
+        if (!SEMVER_RE.test(v)) {
+            warnings.push(`manifest.version "${v}" not semver, treating as "0.0.0"`);
+        }
+        else {
+            version = v;
+        }
+    }
+    // description 原样保留（仅诊断用，无校验）
+    if (typeof data.description === "string" && data.description.trim()) {
+        description = data.description.trim();
+    }
+    return { ok: true, name, version, description, warnings };
+}
+function isRecord(x) {
+    return !!x && typeof x === "object" && !Array.isArray(x);
+}