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

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

@@ -53,6 +53,17 @@ export declare function stripEntityJsonBlocks(text: string): string;
  * 仅当首行非空是 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

@@ -146,13 +146,46 @@ export function stripLeadingTitle(text, chapterTitle) {
     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)}`, '');
-        // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记。
-        const narrative = stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title);
+        // 依次净化：剥内嵌契约 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.8.2-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": [