@gordon.gan/specflow 1.8.0-beta → 1.8.2-beta

package/dist/core/document/review.js

@@ -0,0 +1,202 @@
+/**
+ * Document Engine — Pass 3 AI review (decision 9 · target + max_rounds + part_hashes).
+ *
+ * Fresh-context reviewer (separate from generator) produces findings with a `target`
+ * (entity|narrative|mixed). Findings apply by target; review-result is validated against
+ * part_hashes (post-review tamper detection) and max_rounds (infinite-loop guard).
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { parseReviewResult, } from './schemas.js';
+import { chapterPath } from './paths.js';
+import { semanticCoverageChecklist } from './coverage.js';
+export const AI_REVIEW_CHECKLIST = [
+    'R1 跨章命名一致',
+    'R2 决策落地',
+    'R3 实体↔正文',
+    'R4 深度均衡',
+    'R5 交叉引用稳定',
+    'R6 图文一致',
+    'R7 契约完整',
+    'R8 枚举闭合',
+    'R9 分支闭合',
+    'R10 UI↔API 对齐',
+    'R11 场景一致',
+    'R12 stub 清除',
+    'R13 结论一致',
+    'R14 大纲要点覆盖',
+];
+// ============= Packet (T8.1) =============
+export async function buildReviewPacket(workRoot, change, outline, prevFindings = [], 
+/** 内存态章节覆盖（P2）：persist=false 时磁盘无章节文件，传 narrativeMap 让评审者
+ *  看到真实内容而非空串；缺省时回退读磁盘。 */
+narratives) {
+    const chapters = new Map();
+    for (const ch of outline.chapters) {
+        const fromMemory = narratives?.get(ch.id);
+        if (fromMemory !== undefined) {
+            chapters.set(ch.id, fromMemory);
+            continue;
+        }
+        try {
+            chapters.set(ch.id, await fs.readFile(chapterPath(workRoot, ch.id), 'utf-8'));
+        }
+        catch {
+            chapters.set(ch.id, '');
+        }
+    }
+    return {
+        schema: 'specflow.document.review-packet/v1',
+        change,
+        outline,
+        chapters,
+        checklist: [...AI_REVIEW_CHECKLIST],
+        semanticChecklist: semanticCoverageChecklist(outline),
+        prevFindings,
+    };
+}
+// ============= Review call (T8.2) =============
+export async function reviewWithAgent(llm, packet, prompt) {
+    const checklist = packet.checklist.join('\n');
+    const semantic = packet.semanticChecklist.length > 0
+        ? packet.semanticChecklist.map((s) => `- ${s.chapter} · ${s.pointId}: ${s.text}`).join('\n')
+        : '（无 narrative/mixed 要点）';
+    const prev = packet.prevFindings.length > 0
+        ? packet.prevFindings
+            .map((f) => `- ${f.id} [${f.severity}] ${f.target ?? 'narrative'} ${f.chapter ?? ''}: ${f.message}`)
+            .join('\n')
+        : '（无）';
+    const content = [
+        `# Review packet`,
+        `change: ${packet.change}`,
+        `checklist:\n${checklist}`,
+        `## 上一轮 findings（闭环核对：对应章节已追加 <!-- review-fix --> 注记；已解决 → status=fixed，勿重复报告）`,
+        prev,
+        `## R14 语义覆盖核对清单（逐要点核对：对应小节存在且有实质内容）`,
+        semantic,
+        `outline: ${JSON.stringify(packet.outline)}`,
+        `chapters:\n${[...packet.chapters.entries()].map(([id, c]) => `### ${id}\n${c}`).join('\n\n')}`,
+    ].join('\n\n');
+    // 超长保护（P2）：大文档全文内联会超模型上下文导致审查失败；截断章节正文并标注。
+    const MAX_PACKET_CHARS = 60000;
+    const contentFinal = content.length > MAX_PACKET_CHARS
+        ? content.slice(0, MAX_PACKET_CHARS) + `…（已截断，原内容 ${content.length} 字符 > ${MAX_PACKET_CHARS}；请基于可见部分审查）`
+        : content;
+    const input = {
+        system: prompt ??
+            '你是独立长文档审查者。按 checklist 审查，输出 review-result JSON。R14 必须逐要点核对语义覆盖清单。' +
+                '对「上一轮 findings」逐条核实：对应章节已含 review-fix 注记且问题已解决 → 标 status=fixed；仅报告仍未解决的问题。',
+        messages: [{ role: 'user', content: contentFinal }],
+    };
+    let res;
+    try {
+        res = await llm.complete(input);
+    }
+    catch (e) {
+        throw new Error(`reviewWithAgent: LLM call failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        // 剥离 ```json 围栏与前后缀文本（P2）：LLM 常用围栏包裹/附带说明，裸 JSON.parse 会硬失败。
+        const content = res.content.trim();
+        const fence = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+        const jsonText = fence ? fence[1].trim() : content;
+        return parseReviewResult(JSON.parse(jsonText));
+    }
+    catch (e) {
+        throw new Error(`reviewWithAgent: unparsable review result: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+// ============= Apply findings by target (T8.3) =============
+/**
+ * 应用待修复的 findings。闭环语义（decision 9）：
+ *  - status==='open'（默认）→ 尚未解决，需要应用修复（追加 fix note / 重填实体）。
+ *  - status==='fixed'  → 评审者已确认上一轮注记生效，仅作闭环核对记账，不再应用。
+ *  - status==='waived' → 豁免，不应用。
+ * 同一 finding 可能跨轮被回显，按 id 去重避免注记/修复重复累积。
+ */
+export async function applyFindings(workRoot, findings, apply, appliedIds) {
+    const seen = appliedIds ?? new Set();
+    for (const f of findings) {
+        if (f.status !== 'open')
+            continue;
+        if (seen.has(f.id))
+            continue;
+        seen.add(f.id);
+        await apply(f);
+    }
+}
+// ============= Part hashes (T8.4) =============
+export function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+export async function computePartHashes(workRoot, chapterIds) {
+    const out = [];
+    for (const id of chapterIds) {
+        try {
+            const content = await fs.readFile(chapterPath(workRoot, id), 'utf-8');
+            out.push({ id, sha256: sha256(content) });
+        }
+        catch {
+            // missing chapter skipped
+        }
+    }
+    return out;
+}
+export async function checkReviewResult(workRoot, review, outline, currentHashesParam) {
+    const diags = [];
+    if (review.verdict === 'fail') {
+        diags.push({ code: 'review_verdict_fail', severity: 'error', message: 'review verdict is fail' });
+    }
+    // open critical/important findings
+    for (const f of review.findings) {
+        if (f.status === 'open' && f.severity !== 'minor') {
+            diags.push({ code: 'review_finding_open', severity: 'error', message: `[${f.id}] ${f.message}` });
+        }
+        if (f.status === 'waived' && !f.waiver_reason?.trim()) {
+            diags.push({ code: 'review_waiver_missing_reason', severity: 'error', message: `[${f.id}] waived finding must include waiver_reason` });
+        }
+    }
+    // part_hashes tamper detection (decision 9): review-result MUST include a hash for every chapter
+    // that exists on disk, so post-review changes are detected. Missing coverage for a persisted
+    // chapter = incomplete review (no tamper verification).
+    //
+    // `part_hashes` is the engine-computed snapshot of what the reviewer ACTUALLY saw (the LLM
+    // cannot compute sha256 reliably). Chapters the engine legitimately changed after that snapshot
+    // (entity refill / narrative fix notes) are recorded in `post_review_repairs` and exempted from
+    // the "stale" verdict — everything else must still match the snapshot, so genuine post-review
+    // tampering is still caught. The engine no longer refreshes hashes before checking, which made
+    // the check vacuous.
+    // currentHashes 由调用方提供（P2）：persist=false 时磁盘无章节，引擎传内存哈希；
+    // 缺省时回退读磁盘（兼容旧调用方/validateWork）。
+    const currentHashes = currentHashesParam ?? await computePartHashes(workRoot, outline.chapters.map((c) => c.id));
+    const current = new Map(currentHashes.map((h) => [h.id, h.sha256]));
+    const reported = new Set((review.part_hashes ?? []).map((ph) => ph.id));
+    const repaired = new Set((review.post_review_repairs ?? []).map((r) => r.chapter));
+    for (const [chId] of current) {
+        if (!reported.has(chId)) {
+            diags.push({
+                code: 'review_part_hashes_missing',
+                severity: 'error',
+                message: `review-result missing part_hashes for persisted chapter "${chId}" — cannot verify no post-review tampering`,
+            });
+        }
+    }
+    for (const ph of review.part_hashes ?? []) {
+        const now = current.get(ph.id);
+        if (now === undefined) {
+            // 审查后章节被删除（P2）：此前 computePartHashes 静默跳过缺失文件，删除型篡改不可见。
+            if (!repaired.has(ph.id)) {
+                diags.push({ code: 'review_part_missing', severity: 'error', message: `Chapter "${ph.id}" existed at review time but is now missing — possible post-review deletion` });
+            }
+        }
+        else if (now !== ph.sha256 && !repaired.has(ph.id)) {
+            diags.push({ code: 'review_part_stale', severity: 'error', message: `Chapter "${ph.id}" changed after review; re-run review` });
+        }
+    }
+    return { ok: diags.every((d) => d.severity !== 'error'), diagnostics: diags };
+}
+// ============= Persistence (T8.5) =============
+export async function writeReviewResult(workRoot, review) {
+    await fs.writeFile(join(workRoot, 'review-result.json'), JSON.stringify(review, null, 2), 'utf-8');
+}

package/dist/core/document/scene-detect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Document Engine — scene detection (decision: auto-detect 0to1 / bugfix / feature /
+ * poc / migration from natural language; confirm with the user when uncertain).
+ *
+ * Deterministic keyword scoring as a first pass. The Agent (IDE model) may refine and confirm
+ * when confidence is low. Returns the best match + confidence + candidates.
+ *
+ * Scene axis (what we are doing) is orthogonal to the tech-stack axis (which layers are
+ * involved — derived by input-features hasBackend/uiInScope). `frontend-0to1` is the one
+ * stack-specific variant: pure-frontend 0→1 (no backend signals → 0to1 is narrowed to it).
+ */
+export type SceneProfile = '0to1' | 'frontend-0to1' | 'bugfix' | 'feature' | 'poc' | 'migration';
+export interface SceneDetectResult {
+    profile: SceneProfile | null;
+    confidence: number;
+    candidates: Array<{
+        profile: SceneProfile;
+        score: number;
+    }>;
+    reasons: string[];
+}
+/**
+ * Detect the most likely scene profile from natural language.
+ * - `frontend-0to1` is NOT a competing candidate: it is a narrowing of `0to1` (pure-frontend,
+ *   no backend hints) — so the "strongest scene" race runs on the 5 base scenes only, and 0to1
+ *   is narrowed to frontend-0to1 when backend is absent and pure-frontend signals are present.
+ * - Returns a profile when its score clearly leads (≥ 2× runner-up, or score ≥ threshold).
+ * - Returns null when signals are weak/conflicting → caller should confirm with the user.
+ */
+export declare function detectScene(text: string): SceneDetectResult;
+/** The user-facing prompt when detection is uncertain. */
+export declare function confirmationPrompt(result: SceneDetectResult, text: string): string;

package/dist/core/document/scene-detect.js

@@ -0,0 +1,237 @@
+/**
+ * Document Engine — scene detection (decision: auto-detect 0to1 / bugfix / feature /
+ * poc / migration from natural language; confirm with the user when uncertain).
+ *
+ * Deterministic keyword scoring as a first pass. The Agent (IDE model) may refine and confirm
+ * when confidence is low. Returns the best match + confidence + candidates.
+ *
+ * Scene axis (what we are doing) is orthogonal to the tech-stack axis (which layers are
+ * involved — derived by input-features hasBackend/uiInScope). `frontend-0to1` is the one
+ * stack-specific variant: pure-frontend 0→1 (no backend signals → 0to1 is narrowed to it).
+ */
+const KEYWORDS = {
+    // 从零做一个产品/项目
+    '0to1': [
+        { text: '想做', weight: 3 },
+        { text: '想做一个', weight: 4 },
+        { text: '打算做', weight: 3 },
+        { text: '做一个', weight: 2 },
+        { text: '从零', weight: 3 },
+        { text: '新产品', weight: 2 },
+        { text: 'startup', weight: 2 },
+        { text: '想法', weight: 2 },
+        { text: 'idea', weight: 2 },
+        { text: '开始做', weight: 2 },
+        { text: '立项', weight: 2 },
+        { text: '技术选型', weight: 1 },
+        { text: 'mvp', weight: 1 },
+        { text: 'MVP', weight: 1 },
+    ],
+    // 纯前端 0→1（无后端信号的 0to1 收敛变体；hasBackend 命中时回落 0to1）
+    'frontend-0to1': [
+        { text: '纯前端', weight: 4 },
+        { text: '前端项目', weight: 3 },
+        { text: '静态站点', weight: 3 },
+        { text: '静态网站', weight: 3 },
+        { text: '官网', weight: 2 },
+        { text: '落地页', weight: 2 },
+        { text: 'landing page', weight: 3 },
+        { text: 'landing', weight: 2 },
+        { text: '前端应用', weight: 3 },
+        { text: 'web 前端', weight: 2 },
+        { text: '无后端', weight: 3 },
+        { text: '不要后端', weight: 3 },
+        { text: '只有页面', weight: 2 },
+        { text: '纯 UI', weight: 2 },
+    ],
+    // 修 bug / 排查故障（含前端/多端维度；不再单列 fullstack-bugfix）
+    bugfix: [
+        { text: '报错', weight: 3 },
+        { text: '500', weight: 3 },
+        { text: '崩溃', weight: 3 },
+        { text: '挂了', weight: 3 },
+        { text: '修复', weight: 2 },
+        { text: '修一下', weight: 3 },
+        { text: 'bug', weight: 2 },
+        { text: 'BUG', weight: 2 },
+        { text: '异常', weight: 2 },
+        { text: '失败', weight: 2 },
+        { text: '闪退', weight: 3 },
+        { text: '无法使用', weight: 2 },
+        { text: '不工作', weight: 2 },
+        { text: '错误', weight: 2 },
+        { text: '故障', weight: 3 },
+        { text: '排查', weight: 2 },
+        { text: '定位问题', weight: 2 },
+        { text: 'debug', weight: 2 },
+        { text: '前端报错', weight: 3 },
+        { text: '页面崩溃', weight: 3 },
+        { text: '页面白屏', weight: 3 },
+        { text: '渲染问题', weight: 3 },
+        { text: '样式错乱', weight: 3 },
+        { text: '浏览器兼容', weight: 2 },
+        { text: '兼容性问题', weight: 3 },
+        { text: '多端', weight: 2 },
+        { text: '跨端', weight: 2 },
+        { text: '联调 bug', weight: 3 },
+        { text: '数据对不上', weight: 2 },
+    ],
+    // 给已有系统加功能（含全栈/接口/前端维度，由输入特征伸缩；不再单列 fullstack-feature）
+    feature: [
+        { text: '新增', weight: 3 },
+        { text: '增加', weight: 2 },
+        { text: '加一个', weight: 3 },
+        { text: '加个', weight: 3 },
+        { text: '扩展', weight: 2 },
+        { text: '添加', weight: 2 },
+        { text: '支持', weight: 1 },
+        { text: '功能', weight: 1 },
+        { text: '开发一个功能', weight: 3 },
+        { text: 'feat', weight: 2 },
+        { text: '新增模块', weight: 3 },
+        { text: '新页面', weight: 3 },
+        { text: '新路由', weight: 3 },
+        { text: '多个页面', weight: 3 },
+        { text: '状态管理', weight: 2 },
+        { text: '接口对接', weight: 2 },
+        { text: '前后端联调', weight: 3 },
+        { text: '功能开发', weight: 2 },
+        { text: '组件化', weight: 2 },
+        { text: '页面组件', weight: 2 },
+    ],
+    // 技术预研 / PoC / 方案选型（原 fullstack-poc；预研不限于全栈，是否全栈由特征决定）
+    poc: [
+        { text: '预研', weight: 3 },
+        { text: '技术调研', weight: 3 },
+        { text: '方案对比', weight: 3 },
+        { text: '候选', weight: 2 },
+        { text: 'poc', weight: 3 },
+        { text: 'PoC', weight: 3 },
+        { text: 'benchmark', weight: 2 },
+        { text: '选型评估', weight: 3 },
+        { text: '评估一下', weight: 2 },
+        { text: '对比一下', weight: 2 },
+        { text: '可行性验证', weight: 3 },
+    ],
+    // 技术升级（原 fullstack-migration；是否全栈由特征决定）
+    migration: [
+        { text: '迁移', weight: 3 },
+        { text: '大版本', weight: 3 },
+        { text: '框架升级', weight: 3 },
+        { text: '技术升级', weight: 3 },
+        { text: '构建工具升级', weight: 3 },
+        { text: 'vue2', weight: 2 },
+        { text: 'vue3', weight: 2 },
+        { text: 'webpack', weight: 2 },
+        { text: 'vite', weight: 2 },
+        { text: '代码迁移', weight: 3 },
+        { text: '升级到', weight: 2 },
+    ],
+};
+/**
+ * 关键词匹配（P2）：
+ * - CJK 关键词：子串匹配。
+ * - ASCII/数字关键词（api/server/rest/500/vue2 等）：词边界匹配，避免 'api'⊂rapid、'500'⊂1500、'server'⊂serverless 误报。
+ */
+function keywordHit(text, kw) {
+    if (/^[A-Za-z0-9_.-]+$/.test(kw)) {
+        const re = new RegExp(`(^|[^A-Za-z0-9_])${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^A-Za-z0-9_])`);
+        return re.test(text);
+    }
+    return text.includes(kw);
+}
+/** Score a text against one profile's keywords. 重叠关键词取最长匹配（P2）：
+ *  '想做一个' 命中后不再计 '想做'/'做一个'；'landing page' 命中后不再计 'landing'；
+ *  '开发一个功能' 命中后不再计 '功能'——避免同一短语重复计分导致误判场景。 */
+function score(text, profile) {
+    // 按长度降序处理：先匹配长的（更具体），命中则其包含的短词不再计分。
+    const sorted = [...KEYWORDS[profile]].sort((a, b) => b.text.length - a.text.length);
+    let score = 0;
+    const hits = [];
+    for (const kw of sorted) {
+        if (!keywordHit(text, kw.text))
+            continue;
+        // 若存在更长的已命中关键词包含本词（如 '想做一个' 包含 '想做'），跳过本词避免重复计分。
+        const coveredByLonger = sorted.some((other) => other !== kw && other.text.length > kw.text.length && other.text.includes(kw.text) && keywordHit(text, other.text));
+        if (coveredByLonger)
+            continue;
+        score += kw.weight;
+        hits.push(kw.text);
+    }
+    return { score, hits };
+}
+/** Backend signal: if the text mentions backend/API/database, a 0to1 is NOT pure-frontend.
+ *  Negated forms (无后端/不要后端/没有后端…) are stripped first so they don't false-positive.
+ *  ASCII hints use word-boundary matching（P2）：'api' 不应命中 rapid/capital，'server' 不应命中 serverless。 */
+const BACKEND_HINTS = ['后端', '服务端', '服务器', '接口', '数据库', '微服务', '后台', '网关', 'api', 'rest', 'backend', 'server', 'daemon'];
+const BACKEND_NEGATIONS = ['无后端', '不要后端', '没有后端', '不用后端', '不需要后端', '无需后端', 'no backend', 'without backend', '不接后端'];
+function hasBackendSignal(lower) {
+    let text = lower;
+    for (const neg of BACKEND_NEGATIONS)
+        text = text.split(neg).join(' ');
+    return BACKEND_HINTS.some((h) => keywordHit(text, h));
+}
+/**
+ * Detect the most likely scene profile from natural language.
+ * - `frontend-0to1` is NOT a competing candidate: it is a narrowing of `0to1` (pure-frontend,
+ *   no backend hints) — so the "strongest scene" race runs on the 5 base scenes only, and 0to1
+ *   is narrowed to frontend-0to1 when backend is absent and pure-frontend signals are present.
+ * - Returns a profile when its score clearly leads (≥ 2× runner-up, or score ≥ threshold).
+ * - Returns null when signals are weak/conflicting → caller should confirm with the user.
+ */
+export function detectScene(text) {
+    const lower = text.toLowerCase();
+    const all = Object.keys(KEYWORDS).map((p) => ({
+        profile: p,
+        score: score(lower, p).score,
+    }));
+    const candidates = [...all].sort((a, b) => b.score - a.score);
+    // Base-scene race excludes frontend-0to1 (it narrows 0to1, never outranks it).
+    const base = all.filter((s) => s.profile !== 'frontend-0to1').sort((a, b) => b.score - a.score);
+    const best = base[0];
+    const runner = base[1];
+    const total = base.reduce((s, x) => s + x.score, 0);
+    const reasons = [];
+    // Strong signal: clear winner.
+    if (best.score >= 3 && (runner.score === 0 || best.score >= runner.score * 2)) {
+        let winner = best.profile;
+        // 0to1 → frontend-0to1 narrowing: pure-frontend signals with no backend hints.
+        if (best.profile === '0to1' && !hasBackendSignal(lower)) {
+            const feScore = candidates.find((s) => s.profile === 'frontend-0to1')?.score ?? 0;
+            if (feScore > 0)
+                winner = 'frontend-0to1';
+        }
+        const confidence = Math.min(1, best.score / (best.score + runner.score + 1));
+        reasons.push(`匹配「${winner}」关键词 ${best.score} 分（次优 ${runner.profile} ${runner.score} 分）`);
+        return { profile: winner, confidence, candidates, reasons };
+    }
+    // Conflicting/weak → uncertain.
+    if (total === 0) {
+        reasons.push('未检测到明显场景信号，需向用户确认');
+    }
+    else {
+        reasons.push(`场景信号较弱或冲突（${base.map((s) => `${s.profile}:${s.score}`).join(', ')}），需确认`);
+    }
+    return { profile: null, confidence: 0, candidates, reasons };
+}
+/** The user-facing prompt when detection is uncertain. */
+export function confirmationPrompt(result, text) {
+    const lines = [
+        `未能明确判断你的需求属于哪个场景：`,
+        `「${text.slice(0, 60)}${text.length > 60 ? '…' : ''}」`,
+        '',
+        `检测到的候选：`,
+        ...result.candidates
+            .filter((c) => c.score > 0)
+            .map((c) => `- ${c.profile}: ${c.score} 分`),
+        '',
+        `请选择场景（或直接输入新的需求描述）：`,
+        `- 0to1   → 从零启动一个产品/项目（全栈；纯前端自动走 frontend-0to1）`,
+        `- frontend-0to1 → 从零启动一个纯前端项目（无后端/仅页面与样式）`,
+        `- bugfix → 排查并修复一个问题（含前端/多端维度，按输入特征伸缩）`,
+        `- feature → 给已有系统新增功能（按输入特征伸缩：纯逻辑/含后端/含前端/全栈）`,
+        `- poc → 技术预研/选型（新技术评估/PoC/方案对比）`,
+        `- migration → 技术升级（框架迁移/大版本/构建工具升级）`,
+    ];
+    return lines.join('\n');
+}