@topmindspace/tms-skills 0.1.0

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

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 文档一致性审计（规范与引用完整性 · 零依赖）
+
+用法:
+    python scripts/audit_docs.py            # 全量审计
+    python scripts/audit_docs.py --quiet    # 仅打印结论
+
+审计项（任一不过 → 退出码 1）:
+  ① § 引用可解析性 —— references 采用**跨文件唯一稳定编号**（§1–§77），
+     所有 `§数字` 引用必须能在三份组件/图表规范中解析到章节
+     （白名单：`design-system.md` 自有子节 §1a–§1f / §9b–§9d）
+  ② 文件前缀规范性 —— 引用组件/图表规范时须带正确文件名，且不出现
+     重复前缀（`` `charts.md` charts.md §N ``）或裸前缀（`charts.md §N` 未加反引号）
+  ③ §46 选型表覆盖度 —— 36 个登记图表类型与 29 个页型都必须在选型表出现
+  ④ 图表代码节齐备 —— 每个登记图表类型都要在 charts.md / infographics.md 有 `data-chart` 代码节
+  ⑤ 篇数与必需文件 —— references 篇数、SKILL.md frontmatter、进包必需文件齐全
+  ⑥ 任务路由可解析性 —— extract_snippet.py 的 TASK_ROUTES 每条 (文件, 节) 必须可
+     实际抽取（防「文字声明同源」漂移：路由声明的节在文件里找不到即失败；
+     空节路由 = 该文件只能整读，≥20KB 的 L2 文件不允许）
+
+何时跑：改 `references/*`、拆分/新增规范文件、调整选型表后（与 regression.py 互补——
+后者管交付物正确性，本工具管规范自洽性）。
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from package_skill import DESC_LIMIT, NAME, REQUIRED  # noqa: E402  （复用进包清单，避免两处维护）
+import extract_snippet as ES  # noqa: E402  （⑥ 任务路由审计复用同一解析器，避免第三源）
+
+ROOT = Path(__file__).resolve().parent.parent
+REF = ROOT / 'references'
+QUIET = '--quiet' in sys.argv[1:]
+
+# 组件/图表族物理文件（components.md / charts.md 为逻辑索引；§编号跨文件稳定）
+COMPONENT_FILES = (
+    'components.md', 'components-atoms.md', 'layouts-research.md',
+    'layouts-architecture.md', 'layouts-combo.md',
+)
+CHART_FILES = (
+    'charts.md', 'charts-basic.md', 'charts-extended.md', 'charts-discipline.md',
+)
+OWNER_SRC = tuple(
+    [(fn, r'^## (\d+[a-z]?)\. ') for fn in COMPONENT_FILES + CHART_FILES]
+    + [('infographics.md', r'^### (7[1-9]|8\d)\.? '),
+       ('infographics-stats.md', r'^### (?:§)?(\d+[a-z]?)\.?\s'),
+       ('infographics-structure.md', r'^### (?:§)?(\d+[a-z]?)\.?\s')]
+)
+# design-system.md 自有子节编号（不算悬空）
+DS_OWN = {'1a', '1b', '1c', '1d', '1e', '1f', '9b', '9c', '9d'}
+DUP_PRE = re.compile(r'`(components|charts|infographics)\.md`\s*[（(]?\s*`?\1\.md')
+BARE_PRE = re.compile(r'(?<![`\w])(components|charts|infographics)\.md\s*§')
+REF_ID = re.compile(r'§\s*(\d+[a-zA-Z]?)')  # 节号后缀大小写均收录（§38b / §46C 一并受审计）
+
+
+def doc_files():
+    files = ['SKILL.md', 'README.md']
+    files += ['references/%s' % p.name for p in sorted(REF.glob('*.md'))]
+    return files
+
+
+def main() -> int:
+    errs: list[str] = []
+    lc = json.loads((ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8'))
+    ms = json.loads((ROOT / 'scripts' / 'model-schema.json').read_text(encoding='utf-8'))
+
+    owner: dict[str, str] = {}
+    for f, pat in OWNER_SRC:
+        p = REF / f
+        if not p.exists():
+            continue
+        for m in re.finditer(pat, p.read_text(encoding='utf-8'), re.M):
+            owner[m.group(1)] = f
+
+    # ① § 引用可解析性
+    dangling = 0
+    for rel in doc_files():
+        for i, ln in enumerate((ROOT / rel).read_text(encoding='utf-8').splitlines()):
+            for m in REF_ID.finditer(ln):
+                i_d = m.group(1)
+                if i_d in owner or i_d in DS_OWN:
+                    continue
+                dangling += 1
+                errs.append(f'悬空引用 {rel} L{i+1}: §{i_d}')
+    print(f'① § 引用可解析性：悬空 {dangling} 处（编号空间 {len(owner)} 项）')
+
+    # ② 文件前缀规范性
+    prefix_bad = 0
+    for rel in doc_files():
+        for i, ln in enumerate((ROOT / rel).read_text(encoding='utf-8').splitlines()):
+            if DUP_PRE.search(ln):
+                prefix_bad += 1
+                errs.append(f'重复文件前缀 {rel} L{i+1}')
+            if BARE_PRE.search(ln):
+                prefix_bad += 1
+                errs.append(f'裸文件前缀 {rel} L{i+1}')
+    print(f'② 文件前缀规范性：异常 {prefix_bad} 处')
+
+    # ③ §46 选型表覆盖度（物理文件 layouts-combo.md；逻辑名 components.md 亦可）
+    combo = REF / 'layouts-combo.md'
+    if not combo.exists():
+        combo = REF / 'components.md'
+    comp = combo.read_text(encoding='utf-8')
+    sec46 = re.search(r'## 46\. .*?\n(.*?)\n## 46b\.', comp, re.S)
+    table = sec46.group(1) if sec46 else ''
+    chart_types = lc['charts']['types']
+    page_types = [k for k in ms['pageTypes'] if not k.startswith('$')]
+    miss_chart = [t for t in chart_types if t not in table]
+    miss_page = [t for t in page_types if ('`%s`' % t) not in table]
+    if miss_chart:
+        errs.append(f'§46 未覆盖图表类型：{miss_chart}')
+    if miss_page:
+        errs.append(f'§46 未覆盖页型：{miss_page}')
+    print(f'③ §46 选型表覆盖：图表 {len(chart_types) - len(miss_chart)}/{len(chart_types)} · '
+          f'页型 {len(page_types) - len(miss_page)}/{len(page_types)}')
+
+    # ④ 图表代码节齐备（拆分后的 charts-* + infographics）
+    charts_txt = ''
+    for fn in CHART_FILES + ('infographics.md', 'infographics-stats.md', 'infographics-structure.md'):
+        p = REF / fn
+        if p.exists():
+            charts_txt += p.read_text(encoding='utf-8')
+    no_code = [t for t in chart_types
+               if not re.search(r'data-chart="%s"' % re.escape(t), charts_txt)]
+    if no_code:
+        errs.append(f'缺代码节的图表类型：{no_code}')
+    print(f'④ 图表代码节：{len(chart_types) - len(no_code)}/{len(chart_types)} 齐备')
+
+    # ⑤ 篇数与必需文件
+    n_ref = len(list(REF.glob('*.md')))
+    sk = (ROOT / 'SKILL.md').read_text(encoding='utf-8')
+    d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M | re.S)
+    dlen = len(d.group(1)) if d else -1
+    nm = re.search(r'^name:\s*(\S+)\s*$', sk, re.M)
+    missing = [r for r in REQUIRED if not (ROOT / r).exists()]
+    if dlen < 0 or dlen > DESC_LIMIT:
+        errs.append(f'SKILL.md description 长度异常：{dlen}（上限 {DESC_LIMIT}）')
+    if not nm or nm.group(1) != NAME:
+        errs.append(f'SKILL.md name 与技能名 {NAME} 不一致')
+    if missing:
+        errs.append(f'缺必需文件：{missing}')
+    print(f'⑤ 规范篇数 {n_ref} · description {dlen} 字符 · 必需文件缺 {len(missing)} 项')
+
+    # ⑥ 任务路由可解析性（--task 与 validate_report FIX_GUIDE 的修复链路依赖它；
+    #    实现与 regression ⑦-b 共用 ES.verify_routes，防两处维护）
+    route_bad = ES.verify_routes()
+    unresolved = [x for x in route_bad if not x.endswith('空路由')]
+    empty_routes = [x for x in route_bad if x.endswith('空路由')]
+    if unresolved:
+        errs.append(f'任务路由不可解析（--task/FIX_GUIDE 修复链路断裂）：{unresolved}')
+    if empty_routes:
+        errs.append(f'任务路由空节（整读大文件，应补节号或标题关键词）：{empty_routes}')
+    print(f'⑥ 任务路由可解析性：{len(ES.TASK_ROUTES)} 条路由 · 不可解析 {len(unresolved)} · 空节 {len(empty_routes)}')
+
+    print()
+    if errs:
+        print('审计未通过：')
+        for e in errs:
+            print(f'  ✗ {e}')
+        return 1
+    print('文档一致性审计通过：引用可解析 · 前缀规范 · 选型表全覆盖 · 代码节齐备 · 元数据合规')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 技能工程审计（零依赖 · 体积预算 / 渐进式披露 / 触发门禁 / 冗余）
+
+用法:
+    python scripts/audit_skill.py            # 全量审计
+    python scripts/audit_skill.py --quiet    # 仅打印结论
+    python scripts/audit_skill.py --json     # 机器可读
+
+为什么需要它（第一性原理）:
+    技能的成本 = **加载进上下文的字节数** + **必须执行的步骤数**。这两项在 v7.1 完全无预算、
+    无门禁，导致"技能越做越全 → 单次生成越慢越贵"。本脚本把「效率目标」变成可检查项。
+
+审计项（任一不过 → 退出码 1）:
+  ① 体积预算   —— SKILL.md / 常读入口 playbook.md / 单份 reference / 模式模板 的上限
+  ② 元数据     —— frontmatter name 与技能名一致；description ≤ DESC_HARD，且 ≤ DESC_SOFT（触发精度）
+  ③ 披露分层   —— SKILL.md 必须声明 L0/L1/L2 三档，且 L1（常读入口）恰好 1 份
+  ④ 交互门禁   —— SKILL.md 必须含「Gate 0 参考图先行」，且其出现位置在「六项问询」之前
+  ⑤ 效率预算   —— SKILL.md 必须显式声明交互轮次上限与必读文件数上限
+  ⑥ 引用完整性 —— SKILL.md 与 playbook.md 提到的 references/*.md 必须存在
+  ⑦ 冗余报告   —— SKILL.md ↔ 全部 references（含 playbook）的归一化共同片段
+                 （≥20 字含 CJK；命令行/路径等纯 ASCII 重复豁免）
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from package_skill import DESC_LIMIT, NAME  # noqa: E402  复用进包门禁的同一常量
+
+ROOT = Path(__file__).resolve().parent.parent
+REF = ROOT / 'references'
+TPL = ROOT / 'assets' / 'templates'
+QUIET = '--quiet' in sys.argv[1:]
+AS_JSON = '--json' in sys.argv[1:]
+
+# ── 效率预算（唯一来源；调整预算改这里）──────────────────────────────────
+BUDGET = {
+    'skill_md': 13 * 1024,        # 入口路由：加载即占上下文，必须瘦（v8.3 从 16KB 收紧：SKILL.md 瘦身后 12.4KB + 余量）
+    'playbook': 22 * 1024,        # 唯一常读入口（决策层：模式/版式/图表/配色/校验）
+    'reference': 96 * 1024,       # 单份深度文件上限
+    'template': 320 * 1024,       # 模式模板（引擎+运行时内联，天然大；靠 scaffold 脚本避免被读）
+    'desc_soft': 700,             # description 软上限（触发精度）
+    'desc_hard': DESC_LIMIT,      # description 硬上限（宿主规范）
+    'l1_files': 1,                # 常读入口份数
+}
+PLAYBOOK = REF / 'playbook.md'
+
+# 「内容两处维护」检测：归一化滑窗子串（v8.3 起）。
+# 旧实现只切 ≥40 字整句且**排除 playbook** —— 表格行/公式/判定条件全部漏检。
+# 新实现：整库归一化（去空白与 markdown 修饰符）后做滑窗子串匹配，
+# 窗口须含 CJK（纯 ASCII 的命令行/路径重复属工具语义，豁免）。
+_NORM_STRIP = re.compile(r'[`*_#>\[\]()|:：,，。;；\s·—\-–/\\="「」『』（）]')
+_CJK = re.compile(r'[\u4e00-\u9fff]')
+DUP_WIN = 20       # 共同片段最小归一化长度（<20 的短语级重合属合理摘要，放行）
+DUP_MAX = 0        # 允许的重复片段上限（S2-1 瘦身后应为 0）
+
+
+def norm_text(text: str) -> str:
+    return _NORM_STRIP.sub('', text)
+
+
+def dup_spans(sk_text: str, refs_text: str) -> list[str]:
+    """返回 SKILL.md 与 references 的共同归一化片段（合并相邻窗口）。"""
+    a, b = norm_text(sk_text), norm_text(refs_text)
+    ranges: list[tuple[int, int]] = []
+    i = 0
+    while i + DUP_WIN <= len(a):
+        w = a[i:i + DUP_WIN]
+        if _CJK.search(w) and w in b:
+            p = b.find(w)
+            lo, hi = i, i + DUP_WIN
+            # 命中后向两侧扩展到最长共同片段（闭合步长 4 的对齐缺口）
+            while lo > 0 and p > 0 and a[lo - 1] == b[p - 1]:
+                lo -= 1
+                p -= 1
+            hi_b = p + DUP_WIN
+            while hi < len(a) and hi_b < len(b) and a[hi] == b[hi_b]:
+                hi += 1
+                hi_b += 1
+            if ranges and lo <= ranges[-1][1]:
+                ranges[-1] = (ranges[-1][0], hi)
+            else:
+                ranges.append((lo, hi))
+            i = hi  # 跳过已覆盖区间（顺带提速）
+        else:
+            i += 4
+    return [a[lo:hi] for lo, hi in ranges]
+
+
+def kb(n: int) -> str:
+    return f'{n / 1024:.1f}KB'
+
+
+def main() -> int:
+    errs: list[str] = []
+    notes: list[str] = []
+    rows: list[tuple[str, bool, str]] = []
+
+    def chk(name: str, ok: bool, bad_detail: str, ok_detail: str | None = None,
+            fatal: bool = True) -> None:
+        """bad_detail 用于失败说明；ok_detail 用于通过说明（缺省复用 bad_detail）。"""
+        detail = (ok_detail if (ok and ok_detail is not None) else bad_detail)
+        rows.append((name, ok, detail))
+        if not ok:
+            (errs if fatal else notes).append(f'{name}: {bad_detail}')
+
+    sk_path = ROOT / 'SKILL.md'
+    sk = sk_path.read_text(encoding='utf-8')
+
+    # ① 体积预算
+    sk_size = sk_path.stat().st_size
+    chk('① SKILL.md 体积', sk_size <= BUDGET['skill_md'],
+        f'{kb(sk_size)} / 上限 {kb(BUDGET["skill_md"])}')
+
+    pb_size = PLAYBOOK.stat().st_size if PLAYBOOK.exists() else -1
+    chk('① 常读入口 playbook.md', 0 < pb_size <= BUDGET['playbook'],
+        f'{kb(pb_size)} / 上限 {kb(BUDGET["playbook"])}' if pb_size > 0
+        else f'缺失（应存在且 ≤ {kb(BUDGET["playbook"])}）')
+
+    over_ref = [(p.name, p.stat().st_size) for p in sorted(REF.glob('*.md'))
+                if p.stat().st_size > BUDGET['reference']]
+    chk('① 单份 reference 体积', not over_ref,
+        '; '.join(f'{n} {kb(s)}' for n, s in over_ref) or
+        f'最大 {kb(max((p.stat().st_size for p in REF.glob("*.md")), default=0))} / 上限 {kb(BUDGET["reference"])}')
+
+    over_tpl = [(p.name, p.stat().st_size) for p in sorted(TPL.glob('*.html'))
+                if p.stat().st_size > BUDGET['template']]
+    chk('① 模式模板体积', not over_tpl,
+        '; '.join(f'{n} {kb(s)}' for n, s in over_tpl) or
+        f'最大 {kb(max((p.stat().st_size for p in TPL.glob("*.html")), default=0))} / 上限 {kb(BUDGET["template"])}')
+
+    # ② 元数据
+    d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M | re.S)
+    dlen = len(d.group(1)) if d else -1
+    nm = re.search(r'^name:\s*(\S+)\s*$', sk, re.M)
+    chk('② name 一致', bool(nm) and nm.group(1) == NAME,
+        f'name={nm.group(1) if nm else "缺失"}（应为 {NAME}）')
+    chk('② description 硬上限', 0 < dlen <= BUDGET['desc_hard'],
+        f'{dlen} / 上限 {BUDGET["desc_hard"]}')
+    chk('② description 软上限（触发精度）', 0 < dlen <= BUDGET['desc_soft'],
+        f'{dlen} / 建议 ≤ {BUDGET["desc_soft"]}')
+
+    # ③ 渐进式披露分层（机器可读标记：L0=… · L1=… · L2=…）
+    m_l1 = re.search(r'L1\s*=\s*`?([^`\s·|]+)`?', sk)
+    has_l0 = bool(re.search(r'L0\s*=', sk))
+    has_l2 = bool(re.search(r'L2\s*=', sk))
+    l1_files = [f.strip() for f in re.split(r'[,、]', m_l1.group(1)) if f.strip()] if m_l1 else []
+    chk('③ 披露分层 L0/L1/L2', has_l0 and has_l2 and len(l1_files) == BUDGET['l1_files'],
+        f'L0={has_l0} L1={l1_files} L2={has_l2}（L1 须恰好 {BUDGET["l1_files"]} 份）')
+    chk('③ 常读入口存在', bool(l1_files) and all((ROOT / f).exists() for f in l1_files),
+        f'L1={l1_files} 不存在', f'{l1_files} 存在')
+
+    # ④ Gate 0（参考图先行）
+    g0 = sk.find('Gate 0')
+    ask = sk.find('六项问询')
+    chk('④ Gate 0 存在', g0 >= 0, '未找到「Gate 0」标记', '已就位')
+    chk('④ Gate 0 在问询之前', g0 >= 0 and ask >= 0 and g0 < ask,
+        f'Gate0@{g0} 未在六项问询@{ask} 之前', f'位置正确（{g0} < {ask}）')
+
+    # ⑤ 效率预算声明
+    chk('⑤ 交互轮次预算', bool(re.search(r'交互轮次|轮次上限|≤\s*3\s*轮', sk)),
+        'SKILL.md 未声明交互轮次上限', '已声明（≤3 轮）')
+    chk('⑤ 必读文件预算', bool(re.search(r'必读.{0,6}上限|必读文件数|只读当前需要的|不预读', sk)),
+        'SKILL.md 未声明必读文件预算/不预读纪律', '已声明（不预读纪律）')
+
+    # ⑥ 引用完整性
+    missing: list[str] = []
+    n_refs = 0
+    for src, text in (('SKILL.md', sk),
+                      ('references/playbook.md',
+                       PLAYBOOK.read_text(encoding='utf-8') if PLAYBOOK.exists() else '')):
+        for rel in sorted(set(re.findall(r'references/([a-z0-9\-]+\.md)', text))):
+            n_refs += 1
+            if not (REF / rel).exists():
+                missing.append(f'{src} → references/{rel}')
+    chk('⑥ 引用文件存在', not missing, '; '.join(missing),
+        f'{n_refs} 处引用全部存在')
+
+    # ⑦ 冗余报告（SKILL.md ↔ 全部 references，含 playbook；归一化滑窗子串）
+    refs_all = '\n'.join(p.read_text(encoding='utf-8') for p in sorted(REF.glob('*.md')))
+    dup = dup_spans(sk, refs_all)
+    chk('⑦ 内容重复（SKILL.md ↔ references · 归一化 ≥%d 字）' % DUP_WIN,
+        len(dup) <= DUP_MAX,
+        f'{len(dup)} 处重复' + (f'：{dup[0][:40]}…' if dup else ''),
+        f'0 处重复（≥{DUP_WIN} 字归一化片段）')
+
+    # ── 输出 ────────────────────────────────────────────────────────────────
+    if AS_JSON:
+        print(json.dumps({'rows': [{'item': r[0], 'ok': r[1], 'detail': r[2]} for r in rows],
+                          'errors': errs, 'notes': notes}, ensure_ascii=False, indent=2))
+        return 1 if errs else 0
+    if not QUIET:
+        print('技能工程审计 · 效率预算与门禁\n' + '-' * 56)
+        for n, ok, det in rows:
+            print(f'  {"✓" if ok else "✗"} {n}：{det}')
+        if notes:
+            print('\n提示（不判失败）：')
+            for n in notes:
+                print(f'  · {n}')
+        print('-' * 56)
+    if errs:
+        print(f'技能工程审计未通过：{len(errs)} 项')
+        for e in errs:
+            print(f'  ✗ {e}')
+        return 1
+    print('技能工程审计通过：体积达标 · 元数据合规 · 三档披露 · Gate 0 就位 · 预算已声明')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())