Queenshow 商品详情页

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

基础 URL 说明：

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

快速工作流

1. 查阅 references/openapi.md 获取接口端点详情与请求体（payload）结构。
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 超时、钱包余额耗尽、缺失发布接口等）
• 新增批量执行效率优先规则
• 新增关键规则：严禁跨商品复用 mainImage URL

v2.0.0（2026-06-05）

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

v1.0.0（2026-06-04）

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