281 lines
14 KiB
Markdown
281 lines
14 KiB
Markdown
# 互动组件配置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`
|