li-Record-lecture-video

通用录播课学习计划生成 Skill (v2.0.2)

触发条件

当用户提供已录好的视频课程清单（含视频标题和时长），并要求生成按天分组的学习计划Excel时触发。

典型触发词：录播课学习计划、按天安排学习、视频时长分组、生成学习计划表、学习计划Excel、录播课排期

核心原则

1. 课程内容是既成事实：视频标题和时长从源头直接搬运，不可改写
2. 生成的是学习安排：告诉学员每天学哪几个视频、学到什么程度，不是课程设计
3. 模板可替换：支持用户提供自定义 Excel 模板（占位符模式或自动检测），也支持内置 11 列默认模板

安全约束（必须遵守）

⚠️ Agent 在调用本 Skill 时必须执行以下安全检查，不可跳过。

输入方式

方式A：Excel 文件

用户提供包含「视频标题」和「视频时长」列的 .xlsx 文件。 脚本自动读取并解析时长（支持 timedelta 和数值格式）。

方式B：直接文字输入

用户通过聊天发送视频清单，格式灵活：

课程导入.mp4  16分钟
1.1 信息安全定义.mp4  22分钟
...

Agent 需先解析为结构化数据（标题、分钟数），再写入临时 JSON 供脚本读取。

方式C：混合输入

用户提供 Excel 视频清单 + 口头补充课程信息（如考试说明）。

模板模式（v2.0 新增）

用户自定义模板

用户可以提供自己的 Excel 模板，Skill 读取模板后在数据区插入按天分组的视频数据。模板中的所有样式、配色、列宽、合并规则将被保留。

方式 A：占位符模式（推荐）

在模板的 Excel 中，在数据区第一行的任意单元格写入 {{DAILY_DATA}}。Skill 会自动找到该标记，删除该行，并在该位置插入分组数据。

模板中还可使用以下占位符（可选）：

• {{COURSE_TITLE}} — 课程大标题
• {{REGISTRATION_INFO}} — 报名阶段文字
• {{PHASE_TITLE}} — 精讲阶段标题
• {{EXAM_INFO}} — 考试介绍
• {{EXAM_PHASE}} — 考试阶段
• {{SCORE_INFO}} — 成绩查询

方式 B：自动检测模式

如果模板不含占位符，Skill 会扫描表头行自动匹配列名。支持的列名关键词：

方式 C：内置默认模板（向后兼容）

不提供模板时，使用内置 11 列通用标准模板（适用于各类培训认证课程场景）。所有现有 v1.x 用法无需改动。

模板模式 config 示例

{
  "course_name": "课程名称",
  "daily_hours": 2,
  "template": "path/to/user_template.xlsx",
  "videos": [["视频.mp4", 30.0]],
  "guide": {"视频.mp4": ["目标", "验证", "内容"]},
  "registration_info": "...",
  "exam_info": "...",
  "output": "output/学习计划.xlsx"
}

必需参数（缺失时主动询问）

工作流

1. 确认输入：读取 Excel 或解析文字，确认视频数量和总时长
2. 收集缺失参数：按上表问用户（一次性问完，不要逐个问）
3. 确认模板（v2.0）：检查用户是否提供了自定义模板 Excel；如有则使用模板模式，否则使用内置默认模板
4. 构建 config.json：根据场景选路径（见下方）
5. 自动生成学习指引（可选但推荐）：对无 guide 的视频自动匹配学习目标/验证/内容（见下方）；也可使用 scripts/auto_guide.py 提供的 build_guide_map() 函数
6. 安全校验：检查输出路径不在系统目录、参数在合法范围
7. 调用脚本：python scripts/generate_study_plan.py --config [--template <模板路径>]
8. 日期校验：脚本自动检查实际分组天数与用户指定日期范围是否匹配，不匹配时输出 WARNING
9. 展示结果：用 present_files 展示生成的 .xlsx

config.json 构建指南

场景 A — 简单模式（无学习指引）：视频清单来自 Excel，不需要填写学习目标/验证/内容。

直接用 input_excel 字段，脚本自动读取视频：

{
  "course_name": "课程名称",
  "daily_hours": 2,
  "phase_name": "精讲阶段",
  "phase_dates": "X月XX日-X月XX日",
  "input_excel": {
    "path": "用户提供的Excel路径",
    "title_col": 1,
    "dur_col": 2,
    "header_row": 1
  },
  "output": "output/学习计划.xlsx"
}

场景 B — 完整模式（含学习指引）：需要填写每视频的学习目标/验证/内容。

先用 Python 读取 Excel 提取视频标题和时长，构造 videos 数组，再用关键词匹配自动生成 guide 映射（见下一节），最终构建完整 config：

{
  "course_name": "...",
  "daily_hours": 2,
  "phase_name": "...",
  "phase_dates": "...",
  "videos": [["标题.mp4", 16.5], ["另一个.mp4", 22.0]],
  "guide": {
    "标题.mp4": ["学习目标", "验证方式", "学习内容"],
    "另一个.mp4": ["目标", "验证", "内容"]
  },
  "exam_info": "考试信息...",
  "score_info": "成绩查询...",
  "output": "output/学习计划.xlsx"
}

场景 C — 模板模式（v2.0 新增）：用户提供了自定义 Excel 模板。

{
  "course_name": "课程名称",
  "daily_hours": 2,
  "template": "path/to/user_template.xlsx",
  "phase_name": "精讲阶段",
  "phase_dates": "X月XX日-X月XX日",
  "videos": [["标题.mp4", 16.5]],
  "guide": {"标题.mp4": ["目标", "验证", "内容"]},
  "registration_info": "注册说明...",
  "exam_info": "考试信息...",
  "exam_phase": "考试阶段...",
  "score_info": "成绩查询...",
  "output": "output/学习计划.xlsx"
}

先用 Python 读取 Excel 提取视频标题和时长，构造 videos 数组，再用关键词匹配自动生成 guide 映射（见下一节），最终构建完整 config：

{
  "course_name": "...",
  "daily_hours": 2,
  "phase_name": "...",
  "phase_dates": "...",
  "videos": [["标题.mp4", 16.5], ["另一个.mp4", 22.0]],
  "guide": {
    "标题.mp4": ["学习目标", "验证方式", "学习内容"],
    "另一个.mp4": ["目标", "验证", "内容"]
  },
  "exam_info": "考试信息...",
  "score_info": "成绩查询...",
  "output": "output/学习计划.xlsx"
}

自动学习指引生成

当用户未提供每视频的学习目标/验证/内容时，Agent 应使用内置 scripts/auto_guide.py 模块自动生成 guide 映射。

推荐用法：调用 auto_guide.py

import sys
sys.path.insert(0, r'/scripts')
import auto_guide

# 从视频标题列表生成 guide 映射
guide = auto_guide.build_guide_map([title for title, _ in videos])

# 验证覆盖率
missing = auto_guide.validate_coverage(guide, [title for title, _ in videos])
auto_guide.print_coverage_report(guide, [title for title, _ in videos])

高级用法：自定义规则

import auto_guide

# 定义课程专属关键词规则
my_rules = [
    auto_guide.make_simple_rule('DevOps', ['devops', 'dev ops'],
        ('掌握DevOps核心概念', '能说明DevOps定义与价值', 'DevOps原则与实践')),
    auto_guide.make_multi_rule('流水线', ['流水线', 'pipeline', 'CI/CD'],
        ('掌握持续交付流水线', '能设计部署流水线', 'CI/CD流程与工具')),
]

# 用自定义规则构建
guide = auto_guide.build_guide_map(videos, rules=my_rules)

内置通用规则

auto_guide.py 内置了三组通用规则模板（COMMON_RULES），Agent 也可以基于视频标题主题自行构建 auto_guide.build_guide_map(course='iso27001'|'devops'|'general') 快速生成。

注意事项

• 规则按优先级从具体到宽泛排列
• 兜底规则确保每个视频都有指引，不留空
• 匹配规则随课程主题调整（ISO27001 / TOGAF / DevOps 等各有不同关键词）
• 如有教学大纲 PDF 可作为更精确的指引来源（Agent 应基于 PDF 手动构建 guide 映射）

脚本调用说明

脚本接受一个 JSON 配置文件，包含所有课程参数和视频数据。

python scripts/generate_study_plan.py --config /path/to/config.json

# 或使用自定义模板
python scripts/generate_study_plan.py --config config.json --template my_template.xlsx

配置文件结构见 references/template-spec.md。

备用：无配置文件模式

如果只有视频清单和课程名，Agent 可直接构造最小 config：

{
  "course_name": "课程名称",
  "daily_hours": 2,
  "videos": [["视频标题.mp4", 16.5], ["另一个视频.mp4", 22.0]],
  "phase_name": "精讲阶段",
  "phase_dates": "X月XX日-X月XX日",
  "registration_info": "默认注册说明",
  "exam_info": "默认考试信息",
  "exam_phase": "默认考试阶段",
  "score_info": "默认成绩查询",
  "guide": {},
  "output": "output/学习计划.xlsx"
}

其中 videos 为 [[标题, 分钟数], ...]。

输出物

• 一个 .xlsx 文件，按用户选择的模式输出：
  • 自定义模板模式：保留用户模板的全部样式和布局，在数据区填入按天分组数据
  • 内置模板模式：11 列通用学习计划表（含大标题、报名阶段、精讲阶段、按天数据、考试信息、成绩查询）
• 每天自动小计，同天单元格合并，表头冻结

兼容性

与智能体无关：脚本是纯 Python + openpyxl，任何能执行 Python 的 agent（opencode、hermes、WorkBuddy 等）均可使用。Agent 的职责只是收集参数、构造 config JSON、调用脚本、展示结果。

---

使用说明 / Usage Instructions / Mode d'emploi

中文

功能简介：通用录播课学习计划生成工具。适用于任何培训认证课程（ISO27001、TOGAF、DevOps、ITIL 等），将已录好的视频课程清单（标题+时长）自动生成按天分组的学习计划 Excel 表格。

三种使用方式：

1. 内置模板（零配置）：直接提供视频清单 + 课程名，自动生成 11 列通用标准学习计划
2. 自定义模板（占位符）：上传自己的 Excel 模板，在数据区标记 {{DAILY_DATA}}，工具自动填入分组数据，保留模板全部样式
3. 自定义模板（自动检测）：上传任意 Excel 模板，工具自动扫描表头关键词匹配列

使用步骤：

1. 准备视频清单：Excel 文件（含标题列和时长列）或直接在聊天中发送 视频名 时长 格式的列表
2. 告诉 Agent 课程名称和每天想学多少小时（默认 2 小时）
3. 可选：提供一个自定义 Excel 模板（支持占位符或自动检测）
4. Agent 自动构造配置，调用生成脚本
5. 完成：获得按天分组的完整学习计划 Excel

示例：

我有一个 ISO27001 的录播课，视频清单在 videos.xlsx 里，每天学 2 小时，帮我生成学习计划

用我这个 Excel 模板生成学习计划，视频数据在 videos.xlsx

安全提示：脚本仅读取您指定的文件，输出受限目录外写入，视频标题自动防 Excel 注入。不访问网络，不上传数据。

---

English

Overview: A universal recorded-course study plan generator. Works with any training/certification course (ISO27001, TOGAF, DevOps, ITIL, etc.). Automatically generates a day-by-day study plan Excel from a recorded video list (title + duration).

Three Modes:

1. Built-in Template (zero config): Just provide a video list + course name to generate an 11-column universal study plan
2. Custom Template (placeholders): Upload your own Excel template, mark {{DAILY_DATA}} in the data area, and the tool fills in grouped daily data — preserving all of your template's styling
3. Custom Template (auto-detect): Upload any Excel template; the tool scans header keywords to auto-map columns

Steps:

1. Prepare your video list: either an Excel file (with title and duration columns) or send video_name duration pairs directly in chat
2. Tell the Agent the course name and how many hours per day you'd like to study (default: 2h)
3. Optional: provide a custom Excel template (supports placeholders or auto-detection)
4. The Agent builds a config and invokes the generation script
5. Done: receive a complete day-by-day study plan Excel

Example:

I have an ISO27001 recorded course, the video list is in videos.xlsx, 2 hours per day. Generate a study plan.

Use my Excel template to generate a study plan, with video data from videos.xlsx

Security: The script only reads files you explicitly provide. Output is restricted from system directories. Video titles are automatically sanitized against Excel formula injection. No network access, no data upload.

---

Français

Aperçu : Un générateur universel de plans d'étude pour cours enregistrés. Fonctionne avec tout type de formation/certification (ISO27001, TOGAF, DevOps, ITIL, etc.). Génère automatiquement un plan d'étude Excel jour par jour à partir d'une liste de vidéos (titre + durée).

Trois Modes :

1. Modèle intégré (zéro config) : Fournissez simplement une liste de vidéos + le nom du cours pour générer un plan standard universel à 11 colonnes
2. Modèle personnalisé (placeholders) : Téléversez votre propre modèle Excel, marquez {{DAILY_DATA}} dans la zone de données, l'outil remplit les données groupées par jour — en conservant tout le style de votre modèle
3. Modèle personnalisé (auto-détection) : Téléversez n'importe quel modèle Excel ; l'outil scanne les mots-clés d'en-tête pour mapper automatiquement les colonnes

Étapes :

1. Préparez votre liste de vidéos : soit un fichier Excel (avec colonnes titre et durée), soit envoyez des paires nom_vidéo durée directement dans le chat
2. Indiquez à l'Agent le nom du cours et le nombre d'heures d'étude par jour souhaité (par défaut : 2h)
3. Optionnel : fournissez un modèle Excel personnalisé (supporte les placeholders ou l'auto-détection)
4. L'Agent construit une configuration et lance le script de génération
5. Terminé : recevez un plan d'étude Excel complet jour par jour

Exemple :

J'ai un cours enregistré ISO27001, la liste des vidéos est dans videos.xlsx, 2 heures par jour. Générez un plan d'étude.

Utilisez mon modèle Excel pour générer un plan d'étude, avec les données vidéo de videos.xlsx

Sécurité : Le script lit uniquement les fichiers que vous fournissez explicitement. La sortie est limitée aux répertoires non-système. Les titres des vidéos sont automatiquement protégés contre l'injection de formules Excel. Pas d'accès réseau, pas de téléchargement de données.