# 互动组件配置JSON生成器 — 产品需求文档

## v1 基础版（已完成）

### 目标
从飞书wiki剧本文档出发，经过sheet数据解析、组件类型匹配、LLM驱动的jsonData生成，
最终输出组件配置JSON并持久化到本地SQLite数据库。

### 已实现能力
- 27种中互动组件类型的中英对照注册表
- 飞书wiki文档+内嵌sheet读取（feishu_client.py）
- 组件行识别与教研配置提取（parse_script.py）
- 通用LLM生成（few-shot参考样例驱动）
- 规则化kpInfo生成
- 端到端pipeline + SQLite持久化

---

## v2 精确Prompt优化（已完成 2026-04-28）

> 来源: /root/.openclaw/prd/xiaoyan_comp_json_skill_v2.md

### 核心需求

1. **每种组件类型使用独立的精确Prompt模板**，包含完整的字段定义、抽取规则、输出格式和样例，
   方便排查问题。输出规则设置应尽量全部保留，最终达成与原有流程一样的输出效果。

2. **角色物品配置（resourceMapping）通过 section 对应关系解析**：
   - 读取文档markdown中 "角色-section对应" 表格，获取每个section的角色id对应关系
   - 组件配置行的"配置信息"列标记了所属section（如 "S1主线"）
   - 根据section找到对应的角色id，写入最终JSON的 resourceMapping 字段

3. **教研配置文本拆解为结构化字段**，作为prompt的输入变量：
   - 标题、情境引入、互动内容、后置对话、角色配置、资源配置、互动反馈、互动描述、学习意义构建、语音识别热词

### 覆盖组件类型（16种已提供精确prompt）

#### 对话类（6种）
| 中文名 | cType | 特殊字段 |
|--------|-------|----------|
| 对话朗读 | mid_dialog_repeat | question(去掉"朗读"), imgShowTimingList, audioFile/itemName |
| 对话表达 | mid_dialog_express | asrPrompt(热词), tip, corFeedback/errFeedback, question.desc, example |
| 对话选择 | mid_dialog_choose | optionList+needAudio, answer, corFeedback/errFeedback |
| 对话选读 | mid_dialog_select | optionList+needAudio+feedback(per-option) |
| 对话挖空 | mid_dialog_fillin | question(desc+content), optionGroupList, corFeedback/errFeedback |
| 对话组句 | mid_dialog_sentence | question(desc+content), optionList, answer(索引), tip, corFeedback/errFeedback |

#### 信息类（6种）
| 中文名 | cType | 特殊字段 |
|--------|-------|----------|
| 信息描写 | mid_message_trace | cDesc, trace, img, inputSet=[] |
| 信息拼词 | mid_message_spell | cDesc, inputConfig(stem+value), stemList, tip |
| 信息组句 | mid_message_combine | cDesc, optionList, answer(索引), tip |
| 信息补词 | mid_message_fillin | cDesc, inputConfig(stem+value), tip |
| 信息填词 | mid_message_word | cDesc, answer(数组), tip |
| 信息填句 | mid_message_sentence | cDesc, answerHint, tip |

#### 图片类（4种）
| 中文名 | cType | 特殊字段 |
|--------|-------|----------|
| 图片单选 | mid_image_choose | meaning, imageInfo(questionImg+answerImg), optionList({ID}_option_XX.png), answer, cDesc |
| 图片多选 | mid_image_multiple | 同上，answer为多个索引 |
| 图片有序 | mid_image_sequence | 同上，answer为排序索引 |
| 图片拖拽 | mid_image_drag | 同上，question可含content(音频) |

### 通用输出规则（所有类型）
- 输出必须在一行内完成，不要换行
- 不要使用markdown代码块包裹
- 输出内容必须是合法JSON，可直接用于 JSON.parse
- resourceMapping中id必须为int类型
- "无"的字段使用空数组[]或空对象{}
- imgShowTimingList对应关系：preDialog:情境引入、content:互动内容、feedback:互动反馈、postDialog:后置对话
- img字段值为"{ID}.png"（仅资源配置中存在图片时机时）
- audioFile字段值为"{ID}.mp3"（仅资源配置中存在音频载体时）
- "（音频）"标记 → needAudio:true
- "（正确）"标记 → answer索引，抽取时不包含标记本身

### 实现方案
- `prompts/prompt_registry.py` — 16种组件的prompt模板 + 结构化字段解析 + prompt构建
- `parse_script.py` 增强 — extract_section_character_map() + resolve_resource_mapping() + config_info列
- `generate_json.py` 重写 — 优先使用per-type prompt模板，无模板时回退到few-shot
- `pipeline.py` 更新 — 传递section_char_map到generate_component

### 参考文档
- 输入: https://makee-interactive.feishu.cn/wiki/Z3ydwGJnti4zaDkLXLNcGk3enod

---

## v3 resourceMapping补全 + LLM升级（已完成 2026-04-28）

> 来源: /root/.openclaw/prd/xiaoyan_comp_json/v3.md

### 核心需求

1. **resourceMapping字段补全**：所有互动类型都有resourceMapping字段，此前6种信息类（mid_message_*）
   的prompt模板中遗漏了该字段。已为全部6种信息类模板补充resourceMapping字段定义和角色配置输入。

2. **section-character映射验证**：确认每个组件的config_info（如"S1主线"）正确关联到角色ID：
   - S1-S14 → Eva:663, Peter:653, Vicky:658
   - S15-S16 → Eva:738, Peter:739
   - 实现：parse_script.py中extract_section_character_map()解析markdown表格，
     resolve_resource_mapping()根据config_info列的section编号查找对应角色ID

3. **LLM模型切换到doubao-seed-2.0-pro**：
   - 端点：ep-m-20260301164317-vmmj4
   - 关闭thinking模式（payload中设置 `thinking: {type: "disabled"}`）
   - 性能提升：单组件生成从~17s降至~4s

### 变更文件
- `prompts/prompt_registry.py` — 6种mid_message_*模板补充resourceMapping + INPUT_FIELDS补充角色配置
- `scripts/llm_client.py` — 新增doubao-seed-2.0-pro模型注册，设为默认，disable_thinking支持

---

## v3.1 语音识别热词自动生成（已完成 2026-04-28）

### 核心需求
对涉及语音识别的互动组件，基于教研配置上下文自动生成热词（asrPrompt）：
- **表达类**（mid_dialog_express）：LLM根据情境引入、互动内容、后置对话自动生成高频/难识别词汇，逗号连接
- **朗读类**：返回"无"

### 实现
- `scripts/generate_json.py` — 新增 `generate_asr_hotwords()` 函数 + `ASR_TYPES` 集合
- 在 `_generate_with_template()` 中，对 ASR_TYPES 类型在构建prompt前自动生成热词并注入 parsed_fields

---

## v4 核心互动组件支持（已完成 2026-04-28）

> 来源: /root/.openclaw/prd/xiaoyan_comp_json/v4.md

### 数据来源说明
**数据来源不变** — 仍然是剧本文档表格的"组件配置"列。多维表格（bitable）是旧的数据流程，
我们基于剧本文档进行自动化生产是新流程，目标是替换多维表格流程。

### 飞书多维表格读取经验（参考用）
已有能力通过 `feishu_client.py` 读取多维表格数据，可用于参考理解数据结构：
```python
from feishu_client import list_bitable_tables, read_bitable_records

# 列出表
tables = list_bitable_tables('H6DJweNkpigCbak2Y5LcTZ8Vnfb')
# 读取记录
records = read_bitable_records('H6DJweNkpigCbak2Y5LcTZ8Vnfb', 'tblAsmsV19vUnFb8', page_size=5)
# 每条记录: {"record_id": str, "fields": dict}
```

### 一. 合作阅读（core_reading_order）

#### 输入
剧本"组件配置"列 = "教研配置-任务" + "教研配置-材料" 拼接，包含以下【】section：
- 【任务标题】、【任务背景】、【通关知识】（来自教研配置-任务）
- 【阅读材料】（来自教研配置-材料）
- 【流程编排】、【角色配置】、【专有词汇】、【学习材料】等

#### 多维表格参考（合作阅读 bitable）
- wiki: H6DJweNkpigCbak2Y5LcTZ8Vnfb
- S3表: tblAsmsV19vUnFb8
- 字段列表: ID, 教研配置-任务, 教研配置-材料, 角色配置, 通关知识, 流程编排, 专有名词,
  阅读材料, 学习材料, 互动题目, 阅读材料格式化, 学习材料格式化, 学习过程配置,
  taskData, textData, sequenceData, learningData, kpInfo

#### 生成流水线（7步LLM调用）
```
教研配置-材料 ──┬──→ [Step 1] 阅读材料格式化 ──→ 材料正文
               └──→ [Step 2] 学习材料格式化 ──→ 学习内容(段落)
                                                    ↓
              [Step 3] 学习过程配置 ←── 文章材料(S1) + 学习内容(S2) + 专有词汇
                  │
    ┌─────────────┼─────────────┬─────────────┐
    ↓             ↓             ↓             ↓
[Step 4]      [Step 5]      [Step 6]      [Step 7]
taskData      textData    sequenceData  learningData
```

#### 4个最终JSON输出
- **taskData**: cType, cId, title, sceneDesc, img, key(通关知识), resourceMapping
- **textData**: text(材料正文), question(互动题目)
- **sequenceData**: sequence(流程编排→材料/对话/题目序列)
- **learningData**: closing, learningPart(段落+题目+反馈)

### 实现
- `scripts/match_component.py` — 注册 `core_reading_order` cType
- `prompts/core_reading_prompts.py` — 7步prompt模板 + `build_step_prompt()` + `CORE_READING_STEPS` 注册表
- `scripts/generate_json.py` — 新增:
  - `CORE_TYPES` 集合
  - `parse_core_reading_fields()` 从【】section提取各字段
  - `generate_core_reading_order()` 7步LLM调用编排器
  - `generate_component()` 增加核心互动分流逻辑，返回 taskData/textData/sequenceData/learningData
- `scripts/pipeline.py` — 核心互动结果写入多JSON字段，HTML报告传递 category
- `scripts/db_manager.py` — 新增5列: task_data_json, text_data_json, sequence_data_json, learning_data_json, intermediate_json + 自动迁移
- `scripts/html_report.py` — 核心互动卡片展示多JSON section + 中间结果 + 核心互动badge

### 验证
使用 bitable 样例数据 (ID=0325001) 端到端通过7步生成，所有JSON结构正确。

---

## v5 看图选词 + 口语快答 核心互动支持（已完成 2026-04-28）

> 来源: prd/v5.md

### 二. 看图选词（core_reading_imageDrag）

#### 输入
剧本"组件配置"列 = "教研-导览配置" + "教研-互动配置" 拼接，包含以下【】section：
- 【任务标题】、【任务背景】、【任务描述】、【通关知识】（来自教研-导览配置）
- 【阅读材料】、【互动问题】（来自教研-互动配置）

#### 多维表格参考
- wiki: MVo7wugWfimJPIkxhJCcqppFnyf
- 表: tblKl9CGmARjpw1O
- 字段: ID, 教研-导览配置, 教研-互动配置, 用户任务描述, 用户任务知识, 角色配置, 专有名词,
  学习流程配置, 互动描述, taskInfo, questionGroup, studyInfo, kpInfo

#### 生成流水线（5步LLM调用）
```
教研配置 ──┬──→ [Step 1] 学习流程配置 ──→ 中间文本
           └──→ [Step 2] 互动描述      ──→ 中间文本
                                              ↓
               [Step 3] taskInfo  ←── 用户任务描述 + 用户任务知识 + 角色配置 + 互动描述
               [Step 4] questionGroup ←── 互动配置(材料+问题)
               [Step 5] studyInfo     ←── 学习流程配置(S1)
```

#### 3个最终JSON输出
- **taskData**: cType, cId, title, taskDesc, sceneDesc, key(通关知识), resourceMapping, cDesc
- **questionGroupData**: [{ image, questionList: [{ type, npcName, content/title, desc, optionList, answer }] }]
- **studyData**: { learningPart: [{ image, learning: [{ question, optionList(+feedback), answer }] }], closing }

### 三. 口语快答（core_speaking_reply）

#### 输入
剧本"组件配置"列 = "教研-用户视角任务信息" + "教研-任务规则与NPC设定" 拼接，包含以下【】section：
- 【任务标题】、【任务背景】、【任务描述】、【通关知识】（用户视角任务信息）
- 【对话角色】、【回合设定】、【任务设定】、【示例对话】、【通过规则】（任务规则与NPC设定）

#### 多维表格参考
- wiki: TSwcw0nFmi21khkpUndchNMsn6f
- 表: tbl4Qg8d45O58Cqf
- 字段: ID, 教研-用户视角任务信息, 教研-任务规则与NPC设定, 用户任务描述, 用户任务知识,
  示例对话, 角色配置, 对话角色及回合设定, 通过规则, 任务设定, 任务背景,
  学习流程配置, promptInfo配置, 语音识别热词, taskData, settingData, configData, learningData, kpInfo

#### 生成流水线（7步LLM调用）
```
教研配置 ──┬──→ [Step 1] 学习流程配置   ──→ 中间文本
           ├──→ [Step 2] promptInfo配置  ──→ 中间文本
           └──→ [Step 3] 语音识别热词    ──→ 中间文本
                                               ↓
               [Step 4] taskData     ←── 用户任务描述 + 用户任务知识 + 角色配置
               [Step 5] settingData  ←── 对话配置(角色+回合)
               [Step 6] configData   ←── 热词(S3) + 背景 + promptInfo(S2) + 示例对话 + 通过规则
               [Step 7] learningData ←── 学习流程配置(S1)
```

#### 4个最终JSON输出
- **taskData**: cType, cId, title, taskDesc, sceneDesc, img, key(通关知识), resourceMapping
- **settingData**: { setting: { npcName, round, checkRound } }
- **configData**: { config: { asrPrompt, promptInfo: { default, scene, in_progress_goal, final_goal, reference_dialog, user_task, user_scene, user_knowledge } } }
- **learningData**: { learningPart: { opening, wrongReadLeadIn, learning: [{ question, optionList(+feedback), answer, read, feedback }], closing } }

### 实现
- `scripts/match_component.py` — 注册 `core_reading_imageDrag` + `core_speaking_reply` cType 及 db_table
- `prompts/core_imagedrag_prompts.py` — 5步prompt模板 (2中间+3最终JSON)
- `prompts/core_speaking_prompts.py` — 7步prompt模板 (3中间+4最终JSON)
- `scripts/generate_json.py` — 新增:
  - `parse_core_imagedrag_fields()` / `parse_core_speaking_fields()` 字段解析器
  - `generate_core_reading_imagedrag()` 5步LLM编排器
  - `generate_core_speaking_reply()` 7步LLM编排器
  - `generate_component()` 增加两种新核心类型分流
  - `CORE_TYPES` 集合新增两种类型
- `scripts/pipeline.py` — 核心互动结果写入多JSON字段 (questionGroupData/studyData/settingData/configData)
- `scripts/html_report.py` — 核心互动卡片展示全部JSON section
- `scripts/db_manager.py` — 新增4列: question_group_json, study_data_json, setting_data_json, config_data_json + 自动迁移 + allowed_fields

### 验证
- 看图选词 (ID=1201001): 5步生成全部通过，taskData/questionGroupData/studyData 结构正确，耗时~47s
- 口语快答 (ID=0325001): 7步生成全部通过，taskData/settingData/configData/learningData 结构正确，耗时~90s
- HTML验证报告: `outputs/V5核心互动验证 - imageDrag + speaking`