项目定位与目标

presentation-md 是一个面向 AI 编程助手生态的演示文稿制作工具套件，目标是让用户通过 Markdown 文件结合技能包 (skill) 的方式生成、渲染并导出幻灯片。仓库以多适配器 (adapters) 形式分发，针对不同 AI IDE 客户端加载对应的文档与安装入口。资料来源：README.md。

最新发布版本为 @presentation-md/[email protected]，同时升级了 @presentation-md/[email protected] 与 @presentation-md/[email protected]。这表明系统采用 monorepo 分包发布策略，由 core（核心能力）、render（版式工艺与渲染）、export（导出器）三个 npm 包共同组成渲染管线。资料来源：README.md。

核心功能与版式工艺

render 包在 1.1.0 版本引入了一组制作工艺：

• 新增 code 版式，专门适配代码片段展示场景
• 支持非对称双栏 (two-column)、对比 (comparison)、便当 (bento) 等版式手法
• 提供 preview_themes 多版式预览模式，便于一次性比对多种主题

这套工艺组合让开发者可以直接从 Markdown 产出风格统一、版式多样的网页幻灯片，而不再受限于单一的居中标题/正文结构。资料来源：README.md。

适配器生态

仓库通过 adapters/ 目录对接各类 AI 编程客户端，每个适配器都自带独立的 README，说明安装方式、触发命令以及与该客户端文件系统的对接方式：

资料来源：adapters/claude-code/README.md ; adapters/cli/README.md ; adapters/codex/README.md ; adapters/copilot/README.md ; adapters/cursor/README.md。

社区讨论指出（Issue #9），README 已将 deck-design-judge 列为仓库自带的 skill，但默认安装命令仍只解析 @presentation-skill-pack/core/skill，缺少将 deck-design-judge 一并纳入安装管道的逻辑。这反映出当前适配器与技能注册之间的耦合尚需补齐，是后续需要关注的方向。资料来源：adapters/claude-code/README.md ; README.md。

已知限制与发展方向

渲染脚本侧存在一个待修复问题（Issue #8）：skills/deck-design-judge/scripts/render_slides.sh:45 在按页截图时，往 URL 追加 fragment 并不能让 headless Chrome 视口跟随滚动。当演示文稿自身没有实现 #__shot=N 哈希监听器时，截图结果会出现错位。这是 render 流程中的一个真实缺陷，建议在编写自定义 deck 时显式实现相应的 hash 监听逻辑。资料来源：skills/deck-design-judge/scripts/render_slides.sh:45。

小结

presentation-md 以 Markdown 为输入、以 @presentation-md/core 为内核、以 @presentation-md/render 为版式工艺集、以 @presentation-md/export 为导出器，配合多适配器分发到主流 AI 编程客户端。开发者当前重点关注的方向包括：扩展 deck-design-judge skill 的安装覆盖（Issue #9）、修复 render_slides.sh 中视口截图的滚动逻辑（Issue #8），以及通过 1.1.0 引入的非对称双栏 / 对比 / 便当等新工艺来丰富幻灯片视觉表达。资料来源：README.md。

概述

packages/studio/src/ 是 presentation-md 仓库中 Studio 前端应用的源码根目录。该模块基于 React + TypeScript 构建，承担可视化编辑器的全部交互职责——包括幻灯片表单编辑、AI 一键生成大纲、实时预览以及全屏演示。它与同仓库内的 @presentation-md/core、@presentation-md/render、@presentation-md/export 三个包协同工作，构成从"原始数据 → 渲染预览 → 导出发布"的完整链路。

资料来源：packages/studio/src/App.tsx:1-40

模块组成与职责

src/ 主要由三类文件组成：根组件入口、AI 生成层、UI 组件层。

根组件入口：`App.tsx`

App.tsx 是 Studio 的顶层容器，负责编排路由、全局状态（decks/slides）以及子组件的挂载顺序，所有子视图（表单、预览、演示、生成弹窗）都受其状态控制。

资料来源：packages/studio/src/App.tsx:1-120

AI 生成层：`ai/generate.ts`

ai/generate.ts 把大模型调用封装为单一函数，向其传入主题、语气、要点等参数，返回符合核心数据契约的幻灯片 JSON 数组。该模块是 GenerateModal 与外部 LLM 之间的唯一适配层。

资料来源：packages/studio/src/ai/generate.ts:1-80

UI 组件层：`components/`

components/ 子目录聚合了所有面向用户的视图组件，按职责可划分为：

• 编辑侧：SlideForm.tsx 负责单张幻灯片标题、正文、布局（layout）、主题等字段的增删改查。
• 预览侧：Preview.tsx 调用 @presentation-md/render 包在右侧面板即时渲染当前幻灯片，是新布局能力（如 code、asymmetric two-column/bento、preview_themes）的前端承载点。
• 演示侧：PresentMode.tsx 提供全屏演示模式，接管键盘翻页与聚焦交互。
• AI 入口：GenerateModal.tsx 以弹窗形式收集生成参数，调用 ai/generate.ts 并把结果回填到 App.tsx 持有的状态中。

资料来源：

• packages/studio/src/components/SlideForm.tsx:1-100
• packages/studio/src/components/Preview.tsx:1-90
• packages/studio/src/components/PresentMode.tsx:1-90
• packages/studio/src/components/GenerateModal.tsx:1-60

数据流与运行时协作

四个主要组件围绕 App.tsx 持有的统一状态形成单向数据流：编辑表单或 AI 生成写入状态，预览与演示从状态读取并渲染。

flowchart LR
    SF[SlideForm<br/>手动编辑] --> ST[App 状态<br/>decks/slides]
    GM[GenerateModal<br/>AI 弹窗] --> ST
    GM -->|调用| AI[ai/generate.ts]
    AI -->|回填 JSON| ST
    ST --> PV[Preview<br/>实时渲染]
    ST --> PM[PresentMode<br/>全屏演示]

用户在 SlideForm 手动维护幻灯片，或在 GenerateModal 通过 ai/generate.ts 一键生成；两者最终汇入 App.tsx 的同一份状态，再分别供给 Preview 与 PresentMode 进行渲染与播放。

资料来源：packages/studio/src/App.tsx:40-160

与发布版本及社区反馈的关联

发布版本带来的能力

最新发布的 @presentation-md/[email protected] 新增了 code 布局、非对称双列/对比/bento 工艺以及 preview_themes 多布局模式。这些新增能力会在 Preview.tsx 加载渲染包时即时生效，使 Studio 的预览面板成为用户最先感知版本升级的位置。

资料来源：packages/studio/src/components/Preview.tsx:20-80

安装管线相关讨论

社区反馈指出，README 中已声明仓库携带 deck-design-judge 这项 skill，但 npx @presentation-skill-pack/install claude-code 这条一键安装命令目前只解析 @presentation-skill-pack/core/skill，其 files 列表未包含 deck-design-judge。该问题涉及安装管线，与 src/ 模块的运行时代码无直接耦合，但若未来 Studio 增加"内置评审"开关，则需在 GenerateModal 或 Preview 侧补齐调用入口。

资料来源：README.md:40-60

已知截图缺陷（跨模块）

skills/deck-design-judge/scripts/render_slides.sh 中存在一个已知问题：当目标 deck 未实现 #__shot=N 哈希监听器时，向 URL 追加 fragment 并不能驱动 headless-Chrome 视口下移，从而导致逐页截图错位。该缺陷不在 src/ 模块内，但与 Preview 在演示模式下的真实视口表现相关，是后续接入视觉回归时需要协同修复的点。

资料来源：skills/deck-design-judge/scripts/render_slides.sh:40-50

Pitfall Log / 踩坑日志

项目：isatimur/presentation-md

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Wire deck-design-judge into the npx install pipeline。

1. 安装坑 · 来源证据：Wire deck-design-judge into the npx install pipeline

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Wire deck-design-judge into the npx install pipeline
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/isatimur/presentation-md/issues/9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/isatimur/presentation-md | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli, chatgpt

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/isatimur/presentation-md | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/isatimur/presentation-md | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/isatimur/presentation-md | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/isatimur/presentation-md | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：render_slides.sh: per-slide screenshot fragment-scroll doesn't move the viewport

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：render_slides.sh: per-slide screenshot fragment-scroll doesn't move the viewport
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/isatimur/presentation-md/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/isatimur/presentation-md | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/isatimur/presentation-md | release_recency=unknown