# 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）中安装。

```bash
# 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`），请先从模板复制一份：

```bash
cp config.yaml.example config.yaml        # Windows PowerShell: Copy-Item config.yaml.example config.yaml
```

然后填入你自己的 API Key：

```yaml
# 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`，获得联网搜索能力（搜索新闻、查找资料等）。留空则仅本地文档功能可用。

```yaml
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 留空）作为模板。
> 可到 [百炼控制台](https://bailian.console.aliyun.com/?apiKey=1#/api-key) 申请 / 管理 Key。

## 运行

### GUI 模式（默认）

```bash
python assistant_doc_bot.py
```

启动后访问 http://127.0.0.1:7860 ，在对话框输入自然语言指令即可，例如：

- 帮我统计桌面上各种文档的数量
- 桌面上有多少个 PDF 文件？列出来
- 读取桌面上的 test.pdf 文件内容
- 读取桌面上的 data.xlsx 表格内容

### 终端模式（TUI）

把 `assistant_doc_bot.py` 末尾改为：

```python
if __name__ == '__main__':
    app_tui()
```

### 测试模式

```python
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，请立即在 [百炼控制台](https://bailian.console.aliyun.com/?apiKey=1#/api-key) 吊销并重新生成，并使用 [`git filter-repo`](https://github.com/newren/git-filter-repo) 清理历史。

## 贡献

欢迎提 Issue 或 PR。提交前请确保：

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

## License

本项目基于 [MIT License](./LICENSE) 开源，可自由使用、修改和分发。