/sn-ppt-entry

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`

创建目录后立即写入，并在每个阶段边界原地更新。它在任务完成后仍然保留，用于进度 展示、任务中断恢复和后续编辑。保持字段少而稳定：

{
  "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`

只承载材料和事实信息，不复制运行状态：

{
  "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 继续；只有 Creative 已被明确选择且 原生、内置生图都不可用时，暂停 Creative 出口并保留全部前置产物，不自动切换出口。 需要用户处理配置时只提示运行 `sn-ppt-doctor`；不要在 Entry 重复变量清单。Doctor 会显示 Hermes/OpenClaw 实际读取的用户级 `.env`、缺失项和配置模板。

新任务流程

1. **进入和识别**：回显已经进入 Entry。提取角色、受众、场景、页数、语言、附件、 明确的设计要求，以及用户是否明确要求 Static 只交付 HTML。已经提供的信息不再询问。 2. **路由已有 PPTX**：若任务是编辑、优化、续写或模板填充，交给 `sn-ppt-edit`。若是从零生成，继续本流程。 3. **推荐三个选择**：确定执行深度、输出格式和设计丰富度。只有输出意图确实无法判断且会产生完全不同交付物时才询问；其他情况先给推荐并继续。 4. **建立固定目录**：严格按“唯一目录规则”创建目录和初始