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 文本（页数）	.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 tavily-mcp@0.1.4 启动官方 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。提交前请确保：

1. 不要把 config.yaml 加入暂存区
2. 新增依赖请同步更新 requirements.txt
3. 代码风格与现有文件保持一致

License

本项目基于 MIT License 开源，可自由使用、修改和分发。