# lesson-analyzer

**Repository Path**: yldj-it/lesson-analyzer

## Basic Information

- **Project Name**: lesson-analyzer
- **Description**: B站视频学习笔记
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 听课记录生成工具 (Lesson Analyzer)

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-Standard-success.svg)](.agents/skills/lesson-analyzer/SKILL.md)
[![Tencent WorkBuddy](https://img.shields.io/badge/Tencent%20WorkBuddy-Ready-07C160.svg)](https://workbuddy.cn)

根据 B 站公开课视频字幕，自动生成包含**教学目标、教学重难点、教学过程、板书设计、教学评价**（严格对标新课标核心素养）的专业听课记录。支持 **Markdown + Word 双格式本地交付** 及 **腾讯 ima 知识库自动同步归档**。

---

## 🤖 AI 智能体 / Skills 安装指南 (Agent Installation)

本项目不仅是一个独立 CLI 工具，更是一个遵循标准规范的 **Agentic Skill**，可直接安装至各大主流 AI Agent 平台。

### 1. 腾讯 WorkBuddy 安装
WorkBuddy 原生兼容本技能规范：
- **方式一：Git 仓库一键导入（推荐）**
  1. 打开 WorkBuddy 客户端 ➔ 进入 **「设置 / 技能管理」** ➔ 点击 **「从 Git 仓库导入」**。
  2. 输入本仓库 Git 地址（如 `https://github.com/<your-username>/lesson-analyzer.git`）即可自动安装。
- **方式二：本地工作区使用**
  1. `git clone` 本仓库到本地，并在终端运行 `pip install -r requirements.txt`。
  2. 使用 WorkBuddy 打开该文件夹作为工作区，WorkBuddy 会自动识别并加载 `.agents/skills/lesson-analyzer/` 技能。
- **方式三：ZIP 技能包导入**
  - 将 `.agents/skills/lesson-analyzer/` 文件夹打包为 `.zip`，在 WorkBuddy 的「导入本地技能包」中上传。

### 2. Cursor / Windsurf / Trae
- 克隆本项目后作为 Workspace 打开。
- 在规则配置（如 `.cursorrules` / `.windsurfrules`）中添加引用：
  ```markdown
  生成听课记录时，请遵循 .agents/skills/lesson-analyzer/SKILL.md 中的规范与流程。
  ```

### 3. Claude Code / OpenCode / Google Antigravity
- 平台会自动扫描根目录下的 `.agents/skills/lesson-analyzer/SKILL.md`，开箱即用。

---

## ✨ 核心特性

- 📹 **B站字幕智能获取** — 支持扫码登录与 Cookie 凭证持久化，优先官方 CC 字幕 → AI 语音转文字字幕 → 降级解析。
- 🧹 **课堂口语智能清洗** — 自动过滤高频语气词、填充词与重复口误，保留时间戳与核心教学话术。
- 🔍 **学科/年级智能预判与纠错** — 结合标题与课堂字幕智能推断，支持 LLM 根据实际授课内容二次纠错。
- 📖 **新课标 16 学科核心素养对标** — 内置义务教育阶段 16 门学科核心素养框架与评课量规。
- 🏷️ **统一教研文件命名** — 自动提纯课名并输出为 `[学科-年级] 核心课题_听课记录(BV号).ext` 规范格式。
- 📄 **双格式本地交付** — 一键生成排版精美的 `.md` 与 `.docx`（Word 基于纯本地样式转换，无需额外排版）。
- ☁️ **腾讯 ima 知识库自动同步** — 
  - **分层目录智能归档**：支持自然语言/参数临时指定，或按 `默认根目录/学科/年级` 自动分层归类；
  - **知识库名智能映射**：支持直接使用知识库中文名（如“初中信息科技教研组”），自动匹配 ID 上传；
  - **优雅容错机制**：网络或配置异常时不阻断本地文档产出。

---

## 🚀 快速开始 (CLI 运行)

### 1. 环境准备与依赖安装

```bash
# 克隆仓库
git clone https://github.com/<your-username>/lesson-analyzer.git
cd lesson-analyzer

# 安装 Python 依赖（推荐 Python 3.10+）
pip install -r requirements.txt
```

### 2. 配置环境变量 (`.env`)

复制配置模板：
```bash
cp .env.example .env
```

根据实际需要编辑 `.env` 文件：

```ini
# 1. LLM API 配置（支持 DeepSeek / OpenAI / 任何兼容接口）
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# 2. B站 Cookie 存储路径（首次运行未登录会弹出控制台二维码扫码登录）
BILI_COOKIE_PATH=./cookies/bilibili_cookies.json

# 3. 腾讯 ima 知识库 OpenAPI 配置（可选，配置后自动上传）
# 凭证获取地址：https://ima.qq.com/agent-interface
IMA_OPENAPI_CLIENTID=your-client-id
IMA_OPENAPI_APIKEY=your-api-key
IMA_DEFAULT_FOLDER=听课记录
IMA_AUTO_UPLOAD=true

# 可选：指定知识库中文名称（如“初中信息科技教研组”）或 ID
# IMA_KNOWLEDGE_BASE_NAME=初中信息科技教研组
# IMA_KNOWLEDGE_BASE_ID=kb_xxxxxx
```

### 3. 生成听课记录

```bash
# 自动识别学科与年级，生成 Markdown + Docx 并同步至腾讯 ima 知识库
python main.py https://www.bilibili.com/video/BV1oroDB1E1K

# 手动指定学科与年级
python main.py BV1oroDB1E1K --subject 信息科技 --grade 初一

# 动态指定 ima 知识库与目标文件夹
python main.py BV1oroDB1E1K --subject 信息科技 --grade 初一 --ima-kb "初中教研组" --ima-folder "优质课展示"
```

---

## 🛠️ CLI 常用参数说明

```text
用法: python main.py <BV号或B站URL> [选项]

必选参数:
  bvid                      B站视频 BV 号（如 BV1oroDB1E1K）或完整视频 URL

基础选项:
  --subject SUBJECT         学科标识符或中文名（如: math, 语文, 信息科技）。留空则自动预判
  --grade GRADE             年级（如: 五年级, 初一, 初二, 初三）。留空则自动预判
  --output {markdown,docx,both}
                            输出格式（默认: both）
  --title TITLE             自定义课程标题（留空自动提取 B 站视频标题）
  --mode {auto,analyze,raw} 运行模式（默认: auto 自动检测；无本地 LLM 配置时输出 raw 数据）
  --output-dir OUTPUT_DIR   文件输出目录（默认: 当前工作目录）
  --no-clean                跳过字幕口语清洗（调试用）

腾讯 ima 知识库选项:
  --ima-kb IMA_KB           目标知识库中文名称或 ID（如: '初中信息科技教研组'）
  --ima-folder IMA_FOLDER   目标文件夹目录（如: '优质课/七年级'，留空自动按 学科/年级 归档）
  --no-ima                  禁用本次向腾讯 ima 知识库的同步上传
```

---

## ☁️ 腾讯 ima 知识库分层目录机制

```mermaid
flowchart TD
    A[生成听课记录] --> B{1. 用户表述/CLI是否指定目录?}
    B -- 是 (最高优先级) --> C[使用用户指定的自定义目录<br>例如: 优质课评比/初中组]
    B -- 否 --> D{2. .env 是否配置 IMA_DEFAULT_FOLDER?}
    D -- 是 --> E[IMA_DEFAULT_FOLDER + 学科 + 年级<br>例如: 听课记录/信息科技/七年级]
    D -- 否 (系统兜底) --> F[默认规则: 听课记录/{学科}/{年级}<br>例如: 听课记录/数学/初一]
    C --> G[同步上传至腾讯 ima 知识库]
    E --> G
    F --> G
```

---

## 🧰 独立辅助脚本

所有独立工具脚本位于 `.agents/skills/lesson-analyzer/scripts/`：

1. **查询腾讯 ima 账号下的知识库列表与 ID**：
   ```bash
   python .agents/skills/lesson-analyzer/scripts/list_ima_kb.py
   ```
2. **独立上传已生成的 Markdown 笔记到腾讯 ima 知识库**：
   ```bash
   python .agents/skills/lesson-analyzer/scripts/upload_to_ima.py <md路径> --subject 信息科技 --grade 七年级 [--folder 目录] [--kb 知识库名]
   ```
3. **独立将 Markdown 转换为 Word (.docx)**：
   ```bash
   python .agents/skills/lesson-analyzer/scripts/md2docx.py <md路径> [--output <docx路径>]
   ```

---

## 📚 支持的学科标识与别名

内置义务教育新课标 16 门学科核心素养对标：

| 标识符 | 学科标准名 | 常见别名 |
|---|---|---|
| `moral-law` | 道德与法治 | 道法、道德法治 |
| `chinese` | 语文 | 中文、汉语 |
| `history` | 历史 | 历史课 |
| `math` | 数学 | 算术、mathematics |
| `english` | 英语 | 英文 |
| `japanese` | 日语 | 日文 |
| `russian` | 俄语 | 俄文 |
| `geography` | 地理 | 地理课 |
| `science` | 科学 | 小学科学 |
| `physics` | 物理 | 物理课 |
| `chemistry` | 化学 | 化学课 |
| `biology` | 生物学 | 生物 |
| `information-tech` | 信息科技 | 信息技术、微机、计算机、IT |
| `physical-health` | 体育与健康 | 体育、PE |
| `arts` | 艺术 | 音乐、美术、舞蹈、戏剧、影视 |
| `labor` | 劳动 | 劳动教育、劳技 |

---

## 📂 项目结构

```
lesson-analyzer/
├── main.py                                  # CLI 命令行主入口
├── src/
│   ├── auth.py                              # B站扫码登录与 Cookie 凭证管理
│   ├── subtitle.py                          # B站官方与 AI 字幕提取模块
│   ├── subtitle_cleaner.py                  # 字幕口语过滤与去噪清洗
│   ├── subject_predictor.py                 # 学科与年级智能预判
│   ├── analyzer.py                          # 结构化听课记录分析核心引擎
│   ├── docx_converter.py                    # Markdown → Word 排版生成器
│   ├── ima_uploader.py                      # 腾讯 ima OpenAPI 上传与目录映射模块
│   ├── output.py                            # 输出生成与规范化命名封装
│   └── qr_display.py                        # 控制台终端二维码展示组件
├── .agents/skills/lesson-analyzer/
│   ├── SKILL.md                             # Agent 技能规范定义 (Skill Specification)
│   ├── ALIGNMENT.md                         # 核心素养对标量规与评课标准
│   ├── knowledge_base/                      # 16 门学科新课标素养知识库
│   └── scripts/
│       ├── upload_to_ima.py                 # 独立同步上传脚本
│       ├── list_ima_kb.py                   # 知识库列表与 ID 查询工具
│       └── md2docx.py                       # 本地 Word 转换工具
├── tests/                                   # 自动化测试用例
├── requirements.txt                         # Python 依赖清单
├── .env.example                             # 环境变量配置模板
└── README.md                                # 项目使用与 Skill 安装说明
```

---

## 📄 License

本项目基于 [MIT License](LICENSE) 开源。