293 lines
15 KiB
Markdown
293 lines
15 KiB
Markdown
---
|
||
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 <user_id>`）
|
||
- 群聊场景：发送到当前群组（使用 `--send-to-chat <chat_id>`）
|
||
- 发送失败时回退为返回文件路径
|
||
|
||
### Agent 调用指引
|
||
|
||
当收到用户的“组件配置-json”请求时，agent 应执行：
|
||
|
||
```bash
|
||
# 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 后操作）：
|
||
|
||
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 报告前会自动管理代理服务，运行时会输出 `[代理]` 前缀的状态信息：
|
||
|
||
| 输出信息 | 含义 |
|
||
|----------|------|
|
||
| `[代理] ✓ 中转服务正常 → <url>` | 代理服务运行正常，HTML 将使用中转地址 |
|
||
| `[代理] ⚠️ 端口被僵死进程占用，正在清理...` | 检测到旧进程卡死，自动 kill 并重启 |
|
||
| `[代理] ✓ 中转服务启动成功 → <url>` | 代理重启成功 |
|
||
| `[代理] ❌ 中转服务启动失败！` | 代理无法启动，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://<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文件给请求者
|
||
```
|
||
|
||
### 快速使用
|
||
|
||
```bash
|
||
# 端到端处理（写入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
|
||
|
||
## 开发进度
|
||
|
||
- [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推送
|