diagram-reports-generator

图表报告生成器

概述

此技能通过分析章节 Markdown 文件，自动生成几何课程中所有图表和 MicroSims 的综合报告。它会创建两个报告文件：一个便于快速查阅的表格视图，以及一个按章节组织的详细视图。

何时使用此技能

在以下情况下使用此技能：

• 处理几何课程智能教材项目
• 需要审核各章节中的所有图表和 MicroSims
• 跟踪视觉元素的实现状态
• 分析复杂度和布鲁姆分类法分布
• 添加新的图表或 MicroSims 后更新文档
• 为教师或内容创作者生成报告

工作流

步骤 1：安装图表报告生成器脚本

如果项目中尚未包含图表报告生成器脚本，请从此技能随附的资源中安装：

1. 检查项目中是否存在 src/diagram-reports/diagram-report.py
2. 如果不存在：
   • 创建目录：mkdir -p src/diagram-reports
   • 将此技能中的 scripts/diagram-report.py 复制到 src/diagram-reports/diagram-report.py
3. 如果已存在，请确认它是最新版本（如有差异，可选择向用户展示差异）

安装示例：

# Create directory if needed
mkdir -p src/diagram-reports

# Copy script from skill (use Read tool to get script content, then Write tool to create file)
# The script is located in this skill's scripts/diagram-report.py

步骤 2：验证项目结构

运行报告生成器之前，请验证项目结构：

1. 确认当前工作目录是几何课程项目的根目录（或任何智能教材项目的根目录）
2. 确认 docs/chapters/ 包含章节目录（格式：01-chapter-name、02-chapter-name 等）
3. 确保用于输出的 docs/learning-graph/ 目录存在

步骤 3：运行报告生成器

执行 Python 脚本以生成报告：

python src/diagram-reports/diagram-report.py

脚本将会：

• 扫描 docs/chapters/ 中的所有章节目录
• 解析每个章节的 index.md 文件
• 从带有“#### Diagram:”标题的 <details> 块中提取图表和 MicroSim 规格
• 分析每个元素的以下信息：
  • 类型（图表或 MicroSim）
  • 状态（如有指定，则为实现状态）
  • 布鲁姆分类法级别
  • UI 元素数量
  • 估计难度（简单、中等、困难、非常困难）
  • 学习目标

步骤 4：验证生成的报告

运行脚本后，确认已在 docs/learning-graph/ 中创建以下两个文件：

1. diagram-table.md - 可排序的表格视图，包含以下列：

   • 章节编号
   • 元素标题（带有指向章节部分的链接）
   • 状态
   • 类型（图表/MicroSim）
   • 布鲁姆分类法级别
   • UI 元素数量
   • 难度评级

2. diagram-details.md - 按章节组织的详细视图，包含：

   • 章节级摘要
   • 完整的元素说明
   • 学习目标
   • 链接到源章节部分的标题

步骤 5：检查导航配置

生成的报告应已添加到 MkDocs 导航中。请确认 mkdocs.yml 文件的“Learning Graph”部分包含以下条目：

- Learning Graph:
    - Diagrams Table: learning-graph/diagram-table.md
    - Diagrams Details: learning-graph/diagram-details.md

如果缺少这些条目，请将其添加到导航结构中。

步骤 6：预览报告

查看生成的报告：

1. 运行 mkdocs serve 启动本地开发服务器
2. 导航到“Learning Graph”部分
3. 点击“Diagrams Table”或“Diagrams Details”
4. 确认所有图表和 MicroSims 均已正确列出，且信息准确无误

了解报告输出

难度估算

该脚本根据以下因素估算难度：

• 元素类型：MicroSim 的基础难度较高
• UI 复杂度：滑块、按钮、下拉菜单及其他控件的数量
• 功能：动画、旋转、3D／等距视图、实时计算
• 画布尺寸：画布越大，复杂度越高

难度级别：

• 简单：静态图表或简单可视化
• 中等：包含 1-3 个 UI 元素的基本交互
• 困难：包含 4-6 个 UI 元素的中等交互，或复杂功能
• 非常困难：包含许多 UI 元素的高交互性内容，或高级功能

布鲁姆分类法检测

该脚本会自动检测规格说明中提到的布鲁姆分类法层级：

• 记忆
• 理解
• 应用
• 分析
• 评价
• 创造

故障排除

未找到元素

如果报告显示元素数量为零：

• 确认章节 Markdown 文件包含 #### Diagram: 标题，后面紧跟 <details> 块
• 检查 <details> 块是否包含规格说明内容
• 使用详细模式标志运行：python src/diagram-reports/diagram-report.py --verbose

缺少信息

如果元素缺少类型、状态或其他字段：

• 检查章节文件中的 <details> 块格式
• 确保规格说明包含 **Type:**、**Status:** 和 **Learning Objective:** 字段
• 如果未明确指定类型，该脚本会根据内容推断类型

报告中的链接失效

如果章节链接无法使用：

• 确认章节目录的命名遵循以下模式：##-descriptive-name
• 检查 MkDocs 锚点生成方式是否与脚本的锚点创建逻辑一致
• 在已部署的网站中打开链接进行测试

高级用法

自定义输出位置

指定其他输出目录：

python src/diagram-reports/diagram-report.py --output-dir /path/to/output

生成 CSV 格式

用于电子表格分析：

python src/diagram-reports/diagram-report.py --format csv

生成 HTML 格式

用于独立 HTML 报告：

python src/diagram-reports/diagram-report.py --format html

使用详细输出进行调试

启用详细日志记录：

python src/diagram-reports/diagram-report.py --verbose

与智能教科书工作流集成

此技能集成于更广泛的智能教科书创作工作流中：

1. 内容创建后：生成或更新章节内容后运行此技能
2. 评审会议前：生成报告，以找出缺漏或不一致之处
3. 规划期间：利用难度分布平衡实现工作量
4. 用于文档编写：将报告纳入教师指南或项目文档

内置资源

scripts/diagram-report.py

此技能包含用于生成图表和 MicroSim 报告的完整 Python 脚本。首次使用此技能时，该脚本将安装到用户项目中的 src/diagram-reports/diagram-report.py。

该脚本：

• 分析 docs/chapters/ 中的所有章节 Markdown 文件
• 从 <details> 块中提取图表和 MicroSim 规格说明
• 根据 UI 复杂度和功能估算难度
• 从规格说明文本中检测布鲁姆分类法层级
• 生成表格格式和详细报告格式
• 支持多种输出格式（Markdown、CSV、HTML）