@topmindspace/tms-skills 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +13 -3
  3. package/bin/tms-skills.js +7 -2
  4. package/package.json +1 -1
  5. package/top-ppt-html/README.md +69 -148
  6. package/top-ppt-html/SKILL.md +42 -23
  7. package/top-ppt-html/agents/openai.yaml +5 -0
  8. package/top-ppt-html/assets/theme-overview-architecture.png +0 -0
  9. package/top-ppt-html/assets/theme-overview-research.png +0 -0
  10. package/top-ppt-html/assets/theme-overview.png +0 -0
  11. package/top-ppt-html/evals/trigger-queries.json +181 -0
  12. package/top-ppt-html/package.json +3 -2
  13. package/top-ppt-html/references/chart-decision-tree.md +42 -0
  14. package/top-ppt-html/references/charts-discipline.md +3 -1
  15. package/top-ppt-html/references/charts.md +24 -15
  16. package/top-ppt-html/references/content-rules.md +54 -34
  17. package/top-ppt-html/references/default-surface.md +62 -0
  18. package/top-ppt-html/references/design-system.md +2 -2
  19. package/top-ppt-html/references/failure-modes.md +14 -1
  20. package/top-ppt-html/references/icons.md +56 -277
  21. package/top-ppt-html/references/illustration-layout.md +39 -0
  22. package/top-ppt-html/references/layout-grammar.md +16 -6
  23. package/top-ppt-html/references/modes.md +16 -11
  24. package/top-ppt-html/references/outline-design.md +24 -0
  25. package/top-ppt-html/references/page-type-matrix.md +35 -0
  26. package/top-ppt-html/references/playbook.md +42 -86
  27. package/top-ppt-html/references/pptx-export.md +20 -2
  28. package/top-ppt-html/references/presentation-craft.md +77 -0
  29. package/top-ppt-html/references/tech-design.md +11 -5
  30. package/top-ppt-html/scripts/audit_docs.py +1 -1
  31. package/top-ppt-html/scripts/audit_skill.py +45 -6
  32. package/top-ppt-html/scripts/build_examples.py +39 -2260
  33. package/top-ppt-html/scripts/build_pptx.js +6 -0
  34. package/top-ppt-html/scripts/check_triggers.py +153 -0
  35. package/top-ppt-html/scripts/checks_html.py +39 -0
  36. package/top-ppt-html/scripts/cross_verify.py +5 -1
  37. package/top-ppt-html/scripts/extract_snippet.py +2 -2
  38. package/top-ppt-html/scripts/layout-constants.json +111 -18
  39. package/top-ppt-html/scripts/lib_layout_regions.js +7 -9
  40. package/top-ppt-html/scripts/negative_tests.py +137 -1
  41. package/top-ppt-html/scripts/package_skill.py +29 -10
  42. package/top-ppt-html/scripts/quality_gate.py +11 -3
  43. package/top-ppt-html/scripts/recommend_layout.py +384 -0
  44. package/top-ppt-html/scripts/regression.py +1 -1
  45. package/top-ppt-html/scripts/smoke_pptx.sh +30 -0
  46. package/top-ppt-html/scripts/sync_runtime.py +22 -25
  47. package/top-ppt-html/scripts/validate_pptx.py +69 -0
  48. package/top-ppt-html/scripts/validate_report.py +336 -10
  49. package/top-ppt-html/assets/examples/2026-09-09-architecture-spectrum.html +0 -3926
  50. package/top-ppt-html/assets/examples/2026-09-09-architecture-spectrum.model.json +0 -168
  51. package/top-ppt-html/assets/examples/2026-09-09-presentation-apple-mono.html +0 -4325
  52. package/top-ppt-html/assets/examples/2026-09-09-presentation-apple-mono.model.json +0 -321
  53. package/top-ppt-html/assets/examples/2026-09-09-presentation-brand-red.html +0 -4325
  54. package/top-ppt-html/assets/examples/2026-09-09-presentation-brand-red.model.json +0 -321
  55. package/top-ppt-html/assets/examples/2026-09-09-research-deep-teal.html +0 -5527
  56. package/top-ppt-html/assets/examples/2026-09-09-research-deep-teal.model.json +0 -914
  57. package/top-ppt-html/assets/examples/2026-09-09-research-indigo-violet.html +0 -5527
  58. package/top-ppt-html/assets/examples/2026-09-09-research-indigo-violet.model.json +0 -914
  59. package/top-ppt-html/assets/examples/2026-09-09-research-warm-sand.html +0 -5527
  60. package/top-ppt-html/assets/examples/2026-09-09-research-warm-sand.model.json +0 -914
  61. package/top-ppt-html/references/design-system-engine.md +0 -235
  62. package/top-ppt-html/references/industry-benchmark.md +0 -105
  63. package/top-ppt-html/references/reform-plan.md +0 -252
  64. package/top-ppt-html/scripts/layout_slots.json +0 -830
@@ -0,0 +1,35 @@
1
+ # 页型选型矩阵(L2)
2
+
3
+ > **何时读**:选页型 / 意图→页型映射;常读入口仍是 `playbook.md`。读完即停。
4
+ > 自动选型:`python scripts/recommend_layout.py --mode A --intent "…" --json`
5
+ > 穷举表(内容形态 → 版式 → PPTX 页型)见 `components.md` §46;密度档 `components.md` §46b;组合见 playbook §四。
6
+
7
+ | 我要表达 | 首选页型 | 次选 | 关键约束 |
8
+ |---------|---------|------|---------|
9
+ | 要点式并列主张(默认页) | `points` | `cards` | 每卡宜 3–5 条;更多拆卡/跟进页,勿截断条目 |
10
+ | 现状基线 / 指标快照 | `metrics` | `kpi` | 4–6 个;单数压场用 `kpi` |
11
+ | 单个核心数字压场 | `kpi` | `metrics` | hero 一数一结论 |
12
+ | 多维对标清单 | `table` | `halftable` | ≤8 行(research ≤16) |
13
+ | 时间趋势 / 爬坡 | `bar`(chart.type=line/area/dualline) | `exhibit` | 时间点 >8 改折线 |
14
+ | 构成占比 | `donut`(pie/multidonut/waffle) | `halftable` / **V3 KPI** | 扇区 ≤5,最小扇区 ≥8%;**极偏(min<5% 或 max/min>20)禁 donut→V3** |
15
+ | 排名 / 大小对比 | `bar`(chart.type=hbar/lollipop/pareto) | `table` | 类别 >8 取 Top 7 + 附录 |
16
+ | 现状 vs 目标 | `bullet` / `comparison` | `bar`(vsbar/bulletchart) | 目标线与实际条同量纲 |
17
+ | 两期升降(谁升谁降) | `bar`(slope/dumbbell) | `table` | 两端都要标数值 |
18
+ | 双维分布 / 优先级 | `bar`(scatter/bubble) | `matrix` | 气泡半径 ∝ √值 |
19
+ | 分布 / 离散度 | `boxplot` | `bar`(dotplot) | 组数 ≤8;箱线四件齐备 |
20
+ | 增减归因(A→B) | `bar`(waterfall) | `table` | 每段标变化量 + 合计收口 |
21
+ | 转化 / 筛选漏斗 | `bar`(funnel) | `sankey` | 层数 ≤5 |
22
+ | 计划排期(并行) | `bar`(gantt) | `timeline` | 里程碑叙事用 `timeline`,勿混 |
23
+ | 里程碑 / 路线叙事 | `timeline` | `steps` | 3–5 个,每个 ≤2 行 |
24
+ | 步骤 / 实施节奏 | `steps` | `timeline` | 3–6 步;高亮步 ≤2 处 |
25
+ | 二维强度对标 | `heatmap` | `matrix` | 行列 ≤5×5;只用强调色明度阶梯 |
26
+ | 定位 / 优先级 / 象限 | `matrix` | `bar`(scatter) | ≤3×3 |
27
+ | 层级递进 / 价值阶梯 | `pyramid` | `diagram` | 3–5 层;强调层 ≤1 |
28
+ | 关键判断 / 金句休止 | `quote` | `points` | 全文 1–2 处,多了廉价 |
29
+ | 完整论述(发现→证据→含义) | `twocol`(research R1) | `threecol` | 段 ≤200 字;标题必须结论句 |
30
+ | 数据证据页(主力) | `exhibit`(R2) | `split` | 全篇 Exhibit 连续编号 |
31
+ | 三栏并列论点 | `threecol`(R6) | `cards` | 每栏 ≤150 字 |
32
+ | 系统分层架构 | `diagram` | `bar`(chart.type=network) | 节点 ≤24;层 ≤4 |
33
+ | 流程 / 职责协作 | `lane` | `diagram` | 每行 ≤6 步;正交折线优先 |
34
+ | 素材图片(实拍/截图) | `image` | `split` | 六版式;无图用 `image.placeholder` |
35
+ | 待核实项收口 | `flags` 字段 | `table` | 标色必须配说明 |
@@ -23,8 +23,8 @@
23
23
  | `data-mode` | `presentation` | `research` | `architecture` |
24
24
  | 阅读契约 | 3 秒一屏,听讲 | 30 秒一页,深读 | 一眼看全结构 |
25
25
  | 版心 / 正文 | 1400px / 17–18px | 1240px / 14–15px | 1600px / 图注级 |
26
- | 单页文字 | ≤1500 | ≤3200 | ≤600 |
27
- | 并列单元 | ≤8 | ≤12 | 节点 ≤24 |
26
+ | 单页文字 | ≤1800 预警(密卡/列表可偏密;超限先拆页) | ≤3200 | ≤600 |
27
+ | 并列单元 | ≤8(更多→拆屏/改表,勿删条) | ≤12 | 节点 ≤24 |
28
28
  | 表格行 | ≤8 | ≤16 | 表转图 |
29
29
  | 每页图表 | **按复杂度定面积**(V1–V4;简单图禁全幅) | 1–2 个(取尺寸下限) | 1 张全幅(宽 ≥85% 版心) |
30
30
  | 论证结构 | 主张 → 证据 → 休止 | 发现 → 证据 → 含义 + so-what | 标题 → 图 → 图注 |
@@ -32,8 +32,10 @@
32
32
  | 篇幅 | 8–15 页 | 12–25 页 | 1–3 张图(6–8 页) |
33
33
  | PPTX 正文 | 13pt | 10.5pt | 13pt |
34
34
 
35
- **密度选错的症状**:A 出现双栏小字(投影看不清)→ 拆页;B 出现大面积留白(坐读信息量不足)→ 合页或补证据;C 出现成段正文 → 转图注。
35
+ **密度选错的症状**:A 出现双栏小字墙(投影看不清)→ 拆页/换形态;A 为「疏朗」删证据/so-what → **反模式**,按 content-rules §四-c 恢复;B 大面积留白 → 合页或补证据;C 成段正文 → 转图注。
36
36
  **节奏**:禁止连续 3 页同密度档;同一版式不连用超过 2 页;research 每 3–4 页插一个低密度页(指标带/金句/大数)。
37
+ **反截断**:溢出顺序 = 重构承载 → 拆页/分章 → 换布局 → 有限 fontShrink;禁静默截断(见 `presentation-craft.md`)。
38
+ **插画页**:情绪/产品/占位图 ≠ 数据图;安全边距、图文不叠、icon+chart 共存、Mode A full-bleed+主张叠字规则见 `illustration-layout.md`。
37
39
 
38
40
  ---
39
41
 
@@ -41,51 +43,28 @@
41
43
 
42
44
  **轻量路径**(默认)——同时满足:≤12 页 · 材料单一完整 · 无未敲定关键判断 · 用户没要求看框架。
43
45
  ```
44
- Gate 0 参考图 → 六项问询(1 轮)→ 1 张规划卡 → scaffold_report.py → 填内容+模型 → 校验 → 交付
46
+ Gate 0 参考图 → 六项问询(1 轮)→ 最小大纲(outline-design「轻量最小集」)→ 1 张规划卡 → scaffold_report.py
47
+ → **只填 REPORT_MODEL** → render_from_model.py --inplace → validate_report.py --strict → 交付
45
48
  ```
49
+ (Fast Mode 跳过 Gate 0/六项,仍须最小大纲;其余同链;**禁止**手改 HTML 正文与模型双写。)
46
50
 
47
51
  **完整路径**(任一命中)——研究 ≥20 页 / 演示 ≥12 页 / 材料量大且杂 / 含未敲定关键判断 / 用户要看框架。
48
52
  ```
49
- Gate 0 参考图 → 六项问询(1 轮)→ 证据表 → 故事线脑暴 → SCR+主张树 → 逐页规划卡 → 大纲确认(1 轮)→ 生成 → 校验 → 交付
53
+ Gate 0 参考图 → 六项问询(1 轮)→ 证据表 → 故事线脑暴 → SCR+主张树 → 逐页规划卡 → 大纲确认(1 轮)
54
+ → scaffold_report.py → **只填 REPORT_MODEL** → render_from_model.py --inplace → validate_report.py --strict → 交付
50
55
  ```
51
56
 
52
- **预算(硬)**:交互轮次 ≤3;必读文件 = `SKILL.md` + 本文件(≤2 份);L2 深度文件按需且单份读完即停。
57
+ **预算(硬)**:交互轮次 ≤3;常读面仅入口两份(`SKILL.md` + 本手册)。正式演示 / Fast 演示路径额外允许工艺双件为 L1.5(`default-surface` 与 `presentation-craft`),不记作超读。深度 L2 命中再开、读完即停。
53
58
 
54
59
  ---
55
60
 
56
61
  ## 三、页型选型(意图 → 页型 → 关键约束)
57
62
 
58
- > 穷举表(内容形态 → 版式 → PPTX 页型)见 `components.md` §46;密度档适配见 `components.md` §46b;组合见下节 §四。
59
-
60
- | 我要表达 | 首选页型 | 次选 | 关键约束 |
61
- |---------|---------|------|---------|
62
- | 要点式并列主张(默认页) | `points` | `cards` | 每卡 ≤4 条(research ≤5) |
63
- | 现状基线 / 指标快照 | `metrics` | `kpi` | 4–6 个;单数压场用 `kpi` |
64
- | 单个核心数字压场 | `kpi` | `metrics` | hero 一数一结论 |
65
- | 多维对标清单 | `table` | `halftable` | ≤8 行(research ≤16) |
66
- | 时间趋势 / 爬坡 | `bar`(chart.type=line/area/dualline) | `exhibit` | 时间点 >8 改折线 |
67
- | 构成占比 | `donut`(pie/multidonut/waffle) | `halftable` / **V3 KPI** | 扇区 ≤5,最小扇区 ≥8%;**极偏(min<5% 或 max/min>20)禁 donut→V3** |
68
- | 排名 / 大小对比 | `bar`(chart.type=hbar/lollipop/pareto) | `table` | 类别 >8 取 Top 7 + 附录 |
69
- | 现状 vs 目标 | `bullet` / `comparison` | `bar`(vsbar/bulletchart) | 目标线与实际条同量纲 |
70
- | 两期升降(谁升谁降) | `bar`(slope/dumbbell) | `table` | 两端都要标数值 |
71
- | 双维分布 / 优先级 | `bar`(scatter/bubble) | `matrix` | 气泡半径 ∝ √值 |
72
- | 分布 / 离散度 | `boxplot` | `bar`(dotplot) | 组数 ≤8;箱线四件齐备 |
73
- | 增减归因(A→B) | `bar`(waterfall) | `table` | 每段标变化量 + 合计收口 |
74
- | 转化 / 筛选漏斗 | `bar`(funnel) | `sankey` | 层数 ≤5 |
75
- | 计划排期(并行) | `bar`(gantt) | `timeline` | 里程碑叙事用 `timeline`,勿混 |
76
- | 里程碑 / 路线叙事 | `timeline` | `steps` | 3–5 个,每个 ≤2 行 |
77
- | 步骤 / 实施节奏 | `steps` | `timeline` | 3–6 步;高亮步 ≤2 处 |
78
- | 二维强度对标 | `heatmap` | `matrix` | 行列 ≤5×5;只用强调色明度阶梯 |
79
- | 定位 / 优先级 / 象限 | `matrix` | `bar`(scatter) | ≤3×3 |
80
- | 层级递进 / 价值阶梯 | `pyramid` | `diagram` | 3–5 层;强调层 ≤1 |
81
- | 关键判断 / 金句休止 | `quote` | `points` | 全文 1–2 处,多了廉价 |
82
- | 完整论述(发现→证据→含义) | `twocol`(research R1) | `threecol` | 段 ≤200 字;标题必须结论句 |
83
- | 数据证据页(主力) | `exhibit`(R2) | `split` | 全篇 Exhibit 连续编号 |
84
- | 三栏并列论点 | `threecol`(R6) | `cards` | 每栏 ≤150 字 |
85
- | 系统分层架构 | `diagram` | `bar`(chart.type=network) | 节点 ≤24;层 ≤4 |
86
- | 流程 / 职责协作 | `lane` | `diagram` | 每行 ≤6 步;正交折线优先 |
87
- | 素材图片(实拍/截图) | `image` | `split` | 六版式;无图用 `image.placeholder` |
88
- | 待核实项收口 | `flags` 字段 | `table` | 标色必须配说明 |
63
+ > 自动选型:`python scripts/recommend_layout.py --mode A --intent "路演" --pages 10 --json`(或 `--from-model report.model.json`)→ `{pageType,skel,chart,rationale}`;Mode A 交付 `--strict` 已含 layout-qa。
64
+
65
+ > **穷举意图→页型表** → L2 `page-type-matrix.md`(命中才读)。`components.md` §46 / §46b;组合见 §四。
66
+
67
+ **速记(默认面)**:要点→`points`/`cards` · 指标→`metrics`/`kpi` · 证据图→`exhibit`/`split` · 对标表→`table`/`halftable` · 趋势→`bar`+line/area · 占比→`donut`(极偏→**V3**)· 架构→`diagram`/`lane` · 图文演讲→§三-b V1–V4。
89
68
 
90
69
  ---
91
70
 
@@ -115,7 +94,7 @@ Gate 0 参考图 → 六项问询(1 轮)→ 证据表 → 故事线脑暴
115
94
 
116
95
  ## 四、组合版式矩阵("内容丰富"的落地方式)
117
96
 
118
- > **先选骨架**:P1–P12(`layout-grammar.md`);下表是「主件+从件+注释」内容组合,必须落在某 P__ 上。
97
+ > **先选骨架**:P1–P12(`layout-grammar.md`)。Mode A **主力** P1–P4+P6/P10;**次级** P7–P9/P11–P12(意图命中);画廊/示例外举主力。下表是「主件+从件+注释」组合,必须落在某 P__ 上。
119
98
 
120
99
  > **默认一页 = 主件 + 从件 + 注释层**。单件页(只有一张图/一张表)是**例外**(金句/大数/章节幕),不是默认。
121
100
  > **复杂内容页可扩展组合**:主件 + 双从件、或 `split`/`halftable` 双区并置、或信息图 + 指标带 + so-what + flags——不必强行「一主一从」。先定主件(视觉重心),再从本表挑从件与注释层;表外自由组合须落在已登记页型字段上(否则 PPTX 无法交付)。
@@ -146,45 +125,13 @@ Gate 0 参考图 → 六项问询(1 轮)→ 证据表 → 故事线脑暴
146
125
 
147
126
  ## 五、图表选型决策树(先问"要回答什么",再选图)
148
127
 
149
- > 穷举代码见 `charts.md` §16–§31、§35、§52–§70;误用反例与多样性纪律见 `charts.md` §66。
150
- > **默认生成面(P1 收敛)**:优先 `bar / hbar / line / donut / progress / area / stack / dualline`。
151
- > **高级图型**(waterfall/gantt/funnel/slope/… 与 6 类信息图)按需选用,不进默认轮换。
152
- > **纪律**:全篇不同 `data-chart` 类型 ≥ `min(模式上限, ⌈图表页数 × 0.6⌉)`(上限:research 6 / presentation 4 / architecture 3);**相邻图表页不得同型**。
153
-
154
- | 分析意图(读者要得出的结论) | 首选 | 次选 | 禁用 / 改判条件 |
155
- |---------------------------|------|------|----------------|
156
- | 谁大谁小 | `hbar` | `lollipop` / `bar` | 类别 >8 → Top7 + 附录 |
157
- | 随时间怎么变 | `line` | `area` / `dualline` | 时间点 >8 不标点值 |
158
- | 占比是多少 | `donut` | `pie` / `multidonut` | 扇区 >5 → 合并"其他"或 `treemap` |
159
- | 每 1% 的直觉 | `waffle` | `donut` | 类别 >3 改 `marimekko` |
160
- | 结构在变形 | `streamgraph` | `stackline` | 系列 >6 合并 |
161
- | 总量 × 构成双编码 | `marimekko` | `treemap` | 列 >6 / 段 >4 → 拆 |
162
- | 份额悬殊(头部集中) | `treemap` | `donut` | 叶 >16 → 合并小项 |
163
- | 从 A 到 B 是谁贡献的 | `waterfall` | `pareto` | 段 >6 → 合并 |
164
- | 主要矛盾是哪几个 | `pareto` | `waterfall` | 类别 >7 → 合并 |
165
- | 转化/流失在哪一环 | `funnel` | `sankey` | 层 >5 → 改 `hbar` |
166
- | 多对多的流向 | `sankey` | `network` | 节点 >12 / 流带 >24 → 拆页 |
167
- | 谁和谁相连 | `network` | `diagram` | 节点 >18 / 边 >30 → 拆页 |
168
- | 两期谁升谁降 | `slope` | `dumbbell` | 系列 >6 → 取 Top 6 |
169
- | 单指标前后对比(多对象) | `dumbbell` | `vsbar` | 行 >6 → 拆页 |
170
- | 实际 vs 目标(含区间) | `bulletchart` | `bullet` | 行 >6 → 拆页 |
171
- | 达成率(多指标同心) | `radialbar` | `gauge` | 环 >5 → 改 `bullet` |
172
- | 一个值够不够 | `gauge` | `radialbar` | 单值叙事,勿与图并存 |
173
- | 分布不是均值 | `boxplot` | `dotplot` | 组 >8 → 拆页 |
174
- | 双维定位 + 第三维权重 | `bubble` | `scatter` | 气泡 >8 → 标注关键项 |
175
- | 六维能力画像 | `radar` | `rose` | 维度 >6 → 拆两组 |
176
- | 区间波动(开高低收) | `candlestick` | `line` | 蜡烛 >12 → 聚合 |
177
- | 多项目完成度 | `progress` | `bullet` | 行 >6 → 拆页 |
178
- | 迷你趋势(卡内) | `sparkline` | — | 只用于指标卡,不与大图并存 |
179
-
180
- **七种最常见的误用(出现即改判)**:
181
- 1. 用 `bar` 表达占比 → 改 `donut`/`stackline`/`waffle`。
182
- 2. 用 `donut` 表达 8 个类别 → 合并或改 `treemap`。
183
- 3. 用 `line` 表达类别对比(无时间轴)→ 改 `hbar`。
184
- 4. 用 `table` 表达趋势 → 改 `line`/`area`。
185
- 5. 用均值型图表表达分布 → 改 `boxplot`/`dotplot`。
186
- 6. 同一页放两张同型图 → 改 `split`/`halftable` 并让两图**编码不同维度**。
187
- 7. 多系列图用单色明度阶梯(分不清) → 用 `f-c1~c5` 编码色板(见 §八)。
128
+ > **默认面(8 核心图)**:`bar` · `hbar` · `line` · `donut` · `progress` · `area` · `stack` · `dualline`
129
+ > (= `layoutSystem.defaultCharts`)。完整登记与代码 → `extract_snippet.py --chart <类型>`;误用纪律 → `charts.md`(先 `charts-discipline`,核图 8,extended 按需)。
130
+ > **扩展决策表 + 七种误用** → L2 `chart-decision-tree.md`(命中才读)。**生成默认只从 8 核心里选**,扩展图仅意图明确命中。
131
+
132
+ **多样性(硬摘要 · 保留)**:全篇不同 `data-chart` ≥ `min(模式上限, ⌈图表页数 × 0.6⌉)`(上限 research 6 / presentation **4** / architecture 3);**相邻图表页不得同型**。**preferCoreFirst**:先拉开核图 8;advanced 计入 `minTypes`(不罚)但禁预读 `charts-extended.md`;**禁**为凑下限硬上冷门图、简单图全幅、极偏 donut/pie。
133
+
134
+ **速记**:谁大谁小→`hbar` · 时间→`line`/`area` · 占比→`donut`(扇区>5/极偏改判)· 归因→`waterfall` · 转化→`funnel` · 流向→`sankey`。
188
135
 
189
136
  ---
190
137
 
@@ -231,36 +178,45 @@ Gate 0 参考图 → 六项问询(1 轮)→ 证据表 → 故事线脑暴
231
178
  python scripts/scaffold_report.py --mode research --style mckinsey --theme light \
232
179
  --title "报告标题" --sections 8 --out 2026-09-15-主题.html # 起点(不要手抄模板)
233
180
  # 或用黄金节奏包:--preset consulting|diagnostic|pitch|ops-review|layered-arch|flow-arch
234
- python scripts/validate_report.py 2026-09-15-主题.html --strict # HTML 硬门禁(0 FAIL / 0 WARN)
181
+ # 只填 window.REPORT_MODEL(禁止手改 HTML 正文),然后回填:
182
+ python scripts/render_from_model.py 2026-09-15-主题.html --inplace
183
+ python scripts/validate_report.py 2026-09-15-主题.html --strict # presentation 自动 --layout-qa;B/C 可显式加
184
+ # 可选:python scripts/recommend_layout.py --from-model 报告.model.json
235
185
  python scripts/extract_model.py 2026-09-15-主题.html # → .model.json
236
186
  node scripts/build_pptx.js 2026-09-15-主题.pptx --model=….model.json
237
187
  python scripts/validate_pptx.py 2026-09-15-主题.pptx --strict --model=….model.json # 0/0
238
188
  ```
239
189
 
240
- **交付前必过**:`validate_report.py --strict` 0/0;含 PPTX 时 `validate_pptx.py --strict --model=` 0/0(`pictures` 数 = 声明数)。
241
- **推荐一键门禁**:`python scripts/quality_gate.py 报告.html [--pptx x.pptx --model x.model.json]`(strict + evals + rubric 启发式五维;交付时加 `--deliver` 开关自动产出七要素说明,不要手拼)。
190
+ **交付前必过**:`validate_report.py --strict` 0/0(**Mode A / presentation 隐含 `--layout-qa`**;research/architecture 不强制);含 PPTX 时 `validate_pptx.py --strict --model=` 0/0。
191
+ **推荐一键门禁**:`python scripts/quality_gate.py 报告.html [--pptx x.pptx --model x.model.json]`(presentation 同口径附带 layout-qa;交付加 `--deliver` 出七要素,不要手拼)。
192
+ **A/B 全文对等**:`cross_verify.py` 默认 SKIP,仅 `python scripts/cross_verify.py --full-ab` 或 `regression.py --full-ab` 时启用。
193
+ **PPTX 冒烟**:`bash scripts/smoke_pptx.sh`(extract_model → build_pptx → validate_pptx --strict)。
242
194
  **失败自修复**:按输出逐条修 → 重跑,直到 0/0;修复顺序见 `failure-modes.md`。
243
195
 
244
196
  ---
245
197
 
246
198
  ## 十、L2 节级路由(按任务只读这些,读完即停)
247
199
 
248
- > **不要整读** `components.md` / `charts.md` 背后的物理拆分大文件。需要代码时优先:
249
- > `python scripts/extract_snippet.py --list` · `--task <名>` · `--chart <类型>` · `--page-type <页型>` · `--file components.md --section 46`(逻辑名自动路由)
200
+ > 常读仍为入口两份;演示路径可加 **L1.5 工艺双件**:`default-surface.md` + `presentation-craft.md`。
201
+ > 默认生成面:`default-surface.md`(12 页型 + 8 图 + V1–V4)。Mode A 工艺:`presentation-craft.md`。插画:`illustration-layout.md`。
202
+ >
203
+ > **禁止整读(强制走 `extract_snippet.py`)**:`layouts-combo.md` · `components-atoms.md` · `charts-basic.md` · `charts-extended.md` · `content-rules.md` 全文 · `pptx-export.md` · 模式模板 HTML(`assets/templates/*.html`,走 `scaffold_report.py`)。
204
+ > 取码:`python scripts/extract_snippet.py --list` · `--task <名>` · `--chart <类型>` · `--page-type <页型>` · `--file components.md --section 46`(逻辑名自动路由)
250
205
 
251
206
  | 任务 | 只读 |
252
207
  |------|------|
253
- | research 证据页 / Exhibit / 密表 | `components.md` §36d/§46/§46c · 本文件 §三/§四 · `extract_snippet.py --task research-evidence` |
208
+ | research 证据页 / Exhibit / 密表 | `components.md` §36d/§46/§46c · 本文件 §三/§四 · `page-type-matrix.md` · `extract_snippet.py --task research-evidence` |
209
+ | 正式演示 / Mode A 工艺 | `default-surface.md` · `presentation-craft.md` · 本文件 §三-b/§五 · `page-type-matrix.md` |
254
210
  | 演示组合版式 | `components.md` §39–§42/§46/§46b/§46c · `--task presentation-combo` |
255
211
  | 架构 / 泳道 / 分层 | `components.md` §37–§38b · `infographics.md` §78–§80 · `--task architecture-diagram` |
256
- | 选图 / 取图表代码 | 本文件 §五 · `--chart <类型>` · 误用见 `charts.md` §66 |
212
+ | 选图 / 取图表代码 | 本文件 §五 · `chart-decision-tree.md` · `--chart <类型>` · 误用见 `charts.md` §66 |
257
213
  | 密度 / 字数 / 去 AI 味 | `content-rules.md` §一/§四 · 本文件 §六 · `--task content-rules` |
258
- | 素材图片 / 占位 | `components.md` §11c · `--task image-layout` |
214
+ | 素材图片 / 占位 / 插画页 | `illustration-layout.md` · `components.md` §11c · `--task image-layout` |
259
215
  | PPTX 精导字段 | `pptx-export.md` · 本文件 §九 · `--task pptx-export` |
260
216
  | 高保真 / 锚点 | `high-fidelity.md` · `--task high-fidelity` |
261
217
  | 配色 / 风格 | `styles.md` · `design-system.md` §1a–§1b/§9 · `--task style-theme` |
262
218
  | 图标 / 语义速查 | `icons.md` · `--task icons` |
263
219
  | 起骨架用节奏包 | `scaffold_report.py --list-types` → `--preset consulting` 等 |
264
220
 
265
- **纪律**:L0+L1 是默认全部所需;上表命中才开 L2;**读完即执行,不预读下一份**。页型语义槽位见 `scripts/layout_slots.json`(双通道同源 IR)。
221
+ **纪律**:L0+L1 是默认全部所需(Mode A/Fast 可加 L1.5);上表命中才开 L2;**读完即执行,不预读下一份**;大文件**禁止整读**,一律 `extract_snippet.py`。页型语义槽位见 `layout-constants.json` → `layoutSlots`(双通道同源 IR)。
266
222
  **维护者**:改常量/schema/引擎后必跑 `sync_runtime.py` → `audit_styles.py` → `audit_docs.py` → `audit_skill.py` → `build_examples.py` → `regression.py`。
@@ -24,7 +24,20 @@
24
24
  - **智能体精导**:正式 PPTX 的唯一交付路径——从报告抽模型 → 生成 → **过 strict 质检** → 交付。生成时用户选了「HTML+PPTX」交付格式的,交付时一并生成;交付后用户随时可通过页面提示词回来补生成。
25
25
  - **双单源**:页面几何/三模式独立比例尺(`typeScale` 基准 + `modeTypeScale` 模式取值)/页型几何/9 风格 token 全在 `scripts/layout-constants.json`;**页型 DSL schema(字段/必填/适用模式)在 `scripts/model-schema.json`**。通道 B 直接 `require`;页面运行时由 `sync_runtime.py` 注入(同时注入三模板的引擎/UI/运行时内联副本)。**改常量只改 JSON,改 schema 只改 schema JSON,然后跑 `python scripts/sync_runtime.py`**。
26
26
 
27
- ## 内容模型(生成报告时与正文同步填写)
27
+ ### 会场与字号(venue · P1-4)
28
+
29
+ PPTX `modeTypeScale` 以**中型会议室投影**为默认(presentation 正文 13pt)。按会场微调,**不要**用无限缩字号塞字:
30
+
31
+ | 会场 | 建议 | 做法 |
32
+ |------|------|------|
33
+ | 小会议室 / 桌面投屏 | 默认可略紧 | 保持 mode 比例尺;密卡页走拆页而非降到 floor 下 |
34
+ | 中型会议室(默认) | presentation body 13pt / research 10.5pt | `modeTypeScale` 原值 |
35
+ | 礼堂 / 大报告厅 | 提高可读性 | 演示稿优先更大标题档与更少每页单元;必要时整体上移一档角色映射,**仍禁**为塞字破 fontShrink floor |
36
+
37
+ HTML 侧仍用 MD3 clamp;双端都以「最后一排可读」为准(`presentation-craft` back-of-room)。
38
+
39
+
40
+ ## 内容模型(只填模型 · render_from_model 回填正文)
28
41
 
29
42
  三份模式模板(`assets/templates/{presentation|research|architecture}.html`)尾部已带对应模式的占位。字段:
30
43
 
@@ -122,7 +135,7 @@
122
135
 
123
136
  ## 页面预览(已内置三模板)
124
137
 
125
- 三份模式模板均已集成:header 工具组「预览 PPTX」(快捷键 P)+「?」PPT 生成指引弹窗(快捷键 H,精导通道说明 + 可复制提示词)+ 内嵌预览运行时 + 对应模式模型占位。**生成报告时只需做一件事:把 `window.REPORT_MODEL` 填成与正文一致的内容(mode 用模板默认值,勿改)。**
138
+ 三份模式模板均已集成:header 工具组「预览 PPTX」(快捷键 P)+「?」PPT 生成指引弹窗(快捷键 H,精导通道说明 + 可复制提示词)+ 内嵌预览运行时 + 对应模式模型占位。**生成报告时只填 `window.REPORT_MODEL`,再跑 `render_from_model.py --inplace` 回填正文(mode 用模板默认值,勿改;禁止双写)。**
126
139
 
127
140
  - 预览模态读取 `slidesXml`(与精导同一序列化输出)渲染 16:9 页序列——所见即所得
128
141
  - 打开即自检(schema 单源驱动):模型完整 → 正常预览 + 提示词;不完整 → 尽力渲染 + 缺失清单 + 提示词
@@ -207,3 +220,8 @@ python scripts/validate_pptx.py "报告.pptx" --strict --model="报告.model.jso
207
220
  - **Node + pptxgenjs**:仅精导通道与回归双裁判需要。在技能目录执行 `npm install pptxgenjs`,或把 `NODE_PATH` 指向任意已含 pptxgenjs 的 node_modules;`regression.py` 会自动探测(`TOP_PPT_NODE_PATH` / `NODE_PATH` / 仓库内 node_modules / 全局 npm root)。
208
221
  - **Python(标准库)**:跑 `validate_report.py` / `validate_pptx.py` / `extract_model.py`(读 `model-schema.json` 单源)/ `sync_runtime.py` / `audit_styles.py`,无第三方依赖;`cross_verify.py` 可选依赖 python-pptx(未装则自动跳过该第三方裁判,不影响交付判定)。
209
222
  - 页面预览运行时零依赖(浏览器纯序列化,无 ZIP 打包)。
223
+
224
+ ### Chrome 一致性(P1-6)
225
+
226
+ 跨页页眉/页脚/页码(chrome)应**锁死同一几何**:同 y、同字号角色、同边距(`layoutSystem.zones.chromePct`)。禁止逐页漂移页码位置或交替有无页脚。HTML 用模板页脚;PPTX 由 `pageTypes` chrome 槽位同源落位。便宜门禁:`validate_pptx` 对页脚/页码 y 漂移做 WARN(见 `qualityGates.chromeDriftIn`)。
227
+
@@ -0,0 +1,77 @@
1
+ # 演示工艺清单 · Presentation Craft(L2 · Mode A)
2
+
3
+ > **何时读**:Mode A / 正式演示 / 路演 / 演讲 / Fast 演示路径。与 `default-surface.md` 同级常读。
4
+ > **何时不读**:Mode B 密排、Mode C 架构深读(能力保留,不反向污染 A)。
5
+ > **定位**:大气、演讲友好;一屏一主张;图标/图表克制配文——非 gadget deck、非咨询 dump。
6
+
7
+ ## 铁律速查(Hard rules)
8
+
9
+ | 中文原则 | English | 可执行 |
10
+ |----------|---------|--------|
11
+ | 一屏一主张 | one idea per slide | 标题即结论;第二主张拆页 |
12
+ | 三秒可读 | 3-second / glance rule | 主信息 3 秒可抓;广告牌不是文档 |
13
+ | 留白即设计 | whitespace as design | 合法空:封面/章节幕/金句/收尾;内容页半空 = underfill |
14
+ | 最后一排 | back of the room | 投影正文宜大;少字号档(display/h1 · body · caption) |
15
+ | CRAP | Contrast / Repetition / Alignment / Proximity | 强焦点;跨页 chrome 锁死;左缘顶边齐;相关成组 |
16
+ | 行动标题 | action / claim title | 主张句,非「现状分析」式话题标签 |
17
+ | 少色单强调 | single accent | 2–3 主色 + 灰阶;1 accent;红仅警示 |
18
+ | 图表克制 | restrain / reduce / emphasize | 8 核图优先;简单图禁全幅;极偏禁 donut→V3 |
19
+ | 图标语义 | icons as meaning | 约 3–8/屏;固定 px 档;禁表内/图内乱插 |
20
+ | **默认无动画** | **motion = none** | 禁炫技转场/飞入作默认;HTML 翻页即可 |
21
+ | 无障碍对比 | WCAG AA | 正文 ≥4.5:1;大字/图形 ≥3:1;不靠颜色单独编码 |
22
+ | 舞台纪律 | 16:9 stage | 安全边距;一屏一重心;同页双大件 FAIL |
23
+
24
+ ## 默认面(与 default-surface 对齐)
25
+
26
+ - **页型**:12 默认页型;**主力骨架 P1–P4 + P6/P10**(≈V1–V4)覆盖约 80% 页。
27
+ - **次级骨架 P7–P9 / P11–P12**:合法保留;A 下仅密表/全幅结构/一主两从等意图命中再用,**不进默认轮换**。P5 为常用扩展。
28
+ - **核图 8**:`bar` · `hbar` · `line` · `donut` · `progress` · `area` · `stack` · `dualline`。默认读面 = 纪律 + 核图;**不预读** `charts-extended.md`。
29
+ - **多样性**:先拉开核图;advanced **计入** `minTypes`(不罚)但**只按内容需要**选用,绝不为凑下限垫冷门图。
30
+
31
+ ## 交付门禁(Mode A)
32
+
33
+ ```
34
+ validate_report.py --strict # presentation 自动隐含 --layout-qa
35
+ quality_gate.py … --deliver # 同口径
36
+ ```
37
+
38
+ 检查:V 契约 · 简单全幅 · 骨架连用 · 截断/溢出未拆页 · 半空卡 · 对齐节奏 · 主张标题 WARN · 核图多样性 · WCAG。
39
+
40
+ ## 自检(上台前 30 秒)
41
+
42
+ - [ ] 标题是主张句,不是话题词
43
+ - [ ] 眯眼可见:一条左线、一条顶线、一块重心
44
+ - [ ] 休止页有意留白;内容页不无故半空
45
+ - [ ] 无多强调色、无动画墙、无冷门图硬凑
46
+ - [ ] `motion = none`;翻页靠内容节奏
47
+
48
+
49
+ ## 插画页(非数据配图)
50
+
51
+ - 情绪/产品/占位图与数据图**勿同页抢主位**;规则见 `illustration-layout.md`。
52
+ - **安全边距** ≥24px;文字不压照片焦点;标签/图例不重叠。
53
+ - **icon + chart**:icon 在注释列,不进绘图区。
54
+ - **full-bleed + 主张叠字**(Mode A):仅封面/章节幕/金句/收尾;遮罩保对比度;必有 caption/来源;证据另页。
55
+ - 配图页写 **caption + so-what**(氛围休止页可免 so-what);校验对缺项 WARN。
56
+
57
+ ## 长文与信息承载(anti-truncation)
58
+
59
+ > **硬原则**:大量文字**不得**为了「看起来像稀疏 demo 甲板」而被故意压缩或删除。留白是设计;**删掉证据 / so-what / 口径不是设计**。
60
+
61
+ **Mode A 仍主张一屏一主张**——但「一主张」可以带充分证据:次要卡、列表、表、跟进页。内容密时优先**加结构**,不砍实质。
62
+
63
+ ### 溢出处置顺序(铁律 · 与 `containers.overflowRule` 同源)
64
+
65
+ 1. **重构承载**:段落 → 列表 / 卡片 / 表 / 图 / 组合版式
66
+ 2. **拆页 / 分章**:议程→主张→证据卡→明细列表等多页序列;01a/01b;多部分章节
67
+ 3. **换布局形态**:V1–V4 · 多列 · 卡栅格 · `g-side` / `g-bento`
68
+ 4. **有限 `fontShrink`**(阶梯内、模式 floor 以上,最多 4 档)
69
+ 5. **禁止**静默截断、砍 so-what、砍证据、为审美稀疏而删决策必需信息
70
+
71
+ ### 密度许可
72
+
73
+ - 卡片/列表页在主张清楚时可**偏密**(多卡、多条),仍须可读、对齐、一重心。
74
+ - 单页字数预算是**溢出预警**,不是「字数太多就删」的许可证;超预算先走 1–3 步。
75
+ - 校验:`overflow-without-split` / 截断迹象 → FAIL 或 WARN;**不为「字多」单独 FAIL**。
76
+
77
+ > *Hard rules protect the stage; adaptive choices serve the content.*
@@ -30,7 +30,7 @@
30
30
  |------|------|--------|
31
31
  | `scripts/layout-constants.json` | 页面几何 `page` / **12 列网格 `grid`** / **语义字阶 `typography` C0–T14** / 三模式比例尺 `typeScale`+`modeTypeScale` / 页型几何 `pageTypes`+`pageTypeGeometry` / **9 风格 token `styles`+`stylesDark`+`styleAccents`** / **编码色板 `styleDataColors`+`styleDataColorsDark`(9 套 × 亮暗 × c1–c5)** / **图表登记四元组 `charts.registry`** / 图表最小尺寸 `charts.minSize` / **图表多样性预算 `charts.variety`** / **容器内边距 `containers`** / **锚点容差 `anchorTolerance`** / **图片准入门 `imageAdmission`** / **图片规格 `imageSpec`**(版式 `layouts` / 比例 `ratioDefault`+`ratioCssClass` / 建议尺寸 / 占位标签 / 体积上限) / **深度模式 `deepMode`** / 校验预算 `checkBudgets` / 强调带 `emphasis` / 待核实 `annotations` / 去AI味词 `aiFlavor` / **内容级质量 `contentQuality`**(版式节奏 / so-what 实质 / research 标题判断) | `build_pptx.js`(require)、`pptx-export.js`(注入常量块)、三模板、`style-gallery.html`、`validate_report.py`、`validate_pptx.py`、`audit_styles.py`、`audit_skill.py`、`prepare_images.py`、`evals/run_evals.py` |
32
32
  | `scripts/model-schema.json` | 29 种页型的字段与必填约束 / **图表类型白名单 `chartTypes`(30 类:16 原生 + 14 形状)** / **数据表策略 `chartDataTable`** / 通用可选字段 `commonSectionFields` | `extract_model.py`(本地校验)、`pptx-export.js`(浏览器端 `validateModel`) |
33
- | `scripts/layout_slots.json` | **页型布局 IR(29 页型全量)**:语义槽位(head/primary/secondary/annotation + required)——双通道按同一槽位语义落位 | `sync_runtime.py`(完整性校验);`lib_layout_regions.js`(槽位→英寸矩形);`extract_snippet.py --page-type` |
33
+ | `layout-constants.json` → `layoutSlots` | **页型布局 IR(29 页型全量)**:语义槽位(head/primary/secondary/annotation + required)——双通道按同一槽位语义落位 | `sync_runtime.py`(完整性校验);`lib_layout_regions.js`(槽位→英寸矩形);`extract_snippet.py --page-type` |
34
34
  | 交付一键 | `quality_gate.py` | `validate_report --strict` + 可选 `validate_pptx` + `evals --score` + **rubric 启发式五维**(content/layout/chart/infographic/tone) |
35
35
 
36
36
  **纪律**:改常量只改 JSON,改 schema 只改 schema JSON,然后跑 `python scripts/sync_runtime.py`(注入 + 完整性校验 + 哈希摘要)。**禁止手改** `pptx-export.js` / 三模板 / `style-gallery.html` 的标记块。
@@ -43,7 +43,7 @@
43
43
  5. **页型实现可达性(冒烟)**:schema 每个页型都应出现在 `build_pptx.js` 与 `pptx-export.js` 源码中(子串级,拦「schema 加了页型、引擎没实现」)
44
44
  6. **骨架尺寸单源不变量**:`charts.scaffold`(scaffold_report.py 骨架尺寸唯一事实源)键 ⊆ registry,且默认值 ≥ `charts.minSize` 同口径阈值——拦「脚本硬编码第二源漂移」
45
45
  7. **语义字阶**:每个 level 的 `role` 在 `modeTypeScale` 中存在
46
- 8. **页型布局 IR**:`layout_slots.json` 每个页型在 schema 中存在,且含 head + primary 槽位
46
+ 8. **页型布局 IR**:`layoutSlots(LC)` 每个页型在 schema 中存在,且含 head + primary 槽位
47
47
 
48
48
  > **图表计数的两种口径**(同一事实的两种切法,勿混用):`registry` 视角 **36 = 16 原生 + 20 形状**(SKILL.md 铁律 9 用此口径);`chartTypes` 视角 **30 = 16 原生 + 14 形状**(可作 `chart.type` 的形状类,`pptx-export.md` 页型表用此口径)——差额 6 类是信息图专属页型(sankey/treemap/boxplot/network/marimekko/streamgraph),它们只作 `sections[].type`,不作 `chart.type`。
49
49
 
@@ -110,7 +110,7 @@
110
110
 
111
111
  - **发布版**:**v0.1**(布局语法 + 模型单写 + 硬门禁 + 风格语汇层)。**版本唯一事实源 = `layout-constants.json` `version`**;`model-schema.json` / `layoutSlots` 同步该值、技能 `package.json` 为 `0.1.x`;`sync_runtime.py` 校验一致。变更流水见仓库根 `CHANGELOG.md`。
112
112
  - **兼容回落**:排版比例尺只有 `modeTypeScale` 一套;未知模式回落 `presentation` 档。环境变量 `TOP_PPT_NODE_EXE` / `TOP_PPT_NODE_PATH`(旧名已移除)。
113
- - **文档分工**:本文件管架构与机制;日常规范见 `references/*`,业界对标依据见 `industry-benchmark.md`。
113
+ - **文档分工**:本文件管架构与机制;日常规范见 `references/*`,业界对标依据见 `docs/archive/refs/industry-benchmark.md`。
114
114
 
115
115
  ## 八、目录职责
116
116
 
@@ -121,7 +121,7 @@
121
121
  | `references/modes.md` | 三模式密度契约与锁定版式(L2:定模式细节时读) |
122
122
  | `references/outline-design.md` | 内容架构七步法 + 跨页叙事节奏 + 细节保全 |
123
123
  | `references/design-system.md` | MD3 对齐、设计原理(CRAP/7:2:1/字体矩阵)、页高模型、12 列网格、语义字阶、SVG 语义类(生成时主读) |
124
- | `references/design-system-engine.md` | 顶栏/卡片/列表/表格/页脚/动效等 CSS 类实现目录(维护者;生成时勿读) |
124
+ | `docs/archive/refs/design-system-engine.md` | 顶栏/卡片/列表/表格/页脚/动效等 CSS 类实现目录(维护者;生成时勿读) |
125
125
  | `references/styles.md` | 9 套风格定义与选型 |
126
126
  | `references/content-rules.md` | 页内写作规则、密度三档、表格语义字号、容器内边距、连续文本流 |
127
127
  | `references/components.md` | 结构组件与锁定版式(`components.md` §1–§15c、§32–§50)+ 版式选型表 + **组合版式矩阵(§46c)** |
@@ -131,8 +131,14 @@
131
131
  | `references/pptx-export.md` | PPTX 导出通道、模型字段、双单源、29 页型、图表双通道 |
132
132
  | `references/high-fidelity.md` | 按需深度模式规范(触发、容差、manifest、渲染对照) |
133
133
  | `references/failure-modes.md` | 十四类失败模式 + 修复顺序铁律 + 错误解释纠正表 |
134
- | `references/industry-benchmark.md` | 业界对标与采纳/不采纳决策依据 |
134
+ | `docs/archive/refs/industry-benchmark.md` | 业界对标与采纳/不采纳决策依据 |
135
135
  | `scripts/*` | 校验器、**骨架生成器 `scaffold_report.py`**、注入器、回归、**三项审计(styles / docs / skill)**、打包(全部标准库;PPTX 精导需 Node + pptxgenjs) |
136
136
  | `evals/*` | Eval 框架:`prompts.csv`(14 条,含负对照)+ `rubric.schema.json`(风格目标评分契约)+ `run_evals.py`(结果/过程/风格/效率四类目标) |
137
137
  | `assets/templates/*` | 三模式模板 + 公共引擎/UI(标记块由 `sync_runtime.py` 注入) |
138
138
  | `assets/examples/*` | 示例矩阵(含信息图页型与原生图表技巧) |
139
+
140
+ ## 附:第三方校验与实验 frontmatter
141
+
142
+ - **主门禁**:`audit_skill.py` / `package_skill.py --check`(体积、披露、Gate0、触发覆盖)。
143
+ - **可选**:`npx --yes skills-ref@0.1.5 validate .`(Agent Skills 开放标准;本技能已通过)。**不**作为 CI 硬依赖。
144
+ - **不启用**:Claude-only `when_to_use`(会破坏严格 allowlist);跨端 `allowed-tools`(宿主语法分叉)——需要时由宿主侧实验,不进本仓库 frontmatter。
@@ -139,7 +139,7 @@ def main() -> int:
139
139
  # ⑤ 篇数与必需文件
140
140
  n_ref = len(list(REF.glob('*.md')))
141
141
  sk = (ROOT / 'SKILL.md').read_text(encoding='utf-8')
142
- d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M | re.S)
142
+ d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M)
143
143
  dlen = len(d.group(1)) if d else -1
144
144
  nm = re.search(r'^name:\s*(\S+)\s*$', sk, re.M)
145
145
  missing = [r for r in REQUIRED if not (ROOT / r).exists()]
@@ -13,9 +13,9 @@
13
13
 
14
14
  审计项(任一不过 → 退出码 1):
15
15
  ① 体积预算 —— SKILL.md / 常读入口 playbook.md / 单份 reference / 模式模板 的上限
16
- ② 元数据 —— frontmatter name 与技能名一致;description ≤ DESC_HARD,且 ≤ DESC_SOFT(触发精度)
16
+ ② 元数据 —— frontmatter name 与技能名一致;description ≤ DESC_HARD/SOFT;可选 license/compatibility/metadata(开放标准)
17
17
  ③ 披露分层 —— SKILL.md 必须声明 L0/L1/L2 三档,且 L1(常读入口)恰好 1 份
18
- ④ 交互门禁 —— SKILL.md 必须含「Gate 0 参考图先行」,且其出现位置在「六项问询」之前
18
+ ④ 交互门禁 —— SKILL.md 必须含「Gate 0 参考图先行」,且其出现位置在「六项问询」之前;若声明 Fast Mode,须同时有豁免句且标准路径仍为硬门禁
19
19
  ⑤ 效率预算 —— SKILL.md 必须显式声明交互轮次上限与必读文件数上限
20
20
  ⑥ 引用完整性 —— SKILL.md 与 playbook.md 提到的 references/*.md 必须存在
21
21
  ⑦ 冗余报告 —— SKILL.md ↔ 全部 references(含 playbook)的归一化共同片段
@@ -139,7 +139,7 @@ def main() -> int:
139
139
  f'最大 {kb(max((p.stat().st_size for p in TPL.glob("*.html")), default=0))} / 上限 {kb(BUDGET["template"])}')
140
140
 
141
141
  # ② 元数据
142
- d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M | re.S)
142
+ d = re.search(r'^description:\s*"(.*)"\s*$', sk, re.M)
143
143
  dlen = len(d.group(1)) if d else -1
144
144
  nm = re.search(r'^name:\s*(\S+)\s*$', sk, re.M)
145
145
  chk('② name 一致', bool(nm) and nm.group(1) == NAME,
@@ -149,9 +149,37 @@ def main() -> int:
149
149
  chk('② description 软上限(触发精度)', 0 < dlen <= BUDGET['desc_soft'],
150
150
  f'{dlen} / 建议 ≤ {BUDGET["desc_soft"]}')
151
151
 
152
+ # ②b 开放标准可选 frontmatter(允许额外键;校验存在与粗约束)
153
+ lic = re.search(r'^license:\s*(.+)$', sk, re.M)
154
+ chk('② license', bool(lic) and 'MIT' in (lic.group(1) if lic else ''),
155
+ '缺 license: MIT(开放标准可选,本技能应对齐 package.json)',
156
+ 'license=MIT')
157
+ compat = re.search(r'^compatibility:\s*"(.*)"\s*$', sk, re.M | re.S)
158
+ clen = len(compat.group(1)) if compat else -1
159
+ chk('② compatibility', 0 < clen <= 500,
160
+ f'compatibility 缺失或超 500 字符({clen})',
161
+ f'{clen} 字符')
162
+ meta_ver = re.search(r'^\s+version:\s*"?([\w.\-]+)"?\s*$', sk, re.M)
163
+ meta_author = re.search(r'^\s+author:\s*(\S+)\s*$', sk, re.M)
164
+ pkg_ver = ''
165
+ try:
166
+ import json as _json
167
+ pkg_ver = str(_json.loads((ROOT / 'package.json').read_text(encoding='utf-8')).get('version') or '')
168
+ except Exception:
169
+ pass
170
+ chk('② metadata.version', bool(meta_ver) and (not pkg_ver or meta_ver.group(1) == pkg_ver),
171
+ f'metadata.version 缺失或与 package.json 不一致(fm={meta_ver.group(1) if meta_ver else None} pkg={pkg_ver})',
172
+ f'{meta_ver.group(1) if meta_ver else "?"}')
173
+ chk('② metadata.author', bool(meta_author),
174
+ '缺 metadata.author',
175
+ meta_author.group(1) if meta_author else '')
176
+
152
177
  # ③ 渐进式披露分层(机器可读标记:L0=… · L1=… · L2=…)
153
- m_l1 = re.search(r'L1\s*=\s*`?([^`\s·|]+)`?', sk)
154
- has_l0 = bool(re.search(r'L0\s*=', sk))
178
+ # Prefer machine-readable disclosure marker `L1=references/...`(忽略正文「L0+L1 共 2」等)
179
+ m_l1 = re.search(r'L1\s*=\s*`?(references/[a-z0-9\-./]+\.md)`?', sk)
180
+ if not m_l1:
181
+ m_l1 = re.search(r'L1\s*=\s*`?([^`\s·|]+)`?', sk)
182
+ has_l0 = bool(re.search(r'L0\s*=\s*`?SKILL', sk)) or bool(re.search(r'`L0=SKILL', sk))
155
183
  has_l2 = bool(re.search(r'L2\s*=', sk))
156
184
  l1_files = [f.strip() for f in re.split(r'[,、]', m_l1.group(1)) if f.strip()] if m_l1 else []
157
185
  chk('③ 披露分层 L0/L1/L2', has_l0 and has_l2 and len(l1_files) == BUDGET['l1_files'],
@@ -159,12 +187,23 @@ def main() -> int:
159
187
  chk('③ 常读入口存在', bool(l1_files) and all((ROOT / f).exists() for f in l1_files),
160
188
  f'L1={l1_files} 不存在', f'{l1_files} 存在')
161
189
 
162
- # ④ Gate 0(参考图先行)
190
+ # ④ Gate 0(参考图先行)——标准路径硬门禁;Fast Mode 可声明豁免
163
191
  g0 = sk.find('Gate 0')
164
192
  ask = sk.find('六项问询')
193
+ has_fast = bool(re.search(r'Fast\s*Mode|快速模式', sk))
165
194
  chk('④ Gate 0 存在', g0 >= 0, '未找到「Gate 0」标记', '已就位')
166
195
  chk('④ Gate 0 在问询之前', g0 >= 0 and ask >= 0 and g0 < ask,
167
196
  f'Gate0@{g0} 未在六项问询@{ask} 之前', f'位置正确({g0} < {ask})')
197
+ if has_fast:
198
+ ok_exempt = bool(re.search(
199
+ r'(?:Fast\s*Mode|快速模式).{0,400}(?:跳过|豁免).{0,120}(?:Gate\s*0|参考图|六项)',
200
+ sk, re.S)) or bool(re.search(
201
+ r'(?:跳过|豁免).{0,60}(?:Gate\s*0|参考图|六项问询)', sk))
202
+ chk('④ Fast Mode 豁免声明', ok_exempt,
203
+ '有 Fast Mode 但未声明 Gate 0/六项豁免', '已声明豁免')
204
+ ok_std = bool(re.search(r'标准.{0,24}(?:硬门禁|强制)|Gate\s*0.{0,48}硬门禁', sk))
205
+ chk('④ 标准路径 Gate 0 仍为硬门禁', ok_std,
206
+ '有 Fast Mode 但标准路径未保留 Gate 0 硬门禁表述', '已保留')
168
207
 
169
208
  # ⑤ 效率预算声明
170
209
  chk('⑤ 交互轮次预算', bool(re.search(r'交互轮次|轮次上限|≤\s*3\s*轮', sk)),