@istuen/pt 0.1.0

package/dist/parse/shared.js

@@ -0,0 +1,273 @@
+// 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";
+// ==================== 词法/语法（共享） ====================
+/** 读 asset 文件并解析 frontmatter + H2 段。 */
+export async function readAsset(path) {
+    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 = "domain"; // 默认值——保留 AssetKind 联合类型以备未来扩展
+    const sectionsArr = splitSections(body);
+    const sections = {};
+    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) {
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!m)
+        return { fm: {}, body: text };
+    const fm = {};
+    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) {
+    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) {
+    const inner = s.slice(1, -1).trim();
+    if (!inner)
+        return {};
+    const out = {};
+    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, sep) {
+    const out = [];
+    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) {
+    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) {
+    const lines = body.split(/\r?\n/);
+    const sections = [];
+    let cur = 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) {
+    const lines = sectionRaw.split(/\r?\n/);
+    const hasH3 = lines.some((l) => /^###\s+/.test(l));
+    if (hasH3) {
+        const items = [];
+        let cur = 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 = [];
+    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) {
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string").join(", ");
+    return "";
+}
+/** 把 unknown 收窄为 string[]（单值包成 1-数组）。无值 → []。 */
+export function sArr(v) {
+    if (Array.isArray(v))
+        return v.filter((x) => 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, key) {
+    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) {
+    return extractBareListUnderH3(section, "Modules");
+}
+/** 同 extractBareListUnderH3(section, "Domains") 的别名（Blueprint 用）。 */
+export function extractDomainsList(section) {
+    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, h3Name) {
+    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) => typeof x === "string");
+            if (strs.length > 0)
+                return strs;
+        }
+    }
+    // 主路径：扫 raw text 找 H3 + 后随的 `- name` 行
+    const lines = section.raw.split(/\r?\n/);
+    const out = [];
+    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 形态。 */

package/dist/profile-persist.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** session JSONL 通用接口的最小子集（结构类型，不用 ReadonlySessionManager——不在 pi 包顶层 export）。 */
+export interface MinimalSessionManager {
+    getEntries(): Array<{
+        type: string;
+        customType?: string;
+        data?: unknown;
+    }>;
+}
+/** session JSONL 中持久化 activeProfile 的 custom entry customType。
+ *  用 `pt:` 命名空间避免污染 pi 通用命名空间。 */
+export declare const PT_PROFILE_ENTRY = "pt:active-profile";
+/** 从 session JSONL 读上次保存的 profile。
+ *  - 反向遍历 entries，取最后一个 `pt:active-profile`（最新一次切换覆盖前一次）。
+ *  - 静默 fallback：SessionManager 不可用 / ephemeral session / entry 损坏 → 返 undefined。
+ *  - 不校验 profile 是否仍存在于 assets——校验留给 transpileActive（transpile 失败会被 session_start catch）。
+ *  - 用结构类型而非 `ReadonlySessionManager`（该类型不在 pi 包顶层 export.d.ts 里）。 */
+export declare function readProfileFromSession(sessionManager: MinimalSessionManager): string | undefined;
+/** 把当前 activeProfile 写入 session JSONL（Pi 自带持久化）。
+ *  - 用 `pi.appendEntry()`（dist/core/extensions/types.d.ts:78 官方 API）。
+ *  - 失败静默（ephemeral session / 旧版 pi 无此 API）——内存中 activeProfile 仍可用本进程。 */
+export declare function persistProfileToSession(pi: ExtensionAPI, name: string): void;

package/dist/profile-persist.js

@@ -0,0 +1,53 @@
+// src/profile-persist.ts — Session JSONL profile 持久化（P1.4 抽出）
+//
+// v10.x：用 pi.appendEntry() 把 activeProfile 写到 session JSONL。
+//  - 读：反向遍历 entries，取最后一个 pt:active-profile（最新覆盖前一次）。
+//  - 写：appendEntry，失败静默（ephemeral session / 旧版 pi 无此 API）。
+//
+//  MinimalSessionManager 是 session JSONL 通用接口的最小子集（profile + manual 持久化共用）。
+//  P1 范围内放这里；未来 contract/ 迁移（P2+）时可考虑抽到 src/contract/。
+import { errMsg } from "./diagnostics.js";
+/** session JSONL 中持久化 activeProfile 的 custom entry customType。
+ *  用 `pt:` 命名空间避免污染 pi 通用命名空间。 */
+export const PT_PROFILE_ENTRY = "pt:active-profile";
+/** 从 session JSONL 读上次保存的 profile。
+ *  - 反向遍历 entries，取最后一个 `pt:active-profile`（最新一次切换覆盖前一次）。
+ *  - 静默 fallback：SessionManager 不可用 / ephemeral session / entry 损坏 → 返 undefined。
+ *  - 不校验 profile 是否仍存在于 assets——校验留给 transpileActive（transpile 失败会被 session_start catch）。
+ *  - 用结构类型而非 `ReadonlySessionManager`（该类型不在 pi 包顶层 export.d.ts 里）。 */
+export function readProfileFromSession(sessionManager) {
+    try {
+        const entries = sessionManager.getEntries();
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const e = entries[i];
+            if (e && e.type === "custom" && e.customType === PT_PROFILE_ENTRY) {
+                const data = e.data;
+                if (data && typeof data === "object") {
+                    const profile = data.profile;
+                    if (typeof profile === "string" && profile.trim()) {
+                        return profile.trim();
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // SessionManager 异常（如不存在 / 旧版 pi）→ 静默
+    }
+    return undefined;
+}
+/** 把当前 activeProfile 写入 session JSONL（Pi 自带持久化）。
+ *  - 用 `pi.appendEntry()`（dist/core/extensions/types.d.ts:78 官方 API）。
+ *  - 失败静默（ephemeral session / 旧版 pi 无此 API）——内存中 activeProfile 仍可用本进程。 */
+export function persistProfileToSession(pi, name) {
+    try {
+        if (typeof pi.appendEntry !== "function")
+            return;
+        pi.appendEntry(PT_PROFILE_ENTRY, { profile: name });
+    }
+    catch (e) {
+        // P1.4 边界：slog 是 index.ts 本地函数，profile-persist 不反向依赖 index。
+        // 直接 console.warn 兜底（与 slog 行为一致）。未来抽 log 工具时统一接入。
+        console.warn(`[pt] persistProfileToSession failed:`, { profileName: name, err: errMsg(e) });
+    }
+}

package/dist/render/cache.d.ts

@@ -0,0 +1,15 @@
+import type { AgentContext } from "../schema.js";
+/** v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md，
+ *  sanitize 非法字符为 _（pack 名已是 kebab-case 通常不需要；profile 名可能含特殊字符）。 */
+declare function cacheFileName(packName: string, profileName: string): string;
+/** 把 AgentContext IR 序列化并写入 <CACHE_DIR>/<pack>__<name>.agent-context.md。
+ *  文件头：source-hash: <hash>（缓存失效依据）+ pack: <packName>。 */
+export declare function saveAgentContext(cwd: string, ctx: AgentContext): Promise<string>;
+/** 读 <CACHE_DIR>/<pack>__<name>.agent-context.md 并校验 sourceHash。
+ *  - 文件不存在 → 触发 §9.4.1 旧缓存清理：检测旧名 <name>.agent-context.md → 删除 → 返 null（重编译）
+ *  - 文件存在但 hash 不一致 → 返 null（需重编译覆盖）
+ *  - 命中 → 返 AgentContext IR
+ *  v15.x PR2（§8.3）：签名加 packName 参数；旧名 <profile>.agent-context.md 自动清理迁移。 */
+export declare function loadAgentContext(cwd: string, packName: string, name: string, expectedHash: string): Promise<AgentContext | null>;
+/** v15.x PR2（§8.3）：导出 cacheFileName 给测试用。 */
+export { cacheFileName };

package/dist/render/cache.js

@@ -0,0 +1,135 @@
+// src/render/cache.ts — AgentContext 文件读写 + hash 校验
+//
+// v9 失效策略：sourceHash = hash(Profile + Blueprint + Domains) 组合。
+// 三者任一变化即失效重编译。
+//
+// v15.x PR2（§8.1）：sourceHash 加 packs 维度——pack 内容变化触发失效。
+// v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md（sanitize 特殊字符）。
+// v15.x PR2（§9.4.1）：旧缓存清理——loadAgentContext 检测旧名 → 删除 → 触发重编译。
+//
+// Phase term-P1：Context IR → AgentContext 改名同步——
+//   - 文件后缀 .context.md → .agent-context.md
+//   - saveContext → saveAgentContext / loadContext → loadAgentContext
+//   - serializeContext → serializeAgentContext / deserializeContext → deserializeAgentContext
+//
+// Phase term-P4.2：cacheDir 改用 constants.CACHE_DIR 常量（替代 Blueprint.compilation.cacheDir）。
+//   split 硬编码 single-file（唯一选项，by-injection-point 已 YAGNI 移除）。
+//   签名删 compilation 参数。
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CACHE_DIR } from "../constants.js";
+/** v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md，
+ *  sanitize 非法字符为 _（pack 名已是 kebab-case 通常不需要；profile 名可能含特殊字符）。 */
+function cacheFileName(packName, profileName) {
+    const sanitize = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `${sanitize(packName)}__${sanitize(profileName)}.agent-context.md`;
+}
+/** 把 AgentContext IR 序列化并写入 <CACHE_DIR>/<pack>__<name>.agent-context.md。
+ *  文件头：source-hash: <hash>（缓存失效依据）+ pack: <packName>。 */
+export async function saveAgentContext(cwd, ctx) {
+    const dir = join(cwd, CACHE_DIR);
+    await mkdir(dir, { recursive: true });
+    // v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md
+    const file = join(dir, cacheFileName(ctx.packName, ctx.name));
+    const body = serializeAgentContext(ctx);
+    await writeFile(file, body, "utf8");
+    return file;
+}
+/** 读 <CACHE_DIR>/<pack>__<name>.agent-context.md 并校验 sourceHash。
+ *  - 文件不存在 → 触发 §9.4.1 旧缓存清理：检测旧名 <name>.agent-context.md → 删除 → 返 null（重编译）
+ *  - 文件存在但 hash 不一致 → 返 null（需重编译覆盖）
+ *  - 命中 → 返 AgentContext IR
+ *  v15.x PR2（§8.3）：签名加 packName 参数；旧名 <profile>.agent-context.md 自动清理迁移。 */
+export async function loadAgentContext(cwd, packName, name, expectedHash) {
+    const file = join(cwd, CACHE_DIR, cacheFileName(packName, name));
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        // §9.4.1：旧缓存清理——新名不存在时尝试旧名
+        return await tryLoadOldCacheAndCleanup(cwd, name, expectedHash);
+    }
+    const ctx = deserializeAgentContext(name, raw);
+    if (!ctx)
+        return null;
+    if (ctx.sourceHash !== expectedHash)
+        return null; // 失效，需重编译
+    return ctx;
+}
+/** v15.x PR2（§9.4.1）：旧缓存清理——升级后旧名 <profile>.agent-context.md 检测 + 删除。
+ *  旧文件存在时删除（无论 hash 是否匹配），返 null 触发 saveAgentContext 以新名重写。
+ *  未传 packName 也能工作（旧名无 pack 概念，默认归 "prj"——但会被清理掉，不会真用到）。 */
+async function tryLoadOldCacheAndCleanup(cwd, name, _expectedHash) {
+    const oldFile = join(cwd, CACHE_DIR, `${name}.agent-context.md`);
+    try {
+        await readFile(oldFile, "utf8");
+    }
+    catch {
+        return null; // 旧名也不存在——首次加载
+    }
+    // 旧文件存在——无论 hash 是否匹配都删除（新名格式不同，重编译）
+    await rm(oldFile, { force: true });
+    return null; // 返 null 触发 saveAgentContext 以新名重写
+}
+// ==================== 序列化/反序列化 ====================
+/** AgentContext IR → 文件内容（含 sourceHash 头 + pack 字段）。 */
+function serializeAgentContext(ctx) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`source-hash: ${ctx.sourceHash}`);
+    lines.push(`pack: ${ctx.packName}`); // v15.x PR2 新增
+    lines.push(`profile: ${ctx.name}`);
+    lines.push(`blueprint: ${ctx.blueprint}`);
+    lines.push("---");
+    lines.push("");
+    for (const [h2Name, content] of Object.entries(ctx.modules)) {
+        lines.push(`## ${h2Name}`);
+        lines.push("");
+        lines.push(content);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+/** 文件内容 → AgentContext IR。返 null 表示格式损坏。 */
+function deserializeAgentContext(name, raw) {
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fmMatch)
+        return null;
+    const fm = {};
+    for (const line of fmMatch[1].split(/\r?\n/)) {
+        const kv = line.match(/^([a-zA-Z_-]+)\s*:\s*(.+)$/);
+        if (kv)
+            fm[kv[1]] = kv[2].trim();
+    }
+    const hash = fm["source-hash"];
+    const fmName = fm.profile ?? fm.name ?? name;
+    const fmBlueprint = fm.blueprint ?? "";
+    // v15.x PR2（§9.4.1）：旧 cache 无 pack 字段时兜底 "prj"——但 §9.4.1 tryLoadOldCacheAndCleanup
+    // 会先删除旧文件，不会真用到兜底。这里兜底仅为 deserialize 容错。
+    const fmPack = fm.pack ?? "prj";
+    if (!hash)
+        return null;
+    const body = fmMatch[2];
+    const modules = {};
+    // 按 ## H2 切分（保留段内换行）
+    const sectionRe = /^## (.+)$/gm;
+    const matches = [];
+    let m;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex exec loop pattern
+    while ((m = sectionRe.exec(body)) !== null) {
+        matches.push({ name: m[1].trim(), start: m.index + m[0].length + 1, end: body.length });
+    }
+    // 排序每个段的结束位置
+    for (let i = 0; i < matches.length; i++) {
+        const cur = matches[i];
+        const next = matches[i + 1];
+        cur.end = next ? next.start - `## ${next.name}`.length - 2 : body.length;
+    }
+    for (const sec of matches) {
+        modules[sec.name] = body.slice(sec.start, sec.end).trim();
+    }
+    return { name: fmName, blueprint: fmBlueprint, sourceHash: hash, modules, packName: fmPack };
+}
+/** v15.x PR2（§8.3）：导出 cacheFileName 给测试用。 */
+export { cacheFileName };

package/dist/render/index.d.ts

@@ -0,0 +1,3 @@
+export { renderSessionInject } from "./session-inject.js";
+export { bindFlowTemplate, findFlowInBlueprint, renderTurnInject } from "./turn-inject.js";
+export { saveAgentContext, loadAgentContext } from "./cache.js";

package/dist/render/index.js

@@ -0,0 +1,14 @@
+// src/render/index.ts — Render 后端入口
+//
+// Phase 9.5：v9 后端入口。
+//   - session-inject.ts : AgentContext 聚合组 → Session Inject 字符串（按 Blueprint inject=session 聚合）
+//   - turn-inject.ts    : FlowTemplate + 参数 → Turn Inject（/manual:xxx + /<flow-name>）
+//                          AgentAdapter 内部映射到 Pi 的 system_prompt/context_message
+//   - cache.ts          : AgentContext 文件读写 + hash 校验（用 constants.CACHE_DIR 常量，P4.2）
+//
+// Phase term-P1：Context IR → AgentContext 改名同步——
+//   - saveContext/loadContext → saveAgentContext/loadAgentContext
+// Phase term-P4.3：render 函数名 + 文件名对齐 session/turn。
+export { renderSessionInject } from "./session-inject.js";
+export { bindFlowTemplate, findFlowInBlueprint, renderTurnInject } from "./turn-inject.js";
+export { saveAgentContext, loadAgentContext } from "./cache.js";

package/dist/render/session-inject.d.ts

@@ -0,0 +1,5 @@
+import type { AgentContext, Blueprint } from "../schema.js";
+/** AgentContext 聚合组聚合 → Session Inject 字符串。
+ *  v9：遍历 Blueprint.groups，聚合所有 inject=session 的聚合组内容。
+ *  AgentAdapter 内部把 Session Inject 注入到 Agent 的 session 级（Pi: system_prompt 事件）。 */
+export declare function renderSessionInject(ctx: AgentContext, blueprint: Blueprint): string;

package/dist/render/session-inject.js

@@ -0,0 +1,24 @@
+// src/render/session-inject.ts — AgentContext 聚合组 → Session Inject 字符串
+//
+// Phase 9.5：v9 后端通用化——遍历 Blueprint.groups（不再 Channel.groups），
+//   聚合所有 inject=session 的聚合组内容。
+//
+// renderSessionInject(ctx, blueprint) → string
+// 设计上保留函数包装，便于将来在渲染阶段做最终修整（如日志、注入标记）。
+//
+// Phase term-P1：参数类型 Context → AgentContext（IR 改名同步）。
+// Phase term-P4.3：函数名 renderSystemPrompt → renderSessionInject；inject 语义值 system_prompt → session。
+/** AgentContext 聚合组聚合 → Session Inject 字符串。
+ *  v9：遍历 Blueprint.groups，聚合所有 inject=session 的聚合组内容。
+ *  AgentAdapter 内部把 Session Inject 注入到 Agent 的 session 级（Pi: system_prompt 事件）。 */
+export function renderSessionInject(ctx, blueprint) {
+    const parts = [];
+    for (const group of blueprint.groups) {
+        if (group.inject === "session") {
+            const content = ctx.modules[group.name];
+            if (content)
+                parts.push(content);
+        }
+    }
+    return parts.join("\n\n");
+}

package/dist/render/turn-inject.d.ts

@@ -0,0 +1,36 @@
+import type { AgentContext, Blueprint, Domain, FlowTemplate, Profile } from "../schema.js";
+/** FlowTemplate + 元数据（adapter 附加的 _vars）。_vars 优先于 argument-hint fallback。 */
+export type BoundableTemplate = FlowTemplate & {
+    _vars?: string[];
+};
+/**
+ * 给定 AgentContext + Blueprint + Domains + args（形如 "/manual:pt-quality" 或 "/risk-check 客户A 5000"），
+ * 展开目标 Domain 的 Manual 段内容或 FlowTemplate。
+ *
+ * v9 触发：
+ *   - /manual:<domain-name>：注入该 Domain 的 Manual 段内容（term→Rule checklist / workflow→FlowTemplate 列表）
+ *   - /<flow-name> <args>：展开 workflow-Domain 的 FlowTemplate（v8 逻辑保留）
+ *
+ * Phase term-P4.3：AgentAdapter 内部把 Turn Inject 注入到 Agent 的 turn 级（Pi: input 事件 transform）。
+ *
+ * v13.x（issue pt-turn-inject-not-profile-scoped）：加 profile 参数——
+ *   - domain 维度：调用方（adapter）应已用 filterDomainsByProfile 过滤 domains，renderTurnInject
+ *     不再二次过滤（信任传入的 domains scope）
+ *   - modules 维度（阶段 2）：从 blueprint 的 inject=turn 聚合组 + profile 同名 ProfileGroup.modules 算
+ *     白名单，/manual:<domain> 只渲染白名单内的段，/<flow-name> 只在白名单含 Flows 段时查找。
+ *     profile 为 null 或无 turn 聚合组 → 白名单 null = 不限制（向后兼容）。
+ */
+export declare function renderTurnInject(_ctx: AgentContext, blueprint: Blueprint, domains: Domain[], profile: Profile | null, args: string): string | null;
+/**
+ * 把 FlowTemplate 模板 + 用户参数 展开为完整手册 markdown。
+ * 错误 / 缺失变量 → 留为字面量（不抛异常）。
+ */
+export declare function bindFlowTemplate(tpl: BoundableTemplate, args: string): string;
+/** 在 Blueprint 聚合组（inject=turn）的引用域中按名查找 FlowTemplate（跨 Domain）。
+ *  v13.x（issue pt-turn-inject-not-profile-scoped）：加 profile 参数——内部算 mods 白名单，
+ *  白名单不含 Flows 段时返 undefined（Profile "参考手册"### Modules 未声明 Flows 则 /<flow-name> 触发失效）。
+ *  Phase term-P4.3 + term-final：inject 语义值 turn（原 context_message → turn → 现聚合组 inject=turn）。 */
+export declare function findFlowInBlueprint(blueprint: Blueprint, domains: Array<{
+    name: string;
+    modules: Record<string, unknown>;
+}>, tplName: string, profile?: Profile | null): BoundableTemplate | undefined;