设计文档 — 课程表 / 日程管理智能助手

版本: v1.0
更新日期: 2026-06-08
目标: 帮助用户自动处理课程表 / 日程相关文档，提取关键信息并生成结构化输出，支持多格式导出与日历集成。

---

目录

• 1. 概述

• 2. 相关依赖库与环境初始化

• 3. Step One: 预处理

  • 3.1 输入识别与路由

  • 3.2 图片处理

  • 3.3 表格处理

  • 3.4 PDF 处理

  • 3.5 Word 处理

  • 3.6 其他格式处理

  • 3.7 数据清洗与结构化

  • 3.8 处理结果可视化与持久化

• 4. Step Two: 核心功能（格式化输出）

  • 4.1 用户需求导出格式调查

  • 4.2 默认模板设计

  • 4.3 课程 / 日程元素标签体系

  • 4.4 输出格式详细规范

• 5. Step Three: 自动化

  • 5.1 检测主机 Agent 与 Claw 状态

  • 5.2 日历系统集成

  • 5.3 课表软件兼容格式生成

  • 5.4 数据持久化

  • 5.5 日程卡片生成（可选）

• 6. 异常处理与容错机制

• 7. 流程总结

• 8. 附录

---

1. 概述

本文档描述了 TRAE Skill 的完整设计流程。该 Skill 旨在帮助用户自动处理课程表 / 日程相关的文档（图片、表格、PDF、Word 等），提取关键信息并生成结构化输出。

整个流程分为三个主要阶段：

---

2. 相关依赖库与环境初始化

在 Skill 运行前，Agent 需要配置以下 Skill 及相关库，并进行初始化。

2.1 依赖库清单

2.2 初始化流程

1. 检测运行环境（操作系统、已安装软件列表）
2. 逐一验证依赖库是否可用
3. 若有缺失，提示用户安装或选择替代方案
4. 加载所有可用库，记录环境状态到 history 文件

---

3. Step One: 预处理

预处理阶段负责识别并解析用户输入的各类文档格式。若有 Data、History、URL 等前置对话数据，则直接读取，跳过对应步骤。

3.1 输入识别与路由

用户输入 → 格式检测 → 路由到对应处理器
                        ├── 图片 → 3.2
                        ├── 表格 → 3.3
                        ├── PDF  → 3.4
                        ├── Word → 3.5
                        └── 其他 → 3.6

格式检测方法：

• 检查文件扩展名（.jpg/.png/.pdf/.docx/.xlsx/.csv 等）

• 若扩展名不明确，读取文件头（Magic Number）判断

• 若用户直接粘贴文本或 URL，按纯文本 / 网页处理

3.2 图片处理

方法一：Rapid OCR（推荐，适用于扫描件 / 截图）

# 伪代码
from rapid_ocr import RapidOCR
engine = RapidOCR()
result, _ = engine(img_path)
# result: [(bbox, text, confidence), ...]

详细步骤：

1. 加载 OCR 引擎，配置识别语言（中文 / 英文 / 中英混合）

2. 对图片进行预处理（去噪、二值化、倾斜校正）

3. 执行文字识别，获取文本块及坐标

4. 根据坐标信息还原表格结构（若有课表表格）

5. 输出结构化文本

方法二：多模态模型识别（适用于复杂图表 / 手写内容）

# 伪代码 - 调用通义千问等多模态模型
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="qwen-vl-max",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "file:///path/to/image"}},
            {"type": "text", "text": "请识别这张课程表图片中的所有文字和表格结构，以 Markdown 表格格式输出"}
        ]
    }]
)

适用场景：

• 图片中包含复杂排版（手写课表、拍照课表）

• 需要理解上下文语义（如 "第 1-8 周" 等缩写）

• OCR 识别效果不佳时的备选方案

图片处理决策树

图片输入
├── 是否为课表/日程表？
│   ├── 是 → 尝试 OCR → 检查识别质量
│   │   ├── 质量合格 → 结构化输出
│   │   └── 质量不合格 → 多模态模型识别
│   └── 否 → 多模态模型描述图片内容
└── 是否包含表格线？
    ├── 是 → OCR + 表格结构还原
    └── 否 → 纯文本 OCR

3.3 表格处理

方法一：Excel MCP（主机需安装 Microsoft Excel）

# 伪代码
import excel_mcp
workbook = excel_mcp.open("schedule.xlsx")
sheet = workbook.active
data = sheet.read_all()

详细步骤：

1. 通过 Excel MCP 打开工作簿

2. 自动检测表头行（通常为第一行或前几行）

3. 识别合并单元格，还原逻辑结构

4. 提取所有单元格数据，保留行列关系

5. 处理空值和格式化数据（如时间格式 “08:00-09:40”）

方法二：Claude Code Document 插件（未安装 Excel 时）

# 伪代码 - 使用 openpyxl 直接解析
from openpyxl import load_workbook
wb = load_workbook("schedule.xlsx")
ws = wb.active
for row in ws.iter_rows(values_only=True):
    print(row)

表格数据清洗规则：

• 合并单元格：取左上角值，其余标记为 "同上"

• 时间格式统一：将 “8:00”、“08:00”、“8：00” 统一为 “08:00”

• 空值处理：标记为 “待确认” 或根据上下文推断

• 重复项检测：合并相同课程的不同时间段

3.4 PDF 处理

PDF 处理需要根据内容类型选择不同策略：

3.4.1 纯图片 PDF

PDF（纯图片）→ 逐页转图片 → OCR 识别 → 结构化输出

详细步骤：

1. 使用 pdfplumber 或 PyMuPDF 将每页转为高分辨率图片（建议 200-300 DPI）

2. 对每页图片执行 OCR（参见 3.2）

3. 拼接多页识别结果

4. 检查跨页表格的连续性

3.4.2 图文混排 PDF

PDF（图文混排）→ 并行处理
                      ├── 文本层提取（pdfplumber/PyMuPDF）
                      └── 图片层 OCR
                      → 合并结果 → 结构化输出

详细步骤：

1. 先尝试提取 PDF 内嵌文本层

2. 同时提取 PDF 中的图片，对图片执行 OCR

3. 根据页面布局信息，将文本和图片内容按位置合并

4. 处理可能存在的表格（使用 pdfplumber.extract_tables()）

5. 对于无法自动处理的复杂布局，回退到多模态模型

3.4.3 纯文本 PDF

PDF（纯文本）→ pdfplumber 提取 → 结构化解析

详细步骤：

1. 使用 pdfplumber.open() 逐页提取文本

2. 识别文本中的表格模式（通过对齐、分隔符等）

3. 将线性文本重组为表格结构

4. 验证数据完整性

3.5 Word 处理

与 PDF 处理策略类似：

Word 文档 → 识别内容类型
              ├── 纯文本 → python-docx 提取段落
              ├── 包含表格 → python-docx 提取表格
              ├── 包含图片 → 提取图片 → OCR
              └── 图文混排 → 并行处理文本和图片

详细步骤：

1. 使用 python-docx 打开文档

2. 遍历文档段落（doc.paragraphs）和表格（doc.tables）

3. 提取内嵌图片（doc.inline_shapes），对图片执行 OCR

4. 注意处理 Word 特有的格式：文本框、页眉页脚、批注等

5. 合并所有提取结果

3.6 其他格式处理

3.7 数据清洗与结构化

无论输入格式如何，最终都需要将提取的原始数据清洗为统一的结构化格式：

{
  "schedule": {
    "meta": {
      "semester": "2026年春季学期",
      "grade": "2024级",
      "major": "计算机科学与技术",
      "class": "1班",
      "total_students": 45,
      "source_file": "课程表.pdf",
      "extracted_at": "2026-06-08T10:30:00"
    },
    "time_layout": {
      "name": "标准时间表",
      "periods": [
        { "id": 1, "type": "class", "start": "08:00", "end": "08:45", "label": "第1节" },
        { "id": 2, "type": "break", "start": "08:45", "end": "08:55", "label": "课间休息" },
        { "id": 3, "type": "class", "start": "08:55", "end": "09:40", "label": "第2节" },
        { "id": 4, "type": "break", "start": "09:40", "end": "10:00", "label": "大课间" },
        { "id": 5, "type": "class", "start": "10:00", "end": "10:45", "label": "第3节" },
        { "id": 6, "type": "class", "start": "10:45", "end": "11:30", "label": "第4节" }
      ]
    },
    "courses": [
      {
        "name": "高等数学",
        "teacher": "张教授",
        "ta": "李助教",
        "location": "教学楼A-301",
        "type": "required",          // required | elective
        "exam_type": "exam",         // exam | assessment | practice
        "weeks": "1-16周",
        "day": "周一",
        "period": "1-2节",
        "total_hours_weekly": 4,
        "credits": 4,
        "class_size": 45
      }
    ]
  }
}

数据清洗规则：

• 时间标准化：统一为 24 小时制 “HH:MM” 格式

• 周次解析：将 “1-8 周,10-16 周” 解析为具体周次列表

• 地点标准化：统一建筑名称缩写（如 “教 A301” → “教学楼 A-301”）

• 去重：合并相同课程在不同周次的出现

• 缺失值标记：无法识别的字段标记为 null 并提示用户确认

3.8 处理结果可视化与持久化

处理完成后：

1. 生成读友好的 Markdown 文档：汇报数据处理流程与状况

2. 保存文件并与处理原始文件挂钩：建立文件关联映射

3. 数据持久化：生成 Data-{原始文档名}.json 和 history-{日期}.md，方便跨对话处理

Markdown 报告模板：

# 数据处理报告

## 处理概况
- **源文件**: 课程表.pdf
- **文件类型**: PDF（图文混排）
- **处理方式**: 文本层提取 + 图片 OCR
- **处理时间**: 2026-06-08 10:30:00
- **识别置信度**: 92%

## 提取结果摘要
- 课程总数: 8 门
- 周课时: 28 节
- 日均课时: 4.7 节
- 识别问题: 2 处需确认（已标注）

## 待确认项
1. 周三第5节：识别为"计网实验"，请确认是否为"计算机网络实验"
2. 教学楼B-205：可能为"教学楼B-205"或"实验楼B-205"

---

4. Step Two: 核心功能（格式化输出）

4.1 用户需求导出格式调查

询问用户最终需求格式，默认导出格式为 Markdown。

4.2 默认模板设计

后续生成并导入（待完成）。字体文件可由第三方托管服务商导入。

Markdown 课表模板示例：

# 2026年春季学期课程表

> 年级：2024级 | 专业：计算机科学与技术 | 班级：1班

## 时间安排

| 节次 | 时间 | 时长 |
|------|------|------|
| 第1节 | 08:00 - 08:45 | 45min |
| 第2节 | 08:55 - 09:40 | 45min |
| 第3节 | 10:00 - 10:45 | 45min |
| 第4节 | 10:45 - 11:30 | 45min |
| 第5节 | 14:00 - 14:45 | 45min |
| 第6节 | 14:55 - 15:40 | 45min |
| 第7节 | 16:00 - 16:45 | 45min |
| 第8节 | 16:45 - 17:30 | 45min |

## 周一

| 时间 | 课程 | 教师 | 地点 | 类型 | 考核 | 周次 |
|------|------|------|------|------|------|------|
| 1-2节 | 高等数学 | 张教授 | 教A-301 | 必修 | 考试 | 1-16 |
| 3-4节 | 大学英语 | 王老师 | 教B-205 | 必修 | 考试 | 1-16 |
| 5-6节 | 数据结构 | 刘教授 | 教A-401 | 必修 | 考试 | 1-16 |
| 7-8节 | — | — | — | — | — | — |

## 统计信息

- **周总课时**: 28 节 / 1680 分钟
- **日平均课时**: 4.7 节
- **周时间占比**: 28 / (7×24) = 16.7%
- **必修课**: 6 门 | **选修课**: 2 门
- **考试课**: 5 门 | **考查课**: 3 门

4.3 课程 / 日程元素标签体系

输出文档应包含以下课程 / 日程元素标签：

4.4 输出格式详细规范

4.4.1 Excel 输出规范

参考 FullCalendar 排班排课表的数据组织方式：

• Sheet 1 - 课表总览：周一至周日 × 第 1-8 节的矩阵视图

• Sheet 2 - 课程详情：每门课程的完整信息列表

• Sheet 3 - 时间统计：日 / 周课时统计与占比

• Sheet 4 - 待确认项：识别不确定的数据项

样式要求：

• 表头：蓝色背景 + 白色加粗文字

• 必修课行：浅蓝底色

• 选修课行：浅绿底色

• 冻结首行，方便滚动查看

4.4.2 HTML 输出规范

参考 Scheduling-System 的点按式交互设计：

• 使用 CSS Grid 布局课表网格

• 响应式设计，适配手机 / 平板 / 桌面

• 课程卡片包含：课程名、教师、地点、时间

• 悬停显示详细信息（考核方式、周次等）

• 支持按课程类型筛选 / 高亮

4.4.3 ICS (iCalendar) 输出规范

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//TRAE Skill//CN
BEGIN:VEVENT
DTSTART:20260217T080000
DTEND:20260217T0940
RRULE:FREQ=WEEKLY;BYDAY=MO;COUNT=16
SUMMARY:高等数学
LOCATION:教学楼A-301
DESCRIPTION:张教授 | 必修 | 考试 | 1-16周
END:VEVENT
END:VCALENDAR

生成规则：

• 每门课程生成一个 VEVENT

• 使用 RRULE 设置重复规则（按周重复）

• 考虑节假日排除（可后续扩展）

• 支持提醒设置（默认提前 15 分钟）

---

5. Step Three: 自动化

5.1 检测主机 Agent 与 Claw 状态

检测流程:
1. 扫描可用自动化环境（Windows 计划任务 / macOS launchd / Linux cron）
2. 检测 Claw（自动化代理）是否已安装并运行
3. 若无可用环境 → 提醒用户完成安装
4. 若有 → 记录环境信息，进入自动化配置

5.2 日历系统集成

推荐集成 Notion 日历，同时支持 Windows 日历。

5.2.1 Notion 集成流程

预工作：

自动化安排内容：

• 课程安排日历与提醒：

  • 将每门课程创建为日历事件

  • 设置上课前 15 分钟提醒

  • 按学期自动生成重复事件

• 考试待办日历与提醒：

  • 创建考试日程条目

  • 设置考前 1 天 / 3 天 / 1 周提醒

  • 关联复习资料链接（若有）

Notion API 调用示例：

import requests

NOTION_TOKEN = "secret_xxx"
NOTION_DB_ID = "db_xxx"
headers = {
    "Authorization": f"Bearer {NOTION_TOKEN}",
    "Content-Type": "application/json",
    "Notion-Version": "2022-06-28"
}

# 创建课程事件
def create_course_event(course):
    data = {
        "parent": {"database_id": NOTION_DB_ID},
        "properties": {
            "名称": {"title": [{"text": {"content": course["name"]}}]},
            "日期": {"date": {"start": course["start_date"], "end": course["end_date"]}},
            "时间": {"rich_text": [{"text": {"content": course["time_range"]}}]},
            "地点": {"rich_text": [{"text": {"content": course["location"]}}]},
            "教师": {"rich_text": [{"text": {"content": course["teacher"]}}]},
            "类型": {"select": {"name": course["type"]}},
        }
    }
    requests.post("https://api.notion.com/v1/pages", headers=headers, json=data)

5.2.2 Windows 日历集成

Windows 日历集成方案:
1. 生成 .ics 文件
2. 双击导入到 Windows 日历
3. 或通过 PowerShell 脚本调用 Windows API 自动导入

5.3 课表软件兼容格式生成

5.3.1 ClassIsland 兼容格式

参考 ClassIsland 官方文档，ClassIsland 是一款适用于班级多媒体屏幕的课表信息显示工具，基于 .NET 8 + Avalonia UI 框架开发。

ClassIsland 核心概念映射：

ClassIsland 时间点类型：

生成 ClassIsland 兼容 JSON 格式：

{
  "profile": {
    "timeLayouts": [
      {
        "name": "标准时间表",
        "timePoints": [
          { "type": "class", "start": "08:00", "end": "08:45", "label": "第1节" },
          { "type": "break", "start": "08:45", "end": "08:55", "label": "课间" },
          { "type": "class", "start": "08:55", "end": "09:40", "label": "第2节" }
        ]
      }
    ],
    "subjects": [
      { "name": "高等数学", "color": "#FF6B6B", "icon": "📐" },
      { "name": "大学英语", "color": "#4ECDC4", "icon": "📖" }
    ],
    "classPlans": [
      {
        "name": "周一课表",
        "timeLayoutName": "标准时间表",
        "triggerRules": { "dayOfWeek": 1 },
        "classes": [
          { "periodIndex": 0, "subjectName": "高等数学" },
          { "periodIndex": 2, "subjectName": "大学英语" }
        ]
      }
    ]
  }
}

5.3.2 ClassIsland IPC 跨进程通信（高级集成）

若需要与 ClassIsland 进行实时联动，可通过其 IPC（跨进程通信）接口实现：

// C# 示例 - 通过 IPC 获取 ClassIsland 当前课表信息
var client = new IpcClient();
await client.Connect();

// 获取当前课表服务
var scheduleService = client.Provider
    .CreateIpcProxy<IScheduleService>(client.PeerProxy);

// 获取当前正在上的课程
var currentClass = scheduleService.GetCurrentClass();

// 监听上课事件
client.JsonIpcProvider.AddNotifyHandler(
    IpcRoutedNotifyIds.OnClassNotifyId,
    () => Console.WriteLine("上课了！")
);

IPC 集成步骤：

1. 安装 ClassIsland.Shared.Ipc NuGet 包（需 .NET 8+）

2. 创建 IPC 客户端并连接到 ClassIsland

3. 通过服务代理获取课表数据或调用功能

4. 订阅事件（上课 / 下课 / 换课等）实现实时响应

5.3.3 FullCalendar 前端集成（参考）

参考 FullCalendar 排班排课表方案，可生成前端可视化页面：

// FullCalendar 配置示例
import FullCalendar from '@fullcalendar/vue';
import dayGridPlugin from '@fullcalendar/daygrid';
import interactionPlugin from '@fullcalendar/interaction';
import timeGridPlugin from '@fullcalendar/timegrid';

const calendarOptions = {
  plugins: [dayGridPlugin, interactionPlugin, timeGridPlugin],
  initialView: 'timeGridWeek',
  locale: 'zh-cn',
  headerToolbar: {
    left: 'prev,next today',
    center: 'title',
    right: 'dayGridMonth,timeGridWeek,timeGridDay'
  },
  events: [
    {
      title: '高等数学',
      daysOfWeek: [1],  // 周一
      startTime: '08:00',
      endTime: '09:40',
      color: '#FF6B6B',
      extendedProps: {
        teacher: '张教授',
        location: '教A-301',
        type: '必修'
      }
    }
  ],
  // 支持拖拽调整课程时间
  editable: true,
  droppable: true,
  eventReceive: (info) => {
    console.log('课程已调整:', info.event.title);
  }
};

FullCalendar 功能特性（参考实现）：

• 日程状态图例：未开始 / 进行中 / 已完成 / 已延时

• 可拖动列表：从侧边栏拖拽课程到日历

• 新建日程弹窗：表单验证（课程名、时间、地点等）

• 搜索过滤：按课程名 / 教师 / 地点搜索

5.4 数据持久化

5.4.1 数据库方案（推荐）

检查环境:
├── 有数据库环境（MySQL / SQLite / PostgreSQL）
│   ├── 创建 schedule_management 数据库
│   ├── 创建表结构（courses, schedules, time_layouts, etc.）
│   ├── 导入解析后的数据
│   └── 生成 history-{日期}.md 记录操作历史
└── 无数据库环境
    ├── 提示用户安装
    ├── 用户选择不安装 → 生成本地文件
    └── 生成本地文件方案 ↓

5.4.2 本地文件方案（无数据库时）

跨对话必要提示：

⚠️ 当前未检测到数据库环境。已将数据保存为本地文件。在后续对话中，请提供 Data-xxx.json 文件以便继续处理。

5.5 日程卡片生成（可选）

待补充完善。计划支持生成精美的日程卡片图片，包含：

• 当日课程概览

• 下节课程提醒

• 一周课表缩略图

• 可分享到社交媒体

---

6. 异常处理与容错机制

---

7. 流程总结

┌─────────────────────────────────────────────────────────────┐
│                    TRAE Skill 工作流程                        │
├─────────────┬───────────────────────────────────────────────┤
│  Step One   │  预处理                                        │
│             │  ├── 识别输入格式（图片/表格/PDF/Word/其他）    │
│             │  ├── 执行对应解析策略                           │
│             │  ├── 数据清洗与结构化                           │
│             │  └── 生成处理报告 + 数据持久化                  │
├─────────────┼───────────────────────────────────────────────┤
│  Step Two   │  格式化输出                                    │
│             │  ├── 调查用户需求格式（默认 Markdown）           │
│             │  ├── 按模板填充课程/日程元素标签                 │
│             │  └── 输出结构化文档（MD/XLS/HTML/PDF/DOCX/ICS）  │
├─────────────┼───────────────────────────────────────────────┤
│  Step Three │  自动化                                        │
│             │  ├── 检测自动化环境                             │
│             │  ├── 日历集成（Notion / Windows）                │
│             │  ├── 课表软件兼容（ClassIsland / FullCalendar）  │
│             │  └── 数据持久化（数据库 / 本地文件）             │
└─────────────┴───────────────────────────────────────────────┘

---

8. 附录

8.1 待完成项

• [ ] 默认模板的生成与导入

• [ ] 日程卡片生成功能

• [ ] 字体文件第三方托管服务商导入方案

• [ ] 节假日自动排除功能

• [ ] 多学期课表管理

• [ ] 课程评价 / 成绩录入扩展

8.2 术语表

8.3 参考资源