sn-ppt-entry · git:20260917.b47f4e7 · 2026-09-17 · sha256 0dba5b354efecf6e
sn-ppt-entry git:20260917.b47f4e7A
Immutable. This exact content is served forever at /api/v1/blob/0dba5b354efecf6e.
---
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_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`；生成前让用户确认。
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. 唯一父目录是 `<workspace_root>/ppt_decks/`。
3. 目录名是 `<topic_concise>_<YYYYMMDD_HHMMSS>`。
4. 创建后在同一条命令中用 `pwd -P`/绝对化结果回显 `deck_dir`，立即写入
`task_pack.deck_dir`，此后全链路只逐字复用该值，禁止根据框架 workspace 信息重新拼接。
5. 不使用用户 home 根、Skill 目录、repo 根、`/tmp`、另一个 workspace 或
`PPT_DECK_ROOT`。
6. 不能创建 `<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 安装目录只读。
## `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 = <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 继续；只有 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 "<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`，继续处理其他文件。
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. **完成外部证据补充**：先按可选能力规则确定普通搜索来源：宿主原生网页搜索可用时
直接使用；否则调用 `<PPT_TOOLS_DIR>/scripts/web_search.py`。
- Standard 由 Entry 当前 Agent 做定向搜索，不调用 `sn-deep-research`，不做 scout、
多维拆解、补研循环或完整研究报告编排。搜索目标只来自用户 query、材料中的时效性风险、
关键事实和会影响叙事的明显缺口；优先官方和一手来源，记录标题、URL、日期、支持的结论
及未解决限制。停止条件是 Story 所需关键证据已经覆盖或缺口已经明确，不为扩写而漫游。
把简洁结果写到 `<deck_dir>/research/report.md`。
- Deep 把普通搜索来源、绝对 `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。
- 原生与内置搜索都不可用时，不伪造 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，生成唯一
`<deck_dir>/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 启动是生成流程的最佳努力辅助能力；失败不得改变输出选择或中止生成。