# idearuncreate — Knowhow 深度调研报告

> 生成时间: 2026-04-13
> 来源: idearuncreate 7 个技能文件深度分析

---

## 一、核心能力维度

| 能力 | 文件 | 说明 |
|------|------|------|
| **剧本生成** | `SKILL.md` | 从素材（新闻/故事/段子）自动生成 classic 互动剧本 |
| **角色图生成** | `generate-images.js` | AI 生图 → 去背景 → 上传 OSS |
| **背景图生成** | `generate-images.js` | AI 生图 → 上传 OSS |
| **封面图生成** | `generate-images.js` | AI 生图 → 上传 OSS |
| **人脸对齐** | `face-align.js` | 像素检测 + 表情叠加 + CSS 偏移量计算 |
| **数据入库** | `insert-drama.js` | MySQL 写入 + bundle.json 生成上传 |
| **声音修复** | `_fix_voices.js` | 更新角色音色 ID + 重新生成 bundle |
| **声音更新** | `update_voices.js` | 批量更新剧本角色音色 |

---

## 二、API 规范与可用性

### 2.1 万界生图 API (Wanjie)

**Base URL**: `maas-openapi.wanjidedata.com`

| 端点 | 模型 | 模式 | 限额 | 说明 |
|------|------|------|------|------|
| `CVSync2AsyncSubmitTask` | `jimeng_t2i_v40` | 异步 | 120s 超时 | 主用生图引擎 |
| `v1beta/models/gemini-3-pro-image-preview:generateContent` | Nano Banana Pro | 同步 | 3 次重试 | Fallback 引擎 |

**调用方式**:
```javascript
// Jimeng (主用)
await wanjieRequest('CVSync2AsyncSubmitTask', {
  req_key: 'jimeng_t2i_v40',
  prompt, width, height,
});

// Fallback
await generateImageNano(prompt);
```

### 2.2 阿里云 OSS

**配置项**:
- `OSS_REGION`: e.g. `oss-cn-beijing`
- `OSS_ACCESS_KEY_ID`
- `OSS_ACCESS_KEY_SECRET`
- `OSS_BUCKET`
- `OSS_ENDPOINT`: e.g. `https://oss-cn-beijing.aliyuncs.com`

**上传路径规则**:
- 角色图: `dramas/{dramaKey}/characters/{hex_name}.png`
- 背景图: `dramas/{dramaKey}/background.png`
- 封面图: `dramas/{dramaKey}/cover.png`
- Bundle: `dramas/{dramaKey}/bundle.json`

### 2.3 数据库 (MySQL)

**连接**:
- Host: `DB_HOST` (默认 127.0.0.1)
- Port: `DB_PORT` (默认 3306)
- User: `DB_USER` (默认 root)
- Password: `DB_PASSWORD`
- Database: `DB_NAME` (默认 shadiao_drama)

**表结构**:
- `dramas` — 剧本元数据
- `drama_characters` — 角色配置 (body_url, face_offset, voice_id)
- `drama_emotions` — 表情映射 (avatar_key, face_url, emotion_name)
- `drama_scripts` — 台词序列 (character, dialogue, avatar, instruction)

### 2.4 豆包复刻音色

**可用音色 (6 个)**:
| ID | 名称 | 性别 | 推荐用途 |
|----|------|------|---------|
| `S_Ex8na7LH1` | Howard | 男 | 搞笑/技术宅/配角 |
| `S_Dx8na7LH1` | Sheldon | 男 | 毒舌/学霸/较真角色 |
| `S_Cx8na7LH1` | Penny | 女 | 活泼/女主/社交达人 |
| `S_Bx8na7LH1` | Leonard | 男 | 温和男主/理性角色 |
| `S_Ax8na7LH1` | Amy | 女 | 知性/认真/学术型女性 |
| `S_zx8na7LH1` | Raj | 男 | 害羞/异域/感性角色 |

**能力**:
- 多语言: zh/en/ja/es/id/pt
- 情感: happy/sad/angry/surprised/fear/hate/excited/coldness/neutral
- 控制格式: `<cot text=描述>文本</cot>`

---

## 三、已知限制

| 限制类型 | 描述 | 规避方案 |
|----------|------|----------|
| **Text Risk** | 内容审核失败，人物特征敏感 | 脱敏改写 prompt，去政治特征 |
| **API 429** | 生图 API 限流 | 3 次重试，间隔递增 |
| **超时** | Jimeng 异步任务 120s | fallback 到 Nano |
| **rembg** | Python 工具未安装 | 跳过去背景，使用原图 |
| **无脸要求** | 必须脸部留白，无五官 | prompt 明确要求无脸纯肤色 |
| **纯色背景** | 角色立绘必须纯色背景 | prompt 要求纯色背景 |
| **字体限制** | 背景/封面禁含文字 | prompt 强调"绝不要含任何文字" |

---

## 四、输入输出规范

### 4.1 剧本 JSON Schema

```json
{
  "name": "string",
  "title": "string",
  "subtitle": "string",
  "description": "string",
  "systemPrompt": "string",
  "isPublic": "boolean",
  "userId": "number",
  "tags": "string",
  "language": "zh|en|multi",
  "i18n": {
    "name": { "en": "...", "ja": "...", ... },
    "title": { ... },
    "subtitle": { ... },
    "desc": { ... },
    "sysPrompt": { ... }
  },
  "characters": [
    {
      "name": "string",
      "nameI18n": { "en": "...", ... },
      "gender": "male|female",
      "voiceId": "S_Ex8na7LH1",
      "imagePrompt": "string"
    }
  ],
  "script": [
    {
      "character": "string",
      "dialogue": "string",
      "dialogueI18n": { ... },
      "avatar": "normal.png|happy.png|...",
      "instruction": "string|null",
      "action": "none|shake|jump|spin|zoom-in",
      "position": "left|right"
    }
  ],
  "backgroundPrompt": "string",
  "coverPrompt": "string"
}
```

### 4.2 生成后 JSON Schema

```json
{
  ...original,
  "dramaKey": "string",
  "characters": [
    {
      "name": "string",
      "bodyUrl": "https://...",
      "faceOffset": { "top": "8%", "left": "35%", "width": "30%" },
      "voiceId": "S_Ex8na7LH1"
    }
  ],
  "backgroundUrl": "https://...",
  "coverUrl": "https://..."
}
```

### 4.3 表情文件映射

| Key | 情感 | Scale |
|-----|------|-------|
| `normal.png` | neutral | 3 |
| `happy.png` | happy | 4 |
| `very_happy.png` | happy | 5 |
| `angry.png` | angry | 4 |
| `sad.png` | sad | 4 |
| `cry.png` | sad | 5 |
| `shock.png` | surprised | 5 |
| `smirk.png` | happy | 3 |
| `speechless.png` | neutral | 2 |

---

## 五、执行流程

```
素材输入
    │
    ▼ 剧本 JSON 生成 (SKILL.md)
    │
    ▼ 生图 (generate-images.js)
    │   Jimeng → fallback Nano
    │   rembg 去背景
    │   OSS 上传
    │
    ▼ 人脸对齐 (face-align.js)
    │   像素引擎检测
    │   标尺图生成
    │   Claude VLM 审阅
    │
    ▼ 数据入库 (insert-drama.js)
    │   MySQL 写入
    │   bundle.json 生成
    │   OSS 上传
    │
    ▼ 输出结果
    dramaKey, bundleUrl
```

---

## 六、错误处理

| 错误 | 检测方式 | 处理 |
|------|----------|------|
| **Text Risk** | API 返回 `code != 10000` | 脱敏改写 prompt 重试 |
| **API 超时** | 120s 无返回 | fallback Nano |
| **网络错误** | `req.on('error')` | 重试 3 次 |
| **OSS 失败** | `client.put` 异常 | 跳过，不阻塞剧本 |
| **DB 失败** | `sequelize` 异常 | 事务回滚 |

---

## 七、评分维度

| 维度 | 指标 | 权重 |
|------|------|------|
| **完整性** | 角色图/背景图/封面图是否全部生成 | 30% |
| **对齐精度** | face-align 是否执行，偏移量是否合理 | 20% |
| **多语言** | i18n 翻译是否覆盖 5+ 语言 | 15% |
| **内容质量** | 台词生动度、戏剧冲突 | 20% |
| **技术合规** | 无脸要求、纯色背景、文字禁含 | 15% |

---

## 八、数据源

| 来源 | 用途 | 链接 |
|------|------|------|
| 万界 API 文档 | 生图 API 规范 | `maas-openapi.wanjidedata.com` |
| 阿里云 OSS | 文件上传 | `oss-cn-beijing.aliyuncs.com` |
| MySQL drama 表 | 数据持久化 | 本地 MySQL |
| 表情图 CDN | 默认表情资源 | `shadiao-drama.oss-cn-beijing.aliyuncs.com/dramas/zhenhuan_chuan/emojis/` |

---

## 九、配置加载优先级

```
--env 参数 > DRAMA_ENV_PATH 环境变量 > 脚本同目录 .env 文件 > 系统环境变量
```

所需配置:
```env
# 数据库
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=xxx
DB_NAME=shadiao_drama

# 阿里云 OSS
OSS_REGION=oss-cn-beijing
OSS_ACCESS_KEY_ID=xxx
OSS_ACCESS_KEY_SECRET=xxx
OSS_BUCKET=xxx
OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com

# 万界生图 API
WANJIE_API_KEY=xxx
```

---

## 十、依赖

- `npm`: ali-oss, sequelize, sharp
- `Python`: rembg (可选)
- `CLI`: node

---

> End of Knowhow