hz4th_coder/material-library
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
material-library/API.md
T

6.7 KiB
Raw Permalink Blame History

素材库系统 — 完整 API 文档

  • 基础地址：http://<主机>:16091
  • 数据格式：JSON（Content-Type: application/json）
  • 文件上传：multipart/form-data
  • 所有接口均为无鉴权访问（内网工具）；如需鉴权可自行在前面加网关

一、项目 Projects

1.1 项目列表

GET /api/projects

查询参数：

参数 说明
q 关键词（匹配名称/描述/标签）
category 按类别过滤（精确）
tags 按标签过滤（逗号分隔，多标签=同时满足 AND）

响应：项目数组，每项含 id, name, description, category, tags, created_at, updated_at, material_count, analyzed_count, analysis（最新项目摘要）

1.2 新建项目

POST /api/projects

{"name": "项目名", "description": "描述", "category": "市场资讯", "tags": "AI,行业"}

1.3 项目详情（含全部素材+分析）

GET /api/projects/<id>

响应：项目对象 + materials 数组（每个素材含抽取文本与最新 AI 分析）

1.4 修改项目

PUT /api/projects/<id>

{"name": "新名", "description": "新描述", "category": "新类别", "tags": "新标签"}

（缺省字段保持原值）

1.5 删除项目（级联删素材+分析+文件）

DELETE /api/projects/<id>

1.6 项目摘要历史

GET /api/projects/<id>/summaries

响应：该项目全部项目级 AI 摘要（按时间倒序），每份含 id, summary, key_points[], keywords[], tags[], category, created_at, model

二、素材 Materials

2.1 批量上传文件

POST /api/projects/<id>/materials/upload multipart/form-data，字段 files（可多个）

支持类型：文本(txt/md/csv/json/xml/srt/log/html) · 文档(pdf/docx/pptx) · 图片 · 视频 · 音频

响应：{"results": [素材对象], "count": n}；不支持的扩展名返回 {"ok":false,"error":"..."}

2.2 新增文本素材（粘贴内容）

POST /api/projects/<id>/materials

{"name": "素材名", "content": "文本内容"}

2.3 素材详情

GET /api/materials/<id>

响应含：name, mtype, file_path, file_size, ext, meta(宽高/格式), extracted_text, text_status, status, created_at, analysis（最新素材级分析）

2.4 修改素材（改名 / 编辑文本内容）

PUT /api/materials/<id>

{"name": "新名字", "content": "新内容", "mtype": "text"}
  • content 有值时更新正文并作废旧分析（需重新分析）
  • 缺省字段保持原值

2.5 删除素材

DELETE /api/materials/<id>

2.6 下载/预览素材文件

GET /files/<material_id>

  • 图片/音视频：浏览器内预览；其它：下载

三、AI 分析 Analysis

3.1 分析单个素材

POST /api/materials/<id>/analyze → {"ok": true, "task": "material:<project_id>"} 后台执行，用任务接口轮询进度。

3.2 分析项目全部素材

POST /api/projects/<id>/analyze → {"ok": true, "task": "material:<project_id>"}

3.3 生成项目级 AI 摘要

POST /api/projects/<id>/summary → {"ok": true, "task": "summary:<project_id>"} 每次生成都会保留为一条历史记录。

3.4 任务进度查询

GET /api/tasks/<key> → {"running": bool, "done": n, "total": n, "msg": "已分析 2/4", "error": null}

四、搜索 Search

4.1 全文搜索

GET /api/search?q=关键词

  • 项目匹配（名称/描述/标签 LIKE）
  • 素材匹配（SQLite FTS5 + jieba 中文分词，索引含素材名/正文/AI摘要/关键词）

响应：{"projects": [...], "materials": [...]}

4.2 元数据/统计

GET /api/meta 响应：{"categories": [{name,count}], "tags": [{name,count}], "stats": {projects, materials, analyzed}}

五、设置 Settings

5.1 读取设置

GET /api/settings 响应（KV）：

{
  "llm_base_url": "https://api.deepseek.com",
  "llm_api_key": "sk-...",
  "llm_model": "deepseek-v4-flash",
  "vision_base_url": "https://ark.cn-beijing.volces.com/api/plan/v3",
  "vision_api_key": "ark-...",
  "vision_model": "doubao-seed-evolving",
  "backup_interval_hours": "24",
  "backup_change_threshold": "50",
  "backup_max_keep": "10",
  "last_backup_time": "...",
  "change_counter": "0"
}

5.2 保存设置

PUT /api/settings 传需要修改的字段即可（部分更新）。大模型/视觉接口改动立即生效，无需重启。

5.3 测试接口连接

POST /api/settings/test

{"kind": "llm|vision", "base_url": "...", "api_key": "...", "model": "..."}

→ {"ok": true, "reply": "..."} 或 {"ok": false, "error": "..."}

六、备份 Backups

6.1 备份列表

GET /api/backups → {"backups": [{name,size,time}], "last_backup_time": "...", "change_counter": "5"}

6.2 手动立即备份

POST /api/backup → {"ok": true, "name": "backup_20260827_100000_manual.zip"} 备份包含完整数据库 + 上传目录，打包为 zip 存于 data/backups/

6.3 下载备份

GET /api/backup/download/<文件名>

6.4 删除备份

DELETE /api/backup/<文件名>

6.5 导入恢复备份

POST /api/backup/restore multipart/form-data，字段 file（上传备份 zip）

⚠️ 会覆盖当前全部数据（数据库 + 上传目录），后台有任务运行时返回 409 拒绝。

七、自动备份触发规则

后台调度器每 30 秒检查一次，满足以下任一条件即自动备份：

  1. 时间间隔：距上次备份 ≥ backup_interval_hours 小时（0=关闭）
  2. 变更量：change_counter（项目/素材增删改次数）≥ backup_change_threshold（0=关闭）

备份后 change_counter 清零、last_backup_time 更新。保留份数 backup_max_keep，超出自动删除最旧备份。

八、错误码约定

情况 状态码
参数/校验错误 400（{"error": "..."}）
资源不存在 404
后台任务运行中（恢复备份） 409
服务器内部错误 500

九、调用示例（curl）

# 新建项目
curl -X POST http://127.0.0.1:16091/api/projects \
  -H 'Content-Type: application/json' \
  -d '{"name":"调研","category":"研究","tags":"AI"}'

# 上传文件
curl -X POST http://127.0.0.1:16091/api/projects/1/materials/upload \
  -F "files=@report.pdf" -F "files=@pic.png"

# 新增文本素材
curl -X POST http://127.0.0.1:16091/api/projects/1/materials \
  -H 'Content-Type: application/json' \
  -d '{"name":"笔记","content":"这是内容"}'

# 全文搜索
curl "http://127.0.0.1:16091/api/search?q=大模型"

# 分析项目全部素材 → 轮询任务
curl -X POST http://127.0.0.1:16091/api/projects/1/analyze
curl http://127.0.0.1:16091/api/tasks/material:1

# 立即备份
curl -X POST http://127.0.0.1:16091/api/backup
Reference in New Issue View Git Blame Copy Permalink