sn-ppt-workbench

sn-ppt-workbench

为现有 HTML 幻灯片演示文稿启动或复用 AI PPT 编辑 WebUI。此辅助工具优先使用 Hermes、canvas 和端口转发 URL（如果可用）。没有转发 URL 时，原生主机默认绑定到 localhost，而 Docker/WSL 绑定到 0.0.0.0，以便远程用户通过主机网络访问 WebUI。

使用场景

• 用户已生成演示文稿，并要求打开 WebUI、编辑器或工作台。
• 用户提供了一个 deck_dir，其中包含 task_pack.json、slides/slide_NN.html、pages/page_NNN.html 或根目录下的 HTML 演示文稿。
• 用户要求检查或编辑先前生成的幻灯片，而不重新生成。

硬性规则

1. 不要运行 sn-ppt-entry、sn-ppt-standard、page-html、batch-page-html 或 export。
2. 不要直接编辑幻灯片文件。面向用户的编辑由 WebUI 处理。
3. 如果缺少 deck_dir，仅在 $(pwd)/ppt_decks 下自动检测。 只有调用方明确传入 --search-root 时，才考虑其他根目录；默认情况下绝不扫描主目录。
4. 如果没有找到可用的演示文稿，请向用户索要绝对路径形式的 deck_dir。
5. 工作台尽力启动。如果跳过启动或启动失败，请报告原因，不要尝试通过生成来兜底。
6. 如果用户可能正在使用 SSH、即时通讯或其他远程设备，优先使用转发或 canvas URL，而非 localhost。
7. 从统一 PPT 流程启动时，使用准确的绝对路径 task_pack.deck_dir；打开工作台不得创建或切换任务。
8. 将 task_pack.json 视为进度/恢复状态，将 outline.md 视为用户可编辑的 Story。现有运行时构建可能只提供这些产物中的一部分；请报告兼容性缺口，而不要重新生成演示文稿。

调用方式

直接使用辅助工具：

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

在没有 python3 的原生 Windows 环境中：

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

如果用户未提供演示文稿路径，让辅助工具自动检测：

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

如果可用，请传入同一会话的桥接信息：

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:-}"

可省略 --agent-transport：当 Hermes Gateway 端点和密钥可解析（来自环境变量或 Hermes .env 文件）时，辅助工具会自动选择 gateway；如果只有其他信息，则依次选择 webui / acp / rest。显式标志和 WORKBENCH_AGENT_TRANSPORT 始终优先。没有可解析的桥接时，底部聊天区域会按设计保持只读。

对于非 Hermes 交互式提供方，请传入结构化桥接信息，而不要抓取 CLI/TUI 输出：

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}"

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

当此辅助工具在 Box Agent 中运行时，导出的 BOX_AGENT_PYTHON 或 BOX_AGENT_SKILL_TOOLS_ROOT 环境变量会自动选择 box-agent、acp 和已安装的 box-agent-acp 命令。显式的 WORKBENCH_AGENT_* 标志或环境变量仍优先。

对于 WorkBuddy，仅将 --agent-provider workbuddy 用作提供方标识。请明确告知用户：WorkBuddy 目前没有受支持的 API 或 ACP 接口来连接交互式工作台桥接，因此 WebUI 可以显示 WorkBuddy 状态，但无法将底部聊天区域中的修改请求发送回 WorkBuddy。

CLI 子命令（直接启动备用方式）

绕过 open_workbench.py 并直接调用工作台启动器时，请使用子命令：

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

旧的仅参数形式（不带子命令）已弃用，会打印用法错误。

重启陷阱： 对于相同的 deck-dir，start 会静默复用现有服务器实例（响应中包含 "reused": true）。如果更新了工作台代码，必须先运行 stop，再运行 start，否则旧进程会继续提供过时的代码：

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

绑定主机

工作台按 --host CLI 标志 → WORKBENCH_HOST 环境变量 → 默认值 127.0.0.1 的顺序解析绑定地址。用户需要远程/LAN 访问时，请设置 WORKBENCH_HOST=0.0.0.0：

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

此时，响应中的 url 字段会显示 LAN IP，而不是 127.0.0.1。

输出处理

解析 stdout 中的单行 JSON。

当 status == "ok" 时，对于编辑现有演示文稿的请求，回显返回的 editor_url、public_url 或 workbench.editorUrl。辅助程序也可能返回 generation_url；该 URL 是位于 /progress 的生成进度页面，而编辑器位于 /editor。

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

如果 workbench.reused == true，说明复用了现有服务。

如果 bind_host 为 0.0.0.0，则该 URL 是 Docker/WSL 局域网回退地址。告知用户，该地址必须能从其设备/网络访问；如果无法访问，请他们提供 Hermes/canvas/端口转发 URL，并使用 --public-url 重新运行，或者通过 --host 指定显式绑定主机。

当 status == "skipped" 或 status == "failed" 时，回显 reason 字段。如果 reason == "nodejs_missing"，询问用户是否要安装 NodeJS/依赖；如果他们拒绝，则不要打开 WebUI。只有在原因表明未找到演示文稿时，才要求提供有效的 deck_dir。

环境

辅助程序按以下顺序查找编辑器启动程序：

1. SENSENOVA_PPT_WORKBENCH_CLI
2. 与此 Skill 一起打包的运行时
3. 当前工作树中最近的 src/ppt-editor 源代码检出目录或打包版本
4. 常见的 ~/Repository/ppt-editor 回退路径

辅助程序不会在终端用户启动时构建编辑器。打包的 Skills 必须包含 workbench-runtime；源代码检出目录必须先显式构建 src/ppt-editor，才能使用其启动程序。仓库级别的 webui/ 目录是独立产品，不是此 Skill 的启动程序回退路径。

远程 URL 的发现顺序：

1. 显式指定 --public-url
2. WORKBENCH_PUBLIC_URL、HERMES_WORKBENCH_PUBLIC_URL
3. Hermes/canvas/转发环境变量，例如 HERMES_CANVAS_URL、HERMES_PORT_FORWARD_URL、CANVAS_URL、PORT_FORWARD_URL、TUNNEL_URL
4. Codespaces/Gitpod URL 模式
5. 原生主机上的 localhost，或 Docker/WSL 上基于机器非环回 IPv4 地址的局域网回退地址

网关身份验证设置

对于可写的交互式 Agent 桥接（workbench 中的聊天面板），Hermes 会继续使用现有的 WebUI/Gateway 协议。OpenClaw 应通过兼容 Gateway/REST 的 HTTP 端点公开。Codex、Claude Code 和 Box Agent 应使用 ACP JSON-RPC 适配器，并通过 --acp-command 或 WORKBENCH_ACP_COMMAND 进行配置。Box Agent 默认使用其已安装的 box-agent-acp 入口点。 切勿解析提供方 CLI/TUI 输出以同步聊天内容。

对于可写的 Hermes Gateway 桥接，Gateway API 服务器和 workbench 必须使用匹配的 API 密钥进行身份验证。

关键环境变量：

变量	由谁设置	值
API_SERVER_KEY	Gateway（.env）	共享密钥
WORKBENCH_GATEWAY_API_KEY	Workbench 环境	与 API_SERVER_KEY 相同；首选的显式桥接密钥
HERMES_GATEWAY_BASE_URL	Workbench 环境	http://127.0.0.1:8642
WORKBENCH_AGENT_PROVIDER	Workbench 环境	hermes、openclaw、codex、claude-code、box-agent 或 workbuddy
WORKBENCH_AGENT_TRANSPORT	Workbench 环境	webui、gateway、rest 或 acp
WORKBENCH_AGENT_BASE_URL	Workbench 环境	OpenClaw/Gateway REST 端点
WORKBENCH_AGENT_API_KEY	Workbench 环境	REST 提供方 bearer 令牌
WORKBENCH_ACP_COMMAND	Workbench 环境	ACP 适配器命令，例如 codex-acp
BOX_AGENT_ACP_COMMAND	Box Agent / Workbench 环境	用于覆盖默认 box-agent-acp 适配器命令的可选设置

快速步骤：

• Gateway：在 .env 中设置 API_SERVER_KEY，然后重启 Gateway
• Workbench：将 WORKBENCH_GATEWAY_API_KEY 设置为相同的值，并设置 HERMES_GATEWAY_BASE_URL=http://127.0.0.1:8642
• 如果未设置显式桥接密钥，Node 中继会依次回退使用 API_SERVER_KEY、HERMES_GATEWAY_API_KEY，然后是仅供后端使用的 AI_GATEWAY_API_KEY（默认值为 ppt-editor-dev）。对于自定义/共享 Gateway，建议使用显式桥接密钥。

进度提示

在 helper 运行前后，始终发送一条简短的进度消息：

时间	示例
helper 运行前	正在启动 PPT 预览工作台，不会重新生成幻灯片...
成功	PPT 编辑工作台已启动：http://127.0.0.1:18087
生成进度 URL 可用	生成进度工作台：http://127.0.0.1:18087/progress
跳过／失败	PPT 工作台未启动：<reason>