15 KiB
15 KiB
| name | version | description | metadata | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| interactive-component-json | 8.0.0 | LLM驱动的互动组件配置JSON生成器。 触发场景：用户发送"组件配置-json"或包含飞书剧本文档链接（wiki URL/token）时自动触发。 覆盖全部27种中互动组件类型 + 12种核心互动类型，从飞书wiki剧本文档出发， 经过sheet数据解析、组件类型匹配、LLM生成jsonData、MySQL知识点库匹配kpInfo， 最终输出组件配置JSON和HTML报告。 |
|
注意: 需求描述请更新到 project.md 中！变更记录请更新到 prd.md 中！
互动组件配置JSON生成器
触发场景
用户发送以下格式的消息时触发完整处理流水线：
组件配置json {飞书剧本文档链接}
处理完成后生成 HTML 报告文件，并直接通过飞书 Bot 将 HTML 文件发送给请求者，而不是仅返回文件路径。
发送规则
- 私聊场景：自动发送给当前对话的用户（使用
--send-to <user_id>） - 群聊场景：发送到当前群组（使用
--send-to-chat <chat_id>） - 发送失败时回退为返回文件路径
Agent 调用指引
当收到用户的“组件配置-json”请求时，agent 应执行：
# user_id 从 USER.md 中查找（非 open_id）
cd /root/.openclaw/workspace-xiaoyan/skills/interactive-component-json && \
python3 scripts/pipeline.py "<wiki_url>" --send-to <user_id>
关键点：
- 默认写入本地 SQLite 数据库（
db/components.db）保留生成记录 - 远程数据库推送通过 HTML 报告中的推送按钮完成（用户手动触发）
--send-to参数使用租户级user_id（如4aagb443），不是open_id- 群聊中使用
--send-to-chat <chat_id> - pipeline 会自动完成整个流程并发送文件，agent 无需额外处理发送逻辑
- 如果发送成功，结尾会输出
✅ HTML报告已发送: <message_id> - 如果发送失败，会输出
❌ 发送失败: <error>，此时应回退为告知用户文件路径 - 可加
--dry-run仅生成不写入本地DB（测试用）
HTML 报告推送功能
生成的 HTML 报告内嵌以下推送能力（用户在浏览器中打开 HTML 后操作）：
- 单组件推送：每个成功组件旁有
[配置↑]和[知识↑]按钮[配置↑]推送组件配置 JSON 到远程数据库[知识↑]推送知识点关联到远程数据库
- 一键推送全部：顶部
一键推送全部配置+知识点按钮，带进度条和成功/失败统计 - 可编辑：推送前可直接在 HTML 中修改 JSON 值和知识点 ID
推送通过 CORS 代理服务中转（解决本地 file:// 打开 HTML 时浏览器 Origin 限制）：
- 代理服务：
scripts/proxy_server.py（端口/IP/速率限制见config.json） - pipeline 执行时自动检测并启动代理服务
- 目标接口：
POST https://api-test.valavala.com/content/feishu/notify
代理服务自动管理
pipeline 在生成 HTML 报告前会自动管理代理服务，运行时会输出 [代理] 前缀的状态信息：
| 输出信息 | 含义 |
|---|---|
[代理] ✓ 中转服务正常 → <url> |
代理服务运行正常，HTML 将使用中转地址 |
[代理] ⚠️ 端口被僵死进程占用，正在清理... |
检测到旧进程卡死，自动 kill 并重启 |
[代理] ✓ 中转服务启动成功 → <url> |
代理重启成功 |
[代理] ❌ 中转服务启动失败！ |
代理无法启动，HTML 回退为直连 HTTPS 地址 |
自动恢复机制：当健康检查失败但端口被占用时（僵死进程），pipeline 会自动终止僵死进程并重新启动代理，无需人工干预。
手动管理代理：
# 查看代理进程
ss -tlnp | grep 18080
# 手动启动
python3 scripts/proxy_server.py &
# 手动停止
kill $(ss -tlnp | grep 18080 | grep -oP 'pid=\K\d+')
# 健康检查
curl http://127.0.0.1:18080/health
注意：如果 HTML 报告中显示的推送地址是 https://api-test.valavala.com/... 而非 http://<external_ip>:18080/api/push，说明生成时代理服务未能正常运行。可在 HTML 顶部地址栏手动修改为中转地址，或重新运行 pipeline 生成。
概述
本skill实现从飞书wiki剧本文档 → 结构化组件配置JSON的完整生产流水线。 覆盖全部27种中互动组件类型 + 12种核心互动类型（合作阅读、看图选词、口语快答、口语妙问、看图说话、合作听力、听力拖拽、听力选择、看图组句、看图撰写、邮件组句、邮件撰写），使用**LLM（doubao-seed-2.0-pro）**驱动核心JSON生成。
核心流程
飞书wiki URL
↓
[1] feishu_client.py — 读取文档 → 提取内嵌sheet → 读取sheet全量数据
↓
[2] parse_script.py — 识别组件行 + 提取角色-section对应 + 配置信息
↓
[3] match_component.py — 中文类型名 → cType英文标识 + bitable_token
↓
[4] generate_json.py — per-type prompt模板 → jsonData + 规则化kpInfo
↓ （section映射解析resourceMapping）
[5] db_manager.py — 写入本地SQLite数据库
↓
[6] html_report.py — 生成交互式HTML报告
↓
[7] send_report_via_bot() — 通过飞书Bot发送HTML文件给请求者
快速使用
# 端到端处理（写入DB）
python3 scripts/pipeline.py <wiki_url_or_token>
# 仅生成不写入DB
python3 scripts/pipeline.py <wiki_url_or_token> --dry-run
# 限制处理前N个组件
python3 scripts/pipeline.py <wiki_url_or_token> --dry-run --limit 3
# 生成后自动发送给指定用户（私聊）
python3 scripts/pipeline.py <wiki_url_or_token> --dry-run --send-to <user_id>
# 生成后自动发送到群组
python3 scripts/pipeline.py <wiki_url_or_token> --dry-run --send-to-chat <chat_id>
# 查看中英类型对照表
python3 scripts/match_component.py
# 查看DB统计
python3 scripts/db_manager.py stats
目录结构
interactive-component-json/
├── SKILL.md # 本文件
├── references/
│ ├── component_registry.md # 组件类型注册表（27种中互动 + 15种核心互动）
│ ├── examples/
│ │ └── all_types_examples.json # 从bitable预取的27种类型参考样例（few-shot用）
│ ├── script_format_spec.md # 输入格式规范
│ └── json_output_spec.md # 输出格式规范
├── prompts/
│ ├── __init__.py
│ ├── prompt_registry.py # 16种中互动per-type prompt模板 + 结构化字段解析
│ ├── core_reading_prompts.py # 合作阅读7步prompt模板
│ ├── core_imagedrag_prompts.py # 看图选词5步prompt模板 (2中间+3最终JSON)
│ ├── core_speaking_prompts.py # 口语快答7步prompt模板 (3中间+4最终JSON)
│ ├── core_speaking_inquiry_prompts.py # 口语妙问7步prompt模板 (3中间+4最终JSON)
│ ├── core_speaking_image_prompts.py # 看图说话8步prompt模板 (2中间+6最终JSON)
│ ├── core_listening_order_prompts.py # 合作听力6步prompt模板 (2中间+4最终JSON)
│ ├── core_listening_drag_prompts.py # 听力拖拽7步prompt模板 (2中间+5最终JSON)
│ ├── core_listening_choose_prompts.py # 听力选择5步prompt模板 (2中间+3最终JSON)
│ ├── core_writing_img_prompts.py # 看图组句/看图撰写6步prompt模板 (2中间+4最终JSON)
│ └── core_writing_question_prompts.py # 邮件组句/邮件撰写6步prompt模板 (2中间+4最终JSON)
├── prd.md # 变更记录（持续更新）
├── project.md # 需求描述
├── scripts/
│ ├── pipeline.py # 端到端流水线（主入口）
│ ├── llm_client.py # LLM调用客户端（火山doubao-1.8）
│ ├── feishu_client.py # 飞书API客户端（wiki/sheet/bitable）
│ ├── parse_script.py # 剧本解析器（sheet数据→组件行）
│ ├── match_component.py # 组件类型匹配器（27种中互动 + 核心互动）
│ ├── generate_json.py # LLM驱动的jsonData/kpInfo生成器（含核心互动多步流水线）
│ └── db_manager.py # SQLite数据库管理
└── db/
└── components.db # SQLite数据库（运行时生成）
组件类型注册表
27种中互动组件（已完成）
| 中文名 | cType | bitable_token |
|---|---|---|
| 对话互动 | mid_sentence_dialogue | GH0hbBT0ZavkCesaVQ7c40Zfnub |
| 对话朗读 | mid_dialog_repeat | MuwubKXoSaJe55sO4k9c63VSnmh |
| 对话表达 | mid_dialog_express | IC2kbvgP0aLrj7sfzZicIozZn1e |
| 对话选读 | mid_dialog_select | GsNEbjVVYarWqpsNanTcf8UnnPf |
| 对话选择 | mid_dialog_choose | MsETbgiUAaG8h4sct0ycTOzGnfb |
| 对话挖空 | mid_dialog_fillin | X6nHbUztFaGY5tsSHnKcmeJtnm5 |
| 对话组句 | mid_dialog_sentence | OfgZbhomiaYj2psBNhuc7THMnF9 |
| 信息描写 | mid_message_trace | Nd8cb0tnKankIHsVgw1caL1Xn3f |
| 信息拼词 | mid_message_spell | X0sPb1KERarvocs4rb3cK35AnFg |
| 信息组句 | mid_message_combine | TXYobOAuaakk6KslHp9caUB7nXa |
| 信息补词 | mid_message_fillin | FxwMb8MJmarcRsso2tQcV8thn5g |
| 信息填词 | mid_message_word | ElRebtQe3aeCyOsRjg6cEniznwg |
| 信息填句 | mid_message_sentence | CNFgbIIszaPWXfsekt7cCZjHnVh |
| 物品互动 | mid_vocab_item | BD9Wbi2l9akojasifEvcJG06n3g |
| 图片互动 | mid_vocab_image | VJ1kb9xp8amX8PskntmcLhjpnQe |
| 图片单选 | mid_image_choose | XyIVbYciraBkoasJtV1c3N5Gnhh |
| 图片多选 | mid_image_multiple | XZo5bwagdau3VvsTDL9cJPrInQd |
| 图片有序 | mid_image_sequence | BZWebQROpagkJ0sxArGcsBjwnCU |
| 图片拖拽 | mid_image_drag | Qqq9bVv19aH6LisRrsVcvf6xnqe |
| 材料互动 | mid_sentence_material | Yd84buD91aGxyqstpXqceftHnvM |
| 指令互动 | mid_vocab_instruction | UorxbVCNYaqpx3sOUdTcF6bUnAh |
| 挖空互动 | mid_grammar_cloze | TaU5baUEEagdlusiWXnc7nrGn5b |
| 组句互动 | mid_grammar_sentence | X5w7bWQXGaWu3dsMEE1c3Tp8nBb |
| 填词互动 | mid_vocab_fillBlank | TtjlbkLFgaDi6hsriHZcHBJnnRH |
| 语音互动 | mid_sentence_voice | Qd2kbHD8has9mys3UhWcJbMznrf |
| 造句互动 | mid_sentence_makeSentence | WfHMbzBYPau6hZsmFD0cBwWuncc |
| 发音互动 | mid_pron_pron | CeH5bO3FhaG5cNsPZ4Xc72axnrb |
核心互动组件（已实现12种，其余待定义）
- 合作阅读
core_reading_order— 7步LLM调用，输出 taskData/textData/sequenceData/learningData - 看图选词
core_reading_imageDrag— 5步LLM调用，输出 taskData/questionGroupData/studyData - 口语快答
core_speaking_reply— 7步LLM调用，输出 taskData/settingData/configData/learningData - 口语妙问
core_speaking_inquiry— 7步LLM调用，输出 taskData/settingData/configData/learningData - 看图说话
core_speaking_image— 8步LLM调用，输出 taskData/configData/imageInfo/optionList/questionList/learningData - 合作听力
core_listening_order— 6步LLM调用，输出 taskData/textData/sequenceData/learningData - 听力拖拽
core_listening_drag— 7步LLM调用，输出 taskData/preDialogData/dialogListData/questionListData/learningData - 听力选择
core_listening_choose— 5步LLM调用，输出 taskData/questionGroupData/learningData - 看图组句
core_writing_imgMakeSentence— 6步LLM调用，输出 taskInfo/textInfo/studyInfo/evalInfo - 看图撰写
core_writing_imgWrite— 6步LLM调用，输出 taskInfo/textInfo/studyInfo/evalInfo - 邮件组句
core_writing_questionMakeSentence— 6步LLM调用，输出 taskInfo/textInfo/studyInfo/evalInfo - 邮件撰写
core_writing_questionWrite— 6步LLM调用，输出 taskInfo/textInfo/studyInfo/evalInfo
其余7种详见 scripts/match_component.py 中的 CORE_INTERACTION_TYPES
LLM 配置
| 项目 | 值 |
|---|---|
| Provider | 火山引擎 Ark |
| 模型 | doubao-seed-2.0-pro |
| Endpoint | ep-m-20260301164317-vmmj4 |
| API Key | 环境变量 VOLCANO_API_KEY 或内置默认值 |
| 参考样例 | references/examples/all_types_examples.json（从bitable预取） |
数据库设计
components 表
- component_id, script_id, script_title, component_index
- category(mid/core), cType, type_name, has_image
- level, unit_id, knowledge_points_raw, raw_config
- final_config_json(jsonData), kp_info_json(kpInfo)
- task_data_json, text_data_json, sequence_data_json, learning_data_json (核心互动-通用)
- question_group_json, study_data_json (核心互动-看图选词)
- setting_data_json, config_data_json (核心互动-口语快答/口语妙问)
- image_info_json, option_list_json, question_list_json (核心互动-看图说话)
- pre_dialog_json, dialog_list_json (核心互动-听力拖拽)
- intermediate_json (核心互动中间结果)
- status: draft → generated → validated → exported
- bitable_token, db_table, created_at, updated_at
generation_logs 表
- log_id, component_id, step, model_used, success, error_message
开发进度
- Phase 1: LLM客户端封装（llm_client.py, doubao-1.8-volcano）
- Phase 2: 飞书API客户端（feishu_client.py, wiki/sheet/bitable）
- Phase 3: 剧本解析器增强（parse_script.py, sheet数据解析）
- Phase 4: 组件类型匹配完善（match_component.py, 27种+配图后缀）
- Phase 5: LLM驱动JSON生成（generate_json.py, few-shot参考样例）
- Phase 6: 端到端流水线（pipeline.py, 已验证15/15组件成功）
- Phase 7: v2 per-type prompt模板（prompts/prompt_registry.py, 16种组件）
- Phase 8: section-character映射（parse_script.py, resourceMapping解析）
- Phase 9: generate_json.py v2重写（模板优先 + 回退few-shot）
- Phase 10: pipeline.py v2（section_char_map传递, 15/15验证通过）
- Phase 11: 核心互动组件支持 — 合作阅读(core_reading_order) 7步LLM流水线，已验证通过
- Phase 12: 核心互动扩展 — 看图选词(core_reading_imageDrag) 5步 + 口语快答(core_speaking_reply) 7步，bitable样例验证通过
- Phase 12.5: v6核心互动 — 口语妙问(core_speaking_inquiry) 7步 + 看图说话(core_speaking_image) 8步，bitable样例验证通过
- Phase 12.6: v7听力类核心互动 — 合作听力(core_listening_order) 6步 + 听力拖拽(core_listening_drag) 7步 + 听力选择(core_listening_choose) 5步
- Phase 12.7: v8写作类核心互动 — 看图组句/看图撰写/邮件组句/邮件撰写 各6步LLM流水线
- Phase 13: JSON校验与质量对比
- Phase 14: 批量处理 + 公司DB推送