@gordon.gan/specflow 1.8.0-alpha → 1.8.1-beta

package/dist/core/document/map.js

@@ -11,7 +11,7 @@
  * Output budget enforced per chapter (decision 6/P6). fill_once falls back to per-chapter when
  * the estimated input context exceeds the budget (decision 9).
  */
-import { parseEntities } from './schemas.js';
+import { parseEntities, parseInterfaceEntity, parseTableEntity, parseDecisionEntity } from './schemas.js';
 import { estimateTokens } from './llm.js';
 import { fetchSegments } from './input-digest.js';
 const MAP_SYSTEM = '你是方案文档撰写员。按给定章节要点"填空题"式展开：逐要点填充，不自由发挥。' +
@@ -19,6 +19,12 @@ const MAP_SYSTEM = '你是方案文档撰写员。按给定章节要点"填空
     '契约实体必须满足字段约束（接口须含 failure_examples，表须含 ddl/migration/rollback）。';
 // ============= Four-layer context build (T6.2) =============
 export async function buildChapterContext(chapter, ctx) {
+    // 缓存命中直接返回（P2：同一章节上下文在 fill_once 决策/执行/回退/review 重填中会被多次构建）
+    if (ctx.contextCache) {
+        const cached = ctx.contextCache.get(chapter.id);
+        if (cached)
+            return cached;
+    }
     const { outline, digests, upstreamEntities, workRoot } = ctx;
     // ① outline points + global entities/decisions
     const chapterPoints = chapter.points.map((p) => `${p.id} [${p.kind}] ${p.text}${(p.references ?? []).length ? ` refs=${(p.references ?? []).join(',')}` : ''}`).join('\n');
@@ -65,7 +71,10 @@ export async function buildChapterContext(chapter, ctx) {
         system: MAP_SYSTEM,
         messages: [{ role: 'user', content }],
     };
-    return { input, estimatedTokens: estimateTokens(content) + estimateTokens(MAP_SYSTEM) };
+    const built = { input, estimatedTokens: estimateTokens(content) + estimateTokens(MAP_SYSTEM) };
+    if (ctx.contextCache)
+        ctx.contextCache.set(chapter.id, built);
+    return built;
 }
 export async function fillChapter(llm, chapter, ctx, budgetTokens) {
     let input;
@@ -78,6 +87,12 @@ export async function fillChapter(llm, chapter, ctx, budgetTokens) {
     catch (e) {
         return { ok: false, error: `Chapter "${chapter.id}" context build failed: ${e instanceof Error ? e.message : String(e)}` };
     }
+    // Input-side budget guard（P2-adjacent）：在 LLM 调用之前拒绝明显超预算输入，
+    // 避免昂贵调用已发出后才失败（decision 6/P6 hard gate）。
+    const maxInputTokens = budgetTokens ? budgetTokens * 4 : undefined;
+    if (maxInputTokens !== undefined && estimatedTokens > maxInputTokens) {
+        return { ok: false, error: `Chapter "${chapter.id}" input context ${estimatedTokens} tokens exceeds 4× output budget` };
+    }
     let res;
     try {
         res = await llm.complete(input);
@@ -91,27 +106,84 @@ export async function fillChapter(llm, chapter, ctx, budgetTokens) {
     // silently produce a contract-less chapter (decision 1 layered source of truth).
     let entities = { interfaces: [], tables: [], decisions: [] };
     const jsonMatch = narrative.match(/```json\s*([\s\S]*?)```/g);
+    // 记录成功解析为实体块的围栏文本：清洗时只移除这些块，保留叙述中的 JSON 示例（P2）。
+    const parsedEntityBlocks = [];
     if (jsonMatch) {
+        // 按 id 去重合并（P1-9）：同一实体跨块/跨引用重复输出时只保留最后出现的版本，
+        // 防止共享实体在 entities.json 与最终文档中重复渲染。
         const merged = { interfaces: [], tables: [], decisions: [] };
+        const seenInterface = new Set();
+        const seenTable = new Set();
+        const seenDecision = new Set();
         for (const block of jsonMatch) {
+            let parsed;
             try {
-                const parsed = JSON.parse(block.replace(/```json\s*/, '').replace(/```$/, '').trim());
-                if (parsed.entities) {
-                    const e = parseEntities(parsed.entities);
-                    merged.interfaces.push(...e.interfaces);
-                    merged.tables.push(...e.tables);
-                    merged.decisions.push(...e.decisions);
-                }
+                parsed = JSON.parse(block.replace(/```json\s*/, '').replace(/```$/, '').trim());
             }
             catch {
-                // non-entity JSON blocks are ignored; strict entity-presence check below catches gaps
+                continue; // 非法 JSON → 非实体块，忽略
+            }
+            if (!parsed || typeof parsed !== 'object' || !parsed.entities)
+                continue;
+            const rawEntities = parsed.entities;
+            // 逐实体容错（P2）：单个实体字段不合 zod（如接口缺 failure_examples）不再丢弃同块其它
+            // 合法实体；非法项跳过并继续，尽量保留有效契约。
+            const e = { interfaces: [], tables: [], decisions: [] };
+            for (const it of rawEntities.interfaces ?? []) {
+                try {
+                    e.interfaces.push(parseInterfaceEntity(it));
+                }
+                catch { /* 跳过非法接口 */ }
+            }
+            for (const tb of rawEntities.tables ?? []) {
+                try {
+                    e.tables.push(parseTableEntity(tb));
+                }
+                catch { /* 跳过非法表 */ }
+            }
+            for (const d of rawEntities.decisions ?? []) {
+                try {
+                    e.decisions.push(parseDecisionEntity(d));
+                }
+                catch { /* 跳过非法决策 */ }
+            }
+            if (e.interfaces.length + e.tables.length + e.decisions.length === 0)
+                continue;
+            parsedEntityBlocks.push(block);
+            for (const it of e.interfaces) {
+                if (!seenInterface.has(it.id)) {
+                    seenInterface.add(it.id);
+                    merged.interfaces.push(it);
+                }
+            }
+            for (const tb of e.tables) {
+                if (!seenTable.has(tb.id)) {
+                    seenTable.add(tb.id);
+                    merged.tables.push(tb);
+                }
+            }
+            for (const d of e.decisions) {
+                if (!seenDecision.has(d.id)) {
+                    seenDecision.add(d.id);
+                    merged.decisions.push(d);
+                }
             }
         }
         entities = merged;
     }
-    // Clean the narrative: remove the embedded ```json entity blocks so they are not rendered
-    // verbatim inside chapters (contract entities are rendered deterministically in the 契约 section).
-    const cleanNarrative = narrative.replace(/```json\s*[\s\S]*?```/g, '').replace(/\n{3,}/g, '\n\n').trim();
+    // Clean the narrative: remove ONLY the successfully-parsed ```json entity blocks so they are
+    // not rendered verbatim inside chapters; narrative JSON examples (e.g. API response samples)
+    // are preserved (P2). Contract entities are rendered deterministically in the 契约 section.
+    let cleanNarrative = narrative;
+    for (const block of parsedEntityBlocks) {
+        cleanNarrative = cleanNarrative.replace(block, '');
+    }
+    cleanNarrative = cleanNarrative.replace(/\n{3,}/g, '\n\n').trim();
+    // 空叙述早失败（P2）：LLM 只输出实体块未产出叙述时立即报错，与 fillOnce 的检查对齐，
+    // 避免拖到管线末尾 gates-fail 才暴露。
+    if (cleanNarrative.length === 0) {
+        return { ok: false, error: `Chapter "${chapter.id}" produced no narrative (LLM returned only entity JSON or empty content)` };
+    }
     // Strict: entity-requiring points must have their referenced entities filled.
     const requiredEntityIds = new Set();
     for (const p of chapter.points) {
@@ -131,11 +203,6 @@ export async function fillChapter(llm, chapter, ctx, budgetTokens) {
         }
     }
     const tokens = estimateTokens(cleanNarrative) + estimateTokens(JSON.stringify(entities));
-    // Input-side budget guard: reject clearly-over-budget inputs (decision 6/P6 hard gate).
-    const maxInputTokens = budgetTokens ? budgetTokens * 4 : undefined;
-    if (maxInputTokens !== undefined && estimatedTokens > maxInputTokens) {
-        return { ok: false, error: `Chapter "${chapter.id}" input context ${estimatedTokens} tokens exceeds 4× output budget` };
-    }
     if (budgetTokens !== undefined && tokens > budgetTokens) {
         return { ok: false, error: `Chapter "${chapter.id}" output ${tokens} tokens exceeds budget ${budgetTokens}` };
     }
@@ -150,9 +217,14 @@ export async function shouldFillOnce(outline, ctx) {
         return false;
     const budget = outline.fill_once.input_budget_tokens ?? 8000;
     let total = 0;
-    for (const ch of outline.chapters) {
-        const { estimatedTokens } = await buildChapterContext(ch, ctx);
-        total += estimatedTokens;
+    try {
+        for (const ch of outline.chapters) {
+            const { estimatedTokens } = await buildChapterContext(ch, ctx);
+            total += estimatedTokens;
+        }
+    }
+    catch {
+        return false; // 上下文构建失败 → 回退 per-chapter（P2）
     }
     return total <= budget;
 }
@@ -161,15 +233,27 @@ const FILL_ONCE_SYSTEM = '你是方案文档撰写员。一次填完全部章节
     '每章内容必须差异化（针对该章要点），禁止复制同一段到所有章节。契约实体须含 failure_examples（接口）/ddl（表）。';
 export async function fillOnce(llm, outline, ctx) {
     // Build a single combined context (all chapters) — bounded by shouldFillOnce pre-check.
-    const sections = [];
-    for (const ch of outline.chapters) {
-        const { input } = await buildChapterContext(ch, ctx);
-        sections.push(input.messages[0].content);
-    }
-    const res = await llm.complete({
-        system: FILL_ONCE_SYSTEM,
-        messages: [{ role: 'user', content: sections.join('\n\n=====\n\n') }],
-    });
+    // try/catch（P2）：上下文构建与 LLM 调用任一抛错都应回退 per-chapter，而不是穿透崩溃。
+    let res;
+    try {
+        const sections = [];
+        for (const ch of outline.chapters) {
+            const { input } = await buildChapterContext(ch, ctx);
+            sections.push(input.messages[0].content);
+        }
+        res = await llm.complete({
+            system: FILL_ONCE_SYSTEM,
+            messages: [{ role: 'user', content: sections.join('\n\n=====\n\n') }],
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            chapters: [],
+            fellBackToPerChapter: true,
+            error: `fill_once: context build or LLM call failed (${e instanceof Error ? e.message : String(e)})`,
+        };
+    }
     const content = res.content.trim();
     // Parse structured per-chapter output; fall back to per-chapter fill on parse failure.
     try {

package/dist/core/document/outline.d.ts

@@ -8,6 +8,7 @@
 import { Outline, ScenarioProfile } from './schemas.js';
 import type { DocumentLLM } from './llm.js';
 import { GlobalInputDigest } from './input-digest.js';
+import { ExtractedContracts } from './extract.js';
 export interface OutlineDiagnostic {
     code: string;
     severity: 'error' | 'warning';
@@ -18,6 +19,8 @@ export interface GenerateOutlineOptions {
     profile: ScenarioProfile;
     inputDigest: GlobalInputDigest;
     prompt?: string;
+    /** 工程契约候选（grounding P0 确定性提取）：冻结实体名供大纲注册表引用，禁止改名/编造。 */
+    extractedContracts?: ExtractedContracts;
 }
 export declare function generateOutline(llm: DocumentLLM, options: GenerateOutlineOptions): Promise<Outline>;
 export declare function lintOutline(outline: Outline, profile: ScenarioProfile): OutlineDiagnostic[];

package/dist/core/document/outline.js

@@ -11,9 +11,34 @@ import { parseOutline } from './schemas.js';
 const DEFAULT_PROMPT = '你是文档大纲设计专家。基于全局输入摘要与场景 Profile 约束，生成结构化文档大纲。见 prompts/document/outline/general.md。';
 const OUTLINE_SYSTEM = '你是文档大纲设计专家。严格按输入要求输出 JSON 大纲，满足所有硬规则（章节约束/要点 kind/references 完整性/source_segments）。';
 // ============= Generation (T5.2) =============
+/** 剥离 LLM 输出中的 ```json 围栏与前后缀文本（P2：与 map.ts 的围栏处理一致）。 */
+function extractJsonBlock(content) {
+    const trimmed = content.trim();
+    const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence)
+        return fence[1].trim();
+    // 无围栏：尝试取首个平衡 {...} 块（容忍前后缀说明文字）。
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start >= 0 && end > start)
+        return trimmed.slice(start, end + 1);
+    return trimmed;
+}
 export async function generateOutline(llm, options) {
     const { profile, inputDigest } = options;
     const prompt = options.prompt ?? DEFAULT_PROMPT;
+    const extracted = options.extractedContracts;
+    // Grounding 注入：工程契约候选（事实）。大纲注册表必须原样引用这些 frozen 名，
+    // 禁止改名/编造；无提取时该段省略（行为与旧版一致）。
+    const extractedBlock = extracted && (extracted.interfaces.length > 0 || extracted.tables.length > 0)
+        ? [
+            `## 工程契约候选（确定性提取，事实）`,
+            `以下实体来自工程数据源（OpenAPI/proto/DDL），是已确认的事实：`,
+            ...extracted.interfaces.map((it) => `- ${it.id} (${it.method} ${it.path}) name=${it.name}${it.request_fields?.length ? ` request=[${it.request_fields.map((f) => `${f.name}:${f.type}`).join(', ')}]` : ''}${it.response_fields?.length ? ` response=[${it.response_fields.map((f) => `${f.name}:${f.type}`).join(', ')}]` : ''}`),
+            ...extracted.tables.map((tb) => `- ${tb.id} (table) name=${tb.name} fields=[${tb.fields?.map((f) => `${f.name}:${f.type}`).join(', ') ?? ''}]`),
+            `规则：大纲 entities 注册表引用这些实体时，frozen 必须使用上述 name；references 用上述 id；禁止新增同名异义实体。`,
+        ].join('\n')
+        : '';
     const input = {
         system: OUTLINE_SYSTEM,
         messages: [
@@ -24,23 +49,31 @@ export async function generateOutline(llm, options) {
                     `Profile: ${JSON.stringify(profile)}`,
                     `全局输入摘要: ${inputDigest.summary}`,
                     `段摘要: ${inputDigest.segments.map((s) => `[${s.id}] ${s.summary}`).join('\n')}`,
-                ].join('\n\n'),
+                    extractedBlock,
+                ].filter(Boolean).join('\n\n'),
             },
         ],
     };
-    // Retry up to 2 times on parse failure.
-    let lastErr;
+    // Retry up to 2 times on PARSE failure only（P2）：LLM 服务/传输错误（限流/5xx）立即抛出，
+    // 不背靠背重试放大延迟与成本；确定性解析错误才重试。
+    let lastParseErr;
     for (let attempt = 0; attempt < 3; attempt++) {
+        let res;
         try {
-            const res = await llm.complete(input);
-            const outline = parseOutline(JSON.parse(res.content));
+            res = await llm.complete(input);
+        }
+        catch (e) {
+            throw new Error(`generateOutline: LLM call failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        try {
+            const outline = parseOutline(JSON.parse(extractJsonBlock(res.content)));
             return outline;
         }
         catch (e) {
-            lastErr = e;
+            lastParseErr = e;
         }
     }
-    throw new Error(`generateOutline: failed to parse outline after retries: ${lastErr}`);
+    throw new Error(`generateOutline: failed to parse outline after retries: ${lastParseErr}`);
 }
 // ============= Lint (T5.3) =============
 export function lintOutline(outline, profile) {
@@ -73,15 +106,25 @@ export function lintOutline(outline, profile) {
             seenP.add(p.id);
         }
     }
+    // 4b. Duplicate entity ids in registry（P2）：重复注册会被 Set 静默折叠，正向引用校验失效。
+    const seenEntity = new Set();
+    for (const e of outline.entities) {
+        if (seenEntity.has(e.id))
+            diags.push({ code: 'duplicate_entity', severity: 'error', message: `Duplicate entity "${e.id}" in registry` });
+        seenEntity.add(e.id);
+    }
     const entityIds = new Set(outline.entities.map((e) => e.id));
     // 5. References forward: point references must exist in entity registry.
-    // 6. Kind consistency: references present → kind must not be narrative; ≤3 refs per point.
+    // 6. Kind consistency: references present → kind must not be narrative; ≤3 unique refs per point.
     for (const ch of outline.chapters) {
         for (const p of ch.points) {
-            const refs = p.references ?? [];
+            const refs = [...new Set(p.references ?? [])]; // 去重（P2：重复引用不误触 ≤3 门禁）
             if (refs.length > 3) {
                 diags.push({ code: 'too_many_references', severity: 'error', chapter: ch.id, message: `Point "${p.id}" references >3 entities` });
             }
+            if ((p.references ?? []).length !== refs.length) {
+                diags.push({ code: 'duplicate_reference', severity: 'warning', chapter: ch.id, message: `Point "${p.id}" has duplicate references` });
+            }
             for (const ref of refs) {
                 if (!entityIds.has(ref)) {
                     diags.push({ code: 'reference_unknown', severity: 'error', chapter: ch.id, message: `Point "${p.id}" references unknown entity "${ref}"` });

package/dist/core/document/paths.d.ts

@@ -9,15 +9,15 @@ export interface DocumentPaths {
     outline: string;
     entities: string;
     chaptersDir: string;
-    segmentsDir: string;
-    digestsDir: string;
-    hashes: string;
-    reviewResult: string;
     documentMd: string;
     documentHtml: string;
 }
 /** Resolve all engine artifact paths under a caller-provided work root. */
 export declare function resolvePaths(workRoot: string): DocumentPaths;
+/** 章节 id 白名单：仅允许安全标识符，拒绝路径分隔符/`..`/空串（防路径穿越，P0-3）。 */
+export declare const CHAPTER_ID_RE: RegExp;
+export declare function assertChapterId(chapterId: string): void;
 export declare function chapterPath(workRoot: string, chapterId: string): string;
-export declare function digestPath(workRoot: string, chapterId: string): string;
+/** Multi-repo synthesize marker: list of repo names (written by document synthesize). */
+export declare function reposPath(workRoot: string): string;
 export declare function segmentIndexPath(workRoot: string): string;

package/dist/core/document/paths.js

@@ -12,19 +12,24 @@ export function resolvePaths(workRoot) {
         outline: join(workRoot, 'outline.yaml'),
         entities: join(workRoot, 'entities.json'),
         chaptersDir: join(workRoot, 'chapters'),
-        segmentsDir: join(workRoot, 'segments'),
-        digestsDir: join(workRoot, 'digests'),
-        hashes: join(workRoot, 'hashes.json'),
-        reviewResult: join(workRoot, 'review-result.json'),
         documentMd: join(workRoot, 'document.md'),
         documentHtml: join(workRoot, 'document.html'),
     };
 }
+/** 章节 id 白名单：仅允许安全标识符，拒绝路径分隔符/`..`/空串（防路径穿越，P0-3）。 */
+export const CHAPTER_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+export function assertChapterId(chapterId) {
+    if (!CHAPTER_ID_RE.test(chapterId)) {
+        throw new Error(`Invalid chapter id "${chapterId}": must match ${CHAPTER_ID_RE}`);
+    }
+}
 export function chapterPath(workRoot, chapterId) {
+    assertChapterId(chapterId);
     return join(workRoot, 'chapters', `${chapterId}.md`);
 }
-export function digestPath(workRoot, chapterId) {
-    return join(workRoot, 'digests', `${chapterId}.md`);
+/** Multi-repo synthesize marker: list of repo names (written by document synthesize). */
+export function reposPath(workRoot) {
+    return join(workRoot, 'repos.json');
 }
 export function segmentIndexPath(workRoot) {
     return join(workRoot, 'segments', 'index.json');

package/dist/core/document/profile-validator.js

@@ -36,11 +36,37 @@ export function validateProfile(options) {
             message: `Profile "${profile.id}" must declare at least one required chapter`,
         });
     }
+    // 2b. 分类冲突（P2）：同一章节出现在 required∩forbidden / optional∩forbidden 时，
+    // expandProfile 会静默从 selected 删除，必需章节凭空消失。加载期即报错。
+    const requiredSet = new Set(profile.required);
+    const optionalSet = new Set(profile.optional_candidates);
+    for (const id of profile.forbidden) {
+        if (requiredSet.has(id)) {
+            diags.push({ code: 'category_conflict', severity: 'error', chapter: id, message: `Chapter "${id}" is in both required and forbidden` });
+        }
+        if (optionalSet.has(id)) {
+            diags.push({ code: 'category_conflict', severity: 'error', chapter: id, message: `Chapter "${id}" is in both optional_candidates and forbidden` });
+        }
+    }
+    // 2c. 数组内重复 id。
+    for (const [label, list] of [['required', profile.required], ['optional_candidates', profile.optional_candidates], ['forbidden', profile.forbidden], ['shared', profile.shared]]) {
+        const seenIds = new Set();
+        for (const id of list) {
+            if (seenIds.has(id)) {
+                diags.push({ code: 'duplicate_id', severity: 'warning', chapter: id, message: `Chapter "${id}" appears more than once in ${label}` });
+            }
+            seenIds.add(id);
+        }
+    }
     // 3+4. Dependency closure + acyclic over the selected chapters.
     //    A chapter may depend on: another selected chapter, a shared chapter, or a chapter in
     //    required/optional that we include in the closure graph.
+    //    closure 检查覆盖 required + optional_candidates（P2）：可选章节是 LLM 可能选中的
+    //    渲染章节，其悬空依赖必须报错；shared 章节仅作依赖闭合、不渲染，其 depends_on
+    //    不需要闭包（引擎不会填充 shared 章节）。
     const closureNodes = new Set([...profile.required, ...profile.optional_candidates, ...profile.shared]);
-    for (const id of profile.required) {
+    const renderedIds = [...profile.required, ...profile.optional_candidates];
+    for (const id of renderedIds) {
         const ch = library.get(id);
         if (!ch)
             continue;
@@ -56,6 +82,7 @@ export function validateProfile(options) {
         }
     }
     // Acyclic check via Kahn's algorithm on selected + shared nodes.
+    // 注意：不再排除自依赖（dep !== n 过滤已删除，P2）——自环必须被正确判为环。
     const nodes = [...closureNodes].filter((n) => library.has(n));
     const indegree = new Map();
     const adj = new Map();
@@ -66,7 +93,7 @@ export function validateProfile(options) {
     for (const n of nodes) {
         const ch = library.get(n);
         for (const dep of ch.depends_on) {
-            if (closureNodes.has(dep) && library.has(dep) && dep !== n) {
+            if (closureNodes.has(dep) && library.has(dep)) {
                 adj.get(dep).push(n);
                 indegree.set(n, (indegree.get(n) ?? 0) + 1);
             }
@@ -93,8 +120,9 @@ export function validateProfile(options) {
             });
         }
     }
-    // 5. When-usable: every when expression must parse and reference known features.
-    for (const id of [...profile.required, ...profile.optional_candidates]) {
+    // 5. When-usable: every when expression must parse and reference known input features.
+    //    （覆盖 shared 章节，P2；未知 feature 提级为 error——拼错 feature 会静默丢章节）
+    for (const id of [...profile.required, ...profile.optional_candidates, ...profile.shared]) {
         const ch = library.get(id);
         if (!ch?.when)
             continue;
@@ -104,7 +132,7 @@ export function validateProfile(options) {
                 if (!isKnownFeature(f)) {
                     diags.push({
                         code: 'when_unknown_feature',
-                        severity: 'warning',
+                        severity: 'error',
                         chapter: id,
                         message: `when expression of chapter "${id}" references unknown input feature "${f}"`,
                     });

package/dist/core/document/profiles.js

@@ -10,7 +10,12 @@ import { parseScenarioProfile } from './schemas.js';
 import { validateProfile, hasErrors } from './profile-validator.js';
 import { evaluateWhen } from './input-features.js';
 const DEFAULT_PROFILES_DIR = join(process.cwd(), 'templates', 'document', 'profiles');
+/** profile id 白名单（P2）：拒绝路径穿越（../、绝对路径）。 */
+const PROFILE_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 export async function loadProfile(profileId, dir = DEFAULT_PROFILES_DIR) {
+    if (!PROFILE_ID_RE.test(profileId)) {
+        throw new Error(`Invalid profile id "${profileId}": must match ${PROFILE_ID_RE}`);
+    }
     const raw = yaml.load(await fs.readFile(join(dir, `${profileId}.yaml`), 'utf-8'));
     return parseScenarioProfile(raw);
 }

package/dist/core/document/render.d.ts

@@ -6,14 +6,40 @@
  * Optional HTML render reuses `marked`.
  */
 import { Outline, Entities, InterfaceEntity, TableEntity } from './schemas.js';
+/** HTML 转义：用于 <title>/<h1> 插值（防存储型 XSS）。 */
+export declare function escapeHtml(s: string): string;
+/** Markdown 表格单元格转义：转义 | 与换行（防破坏列对齐/拆行）。 */
+export declare function escapeTableCell(s: string): string;
+/** 代码围栏内容转义：把可能提前终止 ``` 围栏的行替换为安全形式。 */
+export declare function escapeFenceContent(s: string): string;
+/** 单行内联文本：转义换行，避免注入新标题/新行。 */
+export declare function escapeInline(s: string): string;
 export declare function renderInterface(i: InterfaceEntity): string;
 export declare function renderTable(t: TableEntity): string;
+export declare function renderDecisions(decisions: Array<{
+    id: string;
+    text: string;
+}>): string;
 export declare function renderEntities(entities: Entities): string;
 export interface RenderDocumentInput {
     outline: Outline;
     entities: Entities;
     /** chapterId → narrative markdown */
     narratives: Map<string, string>;
+    /** Scenario profile — drives appendices rendering (profile.appendices, §7.2/7.3). */
+    profile?: {
+        appendices?: string[];
+    };
+    /** LLM-written anti-AI self-check items (from appendices/anti-ai.md, optional). */
+    appendixAntiAI?: string;
 }
+/** Strip engine repair notes (`<!-- review-fix ... -->`) from the FINAL render. The audit trail
+ *  stays in `chapters/<id>.md` and `review-result.json`; the deliverable document must not show
+ *  internal fix notes. */
+export declare function stripReviewNotes(text: string): string;
 export declare function renderDocument(input: RenderDocumentInput): string;
+/** 附录 B · 去AI味自检（frontend-dev-guide §十一 → README §1.6 五维表）。 */
+export declare function renderAppendixAntiAI(content?: string): string;
+/** 附录 C · 下游交付衔接（frontend-dev-guide §八 → README §1.5 矩阵 + 三步）。 */
+export declare function renderAppendixHandoff(): string;
 export declare function renderHtml(markdown: string, title?: string): Promise<string>;