Skip to content
BranchesTags

Repository files navigation

FileIndex · 本地文件识别与检索

一款只读的本地文件识别、文档解析与语义检索 Web 软件。当前版本不移动、不删除任何文件，仅对指定路径建立索引，并提供自然语言搜索、文件导出、在线预览、详情查看等功能。

同时，本项目已封装为 ModelScope AI PC Skill，可作为 Qoder / WorkBuddy / TRAE Work 等 Agent 的本地文档智能能力调用。

文档导航

文档 内容
README.md 项目简介、快速开始、API 概览、项目结构
DEPLOYMENT.md 详细部署文档：环境要求、安装、启动、进程守护、日志排查、升级
USAGE.md 使用文档：Web 界面、Skill 工具、Agent 集成、典型工作流
SUBMISSION.md ModelScope AI PC Skill 提交说明与打包上传指南
SKILL.md 面向 Agent 的工作流指令与工具 schema
doc-engine/README.md Python 文档解析与向量服务说明
skill/README.md Skill 集成说明与服务启动方式
skill/tools/README.md 各 Skill 工具脚本的详细参数与示例
scripts/README.md 打包与上传脚本使用说明

技术栈

  • 前端：HTML + CSS + 原生 JavaScript
  • 主服务：Node.js + Express
  • 文档/向量服务：Python + FastAPI + OpenVINO
  • 文本向量化：BGE（OpenVINO 推理）
  • 图片描述：MiniCPM-V-4.6（OpenVINO INT4 推理）
  • 向量检索：FAISS
  • 文档解析：PyMuPDF、python-docx、RapidOCR
  • 数据库：SQLite（better-sqlite3）

快速开始

一键初始化（推荐）

python skill/tools/setup_environment.py

这条命令会自动完成以下步骤：

  1. 检查 Node.js >= 18、npm >= 9、Python >= 3.10
  2. 安装 Node.js 依赖（npm install）
  3. 安装 Python 依赖（pip install -r doc-engine/requirements.txt）
  4. 下载并导出 OpenVINO 模型：
    • BGE 文本嵌入模型（约 400MB）
    • MiniCPM-V-4.6 视觉语言模型 INT4（原始约 2.6GB，量化后约 1.3GB）
  5. 启动本地服务（http://127.0.0.1:3456）

首次初始化需要下载约 2-3GB 模型文件，并保持网络畅通。如果网络较慢，可以分步执行：先运行 --skip-model，再单独运行 doc-engine/scripts/download_models.py。

如果暂时不想下载模型，可以：

python skill/tools/setup_environment.py --skip-model
USE_DUMMY_EMBEDDER=1 npm start

虚拟嵌入器仅用于验证接口，语义搜索结果是随机的。

手动分步安装

# 1. 安装 Node 依赖
npm install

# 2. 安装 Python 依赖
cd doc-engine
pip install -r requirements.txt

# 3. 下载并导出 OpenVINO 模型
python scripts/download_models.py

# 4. 启动服务
cd ..
npm start

浏览器打开

open http://localhost:3456

使用流程

  1. 打开「配置」页面，点击「添加路径」，在弹出的系统文件夹选择器中选择本地目录。
  2. 点击路径右侧的「启动索引」按钮，系统会扫描目录、解析文档/图片，并建立语义索引。
    • 图片会自动判断：OCR 文字多的按文档图处理；文字少的调用 MiniCPM-V-4.6 生成描述。
  3. 切换到「搜索」页面，在顶部大搜索框输入自然语言（如"小狗"、"合同违约条款"），查看命中的文件列表。
  4. 点击文件卡片可预览；点击「查看详情」可看完整属性、解析内容和 PDF/图片原件。
  5. 在搜索结果页可勾选文件，点击「导出选中」将文件复制到指定目录。

主要 API

索引配置

  • GET /api/status — 服务整体状态
  • GET /api/paths — 已添加的索引路径
  • POST /api/paths — 添加索引路径
  • POST /api/paths/:id/scan-and-index — 扫描并索引单条路径
  • POST /api/paths/:id — 删除索引路径（同时清除解析数据与语义数据）

自然语言搜索

  • POST /api/search/natural — 自然语言搜索（参数：query, top_k, threshold, type）

文件操作

  • GET /api/files/:id — 文件详情（含解析内容）
  • GET /api/files/:id/preview — 文件预览信息
  • GET /api/files/:id/raw — 返回文件原始内容
  • POST /api/files/export — 导出选中的文件到指定目录
  • POST /api/files/:id/open — 用系统默认程序打开文件
  • POST /api/files/:id/open-folder — 打开文件所在文件夹

文档服务

  • GET /api/doc-engine/status — Python 文档服务状态
  • POST /api/documents/:id/parse — 解析单个文档/图片
  • POST /api/documents/:id/index — 对文件建立向量索引
  • POST /api/documents/:id/delete-index — 删除文件向量索引

RAG 问答（可选）

  • GET /api/llm/status — Ollama 可用状态
  • POST /api/chat — RAG 问答（参数：query, top_k）

Skill 工具（ModelScope / Agent 调用）

skill/tools/ 目录下提供 6 个命令行工具，供 Agent 调用本地服务：

工具 作用
setup_environment.py 一键安装依赖、下载模型并启动服务（首次使用）
add_index_path.py --path /path/to/dir 添加并扫描本地目录
search_files.py --query "违约条款" --top_k 5 自然语言语义搜索
index_document.py --file_path /path/to/file.pdf 为指定文件构建向量索引
semantic_search.py --query "违约条款" --top_k 5 语义检索文档片段
chat.py --query "违约金怎么算？" --top_k 5 RAG 问答

除 setup_environment.py 外，其余工具在调用前会自动检测本地服务状态；若未运行，会在后台自动启动。若依赖缺失，会提示先运行 setup_environment.py。

详见 SKILL.md 了解完整工作流与最佳实践。

打包与上传到 ModelScope

# 仅打包
python scripts/package-skill.py --output file-index-assistant.zip

# 打包并上传（需设置 MODELSCOPE_API_TOKEN）
export MODELSCOPE_API_TOKEN=your_token
python scripts/upload-skill.py --source . --output file-index-assistant.zip

详见 SUBMISSION.md。

项目结构

file-index/
├── .design                 # Design Canvas 文件
├── manifest.json           # Skill 元数据与工具定义
├── SKILL.md                # Agent 工作流说明
├── SUBMISSION.md           # ModelScope 提交说明
├── DEPLOYMENT.md           # 部署文档
├── USAGE.md                # 使用文档
├── package.json
├── server.js               # Express 主服务
├── doc-engine/             # Python 文档解析与向量服务
│   ├── README.md
│   ├── main.py             # FastAPI 入口
│   ├── requirements.txt
│   ├── config.py           # 模型与阈值配置
│   ├── parser/             # 文档/图片解析与描述
│   ├── embedding/          # OpenVINO BGE 嵌入器
│   ├── store/              # FAISS 向量存储
│   ├── llm/                # Ollama 客户端与 RAG 提示词
│   └── scripts/            # 模型下载脚本
├── skill/                  # Skill 集成
│   ├── README.md
│   └── tools/              # Skill 命令行工具脚本
│       ├── README.md
│       ├── setup_environment.py
│       ├── add_index_path.py
│       ├── search_files.py
│       ├── index_document.py
│       ├── semantic_search.py
│       ├── chat.py
│       ├── _client.py
│       └── _service_manager.py
├── scripts/                # 打包与上传脚本
│   ├── README.md
│   ├── package-skill.py
│   └── upload-skill.py
├── db/                     # SQLite 数据库（运行时生成）
├── pages/                  # 前端页面
│   ├── index.html          # 搜索页
│   ├── detail.html         # 文件详情
│   ├── settings.html       # 配置页
│   ├── shared.css          # 公共样式
│   └── *.js
└── assets/icons/           # 图标

注意事项

  • 首次扫描会根据目录大小和文件数量耗时不同，请耐心等待。
  • MiniCPM-V-4.6 在 CPU 上生成一张图片描述约需 2-10 秒，大量图片索引时请保持耐心。
  • SHA-256 哈希仅在进入详情页且文件 ≤ 50 MB 时计算，避免大文件拖慢响应。
  • 由于浏览器安全限制，文件打开/导出功能由后端调用系统 API 完成。
  • 文档解析/向量化依赖 Python 环境，若未安装或未下载模型，AI 搜索功能将不可用，但文件索引与基础检索不受影响。
  • Skill zip 包不含模型文件与数据库，用户首次使用需在本地下载模型并启动服务。

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages