---
name: interactive-component-json
version: 8.0.0
description: >
  LLM驱动的互动组件配置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生成器

## 文本输出规范(jsonData 内容强制遵守)

所有生成的 JSON 配置中,任何嵌入的文本内容(题目、选项、解析、台词等)必须遵守:
1. 禁止 Markdown 标记(`**` `*` `__` `_` `#` `>` `-`),纯文本输出
2. 英式拼写优先(colour/centre/travelling 等)
3. 标点符号规范:英文半角(. , ! ? :),中文全角(,。!?：),不混用。特别注意:英文冒号必须用半角 `:`,不得用全角 `：`
4. 中英文混排空格规范:中文与英文/数字之间加半角空格(如"汇报 Jay 不配合"),纯中文或纯英文内容不加额外空格

## 触发场景

用户发送以下格式的消息时触发完整处理流水线:

```
组件配置json {飞书剧本文档链接}
```

处理完成后生成 HTML 报告文件,并**直接通过飞书 Bot 将 HTML 文件发送给请求者**,而不是仅返回文件路径。

### 发送规则

- 私聊场景:自动发送给当前对话的用户(使用 `--send-to <user_id>`)
- 群聊场景:发送到当前群组(使用 `--send-to-chat <chat_id>`)
- 发送失败时回退为返回文件路径

### Agent 调用指引

当收到用户的"组件配置"请求时，agent 应执行：

```bash
# user_id 从 USER.md 中查找(非 open_id)
cd "/root/.openclaw/workspace-xiaoyan/business_production/组件配置/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 **仍使用代理地址**,推送前需手动运行 `python3 scripts/proxy_server.py &` |

**自动恢复机制**:当健康检查失败但端口被占用时(僵死进程),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 始终嵌入代理地址 `http://<external_ip>:18080/api/push`(只要 config.json 存在)。若代理未运行,推送前手动执行 `python3 scripts/proxy_server.py &` 启动即可,无需重新生成 HTML。

## 概述

本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 |

### 核心互动组件(已实现13种,其余待定义)
- **合作阅读** `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
- **看图拼词** `core_writing_imgMakeWord` - 7步(Step5规则),输出 taskInfo/preDialog/imageInfo/questionList/studyInfo

其余6种详见 `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推送
