@gordon.gan/specflow 1.8.1-beta → 1.8.3-beta

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

@@ -82,7 +82,8 @@ export declare function approveDocumentCommand(options: ApproveOptions): Promise
     payload: unknown;
 }>;
 export interface SynthesizeOptions {
-    workspaceRoot: string;
+    workspaceRoot?: string;
+    workset?: string;
     changes?: string;
     profile?: string;
     text?: string;

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

@@ -10,7 +10,7 @@
  *     for library/tests; CLI itself never fetches an API).
  */
 import { promises as fs } from 'node:fs';
-import { join } from 'node:path';
+import { join, basename, dirname, sep } 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';
@@ -18,6 +18,8 @@ import { detectInputFeatures } from '../../core/document/input-features.js';
 import { detectScene, confirmationPrompt } from '../../core/document/scene-detect.js';
 import { reposPath } from '../../core/document/paths.js';
 import { readOutline } from '../../core/document/outline.js';
+import { readWorksetsState, defaultWorksetsStatePath } from '../../core/worksets.js';
+import { getGlobalDataDir } from '../../core/global-config.js';
 async function readInputFile(path, type) {
     const content = await fs.readFile(path, 'utf-8');
     return { type, source: path, content };
@@ -332,14 +334,32 @@ export async function detectDocumentCommand(options) {
 /**
  * Discover multi-repo four-artifact sets under a workspace root.
  * A repo contributes if `<repoRoot>/specflow/changes/<change>/` contains proposal/specs/design/tasks.
+ *
+ * spec 支持两种写法：
+ *   - "repo1:change1,repo2:change2"：精确指定 change（原行为）
+ *   - "repo1,repo2"：只写仓名 → 自动选该仓最相关 change（有 text 时按描述匹配，否则最新）
  */
-async function discoverRepoChanges(workspaceRoot, spec) {
+async function discoverRepoChanges(workspaceRoot, spec, text) {
     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) });
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const [repo, change] = trimmed.split(':');
+            if (!repo)
+                continue;
+            const root = join(workspaceRoot, repo);
+            if (change) {
+                repos.push({ repo, change, root });
+            }
+            else {
+                // repo-only → auto-select the best change: text-matched, else latest non-archive
+                const matched = text ? await matchRepoChangeByText(root, text) : null;
+                const best = matched?.change ?? (await latestRepoChange(root));
+                if (best)
+                    repos.push({ repo, change: best, root });
+            }
         }
         return repos;
     }
@@ -363,6 +383,176 @@ async function discoverRepoChanges(workspaceRoot, spec) {
     }
     return repos;
 }
+/** 某仓最新（mtime 最大）的非 archive change 名；无四件套或目录缺失 → null。 */
+async function latestRepoChange(repoRoot) {
+    const changesDir = join(repoRoot, 'specflow', 'changes');
+    let entries;
+    try {
+        entries = await fs.readdir(changesDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    let latest = null;
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith('archive'))
+            continue;
+        try {
+            const st = await fs.stat(join(changesDir, e.name));
+            if (!latest || st.mtimeMs > latest.mtimeMs)
+                latest = { name: e.name, mtimeMs: st.mtimeMs };
+        }
+        catch {
+            // unreadable entry → skip
+        }
+    }
+    return latest?.name ?? null;
+}
+/** 提取描述文本的匹配 token：英文/数字词（小写）+ 中文 2-gram。用于与 change 摘要做相关性打分。 */
+function extractMatchTokens(text) {
+    const tokens = new Set();
+    for (const m of text.toLowerCase().matchAll(/[a-z0-9][a-z0-9_-]*/g)) {
+        if (m[0].length >= 2)
+            tokens.add(m[0]);
+    }
+    const cjk = text.replace(/[^\u4e00-\u9fff]/g, '');
+    for (let i = 0; i + 1 < cjk.length; i++)
+        tokens.add(cjk.slice(i, i + 2));
+    return tokens;
+}
+/** 读某 change 的提案摘要（proposal.md 优先，缺则 design.md / spec.md），用于文本匹配。 */
+async function readChangeSummary(changeDir) {
+    for (const file of ['proposal.md', 'design.md', 'spec.md']) {
+        try {
+            return (await fs.readFile(join(changeDir, file), 'utf-8')).slice(0, 2000);
+        }
+        catch {
+            // try next artifact
+        }
+    }
+    return '';
+}
+/**
+ * 按 --text 描述匹配某仓最相关的 change：
+ * 1. 对每个非 archive change 读提案摘要（proposal.md 优先，缺则 design.md / spec.md）；
+ * 2. 打分 = 描述 token 在摘要中的**出现次数**（频率加权，区分"提了一次"与"通篇主题"）
+ *    + change 名直接命中加分（英文 token 与 kebab 名直接匹配，中文 2-gram 亦可子串命中）；
+ * 3. 返回命中最多的 change；最高命中为 0（描述与该仓任何 change 都无关联）→ null（回退「最新」）。
+ * 并列时取 mtime 较新者，保证确定性。
+ */
+async function matchRepoChangeByText(repoRoot, text) {
+    const changesDir = join(repoRoot, 'specflow', 'changes');
+    let entries;
+    try {
+        entries = await fs.readdir(changesDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const queryTokens = [...extractMatchTokens(text)];
+    if (queryTokens.length === 0)
+        return null;
+    let best = null;
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith('archive'))
+            continue;
+        const changeDir = join(changesDir, e.name);
+        const summary = `${e.name}\n${await readChangeSummary(changeDir)}`.toLowerCase();
+        let score = 0;
+        for (const t of queryTokens) {
+            const re = new RegExp(escapeRegExp(t), 'g');
+            const matches = summary.match(re);
+            if (matches)
+                score += matches.length;
+            // change 名命中加分（如 kebab 名 scenario-job-compile 对 token 'scenario'/'job'）
+            if (e.name.toLowerCase().includes(t))
+                score += 5;
+        }
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await fs.stat(changeDir)).mtimeMs;
+        }
+        catch {
+            // unreadable → treat as 0
+        }
+        if (!best || score > best.score || (score === best.score && mtimeMs > best.mtimeMs)) {
+            best = { change: e.name, score, mtimeMs };
+        }
+    }
+    return best && best.score > 0 ? { change: best.change, score: best.score } : null;
+}
+/** 转义正则特殊字符（供频率计数用）。 */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 从已存 workset 推导多仓合成输入：workspace-root（成员公共父目录）+ 每仓 change。
+ * 成员路径直接指向各仓根目录，因此不需要用户再手写长路径。
+ * change 选择优先级：
+ *   1. --changes 显式指定（支持 "repo1:ch1" 或只写仓名 "repo1"）；
+ *   2. --text 描述 → 按文本相关性匹配各仓最相关的 change（读提案摘要打分，命中 0 回退最新）；
+ *   3. 均无 → 每仓最新非 archive change。
+ */
+async function resolveWorksetRepos(worksetName, spec, text, worksetsStatePath = defaultWorksetsStatePath(getGlobalDataDir())) {
+    const state = await readWorksetsState(worksetsStatePath);
+    const workset = state.worksets.find((w) => w.name === worksetName);
+    if (!workset) {
+        throw new Error(`Workset '${worksetName}' not found. Run 'specflow workset create <name>' first (members point at each repo root).`);
+    }
+    if (workset.members.length < 2) {
+        throw new Error(`Workset '${worksetName}' has only ${workset.members.length} member(s); synthesize requires ≥2 repos.`);
+    }
+    // workspace-root = 成员路径的公共父目录（各成员须位于同一工作区下）。
+    const parents = workset.members.map((m) => dirname(m.path));
+    const workspaceRoot = commonAncestor(parents) ?? dirname(workset.members[0].path);
+    const dirs = [];
+    if (spec) {
+        // 显式 --changes：仓名可用成员 label 或目录名（basename）；不带 change 时自动选最新。
+        for (const part of spec.split(',')) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const [repo, change] = trimmed.split(':');
+            const member = workset.members.find((m) => m.name === repo || basename(m.path) === repo);
+            if (!member) {
+                throw new Error(`--changes 引用了不在 workset '${worksetName}' 中的仓 '${repo}'。可用仓：${workset.members.map((m) => m.name).join(', ')}`);
+            }
+            const repoName = basename(member.path);
+            const changeName = change ?? (await latestRepoChange(member.path));
+            if (!changeName) {
+                throw new Error(`Workset member '${member.name}' (${member.path}) has no non-archive change.`);
+            }
+            dirs.push({ repo: repoName, change: changeName, root: member.path });
+        }
+    }
+    else {
+        // 无 --changes：有 --text → 按文本相关性匹配每仓最相关 change；无 --text 或匹配不上 → 每仓最新。
+        for (const m of workset.members) {
+            const repoName = basename(m.path);
+            const matched = text ? await matchRepoChangeByText(m.path, text) : null;
+            const change = matched?.change ?? (await latestRepoChange(m.path));
+            if (change)
+                dirs.push({ repo: repoName, change, root: m.path });
+        }
+    }
+    return { workspaceRoot, dirs };
+}
+/** 一组绝对路径的公共父目录（按 / 分段取最长公共前缀）。 */
+function commonAncestor(paths) {
+    if (paths.length === 0)
+        return null;
+    const parts = paths.map((p) => p.split(sep));
+    let common = parts[0];
+    for (const p of parts.slice(1)) {
+        let i = 0;
+        while (i < common.length && i < p.length && common[i] === p[i])
+            i++;
+        common = common.slice(0, i);
+        if (common.length === 0)
+            return null;
+    }
+    return common.join(sep);
+}
 export async function approveDocumentCommand(options) {
     try {
         const library = await loadChapterLibrary();
@@ -538,10 +728,12 @@ function buildSynthRules(dirs) {
 /**
  * 解析合成用 profile：显式 --profile 优先；省略时从 --text（或四件套拼接内容）做场景识别。
  * - 识别置信度达标 → 直接采用识别结果。
- * - 识别不出且用户给了 --text → 返回 needsConfirmation（与 document run 行为一致，向用户确认）。
+ * - 识别不出且用户给了 --text：
+ *   - workset 模式（weakDefault 传 true）→ 取分数最高的候选 profile 兜底（如 feature），不打断流程；
+ *   - 否则 → 返回 needsConfirmation（与 document run 行为一致，向用户确认）。
  * - 识别不出且无 --text → 回退 approve（原 synthesize 默认，保持向后兼容，不打断流程）。
  */
-function resolveSynthProfile(options, inputs) {
+function resolveSynthProfile(options, inputs, weakDefault = false) {
     if (options.profile)
         return { profileId: options.profile };
     const detectText = (options.text ?? inputs.map((i) => i.content).join('\n')).trim();
@@ -550,6 +742,12 @@ function resolveSynthProfile(options, inputs) {
         return { profileId: det.profile, detectedText: detectText };
     }
     if (options.text) {
+        if (weakDefault) {
+            // workset 模式：描述模糊时不打断流程——取分数最高的候选兜底（0 分则 feature）。
+            const top = det.candidates.filter((c) => c.profile !== 'frontend-0to1').sort((a, b) => b.score - a.score)[0];
+            const profileId = top && top.score > 0 ? top.profile : 'feature';
+            return { profileId, detectedText: detectText, weakDefault: true };
+        }
         const message = confirmationPrompt(det, detectText) +
             '\n\n确认后重新运行，例如：\n  specflow techdoc synthesize --workspace-root <root> --profile <profile> ...';
         return {
@@ -563,17 +761,27 @@ function resolveSynthProfile(options, inputs) {
 }
 export async function synthesizeDocumentCommand(options) {
     try {
-        // workspaceRoot 必填（P2）：缺省时 fs.readdir(undefined) 会抛裸 TypeError。
-        if (!options.workspaceRoot) {
-            const msg = 'synthesize 需要 --workspace-root <path>（多仓工作区根目录，必填）。';
+        // 输入来源解析：--workset 优先（从已存 workset 推导 workspaceRoot + 每仓最新 change）；
+        // 其次 --workspace-root（可配 --changes 精确指定或只写仓名）；两者皆无 → 报错。
+        let workspaceRoot = options.workspaceRoot;
+        let dirs = [];
+        if (options.workset) {
+            const resolved = await resolveWorksetRepos(options.workset, options.changes, options.text);
+            workspaceRoot = resolved.workspaceRoot;
+            dirs = resolved.dirs;
+        }
+        else if (options.workspaceRoot) {
+            dirs = await discoverRepoChanges(options.workspaceRoot, options.changes ?? '', options.text);
+        }
+        else {
+            const msg = 'synthesize 需要 --workspace-root <path> 或 --workset <name>（多仓工作区根目录 / 已存 workset）。';
             if (options.json)
                 return { exitCode: 1, payload: { ok: false, error: msg } };
             console.error(`Error: ${msg}`);
             return { exitCode: 1, payload: { ok: false, error: msg } };
         }
-        const dirs = await discoverRepoChanges(options.workspaceRoot, options.changes ?? '');
         if (dirs.length === 0) {
-            const msg = 'No multi-repo four-artifact sets found. Use --workspace-root with --changes "repo1:ch1,repo2:ch2" or auto-scan.';
+            const msg = 'No multi-repo four-artifact sets found. Use --workspace-root with --changes "repo1:ch1,repo2:ch2" (or repo-only "repo1,repo2"), or --workset <name>.';
             if (options.json)
                 return { exitCode: 1, payload: { ok: false, error: msg } };
             console.error(`Error: ${msg}`);
@@ -601,8 +809,9 @@ export async function synthesizeDocumentCommand(options) {
             console.error(`Error: ${msg}`);
             return { exitCode: 1, payload: { ok: false, error: msg } };
         }
-        // 场景识别：显式 --profile 优先；省略时从 --text / 四件套内容识别，不确定则向用户确认（同 document run）。
-        const resolved = resolveSynthProfile(options, inputs);
+        // 场景识别：显式 --profile 优先；省略时从 --text / 四件套内容识别。
+        // workset 模式描述模糊 → weakDefault 兜底（取分数最高候选，不打断）；workspace-root 模式不确定 → 向用户确认。
+        const resolved = resolveSynthProfile(options, inputs, !!options.workset);
         if (resolved.needsConfirmation) {
             const payload = {
                 ok: false,
@@ -620,10 +829,12 @@ export async function synthesizeDocumentCommand(options) {
             ? { profile: profileId, source: 'explicit' }
             : resolved.fallback
                 ? { profile: profileId, source: 'fallback' }
-                : { profile: profileId, source: 'detected' };
+                : resolved.weakDefault
+                    ? { profile: profileId, source: 'weak-default' }
+                    : { profile: profileId, source: 'detected' };
         const library = await loadChapterLibrary();
         const profile = await loadProfile(profileId);
-        const workRoot = options.workRoot ?? join(options.workspaceRoot, '.specflow', 'document-synthesized');
+        const workRoot = options.workRoot ?? join(workspaceRoot, '.specflow', 'document-synthesized');
         await fs.mkdir(workRoot, { recursive: true });
         // Multi-repo synthesize marker: validateWork reads this to enforce the per-repo section gate.
         // 只有 synthesize 写 repos.json；approve --bundle / document run 不写 → 门禁不触发。
@@ -643,16 +854,23 @@ export async function synthesizeDocumentCommand(options) {
                 workRoot,
             });
             const repoList = dirs.map((d) => `${d.repo}/${d.change}`).join('、');
+            const selectionNote = options.text && !options.changes
+                ? `\n> change 按 --text 描述文本相关性自动匹配（未显式 --changes）；如需精确指定请重跑并加 --changes "repo1:ch1,repo2:ch2"。`
+                : '';
             const sceneLine = scene.source === 'detected'
                 ? `（场景识别：${scene.profile}）`
-                : scene.source === 'fallback'
-                    ? '（场景未识别，回退 approve）'
-                    : '';
+                : scene.source === 'weak-default'
+                    ? `（场景识别较弱，默认采用 ${scene.profile}）`
+                    : scene.source === 'fallback'
+                        ? '（场景未识别，回退 approve）'
+                        : '';
             const directive = [
                 `# 跨仓合成文档（${profile.id} · ${dirs.length} 仓${sceneLine}）`,
                 '',
                 `请作为 Agent 用当前 IDE 模型自动完成以下步骤（勿中途停下等用户分步），产物写入 workRoot: ${workRoot}`,
                 '',
+                `## 参与仓与 change：${repoList}${selectionNote}`,
+                '',
                 `## 输入来源（多仓统一输入，每段已标记「来源仓」，段 id 携带仓前缀）`,
                 ...inputs.map((i) => `- \`${i.source}\`（${i.type} · 来自 ${i.content.split('\n')[0] ?? ''}）`),
                 '',
@@ -807,8 +1025,9 @@ export function registerDocumentRunCommand(program) {
     doc
         .command('synthesize')
         .description('Synthesize multi-repo four artifacts into ONE cross-repo document (unified outline + namespaced contract entities + global overview/conclusion). Requires ≥2 repos. Omit --profile to auto-detect the scene (0to1/bugfix/feature/poc/migration) from --text or the artifacts; confirm when uncertain.')
-        .option('--workspace-root <path>', 'Multi-repo workspace root (required)')
-        .option('--changes <spec>', 'Multi-repo "repo1:change1,repo2:change2" (default: auto-scan workspaceRoot)')
+        .option('--workspace-root <path>', 'Multi-repo workspace root (auto-derived from --workset if omitted)')
+        .option('--workset <name>', 'Use a saved workset: derive workspace root + each repo\'s latest change (members point at repo roots)')
+        .option('--changes <spec>', 'Multi-repo "repo1:change1,repo2:change2" or repo-only "repo1,repo2" (auto-select latest change). Default: auto-scan workspaceRoot / all workset members')
         .option('--text <text>', 'Natural-language description of the cross-repo work (used for scene detection when --profile is omitted)')
         .option('--profile <id>', 'Synthesis profile (default: auto-detect scene from --text / artifacts; e.g. approve | 0to1 | bugfix | feature | poc | migration)')
         .option('--work-root <path>', 'Output directory (default: <workspaceRoot>/.specflow/document-synthesized)')

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

@@ -0,0 +1,15 @@
+/**
+ * Document Engine — template asset path resolution.
+ *
+ * Templates (templates/document/chapters, templates/document/profiles) are loaded from two
+ * places, in priority order:
+ *   1. `<project-cwd>/templates` — user-overridable templates (e.g. a repo ships its own).
+ *   2. The specflow package's own `templates/` dir — so the CLI works from ANY directory
+ *      (multi-repo workspaces, repos initialized elsewhere) instead of failing when cwd
+ *      has no templates. This fixes "synthesize 因模板路径失败" when running in a workspace
+ *      that is not the specflow checkout.
+ */
+/** 候选模板根目录（含用户 cwd 覆盖与包内 fallback）。 */
+export declare function templateRoots(projectDir?: string): string[];
+/** 在模板根目录候选里找第一个存在的目录；都不存在则返回包内默认（让上层报可读错误）。 */
+export declare function resolveTemplateDir(subpath: string, projectDir?: string): Promise<string>;

package/dist/core/document/asset-paths.js

@@ -0,0 +1,38 @@
+/**
+ * Document Engine — template asset path resolution.
+ *
+ * Templates (templates/document/chapters, templates/document/profiles) are loaded from two
+ * places, in priority order:
+ *   1. `<project-cwd>/templates` — user-overridable templates (e.g. a repo ships its own).
+ *   2. The specflow package's own `templates/` dir — so the CLI works from ANY directory
+ *      (multi-repo workspaces, repos initialized elsewhere) instead of failing when cwd
+ *      has no templates. This fixes "synthesize 因模板路径失败" when running in a workspace
+ *      that is not the specflow checkout.
+ */
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** specflow 包根：从当前模块（dist/core/document/*.js）上溯到包根（templates 所在层）。 */
+function packageRoot() {
+    const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/dist/core/document
+    return dirname(dirname(dirname(here))); // <pkg>/dist/core → <pkg>/dist → <pkg>
+}
+/** 候选模板根目录（含用户 cwd 覆盖与包内 fallback）。 */
+export function templateRoots(projectDir = process.cwd()) {
+    return [join(projectDir, 'templates'), join(packageRoot(), 'templates')];
+}
+/** 在模板根目录候选里找第一个存在的目录；都不存在则返回包内默认（让上层报可读错误）。 */
+export async function resolveTemplateDir(subpath, projectDir) {
+    for (const root of templateRoots(projectDir)) {
+        const candidate = join(root, subpath);
+        try {
+            const st = await fs.stat(candidate);
+            if (st.isDirectory())
+                return candidate;
+        }
+        catch {
+            // not present → try next
+        }
+    }
+    return join(packageRoot(), 'templates', subpath);
+}

package/dist/core/document/chapters.js

@@ -6,9 +6,11 @@ import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
 import { parseChapterComponent } from './schemas.js';
-const DEFAULT_CHAPTERS_DIR = join(process.cwd(), 'templates', 'document', 'chapters');
-export async function loadChapterLibrary(dir = DEFAULT_CHAPTERS_DIR) {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
+import { resolveTemplateDir } from './asset-paths.js';
+export async function loadChapterLibrary(dir) {
+    // 默认从「用户 cwd/templates 优先、包内 templates fallback」解析（多仓工作区也能跑）。
+    const resolvedDir = dir ?? (await resolveTemplateDir(join('document', 'chapters')));
+    const entries = await fs.readdir(resolvedDir, { withFileTypes: true });
     const lib = new Map();
     const seen = new Set();
     for (const entry of entries) {
@@ -19,7 +21,7 @@ export async function loadChapterLibrary(dir = DEFAULT_CHAPTERS_DIR) {
             continue;
         let raw;
         try {
-            raw = yaml.load(await fs.readFile(join(dir, file), 'utf-8'));
+            raw = yaml.load(await fs.readFile(join(resolvedDir, file), 'utf-8'));
         }
         catch (e) {
             throw new Error(`Failed to parse chapter file ${file}: ${e instanceof Error ? e.message : String(e)}`);

package/dist/core/document/engine.js

@@ -16,7 +16,7 @@ import { buildReviewPacket, reviewWithAgent, checkReviewResult, writeReviewResul
 import { renderDocument, renderHtml } from './render.js';
 import { runGates } from './gates.js';
 import { resolvePaths, reposPath, chapterPath } from './paths.js';
-import { parseEntities } from './schemas.js';
+import { parseEntitiesLenient } from './schemas.js';
 import { lintNarrative, checkRepoSectionCoverage } from './lint.js';
 import { checkStructuredCoverage } from './coverage.js';
 import { resolveProjectConventionPaths } from '../project-conventions.js';
@@ -409,7 +409,7 @@ function extractChapterEntities(content) {
     let m;
     while ((m = jsonBlockRe.exec(content)) !== null) {
         try {
-            const parsed = parseEntities(JSON.parse(m[1]));
+            const parsed = parseEntitiesLenient(JSON.parse(m[1]));
             mergeEntities(out, parsed);
         }
         catch {
@@ -642,7 +642,7 @@ export async function validateWork(options) {
             let jm;
             while ((jm = jsonBlockRe.exec(content)) !== null) {
                 try {
-                    const parsed = parseEntities(JSON.parse(jm[1]));
+                    const parsed = parseEntitiesLenient(JSON.parse(jm[1]));
                     chapterEntities.interfaces.push(...parsed.interfaces);
                     chapterEntities.tables.push(...parsed.tables);
                     chapterEntities.decisions.push(...parsed.decisions);
@@ -660,7 +660,7 @@ export async function validateWork(options) {
     // entities.json.
     try {
         const raw = await fs.readFile(paths.entities, 'utf-8');
-        const parsed = parseEntities(JSON.parse(raw));
+        const parsed = parseEntitiesLenient(JSON.parse(raw));
         allEntities.interfaces = parsed.interfaces;
         allEntities.tables = parsed.tables;
         allEntities.decisions = parsed.decisions;

package/dist/core/document/profiles.js

@@ -9,14 +9,16 @@ import yaml from 'js-yaml';
 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');
+import { resolveTemplateDir } from './asset-paths.js';
 /** 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) {
+export async function loadProfile(profileId, 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'));
+    // 默认从「用户 cwd/templates 优先、包内 templates fallback」解析（多仓工作区也能跑）。
+    const resolvedDir = dir ?? (await resolveTemplateDir(join('document', 'profiles')));
+    const raw = yaml.load(await fs.readFile(join(resolvedDir, `${profileId}.yaml`), 'utf-8'));
     return parseScenarioProfile(raw);
 }
 /**

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

@@ -37,6 +37,33 @@ export interface RenderDocumentInput {
  *  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;
+/**
+ * 从章节叙述中剥离内嵌的**契约实体 JSON 块**（```json {"entities": {...}} ```）。
+ * 这些块是 Agent 写给引擎提取的机器中间格式（map 提示词要求 kind=entity|mixed 要点产出），
+ * 引擎已把其中实体提取进 entities.json，并在文档末尾「契约实体」章节渲染为人类可读的表格。
+ * 最终 document.md 不应再出现原始 JSON——否则读者看到看不懂的 `decisions`/`interfaces` 结构。
+ *
+ * 判定：JSON 可解析且按 Entities schema 解析成功（含 interfaces/tables/decisions 任一非空）
+ * 才剥离；无法解析的块（叙述中的示例 JSON）原样保留，避免误删正文。
+ */
+export declare function stripEntityJsonBlocks(text: string): string;
+/**
+ * 剥离章节叙述首行的**冗余 H1 标题**：叙述以 `# <章节标题>` 开头（Agent 生成正文时习惯性地
+ * 重复了大纲章节标题），而 renderDocument 已为每章输出 `## <title>`——二者叠加造成标题重复。
+ * 仅当首行非空是 H1 且其内容与章节标题 trim 后一致时才剥离，避免误删正文中的真实内容。
+ */
+export declare function stripLeadingTitle(text: string, chapterTitle: string): string;
+/**
+ * 章节叙述标题整体降级 n 级（默认 1）。原因：renderDocument 已为每章输出 `## <章节标题>`（H2），
+ * 而 Agent 生成的叙述内小节标题习惯用 `##`（H2）、分仓小节用 `###`（H3）——与章节头同级，
+ * 造成最终文档目录层级乱（`## 需求` 与 `## 跨仓总目标` 平级）。渲染时降级：`##`→`###`、`###`→`####`…，
+ * 使章节头 H2 → 叙述小节 H3 → 分仓 H4，层级正确。
+ *
+ * 只处理行首的 markdown 标题（`#{1,6}\s`），并跳过围栏代码块（mermaid/``` 内部行不动），
+ * 避免把代码内容里的 `#` 误判成标题。H6 封顶不再升。质量门禁 `### <repo>` 检查的是原始章节
+ * 文件（chapters/*.md），不在此处降级影响范围——仅最终渲染的 document.md 生效。
+ */
+export declare function demoteHeadings(text: string, levels?: number): string;
 export declare function renderDocument(input: RenderDocumentInput): string;
 /** 附录 B · 去AI味自检（frontend-dev-guide §十一 → README §1.6 五维表）。 */
 export declare function renderAppendixAntiAI(content?: string): string;

package/dist/core/document/render.js

@@ -6,6 +6,7 @@
  * Optional HTML render reuses `marked`.
  */
 import { marked } from 'marked';
+import { parseEntities } from './schemas.js';
 // ============= Escaping helpers（P1-5/6：HTML 与 markdown 注入面） =============
 /** HTML 转义：用于 <title>/<h1> 插值（防存储型 XSS）。 */
 export function escapeHtml(s) {
@@ -97,12 +98,94 @@ export function renderEntities(entities) {
 export function stripReviewNotes(text) {
     return text.replace(/<!--\s*review-fix[\s\S]*?-->/g, '').replace(/\n{3,}/g, '\n\n').trim();
 }
+/**
+ * 从章节叙述中剥离内嵌的**契约实体 JSON 块**（```json {"entities": {...}} ```）。
+ * 这些块是 Agent 写给引擎提取的机器中间格式（map 提示词要求 kind=entity|mixed 要点产出），
+ * 引擎已把其中实体提取进 entities.json，并在文档末尾「契约实体」章节渲染为人类可读的表格。
+ * 最终 document.md 不应再出现原始 JSON——否则读者看到看不懂的 `decisions`/`interfaces` 结构。
+ *
+ * 判定：JSON 可解析且按 Entities schema 解析成功（含 interfaces/tables/decisions 任一非空）
+ * 才剥离；无法解析的块（叙述中的示例 JSON）原样保留，避免误删正文。
+ */
+export function stripEntityJsonBlocks(text) {
+    const jsonBlockRe = /```json\s*([\s\S]*?)```/g;
+    const parts = [];
+    let last = 0;
+    let m;
+    while ((m = jsonBlockRe.exec(text)) !== null) {
+        parts.push(text.slice(last, m.index));
+        let isEntityBlock = false;
+        try {
+            const parsed = parseEntities(JSON.parse(m[1]));
+            isEntityBlock = (parsed.interfaces?.length ?? 0) + (parsed.tables?.length ?? 0) + (parsed.decisions?.length ?? 0) > 0;
+        }
+        catch {
+            isEntityBlock = false;
+        }
+        if (!isEntityBlock)
+            parts.push(m[0]);
+        last = m.index + m[0].length;
+    }
+    parts.push(text.slice(last));
+    return parts.join('').replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * 剥离章节叙述首行的**冗余 H1 标题**：叙述以 `# <章节标题>` 开头（Agent 生成正文时习惯性地
+ * 重复了大纲章节标题），而 renderDocument 已为每章输出 `## <title>`——二者叠加造成标题重复。
+ * 仅当首行非空是 H1 且其内容与章节标题 trim 后一致时才剥离，避免误删正文中的真实内容。
+ */
+export function stripLeadingTitle(text, chapterTitle) {
+    const trimmed = text.trim();
+    const firstLine = trimmed.split('\n', 1)[0] ?? '';
+    const m = /^#\s+(.*)$/.exec(firstLine.trim());
+    if (!m)
+        return text;
+    if (m[1].trim() !== chapterTitle.trim())
+        return text;
+    // 去掉首行后，剩余部分（去掉紧邻的空行）即为叙述正文。
+    const rest = trimmed.slice(firstLine.length).replace(/^\n+/, '');
+    return rest;
+}
+/**
+ * 章节叙述标题整体降级 n 级（默认 1）。原因：renderDocument 已为每章输出 `## <章节标题>`（H2），
+ * 而 Agent 生成的叙述内小节标题习惯用 `##`（H2）、分仓小节用 `###`（H3）——与章节头同级，
+ * 造成最终文档目录层级乱（`## 需求` 与 `## 跨仓总目标` 平级）。渲染时降级：`##`→`###`、`###`→`####`…，
+ * 使章节头 H2 → 叙述小节 H3 → 分仓 H4，层级正确。
+ *
+ * 只处理行首的 markdown 标题（`#{1,6}\s`），并跳过围栏代码块（mermaid/``` 内部行不动），
+ * 避免把代码内容里的 `#` 误判成标题。H6 封顶不再升。质量门禁 `### <repo>` 检查的是原始章节
+ * 文件（chapters/*.md），不在此处降级影响范围——仅最终渲染的 document.md 生效。
+ */
+export function demoteHeadings(text, levels = 1) {
+    if (levels <= 0)
+        return text;
+    const lines = text.split('\n');
+    let inFence = false;
+    const out = [];
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('```'))
+            inFence = !inFence;
+        if (!inFence) {
+            const m = /^(#{1,6})(\s.*)$/.exec(line);
+            if (m) {
+                const hashes = Math.min(m[1].length + levels, 6);
+                out.push('#'.repeat(hashes) + m[2]);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
 export function renderDocument(input) {
     const { outline, entities, narratives, profile, appendixAntiAI } = input;
     const body = [`# 方案文档：${escapeInline(outline.profile)}`, ''];
     for (const ch of outline.chapters) {
         body.push(`## ${escapeInline(ch.title)}`, '');
-        const narrative = stripReviewNotes(narratives.get(ch.id) ?? '');
+        // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记，
+        // 再把叙述内标题降级一级（章节头已占 H2，叙述小节 H2→H3、分仓 H3→H4），保证目录层级正确。
+        const narrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title));
         if (narrative.trim())
             body.push(narrative.trim(), '');
     }

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

@@ -1098,6 +1098,14 @@ export declare function parseInterfaceEntity(raw: unknown): InterfaceEntity;
 export declare function parseTableEntity(raw: unknown): TableEntity;
 export declare function parseDecisionEntity(raw: unknown): DecisionEntity;
 export declare function parseEntities(raw: unknown): Entities;
+/**
+ * 兼容两种章节 JSON 块格式的实体解析：
+ *   - 未包装：`{"interfaces": [...], "tables": [...], "decisions": [...]}`（引擎推荐，validate 期望）
+ *   - 包装：`{"entities": {"interfaces": [...]}}`（部分 map 提示词曾要求，Agent 可能照此写）
+ * zod 默认 strip 未知 key，若顶层只有 `entities` 会被剥成空实体——这里显式解包后再解析，
+ * 避免「提示词包装格式 → 实体被剥空 → validate 报缺失 → Agent 反复返工」。
+ */
+export declare function parseEntitiesLenient(raw: unknown): Entities;
 export declare function parseOutline(raw: unknown): Outline;
 export declare function parseChapterComponent(raw: unknown): ChapterComponent;
 export declare function parseScenarioProfile(raw: unknown): ScenarioProfile;

package/dist/core/document/schemas.js

@@ -160,6 +160,26 @@ export function parseDecisionEntity(raw) {
 export function parseEntities(raw) {
     return EntitiesSchema.parse(raw);
 }
+/**
+ * 兼容两种章节 JSON 块格式的实体解析：
+ *   - 未包装：`{"interfaces": [...], "tables": [...], "decisions": [...]}`（引擎推荐，validate 期望）
+ *   - 包装：`{"entities": {"interfaces": [...]}}`（部分 map 提示词曾要求，Agent 可能照此写）
+ * zod 默认 strip 未知 key，若顶层只有 `entities` 会被剥成空实体——这里显式解包后再解析，
+ * 避免「提示词包装格式 → 实体被剥空 → validate 报缺失 → Agent 反复返工」。
+ */
+export function parseEntitiesLenient(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        const obj = raw;
+        if (obj.entities && typeof obj.entities === 'object' && !Array.isArray(obj.entities)) {
+            const inner = obj.entities;
+            // 仅当解包后含实体字段才解包；否则保持原样（可能是非实体叙述块）。
+            if ('interfaces' in inner || 'tables' in inner || 'decisions' in inner) {
+                return parseEntities(inner);
+            }
+        }
+    }
+    return parseEntities(raw);
+}
 export function parseOutline(raw) {
     return OutlineSchema.parse(raw);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.8.1-beta",
+  "version": "1.8.3-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/document/map/acceptance.md

@@ -1,7 +1,7 @@
 # 章节填充：acceptance
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/api-design.md

@@ -1,7 +1,7 @@
 # 章节填充：api-design（接口设计 · 契约 + 前端对接）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/architecture.md

@@ -1,7 +1,7 @@
 # 章节填充：architecture（架构设计 · C4 分层 + ADR）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/closed-loop.md

@@ -1,7 +1,7 @@
 # 章节填充：closed-loop
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/compat-migration.md

@@ -1,7 +1,7 @@
 # 章节填充：compat-migration（兼容性与迁移 · 新旧 API 对照）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/config-runtime.md

@@ -1,7 +1,7 @@
 # 章节填充：config-runtime
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/core-logic.md

@@ -1,7 +1,7 @@
 # 章节填充：core-logic
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/data-model.md

@@ -1,7 +1,7 @@
 # 章节填充：data-model（数据结构/数据模型变更）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/fix.md

@@ -1,7 +1,7 @@
 # 章节填充：fix
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/goal.md

@@ -1,7 +1,7 @@
 # 章节填充：goal
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/impact.md

@@ -1,7 +1,7 @@
 # 章节填充：impact
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/implementability.md

@@ -1,7 +1,7 @@
 # 章节填充：implementability
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/mvp-boundary.md

@@ -1,7 +1,7 @@
 # 章节填充：mvp-boundary
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/non-goals.md

@@ -1,7 +1,7 @@
 # 章节填充：non-goals
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/regression.md

@@ -1,7 +1,7 @@
 # 章节填充：regression
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/reproduce.md

@@ -1,7 +1,7 @@
 # 章节填充：reproduce
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/requirement.md

@@ -1,7 +1,7 @@
 # 章节填充：requirement
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/root-cause.md

@@ -1,7 +1,7 @@
 # 章节填充：root-cause
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/signoff.md

@@ -1,7 +1,7 @@
 # 章节填充：signoff
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/tech-selection.md

@@ -1,7 +1,7 @@
 # 章节填充：tech-selection（技术方案评估 / 技术选型）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/test-strategy.md

@@ -1,7 +1,7 @@
 # 章节填充：test-strategy（测试策略 · 前端金字塔）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/prompts/document/map/ui-design.md

@@ -1,7 +1,7 @@
 # 章节填充：ui-design（前端/UI 设计 · 扩展状态机/路由守卫/埋点/浏览器兼容）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"entities": {...}} ```）
+- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
 - 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词

package/skills/specflow-techdoc-synth/SKILL.md

@@ -10,13 +10,29 @@ description: "One-command multi-repo technical solution document synthesis — m
 ## Invocation（一键入口）
 
 ```text
-/specflow:techdoc-synth run [--workspace-root <root>] [--changes "repo1:ch1,repo2:ch2"] [--text "..."] [--profile <id>] [--work-root <path>] [--signoff]
+/specflow:techdoc-synth run [--workspace-root <root> | --workset <name>] [--changes "repo1:ch1,repo2:ch2" | "repo1,repo2"] [--text "..."] [--profile <id>] [--work-root <path>] [--signoff]
 ```
 
 Cursor: `specflow:techdoc-synth run ...`; Codex: `$specflow-techdoc-synth run ...`。
 
 **收到 `run` 命令后，你必须自动完成全流程，不得中途停下要求分步确认**（除非产物校验失败需要修正）。
 
+## 低成本调用（推荐，三种写法）
+
+命令长是常见痛点，`synthesize` 已内置三档简化：
+
+| 写法 | 命令 | 适用 |
+|---|---|---|
+| **A. `--workset`（最简，推荐）** | `/specflow:techdoc-synth run --workset talos-platform` | 已用 `specflow workset create` 存过三仓路径（成员指向各仓根目录），一次创建、后续零成本 |
+| **B. 只写仓名** | `/specflow:techdoc-synth run --workspace-root <root> --changes "talos,talos-web,talos-worker"` | 仓名短、change 名长时；自动选每仓最新 change |
+| **C. 省略 `--profile`** | 上两式均可省略 `--profile`，从 `--text`（优先）或四件套自动识别场景 | 场景关键词明确时；识别不出且有 `--text` → 向你确认 |
+
+- **workset 语义**：`--workset <name>` 自动推导 workspace-root（成员公共父目录）+ 每仓**最新非 archive change**；`--changes` 可覆盖（支持成员 label 或仓目录名，如 `--changes "api,web:ch2"`）。
+- **`--text` 自动识别涉及哪些功能**：省略 `--changes` 且提供 `--text` 时，按描述**自动匹配每仓最相关的 change**（对 proposal/design 摘要做 token 频率打分，change 名命中加分，并列取较新者；无关联才回退「最新」）。例：`--text "案例场景"` 自动选中三仓的 scenario-job-compile / web-scenario-cases / scenario-execution。
+- **描述模糊不打断（workset 模式）**：`--text` 识别场景不确定时，workset 模式默认取分数最高候选（如 feature）继续，directive 标注「场景识别较弱，默认采用 …」；`--workspace-root` 模式保持确认。
+- **零参数全自动**：`--workset <name>` + `--text "..."` 即可——workspace-root、各仓 change、场景 profile 全部自动解析。
+- **创建 workset**：`specflow workset create <name> --member "api:/path/repo1" --member "web:/path/repo2"`（或编辑 `~/.local/share/specflow/worksets/worksets.yaml`）。
+
 ## 场景自动识别（省略 --profile 时）
 
 与 `techdoc` 相同，`techdoc-synth` 支持场景识别：