Queenshow 商品详情页

使用 Queenshow OpenAPI 为 editor-next 创建 AI 辅助的商品详情页。

基础 URL 说明：

• 通过前端/代理路径调用时，请使用 https://your-host/api/promotion。
• 直连本地后端时，请使用 http://localhost:8890/promotion。

快速工作流

1. 查阅 references/openapi.md 获取接口详情与请求体结构。
2. 所有 /openapi/* 请求均需携带 Authorization: Bearer 或 X-API-Key: 认证头。
3. 通过 POST /openapi/materials/upload 上传本地图片或视频，或直接复用已有公开资源 URL。
4. 调用 POST /openapi/detail-pages 创建详情页。
   • product.mainImages 为必填字段，最多支持 3 个 URL。
   • 新建页面初始状态为一个空的 editor-next 文档。
   • 同一请求将同步提交一个 product_outline_generate 任务。
5. 轮询 GET /openapi/detail-pages/{id}/status，直至 status 变为 outline_ready。
6. 调用 POST /openapi/detail-pages/{id}/outline/apply 应用大纲。
   • 若省略 sections 字段，则直接采用大纲任务生成的结果。
   • 该操作将创建各章节的图片占位符，并提交 section_image_generate 任务。
7. 持续轮询状态，直至变为 completed。
8. 通过 GET /openapi/detail-pages/{id} 获取最终文档。
9. 获取最终页面并验证文档是否包含预期的章节/图片节点：
   • status 为 completed；
   • 文档中每个已应用的章节对应一个图片节点；
   • 每个图片节点均具备 value.url 且 value.generationStatus == "succeeded"。
10. 如需更新 title、desc、thumbnail、product 或完整 document，请使用 POST /openapi/detail-pages/{id}/update。

自动化脚本

可使用 scripts/detail_page_client.py 实现无额外依赖的可重复调用：

python .codex/skills/queenshow-detail-page/scripts/detail_page_client.py 
  --base-url https://your-host/api/promotion 
  --api-key qs_live_xxx 
  --summary 
  run 
  --title "Running Shoes Detail Page" 
  --main-image https://example.com/shoe-1.png 
  --intro "Lightweight running shoes with breathable mesh and rebound foam." 
  --detail-style "clean, premium, high contrast product photography"

脚本默认以 UTF-8 编码发送 JSON，并自动脱敏敏感输出字段（如 plainKey）。仅当某项任务明确要求原始未脱敏输出时，才启用 --show-sensitive。验证过程中如需精简的状态、文档、用量及执行结果输出，请使用 --summary。

常用命令：

• upload：上传本地图片或视频文件。
• materials：列出当前 API Key 已上传的素材。
• create：创建空详情页并启动大纲生成任务。
• pages：列出当前 API Key 创建的所有详情页。
• status：查询详情页任务状态。
• apply-outline：基于大纲生成章节占位符及图片生成任务。
• get：获取最终页面、文档及全部关联任务。
• update：更新 title、desc、thumbnail、product 或完整 document；也可使用 --document-title / --document-desc 安全地拉取当前文档并仅更新其中对应字段。
• task：根据 task id 获取单个任务详情。
• usage：获取当前 API Key 的已消耗额度、预留额度及资源用量统计。
• run：依次完成创建 → 等待大纲就绪 → 应用大纲 → 等待生成完成 → 打印最终详情页。

生产环境最佳实践（源自 100+ 次运行经验）

关键规则

1. 禁止跨商品复用 mainImage URL —— 每个商品必须使用独立上传的图片。复用会导致其他商品内容意外泄露。
2. 先上传，再创建 —— 务必先调用 POST /openapi/materials/upload 获取唯一 COS URL，再创建详情页。
3. 完成后再保存 —— 在状态变为 completed 后，使用 POST /openapi/detail-pages/{id}/update 将完整文档写回并设置缩略图（thumbnail）。
4. 产品简介质量决定输出质量 —— 提供 200–500 字、含具体参数（尺寸、材质、SKU 等）的产品介绍，可获得最优效果。
5. 单商品成本 —— 每个完整详情页约消耗 110–130 幻币（大纲：10 + 5 张图 × 每张 20）。

行业优化风格提示词参考表

常见问题

• RunningHub 超时（发生概率约 10%）：单张图片生成可能超时。遇此情况请重试整个详情页流程。
• 钱包余额耗尽：幻币用尽后，已创建的页面可能被系统自动删除。批量执行前务必调用 GET /openapi/usage 核查余额。
• 无发布（publish）接口：OpenAPI 未提供专用发布/保存接口。请使用 update 持久化内容。分享链接功能不受 published 状态影响。
• outline_ready 响应时间：通常为 20–40 秒，建议每 8–10 秒轮询一次。
• 图片生成耗时：5 张图通常需 2–4 分钟，建议每 15 秒轮询一次。

批量执行规则

批量处理多个商品时，切勿因单个失败而中断流程。应继续处理后续商品，并在全部执行完毕后统一排查失败项。执行效率与整体完成率优先于单次容错。

完成状态判定规则

• 将 completed 视为最终成功状态。
• 将 failed 视为终态错误，需通过 GET /openapi/tasks/{taskId} 查询对应失败任务详情。
• 将 outline_ready 视为可安全调用 outline/apply 的信号。
• 严禁在大纲任务未成功前调用 outline/apply。
• 严格遵守 API Key 配额限制：大批次执行前务必调用 GET /openapi/usage 核查资源余量。
• Windows 系统下，建议优先使用已打包的脚本（兼容中文文本更新）；若自行构造原始 JSON 请求，请确保请求体以 UTF-8 字节编码，并显式设置请求头 Content-Type: application/json; charset=utf-8。

更新日志

v3.0.0（2026-06-06）

• 全面迁移至官方 OpenAPI（/openapi/* 接口），彻底弃用 Playwright 反向工程方案
• 新增来自 9 个行业、13 款商品、100+ 次 API 调用沉淀的生产环境最佳实践
• 新增行业定制化风格提示词对照表
• 归档常见问题（RunningHub 超时、钱包余额耗尽、缺失 publish 接口等）
• 新增批量执行效率优化规则
• 新增关键规则：严禁跨商品复用 mainImage URL

v2.0.0（2026-06-05）

• 初步支持 OpenAPI，引入 API Key 认证机制
• 覆盖完整工作流：上传 → 创建 → 生成大纲 → 应用大纲 → 图片生成 → 保存

v1.0.0（2026-06-04）

• 基于 Playwright 无头浏览器的反向工程实现（已弃用）