Demo 入口验收说明

本文对应 issue #29 和 #32，描述 Cloudflare Pages 上的可访问入口和离线验收方法。 它只验收静态演示材料与隔离的本地预览，不启动真实机器人、不读取真实配置，也不等同于上线发布或 Jetson 验收。

Cloudflare Pages 构建产物

部署使用 Cloudflare Pages 免费计划。部署目录先由 npm run build:pages 生成，再由 scripts/seed-jev-review-preview.js --static-dir _site/jev-review 写入 JEV fixture；本地可用 npm run build:pages:preview 一次执行相同顺序，包含：

• /index.html：claw-bot 产品入口，展示环境、MCP 工具、语音闭环和安装方式。
• /README.html、/README.zh-CN.html、/docs/jev-fast-path-demo.html、/docs/demo-acceptance.html、/docs/claw-bot-deploy-acceptance.html、/docs/mcp-preview-standard.html、/docs/sweetwater-runtime.html、/skills/claw_bot/SKILL.html：由仓库 Markdown 在构建时生成的 HTML 文档页，文档内相对 Markdown 链接会改写为 HTML 路径。
• /jev-review/index.html、/jev-review/app.js、/jev-review/data.json 与 /jev-review/paper.md：JEV 对照预览及其合成静态 fixture。Pages 页面自动回退到 data.json，无需后端即可展示一条明确标记的合成记录；不会调用模型或控制器。实时 /api/* 请求仍只在本地预览服务提供。
• /server.json：MCP Registry 元数据，可核对包名、启动命令和 robot_* 工具入口。
• /skills/claw_bot/SKILL.html：打包给决策 Agent 的能力边界和调用约束。
• /docs/claw-bot-deploy-acceptance.html：Jetson/运行态验收规约，作为参考材料，不在 Pages 构建中部署机器人运行时。

构建成功只证明 artifact 已生成；部署状态和页面内容以 Cloudflare Pages 部署回执及线上 URL 为准。

发布路径与夜间新鲜度检查

当前仓库没有 Cloudflare Pages 项目配置、Wrangler 工作流或 Cloudflare API 凭据引用；仓库中唯一的静态发布工作流 .github/workflows/pages.yml 是 GitHub Pages 工作流，且目前已手动禁用。因此，claw-bot-demo.pages.dev 的 Git-connected 项目/生产分支、实际发布命令和 Cloudflare 账号持有人，不能从仓库或 GitHub 仓库设置核实，必须由 Cloudflare 项目管理员在 Pages 项目设置中确认。pages.dev 子域名表明项目名很可能是 claw-bot-demo，但这也是待管理员核实的事实。

管理员确认项目后，已有本地 Wrangler 登录的维护者可在仓库根目录执行以下非交互路径；它只发布本地生成的静态 _site，不创建资源、不修改 DNS，也不会把凭据写入仓库：

wrangler whoami
npm ci
npm run build:pages
wrangler pages deploy _site --project-name claw-bot-demo

如果 wrangler whoami 未显示有权访问该项目，应停止并交给 Cloudflare 项目管理员处理，不能在 CI 中交互登录或新增凭据。本仓库不自动执行这条发布命令。

每晚 GitHub Actions 任务 .github/workflows/pages-demo-freshness.yml 从 main 构建 artifact，并对公开的 https://claw-bot-demo.pages.dev 逐页比较 <html lang>；它不需要 Cloudflare secret，也不发布页面。任务失败表示线上内容落后于 main 的构建结果，尤其能捕获 README.zh-CN 仍返回 lang="en" 的情况。手工复核可运行：

npm ci
npm run build:pages
node scripts/check-pages-demo-freshness.js _site https://claw-bot-demo.pages.dev

Cloudflare Pages 可能将带 .html 的请求（例如 /docs/demo-acceptance.html 或 /README.html）以 HTTP 308 重定向到无扩展名的规范路径（分别为 /docs/demo-acceptance 和 /README）。因此，线上验收应跟随重定向并检查最终响应；.html 是本地构建产物路径，不能据此判断线上页面失败。

Cloudflare Pages 线上静态验收

线上入口：https://claw-bot-demo.pages.dev/。

按以下步骤验收：

1. 打开 https://claw-bot-demo.pages.dev/，确认首页能打开并能访问文档、server.json 和安装说明。
2. 打开 https://claw-bot-demo.pages.dev/jev-review/，确认页面显示“合成数据”提示、场景选择和 offline-preview-fixture 记录。
3. 在 JEV 页面打开论文大纲，确认 https://claw-bot-demo.pages.dev/jev-review/paper.md 可访问。
4. 浏览器网络面板中不应出现必须成功的 /api/data 请求；页面应从同目录 data.json 和 paper.md 加载。
5. 该记录仅用于验证展示与页面交互，不代表模型质量、时延或机器人结果。静态模式不提供真实模型调用或机器人动作。

对首页链接指向的 .html 路径做命令行检查时跟随 Pages 重定向，例如：

curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' \
  https://claw-bot-demo.pages.dev/docs/demo-acceptance.html

预期最终结果为 200 https://claw-bot-demo.pages.dev/docs/demo-acceptance；中间出现的 308 是 Pages 的正常规范化重定向。README 页面可用同样方式检查 https://claw-bot-demo.pages.dev/README.html，预期最终路径为 /README。

本地构建与预览

npm ci
npm run build:pages:preview
python3 -m http.server 4173 --directory _site

然后打开 http://127.0.0.1:4173/。构建只生成静态文件，不依赖运行时 CDN、模型、控制器或 hosting 账号。

PAGES_OUTPUT_DIR 默认是仓库内的 _site，自定义路径须位于仓库内或系统临时目录内的专用子目录；不接受父目录、.. 路径段或 symlink 逃逸。构建会先清空该输出目录，请勿使用存放其他数据的目录。

本地静态验收

在仓库根目录运行：

set -eu
site="$(mktemp -d)"
PAGES_OUTPUT_DIR="$site" npm run build:pages
node scripts/seed-jev-review-preview.js --static-dir "$site/jev-review"
test -s "$site/index.html"
test -s "$site/README.html"
test -s "$site/README.zh-CN.html"
test -s "$site/docs/jev-fast-path-demo.html"
test -s "$site/docs/demo-acceptance.html"
test -s "$site/docs/claw-bot-deploy-acceptance.html"
test -s "$site/docs/mcp-preview-standard.html"
test -s "$site/docs/sweetwater-runtime.html"
test -s "$site/jev-review/index.html"
test -s "$site/jev-review/data.json"
test -s "$site/jev-review/paper.md"
test -s "$site/server.json"
test -s "$site/skills/claw_bot/SKILL.html"
echo "static demo artifact: $site"

预期结果是所有 test -s 通过，并能从 index.html 看到 MCP、安装和语音闭环入口；docs/jev-fast-path-demo.html 能追溯离线 JEV 命令和限制；server.json 能看到 MCP 元数据。该检查不会联网调用模型或控制器。

JEV 交互预览（本地、隔离）

JEV 界面的交互 API 由本地命令提供。使用合成端口和隔离输出目录。

先在隔离目录写入一条合成记录，再启动预览服务；该步骤不调用模型、不读取真实配置：

demo_home="$(mktemp -d)"
export CLAW_BOT_JEV_REVIEW_DIR="$demo_home/review"
node scripts/seed-jev-review-preview.js
JEV_REVIEW_PORT=14318 node bin/claw-bot-jev-review.js

在同一台机器打开 http://127.0.0.1:14318/，选择“合成离线 fixture”记录（ID 为 offline-preview-fixture） 后点击“重检并预览 claw-bot 命令”。不要设置 TYPESAFE_API_KEY，不要点击需要真实 Jev/GPT 服务的运行按钮。预览适配器使用独立内存状态和 dry-run 命令，输出应标注“隔离命令预览”且不连接控制器。完成后停止该前台进程并删除本次临时目录。

MCP 预览（离线、无真实环境）

MCP 的可复现检查使用仓库测试和 fixture：

test_home="$(mktemp -d)"
HOME="$test_home" \
XDG_CONFIG_HOME="$test_home/.config" \
CLAW_BOT_DASHBOARD_PORT=18787 \
npm run test:mcp

test:mcp 验证 robot_status、环境路由、感知、动作、订阅和反馈的协议契约；测试使用内存/合成环境。它不读取用户配置，不访问 Jetson，不向真实机器人发送动作。

验收记录

逐项记录以下事实即可关闭本地验收：

1. Cloudflare Pages 部署回执存在，线上入口为 https://claw-bot-demo.pages.dev/。
2. 首页链接可打开 /docs/demo-acceptance.html、JEV 文档和 server.json。
3. 静态检查通过；本地 JEV 界面能加载静态资源。
4. MCP 合成测试通过；issue #9、#10、#11 对应修复已分别通过 #22、#24、#25 合入主分支。
5. 未执行真实模型调用或机器人动作。