🦞 FilePulse-CLI

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

🌐 简体中文 | 繁體中文 | 🇺🇸 English

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

---

---

🇨🇳 简体中文

🎉 项目介绍

FilePulse-CLI 是一款零外部依赖的轻量级终端智能文件搜索引擎。灵感来源于GitHub Trending热门项目 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 或更高版本
• 无需安装任何外部依赖

安装方式：

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

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

基本使用：

# 搜索文件名
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

📖 详细使用指南

搜索模式

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

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

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

过滤与排序

# 按扩展名过滤
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仪表盘

# 启动交互式仪表盘
filepulse dashboard

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

MCP Server（AI Agent集成）

# 启动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统计

# 查看搜索统计
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包安装：

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

# 验证安装
filepulse --version

作为独立脚本使用：

# 无需安装，直接运行
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 了解详情。

快速开始：

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 开源。

---

🇹🇼 繁體中文

🎉 專案介紹

FilePulse-CLI 是一款零外部依賴的輕量級終端智能檔案搜尋引擎。靈感來源於GitHub Trending熱門項目 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 或更高版本
• 無需安裝任何外部依賴

安裝方式：

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

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

基本使用：

# 搜尋檔案名
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

📖 詳細使用指南

搜尋模式

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

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

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

過濾與排序

# 按副檔名過濾
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儀表板

# 啟動互動式儀表板
filepulse dashboard

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

MCP Server（AI Agent整合）

# 啟動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儀表板
• 外掛系統（自訂搜尋後端）

📦 打包與部署指南

# 從原始碼安裝
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 了解詳情。

📄 開源協議

本專案基於 MIT License 開源。

---

🇺🇸 English

🎉 Introduction

FilePulse-CLI is a zero-dependency lightweight terminal intelligent file search engine. Inspired by the trending GitHub project 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:

# 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:

# 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

# 📁 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

# 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

# Launch interactive dashboard
filepulse dashboard

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

MCP Server (AI Agent Integration)

# 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

# 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

# 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 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.

---

Made with 🦞 by FilePulse Team

灵感来源于 fff | Inspired by fff