本项目旨在开发一款利用 AI 技术分析磁盘扫描数据（目前主要支持 WizTree 导出的 CSV 文件），帮助用户理解文件组成、识别大文件/冗余文件、追踪文件增长趋势，并提供清理建议的智能工具。

---该工具可以理解为Wizree的拓展，不包含磁盘扫描功能，而是专注于对已有扫描数据的智能分析。

• 智能分析磁盘数据，轻松释放存储空间，洞察文件变化趋势。
• 提供超越传统工具的简单统计，提供AI层次的洞察和建议。
• 清晰展示文件/文件夹随时间的变化，帮助用户理解存储增长模式。
• 支持导入 WizTree 等流行磁盘扫描工具的 CSV 数据，降低用户使用门槛。
• 基于 AI 分析结果，提供针对性的文件清理建议，并能结合用户具体问题对特定文件夹内容进行解答。
• 优化了与 AI 交互的数据量，通过发送摘要信息来应对 API 的字数限制。

1. 准备环境:

   • 确保您的计算机上已安装 Python (建议版本 3.10+，但不推荐 11 及以上，有依赖对高级版本未支持，开发版本为3.10.11)。您可以从 Python官网 下载并安装。
   • 使用您的代码编辑器（如 VS Code），打开项目文件夹。

2. 获取代码:

   • 如果您通过 Git 克隆了仓库，请跳至下一步。
   • 如果直接下载了文件，请确保所有文件和文件夹结构完整。

3. 创建虚拟环境 (推荐):

   • 打开终端或命令提示符，导航到项目根目录 (Csv_Chat)。
   • 运行以下命令创建虚拟环境 (例如，命名为 .venv):

     python -m venv .venv

   • 激活虚拟环境:
     • Windows (CMD/PowerShell):

       .venv\Scripts\activate

     • macOS/Linux (bash/zsh):

       source .venv/bin/activate

4. 安装依赖:

   • 在激活的虚拟环境中，运行以下命令安装所需的库:

     pip install -r requirements.txt

5. 运行程序:

   • 在项目根目录下，运行主程序:

     streamlit run src/app.py

   • 程序启动后，会在浏览器中打开一个网页界面。
   • 详细交互操作查看使用方法。

6. 退出虚拟环境 (可选):

   • 当您完成操作后，可以在终端中输入以下命令退出虚拟环境:

     deactivate

7. 查看已安装的库 (可选):

   • 在激活的虚拟环境中，运行以下命令查看所有已安装的 Python 库:

     pip list

   • 或者使用以下命令将已安装的库导出到 requirements.txt 文件 (如果依赖有更新):

     pip freeze > requirements.txt

1. 准备 WizTree CSV 文件和 AI API 密钥:

   • 使用 WizTree 工具扫描您想要提问的磁盘。(下载可能缓慢，可以尝试科学上网)
   • 扫描完成后，通过 WizTree 的菜单导出数据为 CSV 文件 (通常在 "文件" -> "导出CSV文件...")。
   • 请确保导出的 CSV 文件至少包含 文件名称 (或英文 "File Name") 和 大小 (或英文 "Size") 这两列信息。如果导出的文件有明确的 路径 (或英文 "Path") 列，程序也会优先使用它。(从WizTree导出的CSV文件通常包含这些列，但如果您的 CSV 文件格式有所不同，程序会尝试智能识别。)
   • 需要到硅基流动等平台申请兼容 OpenAI API 规范的 API Key，填入 src/config.py 中，并选择默认模型。如需为对话指定 AI 模型、调整文件传递参数等，可在 src/config.py 中修改参数。

2. 运行程序:

   • 按照上面的 "如何开始" 步骤安装并运行程序 (streamlit run src/app.py)。
   • 程序启动后，会在浏览器中显示一个网页界面。

3. 上传 CSV 文件:

   • 在作者的试用网页或fork后自行部署的网页界面上，点击 "Browse files" 按钮，或者直接将您的 CSV 文件拖拽到指定区域。

4. 查看分析结果:

   • 文件上传成功后，程序会自动进行分析，并在页面上展示各种统计数据、图表和 AI 的建议。
   • 您可以滚动页面查看所有分析内容。

5. 与 AI 互动:

   • 在 "AI 分析特定文件夹内容" 部分，您可以输入 CSV 文件中存在的某个文件夹路径，并提出您关心的问题，然后点击按钮让 AI 进行分析和回答。

6. 调整文件上传大小限制 (适用于大型CSV文件):

   • Streamlit 默认的文件上传大小限制为 200MB，如果您需要分析更大的 CSV 文件，可以通过以下方式调整限制:

     • 方法一: 使用命令行参数启动 Streamlit

       streamlit run src/app.py --server.maxUploadSize=1028

       这会将上传限制调整为 1028MB (约1GB)

     • 方法二: 创建配置文件 在项目根目录创建 .streamlit/config.toml 文件，添加以下内容:

       [server]
       maxUploadSize = 1028

     • 方法三: 在代码中设置环境变量 (不推荐，但可作为临时解决方案)

       import os
       os.environ['STREAMLIT_SERVER_MAX_UPLOAD_SIZE'] = '1028'

   • 注意: 即使提高了上传限制，处理超大文件仍可能导致内存问题，因为整个文件会被加载到内存中，这取决于运行设备。且当文件大于150MB时网页便开始有明显加载痕迹，这取决于py运行速度和代码质量(悲)
   • 受影响的前端:

• src/app.py - Streamlit 前端界面与交互逻辑
• src/deal_csv.py - CSV 数据处理与核心分析逻辑
• src/deal_tree.py - 文件树结构生成与JSON转换
• src/ai_analyzer.py - AI 分析中间件，处理数据转换与API调用
• src/aiapi.py - AI API 接口封装与错误处理
• src/config.py.example - 配置文件模板

• 本地开发：按照上述"如何开始"步骤进行
• 生产环境部署：参考 项目维护说明书.md
• 服务管理：支持 systemd 服务管理，详见维护文档

程序能够：

• 智能解析 CSV：自动识别并处理 WizTree 导出的 CSV 文件，提取关键信息如文件名称、大小等。

  • 特别地，对于路径信息，程序会优先寻找名为 "Path" 的列。如果找不到，它会尝试使用名为 "文件名称" 或 "File Name" 的列作为路径来源。所以"CSV文件中未找到 'Path' 列，将使用 'File Name' 列作为路径。"的提示是正常的。

• 基本统计展示：清晰展示扫描项目总数、总占用空间等基础数据。

• 大文件/文件夹Top榜：快速定位占用空间最多的文件和文件夹，展示表格支持索引和排序。

• 按类型/扩展名分类：统计不同文件类型（如视频、图片、文档）和扩展名（如 .mp4, .jpg, .docx）的空间占用情况，并以图表形式直观展示。

• 特定文件夹 AI 问答：允许用户针对 CSV 中存在的特定文件夹路径提出问题，AI 会结合该文件夹下的文件信息进行解答。

  为了优化与 AI 的交互并管理发送的数据量，该功能采用了智能的双模式处理机制：

  🚀 完整模式 (Full Mode)

  • 触发条件：默认首选模式，当文件夹数据量在可接受范围内时启用
  • 处理方式：
    • 构建所选文件夹内详细的文件和子文件夹结构（完整文件树），由 src/deal_tree.py 实现
    • 包含每个文件的完整路径、大小、类型等详细信息
    • 直接将完整的文件夹结构数据发送给 AI 进行分析
  • 优势：AI 能够获得最全面的信息，提供最精准、最详细的分析和建议
  • 限制：受 src/config.py 中的 max_folder_files（默认1000个文件）和 max_folder_json_size_mb（默认1MB）限制

  📊 摘要模式 (Summary Mode)

  • 触发条件：当完整模式超出数据量限制时自动启用，或在完整模式失败后智能切换
  • 处理方式：
    • 首先生成简化的文件夹树结构（不包含具体文件详情）
    • 调用 src/deal_csv.py 中的分析函数生成关键摘要信息：
      • 📈 文件夹总大小统计
      • 🔝 前500个最大文件列表
      • 📁 文件类型分布统计
      • 📄 前100种扩展名统计
      • 🌳 文件路径前缀树结构
    • 向 AI 提交经过智能压缩的摘要信息而非完整数据
  • 优势：能够处理大型文件夹，同时保持分析的有效性
  • 适用场景：大型项目文件夹、系统目录、包含大量文件的下载文件夹等

  🔄 智能切换机制

  • 程序会首先尝试完整模式，如遇到 FolderTooLargeError 异常会自动切换到摘要模式
  • 在 src/app.py 中通过线程管理和实时状态显示，让用户了解当前处理模式和进度
  • 无论使用哪种模式，都会在界面上明确提示，让用户了解分析的数据基础

  💡 智能模式选择的优势：

  • 无缝体验：用户无需手动选择模式，系统自动选择最优策略
  • 最大化信息利用：在 API 限制范围内提供尽可能详细的分析
  • 处理能力强：即使面对TB级磁盘扫描数据也能有效处理
  • 成本优化：通过智能数据压缩减少 API 调用成本

以下两个函数功能 (analyze_disk_usage_summary, suggest_files_for_cleanup) 虽然在后端代码中仍保留，但已从前端 src/app.py 的主要交互流程中移除。当前版本主要侧重于下面的特定文件夹分析功能。

1. 磁盘使用摘要分析 (analyze_disk_usage_summary)
2. 文件清理建议 (suggest_files_for_cleanup)

3. AI 分析特定文件夹内容 (analyze_folder_contents): 这是本版本核心的 AI 交互功能！当您对某个特定文件夹里的文件感到困惑时（例如，不知道这些文件是干什么的，是否重要，能不能删除），此功能可以提供帮助。

   • 输入:
     • folder_path: 您想分析的文件夹的路径。
     • file_details_df: 一个包含该文件夹内详细文件信息的 Pandas DataFrame (应有 'File Name', 'Size', 'Path', 'Type' 等列)。
     • user_query (可选): 您关于这个文件夹的具体问题。例如："这个文件夹里的 .tmp 文件都是什么？" 或者 "哪些文件可以安全删除？"
   • AI 处理:
     • 程序会首先生成该文件夹内容的摘要信息，包括主要文件类型统计、占用空间较大的文件、文件夹内文件列表等。
     • 然后，这个摘要连同您的具体问题（如果有的话）会一起发送给 AI。
     • AI 会基于这些信息，尝试回答您的问题，分析文件夹内容，并给出整理建议。
   • 输出: AI 针对您的文件夹和问题生成的分析和解答。

   💡 如何有效提问以获得更好的文件夹分析结果？

   • 具体化您的问题：与其问 "这个文件夹能清理吗？"，不如问 "这个文件夹里的 *.log 文件是做什么用的？我可以删除旧的日志文件吗？"
   • 提供上下文：如果可能，在问题中提及文件夹的用途，例如："这是我的 '下载' 文件夹，里面的这些大文件是什么？"
   • 理解 AI 的局限性：AI 的回答基于提供给它的文件摘要信息。它不能直接 "看到" 您的文件内容。对于非常关键或不确定的文件，AI 通常会建议您谨慎操作或先备份。

   通过这种方式，即使我们不能把所有文件细节都发给 AI，AI 也能通过摘要和您的问题，给您提供有价值的帮助！

为了保护您的 API 密钥不被意外上传到代码仓库，本项目采用了 src/config.py.example 的方式管理配置。

1. 复制示例文件：在 src 目录下，找到 config.py.example 文件，复制一份并将其重命名为 config.py。

2. 填写您的密钥：打开新创建的 src/config.py 文件，将 YOUR_API_KEY_HERE 替换为您真实的 API 密钥。根据需要，您也可以修改 api_endpoint 和 model_name。

   # src/config.py (修改后的示例)
   class AIConfig:
       def __init__(self):
           # AI服务配置
           self.api_key = "sk-YourActualAPIKey"  # 替换为你的AI服务的API密钥
           self.api_endpoint = "https://api.siliconflow.cn/v1/chat/completions"
           self.model_name = "Qwen/Qwen3-8B"
           # ... 其他配置 ...

   ✅ config.py 文件已被添加到 .gitignore 中，因此不会被 Git 跟踪和上传。

• CSV 文件格式:
  • 程序主要针对 WizTree 导出的标准 CSV 格式进行了优化。请确保您的 CSV 文件包含可识别的列名，特别是关于文件路径（如 "文件名称"、"Path"）和文件大小（如 "大小"、"Size"）的列。
  • 如果程序提示找不到关键列（如 'Path'、'File Name' 或 'Size'），请检查您的 CSV 文件格式是否正确，或者列名是否与程序预期的有所不同。程序在无法找到 'Path' 列时，会尝试使用 'File Name' 列作为替代。
• AI API 密钥:
  • AI 分析功能依赖于大语言模型服务。您需要在 src/config.py 文件中配置好您的 API 密钥，或者设置相应的环境变量。具体请参考 src/config.py.example 文件。
  • 如果未配置 API 密钥，AI 相关的功能将无法正常使用，但基础的磁盘数据统计和展示功能仍然可用。
• 数据量与性能:
  • 处理非常大的 CSV 文件（例如包含数百万条目）可能会消耗较多时间和内存。程序在设计时已考虑优化，但极端情况下仍需耐心等待。
  • AI 分析部分为了避免超出 API 的 token 限制，会选择性地发送数据摘要或部分数据（如最大的文件列表）给 AI。
  • 对于 "AI 分析特定文件夹内容" 功能，单次查询的文件数量上限由 src/config.py 中的 max_folder_files 配置（默认1000）；序列化 JSON 最大大小由 max_folder_json_size_mb 配置（默认1MB）。可根据需要和选用的api窗口大小调整这些参数以控制提交到 AI API 的数据量。
  • 如果需要更大上下文窗口，可在 src/config.py 中将 model_name 设置为支持更大 token 上限的模型（如 gpt-4-32k、gpt-4o 等），并确保相应的 api_endpoint 支持该模型。

• 产品需求文档 (PRD) - 产品功能说明
• 项目开发状态 (Project Development Status) - 开发进度和功能状态
• 项目维护说明书 - 部署和维护指南
• 开发日志 - 技术实现心得记录

AI 磁盘空间分析助手 (Csv_Chat) 当前版本 (V0.5) 已经成功实现了以下核心功能：

1. CSV 数据导入与处理：
   • 通过 Streamlit Web 界面引导用户选择 WizTree 导出的 CSV 文件。
   • 支持多种文件编码 (UTF-8, GBK, Latin1) 以增强兼容性。
   • 自动跳过 WizTree CSV 文件的元数据行，直接读取数据。
   • 对列名进行标准化处理（例如，将 '文件名称' 统一为 'File Name'，'大小' 统一为 'Size'）。
   • 对 'Size' 列进行数值转换和空值处理。
2. 核心数据分析：
   • 计算并展示扫描的总文件/文件夹数量和总占用空间（动态格式化单位）。
   • 识别并列出占用空间最大的 Top N (默认为100，可在界面调整) 个文件或文件夹，显示其路径和大小。
   • 文件分类统计：根据预设的类别（图片、视频、文档等）对文件进行归类，并统计每个类别的总大小、文件数量及占总空间的百分比。
   • 文件扩展名统计：统计不同文件扩展名的总大小，并列出 Top N (默认为20，可在界面调整) 的扩展名及其占用空间。
   • 所有分析结果通过 Streamlit Web 界面清晰展示。
3. AI 分析集成：
   • 集成了 AISuggest 类，能够接收分析结果的摘要信息，并（在配置真实AI服务后）调用 AI 进行特定文件夹内容的分析和问答。
   • 提供了通过 src/config.py 文件配置 AI 服务 API 密钥和模型参数的机制。
4. 模块化设计：
   • 代码结构清晰，主要逻辑分布在 src/app.py (Streamlit 前端与交互逻辑)、src/deal_csv.py (CSV 处理与核心数据分析)、src/ai_analyzer.py (AI 分析逻辑) 和 src/config.py (配置管理)。
   • 定义了 AnalysisResult 类 (在 src/deal_csv.py 中) 来结构化存储分析结果，便于传递和处理。

当前交互方式：

• 输入：通过 Streamlit Web 界面提供文件上传功能，用户可在浏览器中直接选择或拖拽 CSV 文件。
• 输出：所有分析结果和 AI 建议均通过 Streamlit Web 界面在浏览器中以丰富的形式（表格、图表、文本、交互式元素）直观展示。

这种方式极大地提升了用户体验，使得不熟悉代码的用户也能轻松、直观地使用本工具。

未来交互性改进方向：

为了持续提升用户体验，可能考虑以下几个方向来增强交互性：

1. 更智能的列名识别与容错：
   • 当前：程序主要依赖固定的中文（"文件名称"、"大小"、"路径"）和英文（"File Name"、"Size"、"Path"）列名，并在 "Path" 列缺失时尝试使用 "文件名称" 列。
   • 改进设想：引入更灵活的列名匹配机制，例如模糊匹配或正则表达式。或者，在列名不完全匹配时，提供用户界面让用户手动指定 CSV 列与数据项的映射。
2. 更高级的交互式图表与筛选：
   • 在现有 Streamlit 基础上，探索集成更高级的交互式图表库（如 Plotly Express 的更高级用法, Bokeh），允许用户在图表上进行缩放、筛选、点击查看详情等更丰富的操作。
3. 历史数据快照与对比分析：
   • 支持用户保存当前分析会话的"快照"。
   • 允许导入多次扫描的 CSV 文件或历史快照，并对它们进行对比，分析文件和文件夹大小随时间的变化趋势。
4. 自定义清理规则与预设场景：
   • 允许用户设置自定义规则来识别冗余文件（例如，查找特定模式的重复文件、特定时间范围内的临时文件等）。
   • 提供一些预设的分析场景，如"查找大型日志文件"、"分析下载文件夹"等。
5. 用户界面 (UI/UX) 精细优化：
   • 持续改进用户界面的美观性、响应速度和易用性，提供更流畅、更友好的用户体验。
   • 优化移动设备上的显示效果。
6. 更深入的 AI 集成与个性化建议：
   • 探索更多 AI 应用场景，例如根据文件内容摘要（如果能安全获取）进行更精准的分类。
   • 根据用户的使用习惯和历史操作，提供更个性化的存储优化建议。
7. 错误处理与用户引导强化：
   • 当 CSV 文件格式不符合预期，或缺少关键信息时，提供更清晰、更具指导性的错误提示和解决建议。
   • 增加更完善的用户操作指引和帮助文档。