ai_member_xiaoyan/skills/interactive-component-json/prd.md

互动组件配置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 读取多维表格数据，可用于参考理解数据结构：

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