@topmindspace/tms-skills 0.3.1 → 0.3.6

package/top-ppt-html/scripts/gen_channel_a.js

@@ -195,20 +195,65 @@ function zipStore(files) {
    --model=<file> [--out=<dir>]：对任意模型跑 A 通道，供回归探针（split 组合页）与
    cross_verify.py 复用同一套「预览即交付」双裁判。 */
 const argv = process.argv.slice(2);
-const modelArg = (argv.find((a) => a.startsWith('--model=')) || '').split('=')[1];
-const outArg = (argv.find((a) => a.startsWith('--out=')) || '').split('=')[1];
+/* 取 --name=value 参数值（路径里含 '=' 时 split('=')[1] 会截断，用 slice 精确取） */
+const _argVal = (name) => {
+  const a = argv.find((x) => x.startsWith(name + '='));
+  return a ? a.slice(name.length + 1) : undefined;
+};
+const modelArg = _argVal('--model');
+const outArg = _argVal('--out');
 const OUT_DIR = outArg ? path.resolve(outArg) : OUT;
-fs.mkdirSync(OUT_DIR, { recursive: true });
+/* 输出目录延迟到首次成功写盘前再建：模型读取失败时不留下空目录（原子性） */
+let outDirReady = false;
+function ensureOutDir() {
+  if (outDirReady) return;
+  try {
+    fs.mkdirSync(OUT_DIR, { recursive: true });
+  } catch (e) {
+    console.error('[gen_channel_a] FAIL: 无法创建输出目录 ' + OUT_DIR + '：' + (e && e.message));
+    process.exit(1);
+  }
+  outDirReady = true;
+}
 
-const jobs = modelArg
-  ? [[path.resolve(modelArg), path.basename(modelArg).replace(/\.model\.json$/, '.pptx')]]
-  : fs.readdirSync(EX).filter((f) => f.endsWith('.model.json')).sort()
-      .map((f) => [path.join(EX, f), f.replace('.model.json', '.pptx')]);
+let jobs;
+try {
+  jobs = modelArg
+    ? [[path.resolve(modelArg), path.basename(modelArg).replace(/\.model\.json$/, '.pptx')]]
+    : fs.readdirSync(EX).filter((f) => f.endsWith('.model.json')).sort()
+        .map((f) => [path.join(EX, f), f.replace('.model.json', '.pptx')]);
+} catch (e) {
+  console.error('[gen_channel_a] FAIL: 无法列出模型目录 ' + (modelArg || EX) + '：' + (e && e.message));
+  process.exit(1);
+}
 
+let failed = 0;
 for (const [src, name] of jobs) {
-  const model = JSON.parse(fs.readFileSync(src, 'utf-8'));
-  const bytes = buildPptx(model);
+  let model;
+  try {
+    model = JSON.parse(fs.readFileSync(src, 'utf-8'));
+  } catch (e) {
+    console.error('[gen_channel_a] FAIL: 模型读取失败 ' + src + '：' + (e && e.message));
+    failed++;
+    continue;
+  }
+  let bytes;
+  try {
+    bytes = buildPptx(model);
+  } catch (e) {
+    console.error('[gen_channel_a] FAIL: A 通道组装失败 ' + src + '：' + (e && e.message));
+    failed++;
+    continue;
+  }
   const out = path.join(OUT_DIR, name);
-  fs.writeFileSync(out, Buffer.from(bytes));
+  try {
+    ensureOutDir();
+    fs.writeFileSync(out, Buffer.from(bytes));
+  } catch (e) {
+    console.error('[gen_channel_a] FAIL: 写入失败 ' + out + '：' + (e && e.message));
+    failed++;
+    continue;
+  }
   console.log('A-channel:', path.basename(out), Math.round(bytes.length / 1024) + 'KB');
 }
+process.exit(failed ? 1 : 0);

package/top-ppt-html/scripts/hydrate_charts.py

@@ -7,12 +7,12 @@ Used after render_from_model.py — follows extract_snippet chart patterns
 """
 from __future__ import annotations
 
-import json
 import re
 import sys
 from pathlib import Path
 
-MODEL_RE = re.compile(r'window\.REPORT_MODEL = (\{[\s\S]*?\});')
+from render_from_model import extract_model_span
+
 PLACEHOLDER_SVG_RE = re.compile(
     r'<svg class="chart" data-chart="([^"]+)" viewBox="0 0 560 220">\s*'
     r'<!--[\s\S]*?-->\s*'
@@ -259,10 +259,41 @@ def svg_waterfall(labels, values, unit='') -> str:
             + '\n      '.join(parts) + '\n    </svg>')
 
 
-def build_svg(chart: dict) -> str:
+class ChartDataError(ValueError):
+    """图表数据非法：调用方应捕获并输出干净 FAIL（不打 Traceback）。"""
+
+
+def _coerce_values(values, ctx: str) -> list:
+    out = []
+    for i, v in enumerate(values):
+        try:
+            f = float(v)
+        except (TypeError, ValueError):
+            raise ChartDataError(f'{ctx}: values[{i}] 非数字（{str(v)[:40]!r}），无法绘制')
+        if f != f or f in (float('inf'), float('-inf')):
+            raise ChartDataError(f'{ctx}: values[{i}] 非有限数字，无法绘制')
+        out.append(f)
+    return out
+
+
+def validate_payload(chart: dict, ctx: str) -> tuple:
+    """校验图表数据：空数据/长度不一致/非数字一律干净报错，禁静默截断。"""
     ct = (chart.get('type') or 'bar').lower()
     labels = chart.get('labels') or []
     values = chart.get('values') or []
+    if not labels or not values:
+        raise ChartDataError(
+            f'{ctx}: labels/values 为空（labels={len(labels)} values={len(values)}），无法绘制 {ct} 图')
+    if len(labels) != len(values):
+        raise ChartDataError(
+            f'{ctx}: labels({len(labels)}) 与 values({len(values)}) 长度不一致，'
+            f'拒绝静默截断（{ct} 图）')
+    return list(labels), _coerce_values(values, ctx)
+
+
+def build_svg(chart: dict, ctx: str = '') -> str:
+    ct = (chart.get('type') or 'bar').lower()
+    labels, values = validate_payload(chart, ctx or f'图表({ct})')
     unit = chart.get('unit') or ''
     max_v = chart.get('max')
     if ct == 'hbar':
@@ -279,16 +310,17 @@ def build_svg(chart: dict) -> str:
 
 
 def iter_chart_payloads(model: dict):
-    """Yield chart dicts in document order (sections + split sides)."""
-    for sec in model.get('sections') or []:
+    """Yield (chart dict, context str) in document order (sections + split sides)."""
+    for si, sec in enumerate(model.get('sections') or []):
         st = (sec.get('type') or '').lower()
+        sctx = f'第{si + 1}节[{sec.get("title") or st}]'
         if st in ('bar', 'donut', 'exhibit', 'halftable') and sec.get('chart'):
             ch = dict(sec['chart'])
             if st == 'donut':
                 ch.setdefault('type', 'donut')
             elif not ch.get('type'):
                 ch['type'] = 'bar'
-            yield ch
+            yield ch, f'{sctx} 主图表'
         for side in ('left', 'right'):
             el = sec.get(side)
             if isinstance(el, dict) and el.get('labels') and el.get('values') is not None:
@@ -300,7 +332,7 @@ def iter_chart_payloads(model: dict):
                     'max': el.get('max'),
                     'centerLabel': el.get('centerLabel'),
                 }
-                yield ch
+                yield ch, f'{sctx} {side}区图表'
 
 
 def hydrate(html: str, model: dict) -> str:
@@ -311,7 +343,8 @@ def hydrate(html: str, model: dict) -> str:
         nonlocal idx
         if idx >= len(payloads):
             return m.group(0)
-        svg = build_svg(payloads[idx])
+        ch, ctx = payloads[idx]
+        svg = build_svg(ch, ctx)
         idx += 1
         return svg
 
@@ -324,13 +357,35 @@ def main() -> int:
         print('usage: _hydrate_charts.py <report.html>')
         return 2
     path = Path(sys.argv[1])
-    html = path.read_text(encoding='utf-8')
-    m = MODEL_RE.search(html)
-    if not m:
+    try:
+        html = path.read_text(encoding='utf-8')
+    except FileNotFoundError:
+        print(f'FAIL: 文件不存在 {path}')
+        return 1
+    except UnicodeDecodeError as e:
+        print(f'FAIL: 文件不是合法 UTF-8 {path}（{e}）')
+        return 1
+    except OSError as e:
+        print(f'FAIL: 读取失败 {path}（{e}）')
+        return 1
+    # 括号感知抽取（模型字符串含 `};` 时正则会提前截断；非法 JSON 走干净 FAIL）
+    try:
+        span = extract_model_span(html)
+    except SystemExit as e:
+        print(f'FAIL: {e}')
+        return 1
+    if not span:
         print('FAIL: no REPORT_MODEL')
         return 1
-    model = json.loads(m.group(1))
-    new_html, n_ph, used, total = hydrate(html, model)
+    model = span[2]
+    if not isinstance(model, dict):
+        print(f'FAIL: REPORT_MODEL 根节点必须是对象（得到 {type(model).__name__}）')
+        return 1
+    try:
+        new_html, n_ph, used, total = hydrate(html, model)
+    except ChartDataError as e:
+        print(f'FAIL: 图表数据非法——{e}')
+        return 1
     path.write_text(new_html, encoding='utf-8')
     left = new_html.count('见模型数据')
     print(f'hydrated placeholders={n_ph} used_payloads={used}/{total} remaining_placeholder={left}')

package/top-ppt-html/scripts/negative_tests.py

@@ -319,7 +319,7 @@ def main() -> int:
     else:
         print('  [SKIP] layout-qa 负例（scaffold 未产出 data-skel）')
 
-        ok = _pptx_notes_case() and ok
+    ok = _pptx_notes_case() and ok
     ok = _chart_data_case() and ok
     ok = _title_pattern_case() and ok
     ok = _font_scale_case() and ok

package/top-ppt-html/scripts/prepare_images.py

@@ -273,7 +273,7 @@ def main() -> int:
         lock_cls = (SPEC.get('ratioCssClass') or {}).get(args.layout) or f'media--r{ratio_class(w, h)}'
         html_bits.append(
             f'<figure class="media {lock_cls}{fit_cls} rv">\n'
-            f'  <img src="{url if len(url) < 400 else url[:60] + "…（见 images-snippets.html 全文）"}" '
+            f'  <img src="{url}" '
             f'alt="{src.stem}">\n'
             f'  <figcaption class="media__cap--below">图：{src.stem}（{w}×{h} · {ratio_label(w, h)}）</figcaption>\n'
             f'</figure>')

package/top-ppt-html/scripts/recommend_layout.py

@@ -350,15 +350,38 @@ def main() -> int:
 
     if args.stdin:
         raw = sys.stdin.read()
-        data = json.loads(raw) if raw.strip() else {}
+        try:
+            data = json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError as e:
+            print(f'错误：--stdin 不是合法 JSON: {e}')
+            return 2
+        if not isinstance(data, dict):
+            print('错误：--stdin 根节点必须是对象')
+            return 2
         mode = mode or data.get('mode')
         intents = intents or list(data.get('intents') or [])
         pages = pages if pages is not None else data.get('pages')
         model = data.get('model') or data if 'sections' in data else None
 
     if args.from_model:
-        model = json.loads(Path(args.from_model).read_text(encoding='utf-8'))
-        mode = mode or model.get('mode')
+        try:
+            model = json.loads(Path(args.from_model).read_text(encoding='utf-8'))
+        except FileNotFoundError:
+            print(f'错误：--from-model 文件不存在 {args.from_model}')
+            return 2
+        except UnicodeDecodeError as e:
+            print(f'错误：--from-model 不是合法 UTF-8 {args.from_model}: {e}')
+            return 2
+        except OSError as e:
+            print(f'错误：无法读取 --from-model {args.from_model}: {e}')
+            return 2
+        except json.JSONDecodeError as e:
+            print(f'错误：--from-model 不是合法 JSON {args.from_model}: {e}')
+            return 2
+        mode = mode or (model.get('mode') if isinstance(model, dict) else None)
+        if model is not None and not isinstance(model, dict):
+            print(f'错误：--from-model 根节点必须是对象（得到 {type(model).__name__}）')
+            return 2
 
     if not mode:
         ap.error('--mode is required (or provide via --from-model/--stdin)')

package/top-ppt-html/scripts/render_from_model.py

@@ -38,7 +38,43 @@ IMAGE_SPEC = LC.get('imageSpec') or {}
 
 CONTENT_RE = re.compile(
     r'(<!-- __TOPPPT_CONTENT_START__ -->)[\s\S]*?(<!-- __TOPPPT_CONTENT_END__ -->)')
-MODEL_RE = re.compile(r'window\.REPORT_MODEL = \{[\s\S]*?\};')
+MODEL_RE = re.compile(r'window\.REPORT_MODEL\s*=\s*')
+
+
+def _strict_decoder():
+    """标准 JSON 解码器：拒绝 NaN/Infinity（与 Node JSON.parse 同口径）。"""
+    def _reject_const(x):
+        raise ValueError(f'非法 JSON 常量 {x}')
+    return json.JSONDecoder(parse_constant=_reject_const)
+
+
+def extract_model_span(txt: str):
+    """括号感知抽取 window.REPORT_MODEL：返回 (start, end, model)。
+
+    start/end 是 JSON 文本在 txt 中的起止下标（含首尾花括号，不含末尾分号）。
+    用 JSONDecoder.raw_decode 而非正则 `\\{[\\s\\S]*?\\}`——模型字符串里若含 `};`
+   （如标题含代码片段），正则会提前截断导致解析失败或 --inplace 写坏文件。
+    """
+    m = MODEL_RE.search(txt)
+    if not m:
+        return None
+    try:
+        model, end = _strict_decoder().raw_decode(txt, m.end())
+    except json.JSONDecodeError as e:
+        raise SystemExit(f'REPORT_MODEL 不是合法 JSON: {e}（必须双引号/无尾逗号/无注释）')
+    except ValueError as e:
+        raise SystemExit(f'REPORT_MODEL 不是合法 JSON: {e}（必须双引号/无尾逗号/无注释）')
+    return m.start(), end, model
+
+
+def replace_model_json(txt: str, model: dict) -> str:
+    """把 txt 内 REPORT_MODEL 的 JSON 原子替换为 model（起止下标精确定位，不误伤正文）。"""
+    span = extract_model_span(txt)
+    if not span:
+        raise SystemExit('未找到 window.REPORT_MODEL')
+    start, end, _ = span
+    return (txt[:start] + 'window.REPORT_MODEL = '
+            + json.dumps(model, ensure_ascii=False, indent=2) + ';' + txt[end:])
 
 
 def esc(s) -> str:
@@ -508,6 +544,12 @@ def r_diagram(i, sec):
             if isinstance(nd, dict):
                 nds.append(f'          <div class="arch__node"><div class="arch__nt">{esc(nd.get("t") or "")}</div>'
                            f'<div class="arch__nd">{esc(nd.get("d") or "")}</div></div>')
+            elif isinstance(nd, (list, tuple)):
+                # [标题, 注解] 数组形态（scaffold_report 发射；不处理会原样打出 "['a', 'b']"）
+                t = nd[0] if len(nd) > 0 else ""
+                d = nd[1] if len(nd) > 1 else ""
+                nds.append(f'          <div class="arch__node"><div class="arch__nt">{esc(t)}</div>'
+                           f'<div class="arch__nd">{esc(d)}</div></div>')
             else:
                 nds.append(f'          <div class="arch__node"><div class="arch__nt">{esc(nd)}</div></div>')
         rows.append(
@@ -838,13 +880,30 @@ def render_body(model: dict) -> str:
 
 
 def load_model(path: Path) -> dict:
-    txt = path.read_text(encoding='utf-8')
+    try:
+        txt = path.read_text(encoding='utf-8')
+    except FileNotFoundError:
+        raise SystemExit(f'模型文件不存在: {path}')
+    except UnicodeDecodeError as e:
+        raise SystemExit(f'模型文件不是合法 UTF-8: {path}（{e}）')
+    except OSError as e:
+        raise SystemExit(f'模型文件读取失败: {path}（{e}）')
     if path.suffix.lower() == '.json':
-        return json.loads(txt)
-    m = re.search(r'window\.REPORT_MODEL\s*=\s*(\{[\s\S]*?\})\s*;', txt)
-    if not m:
+        try:
+            model = _strict_decoder().decode(txt)
+        except json.JSONDecodeError as e:
+            raise SystemExit(f'模型不是合法 JSON: {path}（{e}）')
+        except ValueError as e:
+            raise SystemExit(f'模型不是合法 JSON: {path}（{e}）')
+        if not isinstance(model, dict):
+            raise SystemExit(f'模型根节点必须是对象: {path}（得到 {type(model).__name__}）')
+        return model
+    span = extract_model_span(txt)
+    if not span:
         raise SystemExit('未找到 window.REPORT_MODEL')
-    return json.loads(m.group(1))
+    if not isinstance(span[2], dict):
+        raise SystemExit(f'REPORT_MODEL 根节点必须是对象（得到 {type(span[2]).__name__}）')
+    return span[2]
 
 
 def _strip_refs_nav(html: str, body: str) -> str:
@@ -879,11 +938,14 @@ def main() -> int:
             return 2
         t = CONTENT_RE.sub(
             r'\1\n' + body.replace('\\', '\\\\') + r'\n\2', t, count=1)
-        # 同步模型（确保与渲染源一致）
-        t = MODEL_RE.sub('window.REPORT_MODEL = ' +
-                         json.dumps(model, ensure_ascii=False, indent=2) + ';', t, count=1)
+        # 同步模型（确保与渲染源一致；span 精确定位，模型字符串含 `};` 也不写坏）
+        t = replace_model_json(t, model)
         t = _strip_refs_nav(t, body)
-        src.write_text(t, encoding='utf-8')
+        try:
+            src.write_text(t, encoding='utf-8')
+        except OSError as e:
+            print(f'错误：--inplace 写回失败 {src}（{e}）', file=sys.stderr)
+            return 1
         print(f'已按模型重渲染正文：{src}（{len(body)} 字符）')
         print(f'  下一步: python scripts/validate_report.py "{src}" --strict')
         return 0
@@ -899,11 +961,14 @@ def main() -> int:
         print('错误：模板缺少 CONTENT 标记', file=sys.stderr)
         return 2
     t = CONTENT_RE.sub(r'\1\n' + body.replace('\\', '\\\\') + r'\n\2', t, count=1)
-    t = MODEL_RE.sub('window.REPORT_MODEL = ' +
-                     json.dumps(model, ensure_ascii=False, indent=2) + ';', t, count=1)
+    t = replace_model_json(t, model)
     t = _strip_refs_nav(t, body)
     out = Path(args.out or (src.with_suffix('.html')))
-    out.write_text(t, encoding='utf-8')
+    try:
+        out.write_text(t, encoding='utf-8')
+    except OSError as e:
+        print(f'错误：输出写入失败 {out}（{e}）', file=sys.stderr)
+        return 1
     print(f'已从模型生成：{out}  sections={len(model.get("sections") or [])}')
     print(f'  下一步: python scripts/validate_report.py "{out}" --strict')
     return 0

package/top-ppt-html/scripts/scaffold_report.py

@@ -930,11 +930,47 @@ def main() -> int:
     t = tpl_path.read_text(encoding='utf-8')
 
     style = args.style or TPL_DEFAULT_STYLE[mode]
+    # 风格早校验：未知风格现在拦下（干净报错），而不是生成一份后续 validate 才判 FAIL 的 HTML
+    _lc_styles = None
+    try:
+        _lc = json.loads((ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8'))
+        _lc_styles = sorted(k for k in (_lc.get('styles') or {}) if not str(k).startswith('$'))
+    except (OSError, ValueError):
+        _lc_styles = None  # 单源读不到时不拦（校验门禁兜底）
+    if _lc_styles and style not in _lc_styles:
+        print(f'错误：未知风格 {style!r}（可选：{" / ".join(_lc_styles)}）')
+        return 2
     theme = args.theme or ('dark' if style == 'graphite-dark' else 'light')
-    n = args.sections if args.sections else {'presentation': 8, 'research': 10, 'architecture': 3}[mode]
+    n = args.sections if args.sections is not None else {'presentation': 8, 'research': 10, 'architecture': 3}[mode]
+    if n < 0:
+        print(f'错误：--sections 必须 ≥ 0（得到 {n}）')
+        return 2
     plan = None
     if args.plan:
-        plan = json.loads(Path(args.plan).read_text(encoding='utf-8'))
+        plan_path = Path(args.plan)
+        try:
+            plan_text = plan_path.read_text(encoding='utf-8')
+        except FileNotFoundError:
+            print(f'错误：--plan 文件不存在 {plan_path}')
+            return 2
+        except UnicodeDecodeError as e:
+            print(f'错误：--plan 不是合法 UTF-8 {plan_path}: {e}')
+            return 2
+        except OSError as e:
+            print(f'错误：无法读取 --plan {plan_path}: {e}')
+            return 2
+        try:
+            plan = json.loads(plan_text)
+        except json.JSONDecodeError as e:
+            print(f'错误：--plan 不是合法 JSON {plan_path}: {e}')
+            return 2
+        if not isinstance(plan, list):
+            print(f'错误：--plan 根节点必须是数组（得到 {type(plan).__name__}）')
+            return 2
+        bad_items = [k for k, it in enumerate(plan) if not isinstance(it, dict)]
+        if bad_items:
+            print(f'错误：--plan 第 {", ".join(str(k + 1) for k in bad_items)} 项不是对象（每项应为 {{"type","eyebrow","title"}}）')
+            return 2
         n = len(plan)
     pages = build_plan(mode, n, plan, preset=args.preset)
 
@@ -1053,7 +1089,11 @@ def main() -> int:
 
     out = Path(args.out)
     out.parent.mkdir(parents=True, exist_ok=True)
-    out.write_text(t, encoding='utf-8')
+    try:
+        out.write_text(t, encoding='utf-8')
+    except OSError as e:
+        print(f'错误：输出写入失败 {out}（{e}）', file=sys.stderr)
+        return 1
     print(f'已生成骨架：{out}  {len(t)} 字符')
     print(f'  模式 {mode} · 风格 {style} · 主题 {theme} · 内容页 {len(pages)}'
           f'（{"含" if show_agenda else "省略"} Agenda'

package/top-ppt-html/scripts/sync_runtime.py

@@ -298,7 +298,11 @@ def build_schema_block(ms: dict) -> str:
 
 
 def inject(path: Path, pat: re.Pattern, repl: str, label: str) -> bool:
-    src = path.read_text(encoding='utf-8')
+    try:
+        src = path.read_text(encoding='utf-8')
+    except OSError as e:
+        print(f'错误: 无法读取 {path.name}: {e}')
+        return False
     if not pat.search(src):
         print(f'错误: {path.name} 缺少 {label} 标记块')
         return False
@@ -310,15 +314,39 @@ def main() -> int:
     if not LC.exists():
         print(f'错误: 找不到 {LC}')
         return 2
-    lc = json.loads(LC.read_text(encoding='utf-8'))
+    try:
+        lc = json.loads(LC.read_text(encoding='utf-8'))
+    except UnicodeDecodeError as e:
+        print(f'错误: {LC.name} 不是合法 UTF-8: {e}')
+        return 2
+    except json.JSONDecodeError as e:
+        print(f'错误: {LC.name} 不是合法 JSON: {e}')
+        return 2
+    except OSError as e:
+        print(f'错误: 无法读取 {LC}: {e}')
+        return 2
     if not MS.exists():
         print(f'错误: 找不到 {MS}（DSL schema 单源）')
         return 2
-    ms = json.loads(MS.read_text(encoding='utf-8'))
+    try:
+        ms = json.loads(MS.read_text(encoding='utf-8'))
+    except UnicodeDecodeError as e:
+        print(f'错误: {MS.name} 不是合法 UTF-8: {e}')
+        return 2
+    except json.JSONDecodeError as e:
+        print(f'错误: {MS.name} 不是合法 JSON: {e}')
+        return 2
+    except OSError as e:
+        print(f'错误: 无法读取 {MS}: {e}')
+        return 2
     ok = True
 
     # ① 重新生成 pptx-export.js 常量块 + schema 块
-    src = PE.read_text(encoding='utf-8')
+    try:
+        src = PE.read_text(encoding='utf-8')
+    except OSError as e:
+        print(f'错误: 无法读取 {PE}: {e}')
+        return 1
     if not CONST_PAT.search(src):
         print('错误: assets/pptx-export.js 缺少 __TOPPPT_CONSTANTS__ 标记块')
         return 1

package/top-ppt-html/scripts/test_feedback_gates.py

@@ -172,6 +172,29 @@ def test_annotation_band_fires_when_note_present() -> None:
     )
 
 
+def test_annotation_band_textbox_to_content_bottom_no_note() -> None:
+    """Text box framed to contentBottom (6.9) with no annotation is engine-intent
+    (empty frame, no ink invasion) — severe safety net must not fire (cf. 3c)."""
+    xml = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        f'<p:sp xmlns:a="{NS["a"]}" xmlns:p="{NS["p"]}">'
+        "<p:spPr><a:xfrm>"
+        f'<a:off x="{int(0.6 * EMU)}" y="{int(2.35 * EMU)}"/>'
+        f'<a:ext cx="{int(6 * EMU)}" cy="{int(4.55 * EMU)}"/>'
+        "</a:xfrm></p:spPr>"
+        "<p:txBody><a:p><a:r><a:t>发现要点</a:t></a:r></a:p></p:txBody>"
+        "</p:sp>"
+    )
+    el = ET.fromstring(xml)
+    issues = V.annotation_band_overlap_check([el], 1, int(7.5 * EMU))
+    codes = [i["code"] for i in issues]
+    ok(
+        "3e textbox to 6.90 without annotation does not fire",
+        "ANNOTATION_BAND_OVERLAP" not in codes,
+        f"codes={codes}",
+    )
+
+
 def test_font_size_h2_17_allowed() -> None:
     """modeTypeScale h2=17 must be on the allowed set (cover/display whitelist)."""
     xml = (
@@ -425,6 +448,7 @@ def main() -> int:
     test_annotation_band_ignores_full_bleed_bg()
     test_annotation_band_allows_content_without_note()
     test_annotation_band_fires_when_note_present()
+    test_annotation_band_textbox_to_content_bottom_no_note()
     test_annotation_band_reports_all_invaders()
     test_annotation_band_so_what_band_top()
     test_element_overlap()

package/top-ppt-html/scripts/validate_pptx.py

@@ -418,6 +418,13 @@ def annotation_band_overlap_check(
     def _text(el: ET.Element) -> str:
         return (text_content(el) or "").strip()
 
+    def _has_txbody(el: ET.Element) -> bool:
+        # 命名空间无关：是否存在 p:txBody 后代（文本框）
+        for d in el.iter():
+            if isinstance(d.tag, str) and d.tag.rsplit("}", 1)[-1] == "txBody":
+                return True
+        return False
+
     def _is_chrome_or_bg(y: int, cy: int, cx: int) -> bool:
         if (cx * cy) / slide_area >= full_bleed_area and y <= int(0.05 * 914400):
             return True
@@ -501,7 +508,9 @@ def annotation_band_overlap_check(
         overlap = min(bottom, band_bot) - band_top
         if overlap < min_overlap:
             continue
-        if has_annotation or overlap >= severe_overlap:
+        # 无注释页文本框底框到 contentBottom 是引擎有意为之（框内无墨水侵入注释带），
+        # severe 安全网仅对非文本形状保留（feedback gate 用例 3：无 txBody 形状仍触发）。
+        if has_annotation or (overlap >= severe_overlap and not _has_txbody(el)):
             out.append(issue(
                 "ANNOTATION_BAND_OVERLAP",
                 f"主内容侵入注释带（元素底边 {bottom/914400:.2f}in 越过注释带顶 "