--- name: interactive-component-json version: 8.0.0 description: > LLM驱动的互动组件配置JSON生成器。 触发场景：用户发送"组件配置-json"或包含飞书剧本文档链接（wiki URL/token）时自动触发。 覆盖全部27种中互动组件类型 + 12种核心互动类型，从飞书wiki剧本文档出发， 经过sheet数据解析、组件类型匹配、LLM生成jsonData、MySQL知识点库匹配kpInfo， 最终输出组件配置JSON和HTML报告。 metadata: requires: tools: ["exec", "read", "write"] python: ["requests", "pymysql"] identity: bot llm: provider: volcano model: doubao-1.8-volcano endpoint: ep-20260106175024-6stxn --- 注意: 需求描述请更新到 project.md 中！变更记录请更新到 prd.md 中！ # 互动组件配置JSON生成器 ## 触发场景 用户发送以下格式的消息时触发完整处理流水线： ``` 组件配置json {飞书剧本文档链接} ``` 处理完成后生成 HTML 报告文件，并**直接通过飞书 Bot 将 HTML 文件发送给请求者**，而不是仅返回文件路径。 ### 发送规则 - 私聊场景：自动发送给当前对话的用户（使用 `--send-to `） - 群聊场景：发送到当前群组（使用 `--send-to-chat `） - 发送失败时回退为返回文件路径 ### Agent 调用指引 当收到用户的“组件配置-json”请求时，agent 应执行： ```bash # user_id 从 USER.md 中查找（非 open_id） cd /root/.openclaw/workspace-xiaoyan/skills/interactive-component-json && \ python3 scripts/pipeline.py "" --send-to ``` 关键点： - 默认写入本地 SQLite 数据库（`db/components.db`）保留生成记录 - 远程数据库推送通过 HTML 报告中的推送按钮完成（用户手动触发） - `--send-to` 参数使用租户级 `user_id`（如 `4aagb443`），不是 `open_id` - 群聊中使用 `--send-to-chat ` - pipeline 会自动完成整个流程并发送文件，agent 无需额外处理发送逻辑 - 如果发送成功，结尾会输出 `✅ HTML报告已发送: ` - 如果发送失败，会输出 `❌ 发送失败: `，此时应回退为告知用户文件路径 - 可加 `--dry-run` 仅生成不写入本地DB（测试用） ### HTML 报告推送功能 生成的 HTML 报告内嵌以下推送能力（用户在浏览器中打开 HTML 后操作）： 1. **单组件推送**：每个成功组件旁有 `[配置↑]` 和 `[知识↑]` 按钮 - `[配置↑]` 推送组件配置 JSON 到远程数据库 - `[知识↑]` 推送知识点关联到远程数据库 2. **一键推送全部**：顶部 `一键推送全部配置+知识点` 按钮，带进度条和成功/失败统计 3. **可编辑**：推送前可直接在 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 报告前会自动管理代理服务，运行时会输出 `[代理]` 前缀的状态信息： | 输出信息 | 含义 | |----------|------| | `[代理] ✓ 中转服务正常 → ` | 代理服务运行正常，HTML 将使用中转地址 | | `[代理] ⚠️ 端口被僵死进程占用，正在清理...` | 检测到旧进程卡死，自动 kill 并重启 | | `[代理] ✓ 中转服务启动成功 → ` | 代理重启成功 | | `[代理] ❌ 中转服务启动失败！` | 代理无法启动，HTML 回退为直连 HTTPS 地址 | **自动恢复机制**：当健康检查失败但端口被占用时（僵死进程），pipeline 会自动终止僵死进程并重新启动代理，无需人工干预。 **手动管理代理**： ```bash # 查看代理进程 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://: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文件给请求者 ``` ### 快速使用 ```bash # 端到端处理（写入DB） python3 scripts/pipeline.py # 仅生成不写入DB python3 scripts/pipeline.py --dry-run # 限制处理前N个组件 python3 scripts/pipeline.py --dry-run --limit 3 # 生成后自动发送给指定用户（私聊） python3 scripts/pipeline.py --dry-run --send-to # 生成后自动发送到群组 python3 scripts/pipeline.py --dry-run --send-to-chat # 查看中英类型对照表 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 ## 开发进度 - [x] Phase 1: LLM客户端封装（llm_client.py, doubao-1.8-volcano） - [x] Phase 2: 飞书API客户端（feishu_client.py, wiki/sheet/bitable） - [x] Phase 3: 剧本解析器增强（parse_script.py, sheet数据解析） - [x] Phase 4: 组件类型匹配完善（match_component.py, 27种+配图后缀） - [x] Phase 5: LLM驱动JSON生成（generate_json.py, few-shot参考样例） - [x] Phase 6: 端到端流水线（pipeline.py, 已验证15/15组件成功） - [x] Phase 7: v2 per-type prompt模板（prompts/prompt_registry.py, 16种组件） - [x] Phase 8: section-character映射（parse_script.py, resourceMapping解析） - [x] Phase 9: generate_json.py v2重写（模板优先 + 回退few-shot） - [x] Phase 10: pipeline.py v2（section_char_map传递, 15/15验证通过） - [x] Phase 11: 核心互动组件支持 — 合作阅读(core_reading_order) 7步LLM流水线，已验证通过 - [x] Phase 12: 核心互动扩展 — 看图选词(core_reading_imageDrag) 5步 + 口语快答(core_speaking_reply) 7步，bitable样例验证通过 - [x] Phase 12.5: v6核心互动 — 口语妙问(core_speaking_inquiry) 7步 + 看图说话(core_speaking_image) 8步，bitable样例验证通过 - [x] Phase 12.6: v7听力类核心互动 — 合作听力(core_listening_order) 6步 + 听力拖拽(core_listening_drag) 7步 + 听力选择(core_listening_choose) 5步 - [x] Phase 12.7: v8写作类核心互动 — 看图组句/看图撰写/邮件组句/邮件撰写 各6步LLM流水线 - [ ] Phase 13: JSON校验与质量对比 - [ ] Phase 14: 批量处理 + 公司DB推送