sn-ppt-entryUse when a user asks to create a presentation, slide deck, PPT, or PPTX from a query and optional files, or to resume an existing SenseNova presentation task.
Independent GitHub snapshot · Automated classification · Original documentation governs
name: sn-ppt-entry description: Use when a user asks to create a presentation, slide deck, PPT, or PPTX from a query and optional files, or to resume an existing SenseNova presentation task. metadata: allow_override: false project: SenseNova-Skills tier: 1 category: scene user_visible: false triggers:
执行前，必须已有用户明确要求设计模式或无冲突的动态演示，或公共 pptx 入口已收到
presentation_mode 选择卡的 design 回复（用户点击或宿主超时均可）。
若只是模型推荐了设计模式，先返回 get_skill(skill_name="pptx") 完成模式选择，
不要建立任务目录、写任务包或开始研究。加载本 Skill 本身不表示模式已经确认。
已确认模式的同一任务续作不重复选择。
统一接收 PPT 生成请求，建立唯一任务目录，准备材料。Standard 先完成定向外部证据补充，
Deep 先完成完整 Research，下一步必须调用 sn-ppt-story 生成公共 outline.md，再按 choices.output 分发到 sn-ppt-standard 或 sn-ppt-dazzle。
这是一套 Skill 的入口，不是独立运行时。文本理解、视觉理解和推理使用宿主 Agent
已有能力。普通搜索、图片搜索和图片生成优先使用宿主原生工具；原生能力不存在或实际
调用不可用时，才使用 PPT 整包自带的 sn-ppt-tools。不得要求用户另外配置模型客户端，
不得调用 model_client.py、stage.py 或为本流程再造 CLI 调度层。
渲染复用宿主已提供的 Playwright。宿主设置 BOX_AGENT_PLAYWRIGHT_MODULE_PATH 时，
Node 脚本必须加载该绝对模块路径，并把 BOX_AGENT_PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
传给 chromium.launch 的 executablePath。优先调用整包正式渲染脚本，不另装 SDK 或
浏览器，不用裸 require('playwright') 选择工作区中的旧副本。宿主文件缺失时报告客户端修复，
不要改用其他浏览器版本继续。
在 Box-Agent 中，从本次加载的 Skill 提示取得 Entry 的绝对 Skill Root，记为
<ENTRY_SKILL_ROOT>。Entry 的所有确定性脚本都必须使用
python "<ENTRY_SKILL_ROOT>/scripts/<name>.py" 调用；禁止使用 $SKILL_DIR、当前工作目录
或相对的 skills/ 路径。所有任务产物仍必须写入同一个绝对 $DECK_DIR，并在调用 Story
和出口 Skill 时逐字复用该路径。
draft：尽快形成可看的方向稿。默认不做外部事实搜索，大纲完成后直接生产。standard：质量和等待时间平衡。Story 前由 Entry 做定向外部搜索和证据补充，不运行
完整 sn-deep-research；生成前让用户看 outline.md。deep：先确认外部 sn-deep-research 可用，再完成研究和正式 outline.md；生成前让用户确认。该外部 Skill 未随本套件提供，不可用时说明并让用户选择 Draft 或 Standard，保留已有产物。Entry 根据任务复杂度、事实时效性、材料完整度和用户措辞推荐一档，同时展示 Draft / Standard / Deep。用户可以覆盖；用户未覆盖时采用推荐，不为这个选择增加一轮 阻塞问答。
本套件是公共 pptx 入口下的设计模式，保留两个表达出口：
static_html -> sn-ppt-standard：静态 PPT 页面，始终交付整册 present.html，默认另交付 .pptx。dynamic_html -> sn-ppt-dazzle：带动效和翻页交互的 deck.html；不承诺保留动画的 PPTX。对外描述 PPTX 文件交付，不宣传或承诺可编辑、原位编辑能力。
用户未明确要求动态时采用 static_html；只要 HTML 时关闭对应 PPTX 后处理。
已有 PPTX 的原位编辑、模板填充与已选设计模式冲突时，保留原始需求、附件和交付格式，
先向用户澄清是否改用快速模式；只有用户明确同意后才加载 ppt-fast，不得自动切换。
已有 SN HTML 任务继续使用其任务目录与输出选择。
restrained（克制）：政企、学术、法务、财务或明确要求简洁。rich（丰富）：默认，适合多数业务汇报、产品介绍和正式演示。high_creative（高创意）：发布会、品牌传播、创意提案或明确要求强视觉。用户明确指定时直接采用；否则结合场景、受众、输出格式和措辞推荐。显示当前选择与
三档名称，但不单独阻塞。用户在生成前、确认大纲时或后续修改中覆盖时，更新同一份
task_pack.json。丰富度只决定视觉投入，不改变事实标准和 Story 遵循要求。
新任务的输出位置沿用已经验证稳定的原 Entry 规则，不得重新推断：
pwd -P，把该命令实际返回的完整绝对路径逐字记为 workspace_root。宿主显示的
session workspace、repo 根或其他路径标签都不能替代这次 pwd -P 的结果；尤其不得自行
删除返回路径末尾的 output、workspace 等目录名。<workspace_root>/ppt_decks/。<topic_concise>_<YYYYMMDD_HHMMSS>。pwd -P/绝对化结果回显 deck_dir，立即写入
task_pack.deck_dir，此后全链路只逐字复用该值，禁止根据框架 workspace 信息重新拼接。/tmp、另一个 workspace 或
PPT_DECK_ROOT。<workspace_root>/ppt_decks/ 时停止并报告权限问题，不换地方继续。Box-Agent 的文件工具相对根通常是 <session_workspace>/output，而会话元数据中的 workspace
可能是它的父目录。两者不是同一路径。创建 task_pack.json、info_pack.json、outline.md
和后续产物时必须全部使用上述同一个 deck_dir；每次文件工具返回的绝对落盘路径都要位于
该目录。若返回路径不一致，立即停止并修正路径，不得在两个 ppt_decks/ 之间继续。JSON 和
Markdown 直接用文件工具写入，不要用 execute_code 内嵌一个重新推导的绝对路径。
已有任务必须复用已有 task_pack.json 中的绝对 deck_dir；继续任务不得新建目录。
所有 Skill 安装目录只读。
上述目录规则适用于持久文件。仅供本轮看图检查的缩略图、裁片等遵循公共 pptx 入口的
“QA 临时文件与收尾”：生成到 $BOX_AGENT_SCRATCH_DIR，交由运行时回收。需保留的
QA 报告、正式预览和交付依赖仍放 deck_dir；未登记的已有 QA 文件保留，交付不要求
清空目录，不主动发起递归删除或删除审批。
task_pack.json创建目录后立即写入，并在每个阶段边界原地更新。它在任务完成后仍然保留，用于进度 展示、任务中断恢复和后续编辑。保持字段少而稳定：
{
"schema_version": "ppt_task_v2",
"deck_id": "topic_20260729_143015",
"deck_dir": "/absolute/workspace/ppt_decks/topic_20260729_143015",
"workspace_root": "/absolute/workspace",
"ppt_mode": "standard",
"params": {
"role": "...",
"audience": "...",
"scene": "...",
"page_count": 8,
"language": "zh-Hans",
"image_source": "auto",
"infographic_source": "echarts"
},
"request": {
"query": "...",
"source_files": []
},
"choices": {
"execution_depth": "standard",
"output": "static_html",
"design_richness": "rich",
"static_postprocess": ["pptx"]
},
"state": {
"status": "preparing",
"current_stage": "entry",
"completed_stages": [],
"research": {
"required": false,
"executor": null,
"mode": null
},
"capabilities": {},
"artifacts": {},
"last_error": null,
"updated_at": "ISO-8601"
},
"created_at": "ISO-8601"
}
当 choices.output 是 static_html 时，ppt_mode 必须是 standard，
static_postprocess 默认是 ["pptx"]；只有用户明确只要 HTML 时写 []。
当 choices.output 是 dynamic_html 时，ppt_mode 必须是 dazzle，不触发 PPTX 后处理。
动态任务的 static_postprocess 为 []。
choices.output | ppt_mode |
|---|---|
static_html | standard |
dynamic_html | dazzle |
阶段更新只修改相关字段，不重写用户选择和历史完成项。开始阶段时写
current_stage/status/updated_at；完成时把阶段加入 completed_stages 并把真实产物的
绝对路径写入 artifacts；失败时写 last_error。文件系统中的真实产物优先于过时的状态
字段。
info_pack.json只承载材料和事实信息，不复制运行状态：
{
"user_query": "...",
"user_assets": {
"reference_images": [],
"reference_image_captions": {},
"reference_docs": [],
"reference_docs_failed": []
},
"document_digest": {
"topic_summary": "...",
"key_sections": [],
"key_points": [],
"data_highlights": [],
"conflicts": [],
"open_questions": [],
"inherited_tables": [],
"inherited_images": []
},
"raw_documents": "/absolute/deck/raw_documents.json",
"research_report": null
}
document_digest 由宿主 Agent 阅读完整材料后直接写入，不通过额外模型 API。数字、专有
名词、时间、单位和材料间冲突必须保真。上传图片和文档内图片继续遵守“一张图片只理解
一次”的原有能力：宿主 Agent 用原生视觉能力读取后，把上传图片说明缓存到
reference_image_captions[absolute_path]，把文档内图片说明缓存到
raw_documents.documents[].inherited_images[].visual_summary。已有缓存且图片未变时跳过，
下游统一读取缓存；不创建独立 caption 服务。
把当前 Skill 的同级目录解析为 skills 根，并固定：
PPT_TOOLS_DIR = <skills root>/sn-ppt-tools
开始需要某项能力时读取
<PPT_TOOLS_DIR>/references/capability-policy.md，按
native -> bundled -> none 选择。sn-ppt-tools 是 PPT 整包的一部分，不做“是否安装”
判断，也不扫描其他仓库。只把每类能力的来源、状态、非敏感错误摘要和更新时间写入
task_pack.state.capabilities；不得记录 key 或 Authorization header。
媒体能力都不是 Entry 的强制前置。缺失时按 policy 继续，用可交付的无图版式表达内容。
需要用户处理配置时只提示运行 sn-ppt-doctor；不要在 Entry 重复变量清单。Doctor 会显示
Hermes/OpenClaw 实际读取的用户级 .env、缺失项和配置模板。
Standard / Deep 的 Story 完成后，先展示一行叙事概括和同一 deck_dir/outline.md 的
可点击完整路径，再调用 request_user_decision。这是大纲确认，不重新询问制作模式；
本次请求 60 秒，不沿用工具的通用 30 秒建议，也不改变制作模式选择卡的时限：
{
"question": "是否按此大纲继续？60 秒内未操作将按当前大纲继续制作；需要修改可直接填写意见。",
"decision_kind": "outline_confirmation",
"options": [
{"id": "approve", "label": "按此大纲继续", "description": "沿用已展示的大纲制作页面。"},
{"id": "revise", "label": "需要修改", "description": "先修改大纲，再开始制作。"}
],
"default_option_id": "approve",
"requested_auto_submit_seconds": 60,
"risk_level": "low",
"reversible": true,
"preserves_user_intent": true,
"allow_freeform": true
}
只在内容足以继续且用户未要求亲自确认时使用此默认。用户明确要求“等我确认”，或必要 事实/选择仍缺失时，保留确认卡但省略默认选项、超时及三项安全声明，问题中不再承诺 60 秒后继续，先解决缺口。 工具不可用时沿用文本确认；是否启用倒计时以工具回执为准。计时和自动续跑由客户端 负责，不调用 sleep、轮询或自己写“已超时”来模拟回复。用户点击立即生效；卡片中开始 输入修改意见会取消自动提交。Draft 保持默认直接生产，不新增等待。
收到该卡的 approve 回复（trigger=user 或 timeout）后，重新读取同一路径的
outline.md，按既有输出选择继续；未变的大纲不重复弹卡。超时表示采用默认，不写成
“用户已亲自确认”。revise 或自定义修改意见先交给 Story 更新同一份大纲；只有选择
“需要修改”而未给意见时，询问具体修改，不开始制作。大纲实质变化后重新展示并确认，
不能把旧回复用于新内容。普通聊天中的明确确认/修改也按同样规则处理。
进入和识别：回显已经进入 Entry。提取角色、受众、场景、页数、语言、附件、 明确的设计要求，以及用户是否明确要求 Static 只交付 HTML。已经提供的信息不再询问。
路由已有 PPTX：若原位编辑或模板填充与已选设计模式冲突，先澄清是否切换快速模式，用户明确同意后才交给 ppt-fast；已有 SN HTML 任务按恢复规则继续。从零生成继续本流程。
推荐三个选择：确定执行深度、输出格式和设计丰富度。只有输出意图确实无法判断且会产生完全不同交付物时才询问；其他情况先给推荐并继续。
建立固定目录：严格按“唯一目录规则”创建目录和初始 task_pack.json。
解析附件：对 PDF、DOCX、MD、TXT 执行：
python "<ENTRY_SKILL_ROOT>/scripts/parse_user_docs.py" \
--files <absolute paths...> \
--output "<deck_dir>/raw_documents.json" \
--asset-dir "<deck_dir>/source_assets"
Markdown 表格与本地图片引用、DOCX 表格与内嵌图片、PDF 文本、inherited_images 以及按需生成的 page_visuals 都要保留；page_visuals[].path 必须是 $DECK_DIR/source_assets/ 下的绝对路径，并随raw_documents.json 一起交接。未生成页图时，Figure 页裁切任务必须返回 blocked。一份文件失败时记录到 reference_docs_failed，继续处理其他文件。
理解全部材料：读取 raw_documents.json 中全部正文、表格和图片索引；必要时分段
阅读，但不得只读开头。用宿主 Agent 原生视觉能力逐张理解相关上传图片和文档内图片，
按上述兼容字段缓存，失败项记录后继续。再生成 document_digest，写
info_pack.json。Story 和出口不得重复理解已有缓存的图片，除非文件变化或当前任务确实
需要重新核对视觉细节。
决定外部证据路径：
required=false、executor=null、mode=null。用户明确要求核查
某个事实时，可直接用普通搜索完成该核查，但不为 Draft 启动完整 Deep Research。required=true、executor=entry、mode=null。不得因为“用户材料
看起来足够”而跳过；只要用户未禁止联网且普通搜索可用，就必须在 Story 前执行至少一次
真实普通搜索。required=true、executor=sn-deep-research；默认 mode=normal，复杂、
多维、争议、高时效或高风险任务使用 heavy。quick / normal / heavy 只属于
sn-deep-research，不用于描述 Standard。required=false、
executor=null、mode=null 和 skipped_reason=user_forbidden，只做材料内证据审计。完成外部证据补充：先按可选能力规则确定普通搜索来源：宿主原生网页搜索可用时
直接使用；否则调用 <PPT_TOOLS_DIR>/scripts/web_search.py。
sn-deep-research，不做 scout、
多维拆解、补研循环或完整研究报告编排。搜索目标只来自用户 query、材料中的时效性风险、
关键事实和会影响叙事的明显缺口；优先官方和一手来源，记录标题、URL、日期、支持的结论
及未解决限制。停止条件是 Story 所需关键证据已经覆盖或缺口已经明确，不为扩写而漫游。
把简洁结果写到 <deck_dir>/research/report.md。report_dir=<deck_dir>/research 和当前任务材料交给
sn-deep-research，按 mode=normal|heavy 完整运行。sn-ppt-tools 只作为搜索能力
fallback，不是另一套 Research 流程。<deck_dir>/research/report.md 写入
info_pack.research_report 和 task_pack.state.artifacts.research_report，再进入 Story。state.research.required=false、state.research.executor=null、
state.research.skipped_reason=search_unavailable 和
info_pack.document_digest.open_questions 中的事实覆盖限制写清楚，然后直接进入
Story。调用 Story：把同一 deck_dir 交给 sn-ppt-story。Story 读取 query、
info_pack.json、raw_documents.json 和已有 Research，生成唯一
<deck_dir>/outline.md。
大纲交互：Draft 默认继续生产，同时告知大纲路径；Standard / Deep 在 Box-Agent
按“大纲确认”展示原大纲并发卡，其他环境沿用文本确认。继续前重新读取磁盘上的
outline.md，不能使用聊天中的旧副本；确认方式不改变 Static / Dazzle 的出口分工。
出口分发：Story 已完成且当前磁盘 outline.md 已按本档位确认后，
static_html 调用 sn-ppt-standard，dynamic_html 调用 sn-ppt-dazzle；始终传入相同绝对
deck_dir。不得绕过 Story；出口不再研究、重排页面或重写大纲。
后处理和收尾：静态页面完成后，父级核对 Standard 的 deck.py review-prep
结果及最终 Review 合同，确认 <deck_dir>/present.html 存在、覆盖全部页面且播放器
可打开，最终全册像素已检查。仅有逐页 HTML/PNG 或 PPTX 不能代替这些验收。
本轮尚未准备待审产物时，执行 Standard 的 review-prep 后完成最终像素检查；
已验收且此后视觉源未变化时直接消费结果，不重复 build/audit 或改动页面。
随后按 static_postprocess 使用 Standard 自有 exporter
scripts/export_pptx/html_to_pptx.mjs 导出 PPTX，默认同时交付；只有用户明确只要 HTML
时才可省略 PPTX，任何静态任务都不能因此省略 present.html。
只缺播放器时复用已有页面补齐收尾，不重做 Research、Story 或整册页面。
把已验证的绝对路径登记到 task_pack.state.artifacts.present_html，最终回复必须给出
present.html 的可点击链接，保留它引用的 slides、样式与资源，不能只给文件夹或 PPTX。
必需产物缺失或转换失败时保留现有产物、状态写 partial 并记录错误；不得用宿主工具、
python-pptx 或自写脚本替换 exporter，不伪造文件路径。动态出口交付 deck.html 及其
实际使用的本地资源，并提供真实 HTML 链接。只登记真实存在的产物到 task_pack.state.artifacts。
当用户提供 deck 目录，或当前目录下存在明确的任务包时：
task_pack.json、info_pack.json 和磁盘实际文件。outline.md 存在时，以磁盘版本为 Story 真相。outline.md 的受影响项，不因局部修改重做材料或 Research；用户修改 outline 后，只失效 Story 之后受影响的页面及其派生 PPTX；Research 和材料解析不自动重跑；若 HTML、PNG、讲稿、播放器均完整而仅 PPTX 缺失，只重跑对应出口的 exporter。task_pack_v2.json、outline_v2.md 或第二个 deck 目录。超过约 30 秒的工作必须让用户看到有意义的进度。选择卡已展示模式确认结果，续跑直接报告下一步具体动作；加载本 Skill 前后都不要再次宣布进入模式或复述超时选择。只在出现新的进展、结果、阻塞或必要决定时更新，不换一种说法重复上一条进度。用户询问选择原因时正常解释。以下边界按实际变化回显，可合并相邻的短步骤：
deck_dir；outline.md 已生成；present.html、PNG、讲稿和播放器的真实路径。partial，不得伪造 PPTX 路径，并把失败原因写入 task_pack.state.last_error。进度以用户能理解的阶段描述为主，不暴露内部 prompt、模型调用或细碎状态字段。