spectra-cli 4.1.1

package/dist/panoramic/pipelines/product-ux-docs.js

@@ -0,0 +1,959 @@
+/**
+ * Product / UX fact ingestion
+ *
+ * Feature 060: 将 current-spec、README/设计说明与近期提交
+ * 汇总为产品概览、用户旅程与 feature brief 文档。
+ *
+ * 设计原则：
+ * 1. current-spec 是首选事实源；README / 设计文档为补充源
+ * 2. 文档生成完全基于仓库内容，不依赖外部 API 或 CLI
+ * 3. narrative 与 journey/brief synthesis 必须保留 evidence / confidence / inferred
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadTemplate } from '../utils/template-loader.js';
+import { createLogger } from '../utils/logger.js';
+import { truncateAtNaturalBoundary, isDescriptiveText, } from '../utils/text-segmenter.js';
+import { sanitizeMarkdownContent } from '../utils/html-sanitizer.js';
+const logger = createLogger('product-ux-docs');
+export function generateProductUxDocs(options) {
+    const corpus = buildProductFactCorpus(options.projectRoot);
+    const overview = buildProductOverview(corpus);
+    const journeys = buildUserJourneys(corpus, overview);
+    const featureBriefIndex = buildFeatureBriefIndex(corpus, overview, journeys);
+    const writtenFiles = [];
+    writtenFiles.push(...writeOverview(options.outputDir, overview));
+    writtenFiles.push(...writeJourneys(options.outputDir, journeys));
+    writtenFiles.push(...writeFeatureBriefs(options.outputDir, featureBriefIndex));
+    return {
+        overview,
+        journeys,
+        featureBriefIndex,
+        warnings: uniqueSorted([
+            ...corpus.warnings,
+            ...overview.warnings,
+            ...journeys.warnings,
+            ...featureBriefIndex.warnings,
+        ]),
+        writtenFiles,
+    };
+}
+function writeOverview(outputDir, overview) {
+    const mdPath = path.join(outputDir, 'product-overview.md');
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(mdPath, renderProductOverview(overview), 'utf-8');
+    return [mdPath];
+}
+function writeJourneys(outputDir, journeys) {
+    const mdPath = path.join(outputDir, 'user-journeys.md');
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(mdPath, renderUserJourneys(journeys), 'utf-8');
+    return [mdPath];
+}
+function writeFeatureBriefs(outputDir, index) {
+    const briefsDir = path.join(outputDir, 'feature-briefs');
+    const writtenFiles = [];
+    fs.mkdirSync(briefsDir, { recursive: true });
+    const indexMd = path.join(briefsDir, 'index.md');
+    fs.writeFileSync(indexMd, renderFeatureBriefIndex(index), 'utf-8');
+    writtenFiles.push(indexMd);
+    for (const brief of index.briefs) {
+        const mdPath = path.join(briefsDir, `${brief.fileName}.md`);
+        fs.writeFileSync(mdPath, renderFeatureBrief(brief), 'utf-8');
+        writtenFiles.push(mdPath);
+    }
+    return writtenFiles;
+}
+function renderProductOverview(output) {
+    return loadTemplate('product-overview.hbs', import.meta.url)(output);
+}
+function renderUserJourneys(output) {
+    return loadTemplate('user-journeys.hbs', import.meta.url)(output);
+}
+function renderFeatureBriefIndex(output) {
+    return loadTemplate('feature-brief-index.hbs', import.meta.url)(output);
+}
+function renderFeatureBrief(output) {
+    return loadTemplate('feature-brief.hbs', import.meta.url)(output);
+}
+function buildProductFactCorpus(projectRoot) {
+    const currentSpecs = collectCurrentSpecs(projectRoot);
+    const readmes = collectReadmes(projectRoot);
+    const designDocs = collectLocalDesignDocs(projectRoot);
+    const commits = collectRecentCommits(projectRoot, 10);
+    const warnings = uniqueSorted([
+        ...(currentSpecs.length === 0
+            ? ['未找到 current-spec.md，将更多依赖 README 与设计文档进行产品事实推断。']
+            : []),
+        ...(readmes.length === 0
+            ? ['未找到项目级 README.md，产品定位摘要将缺少一份高价值补充源。']
+            : []),
+        ...(designDocs.length === 0
+            ? ['未找到本地设计说明/roadmap Markdown，UX 旅程与 feature brief 将更多依赖 current-spec 与 README。']
+            : []),
+    ]);
+    return {
+        projectName: resolveProjectName(projectRoot, currentSpecs, readmes),
+        currentSpecs,
+        readmes,
+        designDocs,
+        commits,
+        warnings,
+    };
+}
+function buildProductOverview(corpus) {
+    const summary = collectOverviewParagraphs(corpus).slice(0, 4);
+    const targetUsers = buildTargetUsers(corpus);
+    const coreScenarios = buildCoreScenarios(corpus, targetUsers);
+    const evidence = uniqueEvidence([
+        ...collectEvidenceFromSources(corpus.currentSpecs, 'high'),
+        ...collectEvidenceFromSources(corpus.readmes, 'medium'),
+        ...collectEvidenceFromSources(corpus.designDocs, 'medium'),
+    ]);
+    const warnings = uniqueSorted([
+        ...corpus.warnings,
+        ...(summary.length === 0
+            ? ['未提取到稳定的产品概述段落，product-overview 将更多依赖推断和标题级摘要。']
+            : []),
+        ...(targetUsers.length === 0
+            ? ['未识别到显式用户画像表或用户段落，将使用 README / issue 文本推断目标用户。']
+            : []),
+        ...(coreScenarios.length === 0
+            ? ['未识别到显式核心场景列表，将使用 feature briefs 和 README 文本推断核心任务流。']
+            : []),
+    ]);
+    const inferred = corpus.currentSpecs.length === 0;
+    return {
+        title: `产品概览: ${corpus.projectName}`,
+        generatedAt: new Date().toISOString(),
+        projectName: corpus.projectName,
+        summary: summary.length > 0
+            ? summary
+            : ['仅基于代码与现有规格推断；尚未找到足够稳定的产品事实源。'],
+        targetUsers,
+        coreScenarios,
+        keyTaskFlows: coreScenarios.slice(0, 5).map((scenario) => scenario.title),
+        warnings,
+        confidence: currentSpecConfidence(corpus.currentSpecs.length > 0, evidence.length),
+        inferred,
+        evidence,
+    };
+}
+function buildUserJourneys(corpus, overview) {
+    const journeys = overview.coreScenarios.slice(0, 5).map((scenario, index) => {
+        const actor = scenario.actors[0] ?? overview.targetUsers[0]?.name ?? '使用者';
+        const detail = scenario.summary || scenario.title;
+        return {
+            id: `journey-${String(index + 1).padStart(2, '0')}`,
+            title: scenario.title,
+            actor,
+            goal: detail,
+            outcome: deriveOutcomeFromScenario(scenario, actor),
+            steps: [
+                {
+                    title: '触发场景',
+                    detail: deriveTriggerFromScenario(scenario, actor),
+                    inferred: true,
+                },
+                {
+                    title: '执行关键动作',
+                    detail,
+                    inferred: false,
+                },
+                {
+                    title: '消费输出',
+                    detail: deriveConsumptionFromScenario(scenario),
+                    inferred: true,
+                },
+            ],
+            evidence: scenario.evidence,
+            confidence: scenario.confidence,
+            inferred: true,
+        };
+    });
+    const warnings = uniqueSorted([
+        ...corpus.warnings,
+        ...(journeys.length === 0
+            ? ['未识别到可稳定组织成用户旅程的场景，user-journeys 将为空。']
+            : []),
+    ]);
+    return {
+        title: `用户旅程: ${corpus.projectName}`,
+        generatedAt: new Date().toISOString(),
+        projectName: corpus.projectName,
+        summary: journeys.length > 0
+            ? [`基于 ${journeys.length} 条核心场景组织用户旅程，优先引用 current-spec、README 与本地设计文档事实。`]
+            : ['仅基于代码与现有规格推断；尚未识别到稳定的用户旅程输入。'],
+        journeys,
+        warnings,
+        confidence: currentSpecConfidence(corpus.currentSpecs.length > 0, journeys.length),
+    };
+}
+function buildFeatureBriefIndex(corpus, overview, journeys) {
+    const briefs = [];
+    for (const scenario of journeys.journeys.slice(0, 3)) {
+        const id = `BRIEF-${String(briefs.length + 1).padStart(2, '0')}`;
+        briefs.push({
+            id,
+            slug: slugify(scenario.title),
+            fileName: briefFileName(id, scenario.title),
+            title: scenario.title,
+            summary: scenario.goal,
+            problem: `${scenario.actor} 需要更直接地完成”${scenario.title}”相关任务，当前缺少独立的功能说明文档。`,
+            proposedSolution: `围绕 ${scenario.title} 组织一份产品 brief，把用户目标、路径和预期输出显式化。`,
+            audience: scenario.actor,
+            status: 'candidate',
+            evidence: scenario.evidence,
+            confidence: 'medium',
+            inferred: true,
+        });
+    }
+    return {
+        title: `Feature Briefs: ${corpus.projectName}`,
+        generatedAt: new Date().toISOString(),
+        projectName: corpus.projectName,
+        summary: [
+            `共组织 ${briefs.length} 份 feature brief，基于 current-spec 与用户旅程派生。`,
+        ],
+        briefs: briefs.slice(0, 5),
+        warnings: [...corpus.warnings],
+        confidence: currentSpecConfidence(corpus.currentSpecs.length > 0, briefs.length),
+    };
+}
+function collectCurrentSpecs(projectRoot) {
+    const currentSpecs = [];
+    const productsDir = path.join(projectRoot, 'specs', 'products');
+    if (!fs.existsSync(productsDir)) {
+        return currentSpecs;
+    }
+    for (const entry of fs.readdirSync(productsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const filePath = path.join(productsDir, entry.name, 'current-spec.md');
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+        const text = fs.readFileSync(filePath, 'utf-8');
+        currentSpecs.push({
+            sourceType: 'current-spec',
+            label: `${entry.name}/current-spec.md`,
+            path: normalizeProjectPath(filePath, projectRoot),
+            text,
+            productId: entry.name,
+            sections: parseMarkdownSections(text),
+        });
+    }
+    return currentSpecs.sort((left, right) => left.productId.localeCompare(right.productId));
+}
+function collectReadmes(projectRoot) {
+    const readmes = [];
+    for (const candidate of ['README.md', 'readme.md']) {
+        const filePath = path.join(projectRoot, candidate);
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+        readmes.push({
+            sourceType: 'readme',
+            label: candidate,
+            path: normalizeProjectPath(filePath, projectRoot),
+            text: fs.readFileSync(filePath, 'utf-8'),
+        });
+    }
+    return readmes;
+}
+function collectLocalDesignDocs(projectRoot) {
+    const matches = [];
+    walkMarkdownDocs(projectRoot, projectRoot, matches);
+    return matches.sort((left, right) => left.path.localeCompare(right.path));
+}
+function walkMarkdownDocs(root, dir, results) {
+    if (!fs.existsSync(dir)) {
+        return;
+    }
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        const relative = normalizeProjectPath(fullPath, root);
+        if (entry.isDirectory()) {
+            if (['node_modules', '.git', 'specs', 'dist', 'coverage', 'bundles'].includes(entry.name)
+                || entry.name.startsWith('.spectra')) {
+                continue;
+            }
+            walkMarkdownDocs(root, fullPath, results);
+            continue;
+        }
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) {
+            continue;
+        }
+        const lower = relative.toLowerCase();
+        const isRootReadme = lower === 'readme.md';
+        const isGeneratedOutput = /(^|\/)\.spectra[^/]*\//i.test(lower)
+            || /(^|\/)docs\/adr\//i.test(lower)
+            || /(^|\/)feature-briefs\//i.test(lower);
+        const isDesignLike = /(design|product|roadmap|journey|ux|persona|brief|architecture|arch|notes|overview|guide|system|model|diagram)/i.test(entry.name)
+            || /(^|\/)(design|product|roadmap|journey|ux|persona|brief|architecture|arch|notes|overview|guide|system|model|diagram)s?\//i.test(lower);
+        if (!isDesignLike || isRootReadme || isGeneratedOutput) {
+            continue;
+        }
+        results.push({
+            sourceType: 'design-doc',
+            label: path.basename(fullPath),
+            path: relative,
+            text: fs.readFileSync(fullPath, 'utf-8'),
+        });
+    }
+}
+function collectRecentCommits(projectRoot, limit) {
+    const result = spawnSync('git', ['log', `-${limit}`, '--pretty=format:%H%n%s%n%b%n---END-COMMIT---'], {
+        cwd: projectRoot,
+        encoding: 'utf-8',
+    });
+    if (result.status !== 0 || !result.stdout) {
+        return [];
+    }
+    return result.stdout
+        .split('\n---END-COMMIT---\n')
+        .map((chunk) => chunk.trim())
+        .filter((chunk) => chunk.length > 0)
+        .map((chunk) => {
+        const [sha = '', subject = '', ...bodyLines] = chunk.split('\n');
+        return {
+            sha: sha.trim(),
+            subject: subject.trim(),
+            body: bodyLines.join('\n').trim(),
+        };
+    })
+        .filter((entry) => entry.sha.length > 0 && entry.subject.length > 0);
+}
+function collectOverviewParagraphs(corpus) {
+    const paragraphs = [];
+    for (const spec of corpus.currentSpecs) {
+        for (const key of ['产品概述', '概览']) {
+            const section = spec.sections.get(key);
+            if (!section) {
+                continue;
+            }
+            paragraphs.push(...extractParagraphs(section));
+        }
+    }
+    for (const source of [...corpus.readmes, ...corpus.designDocs]) {
+        paragraphs.push(...extractParagraphs(source.text).slice(0, 2));
+    }
+    // 当 current-spec 与 README 均不足时，以近期 commit subject 作为补充事实证据
+    if (paragraphs.length < 2 && corpus.commits.length > 0) {
+        const commitSummary = corpus.commits
+            .slice(0, 5)
+            .map((commit) => commit.subject)
+            .filter((subject) => subject.length >= 10)
+            .join('；');
+        if (commitSummary.length >= 20) {
+            paragraphs.push(`近期变更摘要（基于 git 提交记录推断）：${commitSummary}`);
+        }
+    }
+    return uniqueSorted(paragraphs.filter((paragraph) => paragraph.length >= 20)).slice(0, 6);
+}
+function buildTargetUsers(corpus) {
+    const segments = [];
+    for (const spec of corpus.currentSpecs) {
+        const userSection = spec.sections.get('用户画像与场景');
+        if (!userSection) {
+            continue;
+        }
+        const rows = parseFirstMarkdownTable(userSection);
+        for (const row of rows) {
+            const name = row['角色'] || row['用户'] || row['名称'] || row['persona'] || '';
+            const description = row['描述'] || row['说明'] || row['description'] || '';
+            const scenarios = splitScenarioText(row['主要使用场景'] || row['场景'] || row['scenario'] || '');
+            if (!name.trim()) {
+                continue;
+            }
+            segments.push({
+                name: name.trim(),
+                description: description.trim() || `${name.trim()} 是该产品的关键使用者。`,
+                primaryScenarios: scenarios,
+                evidence: [{
+                        sourceType: 'current-spec',
+                        label: spec.label,
+                        path: spec.path,
+                        excerpt: `${name} | ${description} | ${scenarios.join(' / ')}`,
+                        confidence: 'high',
+                        inferred: false,
+                    }],
+                confidence: 'high',
+            });
+        }
+    }
+    if (segments.length > 0) {
+        return dedupeSegments(segments);
+    }
+    const readmeParagraph = corpus.readmes
+        .flatMap((source) => extractParagraphs(source.text))
+        .find((para) => isDescriptiveParagraph(para));
+    if (!readmeParagraph) {
+        return [];
+    }
+    return [{
+            name: '开发者',
+            description: firstSentence(readmeParagraph) ?? readmeParagraph,
+            primaryScenarios: ['阅读文档、生成规格、理解系统行为'],
+            evidence: [{
+                    sourceType: 'readme',
+                    label: corpus.readmes[0].label,
+                    path: corpus.readmes[0].path,
+                    excerpt: readmeParagraph,
+                    confidence: 'medium',
+                    inferred: true,
+                }],
+            confidence: 'medium',
+        }];
+}
+/**
+ * 判断一段文字是否是有意义的描述性段落（非标题、非导航链接）。
+ * Feature 125: 委托给 Unicode 感知的 isDescriptiveText，按字符数判断链接密度，
+ * 避免按 ASCII 空格分词导致中文段落被误过滤。
+ */
+function isDescriptiveParagraph(text) {
+    return isDescriptiveText(text, { minLength: 30, linkThreshold: 0.5 });
+}
+function buildCoreScenarios(corpus, targetUsers) {
+    const scenarios = [];
+    for (const spec of corpus.currentSpecs) {
+        const userSection = spec.sections.get('用户画像与场景');
+        if (!userSection) {
+            continue;
+        }
+        const items = extractListItems(userSection);
+        for (const item of items) {
+            const [titlePart, ...restParts] = item.split(/[:：]/);
+            const title = titlePart?.trim() || item;
+            const summary = restParts.join('：').trim() || item;
+            const actors = inferActors(title + summary, targetUsers);
+            scenarios.push({
+                id: `scenario-${scenarios.length + 1}`,
+                title,
+                summary,
+                actors,
+                evidence: [{
+                        sourceType: 'current-spec',
+                        label: spec.label,
+                        path: spec.path,
+                        excerpt: item,
+                        confidence: 'high',
+                        inferred: false,
+                    }],
+                confidence: 'high',
+                inferred: false,
+            });
+        }
+    }
+    // README Usage/Features 节 fallback
+    if (scenarios.length === 0) {
+        scenarios.push(...extractScenariosFromReadme(corpus, targetUsers));
+    }
+    // Phase 3：从 README Features/How it works 等标题下提取叙述段落场景
+    if (scenarios.length === 0) {
+        for (const readme of corpus.readmes) {
+            scenarios.push(...extractScenariosFromReadme(readme, targetUsers));
+            if (scenarios.length >= 3)
+                break;
+        }
+    }
+    return dedupeScenarios(scenarios).slice(0, 6);
+}
+/**
+ * 从 README 提取场景：
+ * 1. corpus 模式优先读取 Features / Usage 等章节列表项
+ * 2. 单文档模式回退到叙述型标题段落与段落文本
+ */
+function extractScenariosFromReadme(source, targetUsers) {
+    if ('currentSpecs' in source) {
+        return extractScenariosFromReadmeCorpus(source, targetUsers);
+    }
+    return extractScenariosFromReadmeDocument(source, targetUsers);
+}
+function extractScenariosFromReadmeCorpus(corpus, targetUsers) {
+    const scenarios = [];
+    const sectionKeySet = new Set([
+        'usage', 'features', 'getting started', 'quick start', 'overview',
+        '使用', '使用方法', '功能', '快速开始', '特性',
+    ]);
+    for (const readme of corpus.readmes) {
+        const sections = parseMarkdownSections(readme.text);
+        for (const [rawKey, section] of sections) {
+            if (!sectionKeySet.has(rawKey.toLowerCase()))
+                continue;
+            const items = extractListItems(section);
+            for (const item of items.slice(0, 4)) {
+                if (item.length < 10)
+                    continue;
+                const [titlePart, ...restParts] = item.split(/[:：]/);
+                const title = titlePart?.trim() || item;
+                const summary = restParts.join('：').trim() || item;
+                scenarios.push({
+                    id: `scenario-${scenarios.length + 1}`,
+                    title: truncateAtNaturalBoundary(title, 80),
+                    summary: truncateAtNaturalBoundary(summary || title, 200),
+                    actors: [inferAudience(title, targetUsers) ?? targetUsers[0]?.name ?? '开发者'],
+                    evidence: [{
+                            sourceType: 'readme',
+                            label: readme.label,
+                            path: readme.path,
+                            excerpt: item,
+                            confidence: 'medium',
+                            inferred: true,
+                        }],
+                    confidence: 'medium',
+                    inferred: true,
+                });
+                if (scenarios.length >= 4)
+                    return scenarios;
+            }
+            if (scenarios.length >= 4)
+                return scenarios;
+        }
+        if (scenarios.length >= 4)
+            return scenarios;
+    }
+    return scenarios;
+}
+function extractScenariosFromReadmeDocument(readme, targetUsers) {
+    const FEATURE_HEADING = /^(Features?|How\s+it\s+works?|What\s+(?:it\s+)?does|Capabilities|Use\s+cases?|Getting\s+started|Overview|About)\s*$/i;
+    const scenarios = [];
+    const lines = readme.text.split('\n');
+    let inSection = false;
+    let sectionLines = [];
+    const sections = [];
+    for (const line of lines) {
+        const headingMatch = /^#{1,3}\s+(.+)$/.exec(line);
+        if (headingMatch) {
+            if (inSection && sectionLines.length > 0) {
+                sections.push(sectionLines.join('\n'));
+            }
+            inSection = FEATURE_HEADING.test(headingMatch[1]?.trim() ?? '');
+            sectionLines = [];
+        }
+        else if (inSection) {
+            sectionLines.push(line);
+        }
+    }
+    if (inSection && sectionLines.length > 0) {
+        sections.push(sectionLines.join('\n'));
+    }
+    for (const section of sections) {
+        const items = extractListItems(section);
+        if (items.length > 0) {
+            for (const item of items.slice(0, 4)) {
+                const colonIdx = item.search(/[:：]/);
+                const title = colonIdx > 0 ? item.slice(0, colonIdx).trim() : item;
+                const summary = colonIdx > 0 ? item.slice(colonIdx + 1).trim() : item;
+                scenarios.push({
+                    id: `scenario-${scenarios.length + 1}`,
+                    title,
+                    summary: summary || title,
+                    actors: inferActors(title + summary, targetUsers),
+                    evidence: [{
+                            sourceType: 'readme',
+                            label: readme.label,
+                            path: readme.path,
+                            excerpt: item,
+                            confidence: 'medium',
+                            inferred: true,
+                        }],
+                    confidence: 'medium',
+                    inferred: true,
+                });
+            }
+        }
+        else {
+            // 无列表时从段落提取
+            for (const para of extractParagraphs(section).slice(0, 2)) {
+                const title = firstSentence(para) ?? truncateAtNaturalBoundary(para, 60);
+                scenarios.push({
+                    id: `scenario-${scenarios.length + 1}`,
+                    title,
+                    summary: para,
+                    actors: inferActors(para, targetUsers),
+                    evidence: [{
+                            sourceType: 'readme',
+                            label: readme.label,
+                            path: readme.path,
+                            excerpt: para,
+                            confidence: 'low',
+                            inferred: true,
+                        }],
+                    confidence: 'low',
+                    inferred: true,
+                });
+            }
+        }
+        if (scenarios.length >= 3)
+            break;
+    }
+    return scenarios;
+}
+function parseMarkdownSections(markdown) {
+    const sections = new Map();
+    const matches = [...markdown.matchAll(/^##\s+(.+)$/gm)];
+    for (let index = 0; index < matches.length; index += 1) {
+        const current = matches[index];
+        const next = matches[index + 1];
+        if (current?.index == null) {
+            continue;
+        }
+        const rawHeading = current[1]?.trim() ?? '';
+        const start = current.index + current[0].length;
+        const end = next?.index ?? markdown.length;
+        const content = markdown.slice(start, end).trim();
+        const normalized = normalizeHeading(rawHeading);
+        if (normalized) {
+            sections.set(normalized, content);
+        }
+    }
+    return sections;
+}
+function normalizeHeading(heading) {
+    return heading
+        .replace(/^[0-9]+\.\s*/, '')
+        .replace(/^[一二三四五六七八九十]+\.\s*/, '')
+        .replace(/[：:]\s*$/, '')
+        .trim();
+}
+function parseFirstMarkdownTable(content) {
+    const lines = content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('|'));
+    if (lines.length < 3) {
+        return [];
+    }
+    const header = splitMarkdownTableLine(lines[0]);
+    const divider = lines[1];
+    if (!divider.includes('---')) {
+        return [];
+    }
+    return lines.slice(2).map((line) => {
+        const values = splitMarkdownTableLine(line);
+        const row = {};
+        for (let index = 0; index < header.length; index += 1) {
+            row[header[index] ?? `col-${index}`] = values[index] ?? '';
+        }
+        return row;
+    });
+}
+function splitMarkdownTableLine(line) {
+    return line
+        .split('|')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+}
+function extractListItems(content) {
+    return [...content.matchAll(/^(?:[-*]|\d+\.)\s+(.+)$/gm)]
+        .map((match) => match[1]?.trim() ?? '')
+        .filter((item) => item.length > 0);
+}
+function extractParagraphs(content) {
+    // 先做 block-level HTML 净化（保留行内尖括号如 Array<T>、<target>）
+    // 再 decode entity（&lt; → <），然后按段落切分
+    const sanitized = sanitizeMarkdownContent(content);
+    return sanitized
+        .split(/\n\s*\n/g)
+        .map((paragraph) => paragraph.replace(/\n+/g, ' ').trim())
+        .filter((paragraph) => paragraph.length >= 20
+        && !paragraph.startsWith('|')
+        && !paragraph.startsWith('##')
+        && !paragraph.startsWith('```')
+        && !isBadgeLine(paragraph)
+        && !isPureLinkLine(paragraph));
+}
+/** 是否为纯徽章行（仅含 ![...](url) 或 [![...](url)](url2) 无其他文字） */
+function isBadgeLine(text) {
+    // 先移除图片 ![...](...) 再移除剩余链接壳 [...](...) ，判断是否为空
+    const withoutImages = text.replace(/!\[[^\]]*\]\([^)]+\)/g, '');
+    const withoutAll = withoutImages.replace(/\[[^\]]*\]\([^)]+\)/g, '').trim();
+    return withoutAll.length === 0 && text.includes('![');
+}
+/** 是否为纯链接行（仅含 [...](url) 无其他文字） */
+function isPureLinkLine(text) {
+    const withoutLinks = text.replace(/\[[^\]]*\]\([^)]+\)/g, '').trim();
+    return withoutLinks.length === 0 && text.includes('](');
+}
+function splitScenarioText(value) {
+    return value
+        .split(/[、,，/]/)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function inferActors(text, users) {
+    const matched = users
+        .filter((user) => text.includes(user.name) || user.primaryScenarios.some((scenario) => text.includes(scenario)))
+        .map((user) => user.name);
+    if (matched.length > 0) {
+        return uniqueSorted(matched);
+    }
+    return users[0] ? [users[0].name] : [];
+}
+function inferAudience(title, users) {
+    return inferActors(title, users)[0];
+}
+function dedupeSegments(segments) {
+    const byName = new Map();
+    for (const segment of segments) {
+        const existing = byName.get(segment.name);
+        if (!existing) {
+            byName.set(segment.name, segment);
+            continue;
+        }
+        existing.description = existing.description.length >= segment.description.length
+            ? existing.description
+            : segment.description;
+        existing.primaryScenarios = uniqueSorted([...existing.primaryScenarios, ...segment.primaryScenarios]);
+        existing.evidence = uniqueEvidence([...existing.evidence, ...segment.evidence]);
+    }
+    return [...byName.values()];
+}
+function dedupeScenarios(scenarios) {
+    const byTitle = new Map();
+    for (const scenario of scenarios) {
+        const key = scenario.title.toLowerCase();
+        const existing = byTitle.get(key);
+        if (!existing) {
+            byTitle.set(key, scenario);
+            continue;
+        }
+        existing.summary = existing.summary.length >= scenario.summary.length ? existing.summary : scenario.summary;
+        existing.actors = uniqueSorted([...existing.actors, ...scenario.actors]);
+        existing.evidence = uniqueEvidence([...existing.evidence, ...scenario.evidence]);
+    }
+    return [...byTitle.values()];
+}
+function collectEvidenceFromSources(sources, confidence) {
+    return sources.slice(0, 3).map((source) => ({
+        sourceType: source.sourceType,
+        label: source.label,
+        path: source.path,
+        excerpt: extractParagraphs(source.text)[0] ?? source.text.slice(0, 160).trim(),
+        confidence,
+        inferred: false,
+    }));
+}
+function currentSpecConfidence(hasCurrentSpec, signalCount) {
+    if (hasCurrentSpec && signalCount >= 2) {
+        return 'high';
+    }
+    if (signalCount > 0) {
+        return 'medium';
+    }
+    return 'low';
+}
+function resolveProjectName(projectRoot, currentSpecs, readmes) {
+    const currentSpecTitle = currentSpecs[0]?.text.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    if (currentSpecTitle) {
+        return currentSpecTitle.replace(/^[^—-]+[—-]\s*/, '').replace(/^产品规范活文档[:：]?\s*/, '').trim();
+    }
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            if (pkg.name?.trim()) {
+                return pkg.name.trim();
+            }
+        }
+        catch (err) {
+            logger.debug(`package.json 读取失败，尝试从 README 获取项目名称: ${String(err)}`);
+        }
+    }
+    const readmeTitle = readmes[0]?.text.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    if (readmeTitle) {
+        return readmeTitle;
+    }
+    return path.basename(projectRoot);
+}
+function firstMeaningfulSentence(text) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (!normalized) {
+        return undefined;
+    }
+    const sentence = normalized.split(/(?<=[。.!?])\s+/)[0]?.trim();
+    return sentence && sentence.length > 0 ? sentence : normalized;
+}
+function firstSentence(text) {
+    return firstMeaningfulSentence(text);
+}
+/**
+ * 提取 scenario 中"最后一句话"，作为"消费输出"/"outcome"的描述。
+ * 最后一句通常承载结果语义（如 "...returns a result"、"...得到 XXX"）。
+ * 若无明显句子分隔符，返回整段文字的 trim。
+ *
+ * 规则：
+ *   - 英文句尾 `.?!` 必须后跟 `\s+`（空格）才计为句子边界，
+ *     避免把 "e.g" / "i.e" / "2.1" 等缩写/版本号误拆
+ *   - 中文全角标点 `。！？` 不强制空格（中文无空格习惯）
+ */
+function lastMeaningfulSentence(text) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return undefined;
+    const sentences = normalized
+        .split(/(?<=[。！？])|(?<=[.?!])\s+/)
+        .filter((s) => s.trim().length > 0);
+    if (sentences.length === 0)
+        return undefined;
+    return sentences[sentences.length - 1].trim();
+}
+/**
+ * Feature 125 Story 1: 从 scenario 的事实字段（summary / evidence）推导"消费输出"描述。
+ * 这是 evidence-backed mapping，替代 Fix 124 的关键词桶分类。
+ *
+ * 优先级：
+ *   1. scenario.summary 的最后一句（承载结果语义）— 前提长度 ≥ 10
+ *   2. scenario.evidence[0].excerpt 的最后一句
+ *   3. scenario.title 的最后一句
+ *   4. 兜底 fallback（只在完全无事实时使用）
+ */
+function deriveConsumptionFromScenario(scenario) {
+    // 优先从 summary 取最后一句
+    if (scenario.summary && scenario.summary.length >= 10) {
+        const last = lastMeaningfulSentence(scenario.summary);
+        if (last && last.length >= 10) {
+            return truncateAtNaturalBoundary(last, 140);
+        }
+    }
+    // 次选：evidence excerpt 的最后一句
+    const evidenceExcerpt = scenario.evidence?.[0]?.excerpt;
+    if (evidenceExcerpt && evidenceExcerpt.length >= 10) {
+        const last = lastMeaningfulSentence(evidenceExcerpt);
+        if (last && last.length >= 10 && last !== scenario.title) {
+            return truncateAtNaturalBoundary(last, 140);
+        }
+    }
+    // 再次：title 本身作为"消费输出"的粗略描述
+    if (scenario.title && scenario.title.length >= 10) {
+        return truncateAtNaturalBoundary(scenario.title, 140);
+    }
+    // 兜底 fallback（低置信度通用句子，仅完全无事实时触发）
+    return '查看场景输出，继续后续工作流程。';
+}
+/**
+ * Feature 125 Story 1: 从 scenario 的 summary/title 推导"触发场景"描述。
+ * 优先用 summary 的首句（承载动机/入口），避免直接复述 title 造成三步同文。
+ */
+function deriveTriggerFromScenario(scenario, actor) {
+    // summary 首句（承载动机）
+    if (scenario.summary && scenario.summary.length >= 10) {
+        const first = firstMeaningfulSentence(scenario.summary);
+        // 避免和 title 完全一致（会和第二步"执行关键动作"重复）
+        if (first && first !== scenario.title && first.length >= 10) {
+            return `${actor} 开始：${truncateAtNaturalBoundary(first, 120)}`;
+        }
+    }
+    // 兜底：用 title
+    return `${actor} 需要：${truncateAtNaturalBoundary(scenario.title, 120)}`;
+}
+/**
+ * Feature 125 Story 1: 基于 scenario 生成 outcome（场景完成后的状态）。
+ * 用 actor + scenario summary/title 合成，保留场景完成后的结果语义。
+ */
+function deriveOutcomeFromScenario(scenario, actor) {
+    // outcome = 消费输出 + 推进语，避免和步骤 detail 完全相同
+    const consumption = deriveConsumptionFromScenario(scenario);
+    return `${actor} 完成场景后：${consumption}`;
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-+/g, '-');
+    return slug || 'untitled';
+}
+function briefFileName(id, title) {
+    return `${id.toLowerCase()}-${slugify(title)}`;
+}
+function normalizeProjectPath(filePath, projectRoot) {
+    return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+function uniqueSorted(values) {
+    return [...new Set(values.filter((value) => value.trim().length > 0))].sort((left, right) => left.localeCompare(right, 'zh-Hans-CN'));
+}
+function uniqueEvidence(entries) {
+    const seen = new Set();
+    const deduped = [];
+    for (const entry of entries) {
+        const key = [
+            entry.sourceType,
+            entry.label,
+            entry.path ?? '',
+            entry.ref ?? '',
+            entry.excerpt,
+        ].join('|');
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(entry);
+    }
+    return deduped;
+}
+// ============================================================
+// DocumentGenerator Adapter
+// ============================================================
+/**
+ * ProductUxDocsGenerator
+ *
+ * 将 generateProductUxDocs() 适配为 DocumentGenerator 接口。
+ * generate() 包含 fs 文件写出副作用（写出产品概览、用户旅程、feature brief）。
+ * render() 为纯摘要，不含 fs 调用。
+ *
+ * TInput: GenerateProductUxDocsOptions
+ * TOutput: GenerateProductUxDocsResult
+ */
+export class ProductUxDocsGenerator {
+    id = 'product-ux-docs';
+    name = '产品 UX 文档生成器';
+    description = '基于 current-spec、README 与本地设计文档生成产品概览、用户旅程与 feature brief 文档';
+    outputDir;
+    constructor(outputDir) {
+        this.outputDir = outputDir;
+    }
+    isApplicable(context) {
+        // 只要项目根目录存在即可适用
+        return Boolean(context.projectRoot);
+    }
+    async extract(context) {
+        return {
+            projectRoot: context.projectRoot,
+            outputDir: this.outputDir,
+            projectContext: context,
+        };
+    }
+    async generate(input, _options) {
+        // generate() 包含 fs 写出副作用
+        return generateProductUxDocs(input);
+    }
+    render(output) {
+        // render() 为纯摘要，无 fs 调用
+        const lines = [
+            `# 产品文档生成摘要`,
+            '',
+            `**产品概览**: ${output.overview.title}`,
+            `**用户旅程**: ${output.journeys.journeys.length} 条`,
+            `**Feature Brief**: ${output.featureBriefIndex.briefs.length} 个`,
+            '',
+        ];
+        if (output.writtenFiles.length > 0) {
+            lines.push('**写出文件**:');
+            for (const file of output.writtenFiles) {
+                lines.push(`- ${file}`);
+            }
+        }
+        if (output.warnings.length > 0) {
+            lines.push('', '**警告**:');
+            for (const warning of output.warnings) {
+                lines.push(`- ${warning}`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=product-ux-docs.js.map