pptx-nova

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pptx-nova

Use the local

xdoc

CLI to create, modify, fill, export, and check native editable

.pptx

files. This skill uses declarative xdoc JSON patches, DeckKit, dry-run, sidecars, and visual gates; do not prefer python-pptx, PptxGenJS, or SVG-to-PPTX paths.

使用本地

xdoc

CLI 创建、修改、填充、导出和检查原生可编辑的

.pptx

文件。此 skill 使用声明式 xdoc JSON patch、DeckKit、dry-run、sidecar 和 visual gate；不要优先采用 python-pptx、PptxGenJS 或 SVG-to-PPTX 路径。

Progressive Disclosure Principles

渐进式披露原则

Keep

SKILL.md

limited to routing and non-skippable hard rules. After this skill triggers, read this file first, then read only the reference files that match the task type. Do not load the full creation workflow for an edit task; do not load DeckKit or visual richness documentation for a simple export.

If a task spans multiple types, read the entry reference for each relevant type. When charts, tables, formulas, raw XML, complex brand styling, or other specialized content appears, then read the matching specialized reference.

References are grouped by create, edit, translation, runtime, review, content, and policies; see the reference index for ownership. Reading paths in references are relative to the containing document; explicit

references/...

paths start at the skill root.

将

SKILL.md

限制为仅包含路由和不可跳过的硬性规则。此 skill 触发后，先读取本文件，再只读取与任务类型匹配的 reference 文件。编辑任务不要加载完整的创建 workflow；简单导出不要加载 DeckKit 或视觉丰富度文档。

如果任务横跨多种类型，请读取每种相关类型的入口 reference。当出现 charts、tables、formulas、raw XML、复杂品牌样式或其他专业内容时，再读取对应的专业 reference。

References 按 create、edit、translation、runtime、review、content 和 policies 分组；各 reference 的归属请参阅 reference 索引。reference 中的路径相对于所在文档；显式的

references/...

路径从 skill 根目录开始解析。

Progressive xdoc Capability Discovery

xdoc 能力的渐进式发现

After creating each run, run

<skill-root>/scripts/cli/runtime/probe.mjs

once and save the result as

xdoc-capabilities.json

. The standard refurbish runner does this inside its own run directory; do not manually initialize a full run first. An explicit

--run-dir

must be new, empty, or contain only

xdoc-capabilities.json

. Route from runtime schema and dry-run evidence, never version numbers. Operation/catalog indexes are not allowlists; missing means

undisclosed

. For semantic routing, read the exact

capabilities.capabilityTruth.entries[]

feature/subset:

supported

may use its operations,

partial

requires verification,

preserve-only

stays untouched, and

unsupported

follows its alternative; operation presence never upgrades feature status. When an entry has non-null

axes

, route

create

edit

inspect

preserve

render

verify

independently. The entry-level status does not upgrade a weaker axis, and static PDF/PNG or Viewer fallback evidence never upgrades

verify

to PowerPoint playback support. If a caller-provided run directory is rejected, the guard reports the allowed initial entries, every detected entry, and a safe recovery hint; preserve that directory as evidence and retry with a new one.

For operation lookup, schema projections, or CLI output flags, read

references/runtime/schema-discovery.md#focused-lookup-and-output-flags

first. Prefer exact capability truth and the saved op index; projected schemas discover fields but do not prove patch validity. For direct CLI calls, use explicit commands and action-local options; follow that reference's CLI invocation guidance for literal paths, typed arguments, and parser failures. Derive selectors from inspect, the target op schema, then dry-run suggestions. Choose one selector lookup method; do not combine

id

name

, or

query

with another method. Combine AND predicates inside one query or its supported inline form, and pair

idx

with

placeholder

Block only when the caller explicitly requires a strict gate and a task-critical capability is still undisclosed; otherwise keep exploring or use an existing fallback, and never disable new xdoc capabilities only because the snapshot is minimal.

For Agent transport routing, read the exact contracts under

capabilities.agentTransports

, including

mcp.contract

; command presence alone is insufficient and unknown contracts fail closed. MCP replaces only disclosed adapter calls, never workflow gates. Read

references/runtime/daemon-sessions.md

for details. For auth diagnostics or report validation, use the action-specific schema and report reference in

references/runtime/schema-discovery.md

; the compact capability snapshot is not a complete command contract. For license installation, renewal, unhealthy credentials, or an authorization refusal, read

references/runtime/licensing.md

. Keep authorization-only tasks on that route without deck preparation or deck delivery gates; ordinary successful PPTX tasks need no extra auth-maintenance step. Use

xdoc schema --command <command.action>

--report <schemaVersion>

for focused contracts. Standard runners freeze the display date in

render-context.json

; preserve it when resuming and verify the effective

renderContext

in rendering evidence. Manual render sequences must use the same

--field-date

. Semantic summaries should persist full evidence with

diff --output

, then read and verify that file when detail is needed; see

references/review/export-and-check.md

每次创建一个 run 后，运行一次

<skill-root>/scripts/cli/runtime/probe.mjs

，并将结果保存为

xdoc-capabilities.json

。标准 refurbish runner 会在自己的 run 目录中完成此操作；不要先手动初始化完整的 run。如果显式传入

--run-dir

xdoc-capabilities.json

。应根据 runtime schema 和 dry-run 证据进行路由，绝不能依据版本号。operation/catalog 索引不是 allowlist；缺失即表示

undisclosed

。进行语义路由时，应读取

capabilities.capabilityTruth.entries[]

中对应 feature/subset 的确切条目：

supported

可以使用其 operations，

partial

需要验证，

preserve-only

必须保持不变，

unsupported

应遵循其替代方案；operation 是否存在绝不能提升 feature 状态。

当一个条目的

axes

非 null 时，应分别路由

create

edit

inspect

preserve

render

verify

。条目级状态不能提升较弱 axis 的状态；静态 PDF/PNG 或 Viewer fallback 证据绝不能将

verify

提升为 PowerPoint playback 支持。

如果调用方提供的 run 目录被拒绝，guard 会报告允许的初始条目、检测到的全部条目以及安全恢复提示；应保留该目录作为证据，并使用新目录重试。

如需查询 operation、schema 投影或 CLI 输出选项，请先读取

references/runtime/schema-discovery.md#focused-lookup-and-output-flags

。优先使用确切的 capability truth 和已保存的 op 索引；schema 投影可帮助发现字段，但不能证明 patch 有效。直接调用 CLI 时，应使用明确的命令和 action 局部选项；对于字面量路径、带类型参数和 parser 失败，请遵循该 reference 中的 CLI 调用指南。应依次从 inspect、目标 op schema 和 dry-run suggestions 推导 selector。选择一种 selector 查询方式；不要将

id

、

name

或

query

与另一种方式组合。将 AND 谓词组合在同一个 query 或其支持的内联形式中，并将

idx

与

placeholder

配对使用。

仅当调用方明确要求 strict gate，且任务关键 capability 仍为

undisclosed

时才应阻止执行；否则应继续探索或使用现有 fallback，绝不能仅因为快照内容有限就禁用新的 xdoc capability。

进行 Agent transport 路由时，应读取

capabilities.agentTransports

下的确切 contract，包括

mcp.contract

；仅存在 command 并不足以证明可用，未知 contract 必须 fail closed。MCP 只替代已披露的 adapter 调用，绝不能绕过 workflow gate。详情请参阅

references/runtime/daemon-sessions.md

。进行授权诊断或报告验证时，应使用对应 action 的 schema 和

references/runtime/schema-discovery.md

中的报告 reference；紧凑的 capability 快照并不是完整的 command contract。对于 license 安装、续期、凭据不健康或授权被拒绝的情况，请读取

references/runtime/licensing.md

。仅涉及授权的任务应保持在此路径上，不执行 deck preparation 或 deck delivery gate；普通 PPTX 任务成功时不需要额外的授权维护步骤。使用

xdoc schema --command <command.action>

或

--report <schemaVersion>

获取聚焦的 contract。标准 runner 会冻结

render-context.json

中的显示日期；恢复任务时必须保留该日期，并验证渲染证据中的有效

renderContext

。手动渲染序列必须使用相同的

--field-date

。语义摘要应通过

diff --output

持久化完整证据，需要详细信息时再读取并验证该文件；参见

references/review/export-and-check.md

。

Run Reuse and Isolation

Run 复用与隔离

.pptx-nova/<run>/

may be read as historical evidence, but it must not automatically become the execution context for the current task. Create a new current context for new tasks, old-feedback audits, tool capability investigations, post-upgrade rechecks, or when the user challenges an old result. Use old runs read-only to explain what happened at that time.

Reuse an old run for execution only when the user explicitly asks to continue the same task and the source, output target, and task objective have not changed. Even when reusing a run, probe the current

xdoc

again first. Old

xdoc-capabilities.json

files only describe what was disclosed at that time and are not facts about current capabilities. During development, upgrades, or old-run recovery, any judgment about "missing capabilities" must be checked against the current runtime/schema/help first.

.pptx-nova/<run>/

可以作为历史证据读取，但不得自动成为当前任务的执行上下文。对于新任务、旧反馈审计、工具 capability 调查、升级后复查，或用户质疑旧结果的情况，应创建新的当前上下文。旧 run 只能以只读方式用于解释当时发生的情况。

只有当用户明确要求继续同一任务，并且 source、输出目标和任务目标均未发生变化时，才能复用旧 run 执行。即使复用旧 run，也必须先重新探测当前

xdoc

。旧的

xdoc-capabilities.json

只描述当时披露的能力，并非当前能力的事实依据。在开发、升级或旧 run 恢复过程中，任何关于“缺少 capability”的判断都必须先检查当前 runtime/schema/help。

Artifact Retention and Cleanup Strategy

Artifact 保留与清理策略

.pptx-nova/<slug>-<timestamp>/

is auditable evidence, not an ordinary cache. Keep the current run's capability snapshot, render context, planning/contract inputs, patch and sidecars, machine-gate reports (including retained full diff evidence), final candidate, comparison/contact overview, visual review, and issue-page evidence. Do not invent missing artifacts. The workflow-specific exact retention set is defined in

references/common-workflow.md

Only a successful current run may be slimmed, and only by removing rebuildable heavy previews, caches, logs, failed intermediate candidates, or unreferenced scratch files. Failed, interrupted, unvalidated, or resumable runs stay intact. Never delete user inputs/finals, reference resources, another run, anything outside the workspace, or the whole

.pptx-nova

directory. Cross-run cleanup needs an explicit request and a reviewed candidate list.

--cleanup

still retains the minimal evidence package and writes

cleanup-manifest.json

;

--keep-all

preserves everything. State cleanup status in the final summary.

.pptx-nova/<slug>-<timestamp>/

是可审计的证据，而不是普通缓存。保留当前 run 的 capability 快照、render context、planning/contract 输入、patch 和 sidecar、机器 gate 报告（包括保留的完整 diff 证据）、最终 candidate、comparison/contact overview、visual review 和 issue-page 证据。不得虚构缺失的 artifact。准确的保留集合由

references/common-workflow.md

按 workflow 定义。

只有成功的当前 run 才能精简，并且只能删除可重新生成的重型预览、缓存、日志、失败的中间 candidate 或未被引用的 scratch 文件。失败、中断、未验证或可恢复的 run 必须保持完整。绝不能删除用户输入或最终产物、reference 资源、其他 run、工作区外部的任何内容，或整个

.pptx-nova

目录。跨 run 清理需要用户明确请求，并提供经过审查的 candidate 清单。

--cleanup

仍会保留最小证据包并写入

cleanup-manifest.json

；

--keep-all

会保留全部内容。最终摘要中必须说明清理状态。

Quick Paths

快速路径

Use these only to choose the entry reference; the routing table owns details.

Runtime license / activation / renewal / authorization failure:
```
references/runtime/licensing.md
```
; install for the actual execution user/environment, inspect admission, then verify the intended task.
Create:
```
references/create/create-runner.md
```
and
```
references/create/design-quality.md
```
; the design floor applies even to a one-sentence Express brief. Formal/high-risk work also follows the Studio/design-lock references. The runner prepares canonical candidate evidence first; after actual PNG review, use its
```
--finalize --visual-review
```
phase to publish the same hash-bound candidate without rendering again.
Edit or micro-edit: inspect/select, normalize the Edit Contract, dry-run, apply in the run, collect scoped evidence, run the contract gate, then review changed slides. Source-guarded
```
set-run
```
/
```
replace-paragraph-text
```
edits require top-level operations and input-bound numeric shape IDs. Read
```
references/edit/inspect-and-edit.md
```
for paragraph guards and
```
textLayout
```
: ordinary edits respect autofit; geometry-preserving edits require the disclosed policy and final fit checks.
Connectors / groups / OLE / embedded models: read
```
references/edit/native-shape-editing.md
```
before geometry edits or duplication. Use native connection sites, retain owner-specific resources and reject unrepresentable transforms. A
```
preset-adjustments
```
finding uses an explicitly reviewed, document-bound repair from
```
references/runtime/troubleshooting.md
```
; it is not an automatic retry or an XSD failure.
Animation: inspect timing capabilities first; edit only the declared safe subset and preserve complex or unsupported timing. Read logical
```
kind
```
, all
```
targets[]
```
, and
```
timingSummary.mergeSafe
```
; effect counts and raw behavior metadata do not authorize edits.
```
references/content/animations.md
```
covers fixed whole-shape Box/Dissolve and their distinct preview limits. For basic effects, follow the disclosed repeat/autoReverse/restart/easing contract and its omitted/null/value update semantics. For imported group/pattern effects and Web slideshow controls, follow
```
references/content/animations.md
```
and its conditional playback reference. Shape deletion must preserve surviving timing conditions or reject. For P14 transitions, follow
```
references/content/animations.md
```
's per-kind schema and independent capability axes; inspect source/fallback timing separately and never equate authoring with playback certification. For Morph, use exact
```
!!
```
object names, run
```
morph-check
```
, and bind delivery evidence to the bundled PowerPoint playback probe when that probe is available.
Refurbish / translate: use
```
references/edit/refurbish-runner.md
```
/
```
references/translation/translation-runner.md
```
. The runner owns route, evidence, one canonical comparison, and publication; read only references it names on failure.
Chinese / East Asian font normalization: read
```
references/edit/font-normalization.md
```
. Discover
```
text/font-family-normalization
```
; use Chinese selection when Japanese/Korean must stay intact. The document-wide
```
set-font
```
op has no shape selector. Use its dedicated Edit Contract target, review inferred/ambiguous analysis, and verify all slides; saved geometry does not prove visual fit.
Template / cross-deck copy: edit inherited objects or use one transactional
```
slide-copy
```
; keep the native
```
pptx-slide-copy/v1
```
report as evidence, require a read-only
```
ready
```
preflight with current target/donor file SHA-256 values, normalized package fingerprints, explicit
```
template
```
/
```
slideSize
```
strategy, auditable
```
templates[]
```
outcomes, and no blockers. Default to
```
register-source
```
; choose
```
rebind-target
```
only when target inheritance is intentional. Before apply, run
```
cli/edit/copy-size-gate.mjs
```
as an independent SHA-bound defense;
```
require-match
```
never authorizes different slide sizes, and the workflow must not invent
```
opResults
```
or silently fit donor geometry. Verify independent notes/chart/workbook/classic palette ownership and copied navigation as described in
```
references/edit/template-following.md
```
; equal previews do not prove editing isolation.
Export / diff / preview / check: use
```
references/review/export-and-check.md
```
. Run semantic diff once on a stable candidate; only reliable changes are machine facts. Preview is for inspection, while the canonical visual-evidence decision remains the delivery authority. Discover each action's DPI bounds/default; after upgrades or calendar changes, use fresh rendering evidence as described in
```
references/review/fidelity-diagnosis.md
```
. For input quota or authorization failures, follow
```
references/runtime/troubleshooting.md#conversion-input-quotas-and-authorization-failures
```
; use the local CLI contract, keeping SDK product limits and proposed APIs separate.
ChartEx or structural risk: bind the specialized audit and PowerPoint-native evidence when required; an unavailable optional evidence route is disclosed risk, not invented proof.
Chart numeric precision: follow
```
references/content/charts.md
```
's numeric checks for long labels, extreme histogram ranges, signed percentage stacks and automatic axes/category fitting. Verify source values separately from painted or extracted labels; retain explicit bounds and real tail intervals. For doughnuts, follow its label-position restrictions and explicit hole-size default.
Chart rendering changes: use
```
references/content/charts.md
```
for automatic 2D/3D fitting, surface camera/paint, imported stacked ribbons, crossing-plane occlusion, signed-area end caps, hidden-axis semantics and gradient cuts. Keep Web texture evidence separate from native PDF evidence. For Latin word breaks, distributed paragraphs, table spacing or picture/arrow differences, use
```
references/review/fidelity-diagnosis.md
```
; parser model fields are not patch fields.
Existing Shape 3D / Text 3D: read the local-declaration guidance in
```
references/edit/inspect-and-edit.md
```
. Preserve owner-bound XML facts during neighboring edits; render improvements do not grant authoring support or PowerPoint fidelity. Chart 3D and embedded models have separate contracts.

以下路径仅用于选择入口 reference；具体细节以路由表为准。

Runtime license / 激活 / 续期 / 授权失败：
```
references/runtime/licensing.md
```
；为实际执行用户或环境安装，检查 admission，然后验证目标任务。
Create：
```
references/create/create-runner.md
```
和
```
references/create/design-quality.md
```
；即使是一句话 Express brief，也必须满足设计底线。正式或高风险工作还需遵循 Studio/design-lock references。runner 应先准备规范的 candidate 证据；实际完成 PNG review 后，使用其
```
--finalize --visual-review
```
阶段发布同一个与 hash 绑定的 candidate，不应再次渲染。
Edit 或 micro-edit：inspect/select、规范化 Edit Contract、在 run 中执行 dry-run 和 apply、收集限定范围的证据、运行 contract gate，然后 review 变更后的幻灯片。受 source guard 保护的
```
set-run
```
/
```
replace-paragraph-text
```
编辑需要顶层 operation 和绑定输入的数值型 shape ID。段落 guard 和
```
textLayout
```
请参阅
```
references/edit/inspect-and-edit.md
```
：普通编辑应遵循 autofit；需要保持几何结构的编辑必须使用已披露的策略并完成最终 fit 检查。
Connectors / groups / OLE / embedded models：进行几何编辑或复制前，读取
```
references/edit/native-shape-editing.md
```
。使用原生连接点，保留对象专属资源，并拒绝无法表示的变换。
```
preset-adjustments
```
finding 必须使用经过明确审查且绑定文档的修复方式，参见
```
references/runtime/troubleshooting.md
```
；它不是自动重试，也不是 XSD failure。
Animation：先检查 timing capability；仅编辑声明的安全子集，并保留复杂或不受支持的 timing。读取逻辑
```
kind
```
、全部
```
targets[]
```
和
```
timingSummary.mergeSafe
```
；effect 数量和原始行为 metadata 不能授权编辑。
```
references/content/animations.md
```
涵盖固定 whole-shape Box/Dissolve 及其不同的预览限制。基本效果应遵循已披露的 repeat/autoReverse/restart/easing contract 及其 omitted/null/value 更新语义。对导入的 group/pattern effect 和 Web slideshow controls，请遵循
```
references/content/animations.md
```
及其条件 playback reference。删除 shape 时必须保留仍需生效的 timing conditions，否则应拒绝操作。对 P14 transitions，请遵循
```
references/content/animations.md
```
中按 kind 划分的 schema 和相互独立的 capability axes；分别检查 source/fallback timing，绝不能将 authoring 等同于 playback certification。对 Morph，请使用精确的
```
!!
```
object name，运行
```
morph-check
```
，并将该证据绑定到捆绑的 PowerPoint playback probe（如果该 probe 可用）。
Refurbish / translate：使用
```
references/edit/refurbish-runner.md
```
/
```
references/translation/translation-runner.md
```
。runner 负责路由、证据、唯一的规范 comparison 和发布；仅在失败时读取其指定的 references。
中文 / East Asian 字体规范化：读取
```
references/edit/font-normalization.md
```
。发现
```
text/font-family-normalization
```
；在必须保留日文/韩文时使用中文选择方式。 document-wide
```
set-font
```
op 没有 shape selector。使用其专用 Edit Contract target，审查推断或歧义分析，并验证所有 slides；保存的几何结构不能证明视觉 fit。
Template / cross-deck copy：编辑继承对象或使用一次事务性的
```
slide-copy
```
；保留原生
```
pptx-slide-copy/v1
```
报告作为证据，要求只读
```
ready
```
preflight，并包含当前 target/donor 文件的 SHA-256 值、规范化 package fingerprints、明确的
```
template
```
/
```
slideSize
```
strategy、可审计的
```
templates[]
```
outcomes，且无 blockers。默认使用
```
register-source
```
；仅当目标继承关系是有意设计时才选择
```
rebind-target
```
。apply 前，运行
```
cli/edit/copy-size-gate.mjs
```
作为独立的 SHA 绑定防线；
```
require-match
```
绝不允许不同的 slide size，workflow 不得虚构
```
opResults
```
，也不得静默适配 donor geometry。按照
```
references/edit/template-following.md
```
验证独立的 notes/chart/workbook/classic palette ownership 和复制的 navigation；相同 preview 不能证明 editing isolation。
Export / diff / preview / check：使用
```
references/review/export-and-check.md
```
。对稳定 candidate 仅运行一次 semantic diff；只有可靠变化才能作为机器事实。Preview 用于检查，而规范的视觉证据决策仍是交付依据。发现每个 action 的 DPI bounds/default；升级或日历变化后，按照
```
references/review/fidelity-diagnosis.md
```
获取新的渲染证据。如遇输入配额或授权失败，请遵循
```
references/runtime/troubleshooting.md#conversion-input-quotas-and-authorization-failures
```
；使用本地 CLI contract，并区分 SDK 产品限制与拟议 API。
ChartEx 或结构风险：按要求绑定专业审计和 PowerPoint 原生证据；可选证据路径不可用时应将其披露为风险，而不是虚构证明。
Chart 数值精度：遵循
```
references/content/charts.md
```
中针对长标签、极端 histogram ranges、带符号百分比堆叠和自动 axis/category fitting 的数值检查。分别验证 source values 与绘制或提取出的 labels；保留明确边界和真实尾部区间。对 doughnut chart，遵循其 label-position 限制和明确的 hole-size default。
Chart 渲染变化：使用
```
references/content/charts.md
```
处理自动 2D/3D fitting、surface camera/paint、导入的 stacked ribbons、crossing-plane occlusion、带符号的 area end caps、hidden-axis semantics 和 gradient cuts。将 Web texture 证据与原生 PDF 证据分开。对于 Latin word breaks、distributed paragraphs、table spacing 或 picture/arrow 差异，使用
```
references/review/fidelity-diagnosis.md
```
；parser model fields 不是 patch fields。
现有 Shape 3D / Text 3D：读取
```
references/edit/inspect-and-edit.md
```
中的 local-declaration 指南。在相邻编辑中保留绑定 owner 的 XML 事实；渲染改进不能授予 authoring 支持或 PowerPoint fidelity。Chart 3D 和 embedded models 具有独立的 contract。

Skill Root

Skill 根目录

Treat the directory that contains this

SKILL.md

<skill-root>

. The published skill must be self-contained: scripts required by user workflows live in

<skill-root>/scripts/

, assets in

<skill-root>/assets/

, documentation in

<skill-root>/references/

, and benchmarks in

<skill-root>/benchmarks/

When wrapping xdoc or preparing asset inputs, follow

references/common-workflow.md

's filesystem-path rules. Resolve POSIX symlink/parent traversal before lexical normalization; keep relative assets rooted at the submitted patch/manifest directory, including when the file itself is a symlink.

Do not depend on repository-root

tools/

Justfile

, or files outside this skill directory in skill user paths. Repository-root tools are only for maintainers of this repository.

将包含此

SKILL.md

的目录视为

<skill-root>

。发布的 skill 必须自包含：用户 workflow 所需的脚本位于

<skill-root>/scripts/

，assets 位于

<skill-root>/assets/

，文档位于

<skill-root>/references/

，benchmarks 位于

<skill-root>/benchmarks/

。

包装 xdoc 或准备 asset 输入时，应遵循

references/common-workflow.md

的文件系统路径规则。先解析 POSIX symlink/parent traversal，再进行词法规范化；相对 assets 必须以提交的 patch/manifest 目录为根，即使文件本身是 symlink。

不要依赖 repository-root

tools/

、

Justfile

或 skill 用户路径中此目录以外的文件。Repository-root tools 仅供此 repository 的维护者使用。

Directly Supported Input Formats

直接支持的输入格式

When creating or modifying PPTX files, this skill can directly consume these inputs:

Natural-language briefs, chat content, organized outline text, or Markdown outlines.
HTML files, web URLs, PDFs: source material, not a one-step conversion from web page or PDF to finished deck. Normalize them to Markdown/text with
```
xdoc html2md
```
(HTML/URL) or
```
xdoc pdf extract-text
```
(PDF); the result is equivalent to a user-provided brief and must still go through outline -> content -> DeckKit -> validation. PDF text fidelity depends on the source file; scanned documents or embedded-font anomalies may cause missing characters or incorrect order. Any facts completed from that material must be written to
```
deck_lock.assumptions[]
```
. Store the raw ingestion result in the run directory, such as
```
source_brief.md
```
/
```
source_extract.txt
```
; see Source Ingestion in
```
references/common-workflow.md
```
for details.
```
.pptx
```
: reference decks, template decks,
```
slide-copy
```
sources,
```
template-fill
```
templates, or inputs to modify.
pptx-nova / xdoc workflow JSON:
```
outline.json
```
,
```
deck_lock.json
```
,
```
content.json
```
,
```
edit-contract.json
```
,
```
patch.json
```
,
```
assets_manifest.json
```
, brand/template profiles, and similar files. These are proprietary structured inputs generated by this skill or xdoc, or explicitly provided by the user and compliant with the matching schema; do not treat arbitrary
```
.json
```
files as directly usable PPTX content/patch inputs.
Data-binding JSON:
```
data.json
```
may be used as business data for
```
template-fill
```
/
```
bind-data
```
;
```
bindings.json
```
must comply with xdoc's binding structure and declare text/table/chart binding relationships.
CSV or JSON tabular data: use for table/chart/content data filling, as data for
```
set-table-data
```
or
```
bind-data
```
, or normalize into DeckKit
```
content.json
```
.
Resource files: images, logos, screenshots, SVG formula assets, and similar files. Register them in
```
assets_manifest.json
```
and reference them by asset id or
```
assetSource.path
```
.

创建或修改 PPTX 文件时，此 skill 可直接消费以下输入：

自然语言 brief、chat 内容、结构化 outline 文本或 Markdown outline。
HTML 文件、web URL、PDF：它们是 source material，而不是从 web page 或 PDF 一步转换为成品 deck 的输入。使用
```
xdoc html2md
```
（HTML/URL）或
```
xdoc pdf extract-text
```
（PDF）将其规范化为 Markdown/text；结果等同于用户提供的 brief，仍必须经过 outline -> content -> DeckKit -> validation。PDF text fidelity 取决于 source file；扫描文档或 embedded-font 异常可能导致字符缺失或顺序错误。从该材料补全的任何事实都必须写入
```
deck_lock.assumptions[]
```
。将原始 ingestion 结果保存在 run 目录中，例如
```
source_brief.md
```
/
```
source_extract.txt
```
；详情参见
```
references/common-workflow.md
```
中的 Source Ingestion。
```
.pptx
```
：reference deck、template deck、
```
slide-copy
```
source、
```
template-fill
```
template，或待修改的输入。
pptx-nova / xdoc workflow JSON：
```
outline.json
```
、
```
deck_lock.json
```
、
```
content.json
```
、
```
edit-contract.json
```
、
```
patch.json
```
、
```
assets_manifest.json
```
、brand/template profiles 等。这些是此 skill 或 xdoc 生成的专有结构化输入，或由用户提供且符合对应 schema 的输入；不要将任意
```
.json
```
文件视为可直接使用的 PPTX 内容或 patch 输入。
Data-binding JSON：
```
data.json
```
可作为
```
template-fill
```
/
```
bind-data
```
的业务数据；
```
bindings.json
```
必须符合 xdoc 的 binding structure，并声明 text/table/chart binding relationships。
CSV 或 JSON tabular data：用于 table/chart/content data filling，作为
```
set-table-data
```
或
```
bind-data
```
的数据，或规范化为 DeckKit
```
content.json
```
。
Resource 文件：images、logos、screenshots、SVG formula assets 等。在
```
assets_manifest.json
```
中注册，并通过 asset id 或
```
assetSource.path
```
引用。

Task Routing

任务路由

Determine the task type first, then read the corresponding files:

For a rendering discrepancy or a preview regression after upgrading xdoc, also read

references/review/fidelity-diagnosis.md

before changing authored content or layout. This includes columns/Unicode breaks, tabs/autofit anchors, font/language/placeholder inheritance, merged borders, chart domains/direction, resized cached SmartArt, Web text clipping, missing/stale reflections, and Shape 3D scale offsets; identify the actual renderer and its fallback before treating the symptom as a deck defect.

User intent	Required references	Read conditionally
Install/renew a Runtime license, activate xdoc, or diagnose authorization failures	`references/runtime/licensing.md`	`references/runtime/schema-discovery.md` for exact action/report contracts; `references/runtime/daemon-sessions.md` when the execution environment differs
Simple prompt / wants speed / default new deck generation	`references/create/create-runner.md`	Follow its preparation routes to `references/create/create-express.md` , `references/create/deckkit-mode.md` , or `references/create/narrative-quality.md` only when needed
Investor / client / board / Studio / needs precise control	`references/common-workflow.md` , `references/create/deckkit-mode.md` , `references/create/create-studio.md` , `references/create/design-lock-and-assets.md` , `references/create/narrative-quality.md`	`references/review/visual-qa-and-asset-slots.md` , `references/create/rich-deck-patterns.md`
Strictly follow an existing PPTX template / adapt content to a template	`references/common-workflow.md` , `references/edit/template-following.md` , `references/edit/edit-mode.md`	`references/create/design-lock-and-assets.md` , `references/edit/inspect-and-edit.md`
Reference PPTX + new outline to generate a new deck	`references/common-workflow.md` , `references/create/reference-create.md` , `references/create/deckkit-mode.md`	`references/create/template-library.md`
Polish / refurbish an existing PPTX while preserving original content and changing style	`references/edit/refurbish-runner.md`	Only the references named by `refurbish-plan.json.requiredReferences[]` after route selection
Small text/notes/footer/metadata edit	`references/common-workflow.md` , `references/edit/edit-contract.md` , `references/edit/micro-edit-cheatsheet.md`	If selectors are ambiguous or complex image/multi-object edits are involved, then read `references/edit/edit-mode.md` , `references/edit/inspect-and-edit.md`
Continue the same deck with an explicit future/carryover rule	`references/common-workflow.md` , `references/edit/session-rules.md` , `references/edit/edit-contract.md`	`references/edit/edit-mode.md` , `references/edit/inspect-and-edit.md`
Translate an existing `.pptx` while preserving original layout	`references/translation/translation-runner.md`	Follow its preparation/failure routes into `references/translation/translation-mode.md` ; load charts/tables only when detected
Modify an existing `.pptx`	`references/common-workflow.md` , `references/edit/edit-contract.md` , `references/edit/edit-mode.md` , `references/edit/inspect-and-edit.md`	`references/edit/patch-ops-cheatsheet.md`
Edit connector/group/OLE/model geometry or duplicate native objects	Existing-deck edit references plus `references/edit/native-shape-editing.md`	`references/runtime/troubleshooting.md` for guarded preset repairs
Add/modify/delete animations or transitions	`references/common-workflow.md` , `references/edit/edit-mode.md` , `references/content/animations.md` , `references/edit/inspect-and-edit.md`	`references/edit/patch-ops-cheatsheet.md` ; for complex timing, read `references/edit/control-flow-and-raw-xml.md` only for risk judgment
Data + template / JSON filling	`references/common-workflow.md` , `references/content/data-driven.md`	`references/content/tables.md` , `references/content/charts.md`
Brand conversion / brand check	`references/common-workflow.md` , `references/content/styles-and-themes.md`	`references/create/template-library.md`
Unify Chinese / East Asian font families across an existing deck	`references/common-workflow.md` , `references/edit/font-normalization.md` , `references/edit/edit-contract.md`	`references/content/styles-and-themes.md` for local font or theme-only changes
Only export PDF/PNG/MD/JSON, extract, check, or compare two PPTX files	`references/common-workflow.md` , `references/review/export-and-check.md`	No need to read creation/edit docs unless the user then asks for fixes
Long-task split / resume generation	`references/common-workflow.md` , `references/runtime/resume-split-mode.md`	References for the original task type
Formulas, charts, tables, raw XML	Current task references plus the matching `references/content/formulas.md` / `references/content/charts.md` / `references/content/tables.md` / `references/edit/control-flow-and-raw-xml.md`	`references/runtime/troubleshooting.md`

When the user provides an HTML file, web URL, or PDF as material, first normalize it to Markdown/text with xdoc according to Source Ingestion in

references/common-workflow.md

, then route by the real task type (create / data / edit) in the table above; ingestion itself does not change the target task type. If the user only wants HTML/URL/PDF converted to Markdown/text without a deck, follow

references/review/export-and-check.md

首先确定任务类型，然后读取对应文件：

对于升级 xdoc 后出现的渲染差异或 preview regression，在更改 authored content 或 layout 前，还应读取

references/review/fidelity-diagnosis.md

。这包括 columns/Unicode breaks、tabs/autofit anchors、font/language/placeholder inheritance、merged borders、chart domains/direction、resized cached SmartArt、Web text clipping、missing/stale reflections 和 Shape 3D scale offsets；应先识别实际 renderer 及其 fallback，再判断症状是否属于 deck defect。

用户意图	必需 references	按需读取
安装/续期 Runtime license、激活 xdoc 或诊断授权失败	`references/runtime/licensing.md`	`references/runtime/schema-discovery.md` 用于获取准确的 action/report contract；执行环境不同时读取 `references/runtime/daemon-sessions.md`
简单 prompt / 希望速度优先 / 默认生成新 deck	`references/create/create-runner.md`	仅在需要时按照其 preparation routes 读取 `references/create/create-express.md` 、 `references/create/deckkit-mode.md` 或 `references/create/narrative-quality.md`
Investor / client / board / Studio / 需要精确控制	`references/common-workflow.md` 、 `references/create/deckkit-mode.md` 、 `references/create/create-studio.md` 、 `references/create/design-lock-and-assets.md` 、 `references/create/narrative-quality.md`	`references/review/visual-qa-and-asset-slots.md` 、 `references/create/rich-deck-patterns.md`
严格遵循现有 PPTX template / 将内容适配到 template	`references/common-workflow.md` 、 `references/edit/template-following.md` 、 `references/edit/edit-mode.md`	`references/create/design-lock-and-assets.md` 、 `references/edit/inspect-and-edit.md`
Reference PPTX + 新 outline 生成新 deck	`references/common-workflow.md` 、 `references/create/reference-create.md` 、 `references/create/deckkit-mode.md`	`references/create/template-library.md`
在保留原始内容的同时美化/改造现有 PPTX	`references/edit/refurbish-runner.md`	路由选择后，仅读取 `refurbish-plan.json.requiredReferences[]` 指定的 references
小型 text/notes/footer/metadata 编辑	`references/common-workflow.md` 、 `references/edit/edit-contract.md` 、 `references/edit/micro-edit-cheatsheet.md`	如果 selector 有歧义或涉及复杂 image/multi-object 编辑，再读取 `references/edit/edit-mode.md` 、 `references/edit/inspect-and-edit.md`
根据明确的 future/carryover 规则继续处理同一 deck	`references/common-workflow.md` 、 `references/edit/session-rules.md` 、 `references/edit/edit-contract.md`	`references/edit/edit-mode.md` 、 `references/edit/inspect-and-edit.md`
在保留原 layout 的同时翻译现有 `.pptx`	`references/translation/translation-runner.md`	按照其 preparation/failure routes 读取 `references/translation/translation-mode.md` ；仅在检测到 charts/tables 时读取对应文档
修改现有 `.pptx`	`references/common-workflow.md` 、 `references/edit/edit-contract.md` 、 `references/edit/edit-mode.md` 、 `references/edit/inspect-and-edit.md`	`references/edit/patch-ops-cheatsheet.md`
编辑 connector/group/OLE/model geometry 或复制原生对象	现有 deck edit references 加上 `references/edit/native-shape-editing.md`	需要受保护的 preset 修复时读取 `references/runtime/troubleshooting.md`
添加、修改或删除 animations 或 transitions	`references/common-workflow.md` 、 `references/edit/edit-mode.md` 、 `references/content/animations.md` 、 `references/edit/inspect-and-edit.md`	`references/edit/patch-ops-cheatsheet.md` ；仅在进行复杂 timing 的风险判断时读取 `references/edit/control-flow-and-raw-xml.md`
Data + template / JSON filling	`references/common-workflow.md` 、 `references/content/data-driven.md`	`references/content/tables.md` 、 `references/content/charts.md`
Brand conversion / brand check	`references/common-workflow.md` 、 `references/content/styles-and-themes.md`	`references/create/template-library.md`
统一现有 deck 中的中文 / East Asian font families	`references/common-workflow.md` 、 `references/edit/font-normalization.md` 、 `references/edit/edit-contract.md`	`references/content/styles-and-themes.md` ，用于仅处理 local font 或 theme-only changes
仅导出 PDF/PNG/MD/JSON，或 extract、check、比较两个 PPTX 文件	`references/common-workflow.md` 、 `references/review/export-and-check.md`	除非用户随后要求修复，否则无需读取 creation/edit docs
Long-task split / resume generation	`references/common-workflow.md` 、 `references/runtime/resume-split-mode.md`	原始任务类型对应的 references
Formulas、charts、tables、raw XML	当前任务 references，加上匹配的 `references/content/formulas.md` / `references/content/charts.md` / `references/content/tables.md` / `references/edit/control-flow-and-raw-xml.md`	`references/runtime/troubleshooting.md`

当用户提供 HTML 文件、web URL 或 PDF 作为材料时，应先按照

references/common-workflow.md

中的 Source Ingestion 使用 xdoc 将其规范化为 Markdown/text，再根据实际任务类型（create / data / edit）进入上表路由；ingestion 本身不会改变目标任务类型。如果用户只想将 HTML/URL/PDF 转换为 Markdown/text，而不生成 deck，请遵循

references/review/export-and-check.md

。

Mode Detection

模式检测

Express / Studio: Speed and a short brief select Express; formal, brand-sensitive, asset-heavy, long, or confirmation-sensitive work selects Studio and locks outline/design first.
Template / Reference Create: Template following edits copied/inherited objects; Reference Create treats the reference as read-only style/layout evidence for new content.
Refurbish: Preserve the source as read-only content truth, apply the selected DeckKit visibly to editable objects, and never rasterize, downgrade content, or silently switch DeckKits.
Edit / Micro Edit / Animation: Inspect before patching. Micro edits use the short contract path; animation changes stay inside the capability-declared safe subset. Use reported part identities and current inspect order for slide/layout/master selectors; filename suffixes and ZIP order are not selector indices. See
```
references/edit/inspect-and-edit.md
```
.
Translation: Copy, replace visible text in place, and preserve styling/layout semantics. Repair by compressing text, then minimally reducing font, then geometry only with proven whitespace. Changed multi-column text requires its bound human-review gate; real overflow/overlap/edge findings and rendered chart-title/page-bound collisions never receive a review override. The translation runner owns coverage, style/vision audits, comparison parts, and SHA-256 publication binding.
Data-driven / Export-Check: Data plus template selects
```
references/content/data-driven.md
```
; conversion, preview, extraction, or checking alone must not mutate the PPTX.

Express / Studio：速度优先和简短 brief 选择 Express；正式、品牌敏感、asset 密集、篇幅长或需要确认的工作选择 Studio，并先锁定 outline/design。
Template / Reference Create：Template following 编辑复制或继承的对象；Reference Create 将 reference 作为新内容的只读 style/layout 证据。
Refurbish：将 source 作为只读内容事实来源，将所选 DeckKit 可见地应用到可编辑对象；绝不栅格化、降级内容或静默切换 DeckKits。
Edit / Micro Edit / Animation：patch 前先 inspect。Micro edit 使用简短 contract 路径；animation 变更必须保持在 capability 声明的安全子集内。使用报告中的 part identities 和当前 inspect order 选择 slide/layout/master selector；文件名后缀和 ZIP 顺序不是 selector 索引。参见
```
references/edit/inspect-and-edit.md
```
。
Translation：复制并原位替换可见文本，同时保留 styling/layout semantics。修复时依次压缩文本、轻微减小字体，然后仅在有明确空白证据时调整 geometry。发生变化的多栏文本必须通过绑定的 human-review gate；真实的 overflow/overlap/edge findings 和渲染后的 chart-title/page-bound collisions 绝不能获得 review override。translation runner 负责 coverage、style/vision audits、comparison parts 和 SHA-256 publication binding。
Data-driven / Export-Check：Data 加 template 选择
```
references/content/data-driven.md
```
；仅进行 conversion、preview、extraction 或 checking 时，绝不能修改 PPTX。

Feedback Mode

Feedback 模式

If the user prompt contains explicit feedback intent such as

need feedback

, English feedback phrases, or equivalent Chinese phrases meaning "give feedback", "needs feedback", or "any usage feedback", read

references/review/feedback-mode.md

. Once Feedback Mode is triggered, first write

skill-feedback.md

in the current run directory. Create, Refurbish, and Translation feedback must include the workflow's exact seven-dimension 0-10 process scorecard and a correctly weighted overall score, printed in the final response as required by Completion Summary. Before the final response, run the feedback gate with

--workflow create|refurbish|translation|other

: if the original prompt is available, use

node <skill-root>/scripts/cli/review/feedback-gate.mjs --run-dir <run-dir> --prompt-file <prompt.txt> --workflow <workflow> --strict --overwrite --json > <run-dir>/feedback-gate.json

; if the prompt was not saved but the user feedback request is known, use

--require-feedback

. If the gate fails, add real feedback or correct the scorecard before sending the final response.

During xdoc PPTX creation or editing in Feedback Mode, investigate newly observed, unexpected rendering problems as possible product bugs. Compare with an existing PowerPoint-native screenshot when available; otherwise, if the optional prerequisites are available, try

<skill-root>/scripts/cli/office/powerpoint-snapshot.nu

on the affected slides and compare. Record the evidence and every confirmed new problem in

skill-feedback.md

, and report all of them in the final task summary even when there are more than three feedback items. If native verification is unavailable or inconclusive, label the observation unverified rather than claiming a confirmed product bug. Follow

references/review/feedback-mode.md

for the evidence and reporting details.

如果用户 prompt 包含明确反馈意图，例如

need feedback

、英语反馈短语，或含义等同于“give feedback”“needs feedback”或“any usage feedback”的中文短语，请读取

references/review/feedback-mode.md

。Feedback 模式触发后，首先在当前 run 目录中写入

skill-feedback.md

。Create、Refurbish 和 Translation 反馈必须包含 workflow 规定的七维度 0-10 流程评分表和正确加权的总分，并按照 Completion Summary 的要求打印在最终回复中。在最终回复前，运行反馈 gate：

node <skill-root>/scripts/cli/review/feedback-gate.mjs --run-dir <run-dir> --prompt-file <prompt.txt> --workflow <workflow> --strict --overwrite --json > <run-dir>/feedback-gate.json

；如果原始 prompt 未保存，但已知用户反馈请求，则使用

--require-feedback

。如果 gate 失败，应补充真实反馈或修正评分表后再发送最终回复。

在 Feedback 模式下执行 xdoc PPTX creation 或 editing 时，应将新观察到的异常渲染问题作为潜在产品 bug 进行调查。如有现有 PowerPoint-native screenshot，应与其比较；否则，如果可选前置条件可用，可对受影响的 slides 尝试运行

<skill-root>/scripts/cli/office/powerpoint-snapshot.nu

并进行比较。将证据及每个已确认的新问题记录在

skill-feedback.md

中，即使问题超过三个，也必须在最终任务摘要中全部报告。如果无法完成 native verification 或结果不确定，应将该观察标记为 unverified，而不是声称已确认产品 bug。遵循

references/review/feedback-mode.md

中的证据和报告要求。

Common Creation Hard Rules

通用创建硬性规则

These rules apply to all new decks, including Express and Studio:

Read
```
references/create/design-quality.md
```
before selecting a DeckKit. Infer audience/mode, commit to a content-led visual idea, and inspect actual eligible-kit examples; a readiness score or absence of overflow is not evidence of aesthetic fit. Respect the user's pinned visual world.
Review the rendered design as well as its mechanics. Write candidate/manifest-bound
```
design_review.json
```
with slide-specific observations and a weakest-page assessment; pass it as
```
--design-review
```
when recording the Create visual review. Repair unresolved craft failures before publication. The validator checks the judgment record, not beauty; never invent observations.
Generate or normalize
```
outline.json
```
first, then write
```
deck_lock.json
```
; do not jump directly from prompt to patch.

Default to DeckKit-first:

content.json -> DeckKit -> patch -> xdoc -> PPTX -> validation

Persuasive decks for formal reports, clients, investors, boards, roadshows, strategy, product-platform, and similar contexts must read
```
references/create/narrative-quality.md
```
, lock
```
deckProfile
```
, and per-slide
```
claimTitle
```
/
```
proofObject
```
/
```
rhythm
```
/
```
layoutIntent
```
/
```
visualDensity
```
in
```
deck_lock.json
```
, then write
```
narrative_quality_review.json
```
after PNG review.
Before writing
```
content.json
```
or a manual patch, compare each slide against
```
deck_lock.slides[]
```
and confirm page type, rhythm, structural intent, density, and proof object have not drifted from memory. If mismatched, fix the lock or content source first instead of patching around it.
Non-appendix slides should have a clear point of view or direction. Main titles/subtitles should be short, scannable, and fitted to DeckKit slots. Avoid pure topic labels such as
```
Product Overview
```
,
```
Market Analysis
```
, or
```
Roadmap
```
. Put the full conclusion in
```
claimTitle
```
; when needed, move it into the subtitle, callout, or
```
proofObject
```
. Do not sacrifice layout merely to make the displayed title conclusion-like.
Main titles and subtitles do not use terminal periods by default. Use question marks/exclamation marks only when the tone or interactive intent is explicit.
If the user-provided outline explicitly specifies the main title or subtitle, that wording takes priority. Do not silently rewrite it to be more conclusion-like, shorter, or period-free. Record the source in
```
titleSource: "user"
```
/
```
subtitleSource: "user"
```
, and adjust only for hard layout overflow or when the user asks for polishing; explain the tradeoff.
Automatic selection for delivery may use only DeckKits with
```
readiness in ["production", "default"]
```
.
When a production/default DeckKit is available, do not use
```
deck-generator-template.mjs
```
as the default delivery path.
If no usable DeckKit exists, a page type is missing, or component structure must change, create/extend the DeckKit before delivery.
When referencing templates, brands, or layouts, write
```
deck_lock.templateFusion
```
in semantic layers:
```
brand
```
/
```
layout
```
/
```
deck
```
. Do not guess conflicts and overrides temporarily inside the generator.
If the source outline contains only titles or blanks, factual content completed by AI must be written to
```
deck_lock.assumptions[]
```
; do not disguise unverified competitors, metrics, cases, or market facts as user-provided content.
If the final creation output path already existed before the task began, ask the user to rename, delete, or choose a different path first. Do not overwrite the final path with
```
--overwrite
```
.
For creation tasks,
```
vision-check
```
```
summary.bySeverity.high
```
and
```
summary.bySeverity.medium
```
must both be 0, and the full-package semantic evidence must be internally consistent with
```
semanticSummary.passed=true
```
,
```
semanticSummary.issueCount=0
```
, at least 82 source rules / 81 normalized rules, and
```
semanticIssues=[]
```
. Dry-run and apply must each disclose
```
semanticIssues=[]
```
; a missing semantic field is not proof of safety.
PNG/contact sheet visual review cannot be skipped. It catches real line breaks, character overlap, contrast, decorative occlusion, page-number rhythm, and composition issues that dry-run and
```
vision-check
```
cannot see.

以下规则适用于所有新 deck，包括 Express 和 Studio：

选择 DeckKit 前必须读取
```
references/create/design-quality.md
```
。推断受众/模式，确立由内容驱动的视觉构想，并检查实际符合条件的 kit 示例；readiness score 或没有 overflow 不能证明 aesthetic fit。尊重用户明确指定的视觉方向。
应同时 review 渲染后的设计与机械正确性。编写与 candidate/manifest 绑定的
```
design_review.json
```
，其中包含逐页观察和最弱页面评估；记录 Create visual review 时，将其作为
```
--design-review
```
传入。发布前修复尚未解决的 craft failure。validator 检查的是判断记录，而非美感；绝不能虚构观察。
首先生成或规范化
```
outline.json
```
，然后编写
```
deck_lock.json
```
；不要直接从 prompt 跳到 patch。

默认采用 DeckKit-first：

content.json -> DeckKit -> patch -> xdoc -> PPTX -> validation

。

面向正式报告、客户、investors、boards、roadshows、strategy、product-platform 等场景的说服型 deck，必须读取
```
references/create/narrative-quality.md
```
，锁定
```
deckProfile
```
，并在
```
deck_lock.json
```
中为每页设置
```
claimTitle
```
/
```
proofObject
```
/
```
rhythm
```
/
```
layoutIntent
```
/
```
visualDensity
```
，然后在 PNG review 后写入
```
narrative_quality_review.json
```
。
编写
```
content.json
```
或手动 patch 前，将每页与
```
deck_lock.slides[]
```
对照，确认 page type、rhythm、structural intent、density 和 proof object 未发生偏移。如不匹配，应先修正 lock 或 content source，而不是绕过问题直接 patch。
非 appendix slides 应具有清晰的观点或方向。主标题/副标题应简短、可扫描，并适配 DeckKit slots。避免使用纯主题标签，如
```
Product Overview
```
、
```
Market Analysis
```
或
```
Roadmap
```
。将完整结论放入
```
claimTitle
```
；必要时移入 subtitle、callout 或
```
proofObject
```
。不要仅为使标题更像结论而牺牲 layout。
主标题和副标题默认不使用句末句号。仅在语气或交互意图明确时使用问号/感叹号。
如果用户提供的 outline 明确指定主标题或副标题，该措辞优先。不得静默将其改写为更像结论、更短或无句号的形式。应在
```
titleSource: "user"
```
/
```
subtitleSource: "user"
```
中记录来源，仅在出现硬性 layout overflow 或用户要求 polish 时调整，并说明权衡。
自动交付选择只能使用 readiness 为
```
production
```
或
```
default
```
的 DeckKits。
当存在 production/default DeckKit 时，不要将
```
deck-generator-template.mjs
```
作为默认交付路径。
如果没有可用 DeckKit、缺少 page type，或必须更改 component structure，应先创建/扩展 DeckKit，再交付。
引用 templates、brands 或 layouts 时，在
```
deck_lock.templateFusion
```
中按
```
brand
```
/
```
layout
```
/
```
deck
```
语义层编写。不要在 generator 中临时猜测冲突和 override。
如果 source outline 仅包含标题或空白，由 AI 补全的事实内容必须写入
```
deck_lock.assumptions[]
```
；不得将未经验证的竞争对手、metrics、cases 或 market facts 伪装成用户提供的内容。
如果最终 creation 输出路径在任务开始前已存在，应先让用户重命名、删除或选择其他路径。不得使用
```
--overwrite
```
覆盖最终路径。
对于 creation 任务，
```
vision-check
```
的
```
summary.bySeverity.high
```
和
```
summary.bySeverity.medium
```
必须均为 0，且完整 package semantic evidence 必须满足
```
semanticSummary.passed=true
```
、
```
semanticSummary.issueCount=0
```
、至少 82 条 source rules / 81 条 normalized rules，并满足
```
semanticIssues=[]
```
。dry-run 和 apply 必须各自披露
```
semanticIssues=[]
```
；缺少 semantic field 不能证明安全。
PNG/contact sheet visual review 不可跳过。它能发现 dry-run 和 vision-check 无法发现的真实换行、字符重叠、对比度、装饰遮挡、page-number rhythm 和构图问题。

Common Edit Hard Rules

通用编辑硬性规则

These rules apply to modifying existing PPTX files:

Treat the input deck as read-only by default. Inspect first, then dry-run, then write intermediate files in the run directory.
Keep sidecars distinct from the primary PPTX and every input. On an output failure, inspect publication facts before recovery:
```
primaryOutputPublished:true
```
means the PPTX already reached disk even though the command failed. Preserve both paths and the report; never automatically replay or add
```
--overwrite
```
. See
```
references/common-workflow.md
```
and
```
references/runtime/troubleshooting.md
```
for sidecar recovery, including creation tasks.
Do not edit objects by guessing selectors. When the target object is unclear, first narrow candidates with
```
xdoc pptx select input.pptx --query '{"textRegex":"..."}' --json
```
or a query file, then write the patch. Check dry-run
```
resolvedSelectors[]
```
; for an ambiguous selector, inspect
```
suggestions[].remediation
```
and follow
```
references/runtime/troubleshooting.md
```
. Capture the first submission before an automatic retry, validate the complete kind/target shape against retained request/input/asset snapshots, and revalidate and authorize. A replacement request runs once from the original input; document remediation applies only its repair patch to the exact diagnosed bytes. Missing context or
```
remediationUnavailable
```
never permits a guessed replay.
After inspect/select resolves the targets, normalize
```
edit-contract.json
```
before patch/apply. Bind each target to its patch
```
opIndexes[]
```
, expected categories/values, allowed changes, preserve policy, and required evidence. After the stable candidate is produced, require
```
edit-contract-gate.json.agentGate.passed=true
```
before publication. Translation and Refurbish keep their stronger specialized contracts instead of replacing them with this generic gate.
Only create
```
session-rules.json
```
from an explicit current-deck future/carryover instruction. Resolve it from a structured
```
session-operation.json
```
; never execute free-form
```
appliesWhen
```
text. Pass a successful
```
session-rules-resolution.json
```
to the Edit Contract normalizer so rule-owned targets and preserve requirements are hash-bound and verified by the final contract gate. If no active rule applies, continue without extra evidence or user confirmation. Advance the rules to a new revision only after the candidate passes and is accepted.
After post-apply evidence is stable, generate
```
evidence-manifest.json
```
to bind the candidate SHA-256 and exact evidence-file hashes. The gate must reject a missing/stale manifest, including when the candidate is overwritten at the same path.
Visible text-only edits that must preserve existing formatting require
```
style-diff
```
evidence. Whole-frame
```
set-text-frame
```
may erase run styling even when dry-run, semantic diff, and vision-check appear clean; use an inspect-proven run/text-node preserving edit or treat
```
target-text-style-changed
```
as a blocker.
Visible edits require changed-scope
```
vision-diff
```
by default. Block new or worsened high/medium issues. Dry-run/apply
```
semanticIssues[]
```
are a full-package before/after issue delta and must contain no regression introduced by the edit; the edit-contract gate fails closed when that evidence is missing or non-empty. Candidate-only
```
vision-check.semanticIssues[]
```
scans the full package—even with
```
--slides
```
—so treat it as diagnostic evidence and disclose inherited legacy-deck semantic debt instead of turning it into a false edit blocker.
When the user requests accessibility, inclusive-design, screen-reader, or alt-text validation, run
```
xdoc check
```
with
```
a11y
```
named explicitly (or
```
--checks all
```
, which includes it); the default
```
--checks
```
list does not. Gate on
```
checks.a11y.status
```
and
```
summary.riskLevel
```
, not exit code. A violation blocks the requested accessibility claim;
```
inconclusive
```
requires rendered/manual review and remains unproven. Never apply an a11y
```
patchTemplate
```
unchanged: it is a manual placeholder and has no executable remediation target.
For strict template following, edit copied/inherited objects or template placeholders. Do not use new text boxes, translucent rectangles, or whole-page image overlays to hide old content and manufacture a page that "looks right".
When copying source slides or filling templates, explicitly fill or delete empty structural placeholders such as title/body/dt/sldNum/ftr. Do not leave empty placeholders in PowerPoint edit state just because they are invisible in PNG output. If an actionable finding is intentionally required by the deck's semantics, preserve it only through a source-hash-bound
```
pptx-nova-review-policy/v1
```
rule using the exact
```
reviewIdentity.sha256
```
from
```
layout-final.json
```
; never use a global boolean exception.
Native
```
pptx-slide-copy/v1
```
must disclose
```
preflight.strategy.slideSize: "require-match"
```
; mismatched donor/target dimensions are a core blocker, not a renderer concern. Retain the bundled copy-size gate as independent file-bound evidence, and stop if either native preflight or the gate reports a mismatch. Do not scale implicitly or move this policy into Viewer/PDF rendering.
Identity assets such as logos, client marks, product screenshots, headshots, app icons, and third-party brand graphics must come from user-provided files, source-deck assets whose reuse is allowed, official verifiable sources, or registered authorized sources. When this cannot be confirmed, use text/native shapes instead of generating pseudo-official assets.
When using external, reused, generated, or formula assets,
```
assets_manifest.json
```
must record
```
status
```
,
```
source.kind
```
,
```
licenseRisk
```
, and PPTX usage slots.
```
missing
```
/
```
needs-user
```
/
```
forbidden
```
blocks delivery.
If the user asks for in-place modification, still complete validation in the run directory first, then write back only according to the user's explicit intent.
Preserve SmartArt, macros, complex animations, and unsupported objects by default. Edit animations only inside
```
inspect.animations[].editable
```
or the creation-safe subset explicitly supported by the current schema. Explain the boundary when they cannot be edited.
PowerPoint Repair blocks delivery: Any candidate PPTX that shows "PowerPoint found a problem with content", a
```
Repair
```
button, automatic repair after opening, or an equivalent corruption warning is a failed candidate. Do not deliver it, and do not treat the PowerPoint-repaired file as a final artifact without root cause. Retain the triggering candidate PPTX, patch, dry-run/apply reports, and minimal reproduction evidence. Locate the specific op / OOXML part / structural order issue before generating a new candidate.
For high-risk edits involving charts, tables, raw OOXML, relationship packages, embedded workbooks, themes/styles, and similar structures,
```
xdoc check
```
,
```
vision-check
```
, and PNG preview alone do not prove structural safety. Also perform OPC/OOXML structural validation, such as
```
unzip -t
```
, XML well-formedness checks, and targeted semantic audits for chart axis/legend/data-label/gridline child element order, relationship targets, embedded workbook synchronization, and similar risks. If an op generates a PowerPoint Repair file for a certain input class, make that op fail at the xdoc/pptx-gen source instead of generating problematic content.

以下规则适用于修改现有 PPTX 文件：

默认将输入 deck 视为只读。先 inspect，再 dry-run，然后将中间文件写入 run 目录。
sidecar 必须与主 PPTX 及所有输入保持区分。输出失败时，先检查 publication facts 再恢复：
```
primaryOutputPublished:true
```
表示即使命令失败，PPTX 也已写入磁盘。保留两个路径和报告；绝不能自动 replay 或添加
```
--overwrite
```
。sidecar recovery（包括 creation 任务）参见
```
references/common-workflow.md
```
和
```
references/runtime/troubleshooting.md
```
。
不要通过猜测 selector 编辑对象。目标对象不明确时，先使用
```
xdoc pptx select input.pptx --query '{"textRegex":"..."}' --json
```
或 query file 缩小候选范围，然后编写 patch。检查 dry-run 的
```
resolvedSelectors[]
```
；如果 selector 有歧义，检查
```
suggestions[].remediation
```
并遵循
```
references/runtime/troubleshooting.md
```
。在自动重试前捕获首次提交，将完整的 kind/target shape 与保留的 request/input/asset snapshots 对照验证，然后重新验证并授权。replacement request 仅从原始输入运行一次；document remediation 仅将 repair patch 应用于确切诊断出的 bytes。缺少 context 或出现
```
remediationUnavailable
```
时，绝不能猜测并 replay。
inspect/select 解析目标后，在 patch/apply 前规范化
```
edit-contract.json
```
。将每个 target 绑定到 patch
```
opIndexes[]
```
、预期 categories/values、allowed changes、preserve policy 和 required evidence。稳定 candidate 生成后，发布前必须满足
```
edit-contract-gate.json.agentGate.passed=true
```
。Translation 和 Refurbish 应保留其更严格的专用 contract，而不是替换为该通用 gate。
仅根据当前 deck 明确的 future/carryover 指令创建
```
session-rules.json
```
。通过结构化
```
session-operation.json
```
解析；绝不能执行自由格式的
```
appliesWhen
```
文本。将成功的
```
session-rules-resolution.json
```
传给 Edit Contract normalizer，使规则所属 targets 和 preserve requirements 与 hash 绑定，并由最终 contract gate 验证。如果没有 active rule 适用，则无需额外 evidence 或用户确认即可继续。仅在 candidate 通过并被接受后，才能将规则推进到新 revision。
post-apply evidence 稳定后，生成
```
evidence-manifest.json
```
，将 candidate SHA-256 与确切 evidence-file hashes 绑定。gate 必须拒绝缺失或过期的 manifest，包括在同一路径覆盖 candidate 的情况。
需要保留现有格式的纯可见文本编辑必须提供
```
style-diff
```
evidence。即使 dry-run、semantic diff 和 vision-check 看起来正常，whole-frame
```
set-text-frame
```
仍可能清除 run styling；应使用 inspect 证明可保留 run/text node 的编辑方式，否则将
```
target-text-style-changed
```
视为 blocker。
可见编辑默认需要 changed-scope
```
vision-diff
```
。阻止新增或加剧的 high/medium issues。dry-run/apply 的
```
semanticIssues[]
```
是完整 package 的前后差异，不得包含编辑引入的 regression；缺少该证据或其非空时，edit-contract gate 必须 fail closed。Candidate-only
```
vision-check.semanticIssues[]
```
会扫描完整 package，即使使用了
```
--slides
```
；应将其视为诊断证据，并披露继承自旧 deck 的 semantic debt，而不能将其变成错误的 edit blocker。
当用户要求 accessibility、inclusive-design、screen-reader 或 alt-text validation 时，明确运行带
```
a11y
```
的
```
xdoc check
```
（或使用包含它的
```
--checks all
```
）；默认
```
--checks
```
列表不包含它。以
```
checks.a11y.status
```
和
```
summary.riskLevel
```
为准，而不是 exit code。violation 会阻止相应的 accessibility claim；
```
inconclusive
```
需要 rendered/manual review，且仍视为未经证明。绝不能原样应用 a11y
```
patchTemplate
```
；它是手动 placeholder，不具备可执行的 remediation target。
严格遵循 template 时，应编辑复制或继承的对象，或编辑 template placeholders。不要使用新的 text boxes、半透明 rectangles 或 whole-page image overlays 隐藏旧内容并制造一个“看起来正确”的页面。
复制 source slides 或填充 templates 时，应显式填充或删除空的 structural placeholders，例如 title/body/dt/sldNum/ftr。绝不能仅因 PNG 输出中不可见，就在 PowerPoint edit state 中留下空 placeholders。如果语义上确实需要保留某项 actionable finding，只能使用 source-hash-bound 的
```
pptx-nova-review-policy/v1
```
rule，并使用
```
layout-final.json
```
中确切的
```
reviewIdentity.sha256
```
；绝不能使用全局 boolean exception。
原生
```
pptx-slide-copy/v1
```
必须披露
```
preflight.strategy.slideSize: "require-match"
```
；donor/target 尺寸不匹配是核心 blocker，而不是 renderer concern。保留捆绑的 copy-size gate 作为独立的文件绑定证据；如果原生 preflight 或该 gate 报告不匹配，应立即停止。不得隐式缩放，也不得将该策略转移至 Viewer/PDF rendering。
logos、client marks、product screenshots、headshots、app icons 和第三方品牌图形等 identity assets，必须来自用户提供的文件、允许复用的 source-deck assets、官方可验证来源或已注册授权来源。无法确认时，应改用文本/原生 shapes，而不是生成伪官方 assets。
使用外部、复用、生成或公式 assets 时，
```
assets_manifest.json
```
必须记录
```
status
```
、
```
source.kind
```
、
```
licenseRisk
```
和 PPTX usage slots。
```
missing
```
/
```
needs-user
```
/
```
forbidden
```
会阻止交付。
如果用户要求原地修改，仍应先在 run 目录中完成 validation，然后仅按照用户的明确意图写回。
默认保留 SmartArt、macros、复杂 animations 和不受支持的对象。仅在
```
inspect.animations[].editable
```
或当前 schema 明确支持的 creation-safe subset 内编辑 animations。无法编辑时应说明边界。
PowerPoint Repair 会阻止交付：任何出现“PowerPoint found a problem with content”、
```
Repair
```
按钮、打开后自动修复或同等 corruption warning 的 candidate PPTX，均属于失败 candidate。不得交付，也不得在未查明 root cause 时将 PowerPoint 修复后的文件作为最终产物。保留触发问题的 candidate PPTX、patch、dry-run/apply reports 和最小复现证据。在生成新 candidate 前，定位具体 op / OOXML part / structural order 问题。
对涉及 charts、tables、raw OOXML、relationship packages、embedded workbooks、themes/styles 等结构的高风险编辑，
```
xdoc check
```
、
```
vision-check
```
和 PNG preview 不足以证明结构安全。还应执行 OPC/OOXML structural validation，例如
```
unzip -t
```
、XML well-formedness checks，以及针对 chart axis/legend/data-label/gridline child element order、relationship targets、embedded workbook synchronization 等风险的专业 semantic audits。如果某个 op 会为特定输入类别生成 PowerPoint Repair 文件，应让该 op 在 xdoc/pptx-gen source 层失败，而不是生成有问题的内容。

Visual and Readability Hard Rules

视觉与可读性硬性规则

For client-facing, investor-facing, or formal-report decks, all visible text such as body copy, card descriptions, badges, labels, legends, and table cells must be readable:

Core body text is usually at least
```
10.5pt
```
.
Label / badge / chart/table text is usually at least
```
9pt
```
.
In newly created or explicitly recolored charts, avoid large black or near-black filled regions; black text and lines are allowed. Prefer suitable grays or theme colors, and review 3D sidewalls as well as front faces. Follow
```
references/content/charts.md
```
for palette and contrast checks; this does not authorize recoloring preserved source charts.
Footers/sources may be
```
8.5-9pt
```
, but must not carry critical information.
DeckKit-first creation uses the catalog
```
qualityProfile
```
and that DeckKit's golden baseline as machine gates. Do not damage validated DeckKit layout constants just to satisfy generic font-size hard rules.
Short labels such as percentages, number+unit, amounts, quarters, years,
```
ROI
```
, and
```
KPI
```
must not be split.
Circular or square numbers must be centered horizontally and vertically.
When text does not fit, shorten it, change the layout, increase container height, or split the page. Do not keep shrinking the font to cram it in.
Derive connector lines, arrows, central axes, VS marks, and numbered circles from target shape bounding boxes, not by eye.
Dry-run
```
text-overflow-estimate
```
and
```
vision-check
```
reuse the same static text overflow estimator. When you see a medium issue, fix height, shorten text, split pages, or adjust autofit before writing the file.
Expected single-line text such as
```
subtitle
```
,
```
eyebrow
```
,
```
kicker
```
,
```
badge
```
, and
```
label
```
must not have a stranded trailing word. Handle
```
vision-check
```
```
text-unexpected-wrap
```
by shortening copy, widening the container, or changing layout.
Main titles and subtitles should not break layout in order to express complete sentences. Remove terminal periods by default and move overlong content to subtitle, callout, body, or notes.
When converting PPTX to PNG/PDF or checking generated PPTX, tool watermarks such as
```
structurify.io
```
may appear. These watermarks usually appear only in the top-right corner of a slide, may be ignored during human visual review, and should not be treated as DeckKit composition, occlusion, or content defects.
Bundled
```
.nu
```
PowerPoint helpers are optional, capability-gated evidence integrations, never baseline dependencies. Missing prerequisites remain explicitly unverified and do not block the baseline unless PowerPoint-native proof was explicitly required; never claim missing evidence. Read the routed animation/chart reference for exact use.

PNG/contact-sheet review should be done with a problem-finding mindset, not as a confirmation ritual. Machine gates cannot see every pixel-level defect. In particular, check:

For refurbished decks, ask a more direct question first: if the filename is hidden, is this output clearly a redesigned version? If it only adds lines, page numbers, light backgrounds, or local accents to the original, do not deliver it as "refurbished/polished".
Whether wrapped titles collide with decoration, separators, headers, or logos.
Whether body text, sources, footnotes, legends, and table cells are truncated, overlapping, or hugging edges.
Whether adjacent cards, columns, icon circles, numbered circles, arrows, and connectors are aligned, and whether spacing varies wildly.
Whether text, icons, borders, and gridlines have enough contrast on light/dark backgrounds.
Whether template pages retain placeholders, old footers, old dates, old page numbers, empty image frames, or invisible-but-editable empty objects.
Whether multi-page contact sheets show repetitive layout rhythm, meaningless decorative containers, topic-only titles, or awkward blank space.
Whether chart/table pages pass specialized semantic checks: data dimensions, series/categories, legend/labels, table rows/columns, and binding sources must match the content before checking the PNG for occlusion.
For deliverable PPTX files, especially formal/enterprise or high-risk chart/table/OOXML changes, run the clean-open smoke gate when macOS + PowerPoint are available. Follow
```
references/review/export-and-check.md
```
for the command, prerequisites, delayed Repair-dialog checks, and skipped-evidence disclosure.

对于面向 client、investor 或 formal report 的 deck，所有可见文本，如 body copy、card descriptions、badges、labels、legends 和 table cells，都必须可读：

核心正文字号通常至少为
```
10.5pt
```
。
Label / badge / chart/table 文本通常至少为
```
9pt
```
。
在新建或明确重新着色的 charts 中，避免大面积纯黑或近黑色填充区域；允许使用黑色文本和线条。优先使用合适的灰色或 theme colors，并同时 review 3D sidewalls 和 front faces。遵循
```
references/content/charts.md
```
中的 palette 与 contrast checks；这不授权重新着色被保留的 source charts。
Footers/sources 可使用
```
8.5-9pt
```
，但不得承载关键信息。
DeckKit-first creation 使用 catalog
```
qualityProfile
```
和该 DeckKit 的 golden baseline 作为 machine gates。不得为满足通用字号硬性规则而破坏已验证的 DeckKit layout constants。
percentages、number+unit、amounts、quarters、years、
```
ROI
```
和
```
KPI
```
等短标签不得被拆分。
圆形或方形数字必须在水平和垂直方向上居中。
文本无法容纳时，应缩短文本、更改 layout、增加容器高度或拆分页面。不得持续缩小字体来强行塞入内容。
connector lines、arrows、central axes、VS marks 和 numbered circles 应根据目标 shape bounding boxes 推导，而不是凭目测判断。
dry-run
```
text-overflow-estimate
```
和 vision-check 使用相同的静态 text overflow estimator。看到 medium issue 时，应修复高度、缩短文本、拆分页面或调整 autofit，然后再写文件。
```
subtitle
```
、
```
eyebrow
```
、
```
kicker
```
、
```
badge
```
和
```
label
```
等预期为单行的文本，不得出现孤立的末尾单词。处理 vision-check
```
text-unexpected-wrap
```
时，应缩短 copy、加宽容器或更改 layout。
主标题和副标题不应为了表达完整句子而破坏 layout。默认移除句末句号，并将过长内容移至 subtitle、callout、body 或 notes。
将 PPTX 转换为 PNG/PDF 或检查生成的 PPTX 时，工具水印（如
```
structurify.io
```
）可能出现。此类水印通常仅出现在 slide 右上角，可在人工 visual review 中忽略，不应被视为 DeckKit composition、occlusion 或 content defect。
捆绑的
```
.nu
```
PowerPoint helpers 是可选且受 capability gate 控制的 evidence integrations，绝不是 baseline dependencies。缺少前置条件时必须明确标记为 unverified，除非明确要求 PowerPoint-native proof，否则不应阻止 baseline；绝不能声称存在缺失的 evidence。读取对应动画/chart reference 以了解精确用法。

PNG/contact-sheet review 应采用主动发现问题的思路，而不是确认仪式。 Machine gates 无法发现每个像素级缺陷。尤其应检查：

对于 refurbished deck，应先提出更直接的问题：如果隐藏文件名，输出是否明显是重新设计后的版本？如果只是增加线条、页码、浅色背景或局部强调，则不能将其作为“refurbished/polished”交付。
换行的标题是否与 decoration、separators、headers 或 logos 冲突。
正文、sources、footnotes、legends 和 table cells 是否被截断、重叠或紧贴边缘。
相邻 cards、columns、icon circles、numbered circles、arrows 和 connectors 是否对齐，间距是否变化过大。
文本、icons、borders 和 gridlines 在浅色/深色背景上是否有足够对比度。
Template pages 是否保留 placeholders、旧 footers、旧 dates、旧 page numbers、空 image frames 或不可见但可编辑的空对象。
多页 contact sheets 是否出现重复 layout rhythm、无意义的装饰容器、仅含主题的标题或尴尬的空白空间。
Chart/table pages 是否通过专业 semantic checks：数据维度、series/categories、legend/labels、table rows/columns 和 binding sources 必须与内容一致，然后才能检查 PNG 中的遮挡。
对交付的 PPTX 文件，尤其是正式/企业级或高风险 chart/table/OOXML 变更，如果 macOS + PowerPoint 可用，应运行 clean-open smoke gate。命令、前置条件、延迟出现的 Repair-dialog 检查和 skipped-evidence disclosure 请遵循
```
references/review/export-and-check.md
```
。

Required Validation

必需验证

When creating or visually significant modifying a deck, close in this order:

text

check-lock -> dry-run semanticIssues=0 -> apply semanticIssues=0 -> vision-check visual high/medium=0 + semanticSummary.passed=true for create -> structure-check when needed -> high-risk evidence finalizer when required -> PNG/contact-sheet design review -> design_review.json + visual_review.json -> clean-open gate when available/high-risk -> narrative quality review when required -> optional xdoc check

Generic Edit/Micro Edit must additionally close its own contract:

text

optional session-rules resolve -> edit-contract -> dry-run target coverage -> apply -> one final semantic diff -> declared scoped/style/structure evidence including vision-diff when visible -> edit-contract gate (including applicable session rules) -> PNG review when visible -> publish

Refurbish Existing Deck must also append:

text

refurbish-skin report gate -> source/candidate layout snapshots -> one final pptx semantic diff when source/candidate are stable -> one review-policy evaluation -> non-governing Finding Analysis shadow -> fidelity gate -> one full refurbish-compare render plus lower-layout-DPI Agent review assembly from the same page cache -> refurbish-compare delivery gate -> optional contact-diff aliases from that same compare evidence -> optional legacy supplemental audit

Animation, structural, or compatibility high-risk tasks must also append:

text

OPC zip check -> XML well-formed check -> targeted OOXML semantic audit -> target-Office compatibility gate -> PowerPoint clean-open smoke gate when available

Morph authoring requires the exact adjacent-pair

morph-check

. The

.nu

playback probe is optional; without it the baseline continues but PowerPoint playback stays unverified. An explicit native-proof requirement blocks that proof gate. Static PNG/PDF or viewer fallback does not prove interpolation.

When the user, template, publishing channel, or deployment policy names a target Office release, run

xdoc check <candidate> --checks compat --target-office <release> -o <run-dir>/office-compat.json --overwrite

. The candidate is compatible only when

checks.compat.details.agentGate.passed=true

; a top-level

warning

mc:Ignorable

, an

extLst/ext

extension container, or

AlternateContent

fallback does not prove full-fidelity compatibility. Read

minimumOfficeVersion

unprotectedIssueCount

gracefulDegradationIssueCount

, stable

ruleId

, and

sampleParts

to decide whether to remove the feature, add a fallback, or explicitly change the target policy. Retain

office-compat.json

as delivery evidence. If no target is specified, do not invent an older corporate baseline; the xdoc default is Microsoft 365 and still reports the deck's derived

minimumOfficeVersion

If any gate finds PowerPoint Repair, incorrect OOXML child element order, missing relationship targets, embedded workbook/chart cache mismatch, damaged animation timing tree, or an op that generates corrupted content for an input combination, stop delivery. First fix the xdoc/pptx-gen source and add a regression test covering the scenario that previously generated a bad file, asserting that, after the fix, it either generates a structurally valid file or returns a clear op-level error.

When only exporting or checking files, follow

references/review/export-and-check.md

创建 deck 或对其进行视觉显著的修改时，必须按以下顺序闭环：

text

check-lock -> dry-run semanticIssues=0 -> apply semanticIssues=0 -> vision-check visual high/medium=0 + semanticSummary.passed=true for create -> structure-check when needed -> high-risk evidence finalizer when required -> PNG/contact-sheet design review -> design_review.json + visual_review.json -> clean-open gate when available/high-risk -> narrative quality review when required -> optional xdoc check

通用 Edit/Micro Edit 还必须闭环自身的 contract：

text

optional session-rules resolve -> edit-contract -> dry-run target coverage -> apply -> one final semantic diff -> declared scoped/style/structure evidence including vision-diff when visible -> edit-contract gate (including applicable session rules) -> PNG review when visible -> publish

Refurbish Existing Deck 还必须追加：

text

refurbish-skin report gate -> source/candidate layout snapshots -> one final pptx semantic diff when source/candidate are stable -> one review-policy evaluation -> non-governing Finding Analysis shadow -> fidelity gate -> one full refurbish-compare render plus lower-layout-DPI Agent review assembly from the same page cache -> refurbish-compare delivery gate -> optional contact-diff aliases from that same compare evidence -> optional legacy supplemental audit

Animation、structural 或 compatibility 高风险任务还必须追加：

text

OPC zip check -> XML well-formed check -> targeted OOXML semantic audit -> target-Office compatibility gate -> PowerPoint clean-open smoke gate when available

Morph authoring 要求使用精确的相邻页对执行

morph-check

。

.nu

playback probe 是可选的；没有该 probe 时，baseline 可继续执行，但 PowerPoint playback 仍为 unverified。明确的 native-proof 要求会阻止该 proof gate。静态 PNG/PDF 或 Viewer fallback 不能证明 interpolation。

当用户、template、publishing channel 或 deployment policy 指定目标 Office release 时，运行

xdoc check <candidate> --checks compat --target-office <release> -o <run-dir>/office-compat.json --overwrite

。只有当

checks.compat.details.agentGate.passed=true

时，candidate 才被视为兼容；top-level

warning

、

mc:Ignorable

、

extLst/ext

extension container 或

AlternateContent

fallback 都不能证明 full-fidelity compatibility。读取

minimumOfficeVersion

、

unprotectedIssueCount

、

gracefulDegradationIssueCount

、稳定的

ruleId

和

sampleParts

，以决定移除 feature、添加 fallback 或明确更改 target policy。保留

office-compat.json

作为交付证据。如果未指定 target，不得自行设定旧版企业 baseline；xdoc default 为 Microsoft 365，同时仍会报告 deck 推导出的

minimumOfficeVersion

。

如果任何 gate 发现 PowerPoint Repair、错误的 OOXML child element order、缺失的 relationship targets、embedded workbook/chart cache 不一致、损坏的 animation timing tree，或某个 op 会为特定输入组合生成损坏内容，则停止交付。首先修复 xdoc/pptx-gen source，并添加覆盖该场景的 regression test，断言修复后要么生成结构有效的文件，要么返回清晰的 op-level error。

仅导出或检查文件时，请遵循

references/review/export-and-check.md

。

Common Command Entry Points

常用命令入口

Read the routed reference first and use its canonical runner or command sequence. Creation, refurbishment, and translation entry commands live in

references/create/create-runner.md

references/edit/refurbish-runner.md

, and

references/translation/translation-runner.md

; inspect/apply, export/check, specialized content, visual review, and feedback commands live in their matching references. Do not preload a command encyclopedia or reconstruct a runner from individual commands when a standard runner owns the workflow.

先读取路由对应的 reference，并使用其规范 runner 或命令序列。Creation、refurbishment 和 translation 的入口命令位于

references/create/create-runner.md

、

references/edit/refurbish-runner.md

和

references/translation/translation-runner.md

；inspect/apply、export/check、专业 content、visual review 和 feedback 命令位于各自对应的 reference。不要预加载命令百科，也不要在标准 runner 管理 workflow 时从单个命令重建 runner。

Completion Summary

完成摘要

For authorization-only tasks, report what was actually installed or diagnosed, the selected path/hash, credential health/admission, whether an intended real task passed, and any remaining reason/action. Distinguish installed-and-healthy from task-authorized; when no suitable task input was available, say task authorization remains unverified. Do not invent deck artifacts or apply the deck summary below.

After successfully generating, modifying, exporting, or checking, compress the final response into 4 blocks and avoid dumping the full checklist on the user:

Output: Absolute path to final PPTX/export file + run directory. For translation/refurbish tasks, list every published compare sibling and its run-directory source. Use the compatible unnumbered PNG for decks up to 20 slides; otherwise list the complete numbered
```
*-01.png
```
,
```
*-02.png
```
, ... set and manifest. The delivery bundle must be proven by the corresponding
```
*-compare-gate.json.status=pass
```
and
```
finalBinding.status=bound
```
.

Validation: One line listing the key gates actually run and their statuses, for example

dry-run semantic=0; apply semantic=0; vision high=0 medium=0 semantic=pass; preview reviewed; clean-open not run

Evidence: List only the 3-6 most important artifacts, such as
```
patch.json
```
,
```
vision.json
```
, preview manifest/contact sheet,
```
pptx-diff.json
```
, and
```
evidence-summary.json
```
; do not list artifacts that do not exist.
Risks/next steps: Include only items the user still needs to know, such as clean-open not run, fonts not embedded, external links, unsupported objects, manually unreviewed asset licensing, AI factual assumptions, or no remaining risk.

Add conditional material only when relevant: for high-risk tasks, list

evidence-summary.json

layout-final.json

; for chart/table/XML risk, list the specialized audit; for refurbish/strict template following, list fidelity/template/content audits; for formal persuasive decks, list the narrative-quality conclusion; when cleanup occurs, state retained evidence and deleted rebuildable artifacts. When Feedback Mode triggers, save feedback according to

references/review/feedback-mode.md

and list the

skill-feedback.md

path. Show detailed issues only for 3 or fewer feedback items; beyond 3, list only the detailed-report path. For Create, Refurbish, and Translation, always print the validated seven-row execution scorecard and weighted overall score regardless of issue count. Retain

feedback-gate.json

as well. Do not output xdoc version, CLI schema, or capability-disclosure audit details unless they affect the result, a fallback was used, or the user explicitly asks. In Feedback Mode, the three-item limit does not hide newly confirmed unexpected xdoc rendering problems: summarize every such problem in the final response, with its affected slide/object and PowerPoint comparison result, and link the detailed evidence in

skill-feedback.md

Only output token information when the platform or tooling provides accurate token statistics; do not estimate.

对于仅涉及授权的任务，应报告实际安装或诊断的内容、所选 path/hash、credential health/admission、目标真实任务是否通过，以及仍需采取的措施或剩余原因。应区分“已安装且健康”和“任务已授权”；没有合适的任务输入时，应说明任务授权仍未验证。不得虚构 deck artifacts，也不得套用下述 deck 摘要。

成功生成、修改、导出或检查后，应将最终回复压缩为 4 个区块，避免向用户倾倒完整 checklist：

Output：最终 PPTX/export 文件的绝对路径和 run 目录。对于 translation/refurbish 任务，列出每个已发布的 compare sibling 及其 run-directory source。对于不超过 20 页的 deck，使用兼容的无编号 PNG；否则列出完整的编号
```
*-01.png
```
、
```
*-02.png
```
等文件集合和 manifest。交付 bundle 必须由对应的
```
*-compare-gate.json.status=pass
```
和
```
finalBinding.status=bound
```
证明。

Validation：用一行列出实际运行的关键 gate 及其状态，例如

dry-run semantic=0; apply semantic=0; vision high=0 medium=0 semantic=pass; preview reviewed; clean-open not run

。

Evidence：仅列出 3–6 个最重要的 artifacts，例如
```
patch.json
```
、
```
vision.json
```
、preview manifest/contact sheet、
```
pptx-diff.json
```
和
```
evidence-summary.json
```
；不要列出实际不存在的 artifacts。
Risks/next steps：仅包含用户仍需了解的事项，例如未运行 clean-open、未嵌入 fonts、external links、不受支持的对象、尚未人工审查的 asset licensing、AI factual assumptions，或无剩余风险。

仅在相关时添加条件性材料：对于高风险任务，列出

evidence-summary.json

layout-final.json

；对于 chart/table/XML 风险，列出专业 audit；对于 refurbish/strict template following，列出 fidelity/template/content audits；对于正式说服型 deck，列出 narrative-quality conclusion；发生 cleanup 时，说明保留的 evidence 和已删除的可重建 artifacts。Feedback 模式触发时，按照

references/review/feedback-mode.md

保存 feedback，并列出

skill-feedback.md

路径。详细问题仅在不超过 3 项时展示；超过 3 项时，仅列出详细报告路径。对于 Create、Refurbish 和 Translation，无论问题数量如何，始终打印经过验证的七行执行评分表和加权总分。同时保留

feedback-gate.json

。除非结果受到影响、使用了 fallback，或用户明确要求，否则不要输出 xdoc version、CLI schema 或 capability-disclosure audit details。在 Feedback 模式下，三项限制不能隐藏新确认的异常 xdoc 渲染问题：应在最终回复中总结每个此类问题，包括受影响的 slide/object 和 PowerPoint comparison 结果，并链接

skill-feedback.md

中的详细证据。仅当平台或 tooling 提供准确 token statistics 时才输出 token 信息；不要估算。

Reference Index

Reference 索引

Read the files required by routing first; do not read all references at once. See the reference index for the complete grouped guide descriptions.

先读取路由所要求的文件；不要一次读取所有 references。有关完整的分组指南说明，请参阅 reference 索引。