Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
--- a/openspec/changes/update-kling-capability-version-routing/design.md
+++ b/openspec/changes/update-kling-capability-version-routing/design.md
@@ -0,0 +1,219 @@
+## Context
+
+当前标准 Kling 视频接口具有两个明显特征：
+
+- 提交动作分为：
+  - `POST /kling/v1/videos/text2video`
+  - `POST /kling/v1/videos/image2video`
+- 真正执行版本通过请求体 `model_name` 指定，而不是通过发现到的能力 ID 直接调用
+
+同时，运行时发现已经能够识别出能力型视频标识，例如：
+
+- `kling_video`
+- `kling_image`
+- `kling_effects`
+- `kling_extend`
+- `kling_lip_sync`
+- `kling_virtual_try_on`
+
+这说明 Kling 与 Suno 有相似的结构特征：
+
+- 发现层暴露的是能力入口
+- 执行层需要额外版本字段
+
+但当前标准 Kling adapter 仍然主要围绕版本型模型 ID 运转，例如 `kling-v1-6`。这让以下几层出现语义错位：
+
+1. discovery 发现的是能力
+2. selector 选中的可能是能力
+3. adapter 执行时却把 `model` 理解为可直接提交的执行版本
+
+此外，标准 Kling 视频与 `kling-video-o1`、`kling-video-o1-edit` 不是同一条协议语义：
+
+- 标准 Kling 视频走 `/kling/v1/videos/{action}`
+- `o1` 系列是另一类特例模型，不应被标准 Kling 能力路由误吞
+
+## Goals / Non-Goals
+
+- Goals:
+  - 让标准 Kling 视频沿用 Suno 式“能力入口 + 执行版本”模式
+  - 让 `kling_video` 成为标准 Kling 视频的一等能力模型
+  - 让 `model_name` 成为标准 Kling 视频的执行版本字段
+  - 让 `text2video / image2video` 的版本限制显式建模
+  - 保持旧版本型模型 ID 的兼容，避免历史任务和用户设置立刻失效
+- Non-Goals:
+  - 本次不抽象所有 Kling 能力为统一多动作产品面板
+  - 本次不处理 `o1` 系列的专用协议
+  - 本次不一次性把所有 Kling 高级字段做成复杂 UI 控件
+
+## Decisions
+
+- Decision: 区分标准 Kling 能力模型和执行版本
+
+  - `kling_video` 表示标准 Kling 视频能力入口
+  - `model_name` 表示具体执行版本，例如 `kling-v3`
+  - 发现层与选择层优先使用 `kling_video`
+  - 执行层始终向标准接口提交 `model_name`
+
+- Decision: action 继续由请求语义决定，而不是再拆成两个能力模型
+
+  - 显式传入 `klingAction2` 时优先使用
+  - 否则：
+    - 有参考图 => `image2video`
+    - 无参考图 => `text2video`
+
+- Decision: 版本合法性绑定到 action
+
+  - `text2video` 的可选版本：
+    - `kling-v3`
+    - `kling-v2-6`
+    - `kling-v2-1`
+    - `kling-v1-6`
+    - `kling-v1-5`
+  - `image2video` 的可选版本：
+    - `kling-v3`
+    - `kling-v2-6`
+    - `kling-v2-1`
+    - `kling-v1-6`
+    - `kling-v1-5`
+
+- Decision: 历史版本型模型 ID 作为兼容输入，而不是主路径
+
+  - 若请求模型为 `kling-v1-5` 或 `kling-v1-6`
+  - 运行时仍允许提交
+  - 但内部按“标准 Kling 能力 + 指定 model_name”解释
+
+- Decision: `o1` 系列与标准 Kling 视频能力显式隔离
+
+  - `kling-video-o1`
+  - `kling-video-o1-edit`
+  - 不参与标准 `kling.video` binding 推断
+  - 不复用 `/kling/v1/videos/{action}` 的标准版本校验
+
+- Decision: UI 先暴露最小必要版本选择
+
+  - 第一阶段保证用户可以为标准 Kling 能力选择：
+    - `model_name`
+    - `klingAction2`
+    - `mode`
+    - `cfg_scale`
+    - `negative_prompt`
+  - `camera_control` 通过平铺字段纳入参数体系：
+    - `camera_control_type`
+    - `camera_horizontal / vertical / pan / tilt / roll / zoom`
+  - `image_tail` 与 `callback_url` 暂不纳入本阶段可视化参数体系
+
+- Decision: Kling 数值参数同时在 UI 元数据和 adapter 层校验
+
+  - `cfg_scale` 取值范围固定为 `[0, 1]`
+  - `camera_control` 的六个数值字段固定为 `[-10, 10]` 且必须是整数
+  - 参数面板与 MCP schema 暴露相同的边界信息
+  - adapter 仍负责最终校验，避免 workflow / MCP 直接绕过 UI
+
+## Proposed Data Model
+
+```ts
+interface ProviderVideoBindingMetadata {
+  allowedDurations?: string[];
+  defaultDuration?: string;
+  durationMode?: 'request-param' | 'model-alias';
+  durationField?: string;
+  durationToModelMap?: Record<string, string>;
+  strictDurationValidation?: boolean;
+  resultMode?: 'inline-url' | 'download-content';
+  downloadPathTemplate?: string;
+
+  versionField?: string;
+  versionOptions?: string[];
+  defaultVersion?: string;
+  versionOptionsByAction?: Record<string, string[]>;
+}
+
+interface KlingResolvedRequest {
+  action: 'text2video' | 'image2video';
+  modelName: string;
+}
+```
+
+标准 Kling 视频 binding 期望类似：
+
+```ts
+{
+  operation: 'video',
+  protocol: 'kling.video',
+  requestSchema: 'kling.video.auto-action-json',
+  submitPath: '/kling/v1/videos/{action}',
+  pollPathTemplate: '/kling/v1/videos/{action}/{taskId}',
+  metadata: {
+    video: {
+      versionField: 'model_name',
+      defaultVersion: 'kling-v1-6',
+      versionOptions: [
+        'kling-v3',
+        'kling-v2-6',
+        'kling-v2-1',
+        'kling-v1-6',
+        'kling-v1-5'
+      ],
+      versionOptionsByAction: {
+        text2video: ['kling-v3', 'kling-v2-6', 'kling-v2-1', 'kling-v1-6', 'kling-v1-5'],
+        image2video: ['kling-v3', 'kling-v2-6', 'kling-v2-1', 'kling-v1-6', 'kling-v1-5']
+      }
+    }
+  }
+}
+```
+
+## Execution Flow
+
+1. 发现层识别到 `kling_video`
+2. 选择器保留 `profileId::kling_video`
+3. 运行时 planner 解析到标准 Kling 视频 binding
+4. adapter 根据请求判断 action：
+   - `text2video`
+   - `image2video`
+5. adapter 从以下来源解析执行版本：
+   - `params.model_name`
+   - binding `defaultVersion`
+   - 历史兼容的 `request.model === kling-v*`
+6. adapter 按 action 校验版本是否允许
+7. adapter 构造标准 Kling 请求体并提交
+
+## Compatibility Strategy
+
+### Discovery / Selection
+
+- 新发现到的 `kling_video` 应作为标准主路径能力模型
+- 老的静态版本型模型可以继续存在，但不再作为未来扩展的主心智
+
+### Runtime
+
+- 当请求模型是 `kling_video` 时：
+  - 必须解析 `model_name`
+- 当请求模型是 `kling-v1-5` 或 `kling-v1-6` 时：
+  - 直接将该值视为显式执行版本
+  - 同时仍走标准 Kling adapter
+
+### UI
+
+- 若当前选择的是 `kling_video`
+  - 参数区应能选择 `model_name`
+- 若当前选择的是旧版本型模型
+  - UI 可以继续工作
+  - 但内部行为应与显式 `model_name` 一致
+
+## Risks / Trade-offs
+
+- 风险: 运行时同时支持 `kling_video` 和 `kling-v*`，可能产生双轨心智
+  - Mitigation: 将 `kling_video` 作为主路径，仅保留 `kling-v*` 兼容输入
+
+- 风险: Kling 版本集合仍按 action 维护，后续若再次分叉，UI 或 workflow 可能产生非法组合
+  - Mitigation: 在 adapter 层做最终校验，并在参数层尽量按 action 过滤
+
+- 风险: `o1` 系列误被标准 Kling 识别规则吞掉
+  - Mitigation: 明确在 binding inference 和 adapter 匹配中排除 `kling-video-o1*`
+
+## Open Questions
+
+- 默认版本是否应从 `kling-v1-6` 逐步切换到 `kling-v3`
+- `image_tail` 是否在第一阶段就进入 UI 参数面板
+- `mode / cfg_scale / camera_control` 是否应在后续改为动态 binding 参数，而不是继续依赖静态透传