From 5ae2594a5fef74a0d7f994aa050a0a03cf54c020 Mon Sep 17 00:00:00 2001 From: "songtianyi.theo" Date: Fri, 3 Jul 2026 02:43:19 +0800 Subject: [PATCH] docs: document svglide local execution loop --- skills/lark-slides/SKILL.md | 2 +- .../references/lark-slides-create-svglide.md | 56 +++++++++++++++++-- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 7f5edfa2..5e81ad50 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -20,7 +20,7 @@ metadata: | 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` | | 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` | | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 | -| 使用 AnyGen SVG Slides 本地工作台 | 创建本地 run-dir，由 Codex 分阶段填充产物，再本地 validate / preview | [`lark-slides-create-svglide.md`](references/lark-slides-create-svglide.md)、`slides +create-svglide` | +| 使用 AnyGen SVG Slides 本地工作台 | 创建 run-dir，按 stage 填产物；本地校验/预览/修复，不发布飞书 | [`lark-slides-create-svglide.md`](references/lark-slides-create-svglide.md)、`slides +create-svglide` | | 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `` 元素 | `xml-schema-quick-ref.md` | | 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) | | 使用语义图标 | 先检索 IconPark，再写 `` | `iconpark_tool.py search → resolve`、`iconpark.md` | diff --git a/skills/lark-slides/references/lark-slides-create-svglide.md b/skills/lark-slides/references/lark-slides-create-svglide.md index 3858361a..5509003d 100644 --- a/skills/lark-slides/references/lark-slides-create-svglide.md +++ b/skills/lark-slides/references/lark-slides-create-svglide.md @@ -4,6 +4,8 @@ ## 推荐流程 +初始化 run-dir： + ```bash lark-cli slides +create-svglide \ --as user \ @@ -14,14 +16,44 @@ lark-cli slides +create-svglide \ --delivery-mode self_read \ --pages 8 \ --out ./.lark-slides/svglide-runs/demo +``` +查看下一步： + +```bash lark-cli slides +create-svglide --as user --action status --run ./.lark-slides/svglide-runs/demo lark-cli slides +create-svglide --as user --action next --run ./.lark-slides/svglide-runs/demo +``` + +每个 stage 的循环： + +```bash +lark-cli slides +create-svglide --as user --action next --run ./.lark-slides/svglide-runs/demo +# Codex 根据返回的 prompt 填充当前 stage outputs +lark-cli slides +create-svglide --as user --action complete --run ./.lark-slides/svglide-runs/demo +lark-cli slides +create-svglide --as user --action next --run ./.lark-slides/svglide-runs/demo +``` + +`outline`、`content`、`visual`、`assets` 就绪后，再生成基础文本 SVG： + +```bash +lark-cli slides +create-svglide --as user --action author --run ./.lark-slides/svglide-runs/demo +``` + +最终校验和预览： + +```bash +lark-cli slides +create-svglide --as user --action repair --run ./.lark-slides/svglide-runs/demo +``` + +必要时可单独定位校验或预览问题： + +```bash lark-cli slides +create-svglide --as user --action validate --run ./.lark-slides/svglide-runs/demo lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/svglide-runs/demo ``` -`init` 只建立目录、`run.json`、prompt、schema 和 request 产物。后续研究、设计 brief、内容、资产、SVG authoring 和 repair 由 Codex 按 `next` 返回的 prompt 执行。 +`init` 只建立目录、`run.json`、prompt、schema 和 request 产物。Codex 按 `next` 返回的 prompt 填充当前 stage 产物后，用 `complete` 校验并推进 stage。`repair` 会先执行 validate；只有 lint 失败且失败项可由基础 `author` 覆盖修复时才会重新 author，再生成 preview。deck 缺失、JSON 错误等不可自动修复的问题会保留在 `receipts/lint.json` 和 `repair_queue.md`，由 Codex 手动修复后再运行校验。 ## Action @@ -30,8 +62,11 @@ lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/ | `init` | 创建本地 run-dir | `run.json`、`request/request.json`、`prompts/*.task.md`、`schemas/*.json` | | `status` | 查看当前 stage、缺失输入/输出和下一条命令 | JSON 状态报告 | | `next` | 返回当前 stage 的 prompt、输入和输出列表 | JSON task 报告 | +| `complete` | 校验当前 stage 输出并推进到下一 stage | `run.json`、`receipts/.json` | +| `author` | 基于 deck/content/visual/assets 生成基础文本 SVG | `slides/*.svg`、`receipts/svg_author.json` | | `validate` | 校验 `outline/deck.json` 中的 `slides/*.svg` | `receipts/lint.json`、`repair_queue.md` | | `preview` | 生成本地 HTML 预览 | `preview.html`、`receipts/preview.json` | +| `repair` | 执行 validate；仅在 lint 失败且可由基础 author 覆盖修复时重新 author，再 preview | `receipts/validate_preview_repair.json` | ## 运行目录 @@ -57,6 +92,7 @@ lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/ - CLI 负责 run-dir 骨架、prompt/schema、状态检查、SVG lint、repair queue 和 HTML preview。 - Codex 负责自动研究、设计 brief、slide content、资产规划、生图/搜图结果落地、SVG authoring 和修复。 +- 第一批功能等价适配不实现 chart、table、图片裁剪。遇到真实数据图表、表格或图片构图需求时，Codex 在内容层保留语义说明，CLI 基础 `author` 用文本和形状占位表达，不伪装成 native chart、native table 或 image crop。 - 本命令不发布到 Feishu，不返回 `xml_presentation_id`，不创建 `.slides`，不调用 Slides OpenAPI。 - `preview` 只允许 deck slide path 使用 `slides/.svg` 单层本地路径；不要引用远程 URL、上级目录、百分号编码路径或嵌套目录。 - `validate` 的 `ok=false` 表示内容校验失败，但命令仍会输出结构化报告；只有 run-dir 读取或本地写入失败才是命令异常。 @@ -65,10 +101,11 @@ lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/ 1. 先运行 `status` 或 `next`，确认当前 stage 和缺失产物。 2. 按 `prompts/*.task.md` 填充当前 stage 的输出，不跳 stage 写最终 SVG。 -3. 生成 SVG 时保持纯 SVG、`viewBox="0 0 960 540"`、可选中文本、无远程资源。 -4. 先运行 `validate`，如果 `repair_queue.md` 有问题，修复后再次 validate。 -5. 再运行 `preview`，检查 `preview.html` 不是白屏，并确认每页都来自 `slides/*.svg`。 -6. 不要把这个本地工作台描述成完整 12-agent 自动化系统；它是 Codex 协作的分阶段本地 runtime。 +3. 每个 stage 输出就绪后运行 `complete`，让 CLI 校验当前 stage 并推进 `run.json`。 +4. 当 `outline`、`content`、`visual`、`assets` 已存在时，可运行 `author` 生成基础文本 SVG。 +5. 生成 SVG 时保持纯 SVG、`viewBox="0 0 960 540"`、可选中文本、无远程资源。 +6. 最后运行 `repair`，形成 validate + preview + final receipt；`repair` 只自动处理可由基础 `author` 覆盖的 lint 失败，deck 缺失、JSON 错误等问题会保留 `receipts/lint.json` / `repair_queue.md` 供 Codex 手动修复。 +7. 不要把这个本地工作台描述成完整 12-agent 自动化系统；它是 Codex 协作的分阶段本地 runtime。 ## 常见命令 @@ -76,9 +113,18 @@ lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/ # 查看下一步该做什么 lark-cli slides +create-svglide --as user --action next --run ./.lark-slides/svglide-runs/demo +# 校验当前 stage 并推进 +lark-cli slides +create-svglide --as user --action complete --run ./.lark-slides/svglide-runs/demo + +# 基于已完成的 deck/content/visual/assets 生成基础文本 SVG +lark-cli slides +create-svglide --as user --action author --run ./.lark-slides/svglide-runs/demo + # 只做 SVG 协议校验 lark-cli slides +create-svglide --as user --action validate --run ./.lark-slides/svglide-runs/demo # 生成本地预览 lark-cli slides +create-svglide --as user --action preview --run ./.lark-slides/svglide-runs/demo + +# 执行 validate，必要时重新 author，再生成 preview +lark-cli slides +create-svglide --as user --action repair --run ./.lark-slides/svglide-runs/demo ```