dsh-ppt 0.21.1 → 0.23.0

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 (49) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.en.md +37 -23
  3. package/README.md +37 -22
  4. package/docs/COACHING.md +14 -13
  5. package/docs/DATA.md +8 -8
  6. package/docs/REFERENCE.en.md +17 -19
  7. package/docs/REFERENCE.zh.md +16 -18
  8. package/docs/USAGE.en.md +107 -60
  9. package/docs/USAGE.md +115 -84
  10. package/docs/VALIDATION.md +2 -0
  11. package/docs/VISUAL.md +27 -20
  12. package/docs/WORKBENCH.md +17 -6
  13. package/docs/assets/intro/screen-en.webp +0 -0
  14. package/docs/assets/intro/screen-zh.webp +0 -0
  15. package/lib/client.js +1286 -52
  16. package/lib/coaching.d.ts +1 -1
  17. package/lib/coaching.js +25 -12
  18. package/lib/config.d.ts +2 -0
  19. package/lib/config.js +36 -2
  20. package/lib/execution.d.ts +2 -1
  21. package/lib/execution.js +21 -1
  22. package/lib/tools.d.ts +1 -1
  23. package/lib/tools.js +160 -25
  24. package/lib/types.d.ts +115 -8
  25. package/lib/visual.d.ts +3 -1
  26. package/lib/visual.js +40 -13
  27. package/lib/workbench-language.js +49 -9
  28. package/lib/workbench.d.ts +5 -0
  29. package/lib/workbench.js +603 -12
  30. package/package.json +8 -3
  31. package/skills/dsh-ppt/SKILL.md +56 -54
  32. package/skills/dsh-ppt/package.json +17 -5
  33. package/skills/dsh-ppt/references/advanced.md +123 -41
  34. package/skills/dsh-ppt/references/copywriting.md +63 -41
  35. package/skills/dsh-ppt/references/data.md +83 -36
  36. package/skills/dsh-ppt/references/syntax.md +157 -28
  37. package/skills/dsh-ppt/references/themes.md +113 -58
  38. package/skills/dsh-ppt/references/troubleshooting.md +21 -16
  39. package/skills/dsh-ppt/scripts/build-deck.mjs +67 -28
  40. package/skills/dsh-ppt/scripts/deck-absorb.mjs +1338 -0
  41. package/skills/dsh-ppt/scripts/deck-advanced.mjs +422 -105
  42. package/skills/dsh-ppt/scripts/deck-core.mjs +572 -717
  43. package/skills/dsh-ppt/scripts/deck-data-view.mjs +30 -11
  44. package/skills/dsh-ppt/scripts/deck-data.mjs +35 -5
  45. package/skills/dsh-ppt/scripts/deck-director.mjs +2057 -0
  46. package/skills/dsh-ppt/scripts/deck-layouts.mjs +4673 -0
  47. package/skills/dsh-ppt/scripts/deck-media.mjs +1408 -86
  48. package/skills/dsh-ppt/scripts/deck-themes.mjs +1854 -0
  49. package/skills/dsh-ppt/scripts/deck-visual.mjs +133 -31
@@ -1,66 +1,113 @@
1
- # 数据来源、公式和推演
1
+ # 数据来源溯源、公式引擎与全版式现场推演(`dataModel`)
2
2
 
3
- 默认直接交付成品。需要解释数字或现场推演时,才在 `ppt_create` 提供 `dataModel` 和结构化 `slides`。不从相同数值猜来源,不虚构单元格、原文或文件。
3
+ 默认直接交付成品。当用户需要对关键经营/科研数字保留**可核查来源链**,或在汇报现场通过**交互滑块实时推演不同假设情景**时,在 `ppt_create` 中同时提供 `dataModel` 与结构化 `slides`。**铁律:绝不从相同数值倒推猜测来源,绝不虚构单元格、行号或外部文件。**
4
4
 
5
- ## 最小完整示例
5
+ ---
6
+
7
+ ## 一、最小完整示例(覆盖 KPI 指标卡 + 瀑布/柱状图 + 底栏结论联动)
6
8
 
7
9
  ```json
8
10
  {
9
- "title": "经营情景",
11
+ "title": "2026 经营情景推演",
12
+ "theme": "consulting",
10
13
  "slides": [
11
- { "layout": "cover", "title": "经营情景", "subtitle": "基期收入 {{base}}" },
12
- { "layout": "bullets", "title": "增长 {{growth}}", "bullets": ["推演收入 {{revenue}}", "以上增长率是讨论假设"] },
13
- { "layout": "chart", "title": "收入对比", "chart": { "kind": "column", "categories": ["基期", "情景"], "series": [{"name": "收入", "values": ["{{base}}", "{{revenue}}"]}], "unit": "万元" } }
14
+ {
15
+ "layout": "cover",
16
+ "kicker": "经营推演",
17
+ "title": "存量增购驱动下的年度营收敏感性测算",
18
+ "subtitle": "基期核定收入 {{base}}"
19
+ },
20
+ {
21
+ "layout": "kpi",
22
+ "variant": "grid",
23
+ "kicker": "01 · 核心假设与产出",
24
+ "title": "当增购率达到 {{growth}} 时,全年营收预计跃升至 {{revenue}}",
25
+ "items": [
26
+ { "tag": "基期事实", "value": "{{base}}", "text": "源自财务核定台账" },
27
+ { "tag": "讨论假设", "value": "{{growth}}", "status": "accent", "text": "现场可调增购率参数" },
28
+ { "tag": "推演营收", "value": "{{revenue}}", "delta": "净增 {{deltaRev}}", "status": "positive", "text": "实时公式联动重算" }
29
+ ],
30
+ "takeaway": "敏感性结论:在 {{growth}} 增购假设下,净增贡献达 {{deltaRev}}(仅作经营讨论,非业绩承诺)。",
31
+ "source": "数据来源:经营数据.csv(单元格 B2)及现场推演模型"
32
+ },
33
+ {
34
+ "layout": "chart",
35
+ "kicker": "02 · 情景对比",
36
+ "title": "推演情景较基期实现 {{deltaRev}} 增量突破",
37
+ "chart": {
38
+ "kind": "waterfall",
39
+ "categories": ["基期收入", "增购净增", "情景总收入"],
40
+ "series": [{ "name": "收入", "values": ["{{base}}", "{{deltaRev}}", "{{revenue}}"] }],
41
+ "totalIndices": [0, 2],
42
+ "unit": "万元"
43
+ },
44
+ "source": "数据来源:经营数据.csv"
45
+ }
14
46
  ],
15
47
  "dataModel": {
16
48
  "schemaVersion": 1,
17
- "sources": [{ "id": "sales", "name": "经营数据.csv", "format": "csv", "content": "项目,收入\n基期,1000" }],
49
+ "sources": [
50
+ { "id": "sales", "name": "经营数据.csv", "format": "csv", "content": "项目,收入\n基期,1000" }
51
+ ],
18
52
  "metrics": [
19
53
  { "id": "base", "label": "基期收入", "kind": "source", "source": { "sourceId": "sales", "cell": "B2" }, "format": { "digits": 0, "unit": "万元" } },
20
- { "id": "growth", "label": "增长率", "kind": "input", "value": 0.3, "min": 0, "max": 1, "step": 0.1, "note": "用于讨论的假设,不是业绩承诺", "format": { "style": "percent", "digits": 0 } },
21
- { "id": "revenue", "label": "情景收入", "kind": "formula", "formula": "base * (1 + growth)", "format": { "digits": 0, "unit": "万元" } }
54
+ { "id": "growth", "label": "增购增长率", "kind": "input", "value": 0.3, "min": 0, "max": 1, "step": 0.05, "note": "用于管理层讨论的敏感性假设,非业绩承诺", "format": { "style": "percent", "digits": 0 } },
55
+ { "id": "deltaRev", "label": "净增收入", "kind": "formula", "formula": "base * growth", "format": { "digits": 0, "unit": "万元" } },
56
+ { "id": "revenue", "label": "情景总收入", "kind": "formula", "formula": "base + deltaRev", "format": { "digits": 0, "unit": "万元" } }
22
57
  ]
23
58
  }
24
59
  }
25
60
  ```
26
61
 
27
- `source` 是材料中的事实,`input` 是可调假设,`formula` 是推导。百分比以比例计算:30% 是 `0.3`。数字格式为 `number`(默认)或 `percent`、0–6 位小数及可选 `unit`。显示舍入不改变计算输入。
62
+ ---
28
63
 
29
- 文本、要点、表格、备注和图表标签用 `{{metricId}}`;图表数值必须是完整占位符,计算仍使用原始数值。ID 使用字母开头的字母和数字,最多 48 字符。
64
+ ## 二、绑定范围与格式规则(全版式通用)
30
65
 
31
- ## 来源
66
+ 1. **三类指标(`metrics`)**:
67
+ - `source`:真实材料中的客观事实数值。
68
+ - `input`:汇报现场可通过滑块调节的敏感性假设(必须如实标注 `note` 说明假设性质)。
69
+ - `formula`:由前两者推导出的确定性算术结果。
70
+ 2. **全字段 `{{metricId}}` 占位绑定**:
71
+ - 文本类绑定:支持在 `title`、`subtitle`、`kicker`、`bullets[]`、**`items[]`(含 `gantt / tam / architecture / org / kpi / cards` 的 `tag / value / title / text / delta / bullets`)**、**`columns[]`(`gantt` 时间列)**、**`takeaway`**、**`source`**、`rows[][]`(含 `table` 与 `harvey` 矩阵)与 `notes` 中嵌入一个或多个 `{{metricId}}`(保留内联 `**加粗**` 富文本样式,HTML 放映中渲染为可点击溯源与实时联动更新的数字徽章)。
72
+ - 图表数值绑定:`chart.series[i].values` 中的绑定项必须是完整独立的 `"{{metricId}}"` 字符串(计算与绘图仍使用未舍入的精确原始数值,支持全部 13 类图表及矢量 `waterfall` 实时重绘)。
73
+ - 格式约定:百分比在模型中以比例存储(`30%` 存为 `0.3`);`format.style` 支持 `'number'`(默认)或 `'percent'`,`digits` 为 `0–6` 位小数,可选 `unit`。指标 ID 以字母开头,仅含字母与数字,最长 48 字符。
32
74
 
33
- - 表格:`format:csv/tsv` + `content`,或 `kind:table` + `rows`。地址 `A1–Z500`,首行表头也算第 1 行。引用格必须是单一数值,可含千位逗号或百分号。
34
- - 材料:`format:text` + `content`,或 `kind:text` + `text`。引用 `{sourceId,line:1,numberIndex:0}`;行号从 1 开始,该行数值序号从 0 开始。日期、版本号也可能被识别为数字,必须检查截取位置。
35
- - 工具调用可显式给 `path` 读取本地普通文件,按会话 cwd 解析;只读取一次并嵌入,不监视源文件。网页只能使用用户选取或粘贴的内容,不能让浏览器请求读取任意路径。
36
- - UTF-8 CSV / TSV / TXT / Markdown;最多 8 个来源、合计 1 MiB,表格最多 500 行 / 26 列,各行等宽,每格最多 2000 字符。文本引用行最多 8000 字符。无 XLSX / PDF 数字自动提取。
75
+ ---
37
76
 
38
- ## 算术与范围
77
+ ## 三、数据来源(`sources`)与算术安全边界
39
78
 
40
- 最多 80 个指标和 12 个假设。假设必须提供有限的 `value/min/max/step`,处于范围和步长网格内,最多 100000 步。计算结果绝对值不超过 1e15。
79
+ - **结构化表格来源**:`format: 'csv' | 'tsv'` + `content`(或 `kind: 'table'` + `rows`),单元格地址 `A1–Z500`(首行表头计为第 1 行),被引用格须为单一数值(支持千分位逗号或百分号)。
80
+ - **纯文本/文档来源**:`format: 'text'` + `content`(或 `kind: 'text'` + `text`),通过 `{ sourceId, line: 1, numberIndex: 0 }` 定位(行号从 1 起算,行内数字序号从 0 起算;务必核对日期或版本号以免误取)。
81
+ - **文件读取边界**:工具调用可显式传本地相对会话 `cwd` 的普通文件 `path`(读取一次后内嵌进工程,不后台监听源文件);浏览器网页端仅允许用户主动粘贴或选取内容,严禁请求读取任意本地路径。支持 UTF-8 CSV / TSV / TXT / Markdown,最多 8 个来源、合计 ≤ 1 MiB,表格 ≤ 500 行 × 26 列,不支持直接自动提取 XLSX 或 PDF 二进制表。
82
+ - **确定性公式沙箱**:最多 80 个指标、12 个可调假设(`value / min / max / step` 有限且对齐步长网格,≤ 100,000 步,结果绝对值 ≤ `1e15`)。允许括号、`+ - * / % **`、一元正负及内置函数 `min / max / sum / abs / floor / ceil / round(val, 0..6)`(最多 256 个 AST 节点、32 层表达式、40 层依赖;循环依赖、除零、未知指标立即报中文错误;零 `eval`、零网络或文件副作用)。
41
83
 
42
- 公式允许指标 ID、括号、`+ - * / % **`、一元正负,以及 `min/max/sum/abs/floor/ceil/round`。`round(value,digits)` 的 digits 为 0–6。最多 256 个 AST 节点、32 层表达式和 40 层指标依赖。循环、除零、未知指标、非有限结果会报错。没有 `eval`、属性访问、赋值、网络或文件执行。
84
+ ---
43
85
 
44
- ## 更新与确认
86
+ ## 四、两阶段预览确认更新与离线 `scenario.json` 回存
45
87
 
46
88
  ```js
47
- // 1. 先预览,不修改任何成品。
48
- ppt_data({ action: 'preview', deckPath, expectedRevision: 0,
49
- parameters: { growth: 0.5 } })
50
- // 或替换已有来源:sourceUpdates:[{id:'sales',format:'csv',content:'项目,收入\n基期,1200'}]
51
-
52
- // 2. 向用户展示 changes、affectedSlides 与字段前后差异,确认后再保存。
53
- ppt_data({ action: 'apply', deckPath, expectedRevision: 0,
54
- parameters: { growth: 0.5 }, confirmed: true, previewToken: preview.token })
89
+ // 1. 先 preview 预览(零文件改动),拿到差异明细与 previewToken
90
+ const preview = await ppt_data({
91
+ action: 'preview',
92
+ deckPath,
93
+ expectedRevision: 0,
94
+ parameters: { growth: 0.45 }
95
+ })
96
+
97
+ // 2. 向用户清晰展示 changes、affectedSlides 与前后字段对比,获明确确认后 apply
98
+ await ppt_data({
99
+ action: 'apply',
100
+ deckPath,
101
+ expectedRevision: 0,
102
+ parameters: { growth: 0.45 },
103
+ confirmed: true,
104
+ previewToken: preview.token
105
+ })
55
106
  ```
56
107
 
57
- 应用默认 `saveAs:true`,原稿不变,新副本可撤销;`saveAs:false` 仍执行外部成品修改保护。预览凭证绑定完整工程状态、数据与修订,任一变化都应重新预览。`ppt_undo` 同步恢复来源、参数、公式和页面。
58
-
59
- `ppt_edit` 会保留未修改字段的绑定。用普通文字替换绑定字段会解除该字段绑定;需要继续联动时保留占位符。确认后的静态 PPTX 备注和下载报告附上引用链。可选 AI 预审也会获得页面相关的公式与假设说明,不把来源关联当作事实核验。
60
-
61
- 离线 HTML 的 `scenario.json` 包含 `schemaVersion/deckId/revision/fingerprint/parameters`。导回相同 DSH 工程后预览、确认,再下载匹配的静态 PPTX;也可作为 `ppt_data.scenario` 传入。不可将旧工程参数强套到新副本。
62
-
63
- 跨 harness:在技能目录 `npm install --ignore-scripts` 后,使用 `node scripts/build-deck.mjs --title ... --slides @slides.json --data-model @model.json --out ...`。直接 JS 调用使用 `deck-advanced.mjs` 的 `buildDeckAsync`;同步 `deck-core.buildDeck` 不支持数据模型。
108
+ - `apply` 默认 `saveAs: true` 另存新副本,原稿安全保留,且支持 `ppt_undo` 同步回退数据模型与页面内容。`ppt_edit` 修改其他字段时会自动保留未改动字段的 `{{metricId}}` 绑定(若用纯文本覆盖某字段则解除该字段绑定)。
109
+ - 离线 HTML 放映器调节滑块后可导出 `scenario.json`(含 `deckId / revision / fingerprint / parameters`),导回同一 DSH 工程执行 `preview` → 用户确认 `apply` 后,即可导出数值完全匹配的静态可编辑 PPTX(备注与交付说明自动附带完整数据引用链)。
110
+ - 跨 harness CLI:`node scripts/build-deck.mjs --title "..." --slides @slides.json --data-model @model.json --theme consulting --out dist`(JS 编程调用请使用 `deck-advanced.mjs` 的 `buildDeckAsync`)。
64
111
 
65
112
  ## Dependencies
66
113
 
@@ -1,44 +1,173 @@
1
- # dsh-ppt 输入语法参考(Markdown / 结构化 slides / 动效)
1
+ # dsh-ppt 输入语法与 24 套原生版式参考(结构化 slides · 5 套专业图示 · 扩展 Markdown · 动效)
2
2
 
3
- 只在需要查具体语法时读本文件;常规流程在 SKILL.md。
3
+ `ppt_create` 与 `build-deck.mjs` 支持**结构化 `slides` JSON(大师级精细控制首选)**或**Markdown `content`**(两者二选一,勿混用)。所有版式(含 5 套全新零依赖专业图示)在独立 HTML 与 PPTX 中均编译为 **100% 原生可编辑文本、矢量形状、表格与图表**。
4
4
 
5
- ## Markdown 解析规则
5
+ ---
6
6
 
7
- `ppt_create` 与 `build-deck.mjs` 按以下规则解析 Markdown:
7
+ ## 一、24 套标准版式(`layout` + `variant`)全景速查
8
8
 
9
- - 第一个 `# 标题` 会成为封面标题;其后的段落/列表成为封面副标题来源。
10
- - 每个 `## 小节`(或更深标题)生成一页:
11
- - 有 `- ` / `* ` / `1.` 列表 → `bullets` 页;
12
- - 无列表且无正文 → `section` 过渡页;
13
- - 有正文段落 → 正文拆句后作为 bullets。
14
- - 没有标题的纯文本:第一段第一句为封面副标题,后续段落按 5 句一组拆成要点页。
15
- - 只有一句话:自动生成「封面 → 核心观点 → 结束页」三页。
16
- - 需要更精细控制时使用结构化 `slides` JSON,不要和 Markdown 混用。
9
+ ### A. 19 套零依赖原生版式与专业图示(核心引擎直出)
17
10
 
18
- ## 进阶语法(自动识别)
11
+ | `layout` | 可选 `variant` / `tableStyle` | 核心槽位 | 典型视觉形态与适用场景 |
12
+ | --- | --- | --- | --- |
13
+ | `cover` | `standard \| monolith \| editorial \| swiss-grid \| inverted` | `kicker, title, subtitle` | 演示封面(自动隐藏页码;`exec-jilan`/`exec-palace` 自动深色描金压轴) |
14
+ | `agenda` | `list \| cards`(可选 `activeIndex`) | `kicker, title, items / bullets` | 结构化目录 / 章节导航(支持当前章节高亮) |
15
+ | `section` | `minimal \| number-hero \| inverted` | `kicker, title, subtitle` | 章节过渡页(超大章节编号 + 章节核心命题) |
16
+ | `bullets` | `clean \| accent-rail \| ruled \| two-column` | `kicker, title, subtitle, bullets, takeaway` | 精炼要点页(自动识别 `**加粗引导词**:说明`;建议 ≤ 5 条) |
17
+ | `statement` | `rail \| editorial-asymmetric \| centered` | `kicker, title, subtitle` | 单页核心宣言 / 价值主张留白页 |
18
+ | `quote` | `editorial \| card` | `kicker, title, subtitle` | 金句引述页(`title` 为引文,`subtitle` 为署名/出处) |
19
+ | `kpi` | `grid \| hero-left \| banner` | `kicker, title, items`(2–4 项), `takeaway, source` | 大数字指标卡(等宽核心数值 `value` + `unit` + 涨跌胶囊 `delta`) |
20
+ | `cards` | `pillars \| bento \| exec-summary \| numbered` | `kicker, title, subtitle, items`(2–6 项), `takeaway` | **主力去要点墙版式**:并列支柱卡、Apple/Linear 非对称 Bento 网格、麦肯锡顶部总论断+三支柱 `exec-summary` |
21
+ | `comparison` | `versus \| before-after \| do-dont \| issue-action` | `kicker, title, items`(2 列或 2–4 对配对行), `takeaway` | A/B 方案对比、改造前后、✓ 推荐 vs ✗ 误区、政企「痛点 ──▶ 整改举措」原生箭头配对 |
22
+ | `matrix` | `2x2 \| grid` | `kicker, title, items`(4 象限), `takeaway` | 咨询四象限矩阵(带原生 X/Y 坐标轴箭头与象限卡片) |
23
+ | `process` | `steps \| timeline \| chevron \| layers \| funnel \| flywheel` | `kicker, title, items`(3–6 步), `takeaway` | 方法管线步骤、里程碑时间轴、**咨询价值链咬合五边形箭头(`chevron`,亦支持 `layout: "chevron" \| "value-chain"` 别名)**、技术分层、转化漏斗、4 节点增长飞轮 |
24
+ | `callout` | `formula \| definition \| takeaways` | `kicker, title, subtitle, items / bullets, source` | 学术公式/算法定理框、核心概念定义卡、复盘行动清单 |
25
+ | `table` | `tableStyle`: `consulting \| booktabs \| minimal \| banded \| harvey` | `kicker, title, rows`(首行表头), `takeaway, source` | 原生可编辑对比表(`booktabs` 为**无竖线学术三线表**;`harvey` 支持哈维球;数值列右对齐;> 8 行自动分页) |
26
+ | **`gantt`** | `quarters \| months \| weeks \| swimlane` | `kicker, title, columns[], items[]`(`start, span, milestone?`), `takeaway` | **原生甘特排期图**:自动时间刻度栅格、泳道标签、比例条形块与菱形里程碑节点 |
27
+ | **`architecture`** | `layered \| platform` | `kicker, title, items[]`(`bullets[]` 子模块,`status:'accent'` 侧边纵列) | **原生系统架构图**:多层技术栈横向模块 + 右侧跨层安全/治理纵栏 + 双向数据流箭头 |
28
+ | **`harvey`** | `matrix` | `kicker, title, rows[][]`(支持 `● ◕ ◑ ◔ ○ ✓ ✗` 或 `100%/75%/50%/25%/0%`) | **麦肯锡式哈维球竞品/能力矩阵**:自动高亮「本方案 / Ours」列并将符号渲染为精确矢量圆球 |
29
+ | **`tam`** | `concentric` | `kicker, title, items[]`(3 项 TAM/SAM/SOM,含 `value, title, text`) | **同心圆市场空间测算图**:左侧 3 个底切原生同心椭圆 + 右侧 3 张规模与口径说明卡 |
30
+ | **`org`** | `tree \| team` | `kicker, title, items[]`(`tree` 首项为根节点,2–5 项为子节点;`team` 2–4 人) | **组织架构树 / 核心管理团队介绍**:`tree` 带正交直角连接线;`team` 带圆标首字母头像与履历标签 |
31
+ | `closing` | `standard \| cta-cards \| inverted` | `kicker, title, subtitle, items / bullets` | 结束与行动号召页(自动隐藏页码;支持下一步行动卡片,拒绝孤立「谢谢」) |
19
32
 
20
- - **表格**:`| 列 | 列 |` 连续行(第二行 `| --- | --- |` 分隔线)→ 独立 `table` 页(主题色表头;每页 8 行数据,长表格自动续页并重复表头;最多 8 列、每格 60 字符,超限先报错)。数据对比优先用表格,别堆要点。
21
- - **金句**:`>` 引用块 → 独立 `quote` 页;最后一行写 `—— 出处` 会成为署名。
22
- - **演讲者备注**:`<!-- 备注: 这页要讲的内容 -->`(或 `<!-- note: ... -->`)附着到该页。备注不进正文:HTML 放映按 `S` 呼出备注面板,PPTX 写入原生备注(演示者视图可见)。为汇报/演讲类 deck 主动写备注(口径、数据出处、应答预案)。
33
+ ### B. 5 套媒体与出版级图表版式(`@office-kit/pptx` 增强)
23
34
 
24
- ## 结构化 slides(高级用法)
35
+ | `layout` | 可选 `variant` | 核心槽位 | 典型视觉形态与适用场景 |
36
+ | --- | --- | --- | --- |
37
+ | `image` | `framed \| full-bleed \| gallery` | `title, subtitle, image` 或 `images[]`(2–3 张) | 单图圆角精裱画框、全屏出血视觉页、2–3 图并排画册展示(亦兼容输入别名 `layout: "gallery"`) |
38
+ | `image-left` | `framed \| split-bleed` | `kicker, title, subtitle, image, items / bullets` | 左图右文(正文列垂直居中 + 导语分层;`split-bleed` 为左半屏无边距出血大图) |
39
+ | `image-right` | `framed \| split-bleed` | `kicker, title, subtitle, image, items / bullets` | 左文右图(同上) |
40
+ | `chart` | — | `kicker, title, subtitle, chart, takeaway, source` | 全幅出版级图表(13 种图表含矢量 `waterfall` 瀑布桥;亦兼容别名 `layout: "waterfall"`) |
41
+ | `chart-split` | `chart-left \| chart-right` | `kicker, title, chart, items / bullets, takeaway, source` | **62% 图表 + 38% 结构化洞察卡**(消除单图空旷感,最适合经营归因与消融实验对比) |
25
42
 
26
- `ppt_create` 的 `slides` 与 CLI `--slides` 接受 JSON 数组:
43
+ ---
44
+
45
+ ## 二、统一结构化 `slides` JSON 规范(推荐)
46
+
47
+ 所有卡片/指标/步骤/象限类版式统一使用 **`items` 数组**(引擎同时兼容别名 `cards / metrics / columns / steps / quadrants`,并支持在未传 `items` 时从 `bullets` 自动投影):
27
48
 
28
49
  ```json
29
50
  [
30
- { "layout": "cover", "title": "标题", "subtitle": "副标题", "kicker": "开场", "notes": "开场先自我介绍 30 秒" },
31
- { "layout": "section", "kicker": "01", "title": "背景" },
32
- { "layout": "bullets", "title": "三个论点", "bullets": ["论点一", "论点二", "论点三"] },
33
- { "layout": "table", "title": "业绩对比", "rows": [["大区", "营收"], ["华东", "1.2 亿"]], "notes": "强调华东增速" },
34
- { "layout": "quote", "title": "慢就是快。", "subtitle": "创始人" },
35
- { "layout": "statement", "title": "核心观点一句话", "subtitle": "支撑说明" },
36
- { "layout": "closing", "title": "谢谢", "subtitle": "行动号召" }
51
+ {
52
+ "layout": "cover",
53
+ "variant": "standard",
54
+ "kicker": "2026 年度战略复盘",
55
+ "title": "聚焦高价值政企客群,实现高质量盈利增长",
56
+ "subtitle": "商业战略部 · 2026 Q4",
57
+ "notes": "开场 30 秒点明全年核心战略转向。"
58
+ },
59
+ {
60
+ "layout": "kpi",
61
+ "variant": "grid",
62
+ "kicker": "01 · 总体成效",
63
+ "title": "核心经营指标全面超额达成,净留存率创历史新高",
64
+ "items": [
65
+ { "tag": "年度营收", "value": "1.84", "unit": "亿元", "delta": "+38% YoY", "status": "positive", "text": "政企续费贡献 64% 增量" },
66
+ { "tag": "净收入留存", "value": "126%", "delta": "+11pp", "status": "positive", "text": "头部 50 客户零流失" },
67
+ { "tag": "交付周期", "value": "4.5", "unit": "天", "delta": "-62%", "status": "accent", "text": "标准化模板自动装配" }
68
+ ],
69
+ "takeaway": "核心启示:规模增长已由新客驱动平稳切换为存量增购与交付提效双轮驱动。",
70
+ "source": "数据来源:财务审计报表 2026Q1–Q4"
71
+ },
72
+ {
73
+ "layout": "cards",
74
+ "variant": "bento",
75
+ "kicker": "02 · 增长引擎",
76
+ "title": "三大产品工程能力构筑下一阶段竞争壁垒",
77
+ "items": [
78
+ { "tag": "引擎 01", "title": "母版智能吸收", "text": "**零手工调色**:秒级提取外部 PPTX 色板与字体并自动完成 WCAG 对比度净化。" },
79
+ { "tag": "引擎 02", "title": "19 套原生版式", "text": "**100% 可编辑**:所有卡片、矩阵与三线表均为 PowerPoint 原生形状与表格。" },
80
+ { "tag": "引擎 03", "title": "数字溯源联动", "text": "**一改全改**:CSV 单元格绑定与现场滑块推演同步刷新图表与正文。" }
81
+ ]
82
+ },
83
+ {
84
+ "layout": "comparison",
85
+ "variant": "issue-action",
86
+ "kicker": "03 · 短板与攻坚",
87
+ "title": "针对三大交付堵点制定闭环整改举措",
88
+ "items": [
89
+ { "tag": "痛点 01", "title": "手工排版耗时过长", "text": "单份汇报平均耗费 4.2 小时调对齐 → **上线智能审美导演一键定稿**", "status": "accent" },
90
+ { "tag": "痛点 02", "title": "跨平台投影缺字变形", "text": "Linux/Mac 打开字号错位 → **内置双语安全字体矩阵与 13.5pt 底线锁**", "status": "positive" }
91
+ ]
92
+ },
93
+ {
94
+ "layout": "table",
95
+ "tableStyle": "booktabs",
96
+ "kicker": "04 · 基准评测",
97
+ "title": "新引擎在三项核心评测指标上全面领先传统工作流",
98
+ "rows": [
99
+ ["评测维度", "传统手工模板", "通用 AI 生成", "本方案 (Ours)"],
100
+ ["平均成稿耗时", "240 min", "15 min", "**3.5 min**"],
101
+ ["原生形状可编辑率", "100%", "42%", "**100%**"],
102
+ ["WCAG AA 对比度达标率", "68%", "55%", "**100%**"]
103
+ ],
104
+ "source": "注:基于 30 份真实业务汇报双盲测试均值,加粗为最优项。"
105
+ },
106
+ {
107
+ "layout": "closing",
108
+ "variant": "cta-cards",
109
+ "kicker": "下一步行动",
110
+ "title": "Q1 启动三大标杆部门试点,两周内完成母版入库",
111
+ "subtitle": "联系团队:strategy@example.com",
112
+ "items": [
113
+ { "tag": "第 1 周", "title": "母版归集", "text": "导入集团标准 PPTX 模板生成统一品牌预设" },
114
+ { "tag": "第 2 周", "title": "全员赋能", "text": "覆盖战略、销售与研发三线周报与述职场景" }
115
+ ]
116
+ }
37
117
  ]
38
118
  ```
39
119
 
40
- `layout` 支持 `cover | section | bullets | statement | quote | table | closing | image | image-left | image-right | chart`;每页可选 `notes`,表格用 `rows`(首行为表头)。结构化表格自动分页,备注只放第一页。分页后超过 maxSlides 会报错,最多120页。图文、图表、品牌及按页编辑见 `advanced.md`。
120
+ ### `items[]` 单项字段说明
121
+ - `tag`(别名 `badge`):顶部小标签/序号(如 `"01"`、`"痛点"`、`"Q3"`)。
122
+ - `title`:卡片/步骤/象限主标题。
123
+ - `text`(别名 `body`):说明正文,支持内联 `**加粗**`、`*斜体*`、`` `代码` ``。
124
+ - `value` / `unit` / `delta`:`kpi` 指标卡专用核心大数字、单位与涨跌标签。
125
+ - `bullets`:卡片内部短要点数组(适用于 `comparison[versus]`、`cards`、`architecture` 子模块)。
126
+ - `start` / `span` / `milestone`:`gantt` 甘特图专用起止列索引与里程碑标记(`0` 起始整数)。
127
+ - `columns`:`gantt` 顶部时间刻度列数组(如 `["Q1", "Q2", "Q3", "Q4"]`)。
128
+ - `chrome`:单页可选覆盖母版骨架(`'consulting-classic' | 'keynote-spatial' | 'editorial-folio' | 'saas-bento' | 'academic-minimal' | 'gov-ceremonial'`)。
129
+ - `status`(别名 `tone`):语义色调 `'positive' | 'negative' | 'warning' | 'neutral' | 'accent'`。
130
+
131
+ ---
132
+
133
+ ## 三、Markdown 解析与扩展容器语法(`content` 模式)
134
+
135
+ ### 1. 基础确定性规则
136
+ - 首个 `# 标题` 作为封面主标题,紧随其后的首段或首条作为封面副标题。
137
+ - 每个 `## 章节标题` 生成独立页面:含列表生成要点页,纯标题无正文生成 `section` 章节过渡页,含连续 `| 列 | 列 |` 生成 `table` 页(最多 8 列、单格 ≤ 60 字符),含 `>` 引用块生成 `quote` 金句页(末行 `—— 署名` 自动识别为署名)。
138
+ - **内联富文本保留**:列表、表格与正文中的 `**加粗**`、`*斜体*`、`` `code` `` 原生保留;形如 `- **关键词**:具体说明` 的条目在 HTML 与 PPTX 中自动渲染为粗体主色引导词 + 次级色说明。
139
+ - **底栏核心结论条**:章节内写 `> [!TAKEAWAY] 一句话核心结论` 会提取为该页底部的 `takeaway` 横幅,而非单独拆成金句页。
140
+ - **演讲者备注**:`<!-- 备注: 讲解口径与数据出处 -->`(或 `<!-- note: ... -->`)写入 HTML 演讲者面板(按 `S` 呼出)与 PPTX 原生演示者备注,不出现在画面正文。
141
+
142
+ ### 2. 显式版式容器指令(`:::` Fence Directives)
143
+ 在 Markdown 中无需手写 JSON 即可直接调用高级原生版式:
144
+
145
+ ````markdown
146
+ ## 核心增长指标全面提速
147
+ ::: kpi
148
+ - **1.84 亿元** | 年度营收 | +38% YoY | 政企续费贡献主力增量
149
+ - **126%** | 净收入留存 | +11pp | 头部客户零流失
150
+ - **4.5 天** | 平均交付周期 | -62% | 自动化流水线就绪
151
+ :::
152
+ > [!TAKEAWAY] 增长动力已切换为高留存增购驱动。
153
+
154
+ ## 四阶段演进路线图
155
+ ::: process timeline
156
+ - **Q1 筑基**:完成 14 套大师主题与跨平台字体门禁
157
+ - **Q2 扩展**:上线外部 PPTX 风格吸收器与出版级图表
158
+ - **Q3 闭环**:接入 24 页全量视觉检查与叙事教练
159
+ - **Q4 规模化**:覆盖全集团述职、答辩与客户提案
160
+ :::
161
+ ````
162
+
163
+ 支持指令:`::: kpi`、`::: cards [pillars|bento|exec-summary|numbered]`、`::: comparison [versus|before-after|do-dont|issue-action]`、`::: process [steps|timeline|layers|funnel]`、`::: matrix [2x2|grid]`、`::: callout [formula|definition|takeaways]`。
164
+
165
+ ### 3. 高层智能版式升格(`smartLayout`)
166
+ 当通过 `ppt_create`(`theme` 省略或设为 `'auto'`)处理 ≥ 4 节的常规 Markdown 文档时,智能导演会自动识别含显著指标百分比的列表升格为 `kpi`、含时间/阶段前缀的列表升格为 `process`、含对比语义的小节升格为 `comparison`,并将连续并列要点交替升格为 `cards`,自动消除单调要点墙(底层裸调 `parseMarkdownDeck` 默认不自动改版,确保精确脚本控制)。
167
+
168
+ ---
41
169
 
42
- ## 动效(motion)
170
+ ## 四、动效控制(`motion`)
43
171
 
44
- 默认 `motion: on`:HTML 放映有页间淡入与要点逐条入场;PPTX 每页原生淡入转场,`bullets` 页的要点按「点击一次出现一条」放映。交付严肃/打印场景或用户明确要静态时传 `motion: 'off'`(CLI `--motion off`),产物不含任何动画代码。
172
+ - 默认 `motion: 'on'`:HTML 放映启用平滑页间过渡与列表分步入场;PPTX 每页带原生淡入切换,`bullets` 页要点按鼠标点击逐条出现。
173
+ - 政企公文汇报、学术打印审阅或用户要求静态交付时,传 `motion: 'off'`(CLI `--motion off`),输出的 HTML 与 PPTX 不含任何入场动画代码。
@@ -1,61 +1,116 @@
1
- # dsh-ppt 内置主题参考
1
+ # dsh-ppt 大师主题系统、6 套母版骨架与色彩字体规范(24 套内置主题 + 8 套名家预设 + 外源母版吸收)
2
+
3
+ 每套主题在独立 HTML 与可编辑 PPTX 中共用同一套 **18 语义设计 Token(`theme.tokens`)**、**6 套差异化母版骨架(`chromeStyle`)** 与跨平台零缺字字体映射,确保屏幕放映、会议室投影仪与打印件视觉完全一致。
4
+
5
+ > 预览全部 24 套主题:运行 `ppt_themes { preview: true, outputDir: "dist" }`(或 CLI `--theme-preview --out dist`),生成 `themes-preview.html` 对比页与 24 张 `theme-<id>.svg` 色板卡。
6
+
7
+ ---
8
+
9
+ ## 一、零追问选型决策树(Scenario Auto-Director)
2
10
 
3
- 主题系统移植自 hyperframes 技能的 `visual-styles.md` 视觉风格库。每套主题在 HTML 与 PPTX 中使用同一色板、同一字体族、同一情绪规则。
11
+ 当用户未指定主题时,传 `theme: 'auto'`(或在构建前按以下规则选定具体 ID)。**核心原则:80% 的真实职场、学术与政务场景发生在开灯会议室或教室投影下,默认优先选用明亮高对比度浅底主题,切勿盲目回退暗黑赛博风 `data`!**
4
12
 
5
- > 想先看效果:运行 `ppt_themes { preview: true, outputDir: "dist" }`,会生成 `themes-preview.html` 与每套主题一张 `theme-<id>.svg`;README/npm 首屏可以直接引用 SVG。
13
+ 1. **商业战略、管理咨询、经营分析、周报复盘、通用模糊汇报** → **`consulting`**(蔚蓝战略)或 **`cobalt-cream`**(钴蓝简报);**季度财报、投行路演、宏观研究** → **`financial-ft`**(金融时报粉)
14
+ 2. **政企汇报、国企述职、年度总结、专项行动** → **`exec-jilan`**(霁蓝政务 · 庄重深蓝封面 + 宣纸暖白正文);党政表彰、盛会总结 → **`exec-palace`**(故宫丹宸 · 丹红描金封面 + 暖白正文)
15
+ 3. **学术科研、论文汇报、开题/毕业答辩** → **`academic`**(清澄学术 · ETH 青 + 默认学术三线表);**临床病例、生物医药、医院研讨** → **`medical-clean`**(循证医学蓝绿)
16
+ 4. **教育培训、课程讲义、知识科普、新人入职工作坊** → **`course-sage`**(知行讲义 · 护眼鼠尾草绿)或 **`soft`**(柔和信号 · 亲和暖米色)
17
+ 5. **品牌提案、人文策展、画册设计**:
18
+ - 森系文化 / ESG → **`editorial-forest`**(森系社论)
19
+ - 建筑 / 极简画册 → **`cartesian`**(暖石极简)
20
+ - 高奢品牌 / 黑金典藏 → **`luxury-noir`**(黑金典藏)
21
+ 6. **科技产品发布、AI/SaaS 融资路演、Keynote 演讲**:
22
+ - Apple 极简空间白场 → **`keynote-light`**(苹果极简白 · 无框留白)
23
+ - 现代线性层级暗色(首选)→ **`linear-dark`**(黑曜石路演 · `1px` 微表面层级)
24
+ - 开发者工具 / 精准指标 → **`swiss`**(瑞士脉冲)
25
+ - 前沿 AI / 沉浸数据流 → **`data`**(数据漂移)
26
+ - 奢品高管 / 私享晚宴路演 → **`velvet`**(天鹅绒标准 · 黑金衬线)
27
+ - 高能量活动 / 先锋大字宣言 → **`bold`**(极繁先锋)
28
+ 7. **用户提供了单位母版或参考 `.pptx`** → 调 `ppt_absorb` 或在 `ppt_create` 传 `referencePptx`(加 `cloneStructure: true` 可同步克隆逐页骨架与母版 `chromeStyle`)!
29
+
30
+ ---
31
+
32
+ ## 二、6 套差异化母版骨架(`CHROME_STYLES`)
33
+
34
+ 打破「14 套主题同一套卡片布局」,可通过 `brand.chromeStyle` 整套切换,或通过单页 `slide.chrome` 局部覆写:
35
+
36
+ | `chromeStyle` | 默认关联主题 | 几何与页眉页脚签名特征 |
37
+ | --- | --- | --- |
38
+ | **`consulting-classic`** | `consulting`, `cobalt-cream`, `financial-ft` | `0px` 锐利直角、卡片左侧 `2.5pt` 竖条、右上角章节追踪胶囊、底栏横线 `Key Takeaway:` |
39
+ | **`keynote-spatial`** | `keynote-light`, `bold` | **无顶部分割线**、通透空间留白、`16pt` 无描边软圆角卡、浮动 Kicker 胶囊、居中无框摘要 |
40
+ | **`editorial-folio`** | `editorial-forest`, `cartesian`, `velvet`, `luxury-noir` | 顶部通栏 `0.5pt` 杂志眉栏(**页码移至右上角**)、`0px` 建筑硬边框、超大衬线序号 |
41
+ | **`saas-bento`** | `linear-dark`, `swiss`, `data`, `soft` | `10pt` 圆角微描边卡、首卡强调高亮、现代等宽数据胶囊 |
42
+ | **`academic-minimal`** | `academic`, `course-sage`, `medical-clean` | **Beamer Metropolis 通栏着色页眉带**(`1.5pt` 底边强调线)+ **底部三段式学术状态栏** |
43
+ | **`gov-ceremonial`** | `exec-jilan`, `exec-palace` | **双线庄重页眉**(`1.5pt` 主色线 + `0.5pt` 辅色金线)、`【01 · 章节】` 绶带标签、宣纸对称卡片 |
44
+
45
+ ---
46
+
47
+ ## 三、24 套内置大师主题速查表(16 浅 + 8 深,全部通过 WCAG AA)
48
+
49
+ 前 18 套保持向后兼容,第 18–23 项新增 6 套世界级标杆演示主题(BCG 翡翠战略、经济学人社论简报、红杉日间创投、Stripe 工程工坊、极光舞台、彭博黑曜终端):
50
+
51
+ | ID | 中文名 | English | 明暗 | 画布 `canvas` | 卡片表面 `surface1` | 主文字 `inkPrimary` | 主强调 `accent` | 默认 `chromeStyle` |
52
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- |
53
+ | `swiss` | 瑞士脉冲 | Swiss Pulse | 暗 | `#10151B` | `#161D26` | `#F5F7FA` | `#2F6BFF` | `saas-bento` |
54
+ | `velvet` | 天鹅绒标准 | Velvet Standard | 暗 | `#111316` | `#191C21` | `#F4EFE6` | `#C9A84C` | `editorial-folio` |
55
+ | `data` | 数据漂移 | Data Drift | 暗 | `#070B14` | `#0D1424` | `#E8F1FF` | `#7C3AED` | `saas-bento` |
56
+ | `soft` | 柔和信号 | Soft Signal | 亮 | `#FFF8EC` | `#F6EDE0` | `#3B2F2A` | `#E58A2F` | `saas-bento` |
57
+ | `bold` | 极繁大字 | Maximalist Type | 暗 | `#0D0D0D` | `#16161A` | `#FFFFFF` | `#E63946` | `keynote-spatial` |
58
+ | **`consulting`** | **蔚蓝战略** | **Strategy Navy** | **亮** | `#FFFFFF` | `#F4F6F9` | `#0F172A` | `#0057B8` | `consulting-classic` |
59
+ | **`cobalt-cream`** | **钴蓝简报** | **Blue Professional** | **亮** | `#FDFAE7` | `#F3F1E8` | `#111111` | `#1E2BFA` | `consulting-classic` |
60
+ | **`exec-jilan`** | **霁蓝政务** | **Imperial Slate** | **亮\*** | `#F7F6F2` | `#EFECE6` | `#16243E` | `#1A2B4C` | `gov-ceremonial` |
61
+ | **`exec-palace`** | **故宫丹宸** | **Palace Vermilion** | **亮\*** | `#F9F6F1` | `#F1ECE3` | `#231916` | `#9E1B1E` | `gov-ceremonial` |
62
+ | **`academic`** | **清澄学术** | **ETH & Nature** | **亮** | `#FFFFFF` | `#F5F7FA` | `#111827` | `#006980` | `academic-minimal` |
63
+ | **`editorial-forest`** | **森系社论** | **Editorial Forest** | **亮** | `#F4EFE4` | `#EAE2D3` | `#1A1A17` | `#2E4A2A` | `editorial-folio` |
64
+ | **`cartesian`** | **暖石极简** | **Cartesian Stone** | **亮** | `#F5F1EB` | `#EAE4DB` | `#1A1A1A` | `#734B2F` | `editorial-folio` |
65
+ | **`course-sage`** | **知行讲义** | **Workshop Sage** | **亮** | `#FAFBF9` | `#F0F4F1` | `#182420` | `#0F6E56` | `academic-minimal` |
66
+ | **`linear-dark`** | **黑曜石路演** | **Obsidian Keynote** | **暗** | `#090B10` | `#11151F` | `#F3F6FC` | `#5E81F4` | `saas-bento` |
67
+ | **`keynote-light`** | **苹果极简白** | **Keynote Spatial Light** | **亮** | `#FFFFFF` | `#F5F5F7` | `#1D1D1F` | `#0066CC` | `keynote-spatial` |
68
+ | **`financial-ft`** | **金融时报粉** | **FT Salmon Financial** | **亮** | `#FFF1E5` | `#F6E3D2` | `#1A1817` | `#0D3D56` | `consulting-classic` |
69
+ | **`medical-clean`** | **循证医学蓝绿** | **Clinical Evidence Teal** | **亮** | `#F8FAFC` | `#EEF5F7` | `#0F172A` | `#0F766E` | `academic-minimal` |
70
+ | **`luxury-noir`** | **黑金典藏** | **Luxury Noir Gold** | **暗** | `#0B0B0D` | `#151519` | `#F5F2EB` | `#D4AF37` | `editorial-folio` |
71
+ | **`bcg-emerald`** | **翡翠战略** | **Emerald Strategy** | **亮** | `#FFFFFF` | `#F1F7F4` | `#0D1F18` | `#006B54` | `consulting-classic` |
72
+ | **`economist-brief`** | **经济学人简报** | **Economist Crimson** | **亮** | `#FBF9F5` | `#F3EEE6` | `#161616` | `#C8102E` | `editorial-folio` |
73
+ | **`venture-daylight`** | **红杉创投简报** | **Venture Memo Light** | **亮** | `#FCFCFA` | `#F4F3EE` | `#141413` | `#155EEF` | `saas-bento` |
74
+ | **`stripe-craft`** | **云靛工坊** | **Indigo Craft** | **亮** | `#F8FAFC` | `#EEF2F8` | `#0A2540` | `#533AFD` | `saas-bento` |
75
+ | **`aurora-stage`** | **极光发布会** | **Aurora Keynote** | **暗** | `#070C12` | `#0E1621` | `#F0F6FC` | `#10B981` | `keynote-spatial` |
76
+ | **`obsidian-amber`** | **黑曜终端** | **Terminal Amber** | **暗** | `#0C0D10` | `#15171D` | `#F4F4F5` | `#F59E0B` | `consulting-classic` |
77
+
78
+ > **政务汇报反土味铁律(`exec-jilan` & `exec-palace`)**:彻底告别 `#FF0000` 刺眼荧光红满屏底色与 `#FFFF00` 土味黄字!两套东方政务主题均采用 `coverMode: 'inverted-accent'`——仅封面/章节过渡页使用深邃霁蓝(`#1A2B4C`)或沉淀故宫红(`#9E1B1E`)配描金细线镇场,**90% 的正文与数据页回归宣纸暖白浅底(`#F7F6F2` / `#F9F6F1`)**,既符合正式站位又确保会议室投影清晰锐利。
79
+
80
+ ---
81
+
82
+ ## 三、18 语义设计 Token 规范(`theme.tokens`)
83
+
84
+ 引擎内部不再只用 6 个扁平色值,而是为每套主题及每次 `brand` / `.pptx` 吸收自动求解完整的 18 语义 Token:
85
+
86
+ - **背景与表面层级**:`canvas`(主画布)、`surface1`(一级卡片底衬)、`surface2`(二级嵌套/表头底衬)、`hairline`(`1px` 边框与图表淡网格线,`CR ≈ 1.3:1`,绝不抢戏)。
87
+ - **三级墨色阶梯**:`inkPrimary`(主标题与核心数字,`CR ≥ 10:1` AAA)、`inkSecondary`(正文段落,`CR ≥ 7:1` AAA)、`inkMuted`(页眉面包屑、坐标轴刻度、左下角 `Source:` 脚注,`CR ≥ 4.6:1` AA)、`inkOnAccent`(主色实心块上的反白/深色字)。
88
+ - **双轨强调色(图形 vs 文字分离)**:`accentPrimary` / `accentSecondary` 用于色柱、徽章底衬、几何分割线(对画布 `CR ≥ 3.2:1`);`accentText` / `accent2Text` 专用于小字号标签、Kicker 与行内高亮数字(对卡片表面强制 `CR ≥ 4.6:1` AA,彻底解决浅底橙字或暗底深紫字发虚问题);`accentSoft` 为浅色高亮底衬。
89
+ - **语义状态与出版级图表色**:`positive`(正向增长绿)、`negative`(负向警示红)、`warning`(注意琥珀色);`chartFocal`(图表唯一焦点柱主色)、`chartNeutral`(非焦点对照灰阶柱,践行麦肯锡/经济学人「一主多灰」克制法则)、`chartSeries[6]`(多系列色盲友好高区分度序列)。
90
+
91
+ ---
92
+
93
+ ## 四、跨平台零缺字双语字体规范(HTML ↔ PPTX ↔ LibreOffice)
94
+
95
+ 为杜绝跨操作系统打开 PPTX 或无头 LibreOffice 渲染出现豆腐块(`□□□`)、日文字形误替或 Windows `SimSun`(宋体)大字号发虚锯齿,引擎严格执行分平台原生映射:
96
+
97
+ | 字体角色 `fontRole` | 适用主题 | Windows (`<a:latin>` / `<a:ea>`) | macOS (`<a:latin>` / `<a:ea>`) | Linux (`<a:latin>` / `<a:ea>`) |
98
+ | --- | --- | --- | --- | --- |
99
+ | **`sans`**(现代无衬线) | `consulting, swiss, data, soft, bold, exec-jilan, academic, course-sage, linear-dark` | `Segoe UI` / `Microsoft YaHei` | `Helvetica Neue` / `PingFang SC` | `Liberation Sans` / `Noto Sans CJK SC` |
100
+ | **`geometric-sans`**(几何数字) | `cobalt-cream` | `Segoe UI` / `Microsoft YaHei` | `Avenir Next` / `PingFang SC` | `Liberation Sans` / `Noto Sans CJK SC` |
101
+ | **`editorial-serif`**(仅大标题衬线,正文仍用 Sans) | `velvet, exec-palace, editorial-forest, cartesian` | `Georgia` / `Microsoft YaHei`(Bold,禁用大字号锯齿 `SimSun`) | `Georgia` / `Songti SC` | `Liberation Serif` / `Noto Serif CJK SC` |
6
102
 
7
- ## 速查
8
-
9
- | ID | 中文名 | English | 明暗 | 底色 | 前景 | 主强调 | 次强调 | 情绪 | 适用 |
10
- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
11
- | `data` | 数据漂移 | Data Drift | 暗 | `#070B14` | `#E8F1FF` | `#7C3AED` | `#06B6D4` | 未来/沉浸 | AI、数据、研究、技术发布 |
12
- | `swiss` | 瑞士脉冲 | Swiss Pulse | 暗 | `#10151B` | `#F5F7FA` | `#2F6BFF` | `#FFB300` | 精准/理性 | SaaS、数据、开发者工具 |
13
- | `velvet` | 天鹅绒标准 | Velvet Standard | 暗 | `#111316` | `#F4EFE6` | `#C9A84C` | `#3D4A63` | 高级/克制 | 高管汇报、品牌、融资路演 |
14
- | `soft` | 柔和信号 | Soft Signal | 亮 | `#FFF8EC` | `#3B2F2A` | `#E58A2F` | `#8FAF8C` | 温暖/人本 | 品牌故事、培训、个人分享 |
15
- | `bold` | 极繁大字 | Maximalist Type | 暗 | `#0D0D0D` | `#FFFFFF` | `#E63946` | `#FFD60A` | 大声/动能 | 产品发布、活动、大事件 |
16
-
17
- ## 逐主题说明
18
-
19
- ### data — 数据漂移(默认)
20
-
21
- - 深黑底 + 电光紫 + 青色,细体未来感。
22
- - 适合 AI / ML / 数据 / 前沿技术;大标题少字,用对比数字。
23
- - 反模式:不要加多余暖色;不要堆长段落。
24
-
25
- ### swiss — 瑞士脉冲
26
-
27
- - 黑白灰 + 一个电蓝(或琥珀),栅格感、大数字。
28
- - 适合 SaaS / 指标 / 开发者工具;标题短、要点像 spec。
29
- - 反模式:不要装饰性渐变文字;不要圆角卡片堆叠。
30
-
31
- ### velvet — 天鹅绒标准
32
-
33
- - 黑、米白、香槟金,衬线标题 + 无衬线正文,宽字距,留白多。
34
- - 适合高管汇报 / 品牌 / 融资;节奏慢,页数少而精。
35
- - 反模式:不要动画感强烈的颜色;不要超过一个强调色。
36
-
37
- ### soft — 柔和信号
38
-
39
- - 暖奶油底、深棕字、琥珀 + 鼠尾草绿,亮色唯一浅底主题。
40
- - 适合品牌故事 / 培训 / 个人分享;文字可以更口语。
41
- - 反模式:不要用纯黑正文;不要高饱和撞色。
42
-
43
- ### bold — 极繁大字
44
-
45
- - 黑底、正红 + 明黄,超粗标题,字就是视觉主体。
46
- - 适合产品发布 / 活动 / 大事件;短标题、单页单一冲击。
47
- - 反模式:不要把页面塞满要点;不要让红黄之外再出现第三种强调色。
48
-
49
- ## 选主题决策树
50
-
51
- 1. 情绪是未来/科技 → `data`
52
- 2. 情绪是理性/数据/精准 → `swiss`
53
- 3. 情绪是高级/信任/正式 → `velvet`
54
- 4. 情绪是温暖/人本/故事 → `soft`
55
- 5. 情绪是大音量/发布会 → `bold`
56
-
57
- 无法判断时用 `data`,不要自造主题 ID。
58
-
59
- ## 视觉引擎复用(hyperframes)
60
-
61
- 如果 `hyperframes` 技能已安装,生成前先读它的 `visual-styles.md` / `house-style.md` 作为视觉判断依据;本技能的 5 套主题就是把其中 Swiss Pulse / Velvet Standard / Data Drift / Soft Signal / Maximalist Type 五套风格落成确定性 HTML+PPTX 实现。需要高级动画视频版时,才转用 hyperframes;普通演示不要上视频引擎。
103
+ - **语言标签纯净性**:`lang: 'en'` 生成的 PPTX 仅写入 `lang="en-US"`(不混入 `zh-CN`);`lang: 'zh'` 或 `'bilingual'` 写入 `lang="zh-CN"` 锁定简体中文字形。
104
+ - **等宽数字对齐**:HTML 的 KPI 大数字、表格数值列与图表标签默认启用 `tabular-nums`,避免数字跳动与列错位。
105
+
106
+ ---
107
+
108
+ ## 五、外源 `.pptx` 风格吸收与自动审美净化(`ppt_absorb`)
109
+
110
+ 当用户提供企业 VI 模板、高校答辩模板或过往优秀 `.pptx` 时:
111
+
112
+ 1. 调用 `ppt_absorb { pptxPath: "template.pptx" }`(或在 `ppt_create` / `ppt_edit` 直接传 `referencePptx: "template.pptx"`,工作台亦支持浏览器直接拖拽 `.pptx`)。
113
+ 2. 引擎基于 `@office-kit/pptx` 纯本地解析 `ppt/theme/theme1.xml`(`clrScheme` 12 色槽 + `fontScheme` 西文/东亚字体)、母版背景、内嵌 Logo 与版式留白分布,无需联网、无需调用大模型。
114
+ 3. **`sanitizeAbsorbedTheme()` 自动品味兜底**:
115
+ - 若外部模板母版为高饱和大红/深蓝底(`S > 0.35`),自动将其降级为 `coverMode: 'inverted-accent'`(仅封面深色镇场,内页自动转为柔和浅底),防止全篇红底伤眼。
116
+ - 若外部模板强调色或文字色对比度不足(如白底配 `#FFFF00` 明黄字),自动二分求解亮度并压制荧光饱和度(`S ≤ 0.82`),确保全部 18 个 Token 100% 满足 WCAG AA 可读性标准。
@@ -1,19 +1,24 @@
1
- # dsh-ppt 故障排查
1
+ # dsh-ppt 故障排查与审美修复速查
2
2
 
3
- 只在交付异常时读本文件。
3
+ 只在交付异常、测试告警或画面不符合预期时读取本文件。注意:CLI 与技能层报错信息统一为中文。
4
4
 
5
- | 症状 | 处理 |
5
+ | 症状 / 告警 | 根因与标准处理方式 |
6
6
  | --- | --- |
7
- | `ppt_create` 不存在 | 本插件未安装;用 `node <skill-dir>/scripts/build-deck.mjs` 裸 CLI 生成同样三件套 |
8
- | 未知主题 | `ppt_themes` 或 `--list-themes` 看可用 ID;不要猜 |
9
- | 内容超过 60 页 | 合并论点,或拆成多个 deck;`maxSlides` 默认 60 |
10
- | PPTX 打不开 | 确认文件完整(zip 头 `PK`);Office 首次打开空白版式属正常,编辑视图可用 |
11
- | 双语界面 | `lang: bilingual` 只双语化界面;内容双语由 agent 在写作阶段完成 |
12
- | 放映没有动画 | `motion` 被设为 `off`;默认 `on` 时 HTML 有转场、PPTX 要点逐条点击出现 |
13
- | HTML 打印要点缺失 | 打印样式已强制显示全部要点;若仍缺失检查浏览器是否屏蔽了动画样式 |
14
- | 图片、图表或品牌导出缺少依赖 | 插件重新安装;独立技能目录运行 npm install --ignore-scripts 安装 Office Kit 0.21.0 |
15
- | ppt_render 返回 unavailable | 安装可选官方 Kit 0.2.3(DSH 0.2.2 起内置)或 0.1.5;Windows检查相应VC++v14运行库 |
16
- | 收据 not-verified | 源PPTX或输出发生变化、缺失、版本不同;用当前PPTX重新渲染,不沿用旧结论 |
17
- | 修订号冲突 | 重新用ppt_check读取当前工程,再按新revision编辑 |
18
- | 模板还有待填写 | 补充实际事实/依据/行动;按草稿说明,不作为成品交付 |
19
- | 渲染报告缺失字体 | 替换为环境和目标机器可用字体,重新生成并逐页检查;未解决需标注字体问题,不能声称已验收 |
7
+ | `ppt_create` 等工具不存在 | 当前处于跨 harness 裸技能环境;改用 `node <skill-dir>/scripts/build-deck.mjs` 生成完全一致的 HTML + PPTX + JSON 三件套 |
8
+ | CLI 生成出来默认是黑紫色 `data` 主题 | 裸 CLI 缺省 `--theme` 为兼容旧脚本保留 `data`;**CLI 调用请显式加 `--theme auto` 或具体场景主题(如 `--theme consulting` / `--theme exec-jilan`)** |
9
+ | 会议室/教室投影画面发暗、字迹不清 | 暗底主题在开灯投影下易泛白;用 `ppt_edit` 切换为 12 套浅底主题之一(`consulting`、`exec-jilan`、`academic`、`course-sage`、`cobalt-cream`、`keynote-light`、`financial-ft`、`medical-clean`) |
10
+ | 未知主题报错 | 调 `ppt_themes` 或 `--list-themes` 查看 18 套合法主题 ID(或传 `'auto'`),切勿臆造主题名 |
11
+ | 外部参考 `.pptx` 是刺眼大红底或黄字看不清 | 直接传 `ppt_absorb` 或 `referencePptx`;内置 `sanitizeAbsorbedTheme()` 会自动把高饱和红底降级为庄重深红封面 + 宣纸暖白内页,并将低对比文字钳制到 WCAG AA ≥ 4.6:1 |
12
+ | `ppt_check` 提示 `SLOP-01`(弱标题)或 `SLOP-02`(重复 Kicker) | 将「项目背景 / 数据统计」等名词标签改写为结论判断句(Action Title),并把每页 `kicker` 设为 `01 · 章节名` 面包屑 |
13
+ | `ppt_check` 提示 `SLOP-03` / `SLOP-08`(要点墙 / 版式单一) | 禁止连续 > 2 页 `bullets`;用 `ppt_edit` 将并列指标改为 `kpi`、并列模块改为 `cards`(`pillars/bento`)、对比改为 `comparison`、流程改为 `process` |
14
+ | 学术答辩表格带竖线、像粗糙 Excel 表 | 将表格页设 `tableStyle: "booktabs"`(或选 `academic` 主题),自动输出顶底粗线、表头细线、零竖线的标准学术三线表,数值列自动右对齐 |
15
+ | 图表类别文字重叠或歪斜难读 | 当类别名较长(中文 > 6 字)或类别数 > 7 时,将 `chart.kind` 设为横向条形图 `"bar"`;单系列图表已自动隐藏冗余图例 |
16
+ | 单张图表页显得空旷单薄 | 改用 `layout: "chart-split"`(62% 图表 + 38% 右侧洞察卡片 `items`),并在底部补充一句话 `takeaway` 与左下角 `source` |
17
+ | 内容超过 `maxSlides`(默认 60,硬上限 120) | 提炼合并次要论点,或按章节拆分为多套文稿;单页正文绝不低于 `13.5pt`,超长列表/表格应合理分页 |
18
+ | 图片、图表或 `.pptx` 吸收报缺少依赖 | 在独立技能目录执行 `npm install --ignore-scripts` 安装已声明的 `@office-kit/pptx@0.21.0` |
19
+ | `ppt_render` 返回 `unavailable` | 按需安装可选渲染引擎 `@deepseek-ai/libreoffice-kit@0.2.3`(DSH 0.2.2+ 已内置;0.1.5 亦兼容);Windows 环境确认已安装对应架构 VC++ v14 运行库 |
20
+ | 渲染报告 `missingFonts` 非空 | 将自定义品牌字体替换为跨平台安全字体(Windows `Microsoft YaHei`、macOS `PingFang SC`/`Songti SC`、Linux `Noto Sans CJK SC`),重新生成并复查至 `missingFonts: []`;未解决前必须如实说明,不得声称视觉已验收 |
21
+ | 收据校验为 `not-verified` | 源 PPTX 在渲染后又被编辑或输出图片缺失;对最新 PPTX 重新运行 `ppt_render` 获取新 `renderReceipt`,切勿沿用旧收据 |
22
+ | `expectedRevision` 修订号冲突(409) | 重新调用 `ppt_check` 读取最新 `revision` 与页面结构,再基于最新修订号提交 `ppt_edit` |
23
+ | 外部手工修改过 PPTX 无法直接覆盖 | 为保护用户在 PowerPoint/WPS 中的手工编辑,不可强行覆盖原文件;使用 `saveAs: true` 另存新副本并告知用户手工修改不会自动回导 |
24
+ | 模板仍处于 `deliveryStatus: "draft"` | 当前仅生成了空框架草稿;必须填入材料中的真实事实、数据与可执行行动号召,不得将未填占位的草稿当作正式成品交付 |