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

package/README.md

@@ -72,7 +72,7 @@ explore（可选）→ propose → refine → apply → review → test → veri
 │       ↓                                                                 │
 │  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
 │       ↓                                                                 │
-│  approval [可选]  AI 7 维闭环检查 + 设计质量 + 可实施性 → approval.md 供审批 │
+│  document [可选] 通用长文档引擎 → 方案文档（0→1 / bugfix / feature）      │
 │       ↓                                                                 │
 │  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
 │                   （可选 /specflow:apply --yes：少打断，成功后串行验收）   │
@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.5.0-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.8.0-alpha）
 specflow --help
 ```
 
@@ -266,7 +266,7 @@ specflow init
 | 探索（可选） | `/specflow:explore` | `specflow:explore` | `$specflow-explore` |
 | 规划 | `/specflow:propose` | `specflow:propose` | `$specflow-propose` |
 | 精化 | `/specflow:refine` | `specflow:refine` | `$specflow-refine` |
-| 审批（可选） | `/specflow:approval` | `specflow:approval` | `$specflow-approval` |
+| 文档（可选） | `/specflow:document` | `specflow:document` | `$specflow-document` |
 | 构建 | `/specflow:apply` | `specflow:apply` | `$specflow-apply` |
 | 审查 | `/specflow:review` | `specflow:review` | `$specflow-review` |
 | 测试 | `/specflow:test` | `specflow:test` | `$specflow-test` |
@@ -282,7 +282,7 @@ specflow init
 | **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
 | **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架）；叙述语言跟 `artifacts.language` |
 | **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
-| **approval** | refine 后可选：AI 对四件套做 7 维闭环性检查（含代码落地性、基线对照）+ 设计质量评估 + 可实施性评估，生成 `approval.md` 供人工审批；非轻量变更分片写入 `approval/parts/` 后 `specflow approval assemble` 拼接；不改 phase，不阻塞 apply |
+| **document** | 可选：`specflow document run <0to1|bugfix|feature>` 用**通用长文档引擎**生成方案文档——两遍扫描（Pass 1 大纲冻结 → Pass 2 逐章按要点填空）+ 分层真源（契约实体 zod + 受控叙述）+ 四层上下文注入（大纲要点 + 依赖摘要 + 契约注入 + 本片片段，保证注意力不稀释 / token 不易打满）+ 覆盖双通道校验 + AI Review。多业务场景 × 多方案模板，详见 `docs/GENERIC_LONGDOC_ENGINE_DESIGN.md` |
 | **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |

package/dist/cli/commands/document-run.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CLI: specflow document {plan|validate|run} — Generic LongDoc Engine, IDE-model driven.
+ *
+ * The engine does NOT call a third-party LLM API. In Cursor/Codex the Agent runs on the IDE's
+ * model, so:
+ *   - `document plan <profile>` emits a step list the Agent executes with the IDE model.
+ *   - `document validate --work-root <path>` deterministically validates + renders Agent-written
+ *     artifacts (outline.yaml / chapters/*.md / entities.json) — no LLM call.
+ *   - `document run <profile>` guides: plan → Agent executes → validate (requires injected LLM only
+ *     for library/tests; CLI itself never fetches an API).
+ */
+import type { Command } from 'commander';
+import type { DocumentLLM } from '../../core/document/llm.js';
+export interface DocumentPlanOptions {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    tasks?: string;
+    code?: string;
+    workRoot?: string;
+    json?: boolean;
+    markdown?: boolean;
+    signoff?: boolean;
+}
+export interface DocumentValidateOptions {
+    workRoot?: string;
+    json?: boolean;
+    noRender?: boolean;
+}
+export declare function planDocumentCommand(profileId: string, options: DocumentPlanOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function validateDocumentCommand(options: DocumentValidateOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function injectLLM(llm: DocumentLLM): void;
+export declare function runDocumentCommand(profileId: string | undefined, options: {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    code?: string;
+    workRoot?: string;
+    json?: boolean;
+    signoff?: boolean;
+} & {
+    skipReview?: boolean;
+    maxRounds?: number;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function detectDocumentCommand(options: {
+    text?: string;
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    code?: string;
+    json?: boolean;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export interface ApproveOptions {
+    proposal?: string;
+    specs?: string;
+    design?: string;
+    tasks?: string;
+    change?: string;
+    workspaceRoot?: string;
+    changes?: string;
+    workRoot?: string;
+    signoff?: boolean;
+    bundle?: boolean;
+    json?: boolean;
+}
+export declare function approveDocumentCommand(options: ApproveOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function registerDocumentRunCommand(program: Command): void;

package/dist/cli/commands/document-run.js

@@ -0,0 +1,539 @@
+/**
+ * CLI: specflow document {plan|validate|run} — Generic LongDoc Engine, IDE-model driven.
+ *
+ * The engine does NOT call a third-party LLM API. In Cursor/Codex the Agent runs on the IDE's
+ * model, so:
+ *   - `document plan <profile>` emits a step list the Agent executes with the IDE model.
+ *   - `document validate --work-root <path>` deterministically validates + renders Agent-written
+ *     artifacts (outline.yaml / chapters/*.md / entities.json) — no LLM call.
+ *   - `document run <profile>` guides: plan → Agent executes → validate (requires injected LLM only
+ *     for library/tests; CLI itself never fetches an API).
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { loadChapterLibrary } from '../../core/document/chapters.js';
+import { loadProfile } from '../../core/document/profiles.js';
+import { runDocument, planSteps, validateWork } from '../../core/document/engine.js';
+import { detectScene, confirmationPrompt } from '../../core/document/scene-detect.js';
+async function readInputFile(path, type) {
+    const content = await fs.readFile(path, 'utf-8');
+    return { type, source: path, content };
+}
+async function collectInputs(options) {
+    const inputs = [];
+    if (options.text)
+        inputs.push({ type: 'description', source: 'description', content: options.text });
+    if (options.proposal)
+        inputs.push(await readInputFile(options.proposal, 'proposal'));
+    if (options.design)
+        inputs.push(await readInputFile(options.design, 'design'));
+    if (options.specs)
+        inputs.push(await readInputFile(options.specs, 'specs'));
+    if (options.tasks)
+        inputs.push(await readInputFile(options.tasks, 'tasks'));
+    if (options.code)
+        inputs.push(await readInputFile(options.code, 'code'));
+    return inputs;
+}
+function inputFeatures(inputs, opts) {
+    return {
+        containsApiChange: inputs.some((i) => i.type === 'design' || i.type === 'specs'),
+        hasPersistence: inputs.some((i) => i.type === 'specs'),
+        uiInScope: false,
+        hasLogic: true,
+        includeSignoff: opts?.includeSignoff ?? false,
+    };
+}
+function stepsToMarkdown(steps, profileId) {
+    const lines = [
+        `# 文档生成步骤（${profileId}）`,
+        '',
+        '> 请你在当前 IDE 会话中用模型逐步执行以下步骤，产物写入 workRoot。',
+        '> 完成后运行 `specflow document validate --work-root <path>` 校验。',
+        '',
+    ];
+    for (const s of steps) {
+        lines.push(`## ${s.id}（${s.phase}）`, '');
+        lines.push(`**做什么**：${s.description}`, '');
+        lines.push(`**参考提示词**：\`${s.prompt}\``, '');
+        if (s.inputFiles.length)
+            lines.push(`**输入**：${s.inputFiles.join(', ')}`, '');
+        lines.push(`**输出**：\`${s.outputFile}\``, '');
+        lines.push(`**必做**：${s.required ? '是' : '否（可选）'}`, '');
+        lines.push('', '---', '');
+    }
+    return lines.join('\n');
+}
+// ============= document plan =============
+export async function planDocumentCommand(profileId, options) {
+    try {
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile(profileId);
+        const inputs = await collectInputs(options);
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        await fs.mkdir(workRoot, { recursive: true });
+        const result = planSteps({
+            profile,
+            library,
+            inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+            inputs,
+            workRoot,
+            projectRoot: process.cwd(),
+        });
+        const payload = {
+            ok: true,
+            profile: profileId,
+            workRoot,
+            chapters: result.chapters,
+            steps: result.steps,
+        };
+        if (options.json) {
+            return { exitCode: 0, payload };
+        }
+        if (options.markdown) {
+            console.info(stepsToMarkdown(result.steps, profileId));
+            return { exitCode: 0, payload };
+        }
+        console.info(`文档生成步骤（${profileId}），workRoot: ${workRoot}`);
+        console.info('');
+        for (const s of result.steps) {
+            console.info(`  [${s.phase}] ${s.id}: ${s.title}`);
+            console.info(`       → ${s.outputFile}`);
+        }
+        console.info('');
+        console.info('请用 IDE 模型按上述步骤生成产物，然后运行：');
+        console.info(`  specflow document validate --work-root ${workRoot}`);
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document validate =============
+export async function validateDocumentCommand(options) {
+    try {
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        const library = await loadChapterLibrary();
+        // Detect profile from outline.yaml (or require it).
+        const outlineRaw = await fs.readFile(join(workRoot, 'outline.yaml'), 'utf-8');
+        const profileMatch = outlineRaw.match(/^profile:\s*(\S+)/m);
+        if (!profileMatch) {
+            throw new Error(`Cannot detect profile from ${join(workRoot, 'outline.yaml')}`);
+        }
+        const profile = await loadProfile(profileMatch[1]);
+        const result = await validateWork({
+            profile,
+            library,
+            workRoot,
+            renderHtmlOutput: !options.noRender,
+        });
+        const payload = {
+            ok: result.ok,
+            workRoot,
+            document: result.documentMd ? join(workRoot, 'document.md') : undefined,
+            html: result.documentHtml ? join(workRoot, 'document.html') : undefined,
+            diagnostics: result.diagnostics,
+        };
+        if (options.json) {
+            return { exitCode: result.ok ? 0 : 1, payload };
+        }
+        if (!result.ok) {
+            console.error(`Document validation failed:`);
+            for (const d of result.diagnostics) {
+                console.error(`  [${d.gate}][${d.severity}] ${d.message}`);
+            }
+            return { exitCode: 1, payload };
+        }
+        console.info(`Document valid: ${join(workRoot, 'document.md')}`);
+        if (result.documentHtml)
+            console.info(`HTML: ${join(workRoot, 'document.html')}`);
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document run (Agent-driven guide; library `runDocument` needs an injected LLM) =============
+let injectedLLM = null;
+export function injectLLM(llm) {
+    injectedLLM = llm;
+}
+function getInjectedLLM() {
+    return injectedLLM;
+}
+export async function runDocumentCommand(profileId, options) {
+    // Collect inputs first (needed for scene auto-detection).
+    const inputs = await collectInputs(options);
+    if (inputs.length === 0) {
+        const msg = 'No input provided. Use --text or --proposal/--design/--specs/--code.';
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        console.error(`Error: ${msg}`);
+        return { exitCode: 1, payload: { ok: false, error: msg } };
+    }
+    const text = inputs.map((i) => i.content).join('\n');
+    // Scene resolution: explicit profile, or auto-detect from natural language; confirm when uncertain.
+    let resolvedProfile = profileId ?? '';
+    if (!resolvedProfile) {
+        const det = detectScene(text);
+        if (det.profile && det.confidence >= 0.5) {
+            resolvedProfile = det.profile;
+        }
+        else {
+            const msg = confirmationPrompt(det, text) +
+                '\n\n确认后重新运行，例如：\n  specflow document run <profile> --text "..."';
+            const payload = { ok: false, needsConfirmation: true, candidates: det.candidates, message: msg };
+            if (options.json)
+                return { exitCode: 0, payload };
+            console.info(msg);
+            return { exitCode: 0, payload: { ok: false, needsConfirmation: true } };
+        }
+    }
+    // One-click entry: no injected LLM → emit the Agent execution directive. The Agent (running on
+    // the IDE model) reads this and auto-completes plan → generate → validate. CLI itself never fetches an API.
+    const llm = getInjectedLLM();
+    if (!llm) {
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        await fs.mkdir(workRoot, { recursive: true });
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile(resolvedProfile);
+        const plan = planSteps({ profile, library, inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }), inputs, workRoot, projectRoot: process.cwd() });
+        const directive = [
+            `# 一键生成技术文档（${resolvedProfile}）`,
+            '',
+            `请作为 Agent 用当前 IDE 模型自动完成以下步骤（勿中途停下来等用户分步），产物写入 workRoot: ${workRoot}`,
+            '',
+            `## 步骤`,
+            ...plan.steps.map((s) => `- [${s.phase}] **${s.id}**: ${s.title} → 输出 \`${s.outputFile}\`${s.required ? '' : '（可选）'}`),
+            '',
+            `## 完成后`,
+            `运行 \`specflow document validate --work-root ${workRoot}\`，通过后向用户报告 document.md 路径；失败则修正产物后重跑。`,
+            '',
+            `提示词模板参考（IDE 资产）：`,
+            `- outline: .claude/specflow/prompts/document/outline/general.md`,
+            `- map: .claude/specflow/prompts/document/map/<章节>.md`,
+            `- review: .claude/specflow/prompts/document/review/ai-review.md`,
+        ].join('\n');
+        const payload = { ok: true, mode: 'agent-directive', workRoot, steps: plan.steps };
+        if (options.json)
+            return { exitCode: 0, payload };
+        console.info(directive);
+        return { exitCode: 0, payload };
+    }
+    // Delegates to the library runDocument for completeness (tests use this).
+    try {
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile(resolvedProfile);
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        await fs.mkdir(workRoot, { recursive: true });
+        const result = await runDocument({
+            llm,
+            workRoot,
+            profile,
+            library,
+            inputs,
+            inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+            change: resolvedProfile,
+            skipReview: options.skipReview ?? false,
+            maxRounds: options.maxRounds ?? 3,
+            renderHtmlOutput: false,
+            persist: true,
+        });
+        const payload = {
+            ok: result.ok,
+            stage: result.stage,
+            workRoot,
+            document: result.documentMd ? join(workRoot, 'document.md') : undefined,
+            diagnostics: result.diagnostics,
+        };
+        if (options.json)
+            return { exitCode: result.ok ? 0 : 1, payload };
+        if (!result.ok) {
+            console.error(`Document generation failed at stage "${result.stage}":`);
+            for (const d of result.diagnostics)
+                console.error(`  [${d.gate}][${d.severity}] ${d.message}`);
+            return { exitCode: 1, payload };
+        }
+        console.info(`Document generated (${resolvedProfile}) in ${workRoot}`);
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document detect =============
+export async function detectDocumentCommand(options) {
+    const inputs = await collectInputs(options);
+    const text = inputs.map((i) => i.content).join('\n');
+    const det = detectScene(text);
+    const payload = {
+        ok: true,
+        detected: det.profile,
+        confidence: det.confidence,
+        candidates: det.candidates,
+        reasons: det.reasons,
+    };
+    if (options.json)
+        return { exitCode: 0, payload };
+    if (det.profile) {
+        console.info(`检测到场景: ${det.profile}（置信度 ${Math.round(det.confidence * 100)}%）`);
+    }
+    else {
+        console.info(confirmationPrompt(det, text));
+    }
+    return { exitCode: 0, payload };
+}
+/**
+ * Discover multi-repo four-artifact sets under a workspace root.
+ * A repo contributes if `<repoRoot>/specflow/changes/<change>/` contains proposal/specs/design/tasks.
+ */
+async function discoverRepoChanges(workspaceRoot, spec) {
+    const repos = [];
+    if (spec) {
+        for (const part of spec.split(',')) {
+            const [repo, change] = part.trim().split(':');
+            if (repo && change)
+                repos.push({ repo, change, root: join(workspaceRoot, repo) });
+        }
+        return repos;
+    }
+    // Auto-scan: workspaceRoot/<repo>/specflow/changes/*/
+    const entries = await fs.readdir(workspaceRoot, { withFileTypes: true });
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const changesDir = join(workspaceRoot, e.name, 'specflow', 'changes');
+        try {
+            const changes = await fs.readdir(changesDir);
+            for (const ch of changes) {
+                if (ch.startsWith('archive'))
+                    continue;
+                repos.push({ repo: e.name, change: ch, root: join(workspaceRoot, e.name) });
+            }
+        }
+        catch {
+            // no specflow/changes in this dir → skip
+        }
+    }
+    return repos;
+}
+export async function approveDocumentCommand(options) {
+    const library = await loadChapterLibrary();
+    const profile = await loadProfile('approve');
+    const dirs = [];
+    if (options.workspaceRoot) {
+        dirs.push(...await discoverRepoChanges(options.workspaceRoot, options.changes ?? ''));
+    }
+    else {
+        const change = options.change ?? 'approval';
+        dirs.push({ repo: 'local', change, root: process.cwd() });
+    }
+    if (dirs.length === 0) {
+        const msg = 'No four-artifact change found. Provide --proposal/--specs/--design/--tasks or --workspace-root.';
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        console.error(`Error: ${msg}`);
+        return { exitCode: 1, payload: { ok: false, error: msg } };
+    }
+    // Per-repo approve plan (read four artifacts, emit Agent generation steps).
+    const plans = [];
+    for (const d of dirs) {
+        const changeDir = join(d.root, 'specflow', 'changes', d.change);
+        const inputs = [];
+        for (const [type, file] of [['proposal', 'proposal.md'], ['specs', 'spec.md'], ['design', 'design.md'], ['tasks', 'tasks.md']]) {
+            try {
+                const content = await fs.readFile(join(changeDir, file), 'utf-8');
+                inputs.push({ type, source: join(changeDir, file), content });
+            }
+            catch {
+                // optional missing artifact → skip
+            }
+        }
+        if (inputs.length === 0) {
+            // fall back to explicit options (four artifacts)
+            if (options.proposal)
+                inputs.push(await readInputFile(options.proposal, 'proposal'));
+            if (options.specs)
+                inputs.push(await readInputFile(options.specs, 'specs'));
+            if (options.design)
+                inputs.push(await readInputFile(options.design, 'design'));
+            if (options.tasks)
+                inputs.push(await readInputFile(options.tasks, 'tasks'));
+        }
+        const workRoot = options.workRoot ?? join(changeDir, 'approval');
+        await fs.mkdir(workRoot, { recursive: true });
+        const plan = planSteps({
+            profile,
+            library,
+            inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+            inputs,
+            workRoot,
+            projectRoot: d.root,
+        });
+        plans.push({ repo: d.repo, change: d.change, steps: plan.steps, workRoot });
+    }
+    // Multi-repo bundle: merge each repo's generated document.md into one approval-unified.md.
+    if (options.bundle) {
+        if (plans.length < 2) {
+            const msg = '--bundle requires multiple repos (--workspace-root or --changes with ≥2).';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        const sections = [`# 审批合订（多仓）`, '', `> 各仓审批文档合订视图（只读）。各仓 document.md 为真源。`, ''];
+        const errors = [];
+        for (const p of plans) {
+            const docPath = join(p.workRoot, 'document.md');
+            try {
+                const content = await fs.readFile(docPath, 'utf-8');
+                sections.push(`---`, '', `## 来源 · ${p.repo}（\`${p.change}\`）`, '', content.trim(), '');
+            }
+            catch {
+                errors.push(`${p.repo}/${p.change} document.md 未生成（请先完成该仓生成并 validate）`);
+            }
+        }
+        if (errors.length > 0) {
+            const msg = `合订失败：\n  ${errors.join('\n  ')}`;
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(msg);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        const unifiedPath = join(plans[0].workRoot, 'approval-unified.md');
+        await fs.writeFile(unifiedPath, sections.join('\n'), 'utf-8');
+        const payload = { ok: true, mode: 'bundle', unifiedPath, sources: plans.map((p) => ({ repo: p.repo, change: p.change, document: join(p.workRoot, 'document.md') })) };
+        if (options.json)
+            return { exitCode: 0, payload };
+        console.info(`多仓合订完成: ${unifiedPath}`);
+        return { exitCode: 0, payload };
+    }
+    // Build directive.
+    const lines = ['# 审批文档生成（approve · 四件套 → 审批）', ''];
+    lines.push('请作为 Agent 用当前 IDE 模型，对每个仓的四件套生成审批文档（含闭环检查/可实施性/质量红线），产物写入各仓 workRoot，完成后 validate。');
+    lines.push('');
+    for (const p of plans) {
+        lines.push(`## 仓 ${p.repo}（change: ${p.change}）· workRoot: ${p.workRoot}`);
+        for (const s of p.steps) {
+            lines.push(`- [${s.phase}] **${s.id}**: ${s.title} → \`${s.outputFile}\``);
+        }
+        lines.push(`  - 完成后: \`specflow document validate --work-root ${p.workRoot}\``);
+        lines.push('');
+    }
+    if (plans.length > 1) {
+        lines.push('## 多仓合订（主仓）');
+        lines.push('各仓审批文档生成并 validate 通过后，主仓汇总为统一视图（只读合订）：');
+        lines.push(`  - 合并各仓 document.md 为 approval-unified.md（主仓: ${plans[0].repo}）`);
+    }
+    const payload = { ok: true, mode: 'approve', plans: plans.map((p) => ({ repo: p.repo, change: p.change, workRoot: p.workRoot, steps: p.steps })) };
+    if (options.json)
+        return { exitCode: 0, payload };
+    console.info(lines.join('\n'));
+    return { exitCode: 0, payload };
+}
+// ============= registration =============
+export function registerDocumentRunCommand(program) {
+    const doc = program
+        .command('document')
+        .description('Generate scenario-based solution documents (Generic LongDoc Engine)');
+    doc
+        .command('detect')
+        .description('Auto-detect the scene profile (0to1 | bugfix | feature) from natural language')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--json', 'Output detection as JSON')
+        .action(async (opts) => {
+        const { exitCode, payload } = await detectDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('plan <profile>')
+        .description('Emit the Agent-executable step list (IDE model does the work; no LLM API call)')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--json', 'Output step list as JSON')
+        .option('--markdown', 'Output step list as Markdown')
+        .action(async (profile, opts) => {
+        const { exitCode, payload } = await planDocumentCommand(profile, opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('validate')
+        .description('Deterministically validate + render Agent-written artifacts (no LLM)')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--json', 'Output result as JSON')
+        .option('--no-render', 'Skip HTML rendering')
+        .action(async (opts) => {
+        const { exitCode, payload } = await validateDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('run [profile]')
+        .description('One-click generate a scenario document. Omit <profile> to auto-detect scene; confirm when uncertain.')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--signoff', 'Include an approval sign-off section')
+        .option('--skip-review', 'Skip Pass 3 AI review')
+        .option('--max-rounds <n>', 'AI review max rounds', '3')
+        .option('--json', 'Output result as JSON')
+        .action(async (profile, opts) => {
+        const { exitCode, payload } = await runDocumentCommand(profile, opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('approve')
+        .description('Generate an approval document from the four artifacts (proposal/specs/design/tasks). Multi-repo with --workspace-root.')
+        .option('--proposal <path>', 'Proposal file')
+        .option('--specs <path>', 'Specs file')
+        .option('--design <path>', 'Design file')
+        .option('--tasks <path>', 'Tasks file')
+        .option('--change <name>', 'Change name (single-repo mode)')
+        .option('--workspace-root <path>', 'Multi-repo workspace root (scan per-repo four artifacts)')
+        .option('--changes <spec>', 'Multi-repo "repo1:change1,repo2:change2"')
+        .option('--work-root <path>', 'Work directory')
+        .option('--signoff', 'Include the approval sign-off section')
+        .option('--bundle', 'Merge each repo document.md into approval-unified.md (after all repos generated+validated)')
+        .option('--json', 'Output result as JSON')
+        .action(async (opts) => {
+        const { exitCode, payload } = await approveDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+}

package/dist/cli/index.js

@@ -16,7 +16,7 @@ import { registerStoreCommand } from './commands/store.js';
 import { registerShowCommand } from './commands/show.js';
 import { registerContextCommand } from './commands/context.js';
 import { registerWorksetCommand } from './commands/workset.js';
-import { registerApprovalAssembleCommand } from './commands/approval-assemble.js';
+import { registerDocumentRunCommand } from './commands/document-run.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
@@ -44,7 +44,7 @@ registerStoreCommand(program);
 registerShowCommand(program);
 registerContextCommand(program);
 registerWorksetCommand(program);
-registerApprovalAssembleCommand(program);
+registerDocumentRunCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync();