Lightweight Terminal Intelligent File Search Engine 轻量级终端智能文件搜索引擎
Python 3.8+ License: MIT Zero Dependencies Cross-Platform
🌐 简体中文 | 繁體中文 | 🇺🇸 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
# 启动交互式仪表盘 filepulse dashboard # 指定目录和刷新间隔 filepulse dashboard --path /your/project --refresh 5
# 启动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统计
# 查看搜索统计 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 了解详情。
快速开始:
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/your-feature) - 提交更改 (
git commit -m 'feat: add your feature') - 推送到分支 (
git push origin feature/your-feature) - 发起 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
# 啟動互動式儀表板 filepulse dashboard # 指定目錄和重新整理間隔 filepulse dashboard --path /your/project --refresh 5
# 啟動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 開源。
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
| 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 |
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
# 📁 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
# 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
# Launch interactive dashboard filepulse dashboard # Specify directory and refresh interval filepulse dashboard --path /your/project --refresh 5
# 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 matchingsearch_content— Search file contentsget_file_info— Get detailed file informationlist_directory— List directory contentsget_frecency_stats— Get 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: 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)
# 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
Contributions are welcome! Please read CONTRIBUTING.md for details.
Quick Start:
- Fork this repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'feat: add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
This project is licensed under the MIT License.