灵境 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
x-jdcloud-request-id: <每次请求生成的唯一 UUID>

阶段一：意图路由 (Router)

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

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

输出结构：
json
{
intenttype: IMAGEGENERATION | VIDEO_GENERATION | UNKNOWN,
core_prompt: 提炼后的高质量提示词,
base_params: {
aspect_ratio: 16:9,
has_reference: false,
brand_preference: null
},
videofeatures: { needsaudio: false, camera_movement: null, duration: 5 },
imagefeatures: { tasknum: 1, highqualityreq: false }
}

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

阶段二：模型推荐 (Choice)

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

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

输出结构：
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
Content-Type: application/json

请求体结构

参数品牌映射文档

提交响应处理

// 失败
{ 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 ...

安全提示

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