material-library/README.md

素材库系统 (Material Library)

Flask + SQLite + FTS5 全文检索 + DeepSeek/豆包大模型分析 的素材管理平台。

功能

1. 项目与素材管理

• 新建项目：名称、描述、类别、标签（逗号分隔）
• 修改项目：改类别/标签/描述/名称，增删素材
• 素材导入：
  • 拖拽/点击批量上传文件：文本(txt/md/csv/json/xml/srt…) · 文档(pdf/docx/pptx) · 图片 · 视频 · 音频
  • 直接粘贴文本素材
• 自动文本抽取：txt/md/pdf/docx/pptx 上传即抽取正文，图片提取分辨率/格式元数据

2. 大模型分析（DeepSeek + 豆包视觉）

• 素材级分析：一键分析单个或全部素材，提取
  • 摘要 (summary) · 关键要点 (key_points) · 关键词 (keywords) · 推荐标签 (tags) · 建议归类 (category)
  • 图片走豆包视觉模型生成"视觉描述"，再让 DeepSeek 提炼关键信息
• 项目级摘要：汇总项目全部素材，生成项目报告（摘要/关键发现/项目级关键词/标签/类别）
• 后台线程执行 + 前端轮询进度

3. 索引与查询

• SQLite FTS5 全文索引（jieba 分词）：素材名 + 抽取文本 + AI摘要 + 关键词 全部入库
• 站内搜索：项目匹配 + 素材匹配（带 AI 摘要预览）
• 分类过滤 / 标签多选过滤（同时勾选多个标签 = 同时满足）

4. 系统设置（⚙️ 右上角）

• 大模型配置：分析大模型（OpenAI 兼容接口）+ 图片视觉模型，地址/Key/模型名 均可改，支持“测试连接”
• 自动备份（双触发）：
  • 时间间隔（小时，0=关闭）
  • 变更量阈值（项目/素材改动次数，0=关闭）
  • 后台调度器 30s 检查一次，命中任一条件自动打包备份
  • 保留份数可调，自动清理旧备份
• 手动备份 / 导出 / 删除 备份文件
• 导入恢复：上传备份 zip 一键还原（覆盖当前数据，有确认）

5. 其他便捷功能

• 文本素材直接编辑：查看详情时文本区域默认可直接编辑，点「💾 保存」才真正落库；有未保存修改时关闭弹窗/点外部区域会提示是否保存，防误点
• Markdown 切换：文本查看支持「纯文本 / Markdown」切换，默认纯文本，Markdown 模式渲染预览（只读）
• 粘贴图片上传：在项目页直接 Ctrl+V 粘贴剪贴板截图/图片
• 一键复制：文本素材可一键复制全文（表格行 + 详情弹窗均有入口）
• 摘要历史：每次生成的“项目 AI 摘要”全部保留，可展开查看历史版本
• 素材列表：显示类型/名称/大小/创建时间/状态/操作，点列头可按类型/名称/大小/创建时间升序降序排序
• Logo 点击：左上角 Logo 一键返回首页
• API 文档：右上角 📖 按钮（或 /api-doc）查看完整接口文档，详见 API.md

技术栈

• 后端：Flask 3 (Python 3.12, openclaw conda 环境)
• 存储：SQLite (WAL) + 文件系统 (data/uploads/)
• 检索：SQLite FTS5 + jieba
• LLM：DeepSeek deepseek-v4-flash（结构化 JSON 分析）+ 豆包 doubao-seed-evolving（图片视觉描述）

API 文档

• 网页版：http://<IP>:16091/api-doc（右上角 📖 按钮）
• 完整文档见 API.md（含全部接口、参数、响应、curl 示例）

快速开始

./start.sh          # 启动 (默认 16091)
./start.sh stop     # 停止
./start.sh restart  # 重启
# 访问 http://<IP>:16091/

目录结构

material-library/
├── app.py              # Flask 主程序（路由/抽取/LLM/FTS/后台任务）
├── start.sh            # 启停脚本 (PID 管理)
├── static/index.html   # 前端单页应用
└── data/
    ├── material.db     # SQLite 数据库
    ├── uploads/        # 上传的素材文件
    └── shots/          # 界面截图

数据库表

• projects — 项目（名称/描述/类别/标签）
• materials — 素材（类型/文件/抽取文本/状态）
• analyses — 分析结果（素材级 + 项目级，JSON 字段，项目摘要保留全部历史）
• materials_fts — FTS5 全文索引
• settings — 系统设置（大模型配置 / 备份参数，KV 存储）

备份说明

• 备份目录：data/backups/backup_YYYYMMDD_HHMMSS[_manual].zip（含完整数据库 + 上传目录）
• 自动备份由后台线程触发（时间间隔 / 变更量双条件）
• 恢复 = 上传 zip → 校验 → 覆盖数据库与上传目录 → 自动重建索引

API 一览

方法	路径	说明
GET	/api/projects?q=&category=&tag=	项目列表
POST/PUT/DELETE	/api/projects[/<id>]	项目增改删
GET	/api/projects/<id>	项目详情(含素材+分析)
POST	/api/projects/<id>/materials/upload	批量上传文件
POST	/api/projects/<id>/materials	新增文本素材
GET/PUT/DELETE	/api/materials/<id>	素材详情/改名/删除
POST	/api/materials/<id>/analyze	分析单个素材
POST	/api/projects/<id>/analyze	分析项目全部素材
POST	/api/projects/<id>/summary	生成项目摘要
GET	/api/search?q=	全文搜索
GET	/api/meta	统计/分类/标签
GET	/files/<id>	素材下载/预览