--- 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: project: SenseNova-Skills tier: 1 category: scene user_visible: true triggers: - "生成 PPT" - "做一套 PPT" - "做一份演示" - "继续生成 PPT" - "sn-ppt-entry" --- # sn-ppt-entry 统一接收 PPT 生成请求，建立唯一任务目录，准备材料。Standard 先完成定向外部证据补充， Deep 先完成完整 Research，**下一步必须调用 `sn-ppt-story` 生成公共 `outline.md`**，再按 `choices.output` 分发到 `sn-ppt-standard`、`sn-ppt-dazzle` 或 `sn-ppt-creative`。 这是一套 Skill 的入口，不是独立运行时。文本理解、视觉理解和推理使用宿主 Agent 已有能力。普通搜索、图片搜索和图片生成优先使用宿主原生工具；原生能力不存在或实际 调用不可用时，才使用 PPT 整包自带的 `sn-ppt-tools`。不得要求用户另外配置模型客户端， 不得调用 `model_client.py`、`stage.py` 或为本流程再造 CLI 调度层。 ## Box-Agent 兼容入口 在 Box-Agent 中，从本次加载的 Skill 提示取得 Entry 的绝对 Skill Root，记为 ``。Entry 的所有确定性脚本都必须使用 `python "/scripts/.py"` 调用；禁止使用 `$SKILL_DIR`、当前工作目录 或相对的 `skills/` 路径。所有任务产物仍必须写入同一个绝对 `$DECK_DIR`，并在调用 Story 和出口 Skill 时逐字复用该路径。 ## 三个独立选择 ### 执行深度 - `draft`：尽快形成可看的方向稿。默认不做外部事实搜索，大纲完成后直接生产。 - `standard`：质量和等待时间平衡。Story 前由 Entry 做定向外部搜索和证据补充，不运行 完整 `sn-deep-research`；生成前让用户看 `outline.md`。 - `deep`：先完成 `sn-deep-research`，再生成正式 `outline.md`；生成前让用户确认。 Entry 根据任务复杂度、事实时效性、材料完整度和用户措辞推荐一档，同时展示 Draft / Standard / Deep。用户可以覆盖；用户未覆盖时采用推荐，不为这个选择增加一轮 阻塞问答。 ### 输出格式 - `static_html` -> `sn-ppt-standard` - `dynamic_html` -> `sn-ppt-dazzle` - `creative` -> `sn-ppt-creative` 用户提供已有 PPTX、模板或半成品并要求修改时，直接进入 `sn-ppt-edit`，不是先走生成 出口。Static HTML 仍由 `sn-ppt-standard` 自己后处理（默认导出 PPTX）。Entry 只负责路由、验证真实文件并登记 artifact。 ### 设计丰富度 - `restrained`（克制）：政企、学术、法务、财务或明确要求简洁。 - `rich`（丰富）：默认，适合多数业务汇报、产品介绍和正式演示。 - `high_creative`（高创意）：发布会、品牌传播、创意提案或明确要求强视觉。 用户明确指定时直接采用；否则结合场景、受众、输出格式和措辞推荐。显示当前选择与 三档名称，但不单独阻塞。用户在生成前、确认大纲时或后续修改中覆盖时，更新同一份 `task_pack.json`。丰富度只决定视觉投入，不改变事实标准和 Story 遵循要求。 ## 唯一目录规则 新任务的输出位置沿用已经验证稳定的原 Entry 规则，不得重新推断： 1. 先执行 `pwd -P`，把该命令**实际返回的完整绝对路径**逐字记为 `workspace_root`。宿主显示的 session workspace、repo 根或其他路径标签都不能替代这次 `pwd -P` 的结果；尤其不得自行 删除返回路径末尾的 `output`、`workspace` 等目录名。 2. 唯一父目录是 `/ppt_decks/`。 3. 目录名是 `_`。 4. 创建后在同一条命令中用 `pwd -P`/绝对化结果回显 `deck_dir`，立即写入 `task_pack.deck_dir`，此后全链路只逐字复用该值，禁止根据框架 workspace 信息重新拼接。 5. 不使用用户 home 根、Skill 目录、repo 根、`/tmp`、另一个 workspace 或 `PPT_DECK_ROOT`。 6. 不能创建 `/ppt_decks/` 时停止并报告权限问题，不换地方继续。 Box-Agent 的文件工具相对根通常是 `/output`，而会话元数据中的 workspace 可能是它的父目录。两者不是同一路径。创建 `task_pack.json`、`info_pack.json`、`outline.md` 和后续产物时必须全部使用上述同一个 `deck_dir`；每次文件工具返回的绝对落盘路径都要位于 该目录。若返回路径不一致，立即停止并修正路径，不得在两个 `ppt_decks/` 之间继续。JSON 和 Markdown 直接用文件工具写入，不要用 `execute_code` 内嵌一个重新推导的绝对路径。 已有任务必须复用已有 `task_pack.json` 中的绝对 `deck_dir`；继续任务不得新建目录。 所有 Skill 安装目录只读。 ## `task_pack.json` 创建目录后立即写入，并在每个阶段边界原地更新。它在任务完成后仍然保留，用于进度 展示、任务中断恢复和后续编辑。保持字段少而稳定： ```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”或“不要 PPTX”时才写 `[]`。 其他输出出口的后处理字段写 `[]`，不触发 Static 后处理。 `ppt_mode` 是旧出口的兼容字段： | `choices.output` | `ppt_mode` | |---|---| | `static_html` | `standard` | | `dynamic_html` | `dazzle` | | `creative` | `creative` | 阶段更新只修改相关字段，不重写用户选择和历史完成项。开始阶段时写 `current_stage/status/updated_at`；完成时把阶段加入 `completed_stages` 并把真实产物的 绝对路径写入 `artifacts`；失败时写 `last_error`。文件系统中的真实产物优先于过时的状态 字段。 ## `info_pack.json` 只承载材料和事实信息，不复制运行状态： ```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 根，并固定： ```text PPT_TOOLS_DIR = /sn-ppt-tools ``` 开始需要某项能力时读取 `/references/capability-policy.md`，按 `native -> bundled -> none` 选择。`sn-ppt-tools` 是 PPT 整包的一部分，不做“是否安装” 判断，也不扫描其他仓库。只把每类能力的来源、状态、非敏感错误摘要和更新时间写入 `task_pack.state.capabilities`；不得记录 key 或 Authorization header。 媒体能力都不是 Entry 的强制前置。缺失时按 policy 继续；只有 Creative 已被明确选择且 原生、内置生图都不可用时，暂停 Creative 出口并保留全部前置产物，不自动切换出口。 需要用户处理配置时只提示运行 `sn-ppt-doctor`；不要在 Entry 重复变量清单。Doctor 会显示 Hermes/OpenClaw 实际读取的用户级 `.env`、缺失项和配置模板。 ## 新任务流程 1. **进入和识别**：回显已经进入 Entry。提取角色、受众、场景、页数、语言、附件、 明确的设计要求，以及用户是否明确要求 Static 只交付 HTML。已经提供的信息不再询问。 2. **路由已有 PPTX**：若任务是编辑、优化、续写或模板填充，交给 `sn-ppt-edit`。若是从零生成，继续本流程。 3. **推荐三个选择**：确定执行深度、输出格式和设计丰富度。只有输出意图确实无法判断且会产生完全不同交付物时才询问；其他情况先给推荐并继续。 4. **建立固定目录**：严格按“唯一目录规则”创建目录和初始 `task_pack.json`。 5. **解析附件**：对 PDF、DOCX、MD、TXT 执行： ```bash python "/scripts/parse_user_docs.py" \ --files \ --output "/raw_documents.json" \ --asset-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`，继续处理其他文件。 6. **理解全部材料**：读取 `raw_documents.json` 中全部正文、表格和图片索引；必要时分段 阅读，但不得只读开头。用宿主 Agent 原生视觉能力逐张理解相关上传图片和文档内图片， 按上述兼容字段缓存，失败项记录后继续。再生成 `document_digest`，写 `info_pack.json`。Story 和出口不得重复理解已有缓存的图片，除非文件变化或当前任务确实 需要重新核对视觉细节。 7. **启动生成进度工作台**：`task_pack.json` 和 `info_pack.json` 都已存在后，立即调用 `sn-ppt-workbench/scripts/open_workbench.py`，始终传入当前任务的绝对 `deck_dir` 和可用的 同会话智能体参数。启动成功后立即向用户提供返回的 `generation_url`（固定为 `/progress`）；启动失败或返回 `skipped` 时简要说明原因并继续生成，不得因此阻塞 Research、Story 或页面生产。不得在此步骤运行 npm、构建 Workbench 或切换任务目录。 8. **决定外部证据路径**： - Draft：默认跳过，写 `required=false`、`executor=null`、`mode=null`。用户明确要求核查 某个事实时，可直接用普通搜索完成该核查，但不为 Draft 启动完整 Deep Research。 - Standard：默认写 `required=true`、`executor=entry`、`mode=null`。不得因为“用户材料 看起来足够”而跳过；只要用户未禁止联网且普通搜索可用，就必须在 Story 前执行至少一次 真实普通搜索。 - Deep：写 `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`，只做材料内证据审计。 9. **完成外部证据补充**：先按可选能力规则确定普通搜索来源：宿主原生网页搜索可用时 直接使用；否则调用 `/scripts/web_search.py`。 - Standard 由 Entry 当前 Agent 做定向搜索，不调用 `sn-deep-research`，不做 scout、 多维拆解、补研循环或完整研究报告编排。搜索目标只来自用户 query、材料中的时效性风险、 关键事实和会影响叙事的明显缺口；优先官方和一手来源，记录标题、URL、日期、支持的结论 及未解决限制。停止条件是 Story 所需关键证据已经覆盖或缺口已经明确，不为扩写而漫游。 把简洁结果写到 `/research/report.md`。 - Deep 把普通搜索来源、绝对 `report_dir=/research` 和当前任务材料交给 `sn-deep-research`，按 `mode=normal|heavy` 完整运行。`sn-ppt-tools` 只作为搜索能力 fallback，不是另一套 Research 流程。 - 两条路径完成后都把同一个 `/research/report.md` 写入 `info_pack.research_report` 和 `task_pack.state.artifacts.research_report`，再进入 Story。 - 原生与内置搜索都不可用时，不伪造 Research，也不阻塞 PPT：把 `state.research.required=false`、`state.research.executor=null`、 `state.research.skipped_reason=search_unavailable` 和 `info_pack.document_digest.open_questions` 中的事实覆盖限制写清楚，然后直接进入 Story。 - 搜索能力存在但 Research 本身尚未完成时，仍不得先写正式大纲。 10. **调用 Story**：把同一 `deck_dir` 交给 `sn-ppt-story`。Story 读取 query、 `info_pack.json`、`raw_documents.json` 和已有 Research，生成唯一 `/outline.md`。 11. **大纲交互**：Draft 默认继续生产，同时告知大纲路径；Standard / Deep 展示一行整体 叙事和路径，等待用户修改或确认。继续前重新读取磁盘上的 `outline.md`，不能使用聊天 中的旧副本。 12. **出口分发**：Story 已完成且当前磁盘 `outline.md` 已按本档位确认后，按 `choices.output` 调用唯一对应 Skill：`static_html` 调用 `sn-ppt-standard`， `dynamic_html` 调用 `sn-ppt-dazzle`，`creative` 调用 `sn-ppt-creative`。始终传绝对 `deck_dir`。不得绕过 Story 把原始 query 直接交给任一出口；三个出口都只做表达与产物生产，不 再研究、重排页面或重写 Story。 13. **后处理和收尾**：Static HTML 默认在页面完成后由 `sn-ppt-standard` 内置 exporter（`scripts/export_pptx/html_to_pptx.mjs`）导出 PPTX；该出口**必须同时交付 `present.html` 和 PPTX 两个产物，缺一即技术故障**（用户明确要求只要 HTML 时，PPTX 可缺、`present.html` 仍必须存在）。PPTX **只能**由该内置 exporter 生成：禁止用 python-pptx、自写脚本或宿主原生工具替代。Entry 最终把各出口生成的真实产物写回 `task_pack.state.artifacts`；转换失败保留已有 HTML 产物、状态置 `partial` 并如实说明，不得另起炉灶补产出或伪造 PPTX 路径。 ## 恢复规则 当用户提供 deck 目录，或当前目录下存在明确的任务包时： 1. 读取 `task_pack.json`、`info_pack.json` 和磁盘实际文件。 2. 当前 `outline.md` 存在时，以磁盘版本为 Story 真相。 3. Research 报告、outline、页面、渲染图和最终产物存在时，不因状态字段滞后而重做。 4. 从最早一个“必要产物确实缺失”的阶段继续。 5. 用户修改 outline 后，只失效 Story 之后受影响的页面及其派生 PPTX；Research 和材料解析不自动重跑；若 HTML、PNG、讲稿、播放器均完整而仅 PPTX 缺失，只重跑对应出口的 exporter。 6. 不创建 `task_pack_v2.json`、`outline_v2.md` 或第二个 deck 目录。 ## 进度反馈 超过约 30 秒的工作必须让用户看到进度。至少在以下边界各回显一句： - 已识别任务与三个选择； - 已建立 `deck_dir`； - 附件解析开始/完成； - 生成进度工作台已启动并提供 `/progress`，或说明非阻塞的跳过原因； - Research 开始/完成或明确跳过； - Story 开始/`outline.md` 已生成； - 等待确认或已进入出口； - 页面生产进度；页面完成后回显 `present.html`、PNG、讲稿和播放器的真实路径。 - 后处理与最终产物；PPTX 失败时保留 HTML、PNG、讲稿和播放器，状态为 `partial`，不得伪造 PPTX 路径，并把失败原因写入 `task_pack.state.last_error`。 进度以用户能理解的阶段描述为主，不暴露内部 prompt、模型调用或细碎状态字段。 ## 硬规则 1. 原有能力没有被明确删除时必须保留。 2. 不在 Entry 生成页面、图片或视觉方案。 3. 不允许出口自行搜索或重新决定页序、标题和核心结论。 4. 不静默切换输出格式或设计档位。 5. 可选搜索或图像能力失败时最多尝试原生一次、内置一次；随后执行 policy 的无工具路径。 6. 不用 mock 数字冒充事实；缺口应回到 Research/Story 或明确标示。 7. 不因 Static 默认的 PPTX 后处理失败删除可用的 HTML、图片或 PPTX。 8. 不新增外部模型客户端、额外 API 配置、通用状态机或大型调度脚本。 9. Workbench 启动是生成流程的最佳努力辅助能力；失败不得改变输出选择或中止生成。