feat: add agent-oriented slide-gen CLI example

.gitignore

@@ -6,3 +6,8 @@ coverage/
 .vscode/
 .agents/
 *.tsbuildinfo
+docs/proposal-plan/
+docs/qa/
+docs/research/
+docs/run/
+openspec/

CONTEXT.md

@@ -0,0 +1,37 @@
+# Univer CLI Examples
+
+This repository contains runnable teaching examples for composing Univer CLI SDK capabilities into focused content workflows.
+
+## Language
+
+**Resource-backed Slide**:
+A Slide page whose SVG authoring source references at least one visual asset exported from Resource Library by stable handle before the compiler produces the Univer page.
+_Avoid_: SVG Slide, asset-enabled Slide
+
+**Resource-backed Slide deck**:
+A Slide Unit rebuilt from an Authoring Source in which at least one page references a visual asset exported from Resource Library by stable handle.
+_Avoid_: Resource-backed page, generated deck
+
+**Presentation Brief**:
+The user's requested audience, purpose, narrative, content, and delivery constraints for a generated Slide deck.
+_Avoid_: prompt, template
+
+**Authoring Source**:
+The maintained inputs from which a Slide deck can be rebuilt: its Presentation Brief or deck specification, page SVGs, exported visual assets, and optional Native Enhancements; compiled Facade programs are disposable build outputs.
+_Avoid_: generated program, Slide template
+
+**Native Enhancement**:
+Maintained authoring code that adds editable Slide semantics the SVG compiler does not express, such as a native chart or table.
+_Avoid_: generated program, terminal patch
+
+**Baseline Deck**:
+The committed multi-page Authoring Source that gives an application a deterministic teaching and acceptance target.
+_Avoid_: template, generated sample
+
+**Review Evidence**:
+Per-page structured inspection, layout findings, rendered screenshots, and a deck-level consistency assessment used together before handoff.
+_Avoid_: screenshot, inspection result
+
+**Review URL**:
+A Server-scoped URL for viewing a trunk or Worktree Slide deck while the example's Web Server is running.
+_Avoid_: public URL, permanent share link

README.md

@@ -5,12 +5,13 @@ English | [简体中文](./README.zh-CN.md)
 This repository contains runnable teaching examples for the Univer CLI SDK. Concepts and
 architecture live on the [Univer Office documentation site](https://office.univer.ai/cli/overview).
 
-| Example                                                               | Learn                                             | New concepts                            |
-| --------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------- |
-| [`01-content-operations`](./examples/01-content-operations/README.md) | Read, edit, and view Sheet, Doc, and Slide Units  | CLI, Server, Web, Collaboration Runtime |
-| [`02-file-exchange`](./examples/02-file-exchange/README.md)           | Import and export Office files                    | Exchange, UnitData, native binding      |
-| [`03-visual-inspection`](./examples/03-visual-inspection/README.md)   | Visually inspect all three Unit types             | Render Page, Screenshot, Layout Lint    |
-| [`04-worktree`](./examples/04-worktree/README.md)                     | Edit in a draft and hand it to a human for review | Worktree, Ready, Merge, Reopen, Discard |
+| Example                                                               | Learn                                                   | New concepts                               |
+| --------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------ |
+| [`01-content-operations`](./examples/01-content-operations/README.md) | Read, edit, and view Sheet, Doc, and Slide Units        | CLI, Server, Web, Collaboration Runtime    |
+| [`02-file-exchange`](./examples/02-file-exchange/README.md)           | Import and export Office files                          | Exchange, UnitData, native binding         |
+| [`03-visual-inspection`](./examples/03-visual-inspection/README.md)   | Visually inspect all three Unit types                   | Render Page, Screenshot, Layout Lint       |
+| [`04-worktree`](./examples/04-worktree/README.md)                     | Edit in a draft and hand it to a human for review       | Worktree, Ready, Merge, Reopen, Discard    |
+| [`slide-gen-cli`](./examples/slide-gen-cli/README.md)                 | Generate, review, export, and view Slides with an Agent | SVG Compile, Resource Library, Agent Skill |
 
 Read them in numbered order. Each directory has its own `package.json`, lockfile, and dependencies,
 so it can be copied and run independently.

README.zh-CN.md

@@ -5,12 +5,13 @@
 这个仓库只存放可运行的 Univer CLI SDK 教学 examples。概念和架构说明统一在
 [Univer Office 文档站](https://office.univer.ai/zh-CN/cli/overview)维护。
 
-| Example                                                                     | 学习目标                           | 新增概念                                |
-| --------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------- |
-| [`01-content-operations`](./examples/01-content-operations/README.zh-CN.md) | 读取、修改并查看 Sheet、Doc、Slide | CLI、Server、Web、Collaboration Runtime |
-| [`02-file-exchange`](./examples/02-file-exchange/README.zh-CN.md)           | 导入和导出 Office 文件             | Exchange、UnitData、原生 binding        |
-| [`03-visual-inspection`](./examples/03-visual-inspection/README.zh-CN.md)   | 视觉检查前三种 Unit                | Render Page、Screenshot、Layout Lint    |
-| [`04-worktree`](./examples/04-worktree/README.zh-CN.md)                     | 在 draft 编辑并交给人审阅          | Worktree、Ready、Merge、Reopen、Discard |
+| Example                                                                     | 学习目标                                | 新增概念                                   |
+| --------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------ |
+| [`01-content-operations`](./examples/01-content-operations/README.zh-CN.md) | 读取、修改并查看 Sheet、Doc、Slide      | CLI、Server、Web、Collaboration Runtime    |
+| [`02-file-exchange`](./examples/02-file-exchange/README.zh-CN.md)           | 导入和导出 Office 文件                  | Exchange、UnitData、原生 binding           |
+| [`03-visual-inspection`](./examples/03-visual-inspection/README.zh-CN.md)   | 视觉检查前三种 Unit                     | Render Page、Screenshot、Layout Lint       |
+| [`04-worktree`](./examples/04-worktree/README.zh-CN.md)                     | 在 draft 编辑并交给人审阅               | Worktree、Ready、Merge、Reopen、Discard    |
+| [`slide-gen-cli`](./examples/slide-gen-cli/README.zh-CN.md)                 | 借助 Agent 生成、审阅、导出和查看 Slide | SVG Compile、Resource Library、Agent Skill |
 
 请按编号阅读。每个目录都有自己的 `package.json`、lockfile 和依赖，可以独立复制和运行。
 

examples/slide-gen-cli/.gitignore

@@ -0,0 +1,2 @@
+**/.generated/
+**/output/

examples/slide-gen-cli/README.md

@@ -0,0 +1,126 @@
+# Slide Gen CLI
+
+English | [简体中文](./README.zh-CN.md)
+
+This Slide-only example turns a Presentation Brief into a reviewable Univer deck. The committed
+Authoring Source contains a deck spec, consecutive SVG pages, stable-handle resources, and optional
+programs for editable native charts and tables. Generated Facade JavaScript remains disposable.
+
+```text
+Presentation Brief → deck spec → SVG pages → compile/execute → evidence → Ready review
+                                      ↘ optional native enhancement replay
+```
+
+## Run the Baseline Deck
+
+Run from this directory:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm link-cli
+pnpm start-server
+```
+
+Keep the Server running. In another terminal, compile the two committed 960 × 540 pages:
+
+```bash
+TASK_DIR=authoring/product-release
+mkdir -p "$TASK_DIR/.generated" "$TASK_DIR/output"
+
+slide-gen-cli compile-svg "$TASK_DIR/pages/page-01-status.svg" --page 1 \
+  --out "$TASK_DIR/.generated/page-01.js" --estimate-text-size --json
+slide-gen-cli compile-svg "$TASK_DIR/pages/page-02-handoff.svg" --page 2 \
+  --out "$TASK_DIR/.generated/page-02.js" --estimate-text-size --json
+```
+
+Page 1 uses the committed canonical rocket export; page 2 shows that a page does not need a
+resource reference. Stop on compiler warnings and review each reported lint.
+
+Create one Slide Worktree and execute pages consecutively:
+
+```bash
+UNIT_ID=$(slide-gen-cli create --name "Product release deck")
+WORKTREE_ID=$(slide-gen-cli worktree create --unit "$UNIT_ID")
+
+slide-gen-cli execute --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --file "$TASK_DIR/.generated/page-01.js"
+slide-gen-cli execute --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --file "$TASK_DIR/.generated/page-02.js"
+```
+
+Each execution must report `commit: "confirmed"`. Recompiling an existing page number replaces
+that page; `pageCount + 1` appends the next page; skipping a page number fails instead of creating
+blank pages. The workflow sets no maximum page count.
+
+## Review and deliver
+
+Save structured inspection, layout diagnostics, and a screenshot for every page:
+
+```bash
+slide-gen-cli inspect presentation \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli inspect slide index:1 \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli inspect slide index:2 \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli lint --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --pages 1,2 --json
+slide-gen-cli screenshot --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --pages 1,2 --out "$TASK_DIR/output" --json
+```
+
+Require zero unexplained layout findings. Read every PNG, then review narrative continuity, fonts,
+colors, resource style, page size, and native-element placement across the deck. Fix a page by
+compiling and executing its page number again; do not use `--add` for corrections.
+
+If a page needs an editable native chart or table, run its saved enhancement program only after
+the last SVG replacement. Charts must set explicit category and value field mappings. Replay the
+enhancement after any later replacement of that page.
+
+When the evidence passes:
+
+```bash
+slide-gen-cli worktree ready "$WORKTREE_ID"
+slide-gen-cli open --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --no-launch
+slide-gen-cli export "$TASK_DIR/output/product-release.pptx" \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID"
+```
+
+The review URL is scoped to this Server and works while it is running. PPTX export is optional;
+export the same Worktree revision that the reviewer accepted. Before handing off a PPTX with native
+charts or tables, inspect exporter diagnostics and verify that its OOXML preserves chart
+category/value data, includes the embedded workbook, and contains the native table in slide XML;
+do not return only the file path.
+
+## Use it with an Agent
+
+```bash
+pnpm skill:install
+```
+
+Open this directory with an Agent and enter:
+
+```text
+Use univer-slide-authoring to turn my Presentation Brief into a reviewed Slide Worktree.
+```
+
+When finished:
+
+```bash
+pnpm skill:uninstall
+pnpm unlink-cli
+```
+
+## Files and boundaries
+
+- `authoring/product-release/` is one committed task-directory example, not a required location.
+- A task directory keeps `deck.md`, `pages/`, `resources/`, and optional `enhancements/` together.
+- Put `.generated/` and `output/` under that same task directory; both are disposable and ignored.
+- Use a different task directory for each concurrent or resumable deck job. `.data/` and `dist/`
+  remain application-level disposable output.
+- `test/program.test.ts`, `test/smoke.test.ts`, and `test/native.test.ts` use fixed inputs and local
+  assets, so automated verification does not contact the remote asset host.
+
+The application excludes Sheet and Doc authoring, Office import, templates, hosted publishing, and
+handwritten Facade drawing code for ordinary elements.

examples/slide-gen-cli/README.zh-CN.md

@@ -0,0 +1,124 @@
+# Slide Gen CLI
+
+[English](./README.md) | 简体中文
+
+本例只支持 Slide，把 Presentation Brief 转成可审阅的 Univer deck。仓库提交的 Authoring
+Source 包含 deck spec、连续 SVG pages、stable-handle resources，以及可选的 editable native
+chart/table programs；生成的 Facade JavaScript 仍是一次性产物。
+
+```text
+Presentation Brief → deck spec → SVG pages → compile/execute → evidence → Ready review
+                                      ↘ 可选 Native Enhancement replay
+```
+
+## 运行 Baseline Deck
+
+在当前目录执行：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm link-cli
+pnpm start-server
+```
+
+保持 Server 运行。另开终端，编译仓库提交的两个 960 × 540 pages：
+
+```bash
+TASK_DIR=authoring/product-release
+mkdir -p "$TASK_DIR/.generated" "$TASK_DIR/output"
+
+slide-gen-cli compile-svg "$TASK_DIR/pages/page-01-status.svg" --page 1 \
+  --out "$TASK_DIR/.generated/page-01.js" --estimate-text-size --json
+slide-gen-cli compile-svg "$TASK_DIR/pages/page-02-handoff.svg" --page 2 \
+  --out "$TASK_DIR/.generated/page-02.js" --estimate-text-size --json
+```
+
+Page 1 使用仓库提交的 canonical rocket export；page 2 证明并非每一页都需要引用资源。
+出现 compiler warning 时停止，并检查每一条 lint。
+
+创建一个 Slide Worktree，按连续页码执行：
+
+```bash
+UNIT_ID=$(slide-gen-cli create --name "产品发布 deck")
+WORKTREE_ID=$(slide-gen-cli worktree create --unit "$UNIT_ID")
+
+slide-gen-cli execute --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --file "$TASK_DIR/.generated/page-01.js"
+slide-gen-cli execute --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --file "$TASK_DIR/.generated/page-02.js"
+```
+
+每次 execution 都必须报告 `commit: "confirmed"`。重新执行已有页码会 replace 该页；
+`pageCount + 1` 会 append 下一页；跳过页码会失败且不会生成空白页。workflow 不设最大页数。
+
+## 审阅与交付
+
+为每一页保存 structured inspection、layout diagnostics 和 screenshot：
+
+```bash
+slide-gen-cli inspect presentation \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli inspect slide index:1 \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli inspect slide index:2 \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --json
+slide-gen-cli lint --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --pages 1,2 --json
+slide-gen-cli screenshot --unit "$UNIT_ID" --worktree "$WORKTREE_ID" \
+  --pages 1,2 --out "$TASK_DIR/output" --json
+```
+
+要求 layout findings 为零，或为每条保留明确证据。打开每张 PNG，再检查整个 deck 的叙事、
+字体、颜色、资源风格、page size 和 native-element placement。修正时重新编译并执行对应
+页码；不要用 `--add` 叠加修改。
+
+如果某页需要 editable native chart/table，在该页最后一次 SVG replacement 后执行已保存的
+enhancement program。Chart 必须显式设置 category field 和 value fields mapping。以后再次
+replace 该页时，需重放 enhancement。
+
+证据通过后：
+
+```bash
+slide-gen-cli worktree ready "$WORKTREE_ID"
+slide-gen-cli open --unit "$UNIT_ID" --worktree "$WORKTREE_ID" --no-launch
+slide-gen-cli export "$TASK_DIR/output/product-release.pptx" \
+  --unit "$UNIT_ID" --worktree "$WORKTREE_ID"
+```
+
+Review URL 仅属于当前 Server，并且只在 Server 运行时可用。PPTX export 是按需操作；应从
+审阅者验收的同一个 Worktree revision 导出。交付含 native chart/table 的 PPTX 前，必须检查
+exporter diagnostics，并确认 OOXML 保留 chart category/value data、包含 embedded workbook，
+且 slide XML 中包含 native table；不能只返回文件路径。
+
+## 交给 Agent 使用
+
+```bash
+pnpm skill:install
+```
+
+用 Agent 打开当前目录，然后输入：
+
+```text
+使用 univer-slide-authoring 把我的 Presentation Brief 制作成已审阅的 Slide Worktree。
+```
+
+体验结束后：
+
+```bash
+pnpm skill:uninstall
+pnpm unlink-cli
+```
+
+## 文件与边界
+
+- `authoring/product-release/` 是仓库提交的任务目录示例，不是固定位置。
+- 每个任务目录在其下集中保存 `deck.md`、`pages/`、`resources/` 和可选的 `enhancements/`。
+- 同一任务目录下的 `.generated/` 与 `output/` 是可丢弃且被忽略的产物。
+- 并行或需要恢复的 deck job 必须使用不同任务目录；`.data/` 与 `dist/` 仍是 application-level
+  的可丢弃产物。
+- `test/program.test.ts`、`test/smoke.test.ts` 与 `test/native.test.ts` 使用固定输入和本地
+  assets，因此自动验证不会访问远程 asset host。
+
+本 application 不提供 Sheet/Doc authoring、Office import、template、hosted publishing，
+普通元素也不使用手写 Facade drawing code。

examples/slide-gen-cli/acceptance/agent-online-review/deck.md

@@ -0,0 +1,29 @@
+# Agent 如何用 slide-gen-cli 把想法变成可在线评审的 Univer Slide
+
+## 受众与目标
+
+- 受众：正在评估 `slide-gen-cli` example 的工程团队。
+- 决策：判断这个 example 是否给 Agent 提供了完整、可复验的 Slide 生成闭环。
+- 叙事：先看端到端路径，再看任务目录如何承载中间产物，最后看在线评审与质量回路。
+
+## 视觉规范
+
+- 页面：960 × 540，16:9。
+- 字体：Arial、PingFang SC；标题 36–40 px，正文 14–18 px，元数据 11–12 px。
+- 主色：墨黑蓝 `#0B1020`，白 `#F6F8FF`，灰蓝 `#98A6C7`。
+- 强调色：青绿 `#4DE2C5`，蓝 `#5B8CFF`，紫 `#A77BFF`，橙 `#FFB454`。
+- 视觉语言：深色工程控制台、细线连接、圆角卡片、明确页码；同一强调色在三页保持相同语义。
+- 资源：第 1 页使用 canonical stable handle `example-tabler-outline/ai-agent`，表示执行 authoring skill 的 Agent。
+
+## 页面契约
+
+1. `page-01-from-brief-to-review.svg`：一句话结论和四步流水线，建立完整心智模型。
+2. `page-02-task-directory.svg`：展示任务级目录如何把输入、源码、中间产物和交付证据放在一起。
+3. `page-03-quality-loop.svg`：展示 compile → execute → inspect/lint → screenshot 的修订回路，以及 Ready、PPTX、在线 URL 三种交付结果。
+
+## 精确文案
+
+- 核心结论：Agent 不是“画一张图”，而是在同一个 Worktree revision 上生成、验证并交付一份可在线评审的 deck。
+- 第 1 页步骤：理解 Brief / 编写 SVG / 提交 Worktree / 在线评审。
+- 第 2 页字段：输入、页面源码、稳定资源、生成程序、验收证据。
+- 第 3 页门槛：compiler warnings 可解释；layout lint = 0；逐页截图人工阅读；commit = confirmed。