Doc-Mind-Search
基于 qwen_agent + MCP 协议实现的多格式文档统计、内容检查助手。支持 PDF、DOCX、Excel(xlsx/xls/csv)、HTML 等格式。
项目结构
multi_doc_counter/
├── doc_counter_mcp.py # MCP Server：注册多格式文档的计数 / 列表 / 读取工具
├── assistant_doc_bot.py # qwen_agent Assistant + WebUI，连接 MCP server
├── config_loader.py # 配置加载器（两个脚本共用）
├── config.yaml.example # 配置文件模板（不含敏感信息）
├── config.yaml # 实际配置（需自行创建，已加入 .gitignore）
├── requirements.txt # 依赖清单
├── LICENSE # MIT License
├── .gitignore # Git 忽略规则
├── .gitattributes # 跨平台换行符统一
└── README.md # 本文档
支持的文档格式与工具
MCP Server (doc_counter_mcp.py) 注册了以下工具：
| 工具 | 功能 | 支持格式 |
|---|---|---|
get_desktop_doc_stats |
桌面文档数量总览 | 全部 |
count_desktop_files |
按类型统计文件数量 | txt/pdf/docx/xlsx/xls/csv/html/excel |
list_desktop_files |
按类型列出文件清单 | 同上 |
read_txt_file |
读取 txt 内容（字符数/行数） | .txt |
read_pdf_file |
提取 PDF 文本（页数） | |
read_docx_file |
提取 Word 文本（段落数/字符数） | .docx |
read_excel_file |
读取表格（sheet/行列/预览） | .xlsx / .xls / .csv |
read_html_file |
提取 HTML（标题/链接数/正文） | .html / .htm |
所有工具默认在 桌面 目录（
~/Desktop）下操作（可自行修改扫描目录）。
安装依赖
需要 Python ≥ 3.10。建议在独立虚拟环境（venv / conda）中安装。
# 1. 克隆仓库
git clone https://github.com/<your-username>/multi_doc_counter.git
cd multi_doc_counter
# 2. 安装依赖（国内用户可加 -i https://pypi.tuna.tsinghua.edu.cn/simple 走清华源）
pip install -r requirements.txt
若使用 Anaconda，把
pip替换为对应的 Python 解释器，例如：& "D:/anaconda/python.exe" -m pip install -r requirements.txt
配置（config.yaml）
所有可变参数都集中在 config.yaml，改完重启程序即可生效，无需改动代码。
仓库不携带 config.yaml（含明文 Key，已加入 .gitignore），请先从模板复制一份：
cp config.yaml.example config.yaml # Windows PowerShell: Copy-Item config.yaml.example config.yaml
然后填入你自己的 API Key：
# DashScope API 配置
dashscope:
api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 在此填入你的阿里云百炼 API Key
timeout: 30
# 模型配置
model:
name: "qwen-max"
timeout: 30
retry_count: 3
# 文档检查路径配置
file_path:
scan_dir: "~/Desktop" # 改这里即可扫描任意目录
# MCP server 端口
mcp:
port: 6278
修改扫描目录（不再局限于桌面）
把 file_path.scan_dir 改成任意路径即可，支持：
| 写法 | 含义 |
|---|---|
"~/Desktop" |
桌面（默认） |
"~/Documents" |
用户文档目录 |
"D:/mydocs" |
指定绝对路径 |
"C:\\Users\\admin\\Desktop" |
Windows 绝对路径 |
建议使用
~/开头或绝对路径，避免相对路径依赖运行目录。
联网搜索（Tavily，可选）
在 config.yaml 填入 tavily.api_key 后，助手会额外接入 tavily-mcp，获得联网搜索能力（搜索新闻、查找资料等）。留空则仅本地文档功能可用。
tavily:
api_key: "tvly-xxxxxxxx" # 填入即启用；留空则禁用
前置条件：
- 到 https://app.tavily.com/dashboard 注册获取 API Key（有免费额度）
- 本机需安装 Node.js / npx（因为通过
npx [email protected]启动官方 MCP 服务），检查命令：npx -v
启用后，助手会根据问题自动在"本地文档工具"和"联网搜索"之间选择。
API Key 说明
api_key 通过 llm_cfg['api_key'] 显式传给 qwen_agent，避免被其它来源覆盖（曾经踩过的 InvalidApiKey 坑）。
安全提醒：
config.yaml含明文 Key，请勿提交到 git。建议把config.yaml加入.gitignore，另存一份config.yaml.example（Key 留空）作为模板。可到 百炼控制台 申请 / 管理 Key。
运行
GUI 模式（默认）
python assistant_doc_bot.py
启动后访问 http://127.0.0.1:7860 ，在对话框输入自然语言指令即可，例如：
- 帮我统计桌面上各种文档的数量
- 桌面上有多少个 PDF 文件？列出来
- 读取桌面上的 test.pdf 文件内容
- 读取桌面上的 data.xlsx 表格内容
终端模式（TUI）
把 assistant_doc_bot.py 末尾改为：
if __name__ == '__main__':
app_tui()
测试模式
if __name__ == '__main__':
test()
工作原理
用户 ──> WebUI(7860) ──> qwen_agent Assistant(qwen-max)
│ 调用工具时通过 MCP 协议
▼
┌─────────────────────┴──────────────────────┐
▼ ▼
doc_counter_mcp.py (本地文档) tavily-mcp (联网搜索，可选)
│ │
▼ ▼
读取/统计本地各类文档 搜索新闻/资料/网页内容
assistant_doc_bot.py通过mcpServers配置以子进程方式拉起 MCP 服务（doc_counter_mcp.py必启；tavily-mcp仅在配置了tavily.api_key时启用）- 大模型根据用户意图自动选择并调用合适的 MCP 工具
- 工具结果返回给大模型，再组织成自然语言回复给用户
备注
command字段为"python"，依赖系统 PATH 中的python能解析到已安装mcp库的解释器。如遇ModuleNotFoundError: No module named 'mcp'，请把command改成对应解释器的绝对路径（如 Anaconda 的D:/anaconda/python.exe）。- 单文件内容超过 5000 字符会被截断，避免撑爆模型上下文。
安全提醒
config.yaml含明文 API Key，已加入.gitignore，不会上传 GitHub。- 提交前请检查
git status，确认config.yaml不在暂存区。 - 若历史提交中曾误传 Key，请立即在 百炼控制台 吊销并重新生成，并使用
git filter-repo清理历史。
贡献
欢迎提 Issue 或 PR。提交前请确保：
- 不要把
config.yaml加入暂存区 - 新增依赖请同步更新
requirements.txt - 代码风格与现有文件保持一致
License
本项目基于 MIT License 开源，可自由使用、修改和分发。
