@istuen/pt 0.1.0

package/dist/compile/resolve-use.js

@@ -0,0 +1,171 @@
+// src/compile/resolve-use.ts — v15.x PR5 use Profile 单继承展开
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §5.3.2（展开算法）/ §5.3.3（菱形 M4）
+//         §5.4（Group 合并）/ §5.5（越权校验）/ §5.6（错误信息）
+//
+// 关键纪律：
+//   - parseUseRef 直接复用 parseRef（PR3a 已实现 @pack/name + 无前缀→selfPack 两种语义）
+//   - 菱形用路径 visited（每层 new Set(visited)），不加 memo（M4）
+//   - 越权校验 use 场景 error（§5.5.1 S7）
+//   - mergeProfile blueprint 覆盖用 `||`（frontmatter blueprint 缺省 "" 非 undefined）
+import { parseRef } from "../parse/ref-resolver.js";
+// ==================== §5.6：错误类型 ====================
+/** §5.6 错误类型：use 目标 Profile 不存在。 */
+export class UseTargetNotFound extends Error {
+    useRef;
+    resolvedKey;
+    loadedPacks;
+    constructor(useRef, resolvedKey, loadedPacks) {
+        super(`Profile use: "${useRef}" — profile not found (resolved: ${resolvedKey}). ` +
+            `Loaded profiles: [${loadedPacks.flatMap((p) => p.name).join(", ")}]. ` +
+            `Hint: 检查 use 引用的 pack/name 拼写，或确认目标 pack 已加载`);
+        this.useRef = useRef;
+        this.resolvedKey = resolvedKey;
+        this.loadedPacks = loadedPacks;
+        this.name = "UseTargetNotFound";
+    }
+}
+/** §5.6 错误类型：use 链循环。 */
+export class UseChainCycle extends Error {
+    chain;
+    constructor(chain) {
+        super(`use chain cycle detected: ${chain.join(" → ")}`);
+        this.chain = chain;
+        this.name = "UseChainCycle";
+    }
+}
+/** §5.6 错误类型：Blueprint group 越权（use 场景，error 阻断激活）。 */
+export class BlueprintGroupOutOfScope extends Error {
+    profileName;
+    outOfScopeGroups;
+    blueprintName;
+    allowedSlots;
+    constructor(profileName, outOfScopeGroups, blueprintName, allowedSlots) {
+        super(`Profile "${profileName}" expanded groups: [${outOfScopeGroups.join(", ")}] ` +
+            `— group(s) not in blueprint "${blueprintName}" slots [${allowedSlots.join(", ")}]. ` +
+            `Hint: 在 self.groups 中显式重写越权 group，或改回 use 的 blueprint`);
+        this.profileName = profileName;
+        this.outOfScopeGroups = outOfScopeGroups;
+        this.blueprintName = blueprintName;
+        this.allowedSlots = allowedSlots;
+        this.name = "BlueprintGroupOutOfScope";
+    }
+}
+// ==================== §5.3.2：expandProfile 主算法 ====================
+/**
+ * §5.3.2 expandProfile——递归展开 use 链。
+ *
+ * @param self 当前 Profile（已带 sourcePack）
+ * @param profileByQualifiedName key="pack/name" 的 Profile 视图（= workingSet.profiles 转换）
+ * @param blueprintByQualifiedName key="pack/name" 的 Blueprint 视图（越权校验用）
+ * @param loadedPacks 错误信息展示用
+ * @param visited 路径 visited（循环检测）——每层递归 new Set(visited)，菱形不误报
+ * @param ctx adapterCtx（错误信息可走 notify 三通道 fallback——errors 已 throw，此参数备用）
+ * @returns 展开后的 Profile（合并 use 链结果，self 优先）
+ */
+export function expandProfile(self, profileByQualifiedName, blueprintByQualifiedName, loadedPacks, visited = new Set(), _ctx) {
+    const key = `${self.sourcePack ?? ""}/${self.name}`;
+    // 步骤 2：循环检测（路径 visited）
+    if (visited.has(key)) {
+        throw new UseChainCycle([...visited, key]);
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(key);
+    // 步骤 4：叶子 Profile——不写 use 直接返回 self（back-compat 早退）
+    if (!self.use) {
+        return self;
+    }
+    // 步骤 5：解析 use 引用（复用 parseRef——已含 @prj/@gbl/@pt 别名归一）
+    const useRef = parseRef(self.use, self.sourcePack ?? "");
+    let useKey = `${useRef.pack}/${useRef.name}`;
+    let useProfile = profileByQualifiedName.get(useKey);
+    // v15.x PR3a back-compat（§4.4）：无前缀 ref 跨 packs fallback（与 transpile findBlueprint 一致）
+    // 限定 @pack/name 不 fallback——严格语义
+    if (!useProfile && !self.use.startsWith("@")) {
+        for (const fallbackPack of loadedPacks.map((p) => p.name)) {
+            if (fallbackPack === useRef.pack)
+                continue;
+            const fallback = profileByQualifiedName.get(`${fallbackPack}/${useRef.name}`);
+            if (fallback) {
+                useProfile = fallback;
+                useKey = `${fallbackPack}/${useRef.name}`;
+                break;
+            }
+        }
+    }
+    if (!useProfile) {
+        throw new UseTargetNotFound(self.use, useKey, loadedPacks);
+    }
+    // 步骤 6：递归展开 use Profile（每层独立 visited——菱形不误报）
+    const useExpanded = expandProfile(useProfile, profileByQualifiedName, blueprintByQualifiedName, loadedPacks, nextVisited, // 路径 visited，非全图 visited（§5.3.3）
+    _ctx);
+    // 步骤 7：合并 self ⊕ useExpanded（§5.2 表）
+    const merged = mergeProfile(self, useExpanded);
+    // 步骤 8：越权校验——use 场景 error（§5.5.1 S7）
+    validateGroupScopeForUse(merged, self, blueprintByQualifiedName);
+    return merged;
+}
+// ==================== §5.2：mergeProfile ====================
+/** §5.2 合并规则：self ⊕ useExpanded。
+ *  - name：self 强制覆盖（不继承，§5.2 唯一不继承字段）
+ *  - blueprint：self.blueprint || useExpanded.blueprint（覆盖；空字符串=未写→继承）
+ *  - tagline：self.tagline ?? useExpanded.tagline（覆盖）
+ *  - domains：dedupByName([...useExpanded.domains, ...self.domains])（追加，self 优先去重）
+ *  - groups：mergeGroupsByName（同名 self 替换整个 use group；§5.4） */
+function mergeProfile(self, useExpanded) {
+    return {
+        name: self.name, // 强制覆盖
+        blueprint: self.blueprint || useExpanded.blueprint, // || 而非 ??：空字符串 falsy
+        tagline: self.tagline ?? useExpanded.tagline,
+        domains: dedupByName([...useExpanded.domains, ...self.domains]),
+        groups: mergeGroupsByName(useExpanded.groups, self.groups),
+        use: undefined, // 展开后 Profile 不再带 use（已消化，避免下游重复展开）
+        sourcePack: self.sourcePack, // 身份不变
+    };
+}
+/** §5.2 domains 追加去重——后者（self）优先，保留首次插入顺序。 */
+function dedupByName(domains) {
+    const seen = new Set();
+    const result = [];
+    for (const d of domains) {
+        if (seen.has(d))
+            continue;
+        seen.add(d);
+        result.push(d);
+    }
+    return result;
+}
+/** §5.4 mergeGroupsByName——self 同名 group 整个替换 use 的（含 modules + domains）。
+ *  modules 列表是替换不是 union（§5.4 明示）。 */
+function mergeGroupsByName(useGroups, selfGroups) {
+    const result = [];
+    for (const useGroup of useGroups) {
+        const selfMatch = selfGroups.find((g) => g.name === useGroup.name);
+        result.push(selfMatch ?? useGroup); // self 替换整个 group
+    }
+    for (const selfGroup of selfGroups) {
+        if (!useGroups.find((g) => g.name === selfGroup.name)) {
+            result.push(selfGroup); // self 独有 group 追加
+        }
+    }
+    return result;
+}
+// ==================== §5.5：use 场景越权校验 ====================
+/** §5.5 越权校验——use 场景 error。
+ *  合并后 groups 的所有 group.name 必须在 self.blueprint 的 slots 里。
+ *  blueprint 查不到时 return（transpile.ts 会另行报"未知 Blueprint"，不重复）。 */
+function validateGroupScopeForUse(merged, self, blueprintByQualifiedName) {
+    if (!merged.blueprint)
+        return; // 无 blueprint 不校验（与今天一致）
+    const { pack: bpPack, name: bpName } = parseRef(merged.blueprint, self.sourcePack ?? "");
+    const bpEntry = blueprintByQualifiedName.get(`${bpPack}/${bpName}`);
+    if (!bpEntry)
+        return; // blueprint 查不到不校验（transpile 另行报错）
+    const allowedSlots = bpEntry.asset.groups.map((g) => g.name);
+    const outOfScope = merged.groups
+        .map((g) => g.name)
+        .filter((name) => !allowedSlots.includes(name));
+    if (outOfScope.length > 0) {
+        throw new BlueprintGroupOutOfScope(merged.name, outOfScope, merged.blueprint, allowedSlots);
+    }
+}

package/dist/compile/type-guards.d.ts

@@ -0,0 +1,29 @@
+import type { Checklist, ExternalRef, FlowTemplate, Rule, Term } from "../schema.js";
+/** unknown 是否为数组。 */
+export declare function isArray(x: unknown): x is unknown[];
+/** unknown 是否为非空数组。 */
+export declare function isNonEmptyArray<T>(x: unknown): x is T[];
+/** unknown 是否为索引签名对象（非数组的 object）。 */
+export declare function isRecord(x: unknown): x is Record<string, unknown>;
+/** unknown 是否为 Term[]。 */
+export declare function isTermArray(x: unknown): x is Term[];
+/** unknown 是否为 Rule[]。 */
+export declare function isRuleArray(x: unknown): x is Rule[];
+/** 校验元素是否具备 FlowTemplate 最小形状（{ name, intent, steps[] }）。 */
+export declare function isFlowTemplateLike(x: unknown): x is FlowTemplate;
+/** unknown 是否为 FlowTemplate[]。 */
+export declare function isFlowTemplateArray(x: unknown): x is FlowTemplate[];
+/** unknown 是否为 Trigger 项[]。 */
+export declare function isTriggerItemArray(x: unknown): x is Array<{
+    name: string;
+    desc?: string;
+    hint?: string;
+}>;
+/** unknown 是否为 Checklist[]。 */
+export declare function isChecklistArray(x: unknown): x is Checklist[];
+export declare function isExternalRefArray(x: unknown): x is ExternalRef[];
+/** 通用 fallback 形态：H3 + name + desc 列表项（用于未注册 type 的聚合段输出）。 */
+export declare function isNamedItemArray(x: unknown): x is Array<{
+    name: string;
+    desc?: string;
+}>;

package/dist/compile/type-guards.js

@@ -0,0 +1,107 @@
+// src/compile/type-guards.ts — Domain.modules 内容类型守卫（pt-quality #1）
+//
+// Domain.modules 的 H2 段内容是 unknown（type hole），消费者用 type guard 收窄，
+// 不用 as 断言。type guard 集中管理，新增内容类型加一个 isXxxArray。
+//
+// 与 schema.ts 的区别：schema.ts 定义契约（Term/Rule/FlowTemplate 等结构），
+// type-guards.ts 定义运行时收窄（"这个 unknown 是不是 Term[]?"）。
+// ==================== 通用守卫 ====================
+/** unknown 是否为数组。 */
+export function isArray(x) {
+    return Array.isArray(x);
+}
+/** unknown 是否为非空数组。 */
+export function isNonEmptyArray(x) {
+    return Array.isArray(x) && x.length > 0;
+}
+/** unknown 是否为索引签名对象（非数组的 object）。 */
+export function isRecord(x) {
+    return !!x && typeof x === "object" && !Array.isArray(x);
+}
+// ==================== Term[] 守卫 ====================
+/** 校验元素是否具备 Term 最小形状（{ name: string }）。
+ *  v9.2：Term 加可选 fields/note 后仍只检查 name（最小形状），不强制 desc——
+ *  这样 parse 阶段产出的 Term 即使 desc 为空也过关，renderer 走 `else lines.push("- name")` 分支。
+ *  fields/note 是可选，向后兼容旧 IR。 */
+function isTermLike(x) {
+    return !!x && typeof x === "object" && typeof x.name === "string";
+}
+/** unknown 是否为 Term[]。 */
+export function isTermArray(x) {
+    return Array.isArray(x) && x.every(isTermLike);
+}
+// ==================== Rule[] 守卫 ====================
+/** 校验元素是否具备 Rule 最小形状（{ type: "ban"|"invariant", check: string }）。 */
+function isRuleLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const r = x;
+    return (r.type === "ban" || r.type === "invariant") && typeof r.check === "string";
+}
+/** unknown 是否为 Rule[]。 */
+export function isRuleArray(x) {
+    return Array.isArray(x) && x.every(isRuleLike);
+}
+// ==================== FlowTemplate[] 守卫 ====================
+/** 校验元素是否具备 FlowTemplate 最小形状（{ name, intent, steps[] }）。 */
+export function isFlowTemplateLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const t = x;
+    return typeof t.name === "string" && typeof t.intent === "string" && Array.isArray(t.steps);
+}
+/** unknown 是否为 FlowTemplate[]。 */
+export function isFlowTemplateArray(x) {
+    return Array.isArray(x) && x.every(isFlowTemplateLike);
+}
+// ==================== Trigger 项[] 守卫 ====================
+/** Trigger 段形态：H3 项数组（每项 { name, desc?, hint? }）。
+ *  v9 新增——Trigger 段是索引段，H3 + desc/hint 列表。 */
+function isTriggerItemLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const t = x;
+    return (typeof t.name === "string" &&
+        (t.desc === undefined || typeof t.desc === "string") &&
+        (t.hint === undefined || typeof t.hint === "string"));
+}
+/** unknown 是否为 Trigger 项[]。 */
+export function isTriggerItemArray(x) {
+    return Array.isArray(x) && x.every(isTriggerItemLike);
+}
+// ==================== Checklist[] 守卫（Phase term-P9.2） ====================
+/** Phase term-P9.2：校验 Checklist 最小形状（{ name: string, items: string[] }）。 */
+function isChecklistLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const c = x;
+    return (typeof c.name === "string" &&
+        Array.isArray(c.items) &&
+        c.items.every((i) => typeof i === "string"));
+}
+/** unknown 是否为 Checklist[]。 */
+export function isChecklistArray(x) {
+    return Array.isArray(x) && x.every(isChecklistLike);
+}
+// ==================== ExternalRef[] 守卫 ====================
+function isExternalRefLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const r = x;
+    return typeof r.name === "string" && typeof r.path === "string";
+}
+export function isExternalRefArray(x) {
+    return Array.isArray(x) && x.every(isExternalRefLike);
+}
+// ==================== 通用 fallback 守卫（带 name 字段的项） ====================
+/** 通用 fallback 形态：H3 + name + desc 列表项（用于未注册 type 的聚合段输出）。 */
+export function isNamedItemArray(x) {
+    if (!Array.isArray(x))
+        return false;
+    return x.every((it) => {
+        if (!it || typeof it !== "object")
+            return false;
+        const t = it;
+        return typeof t.name === "string" && (t.desc === undefined || typeof t.desc === "string");
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+/** 读项目 settings.json 的指定 dotted key。文件不存在/解析失败 → undefined */
+export declare function readProjectSetting<T = unknown>(cwd: string, dottedKey: string): Promise<T | undefined>;
+/** 列出可选 Profile 名：项目 + 内建合并，同名时项目覆盖内建。
+ *  必须与 mdAdapter.load 的合并语义一致——否则选择器/补全看不到内建 profile
+ *  （如 builtin `pt`），但 transpile 又能加载，造成“选不到却能手敲”的不一致
+ *  （issue: 内建 pt 无法通过 pt-profile 选择）。 */
+export declare function listProfiles(cwd: string): Promise<string[]>;
+export interface ProfileMeta {
+    name: string;
+    tagline?: string;
+    source: "project" | "settings" | "global" | "builtin";
+    /** v15.x PR3（§7.2）：pack 身份（reserved 短名 prj/gbl/pt 或 manifest.name）。 */
+    pack: string;
+    /** v15.x §4.4.4（缺口 4）：reserved pack 的位置别名（prj/gbl/pt），非 reserved 为 undefined。
+     *  UI 显示层用——reserved 显位置别名，settings 显 pack 名。 */
+    reservedAlias?: "prj" | "gbl" | "pt";
+}
+export declare function listProfilesWithTagline(cwd: string): Promise<ProfileMeta[]>;
+/** 把 ProfileMeta 列表转成选择器展示标签（`[@pack] name — tagline`，§7.3）。
+ *  v15.x §4.4.4（缺口 4）：reserved pack 显 reservedAlias（位置别名），settings pack 显 pack 名。
+ *  tagline 缺省 → 纯名。空 tagline 也走纯名。 */
+export declare function formatProfileLabels(profiles: ProfileMeta[]): string[];
+/** 自动探测：只看项目级 Profile，不把内建 guide 计入用户项目选择。 */
+export declare function detectSingleProfile(cwd: string): Promise<string | null>;
+/** 默认兜底：项目无单 Profile 时，读 settings `pt.default-profile`。
+ *  - 未设 → 返回内建 "guide"（装包即用，真默认）
+ *  - "none" → 返回 null（用户明确不要自动加载）
+ *  - 具体名 → 返回该名（用户自定义默认 Profile）
+ *  与 detectSingleProfile 分离：auto 是项目探测（pickedFrom="auto"），
+ *  default 是兜底机制（pickedFrom="default"），来源可观测。 */
+export declare function detectDefaultProfile(cwd: string): Promise<string | null>;

package/dist/config.js

@@ -0,0 +1,133 @@
+// src/config.ts — 读项目 settings + 探测 Profile
+// ExtensionAPI 无 getSettings，需自读 .pi/settings.json（用 CONFIG_DIR_NAME，不硬编码 .pi）。
+//
+// v9：用户面是 Profile（.pt/assets/profiles/*.profile.md），不是 Blueprint。
+//
+// v14.x（tagline）：加 listProfilesWithTagline() — /pt-profile 选择器展示 tagline 用。
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { BUILTIN_ASSETS_DIR, PROFILES_DIR } from "./constants.js";
+import { isRecord } from "./compile/type-guards.js";
+/** 读项目 settings.json 的指定 dotted key。文件不存在/解析失败 → undefined */
+export async function readProjectSetting(cwd, dottedKey) {
+    const path = join(cwd, CONFIG_DIR_NAME, "settings.json");
+    let json;
+    try {
+        const raw = await readFile(path, "utf8");
+        json = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return dottedKey.split(".").reduce((acc, k) => {
+        if (isRecord(acc) && k in acc) {
+            return acc[k];
+        }
+        return undefined;
+    }, json);
+}
+/** 列出可选 Profile 名：项目 + 内建合并，同名时项目覆盖内建。
+ *  必须与 mdAdapter.load 的合并语义一致——否则选择器/补全看不到内建 profile
+ *  （如 builtin `pt`），但 transpile 又能加载，造成“选不到却能手敲”的不一致
+ *  （issue: 内建 pt 无法通过 pt-profile 选择）。 */
+export async function listProfiles(cwd) {
+    const project = await listProfileNamesIn(join(cwd, PROFILES_DIR));
+    const builtin = await listProfileNamesIn(join(BUILTIN_ASSETS_DIR, "profiles"));
+    const projectNames = new Set(project);
+    const merged = [...project, ...builtin.filter((n) => !projectNames.has(n))];
+    return merged.sort();
+}
+/** 扫描某个 profiles 目录提取 Profile 名（去 .profile.md 后缀）。目录不存在返空。 */
+async function listProfileNamesIn(dir) {
+    try {
+        const files = await readdir(dir);
+        const names = [];
+        for (const f of files) {
+            if (!f.endsWith(".md"))
+                continue;
+            const base = f.slice(0, -3); // 去 .md
+            if (base.endsWith(".profile")) {
+                names.push(base.slice(0, -8)); // 去 .profile
+            }
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/** 从某个 profile 文件里粗读 tagline（只读 frontmatter，不走全 parse）。
+ *  用途：/pt-profile 选择器拼选项 — 不必全 parse profile (可能慢)。
+ *  返回 undefined 表示无 tagline 或读失败（缺省走纯名选项）。 */
+// v15.x PR3：readTaglineFromFile 在新 listProfilesWithTagline 实现中已不用（pack.loadProfiles
+// 返 Profile 对象含 tagline 字段），但保留作为其他代码（readProjectSetting）的辅助。
+// 移除 unused：原 _readTaglineFromFile 实现见 git history。
+/** Profile 名 + tagline 列表（项目 + builtin 合并；同名项目覆盖）。
+ *  builtin 没 tagline 的 profile 返 undefined（选择器退化为纯名）。
+ *  v15.x PR3（§7.2）：加 pack + source（4 类）——选择器显示 [@pack] 前缀；source 区分打包类型。 */
+/** v15.x §4.4.4（位置 alias 表）：reserved pack 的位置别名。reserved pack 才有，非 reserved 为 undefined。
+ *  UI 显示层用——reserved 显位置别名，settings 显 pack 名（§4.4.4 双层语义）。 */
+const RESERVED_ALIAS = new Map([
+    ["project", "prj"],
+    ["global", "gbl"],
+    ["builtin", "pt"],
+]);
+export async function listProfilesWithTagline(cwd) {
+    // v15.x PR4（§4.4.3 #5 + §6.1）：扫所有 pack 含 settings
+    // 顺序与 mdAdapter.load 一致（settings 倒序后者赢）——选择器展示优先级与实际加载一致
+    const { loadProjectPack, loadSettingsPacks, loadGlobalPack, loadBuiltinPack } = await import("./asset-pack/loader.js");
+    const projectPack = await loadProjectPack(cwd);
+    const settingsPacks = await loadSettingsPacks(cwd);
+    const globalPack = await loadGlobalPack();
+    const builtinPack = await loadBuiltinPack();
+    const packs = [projectPack, ...settingsPacks.slice().reverse(), globalPack, builtinPack];
+    const metas = [];
+    for (const pack of packs) {
+        const profiles = await pack.loadProfiles();
+        for (const p of profiles) {
+            if (metas.some((m) => m.name === p.name))
+                continue; // 前者赢
+            metas.push({
+                name: p.name,
+                tagline: p.tagline,
+                source: pack.source,
+                pack: pack.name,
+                reservedAlias: RESERVED_ALIAS.get(pack.source),
+            });
+        }
+    }
+    metas.sort((a, b) => a.name.localeCompare(b.name));
+    return metas;
+}
+/** 把 ProfileMeta 列表转成选择器展示标签（`[@pack] name — tagline`，§7.3）。
+ *  v15.x §4.4.4（缺口 4）：reserved pack 显 reservedAlias（位置别名），settings pack 显 pack 名。
+ *  tagline 缺省 → 纯名。空 tagline 也走纯名。 */
+export function formatProfileLabels(profiles) {
+    return profiles.map((p) => {
+        const label = p.reservedAlias ?? p.pack;
+        const prefix = label ? `[@${label}] ` : "";
+        const tagline = p.tagline ? ` — ${p.tagline}` : "";
+        return `${prefix}${p.name}${tagline}`;
+    });
+}
+/** 自动探测：只看项目级 Profile，不把内建 guide 计入用户项目选择。 */
+export async function detectSingleProfile(cwd) {
+    const project = await listProfileNamesIn(join(cwd, PROFILES_DIR));
+    return project.length === 1 ? project[0] : null;
+}
+/** 默认兜底：项目无单 Profile 时，读 settings `pt.default-profile`。
+ *  - 未设 → 返回内建 "guide"（装包即用，真默认）
+ *  - "none" → 返回 null（用户明确不要自动加载）
+ *  - 具体名 → 返回该名（用户自定义默认 Profile）
+ *  与 detectSingleProfile 分离：auto 是项目探测（pickedFrom="auto"），
+ *  default 是兜底机制（pickedFrom="default"），来源可观测。 */
+export async function detectDefaultProfile(cwd) {
+    const setting = await readProjectSetting(cwd, "pt.default-profile");
+    if (setting === undefined)
+        return "guide"; // 未设 → 内建兜底
+    if (setting === "none")
+        return null; // 明确关闭
+    const trimmed = setting.trim();
+    return trimmed || null;
+}

package/dist/constants.d.ts

@@ -0,0 +1,52 @@
+/** .pt/ 资产根目录 */
+export declare const ASSETS_DIR = ".pt/assets";
+/** Domain md 目录（type=term/workflow/stack/扩展） */
+export declare const DOMAINS_DIR = ".pt/assets/domains";
+/** Blueprint yaml 目录（v9 结构层——groups: name + inject + modules，跨项目复用） */
+export declare const BLUEPRINTS_DIR = ".pt/assets/blueprints";
+/** Profile md 目录（v9 配置层——blueprint + domains + groups H2 实例化） */
+export declare const PROFILES_DIR = ".pt/assets/profiles";
+/** AgentContext 物理缓存目录（Blueprint.compilation.cacheDir 默认值）。
+ *  Phase term-P1：.pt/cache/contexts → .pt/cache/agent-contexts（Context IR 改名 AgentContext 同步）。 */
+export declare const CACHE_DIR = ".pt/cache/agent-contexts";
+/** /pt raw 输出目录（segment dump） */
+export declare const RAW_DIR = ".pt/cache/raws";
+/** /pt full 输出目录（完整 systemPrompt dump） */
+export declare const FULL_DIR = ".pt/cache/fulls";
+/** /pt manual 输出目录（手册实例文档） */
+export declare const MANUAL_DIR = ".pt/manuals";
+export declare const BUILTIN_ASSETS_DIR: string;
+/** Domain 的 Scene 段（Phase term-P9.3：统一为 Term[]，含可选 path 字段）
+ *  拆 Type 后 Scene 不再按 type 分发 schema——一个 H2 段一个 schema（Term[]）。 */
+export declare const MOD_SCENE = "Scene";
+/** Domain 的 Trigger 段（v9 索引段——H3 + desc/hint 列表） */
+export declare const MOD_TRIGGER = "Trigger";
+/** Domain 的 Rules 段（Phase term-P9.2：从 Manual 拆出）—— Rule[]（pt-quality 等） */
+export declare const MOD_RULES = "Rules";
+/** Domain 的 Flows 段（Phase term-P9.2：从 Manual 拆出）—— FlowTemplate[]（dev-workflow 等） */
+export declare const MOD_FLOWS = "Flows";
+/** Domain 的 Checklists 段（Phase term-P9.2：新增）—— Checklist[]（pt-collab 等） */
+export declare const MOD_CHECKLISTS = "Checklists";
+/** Phase term-P8：会话参与者信息段——me Domain 专用，Term[] 与 Scene 同构，复用 renderSceneModule。
+ *  与 Scene 的区别：语义上是"会话参与者描述"（who am I + goal + how we collaborate），
+ *  不是"领域场景元数据"。拆出来让 Blueprint 模块清单更具语义化。 */
+export declare const MOD_PARTICIPANT = "Participant";
+/** Phase modules-to-profile-complete：user-info Domain 专用段名。Phase term-P8 时叫 "Participant"，
+ *  本 phase 拆分为 "User"（user-info）和 "Agent"（agent-info）——段名 = 命名空间，
+ *  限定到单个 domain 通过专用段名实现，避免 modName 形态 3（domain:段.项）的重复写引用。 */
+export declare const MOD_USER = "User";
+/** agent-info Domain 专用段名——同上拆分理由。 */
+export declare const MOD_AGENT = "Agent";
+/** Domain 的 Term 段（fallback term 形态，未指定 type 默认走 Term[]） */
+export declare const MOD_TERM = "Term";
+/** Blueprint 文件名后缀标记（v9 命名约定：<name>.blueprint.yaml，Phase term-P4.5）
+ *  用于识别 Blueprint 资产——保留 .blueprint 部分以便从文件名提取蓝本名。 */
+export declare const SUFFIX_BLUEPRINT = ".blueprint";
+/** Blueprint 文件扩展名（Phase term-P4.5：载体从 .md 转 .yaml） */
+export declare const SUFFIX_BLUEPRINT_YAML = ".blueprint.yaml";
+/** Profile 文件名后缀（v9 命名约定：<name>.profile.md） */
+export declare const SUFFIX_PROFILE = ".profile";
+/** Domain 文件后缀（.md 即可，无 type 后缀） */
+export declare const SUFFIX_MD = ".md";
+/** Pi Agent adapter 名 */
+export declare const AGENT_PI = "pi";

package/dist/constants.js

@@ -0,0 +1,81 @@
+// src/constants.ts — 路径常量 + Domain H2 段名常量（pt-quality #4 + #5）
+//
+// 路径常量集中管理：资产/缓存/输出目录
+// 模块名常量：Domain 的 H2 段名（Scene/Trigger/Manual/Term）
+//
+// 注意：聚合组名（Blueprint groups[].name，如"会话背景"/"参考手册"）是人类自定义的语义名，
+// 不应常量化——常量化的是 Domain 内的 H2 段名（v9 资产的标准段）。
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// ==================== 路径常量 ====================
+//
+// .pt/ 目录布局规范（v11 重排）：
+//   .pt/assets/   入 git — 转译资产（domains / blueprints / profiles）
+//   .pt/docs/     入 git — 文档（designs 设计与执行 / issues 问题跟踪）
+//   .pt/manuals/  gitignore — pt_manual 工作文档
+//   .pt/cache/    gitignore — 运行产物（contexts 编译 / fulls 完整 prompt / raws segment）
+//   .pt/logs/     gitignore — NDJSON trace
+//
+// 规范源：asset-workflow domain 的 `directory-layout` 场景是 .pt/ 布局的声明式 spec
+// （用户可改该 Domain 调整布局）。当前代码路径仍读本文件常量；未来计划让转译层
+// 直接读 Domain 配置（届时删除下方硬编码，由 parse → compile 注入）。
+// 改路径时务必同步改 asset-workflow.md 的 directory-layout 场景。
+/** .pt/ 资产根目录 */
+export const ASSETS_DIR = ".pt/assets";
+/** Domain md 目录（type=term/workflow/stack/扩展） */
+export const DOMAINS_DIR = `${ASSETS_DIR}/domains`;
+/** Blueprint yaml 目录（v9 结构层——groups: name + inject + modules，跨项目复用） */
+export const BLUEPRINTS_DIR = `${ASSETS_DIR}/blueprints`;
+/** Profile md 目录（v9 配置层——blueprint + domains + groups H2 实例化） */
+export const PROFILES_DIR = `${ASSETS_DIR}/profiles`;
+/** AgentContext 物理缓存目录（Blueprint.compilation.cacheDir 默认值）。
+ *  Phase term-P1：.pt/cache/contexts → .pt/cache/agent-contexts（Context IR 改名 AgentContext 同步）。 */
+export const CACHE_DIR = ".pt/cache/agent-contexts";
+/** /pt raw 输出目录（segment dump） */
+export const RAW_DIR = ".pt/cache/raws";
+/** /pt full 输出目录（完整 systemPrompt dump） */
+export const FULL_DIR = ".pt/cache/fulls";
+/** /pt manual 输出目录（手册实例文档） */
+export const MANUAL_DIR = ".pt/manuals";
+/** 内建资产根目录（随 npm 包发布，跨项目复用）。
+ *  用 import.meta.url 定位包自身路径——不能用 cwd 相对路径（外部用户 cwd ≠ 包路径）。
+ *  mdAdapter fallback：项目 .pt/assets/ 优先，内建补充；同名时项目覆盖内建。 */
+const SRC_DIR = dirname(fileURLToPath(import.meta.url));
+export const BUILTIN_ASSETS_DIR = join(SRC_DIR, "builtin", "assets");
+// ==================== Domain H2 段名常量 ====================
+/** Domain 的 Scene 段（Phase term-P9.3：统一为 Term[]，含可选 path 字段）
+ *  拆 Type 后 Scene 不再按 type 分发 schema——一个 H2 段一个 schema（Term[]）。 */
+export const MOD_SCENE = "Scene";
+/** Domain 的 Trigger 段（v9 索引段——H3 + desc/hint 列表） */
+export const MOD_TRIGGER = "Trigger";
+/** Domain 的 Rules 段（Phase term-P9.2：从 Manual 拆出）—— Rule[]（pt-quality 等） */
+export const MOD_RULES = "Rules";
+/** Domain 的 Flows 段（Phase term-P9.2：从 Manual 拆出）—— FlowTemplate[]（dev-workflow 等） */
+export const MOD_FLOWS = "Flows";
+/** Domain 的 Checklists 段（Phase term-P9.2：新增）—— Checklist[]（pt-collab 等） */
+export const MOD_CHECKLISTS = "Checklists";
+/** Phase term-P8：会话参与者信息段——me Domain 专用，Term[] 与 Scene 同构，复用 renderSceneModule。
+ *  与 Scene 的区别：语义上是"会话参与者描述"（who am I + goal + how we collaborate），
+ *  不是"领域场景元数据"。拆出来让 Blueprint 模块清单更具语义化。 */
+export const MOD_PARTICIPANT = "Participant";
+/** Phase modules-to-profile-complete：user-info Domain 专用段名。Phase term-P8 时叫 "Participant"，
+ *  本 phase 拆分为 "User"（user-info）和 "Agent"（agent-info）——段名 = 命名空间，
+ *  限定到单个 domain 通过专用段名实现，避免 modName 形态 3（domain:段.项）的重复写引用。 */
+export const MOD_USER = "User";
+/** agent-info Domain 专用段名——同上拆分理由。 */
+export const MOD_AGENT = "Agent";
+/** Domain 的 Term 段（fallback term 形态，未指定 type 默认走 Term[]） */
+export const MOD_TERM = "Term";
+// ==================== 资产文件名后缀 ====================
+/** Blueprint 文件名后缀标记（v9 命名约定：<name>.blueprint.yaml，Phase term-P4.5）
+ *  用于识别 Blueprint 资产——保留 .blueprint 部分以便从文件名提取蓝本名。 */
+export const SUFFIX_BLUEPRINT = ".blueprint";
+/** Blueprint 文件扩展名（Phase term-P4.5：载体从 .md 转 .yaml） */
+export const SUFFIX_BLUEPRINT_YAML = ".blueprint.yaml";
+/** Profile 文件名后缀（v9 命名约定：<name>.profile.md） */
+export const SUFFIX_PROFILE = ".profile";
+/** Domain 文件后缀（.md 即可，无 type 后缀） */
+export const SUFFIX_MD = ".md";
+// ==================== Agent 名常量 ====================
+/** Pi Agent adapter 名 */
+export const AGENT_PI = "pi";

package/dist/diagnostics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 跨层复用的诊断辅助函数。
+ *
+ * 从 v0.x 起散落在 parse/index.ts / transpile.ts / index.ts 三处，逐字节相同。
+ * P0 抽到此处统一来源，避免改动重复。
+ */
+import type { SourceAdapterContext } from "./schema.js";
+/** 把 unknown error 序列化成可读字符串。 */
+export declare function errMsg(e: unknown): string;
+/** 三通道 fallback: log → notify → console（pt-quality #9 + 自定义细节）。
+ *  顺序：log 优先（持久 trace），再 notify（UI 瞬时），最后 console（debug 兜底）。
+ *  v10.x：增 details 参数，让 log/UI 用户能看到 structured 上下文。 */
+export declare function reportWarn(adapterCtx: SourceAdapterContext | undefined, msg: string, details?: Record<string, unknown>): void;
+export declare function reportError(adapterCtx: SourceAdapterContext | undefined, msg: string, details?: Record<string, unknown>): void;

package/dist/diagnostics.js

@@ -0,0 +1,29 @@
+/**
+ * 跨层复用的诊断辅助函数。
+ *
+ * 从 v0.x 起散落在 parse/index.ts / transpile.ts / index.ts 三处，逐字节相同。
+ * P0 抽到此处统一来源，避免改动重复。
+ */
+/** 把 unknown error 序列化成可读字符串。 */
+export function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** 三通道 fallback: log → notify → console（pt-quality #9 + 自定义细节）。
+ *  顺序：log 优先（持久 trace），再 notify（UI 瞬时），最后 console（debug 兜底）。
+ *  v10.x：增 details 参数，让 log/UI 用户能看到 structured 上下文。 */
+export function reportWarn(adapterCtx, msg, details) {
+    if (adapterCtx?.log)
+        adapterCtx.log.warn(msg, details);
+    if (adapterCtx?.notify)
+        adapterCtx.notify(msg, "warning");
+    if (!adapterCtx?.log && !adapterCtx?.notify)
+        console.warn(`[pt] ${msg}`);
+}
+export function reportError(adapterCtx, msg, details) {
+    if (adapterCtx?.log)
+        adapterCtx.log.error(msg, details);
+    if (adapterCtx?.notify)
+        adapterCtx.notify(msg, "error");
+    if (!adapterCtx?.log && !adapterCtx?.notify)
+        console.error(`[pt] ${msg}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;