@istuen/pt 0.1.0

package/dist/render/turn-inject.js

@@ -0,0 +1,248 @@
+// 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";
+/**
+ * 给定 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, blueprint, domains, profile, args) {
+    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, profile) {
+    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, section) {
+    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, mods) {
+    if (modsAllowsSection(mods, MOD_FLOWS)) {
+        const flows = d.modules[MOD_FLOWS];
+        if (isFlowTemplateArray(flows)) {
+            const lines = [];
+            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 = [];
+            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 = [];
+            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, args) {
+    const tokens = args.trim() ? args.trim().split(/\s+/) : [];
+    const varSpecs = parseVarSpecs(tpl._vars, tpl.argumentHint);
+    const bound = new Map();
+    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 = [];
+    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, i) => {
+        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, hint) {
+    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) {
+    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, bound) {
+    return text.replace(/\{\{([^}]+)\}\}/g, (match, inner) => {
+        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, 
+// Phase term-P9.3：type 字段删除——Domain 不再有 type 维度，按 H2 段名（这里是 ## Flows）识别 FlowTemplate
+domains, tplName, profile = null) {
+    // 验证 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 = { ...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;
+}