---
name: studytime-analysis
description: 分析指定角色的完课时间分布与学习规律，包含一周内时间分布、跨周趋势、寒暑假排除。支持 Markdown 和 HTML 双格式输出。触发词：「学习时间分析」「看看学习时间」「学习时间有什么特点」「studytime」。
slug: studytime-analysis
version: 1.1.0
---

# 学习时间分析技能

## 触发规则

用户通过飞书发送以下格式的消息时触发：
- 「学习时间分析 [角色ID]」
- 「[角色ID] 学习时间分析」
- 「看看 [角色ID] 的学习时间有什么特点」
- 「分析 [角色ID] 的完课时间规律」

角色ID 必须是纯数字。

## 工作流程

1. **参数提取** — 从用户消息中提取角色ID
2. **数据采集** — 执行 Python 脚本查询该角色全部完课记录（包含寒暑假，非按月过滤）
3. **Markdown 报告输出** — 脚本自动完成分析并输出格式化报告：
   - **角色基本信息**：角色ID、账号ID、手机号后4位、角色名字、性别、年龄、留存状态
   - **一周分布**（仅非寒暑假数据）：周一至周日各天完课数量 + 周一至周五上课时段
   - **跨周趋势**（全部数据）：覆盖总周数、周均完课数、连续性、中断周、趋势变化
   - **完课记录明细**（全部数据）：完整的完课时间表
   - **HTML 提示**：报告末尾自动提示用户可生成 HTML 详细报告
4. **HTML 生成（用户确认后）** — 生成精美 HTML 文件，通过飞书发送给用户

## 调用方式

### Markdown 报告（默认）
```bash
cd /root/.openclaw/workspace-xiaoban && \
export PG_DB_HOST=bj-postgres-16pob4sg.sql.tencentcdb.com \
  PG_DB_PORT=28591 PG_DB_USER=ai_member \
  PG_DB_PASSWORD='...' PG_DB_DATABASE=vala && \
export MYSQL_HOST_online=bj-cdb-dh2fkqa0.sql.tencentcdb.com \
  MYSQL_USERNAME_online=read_only MYSQL_PASSWORD_online='...' MYSQL_PORT_online=27751 && \
python3 skills/studytime-analysis/scripts/studytime_analysis.py <role_id>
```

### HTML 报告
```bash
# 在上述环境变量基础上：
python3 skills/studytime-analysis/scripts/studytime_analysis.py <role_id> --format html -o output/studytime_<role_id>.html
```

## HTML 报告结构（5 部分）

1. **基本信息卡** — 角色ID、账号ID、手机号后4位、姓名、性别、年龄、留存状态、注册时间、第一次完课时间、最后一次完课时间、最后一次完课的 Level/Unit/Lesson
2. **完课记录明细表** — 序号、Level、Unit（单元名）、Lesson、星期、时段、开始上课时间、完课时间、完课耗时
3. **周上课时间分布分析** — 文字总结（最活跃星期、时段偏好、周末情况）
4. **跨周趋势分析** — 文字总结（周数、连续性、前后段对比、趋势方向）
5. **关键特征总结** — 要点列表（规模、活跃度、时段特征、趋势、寒暑假等）

## 数据库说明

- **完课数据源**: PostgreSQL Online (`vala` 库) — `user_chapter_play_record_0~7`（8张分表）
- **角色信息源**: MySQL Online (`vala_user` 库) — `vala_app_character` + `vala_app_account`
- **章节映射源**: MySQL Online (`vala` 库) — `vala_game_chapter` + `vala_game_season_package`
- **筛选**: `play_status = 1`（已完成），查询全量数据（不按月过滤）
- **寒暑假处理**: 1-2月（寒假）和 7-8月（暑假）的记录仅在一周时间分布中排除，跨周趋势和完课明细完整保留
- **章节映射**: 通过 `chapter_id` → `vala_game_chapter.id` → `vala_game_season_package` 获取 Level/Unit/Lesson 信息

## 交互流程

1. 用户发起学习时间分析请求 → 输出 Markdown 报告
2. 报告末尾显示：「💡 是否需要将以上所有详细信息生成为一个 HTML 文件？回复「是」或「需要」即可。」
3. 用户回复「是」/「需要」→ 执行 HTML 生成 → 通过飞书发送 HTML 文件给用户
4. 用户回复其他内容 → 不执行 HTML 生成