/sn-ppt-workbench

name: sn-ppt-workbench
description: |
  Open the AI PPT editing WebUI for previously generated SenseNova HTML slides.
  Use when the user asks to preview, inspect, edit, or open an existing/generated
  PPT deck in the WebUI/workbench without regenerating slides. Accepts an
  explicit deck_dir or auto-detects the newest local ppt_decks entry containing
  HTML pages. Does not run style/outline/page-html/export generation.
metadata:
  project: SenseNova-Skills
  tier: aux
  category: ppt
  user_visible: true
triggers:
  - "sn-ppt-workbench"
  - "打开 PPT 工作台"
  - "打开 PPT WebUI"
  - "预览已生成 PPT"

sn-ppt-workbench

Start or reuse the AI PPT editing WebUI for an existing HTML slide deck. The helper prefers Hermes/canvas/port-forward URLs when available. Without a forwarded URL, native hosts bind to localhost by default, while Docker/WSL bind to `0.0.0.0` so remote users can reach the WebUI through the host network.

Use Cases

• The user already generated a deck and asks to open the WebUI/editor/workbench.
• The user provides a `deck_dir` containing `pages/page_NNN.html` or root-level `.html` slides.
• The user says to inspect or edit previously generated slides without regenerating them.

Hard Rules

1. Do not run `sn-ppt-entry`, `sn-ppt-standard`, `page-html`, `batch-page-html`, or `export`. 2. Do not edit slide files directly. The WebUI handles user-visible editing. 3. If `deck_dir` is missing, auto-detect the newest usable deck under:

• `$(pwd)/ppt_decks`
• `~/Downloads/ppt_decks`
• `~/Repository/ppt_decks`

4. If no usable deck is found, ask the user for the absolute `deck_dir`. 5. Workbench startup is best-effort. If it skips or fails, report the reason and do not attempt generation as a fallback. 6. Prefer a forwarded/canvas URL over localhost when the user may be on SSH, IM, or another remote device.

Invocation

Use the helper directly:

python3 $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "${HERMES_SESSION_KEY:-}"

On native Windows where `python3` is unavailable:

python $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "%HERMES_SESSION_KEY%"

If the user did not provide a deck path, let the helper auto-detect:

python3 $SKILL_DIR/scripts/open_workbench.py --agent-session-id "${HERMES_SESSION_KEY:-}"

Pass same-session bridge details when available:

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-session-id "${HERMES_SESSION_KEY:-}" \
  --agent-managed 1 \
  --agent-provider hermes \
  --agent-transport gateway \
  --webui-base-url "${HERMES_WEBUI_BASE_URL:-}" \
  --gateway-base-url "${HERMES_GATEWAY_BASE_URL:-}"

For non-Hermes interactive providers, pass structured bridge details instead of scraping CLI/TUI output:

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider openclaw \
  --agent-transport rest \
  --agent-base-url "${WORKBENCH_AGENT_BASE_URL:-}" \
  --agent-api-key "${WORKBENCH_AGENT_API_KEY:-}"

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider codex \
  --agent-transport acp \
  --acp-command "${WORKBENCH_ACP_COMMAND:-codex-acp}"

For WorkBuddy, pass `--agent-provider workbuddy` only as provider identity. Tell the user clearly that WorkBuddy currently has no supported API or ACP interface for the interactive workbench bridge, so the WebUI can show WorkBuddy status but cannot send bottom-chat modification turns back to WorkBuddy.

CLI Subcommands (direct launch fallback)

When bypassing `open_workbench.py` and invoking the workbench launcher directly, use subcommands:

node <launcher> start   --deck-dir "<path>" [--port 0] [--agent-managed]
node <launcher> status  --deck-dir "<path>"
node <launcher> stop    --deck-dir "<path>"

The old argument-only form (no subcommand) is **deprecated** — it will print a usage error.

**Restart pitfall:** `start` silently **reuses** an existing server instance for the same `deck-dir` (response contains `"reused": true`). If you updated the workbench code, you MUST run `stop` first, then `start` — otherwise the old process keeps serving stale code:

node <launcher> stop  --deck-dir "<path>"
node <launcher> start --deck-dir "<path>" --port 0

Bind Host

The workbench resolves its bind address from `--host` CLI flag → `WORKBENCH_HOST` env var → default `127.0.0.1`. When the user needs remote/LAN access, set `WORKBENCH_HOST=0.0.0.0`:

export WORKBENCH_HOST=0.0.0.0
node <launcher> start --deck-dir "<path>" --port 0

The response `url` field will then show the LAN IP instead of `127.0.0.1`.

Output Handling

Parse the single JSON line from stdout.

When `status == "ok"`, echo the returned `editor_url`, `public_url`, or `workbench.editorUrl` for existing-deck editing requests. The helper may also return `generation_url`; that URL is the generation progress page at `/progress`, while the editor is `/editor`.

PPT 编辑工作台已启动：<editor_url>

If `workbench.reused == true`, say it reused the existing server.

If `bind_host` is `0.0.0.0`, the URL is a Docker/WSL LAN fallback. Tell the user it must be reachable from their device/network; if not, ask them to provide a Hermes/canvas/port-forward URL and rerun with `--public-url`, or an explicit bind host with `--host`.

When `status == "skipped"` or `status == "failed"`, echo the `reason` field. If `reason == "nodejs_missing"`, ask whether the user wants NodeJS/dependencies installed; if they decline, do not open the WebUI. Ask for a valid `deck_dir` only if the reason says no deck was found.

Environment

The helper locates the editor launcher in this order:

1. `SENSENOVA_PPT_WORKBENCH_CLI` 2. `PPT_WORKBENCH_CLI` 3. `~/Repository/ppt-editor/src/ppt-editor/bin/sensenova-ppt-workbench.mjs` 4. `~/Repository/ppt-editor/tools/ppt-editor/bi