# HTML可视化报告

AIS 的 HTML 可视化报告功能将您的学习数据转化为直观、美观的交互式图表，帮助您更好地了解自己的技能进步轨迹。

## 功能概述

HTML 报告提供了比传统文本报告更丰富的数据可视化体验：

- 📈 **6种专业图表类型** - 全方位展示学习数据
- 🎨 **现代化设计** - 响应式布局，适配所有设备
- 🖱️ **交互式体验** - 悬停查看详情，缩放探索数据
- 💡 **AI智能洞察** - 个性化分析和改进建议
- 🔒 **数据安全** - 完全本地生成，无云端上传

## 快速开始

### 基础使用

```bash
# 生成 HTML 报告
ais report --html

# 自定义输出文件名
ais report --html -o my_report.html

# 生成后自动打开浏览器
ais report --html --open

# 组合使用
ais report --html -o weekly_progress.html --open
```

### 安装可视化依赖

HTML 报告功能需要额外的可视化库支持：

```bash
# 使用 pipx 安装（推荐）
pipx install "ais-terminal[html]"

# 或者在现有安装基础上添加
pip install plotly numpy

# 验证安装
ais help-all
```

## 图表类型详解

### 1. 📈 错误趋势图

**功能**：展示最近30天的错误变化趋势，帮助识别学习进步轨迹。

**数据展示**：
- X轴：日期（最近30天）
- Y轴：每日错误次数
- 趋势线：平滑曲线显示总体趋势
- 填充区域：视觉增强效果

**如何解读**：
- 📉 **下降趋势**：说明您的技能在稳步提升
- 📈 **上升趋势**：可能在学习新技能或遇到新挑战
- 🔄 **波动模式**：识别学习周期和规律

### 2. 🎯 技能评估雷达图

**功能**：多维度展示您在不同技能领域的水平。

**技能领域**：
- 🔧 基础命令（ls, cd, pwd, mkdir等）
- 📁 文件操作（find, grep, sed, awk等）
- ⚙️ 系统管理（ps, top, chmod, sudo等）
- 🌐 网络工具（curl, wget, ssh, ping等）
- 📂 Git版本控制
- 🐳 Docker容器

**评分系统**：
- 🔴 新手（0-2分）：频繁出错，需要基础学习
- 🟡 入门（2-4分）：偶尔出错，需要练习巩固
- 🟢 熟练（4-6分）：基本掌握，可以独立操作
- 🔵 精通（6-8分）：很少出错，能够高效使用
- 🟣 专家（8-10分）：几乎不出错，可以指导他人

### 3. ⏰ 时间分布热力图

**功能**：显示错误发生的时间分布模式，帮助发现最佳学习时间。

**数据维度**：
- X轴：24小时时间段（00:00-23:00）
- Y轴：一周七天（周一到周日）
- 颜色深度：错误频次（越深表示错误越多）

**实用洞察**：
- 🌅 **早晨时段**：通常错误较少，思维清晰
- 🌃 **深夜时段**：可能错误增多，注意力下降
- 📅 **工作日vs周末**：发现学习习惯差异
- 🎯 **高频时段**：识别需要特别注意的时间

### 4. 📊 命令频次图

**功能**：显示最常出错的命令排序，帮助确定重点学习目标。

**数据展示**：
- 柱状图形式，按错误次数降序排列
- 显示前8个最常出错的命令
- 悬停显示具体错误次数

**学习建议**：
- 🔴 **高频错误命令**：优先学习和练习
- 🟡 **中频错误命令**：定期复习和巩固
- 🟢 **低频错误命令**：保持现有水平

### 5. 🔍 错误类型分布图

**功能**：饼图展示不同错误类型的占比，帮助针对性改进。

**错误类型分类**：
- 🚫 命令不存在：拼写错误、未安装程序
- 🔒 权限不足：需要sudo、文件权限问题
- 📁 文件/目录不存在：路径错误、文件缺失
- ⚠️ 语法错误：参数错误、选项错误
- 🔧 Git操作错误：版本控制相关问题
- 🐳 Docker操作错误：容器化相关问题
- 🌐 网络操作错误：连接、下载问题
- 📦 包管理错误：安装、更新相关

**改进策略**：
- 针对占比最大的错误类型制定学习计划
- 了解每种错误类型的常见解决方法
- 建立错误预防意识和习惯

### 6. 📈 学习进度趋势图

**功能**：双轴图表展示错误减少和技能提升的平衡关系。

**数据轴**：
- 主轴（红色）：每周错误次数
- 副轴（绿色）：每周探索的命令数量
- X轴：最近8周时间

**进步指标**：
- 📉 **错误减少** + 📈 **命令增加**：理想的学习状态
- 📈 **错误增加** + 📈 **命令增加**：学习新技能的正常阶段
- 📉 **错误减少** + 📉 **命令减少**：技能巩固阶段
- 📈 **错误增加** + 📉 **命令减少**：需要回顾基础

## 使用场景

### 💼 个人技能评估

```bash
# 生成个人技能报告
ais report --html -o "个人技能评估_$(date +%Y%m%d).html" --open
```

**适用于**：
- 求职前的技能自评
- 学习计划制定
- 技能短板识别

### 📚 学习进度追踪

```bash
# 每周生成进度报告
ais report --html -o "第$(date +%U)周学习报告.html"
```

**适用于**：
- 培训课程进度跟踪
- 自学效果评估
- 导师指导参考

### 🎯 项目技能要求分析

```bash
# 针对特定项目生成报告
ais report --html -o "Docker项目技能分析.html"
```

**适用于**：
- 项目开始前的技能准备
- 团队技能分布分析
- 培训需求评估

### 📊 团队技能对比

```bash
# 团队成员分别生成报告进行对比
ais report --html -o "团队成员_张三_技能报告.html"
ais report --html -o "团队成员_李四_技能报告.html"
```

**适用于**：
- 团队技能分布分析
- 培训资源分配
- 任务分工参考

## 高级配置

### 数据收集设置

```bash
# 设置分析数据的时间范围（默认30天）
# 注意：这需要修改源码中的days_back参数

# 调整上下文收集级别影响AI洞察质量
ais config --set context_level=detailed  # 获取更丰富的分析数据
```

### 自定义主题

HTML报告使用现代化的CSS设计，您可以通过修改生成的HTML文件来自定义样式：

1. 生成基础报告：`ais report --html -o custom_report.html`
2. 使用文本编辑器打开HTML文件
3. 修改`<style>`标签内的CSS样式
4. 保存并在浏览器中查看效果

### 集成到工作流

#### 自动化报告生成

```bash
# 添加到crontab，每周自动生成报告
echo "0 9 * * 1 cd /path/to/project && ais report --html -o weekly_$(date +\%Y\%U).html" | crontab -
```

#### CI/CD集成

```yaml
# GitHub Actions 示例
- name: Generate AIS Learning Report
  run: |
    ais report --html -o learning_report.html
    # 上传到artifacts或发送邮件
```

## 故障排除

### 常见问题

#### 1. 缺少依赖错误

**错误信息**：`需要安装plotly库: pip install plotly`

**解决方案**：
```bash
# 安装可视化依赖
pip install plotly numpy

# 或重新安装完整版本
pipx install "ais-terminal[html]"
```

#### 2. 图表显示异常

**可能原因**：
- 数据不足（错误记录太少）
- 浏览器兼容性问题

**解决方案**：
```bash
# 检查数据量
ais history --failed-only | wc -l

# 尝试使用不同浏览器打开
# Chrome, Firefox, Safari, Edge 都支持
```

#### 3. 浏览器无法自动打开

**可能原因**：
- 无图形界面环境（如SSH连接）
- 浏览器未正确安装

**解决方案**：
```bash
# 手动打开文件
ais report --html -o report.html
# 然后手动复制文件到本地机器打开

# 或在服务器上启动简单HTTP服务
python -m http.server 8000
# 在浏览器中访问 http://server-ip:8000/report.html
```

### 性能优化

#### 大数据量优化

当错误记录很多时，生成报告可能较慢：

```bash
# 查看数据量
ais history | wc -l

# 如果超过1000条记录，考虑清理历史数据
# 注意：这会删除数据，请谨慎操作
# 历史数据由数据库自动管理
```

#### 内存使用优化

HTML报告包含图表数据，文件可能较大：

- 📊 典型大小：50-200KB
- 📈 大数据量：500KB-2MB
- 💾 存储影响：可忽略

## 最佳实践

### 📅 定期生成报告

建立定期报告习惯：

```bash
# 每周一上午生成上周报告
ais report --html -o "Week_$(date +%U)_Progress.html" --open

# 每月月底生成月度总结
ais report --html -o "Month_$(date +%m)_Summary.html" --open
```

### 📊 数据驱动学习

基于报告数据制定学习计划：

1. **识别薄弱环节**：查看技能雷达图和错误类型分布
2. **制定改进计划**：针对高频错误命令制定练习计划
3. **跟踪进步情况**：定期对比趋势图查看改进效果
4. **调整学习策略**：基于时间分布优化学习时间安排

### 🎯 目标设定

设定可量化的学习目标：

- 🎯 **错误减少目标**：下周错误数量减少20%
- 📈 **技能提升目标**：Git技能从入门提升到熟练
- ⏰ **时间优化目标**：发现并利用高效学习时间段
- 🔄 **习惯养成目标**：建立每日命令行练习习惯

### 📋 分享与交流

有效利用报告进行交流：

- 👥 **团队分享**：在技术分享会中展示学习进步
- 🎓 **导师指导**：向导师展示学习效果和困难点
- 💼 **面试展示**：用数据证明自己的学习能力和进步
- 📝 **学习笔记**：结合报告撰写技术博客和学习总结

## 扩展功能

### 🔄 与其他工具集成

#### Obsidian笔记集成

```bash
# 生成报告到Obsidian vault
ais report --html -o "/path/to/obsidian/vault/Learning Reports/$(date +%Y%m%d)_AIS_Report.html"
```

#### Notion集成

可以将报告链接或截图添加到Notion学习数据库中，跟踪长期进步。

#### Git仓库集成

```bash
# 将学习报告添加到Git仓库
mkdir -p learning-reports
ais report --html -o "learning-reports/$(date +%Y%m%d)_progress.html"
git add learning-reports/
git commit -m "Add learning progress report for $(date +%Y-%m-%d)"
```

### 📊 数据导出

虽然目前不支持直接导出数据，但您可以通过以下方式获取原始数据：

```bash
# 查看数据库位置
ais config | grep database

# 使用SQLite工具查看数据
# sqlite3 ~/.local/share/ais/ais.db ".tables"
# sqlite3 ~/.local/share/ais/ais.db "SELECT * FROM command_logs;"
```

---

## 反馈与改进

我们持续改进HTML报告功能，欢迎您的反馈：

- 🐛 **问题报告**：[GitHub Issues](https://github.com/kangvcar/ais/issues)
- 💡 **功能建议**：[GitHub Discussions](https://github.com/kangvcar/ais/discussions)
- 📧 **直接联系**：ais@example.com

您的使用体验和建议将帮助我们打造更好的可视化学习体验！