seaslides-typst-slides-skill

SeaSlides Typst 幻灯片技能

将源材料转换为已编译的 Touying/Typst 演示文稿，并根据用户意图匹配审查深度。

完整流程：Source -> Project -> Theme -> Strategist -> [Images] -> Executor -> Compile -> Review -> Export

快速流程：Source -> Project -> Existing Theme -> Author -> Compile -> [Review] -> Export

目录

• 硬性约定
• 模式路由
• 场景路由
• 资源地图
• 完整模式工作流
• 编辑现有幻灯片
• 依赖项

硬性约定

1. 按顺序执行所选模式的各个阶段。完成每个关卡后，才能进入下一阶段。
2. 在阻塞关卡处询问用户必须作出的决定。无人值守模式下，自行决定并继续。
3. 在规划幻灯片之前，先将 PDF、DOCX、PPTX、电子表格和网页来源转换为 Markdown。
4. 将内容与主题相关事项分开处理。在 Plain/Rich 模式下，不要在 main.typ 中随意添加视觉样式。
5. 对于项目自有主题和自定义主题，请严格按以下方式导入 Touying： #import "@preview/touying:0.7.4": *。第三方 Universe 主题可能依赖较旧的 Touying 传递版本；请使用该包文档所述的 API，绝不要添加冲突的直接导入，也不要编辑包缓存。
6. 编译、运行机械质量检查并验证后再交付。根据用户的要求匹配视觉审查深度；用户明确选择不进行视觉审查时，跳过视觉检查，并说明输出未经视觉审查。
7. 缺少 output/slides.pdf 和 output/overview.png 的项目均视为未完成。
8. 每张幻灯片都要添加 #speaker-note[...]。
9. 在快速模式下，仅按 ${SKILL_DIR}/workflows/quick-mode.md 中的定义，省略独立的设计规范和角色参考；规则 3-8 仍然适用。
10. 启动时以及每次阶段转换时，都要用用户使用的语言简要告知模式、当前阶段和要执行的操作。遇到阻塞事项或静默约一分钟后，也要更新进度；不要逐条播报命令。
11. 原地复用现有编辑器或用户工作区。绝不要在其中运行项目初始化，并在每个编译、审计和验证步骤中传入当前工作区内的 Typst 入口文件路径。

请将 ${SKILL_DIR}/references/shared-standards.md 用作 Typst/Touying 约定和反模式的权威参考。

模式路由

当用户明确优先考虑速度、要求先提供可用初稿或接受合理默认值时，使用快速模式。遵循 ${SKILL_DIR}/workflows/quick-mode.md。

标准流程使用完整模式；当任务需要新建或大幅扩展主题、获取新图片、进行大量研究或资料搜集、制定正式设计规范、校准复杂图表，或继续执行长篇幻灯片的中断阶段时，也使用完整模式。

快速模式是一种工作流选择，而 Plain、Rich 和 Canvas 是主题复杂度层级。若 Rich 或 Plain 同样适用且编写更快，应优先选择。若所选现有主题的 theme.md 和 demo.typ 已提供清晰且可编译的路径，仍可选择 Canvas。在任一模式下，都要遵从用户指定、脚手架已搭建或现有的主题。

在快速模式下，无需额外设置决策关卡即可推断视觉审查深度：尊重用户明确提出的不审查要求；普通快速初稿采用针对性审查；用户要求确保视觉效果或进行交付级审查时，则检查每一页。

场景路由

进入标准幻灯片流程前，先处理特殊输出：

意图	阅读并遵循
学术或会议海报	${SKILL_DIR}/references/scenarios/poster.md
CV 或简历	${SKILL_DIR}/references/scenarios/cv.md
社交媒体封面、文章标题图或缩略图	${SKILL_DIR}/references/scenarios/social-cover.md
标准演示文稿或幻灯片	继续阅读下文

使用与用户相同的语言。在 content_design_spec.md 中使用英文小节标题；适当时，字段值使用用户的语言。

对于 25 张或更多幻灯片的 Rich/Canvas 演示文稿，使用 ${SKILL_DIR}/workflows/resume-execute.md，将规划和执行拆分到多个会话中。

资源索引

仅在进入相关阶段时加载参考资料。

工作流路由

任务	资源
完整创作工作流	${SKILL_DIR}/workflows/create-presentation.md
快速创作工作流	${SKILL_DIR}/workflows/quick-mode.md
主题选择	${SKILL_DIR}/workflows/select-theme.md
创建新主题	${SKILL_DIR}/workflows/create-template.md
仅研究主题	${SKILL_DIR}/workflows/topic-research.md
长篇演示文稿续做	${SKILL_DIR}/workflows/resume-execute.md
图表校准	${SKILL_DIR}/workflows/verify-charts.md
视觉审查	${SKILL_DIR}/workflows/visual-review.md
音频旁白	${SKILL_DIR}/workflows/generate-audio.md

参考资料权威性

每一行都是对应事项的唯一权威来源。仅在当前阶段需要时加载详细文件。

事项	权威资源	阅读时机
Typst/Touying 语法、TCS、布局安全和硬性规则	${SKILL_DIR}/references/shared-standards.md	规划或编写任何 Typst 输出时
高级表格、数学公式、图标、SVG、阴影和源图像配方	${SKILL_DIR}/references/shared-standards-extended.md	核心标准链接到此处，或需要高级功能时
视觉方向、构图、节奏和审美反模式	${SKILL_DIR}/references/design-guide.md	确定视觉方向，或进行高品质主题/Canvas 工作时
内容策略和 content_design_spec.md	${SKILL_DIR}/references/strategist.md	策略阶段
所有演示文稿样式共用的完整模式执行器工作流	${SKILL_DIR}/references/executors/base.md	加载唯一一个样式执行器之前
主题文件、公共组件 API、演示示例和主题质量门槛	${SKILL_DIR}/references/template-designer.md	创建或实质性扩展主题时
图像获取分流	${SKILL_DIR}/references/image-base.md	设计规范要求提供新图像时
AI 图像生成和渲染风格	${SKILL_DIR}/references/image-generator.md 和 ${SKILL_DIR}/references/image-renderings/_index.md	image-base.md 选择 AI 路径时
授权网络图像搜索和署名	${SKILL_DIR}/references/image-searcher.md	image-base.md 选择网络路径时
图像布局术语	${SKILL_DIR}/references/image-layout-patterns.md	规划或实现图像密集型页面时
渲染后的视觉审查	${SKILL_DIR}/references/visual-review.md	所选审查策略要求检查渲染结果时
视觉问题归属与修正路由	${SKILL_DIR}/references/artifact-ownership.md	确认存在缺陷时

渲染风格的详细信息位于 ${SKILL_DIR}/references/image-renderings/<anchor>.md；加载对应文件前，先使用渲染索引选择一个锚点。可选的受控对比图库记录在 ${SKILL_DIR}/references/ai-image-comparison/README.md 中，并在 ${SKILL_DIR}/references/ai-image-comparison/_index.md 中编入索引。

执行器风格路由

仅在 Full Mode 下应用此路由。读取执行器基础文件，并且只读取一个匹配的风格文件。 复杂度层级和执行器风格是分开决定的；Canvas 使用 Canvas 执行器，而不是同时加载非 Canvas 风格文件。Quick Mode 不加载执行器参考文件。

呈现意图	风格资源
产品、培训、提案、营销或通用演示文稿	${SKILL_DIR}/references/executors/general.md
商务回顾、绩效报告或数据密集型咨询演示文稿	${SKILL_DIR}/references/executors/consultant.md
董事会、投资或 MBB 风格的高管建议	${SKILL_DIR}/references/executors/consultant-top.md
会议演讲、论文答辩、研讨会或研究演示文稿	${SKILL_DIR}/references/executors/academic.md
编辑、瑞士风格、节庆或定制的页面级构图	${SKILL_DIR}/references/executors/canvas.md

学术海报属于场景工作流，不使用学术演示文稿执行器。

资源中心与目录

需求	人类可读的中心	机器可读或直接资源
脚本发现与操作文档	${SKILL_DIR}/scripts/README.md	${SKILL_DIR}/scripts/docs/
模板资源发现	${SKILL_DIR}/templates/README.md	下方各类别索引
主题选择	${SKILL_DIR}/templates/themes/README.md	${SKILL_DIR}/templates/themes/<tier>/index.json
Typst 包	${SKILL_DIR}/templates/packages/README.md	${SKILL_DIR}/templates/packages/index.json
图表与示意图	${SKILL_DIR}/templates/charts/README.md	${SKILL_DIR}/templates/charts/index.json
图标与符号	${SKILL_DIR}/templates/icons/README.md	${SKILL_DIR}/templates/icons/index.json
内容规划架构	—	${SKILL_DIR}/templates/content_design_spec_reference.md
主题设计架构	—	${SKILL_DIR}/templates/theme_design_spec_reference.md
主题 API 摘要架构	—	${SKILL_DIR}/templates/theme_reference.md

请勿在此文件中逐一列出主题、图表、包或图标。请使用其目录，以便 SKILL 随着捆绑资源的变化保持稳定。

Full Mode 工作流

Full Mode 请使用以下步骤。Quick Mode 遵循其独立工作流；应用 Quick Mode 自有的审查政策，同时复用下方的编译、质量检查、验证和导出命令。

步骤 1：处理来源

关卡：已有源材料或主题。

如果只提供了主题，请遵循 ${SKILL_DIR}/workflows/topic-research.md 或先生成来源简报，再继续。

输入	命令
PDF	python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file> --images filtered
DOCX / EPUB / HTML / LaTeX / RST	python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>
PPTX / PPSX	python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>
Excel	python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>
网页	python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <url>
Markdown / 文本	直接读取

如果有可用的转换器，请勿仅凭尚未读取的原始文档继续。

步骤 2：解析工作区

门槛：存在可读取的源内容。

当用户或宿主编辑器已提供工作区时，就地附加：

python3 ${SKILL_DIR}/scripts/project_manager.py workspace <workspace_path> \
  --entry <workspace-relative-entry.typ> --prepare

这只会创建缺失的 assets/、output/ 和 sources/ 支持目录，不会创建子项目、README 或替代条目。保留返回的条目路径，并在下方将其传给 --entry。如果 Tylina 等宿主通过可信工具提供了工作区和主文件状态，请使用该状态，而不要猜测文件名。

仅当不存在工作区时，才初始化新的独立项目：

python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name>
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --copy

仅在需要确定性且不包含日期的目录名时（例如，可复现基准测试）使用 --exact-name；普通项目保留带日期的后缀。

仅当用户明确要求移动源文件时才使用 --move。将提取的源图像复制到 <project_path>/assets/，并导入转换后的 Markdown。

步骤 3：选择或创建主题

门槛：项目目录已存在。

遵循 ${SKILL_DIR}/workflows/select-theme.md。

1. 直接使用用户指定的主题。
2. 否则，检查主题分派规则和相关目录，再根据内容、受众和交付场景匹配主题元数据。
3. 用户要求克制或极简的输出时，使用 Plain。Rich 是可靠的默认选项。
4. 仅当定制排版能显著改善效果，且执行者能够正确处理 Typst 内容／代码模式、主题 API 和编译探测时，才使用 Canvas。有任何不确定时，改用 Rich。
5. 仅当现有主题库不适合内容，且任务有足够时间完成实现和视觉审查时，才创建新主题。

选择后：

python3 ${SKILL_DIR}/scripts/project_manager.py copy-theme <project_path> <name>

阅读复制后的 theme.md 和 demo.typ。对于 Canvas 任务，也要阅读 template.typ。使用文档中说明的 API 和结构模式；如果装饰细节无助于内容表达，不要机械模仿。

步骤 4：制定内容设计规范

门槛：主题已选定并了解。

阅读：

${SKILL_DIR}/references/strategist.md
${SKILL_DIR}/references/shared-standards.md

将九项决策作为一个整体呈现，并等待回复，除非启用了无人值守模式：

1. 页面格式
2. 页数范围
3. 目标受众
4. 风格目标
5. 复杂度
6. 配色方案
7. 字体排版方案
8. 图像方案
9. 第三方软件包

从 ${SKILL_DIR}/templates/packages/index.json 中选择软件包。常见选择包括：用于 LaTeX 数学公式的 mitex、用于标准图表的 lilaq、用于分层 Grammar-of-Graphics 绘图的 gribouille、用于可选代码样式的 codly、用于伪代码的 lovelace、用于清单的 cheq，以及用于 Mermaid 图表的 merman。

如果存在用户图像，请运行：

python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/assets

使用提供的模板编写 <project_path>/content_design_spec.md。其中应包含项目设置、具体主题、软件包、叙事结构、逐页大纲、图像决策、颜色和字体排版方案。说明有意排除的素材为何未使用。

步骤 5：按需获取图像

门槛：设计规范要求生成或搜索图像。

阅读 ${SKILL_DIR}/references/image-base.md，然后阅读选定的图像工作流。

python3 ${SKILL_DIR}/scripts/image_gen.py --check-available

生成素材清单或提示词文件，创建或搜索图像，并确认 assets/ 中存在所需文件。如果设计规范不需要新图像，则跳过此阶段。

Step 6：编写演示文稿

门槛：设计规范和所需素材已准备就绪。

阅读执行器基础说明、恰好一个风格执行器、共享标准，以及仅在选择 Canvas 时阅读 Canvas 指南。

编写 main.typ 前，重新阅读已复制的 theme.md、demo.typ 和 content_design_spec.md。

编写时遵守以下约束：

• 在主题组件和布局能清晰表达内容时优先使用；重复的对比页面可以有意采用相同布局。
• 对于渲染组件参数，优先使用 Typst 内容块：写成 #card[Title][Body]（或 #card(accent: palette.accent)[Title][Body]），而不是将面向用户的文案作为 "Title" 传入。对于路径、URL、枚举／配置键、字体名称等确实应为字符串的数据，以及需要进行字符串操作的值，仍使用字符串。
• 常规多栏排版使用 #cols[...] [...]。只有在主题的 theme.md 明确要求时，才使用其他主题专属的组合器。
• 在调用层级，按自然顺序直接组合完整组件。不要仅为常规留白而添加固定的 v()，也不要用 stack() 包裹相邻组件；只有在元素构成有意设计的单一视觉分组时，才使用 stack(spacing:)。
• 不要在 Plain/Rich 的 main.typ 中随意使用 rgb() 和 block(fill:) 样式；如果缺少可复用的视觉模式，请扩展 template.typ。
• 使用所有相关或用户要求的素材。不要仅因图片存在就插入无关图片；在设计规范中记录未使用的素材。
• 统计页数时，将标题页、分隔页、主视觉页、重点页和附录页计入用户要求的范围。
• 不要让源码／调试文本、TODO、未解析的组件调用和诊断信息出现在渲染后的幻灯片中。
• 为每张幻灯片添加有意义的演讲者备注。

布局多样性、组件多样性和节奏应根据内容作为设计启发，而非数值配额。当叙事需要呈现对比或顺序时，应优先采用连贯的重复结构，而不是任意变化。

Step 7：编译、审阅、验证并导出

门槛：template.typ 和 main.typ 均已存在。

按顺序运行各子步骤。任何源码变更后，都要重新编译。

7.1 编译

python3 ${SKILL_DIR}/scripts/typst_compiler.py <project_path> --all --entry <entry.typ>

确保生成 output/slides.pdf、每页对应的 PNG、output/overview.png，以及仅在完整的 --all 序列成功后写入的连贯 output/compile-manifest.json 收据。若失败，请诊断并重试，最多五次。

7.2 运行机械质量检查

python3 ${SKILL_DIR}/scripts/typst_quality_checker.py <project_path> --entry <entry.typ>

默认门槛会在出现 blocker 诊断时判定失败。将编译错误、缺失的输出／资源、内容溢出、布局未收敛以及明确的预期页数不匹配视为阻断问题。字体回退和未分类编译器警告等 review 诊断需要检查源码和渲染结果；它们不会自动导致视觉检查失败。Touying 仅针对流式布局发出的 EMPTY_SLIDE 信号属于提示，因为即使页面内容清晰可见，基于放置位置的页面也会触发该信号。视觉审阅启用时，请检查相关 PNG；如果用户选择不进行视觉审阅，则应披露尚未解决的提示，不要声称已通过视觉审阅。已知页数预期时，使用 --expected-pages N；需要机器可读的审计收据时，使用 --json <receipt.json>。

7.3 在已选择时进行视觉审阅

按照 ${SKILL_DIR}/workflows/visual-review.md 中选定的范围进行检查：full 检查概览和每张幻灯片；targeted 仅检查概览／检查器标记的页面；none 跳过渲染检查。启用检查时，使用 ${SKILL_DIR}/references/visual-review.md，修复已确认的问题，并在源码变更后重新编译，最多迭代三次。

结合具体情境评估主题还原度和视觉多样性。不要仅为满足固定布局数量而重新设计清晰的重复序列。

选择 none 时，交付时应说明演示文稿已编译并通过机械检查，但未经视觉审阅。始终分别报告审阅范围和结果。

7.4 验证

python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --entry <entry.typ>
# Quick Mode only:
python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --mode quick --entry <entry.typ>

完成前修复报告中的错误。

7.5 导出

PDF 已生成于 output/slides.pdf。选定的审核策略完成或明确跳过后，如有需要，请导出 PPTX：

python3 ${SKILL_DIR}/scripts/typst_compiler.py <project_path> --format pptx

步骤 8：按需生成音频

仅在幻灯片输出稳定后，才按照 ${SKILL_DIR}/workflows/generate-audio.md 操作。

编辑现有演示文稿

1. 找到并阅读 main.typ、template.typ、主题文档以及当前渲染输出。
2. 修改内容时编辑 main.typ；修改可复用样式时编辑 template.typ。
3. 重新编译，应用选定的视觉审核策略，完成验证并重新导出。
4. 只有在所请求的更改会影响叙事、主题或演示文稿结构时，才重新运行规划。

依赖项

pip install -r ${SKILL_DIR}/requirements.txt

如果可使用 uv，优先使用由调用方应用或用户管理的隔离环境。 不要安装到系统 Python 中，也不要修改 shell 启动文件。由宿主管理的运行时应通过其稳定的工具接口调用这些脚本，而不是让 Agent 自行查找或安装 uv。

使用 typst watch <project_path>/main.typ 进行本地预览，但交付前仍须运行项目编译器和验证流程。