<div align="center">

# 🦞 FilePulse-CLI

**Lightweight Terminal Intelligent File Search Engine**
**轻量级终端智能文件搜索引擎**

[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-orange.svg)]()
[![Cross-Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

[🌐 简体中文](#-简体中文) | [繁體中文](#-繁體中文) | [🇺🇸 English](#-english)

> 🔥 **AI时代的文件搜索引擎** — 基于Frecency记忆排序的智能文件搜索，让AI Agent和开发者在海量代码中精准定位目标文件，越用越聪明。

---

</div>

---

## 🇨🇳 简体中文

### 🎉 项目介绍

**FilePulse-CLI** 是一款零外部依赖的轻量级终端智能文件搜索引擎。灵感来源于GitHub Trending热门项目 [fff](https://github.com/dmtrKovalenko/fff)，我们独立自研了纯Python实现，并做了大量差异化优化。

**解决的核心痛点：**
- 🔍 每次搜索都从零开始，没有"记忆"——传统工具（ripgrep/fzf）无法学习你的使用习惯
- 🤖 AI Agent在大型代码库中搜索效率低下，需要多次往返才能找到目标文件
- 📁 Git仓库中已修改的文件无法被优先展示
- 🌏 中文路径和文件名支持不佳

**自研差异化亮点：**
- 🧠 **Frecency记忆排序** — 基于频率×最近性的指数衰减算法，越常用越靠前
- 🎯 **拼写容错模糊搜索** — 子序列匹配+Levenshtein距离，输入"mn"也能找到"main.py"
- 🔀 **Git状态感知** — 自动检测已修改/已添加文件并提升排名
- 🤖 **MCP Server模式** — 原生支持AI Agent集成（Claude Code/Cursor/Windsurf）
- 📊 **TUI交互式仪表盘** — 实时展示文件分布、Frecency排行、Git状态
- 🌏 **中文路径优化** — 完整支持CJK字符的模糊匹配
- 📤 **多格式导出** — 支持JSON/CSV/Markdown结果导出
- 🚫 **零外部依赖** — 纯Python标准库实现，开箱即用

### ✨ 核心特性

| 特性 | 描述 |
|------|------|
| 🧠 **Frecency排序** | 频率×最近性加权，指数时间衰减，越用越精准 |
| 🎯 **模糊匹配** | 子序列匹配+连续字符奖励+词边界加分+Levenshtein回退 |
| 🔀 **Git感知** | 自动检测modified/added/deleted状态，优先展示工作文件 |
| 🤖 **MCP协议** | JSON-RPC 2.0 over HTTP，5个工具端点，支持stdio模式 |
| 📊 **TUI仪表盘** | ASCII图表展示文件类型分布、Frecency排行、Git状态概览 |
| 📤 **多格式导出** | JSON / CSV / Markdown，一键导出搜索结果 |
| 🌏 **CJK优化** | 中文/日文/韩文路径完整支持 |
| 🚫 **零依赖** | 纯Python标准库，Python 3.8+即可运行 |
| ⚡ **高性能** | 智能忽略模式，跳过二进制文件，大小限制过滤 |
| 🔧 **可配置** | JSON配置文件，支持自定义忽略模式、阈值、衰减参数 |

### 🚀 快速开始

**环境要求：**
- Python 3.8 或更高版本
- 无需安装任何外部依赖

**安装方式：**

```bash
# 方式一：直接克隆运行（推荐）
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# 方式二：使用 pip 安装
pip install .
filepulse --help
```

**基本使用：**

```bash
# 搜索文件名
filepulse search "main.py"

# 模糊搜索（默认开启）
filepulse search "mn" --fuzzy

# 搜索文件内容
filepulse search "def hello" --content

# 按文件类型过滤
filepulse search "config" --type json

# Git感知搜索（优先展示已修改文件）
filepulse search "utils" --git

# 限制搜索深度
filepulse search "test" --depth 2

# JSON输出
filepulse search "readme" --json

# 导出结果
filepulse search "model" --export results.csv
```

### 📖 详细使用指南

#### 搜索模式

```bash
# 📁 文件名搜索（默认）
filepulse search "app.py"

# 📝 内容搜索（在文件内容中查找）
filepulse search "import flask" --content

# 🎯 精确搜索（禁用模糊匹配）
filepulse search "exact_name" --no-fuzzy
```

#### 过滤与排序

```bash
# 按扩展名过滤
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# 按大小过滤
filepulse search "log" --min-size 1KB --max-size 10MB

# 包含隐藏文件
filepulse search "config" --hidden

# 自定义忽略模式
filepulse search "test" --ignore "dist,build,.cache"

# 排序方式：frecency / name / size / modified / relevance
filepulse search "main" --sort size
```

#### TUI仪表盘

```bash
# 启动交互式仪表盘
filepulse dashboard

# 指定目录和刷新间隔
filepulse dashboard --path /your/project --refresh 5
```

#### MCP Server（AI Agent集成）

```bash
# 启动HTTP模式MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# 启动stdio模式（用于直接Agent集成）
filepulse mcp --stdio
```

**MCP工具列表：**
- `search_files` — 按文件名搜索（支持模糊匹配）
- `search_content` — 按文件内容搜索
- `get_file_info` — 获取文件详细信息
- `list_directory` — 列出目录内容
- `get_frecency_stats` — 获取Frecency统计

#### Frecency统计

```bash
# 查看搜索统计
filepulse stats

# 查看Top 20文件
filepulse stats --top 20

# JSON格式输出
filepulse stats --json

# 清除Frecency数据
filepulse stats --clear
```

### 💡 设计思路与迭代规划

**设计理念：**
FilePulse-CLI的核心设计理念是"**有记忆的搜索**"。传统搜索工具每次都从零开始，而FilePulse通过Frecency算法学习用户的使用模式——你经常访问的文件会自动获得更高的排名。这使得搜索结果随着使用越来越精准，特别适合在大型项目中日常使用。

**技术选型原因：**
- **纯Python标准库** — 零依赖策略确保在任何Python环境下都能直接运行，无需担心版本冲突或网络问题
- **Frecency算法** — 参考Firefox的Frecency实现，使用指数衰减函数平衡频率和最近性两个维度
- **MCP协议** — 采用JSON-RPC 2.0标准协议，确保与主流AI Agent的兼容性

**后续迭代计划：**
- [ ] 增量文件监听（inotify/FSEvents）
- [ ] 正则表达式搜索模式
- [ ] 文件内容预览功能
- [ ] 多仓库联合搜索
- [ ] 搜索历史记录与回溯
- [ ] Web UI仪表盘
- [ ] 插件系统（自定义搜索后端）

### 📦 打包与部署指南

**作为Python包安装：**

```bash
# 从源码安装
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# 验证安装
filepulse --version
```

**作为独立脚本使用：**

```bash
# 无需安装，直接运行
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse search "your-query"
```

**兼容环境：**
- Python 3.8, 3.9, 3.10, 3.11, 3.12
- Windows 10+, macOS 10.15+, Linux (主流发行版)
- 无需GPU、无需网络连接

### 🤝 贡献指南

欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

**快速开始：**
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/your-feature`)
3. 提交更改 (`git commit -m 'feat: add your feature'`)
4. 推送到分支 (`git push origin feature/your-feature`)
5. 发起 Pull Request

### 📄 开源协议

本项目基于 [MIT License](LICENSE) 开源。

---

## 🇹🇼 繁體中文

### 🎉 專案介紹

**FilePulse-CLI** 是一款零外部依賴的輕量級終端智能檔案搜尋引擎。靈感來源於GitHub Trending熱門項目 [fff](https://github.com/dmtrKovalenko/fff)，我們獨立自研了純Python實現，並做了大量差異化優化。

**解決的核心痛點：**
- 🔍 每次搜尋都從零開始，沒有「記憶」——傳統工具（ripgrep/fzf）無法學習你的使用習慣
- 🤖 AI Agent在大型程式碼庫中搜尋效率低下，需要多次往返才能找到目標檔案
- 📁 Git倉庫中已修改的檔案無法被優先展示
- 🌏 中文路徑和檔案名支援不佳

**自研差異化亮點：**
- 🧠 **Frecency記憶排序** — 基於頻率×最近性的指數衰減演算法，越常用越靠前
- 🎯 **拼寫容錯模糊搜尋** — 子序列匹配+Levenshtein距離，輸入「mn」也能找到「main.py」
- 🔀 **Git狀態感知** — 自動偵測已修改/已新增檔案並提升排名
- 🤖 **MCP Server模式** — 原生支援AI Agent整合（Claude Code/Cursor/Windsurf）
- 📊 **TUI互動式儀表板** — 即時展示檔案分佈、Frecency排行、Git狀態
- 🌏 **中文路徑優化** — 完整支援CJK字元的模糊匹配
- 📤 **多格式匯出** — 支援JSON/CSV/Markdown結果匯出
- 🚫 **零外部依賴** — 純Python標準庫實現，開箱即用

### ✨ 核心特性

| 特性 | 描述 |
|------|------|
| 🧠 **Frecency排序** | 頻率×最近性加權，指數時間衰減，越用越精準 |
| 🎯 **模糊匹配** | 子序列匹配+連續字元獎勵+詞邊界加分+Levenshtein回退 |
| 🔀 **Git感知** | 自動偵測modified/added/deleted狀態，優先展示工作檔案 |
| 🤖 **MCP協議** | JSON-RPC 2.0 over HTTP，5個工具端點，支援stdio模式 |
| 📊 **TUI儀表板** | ASCII圖表展示檔案類型分佈、Frecency排行、Git狀態概覽 |
| 📤 **多格式匯出** | JSON / CSV / Markdown，一鍵匯出搜尋結果 |
| 🌏 **CJK優化** | 中文/日文/韓文路徑完整支援 |
| 🚫 **零依賴** | 純Python標準庫，Python 3.8+即可運行 |
| ⚡ **高效能** | 智能忽略模式，跳過二進位檔案，大小限制過濾 |
| 🔧 **可配置** | JSON配置檔案，支援自訂忽略模式、閾值、衰減參數 |

### 🚀 快速開始

**環境要求：**
- Python 3.8 或更高版本
- 無需安裝任何外部依賴

**安裝方式：**

```bash
# 方式一：直接克隆運行（推薦）
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# 方式二：使用 pip 安裝
pip install .
filepulse --help
```

**基本使用：**

```bash
# 搜尋檔案名
filepulse search "main.py"

# 模糊搜尋（預設開啟）
filepulse search "mn" --fuzzy

# 搜尋檔案內容
filepulse search "def hello" --content

# 按檔案類型過濾
filepulse search "config" --type json

# Git感知搜尋（優先展示已修改檔案）
filepulse search "utils" --git

# JSON輸出
filepulse search "readme" --json

# 匯出結果
filepulse search "model" --export results.csv
```

### 📖 詳細使用指南

#### 搜尋模式

```bash
# 📁 檔案名搜尋（預設）
filepulse search "app.py"

# 📝 內容搜尋（在檔案內容中查找）
filepulse search "import flask" --content

# 🎯 精確搜尋（禁用模糊匹配）
filepulse search "exact_name" --no-fuzzy
```

#### 過濾與排序

```bash
# 按副檔名過濾
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# 按大小過濾
filepulse search "log" --min-size 1KB --max-size 10MB

# 排序方式：frecency / name / size / modified / relevance
filepulse search "main" --sort size
```

#### TUI儀表板

```bash
# 啟動互動式儀表板
filepulse dashboard

# 指定目錄和重新整理間隔
filepulse dashboard --path /your/project --refresh 5
```

#### MCP Server（AI Agent整合）

```bash
# 啟動HTTP模式MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# 啟動stdio模式（用於直接Agent整合）
filepulse mcp --stdio
```

### 💡 設計思路與迭代規劃

**設計理念：**
FilePulse-CLI的核心設計理念是「**有記憶的搜尋**」。傳統搜尋工具每次都從零開始，而FilePulse透過Frecency演算法學習使用者的使用模式——你經常存取的檔案會自動獲得更高的排名。這使得搜尋結果隨著使用越來越精準，特別適合在大型專案中日常使用。

**後續迭代計劃：**
- [ ] 增量檔案監聽（inotify/FSEvents）
- [ ] 正則表達式搜尋模式
- [ ] 檔案內容預覽功能
- [ ] 多倉庫聯合搜尋
- [ ] 搜尋歷史記錄與回溯
- [ ] Web UI儀表板
- [ ] 外掛系統（自訂搜尋後端）

### 📦 打包與部署指南

```bash
# 從原始碼安裝
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# 驗證安裝
filepulse --version
```

**相容環境：**
- Python 3.8, 3.9, 3.10, 3.11, 3.12
- Windows 10+, macOS 10.15+, Linux（主流發行版）
- 無需GPU、無需網路連線

### 🤝 貢獻指南

歡迎貢獻程式碼！請閱讀 [CONTRIBUTING.md](CONTRIBUTING.md) 了解詳情。

### 📄 開源協議

本專案基於 [MIT License](LICENSE) 開源。

---

## 🇺🇸 English

### 🎉 Introduction

**FilePulse-CLI** is a zero-dependency lightweight terminal intelligent file search engine. Inspired by the trending GitHub project [fff](https://github.com/dmtrKovalenko/fff), we built an independent pure-Python implementation with significant differentiating optimizations.

**Core Pain Points Solved:**
- 🔍 Every search starts from scratch — traditional tools (ripgrep/fzf) can't learn your usage patterns
- 🤖 AI Agents struggle with low search efficiency in large codebases, requiring multiple round trips
- 📁 Modified files in Git repositories can't be prioritized in search results
- 🌏 Poor support for CJK (Chinese/Japanese/Korean) file paths

**Differentiating Features:**
- 🧠 **Frecency Ranking** — Exponential decay algorithm combining frequency × recency, gets smarter with use
- 🎯 **Fuzzy Matching with Tolerance** — Subsequence matching + Levenshtein distance, type "mn" to find "main.py"
- 🔀 **Git-Aware** — Auto-detects modified/added files and boosts their ranking
- 🤖 **MCP Server Mode** — Native AI Agent integration (Claude Code/Cursor/Windsurf)
- 📊 **TUI Interactive Dashboard** — Real-time file distribution, Frecency rankings, Git status overview
- 🌏 **CJK Path Optimization** — Full fuzzy matching support for Chinese/Japanese/Korean characters
- 📤 **Multi-Format Export** — JSON / CSV / Markdown result export
- 🚫 **Zero External Dependencies** — Pure Python standard library, works out of the box

### ✨ Core Features

| Feature | Description |
|---------|-------------|
| 🧠 **Frecency Ranking** | Frequency × recency weighting with exponential time decay |
| 🎯 **Fuzzy Matching** | Subsequence matching + consecutive char bonus + word boundary scoring + Levenshtein fallback |
| 🔀 **Git-Aware** | Auto-detects modified/added/deleted status, prioritizes work-in-progress files |
| 🤖 **MCP Protocol** | JSON-RPC 2.0 over HTTP, 5 tool endpoints, stdio mode support |
| 📊 **TUI Dashboard** | ASCII charts for file type distribution, Frecency rankings, Git status overview |
| 📤 **Multi-Format Export** | JSON / CSV / Markdown, one-click result export |
| 🌏 **CJK Optimization** | Full Chinese/Japanese/Korean path support |
| 🚫 **Zero Dependencies** | Pure Python standard library, Python 3.8+ |
| ⚡ **High Performance** | Smart ignore patterns, binary file skipping, size limit filtering |
| 🔧 **Configurable** | JSON config file, custom ignore patterns, thresholds, decay parameters |

### 🚀 Quick Start

**Requirements:**
- Python 3.8 or higher
- No external dependencies needed

**Installation:**

```bash
# Option 1: Clone and run (recommended)
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# Option 2: Install via pip
pip install .
filepulse --help
```

**Basic Usage:**

```bash
# Search by filename
filepulse search "main.py"

# Fuzzy search (enabled by default)
filepulse search "mn" --fuzzy

# Search file contents
filepulse search "def hello" --content

# Filter by file type
filepulse search "config" --type json

# Git-aware search (prioritize modified files)
filepulse search "utils" --git

# JSON output
filepulse search "readme" --json

# Export results
filepulse search "model" --export results.csv
```

### 📖 Detailed Usage Guide

#### Search Modes

```bash
# 📁 Filename search (default)
filepulse search "app.py"

# 📝 Content search (search within files)
filepulse search "import flask" --content

# 🎯 Exact search (disable fuzzy matching)
filepulse search "exact_name" --no-fuzzy
```

#### Filtering & Sorting

```bash
# Filter by extension
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# Filter by size
filepulse search "log" --min-size 1KB --max-size 10MB

# Include hidden files
filepulse search "config" --hidden

# Sort by: frecency / name / size / modified / relevance
filepulse search "main" --sort size
```

#### TUI Dashboard

```bash
# Launch interactive dashboard
filepulse dashboard

# Specify directory and refresh interval
filepulse dashboard --path /your/project --refresh 5
```

#### MCP Server (AI Agent Integration)

```bash
# Start HTTP mode MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# Start stdio mode (for direct Agent integration)
filepulse mcp --stdio
```

**Available MCP Tools:**
- `search_files` — Search files by name with fuzzy matching
- `search_content` — Search file contents
- `get_file_info` — Get detailed file information
- `list_directory` — List directory contents
- `get_frecency_stats` — Get Frecency statistics

#### Frecency Statistics

```bash
# View search statistics
filepulse stats

# View top 20 files
filepulse stats --top 20

# JSON format output
filepulse stats --json

# Clear frecency data
filepulse stats --clear
```

### 💡 Design Philosophy & Roadmap

**Design Philosophy:**
FilePulse-CLI's core design philosophy is "**search with memory**". Traditional search tools start from zero every time, while FilePulse learns your usage patterns through the Frecency algorithm — files you access frequently automatically rank higher. This makes search results increasingly accurate over time, especially useful for daily work in large projects.

**Why These Tech Choices:**
- **Pure Python Standard Library** — Zero-dependency strategy ensures it runs in any Python environment without version conflicts or network issues
- **Frecency Algorithm** — Inspired by Firefox's Frecency implementation, using exponential decay to balance frequency and recency
- **MCP Protocol** — JSON-RPC 2.0 standard ensures compatibility with mainstream AI Agents

**Roadmap:**
- [ ] Incremental file watching (inotify/FSEvents)
- [ ] Regex search mode
- [ ] File content preview
- [ ] Multi-repository search
- [ ] Search history & recall
- [ ] Web UI dashboard
- [ ] Plugin system (custom search backends)

### 📦 Packaging & Deployment

```bash
# Install from source
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# Verify installation
filepulse --version
```

**Compatible Environments:**
- Python 3.8, 3.9, 3.10, 3.11, 3.12
- Windows 10+, macOS 10.15+, Linux (major distributions)
- No GPU or network connection required

### 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

**Quick Start:**
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes (`git commit -m 'feat: add your feature'`)
4. Push to the branch (`git push origin feature/your-feature`)
5. Open a Pull Request

### 📄 License

This project is licensed under the [MIT License](LICENSE).

---

<div align="center">

**Made with 🦞 by FilePulse Team**

**灵感来源于 [fff](https://github.com/dmtrKovalenko/fff) | Inspired by [fff](https://github.com/dmtrKovalenko/fff)**

</div>