frontend-slides/docs/upstream-merge-analysis.md

Fork 与官方上游差异分析

分析时间：2026-07-06 分叉点：8dca834（Merge PR #48） fork 领先 12 commits，官方领先 12 commits

---

核心冲突：架构路线分歧

这是所有冲突的根源。三方对 viewport-base.css 的处理完全不同：

	slide 模型	排版单位	切换方式	导航
基线（分叉点）	100vw × 100vh 响应式	clamp() 流式	scroll-snap	滚动锚点
你的 fork	保持响应式 + 增强	clamp() 流式	scroll-snap	滚动 + 全屏控制器
官方 upstream	重写为 1920×1080 固定舞台	固定 px	visibility/opacity	JS 缩放整个 stage

关键事实：你的 fork 根本没改过根 viewport-base.css（git diff 8dca834 main -- viewport-base.css 为空），而官方把它整个重写了。

这意味着：官方对 viewport-base.css、html-template.md 中架构相关部分、SKILL.md 中 slide 可见性规则的改动，都无法直接合并——它们假设的是固定舞台模型，和你的响应式方案不兼容。

---

官方 12 个提交逐条评估

✅ 建议合并

1. 8728dd7 Refine slide density intake flow — UX 改进

• 改了什么：把 Phase 1 的"内容密度限制表"换成"低密度/高密度"模式选择；把"问题4: 内联编辑"改成"问题4: 密度"；内联编辑改为默认开启（不再前置询问）
• 价值：真实体验改进。密度模式比死板的字数限制表更灵活；内联编辑默认开启符合"先看草稿再决定编辑"的常识
• 冲突：中等。动了 SKILL.md 和 html-template.md，这两个文件你的 fork 也改过（加 allowed-tools、加图表布局等）。需手动合并，不能直接 cherry-pick
• 建议：值得手动合并。把密度模式表和问题4替换、内联编辑默认开启的逻辑搬过来

2. Scripts 符号链接 → 真实文件 — 安装兼容性修复

• 改了什么：plugins/.../scripts/ 下的 deploy.sh/export-pdf.sh/extract-pptx.py 从符号链接（mode 120000）改成真实文件
• 价值：你的 fork 这里还是符号链接，指向 ../../../../../scripts/。通过 Claude 插件市场安装时，符号链接会断（只拷贝 plugin 目录，没有上层 repo 结构）
• 冲突：无。根目录 scripts/ 内容双方完全一致（行数、内容都相同）

• 建议：直接合并。把根 scripts 复制到 plugins/scripts/ 替换符号链接即可：

  cd plugins/frontend-slides/skills/frontend-slides/scripts/
  rm deploy.sh export-pdf.sh extract-pptx.py
  cp ../../../../../scripts/{deploy.sh,export-pdf.sh,extract-pptx.py} .
  

3. a43b418 Add bold template pack — 大特性

• 改了什么：新增 bold-template-pack/，含 28 个设计模板（每个有 design.md + preview.md）、deck-stage.js（舞台缩放引擎）、selection-index.json（模板索引）
• 价值：大量现成设计配方，用户可选模板快速生成
• 冲突：低（大部分是新文件）。但 deck-stage.js 依赖固定舞台架构（1920×1080 缩放），你的响应式方案下它不能直接用
• 建议：有条件合并。design.md 是设计配方（字体/配色/布局语法），与架构无关，可以搬过来用。deck-stage.js 如果继续用响应式则跳过；如果将来转固定舞台再启用

4. 871ce4d Fix YAML front matter errors — 配套修复

• 改了什么：给 12 个模板 design.md 的 description 字段加引号（值里有冒号会破坏 YAML 解析）
• 价值：纯修复，无副作用
• 建议：和 #3 一起合并

---

⏭️ 不建议合并（不适用 / 架构冲突）

5. 7f32a26 Fix slide visibility switching — 架构专属

• 改了什么：slide 切换从 display:none/block 改成 visibility/opacity/pointer-events，因为后写的 .slide-content { display:flex } 会覆盖 display:none 导致所有 slide 同时可见
• 为什么不合并：你的 fork 没有这个 bug。你用的是 scroll-snap 响应式，slide 始终 display:flex，靠滚动定位，不存在 display 切换被覆盖的问题。这个修复是官方固定舞台架构的配套改动
• 建议：跳过

6. viewport-base.css / html-template.md 架构重写

• 官方把 .slide 从 100vw/100vh 改成 position:absolute; width:1920px; height:1080px，排版从 clamp() 改成固定 px，加了 .deck-viewport/.deck-stage 容器
• 与你的响应式方案根本冲突，合并等于推翻你的整个路线
• 建议：跳过（除非决定整体迁移到固定舞台——那是另一个大决策）

---

🟡 可选（低优先级，按需）

7. 24e420e Bump plugin version to 2.1.0

• plugin.json 版本号 2.0.0 → 2.1.0。你的 fork 已改过 plugin.json（指向 MageByte-Zero），手动把版本号改成 2.1.0 即可

8. fb5b037 Make frontend slides skill agent-neutral

• 让 skill 支持 Codex/Kimi/Gemini CLI 等非 Claude agent。改了 README 和 SKILL.md 措辞
• 你的 fork 是个人 Claude 专用，价值不大。如果在意多 agent 兼容可以搬 README 部分

9-15. 七个 README 文档提交

提交	内容	价值
9366f62	文档 Claude 插件命令命名空间	低
f8d1b32	澄清自定义市场安装步骤	低
5e958f3	移除市场审批措辞	低
96888b4	澄清独立安装步骤	低
161453f	澄清非 Claude agent 用法	低
c286901	补全 Architecture 表截断描述	低
9906a34	README 加新手教程视频	中（有视频链接）

都是 README 改动，零冲突。你的 fork 的 README 已改成指向自己的仓库，按需挑选即可

---

你的 fork 已有而官方没有的（不要丢）

这些是你 fork 的独有价值，合并时务必保留：

提交	内容
a658018	allowed-tools frontmatter（修复新版 Claude Code 的 AskUserQuestion）
79abc3f	overflow:hidden 防滚动条 + 1600px 投影仪/4K 断点
17ca960	修正 1600px 断点注释
847aef5	异步非阻塞字体加载（media=print onload 技巧）
34251e9	安全的 bullet hanging-indent 模式
cdedb0f	修复内联编辑 Enter/粘贴时字体损坏
6f4b428	FullscreenController（F 键 + 按钮）
863b8a8 + d4566b7	图表 CSS 布局模式（循环/流水线/层级/枢纽）

---

建议的合并操作顺序

1. Scripts 真实文件（零风险，立即做）
2. 版本号 2.1.0（一行改动）
3. 8728dd7 密度模式（手动合并 SKILL.md + html-template.md，保留你的 allowed-tools）
4. Bold template pack 的 design.md/preview.md（搬设计配方，跳过 deck-stage.js）
5. 871ce4d YAML 修复（配合 #4）
6. README 按需挑选