@istuen/pt 0.1.0

package/src/profile-persist.ts

@@ -0,0 +1,60 @@
+// 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 type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { errMsg } from "./diagnostics.js";
+
+/** 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 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: MinimalSessionManager): string | undefined {
+  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 as { data?: unknown }).data;
+        if (data && typeof data === "object") {
+          const profile = (data as { profile?: unknown }).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: ExtensionAPI, name: string): void {
+  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/src/render/cache.ts

@@ -0,0 +1,150 @@
+// 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";
+import type { AgentContext } from "../schema.js";
+
+/** v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md，
+ *  sanitize 非法字符为 _（pack 名已是 kebab-case 通常不需要；profile 名可能含特殊字符）。 */
+function cacheFileName(packName: string, profileName: string): string {
+  const sanitize = (s: string): string => 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: string, ctx: AgentContext): Promise<string> {
+  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: string,
+  packName: string,
+  name: string,
+  expectedHash: string
+): Promise<AgentContext | null> {
+  const file = join(cwd, CACHE_DIR, cacheFileName(packName, name));
+  let raw: string;
+  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: string,
+  name: string,
+  _expectedHash: string
+): Promise<AgentContext | null> {
+  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: AgentContext): string {
+  const lines: string[] = [];
+  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: string, raw: string): AgentContext | null {
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!fmMatch) return null;
+  const fm: Record<string, string> = {};
+  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: Record<string, string> = {};
+  // 按 ## H2 切分（保留段内换行）
+  const sectionRe = /^## (.+)$/gm;
+  const matches: Array<{ name: string; start: number; end: number }> = [];
+  let m: RegExpExecArray | null;
+  // 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/src/render/index.ts

@@ -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/src/render/session-inject.ts

@@ -0,0 +1,26 @@
+// 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。
+
+import type { AgentContext, Blueprint } from "../schema.js";
+
+/** AgentContext 聚合组聚合 → Session Inject 字符串。
+ *  v9：遍历 Blueprint.groups，聚合所有 inject=session 的聚合组内容。
+ *  AgentAdapter 内部把 Session Inject 注入到 Agent 的 session 级（Pi: system_prompt 事件）。 */
+export function renderSessionInject(ctx: AgentContext, blueprint: Blueprint): string {
+  const parts: string[] = [];
+  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/src/render/turn-inject.ts

@@ -0,0 +1,278 @@
+// src/render/turn-inject.ts — FlowTemplate + 参数 → Turn Inject
+//
+// Phase 9.5：v9 后端通用化。
+//   - renderTurnInject(ctx, blueprint, domains, args) 修复死代码——实现 /manual:xxx 触发
+//   - findFlowInBlueprint(blueprint, domains, tplName) — 替代 v8 findFlowInBundle
+//
+// /manual:<domain-name> 触发：从 Blueprint 的 turn 聚合组引用的 Domain 里查 Manual 段
+// /<flow-name> <args> 触发：展开 Domain 的 FlowTemplate（v8 逻辑保留）
+//
+// Phase term-P4.3：renderContextMessage → renderTurnInject；inject 语义值 context_message → turn（Agent-agnostic 语义值）。
+//   bindFlowTemplate / findFlowInBlueprint 函数名不改——它们是 FlowTemplate 操作，非注入位置概念。
+//
+// Tech Debt T6: 全用 type guard 收窄，不用 as 断言（pt-quality #1）
+// Tech Debt T2: 用 constants 模块名常量（pt-quality #5）
+
+import { MOD_CHECKLISTS, MOD_FLOWS, MOD_RULES } from "../constants.js";
+import { isChecklistArray, isFlowTemplateArray, isRuleArray } from "../compile/type-guards.js";
+import type {
+  AgentContext,
+  Blueprint,
+  Domain,
+  FlowStep,
+  FlowTemplate,
+  ModName,
+  Profile,
+} from "../schema.js";
+
+/** FlowTemplate + 元数据（adapter 附加的 _vars）。_vars 优先于 argument-hint fallback。 */
+export type BoundableTemplate = FlowTemplate & { _vars?: string[] };
+
+interface VarSpec {
+  name: string;
+  default?: 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 function renderTurnInject(
+  _ctx: AgentContext,
+  blueprint: Blueprint,
+  domains: Domain[],
+  profile: Profile | null,
+  args: string
+): string | null {
+  const m = args.trim().match(/^\/(\S+)\s*(.*)$/);
+  if (!m) return null;
+  const [, name, rest] = m;
+
+  // 阶段 2：算 turn 聚合组的 modules 白名单（Profile "参考手册"聚合组的 ### Modules）
+  const mods = turnGroupModules(blueprint, profile);
+
+  // /manual:<domain-name> 触发（v9 新增）—— name 可能是 "manual:pt-quality"
+  // Phase term-P9.2：Domain 不再有单一 Manual 段，而是 Rules/Flows/Checklists 三选一。
+  //   顺序遍历找第一个非空段，返回对应渲染。
+  // v13.x：受 mods 白名单限制——只渲染白名单内的段。
+  if (name.startsWith("manual:")) {
+    const domainName = name.slice("manual:".length).trim();
+    const d = domains.find((x) => x.name === domainName);
+    if (!d) return null;
+    return renderDomainManual(d, mods);
+  }
+
+  // /manual <domain-name> 触发——空格分隔形式
+  if (name === "manual") {
+    const domainName = rest.trim();
+    const d = domains.find((x) => x.name === domainName);
+    if (!d) return null;
+    return renderDomainManual(d, mods);
+  }
+
+  // /<flow-name> <args> 触发（v8 逻辑保留）
+  // v13.x：findFlowInBlueprint 内部按 mods 白名单判断是否允许查找 Flows 段。
+  const tpl = findFlowInBlueprint(blueprint, domains, name, profile);
+  if (!tpl) return null;
+  return bindFlowTemplate(tpl, rest);
+}
+
+// ==================== turn 聚合组 modules 白名单辅助（v13.x issue pt-turn-inject-not-profile-scoped） ====================
+
+/** 找 turn 聚合组的 modules 白名单（Profile 同名 ProfileGroup 的 ### Modules）。
+ *  返 null = 不限制（profile 为 null / 无 turn 聚合组 / ProfileGroup 未填 modules——向后兼容）。
+ *  这是阶段 2 的核心：让 Profile "参考手册"### Modules 的段选择真正影响 turn 触发渲染范围。 */
+function turnGroupModules(blueprint: Blueprint, profile: Profile | null): ModName[] | null {
+  if (!profile) return null;
+  const turnGroupName = blueprint.groups.find((g) => g.inject === "turn")?.name;
+  if (!turnGroupName) return null;
+  const pg = profile.groups.find((g) => g.name === turnGroupName);
+  if (!pg || pg.modules.length === 0) return null;
+  return pg.modules;
+}
+
+/** 检查 mods 白名单是否包含某段名。null = 不限制（含）。 */
+function modsAllowsSection(mods: ModName[] | null, section: string): boolean {
+  if (!mods) return true;
+  return mods.some((m) => m.section === section);
+}
+
+/**
+ * 渲染 Domain 的"手册"段内容（Phase term-P9.2：从 Manual 拆三段）。
+ *  - Rules → Rule checklist（"## 规范清单"）
+ *  - Flows → FlowTemplate 列表（"## 可用手册"）
+ *  - Checklists → Checklist 列表（"## 验收清单"）
+ *  优先级：Flows > Rules > Checklists（workhorse 最常被查）
+ *  v13.x：受 mods 白名单限制——只渲染 modsAllowsSection 通过的段。
+ *  返回 null 表示该 Domain 没有任何手册段（或所有段都被白名单排除）。 */
+function renderDomainManual(d: Domain, mods: ModName[] | null): string | null {
+  if (modsAllowsSection(mods, MOD_FLOWS)) {
+    const flows = d.modules[MOD_FLOWS];
+    if (isFlowTemplateArray(flows)) {
+      const lines: string[] = [];
+      for (const t of flows) {
+        const hint = t.argumentHint ? ` ${t.argumentHint}` : "";
+        lines.push(`- ${t.name}${hint}: ${t.intent}`);
+      }
+      if (lines.length > 0) {
+        return `# /manual:${d.name}\n\n## 可用手册\n\n${lines.join("\n")}`.trimEnd();
+      }
+    }
+  }
+
+  if (modsAllowsSection(mods, MOD_RULES)) {
+    const rules = d.modules[MOD_RULES];
+    if (isRuleArray(rules)) {
+      const lines: string[] = [];
+      for (const r of rules) {
+        if (r.type === "invariant") {
+          if (r.check) lines.push(`- ${r.name}: ${r.check}`);
+          else lines.push(`- ${r.name}`);
+        } else if (r.type === "ban" && r.items && r.items.length > 0) {
+          if (r.check) lines.push(`- ${r.name}: ${r.check} (${r.items.join(" / ")})`);
+          else lines.push(`- ${r.name}: ${r.items.join(" / ")}`);
+        }
+      }
+      if (lines.length > 0) {
+        return `# /manual:${d.name}\n\n## 规范清单\n\n${lines.join("\n")}`.trimEnd();
+      }
+    }
+  }
+
+  if (modsAllowsSection(mods, MOD_CHECKLISTS)) {
+    const checklists = d.modules[MOD_CHECKLISTS];
+    if (isChecklistArray(checklists)) {
+      const sections: string[] = [];
+      for (const cl of checklists) {
+        sections.push(`### ${cl.name}\n${cl.items.map((i) => `- ${i}`).join("\n")}`);
+      }
+      if (sections.length > 0) {
+        return `# /manual:${d.name}\n\n## 验收清单\n\n${sections.join("\n\n")}`.trimEnd();
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 把 FlowTemplate 模板 + 用户参数 展开为完整手册 markdown。
+ * 错误 / 缺失变量 → 留为字面量（不抛异常）。
+ */
+export function bindFlowTemplate(tpl: BoundableTemplate, args: string): string {
+  const tokens = args.trim() ? args.trim().split(/\s+/) : [];
+  const varSpecs = parseVarSpecs(tpl._vars, tpl.argumentHint);
+
+  const bound = new Map<string, string>();
+  for (let i = 0; i < varSpecs.length; i++) {
+    const spec = varSpecs[i];
+    const token = tokens[i];
+    if (token !== undefined) {
+      bound.set(spec.name, token);
+    } else if (spec.default !== undefined) {
+      bound.set(spec.name, spec.default);
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push(`# ${tpl.name}`);
+  lines.push("");
+  if (tpl.argumentHint) {
+    lines.push(`_参数：${tpl.argumentHint}_`);
+    lines.push("");
+  }
+  lines.push(`## 前提（Intent）`);
+  lines.push(replaceVars(tpl.intent, bound));
+  lines.push("");
+  lines.push(`## 步骤`);
+  tpl.steps.forEach((s: FlowStep, i: number) => {
+    lines.push(`${i + 1}. ${replaceVars(s.desc, bound)}`);
+    if (s.observe && s.observe.length > 0) {
+      lines.push(`   - 验证参照：${s.observe.join(", ")}`);
+    }
+  });
+
+  return lines.join("\n");
+}
+
+// ==================== 内部辅助 ====================
+
+function parseVarSpecs(_vars: string[] | undefined, hint: string | undefined): VarSpec[] {
+  if (_vars && _vars.length > 0) {
+    return _vars.map(parseVarSpecName);
+  }
+  if (hint) {
+    const matches = [...hint.matchAll(/<([^>]+)>/g)];
+    return matches.map((m) => parseVarSpecName(m[1]));
+  }
+  return [];
+}
+
+function parseVarSpecName(raw: string): VarSpec {
+  const trimmed = raw.trim();
+  const idx = trimmed.indexOf("|");
+  if (idx < 0) return { name: trimmed };
+  const name = trimmed.slice(0, idx).trim();
+  const defaultPart = trimmed.slice(idx + 1).trim();
+  const defaultMatch = defaultPart.match(/^default\s*:\s*(.*)$/);
+  if (defaultMatch) return { name, default: defaultMatch[1].trim() };
+  return { name, default: defaultPart };
+}
+
+function replaceVars(text: string, bound: Map<string, string>): string {
+  return text.replace(/\{\{([^}]+)\}\}/g, (match, inner: string) => {
+    const spec = parseVarSpecName(inner);
+    const v = bound.get(spec.name);
+    if (v !== undefined) return v;
+    if (spec.default !== undefined) return spec.default;
+    return match;
+  });
+}
+
+/** 在 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 function findFlowInBlueprint(
+  blueprint: Blueprint,
+  // Phase term-P9.3：type 字段删除——Domain 不再有 type 维度，按 H2 段名（这里是 ## Flows）识别 FlowTemplate
+  domains: Array<{ name: string; modules: Record<string, unknown> }>,
+  tplName: string,
+  profile: Profile | null = null
+): BoundableTemplate | undefined {
+  // 验证 Blueprint 里有 inject=turn 的聚合组（间接确认 input 事件该由本实例覆盖接管）
+  const hasTurnGroup = blueprint.groups.some((g) => g.inject === "turn");
+  if (!hasTurnGroup) return undefined;
+
+  // v13.x：mods 白名单不含 Flows 段则不查找——配置即行为
+  const mods = turnGroupModules(blueprint, profile);
+  if (!modsAllowsSection(mods, MOD_FLOWS)) return undefined;
+
+  for (const d of domains) {
+    // Phase term-P9.2：FlowTemplate 在 ## Flows 段（不分 type）。
+    const flows = d.modules[MOD_FLOWS];
+    if (!isFlowTemplateArray(flows)) continue;
+    const hit = flows.find((t) => t.name === tplName);
+    if (hit) {
+      const bt: BoundableTemplate = { ...hit };
+      // P2.1：v9 BoundableTemplate = FlowTemplate & { _vars? }，vars 字段 spread 不会产生
+      // 原双重 cast (bt as unknown as { vars?: unknown }).vars 永远 undefined（dead code）。
+      // 若未来需从 args 传 vars 进来，应在调用方 bindFlowTemplate 处理，不在此处 cast 补救。
+      return bt;
+    }
+  }
+  return undefined;
+}