灵境 JoyCreator 智能接入 Skill

系统架构：三阶段智能管线

用户自然语言输入
      │
      ▼
┌─────────────────┐
│  阶段一：意图路由  │  解析意图类型 + 提取结构化特征
│  (Router)       │  → 参考 references/router-rules.md
└────────┬────────┘
         │ 输出结构化意图 JSON
         ▼
┌─────────────────┐
│  阶段二：模型推荐  │  根据场景特征匹配最优模型
│  (Choice)       │  → 参考 references/choice-rules.md
└────────┬────────┘
         │ 输出 recommended_model + apiId
         ▼
┌─────────────────┐
│  阶段三：API调用  │  构造请求 → 提交任务 → 轮询结果
│  (Executor)     │  → 参考 references/{brand}.md
└─────────────────┘

前置：收集鉴权信息

在任何阶段开始前，必须先向用户索取：

请提供您的 JoyCreator App Key（在京东云 JoyCreator 控制台「应用管理」页面获取）

请求头格式：

Authorization: Bearer \x3Capp_key>
x-jdcloud-request-id: \x3C每次请求生成的唯一 UUID>

阶段一：意图路由 (Router)

详细规则见 references/router-rules.md

任务：将用户的自然语言输入解析为标准结构化 JSON，供阶段二使用。

输出结构：

{
  "intent_type": "IMAGE_GENERATION" | "VIDEO_GENERATION" | "UNKNOWN",
  "core_prompt": "提炼后的高质量提示词",
  "base_params": {
    "aspect_ratio": "16:9",
    "has_reference": false,
    "brand_preference": null
  },
  "video_features": { "needs_audio": false, "camera_movement": null, "duration": 5 },
  "image_features": { "task_num": 1, "high_quality_req": false }
}

如果用户已明确指定模型品牌（如"用可灵生成..."），跳过阶段二，直接进入阶段三。

阶段二：模型推荐 (Choice)

详细规则见 references/choice-rules.md

任务：根据阶段一输出的意图 JSON，按优先级规则匹配最优模型。

输出结构：

{
  "recommended_model": "模型全名",
  "reason": "一句话推荐理由",
  "api_id": "对应 apiId",
  "brand": "doubao | hailuo | kling | paiwo"
}

推荐后向用户展示推荐结果和理由，询问是否确认或更换。

阶段三：API 调用 (Executor)

各品牌详细参数见 references/{brand}.md

统一接口

POST https://model.jdcloud.com/joycreator/openApi/submitTask
Authorization: Bearer \x3Capp_key>
Content-Type: application/json

请求体结构

{
  "apiId": "\x3C阶段二确定的 apiId>",
  "params": {
    "model" 或 "model_name": "\x3C模型名称>",
    "prompt": "\x3C阶段一提炼的 core_prompt>",
    ... 其他参数（从 base_params / video_features / image_features 中映射）
  }
}

参数品牌映射文档

提交响应处理

// 成功
{ "success": true, "genTaskId": "任务ID" }

// 失败
{ "success": false, "error": "错误码", "errorParamName": "出错参数名" }

轮询策略

• 每 3 秒查询一次任务状态
• 最多 60 次（约 3 分钟超时）
• 终态：SUCCESS 或 FAILED

代码生成

使用 scripts/joycreator.py 为用户生成可运行代码：

• 智能模式（推荐）：python scripts/joycreator.py（自动走三阶段管线）
• 参数模式：python scripts/joycreator.py --brand kling --task text2video --prompt "..."

安全提示

• app_key 建议通过环境变量 JOYCREATOR_APP_KEY 传入，不要硬编码
• 图片 URL 必须为公网可访问地址
• 生成结果 URL 有时效限制，请及时下载保存