nature-image2ppt

Nature Image2PPT

将此目录作为完整运行时使用。仅通过以下方式执行确定性操作：

python <image2ppt-root>/cli/image2ppt/cli.py <command> ...

使用 Python 3.10 或更高版本，并安装 requirements.txt。当存在专用环境时，请将下方每条 python 命令中的 python 替换为 macOS/Linux 上的 <image2ppt-root>/.venv/bin/python 或 Windows 上的 <image2ppt-root>/.venv/Scripts/python.exe。doctor 失败后不要继续；只安装其报告的缺失依赖，然后重新运行它。

不要发现或调用其他 Skill、CLI、Prompt、Schema、模块或状态机。

逐步阅读本地契约

始终阅读 references/workflow.md。仅在设置或 doctor 失败时阅读 references/runtime-dependencies.md，仅在选择或排查 OCR 时阅读 references/ocr-text-hints-contract.md。

在编写页面清单之前，阅读 references/page-decision-tree.md 和 references/manifest-schema.md。仅添加该页面所需的引用：

• 结构化或复合页面：references/region-decomposition.md 和 references/object-routing.md；
• 箭头：references/manifest-arrow-extension.md；
• 栅格资源或图像后端工作：references/assets-provenance-contract.md。

在接受或交付输出之前，阅读 references/qa-contract.md。

保持单一事实来源

• 将 page_jobs.json 视为唯一的页面状态来源。
• 将每个 pages/page_NNN/manifest.json 视为唯一的页面内容来源。
• 将 deck_manifest.json 视为最终组装来源。
• 对于有状态的生命周期操作，仅使用 prepare、run next/dispatch/record/reset/hints/finalize 以及本地 CLI 中的页面命令。
• 将语义区域证据保留在 manifest.json.image2ppt_region_decomposition 中。
• 切勿创建第二个作业文件、重建计划、OCR 规范化器、页面控制器、打包器或 finalize 路径。
• 让补充 QA 报告失败；切勿让它改变生命周期状态。

将每次写入保留在其所有者目录内

• 页面构建、验证、hints 和 QA 只能在该页面目录内读取和写入。清单路径、记录的资产、公式、报告、预览和 --out 覆盖不得使用 ..、符号链接或绝对路径逃逸该目录。唯一的外部输入例外是提供给 image import 或作为 process-sheet --asset-sheet-source 的显式图像工具结果；它会在成为构建依赖之前被复制到页面中。
• 运行级清单和最终输出必须保留在已准备的运行目录内。Finalization 会在同目录的临时文件中重建，并且仅在构建成功后才原子性地发布它。
• 将任何边界拒绝视为硬失败；不要将被拒绝的文件复制回范围内并将其作为运行时输出呈现。

保持迁移前行为

• 将自包含视为路径/导入/入口点迁移，而非重建行为的重新设计。
• 从完整的本地基础层加上保留的 Image2PPT 配置文件层生成每个 worker Prompt。不要压缩、重新解释或替换任一层。
• 当多条路由都满足契约时，优先使用先前已验证的视觉策略。保持简单测量对象为原生，并在原生重绘会降低保真度时保留有界复杂资产。
• 切勿仅为了证明运行时独立性而重新编写已接受的基线页面。

运行工作流

图像后端选择

当 Agent 运行时暴露 image_gen.imagegen 时，使用 builtin-imagegen；它是首选后端，因为工作进程可以检查编辑输入并导入显式的本地结果。仅当内置工具不可用、报错、无法读取输入或未返回有效的本地输出时，才使用 CLI 图像契约。缺失可选参数（如 model、mask、size、quality 或输出路径）绝不允许回退。将实际生产者和允许的回退原因记录在 imagegen-jobs.json 中。

CLI 图像契约在传输边界上与提供商无关。仅对 GPT Image 模型 id 选择 codex-oauth。对于任何提供商专属模型，只要其端点实现了与 OpenAI Images 兼容的 /images/generations 和/或 /images/edits schema，就选择 openai-compatible-api。不要从任务的大模型推断图像后端。当来源追溯很重要时，使用显式后端；auto 仅对兼容的 GPT Image id 使用 Codex OAuth，否则选择已配置的 API，且不会将 Codex OAuth 凭据发送给第三方。

1. 预检与 OCR 选择

python <image2ppt-root>/cli/image2ppt/cli.py doctor --json

当已配置百度 AI Studio PADDLE_OCR_TOKEN 时，使用它。如果未配置，请告知用户一次：本地 builtin-ink 回退仅测量文本几何信息，并不识别字符；提供 references/ocr-text-hints-contract.md 中的配置路径。尊重仅离线这一选择。

2. 准备一次运行

python <image2ppt-root>/cli/image2ppt/cli.py prepare <input...> \
  --out-root output/image2ppt --image-backend builtin-imagegen

若要为可审计的来源追溯固定已配置的第三方提供商/模型，请使用 --image-backend openai-compatible-api 进行准备。运行契约会记录活动项目配置或环境中的确切 IMAGE2PPT_IMAGE_MODEL；它不会仅仅因为没有传入 --model 标志就替换为 GPT Image 默认值。

仅当有意禁用 OCR 处理时，才使用 --no-text-hints。需要时，可在不创建新运行的情况下重新生成提示：

python <image2ppt-root>/cli/image2ppt/cli.py run hints <run-dir>

3. 推进并认领页面

python <image2ppt-root>/cli/image2ppt/cli.py run next <run-dir> --json
python <image2ppt-root>/scripts/build_page_worker_prompt.py \
  <run-dir> --page <page-id> --out <absolute-page-dir>/worker-prompt.md
python <image2ppt-root>/cli/image2ppt/cli.py run dispatch \
  <run-dir> --page <page-id> --agent-id <id> --prompt-file <absolute-prompt>

对于恰好一个页面，使用 --local 认领它，并在当前 Agent 中重建。对于多个页面，按 page_jobs.json 中的容量派发独立的页面工作进程。不要仅仅因为某个活跃工作进程较慢就重置它。

4. 重建并门控每个页面

将结构化页面规划为 3–5 个语义区域，并独立路由每个区域。使用经过测量的复合图形：测量每个节点、关系和受保护锚点。将可测量的圆形、卡片、直线/虚线关系和简单连接线保持为原生元素。仅对复杂的本地子部件使用有界透明资源。

将细箭头表示为一个连接线，且其箭头位于同一对象上。将填充箭头表示为一个 Arrow AutoShape，并将标签文本居中放在同一对象内。绝不要用一条线加一个三角形来构造普通箭头，也绝不要将整个知识图谱压平为一张图像。

使用 schema_version: 2 编写新的页面清单。使用带有显式 kind 和 representation 值的结构化 visual_inventory 项，并为每项必需的质量检查编写具体的 quality_evidence 观察。公式渲染是硬门控：缺少引擎、转换器或编译失败必须保持页面失败，除非用户明确批准该确切公式例外，并且清单同时记录 user_approved_exception: true 和具体的 approval_note。

工作进程 Prompt 执行确定性序列。其最终门控为：

python <image2ppt-root>/cli/image2ppt/cli.py page build <page-dir>
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir>
# The first run writes visual-review-evidence.template.json and remains pending.
# Inspect source.png against render/rendered.png, copy and complete the template
# as visual-review-evidence.json, repair if needed, then:
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <page-dir>/visual-review-evidence.json
python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <page-dir>

证据文件必须覆盖当前源/渲染哈希以及每项必需检查，并提供具体观察。--visual-review-notes 是可选上下文，不能替代证据文件。

仅在标准验证以及 Image2PPT 区域、箭头和渲染门控通过后记录：

python <image2ppt-root>/cli/image2ppt/cli.py run record \
  <run-dir> --page <page-id> --agent-id <id>

使用相同的 run reset → dispatch → record 生命周期来修复被拒绝的页面。

5. 最终确定并重新验证重建后的演示文稿

当 run next 报告 finalize 时，运行：

python <image2ppt-root>/cli/image2ppt/cli.py run finalize <run-dir>
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir>
# The first run writes final/visual-review-evidence.template.json and remains pending.
# Inspect every rendered slide, complete final/visual-review-evidence.json, then:
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <run-dir>/final/visual-review-evidence.json

Finalize 会根据页面清单进行重建，保留源演讲者备注，验证 包，并写入由 deck_manifest.json 记录的输出。Final QA 会重新应用 清单箭头，验证箭头的原子性和复合结构，渲染每一张 幻灯片，检查演讲者备注的完整性，并写入 final/image2ppt_qa.json。

交付

返回最终 PPTX 路径、标准最终验证，以及 final/image2ppt_qa.json。报告哪些复杂视觉元素仍为可替换的位图 资产。当任何页面/最终关卡仍处于待处理或失败状态时，不要称该演示文稿已完成。