fzp 0.1.0__tar.gz

fzp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 r1cardohj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fzp-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: fzp
+Version: 0.1.0
+Summary: A minimal fzf clone in Python: custom fuzzy scoring + prompt_toolkit interactive UI
+Keywords: fzf,fuzzy,finder,cli,terminal
+Author: r1cardohj
+Author-email: r1cardohj <2413302357@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: click>=8.5.1
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/r1cardohj/fzp
+Project-URL: Repository, https://github.com/r1cardohj/fzp
+Project-URL: Issues, https://github.com/r1cardohj/fzp/issues
+Description-Content-Type: text/markdown
+
+# fzp
+
+A minimal [fzf](https://github.com/junegunn/fzf) clone written in Python. The first version (MVP) focuses on the **core algorithm** and a minimal usable interaction: feed it file paths or piped input, fuzzy search, press Enter to print the result.
+
+![CI](https://github.com/r1cardohj/fzp/actions/workflows/ci.yml/badge.svg)
+![PyPI](https://img.shields.io/pypi/v/fzp)
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+
+## Installation
+
+```bash
+pip install fzp
+# Or install an isolated CLI with uv:
+uv tool install fzp
+```
+
+## Quick Start
+
+```bash
+fzp                         # scan the current directory, print the selected path
+ls | fzp                    # read candidates from a pipe
+vim $(ls | fzp)             # use with command substitution
+fzp -q cli                  # start with an initial query
+fzp setup                   # install the Ctrl-T key-binding into ~/.bashrc
+```
+
+### From source
+
+```bash
+git clone https://github.com/r1cardohj/fzp.git && cd fzp
+uv sync
+
+uv run fzp                  # scan the current directory, print the selected path to stdout
+ls | uv run fzp             # read candidates from a pipe
+vim $(ls | uv run fzp)      # use with command substitution
+uv run fzp -q cli           # start with an initial query
+uv run fzp setup            # install the Ctrl-T key-binding into ~/.bashrc
+```
+
+## Shell Integration (`fzp setup`)
+
+Just like `fzf`'s key bindings, `fzp setup` writes a small block into your shell rc file
+(the file is chosen from `$SHELL`: `.bashrc` for bash, `.zshrc` for zsh) and prints a
+reminder to re-source it:
+
+```bash
+fzp setup          # write to ~/.bashrc (or ~/.zshrc) and hint: source ~/.bashrc
+fzp setup --show   # print the snippet that would be written, don't touch any file
+```
+
+After restarting your shell (or `source ~/.bashrc`), press **Ctrl-T** on the command line
+to open fzp: the selected path is pasted at the cursor, followed by a space, ready for the
+next argument. Ending the line with `^` appends the selection instead of replacing
+(`cat notes.md ^` + Ctrl-T → `cat notes.md src/fzp/cli.py`).
+
+The block is wrapped in `# >>> fzp key-bindings >>>` / `# <<< fzp key-bindings <<<`
+markers, so re-running `fzp setup` is idempotent (it replaces the old block in place),
+and deleting the block uninstalls the binding.
+
+> Only bash gets a live binding for now (`bind -x '\C-t'` via readline); on zsh the block
+> is written but inert until zsh integration lands.
+
+Key bindings:
+
+| Key | Action |
+| --- | --- |
+| `↑` / `Ctrl-P` | Move up |
+| `↓` / `Ctrl-N` / `Ctrl-J` | Move down |
+| `PgUp` / `PgDn` | Page up / down |
+| `Enter` | Confirm, print the selected item to stdout |
+| `Esc` / `Ctrl-C` / `Ctrl-D` / `Ctrl-G` | Cancel, exit code 130 |
+
+The UI is drawn inline below the current cursor, with up to 10 visible candidates. It does
+not clear the terminal or enter the alternate screen, and the picker is erased when done.
+The UI is drawn on stderr, and stdout only carries the final result, so it works seamlessly with pipes and `$( )`.
+All UI text is in English (`❯ ` prompt, `<no match>`, `1/3  (4 items)` status bar).
+Matched characters are highlighted with a **text color** (bright green + underline) — no background color or reverse video;
+the selected line is shown in bright cyan and bold.
+
+## Core Algorithm (`src/fzp/fuzzy.py`)
+
+No third-party fuzzy library is used. The approach is inspired by fzf v1:
+
+1. **Subsequence matching**: a candidate matches if the pattern's characters appear in order; case-insensitive.
+2. **Two alignments, pick the better one**: forward greedy (each character takes its earliest occurrence, favoring consecutive matches) and backward greedy (each character takes its latest occurrence, favoring matches near the end of the filename); the higher-scoring one wins.
+3. **Scoring rules**:
+
+   | Rule | Score |
+   | --- | --- |
+   | Each matched character | +16 |
+   | Match at the start of the string | +16 |
+   | Match right after a delimiter (`/ . _ - : ; , |`, space, etc.) or a camelCase / letter-digit boundary | +8 |
+   | Adjacent to the previous match | +16 |
+   | Exact case match | +2 |
+   | Each skipped gap between matches | -3, then -1 for each additional skipped character |
+
+4. **Sorting**: by score descending; ties prefer shorter items and earlier input order; an empty query preserves the input order (same as fzf).
+
+So `app` ranks `app.py` above `a_p_p.py`:
+
+```python
+>>> from fzp import fuzzy_filter
+>>> [item for item, _ in fuzzy_filter("app", ["a_p_p.py", "src/app.py", "app.py"])]
+['app.py', 'src/app.py', 'a_p_p.py']
+```
+
+## Project Structure
+
+```
+src/fzp/
+├── cli.py     # click entrypoint: pipe detection, directory scan, result output
+├── fuzzy.py   # core fuzzy matching + scoring + sorting (pure functions, easy to test)
+├── files.py   # scans the current directory when there's no piped input
+├── setup.py   # shell integration and idempotent rc-file installation
+└── tui.py     # prompt_toolkit interactive UI (query line / result list / status bar)
+tests/         # pytest: algorithm, directory scan, CLI
+scripts/pty_smoke.py  # smoke test driving a real interactive session via pty
+```
+
+## Development
+
+```bash
+uv run pytest                 # unit tests
+uv run python scripts/pty_smoke.py   # interactive smoke test (requires a pty)
+uv build                         # build the sdist and wheel
+```
+
+## Release
+
+Releases use [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/),
+so no long-lived API token is stored in GitHub. After registering the pending
+publisher described in [RELEASING.md](RELEASING.md), push a version tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release workflow runs the test matrix, validates the built packages, and
+publishes them to PyPI.
+
+## Roadmap
+
+- zsh integration (`bindkey` widget) to match the bash Ctrl-T binding
+- Multi-select (Tab to toggle, `--multi`)
+- Result preview (`--preview`)
+- Candidate caching / incremental reading for huge inputs
+- DP (Smith-Waterman) scoring to get even closer to fzf v2

fzp-0.1.0/README.md

@@ -0,0 +1,148 @@
+# fzp
+
+A minimal [fzf](https://github.com/junegunn/fzf) clone written in Python. The first version (MVP) focuses on the **core algorithm** and a minimal usable interaction: feed it file paths or piped input, fuzzy search, press Enter to print the result.
+
+![CI](https://github.com/r1cardohj/fzp/actions/workflows/ci.yml/badge.svg)
+![PyPI](https://img.shields.io/pypi/v/fzp)
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+
+## Installation
+
+```bash
+pip install fzp
+# Or install an isolated CLI with uv:
+uv tool install fzp
+```
+
+## Quick Start
+
+```bash
+fzp                         # scan the current directory, print the selected path
+ls | fzp                    # read candidates from a pipe
+vim $(ls | fzp)             # use with command substitution
+fzp -q cli                  # start with an initial query
+fzp setup                   # install the Ctrl-T key-binding into ~/.bashrc
+```
+
+### From source
+
+```bash
+git clone https://github.com/r1cardohj/fzp.git && cd fzp
+uv sync
+
+uv run fzp                  # scan the current directory, print the selected path to stdout
+ls | uv run fzp             # read candidates from a pipe
+vim $(ls | uv run fzp)      # use with command substitution
+uv run fzp -q cli           # start with an initial query
+uv run fzp setup            # install the Ctrl-T key-binding into ~/.bashrc
+```
+
+## Shell Integration (`fzp setup`)
+
+Just like `fzf`'s key bindings, `fzp setup` writes a small block into your shell rc file
+(the file is chosen from `$SHELL`: `.bashrc` for bash, `.zshrc` for zsh) and prints a
+reminder to re-source it:
+
+```bash
+fzp setup          # write to ~/.bashrc (or ~/.zshrc) and hint: source ~/.bashrc
+fzp setup --show   # print the snippet that would be written, don't touch any file
+```
+
+After restarting your shell (or `source ~/.bashrc`), press **Ctrl-T** on the command line
+to open fzp: the selected path is pasted at the cursor, followed by a space, ready for the
+next argument. Ending the line with `^` appends the selection instead of replacing
+(`cat notes.md ^` + Ctrl-T → `cat notes.md src/fzp/cli.py`).
+
+The block is wrapped in `# >>> fzp key-bindings >>>` / `# <<< fzp key-bindings <<<`
+markers, so re-running `fzp setup` is idempotent (it replaces the old block in place),
+and deleting the block uninstalls the binding.
+
+> Only bash gets a live binding for now (`bind -x '\C-t'` via readline); on zsh the block
+> is written but inert until zsh integration lands.
+
+Key bindings:
+
+| Key | Action |
+| --- | --- |
+| `↑` / `Ctrl-P` | Move up |
+| `↓` / `Ctrl-N` / `Ctrl-J` | Move down |
+| `PgUp` / `PgDn` | Page up / down |
+| `Enter` | Confirm, print the selected item to stdout |
+| `Esc` / `Ctrl-C` / `Ctrl-D` / `Ctrl-G` | Cancel, exit code 130 |
+
+The UI is drawn inline below the current cursor, with up to 10 visible candidates. It does
+not clear the terminal or enter the alternate screen, and the picker is erased when done.
+The UI is drawn on stderr, and stdout only carries the final result, so it works seamlessly with pipes and `$( )`.
+All UI text is in English (`❯ ` prompt, `<no match>`, `1/3  (4 items)` status bar).
+Matched characters are highlighted with a **text color** (bright green + underline) — no background color or reverse video;
+the selected line is shown in bright cyan and bold.
+
+## Core Algorithm (`src/fzp/fuzzy.py`)
+
+No third-party fuzzy library is used. The approach is inspired by fzf v1:
+
+1. **Subsequence matching**: a candidate matches if the pattern's characters appear in order; case-insensitive.
+2. **Two alignments, pick the better one**: forward greedy (each character takes its earliest occurrence, favoring consecutive matches) and backward greedy (each character takes its latest occurrence, favoring matches near the end of the filename); the higher-scoring one wins.
+3. **Scoring rules**:
+
+   | Rule | Score |
+   | --- | --- |
+   | Each matched character | +16 |
+   | Match at the start of the string | +16 |
+   | Match right after a delimiter (`/ . _ - : ; , |`, space, etc.) or a camelCase / letter-digit boundary | +8 |
+   | Adjacent to the previous match | +16 |
+   | Exact case match | +2 |
+   | Each skipped gap between matches | -3, then -1 for each additional skipped character |
+
+4. **Sorting**: by score descending; ties prefer shorter items and earlier input order; an empty query preserves the input order (same as fzf).
+
+So `app` ranks `app.py` above `a_p_p.py`:
+
+```python
+>>> from fzp import fuzzy_filter
+>>> [item for item, _ in fuzzy_filter("app", ["a_p_p.py", "src/app.py", "app.py"])]
+['app.py', 'src/app.py', 'a_p_p.py']
+```
+
+## Project Structure
+
+```
+src/fzp/
+├── cli.py     # click entrypoint: pipe detection, directory scan, result output
+├── fuzzy.py   # core fuzzy matching + scoring + sorting (pure functions, easy to test)
+├── files.py   # scans the current directory when there's no piped input
+├── setup.py   # shell integration and idempotent rc-file installation
+└── tui.py     # prompt_toolkit interactive UI (query line / result list / status bar)
+tests/         # pytest: algorithm, directory scan, CLI
+scripts/pty_smoke.py  # smoke test driving a real interactive session via pty
+```
+
+## Development
+
+```bash
+uv run pytest                 # unit tests
+uv run python scripts/pty_smoke.py   # interactive smoke test (requires a pty)
+uv build                         # build the sdist and wheel
+```
+
+## Release
+
+Releases use [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/),
+so no long-lived API token is stored in GitHub. After registering the pending
+publisher described in [RELEASING.md](RELEASING.md), push a version tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release workflow runs the test matrix, validates the built packages, and
+publishes them to PyPI.
+
+## Roadmap
+
+- zsh integration (`bindkey` widget) to match the bash Ctrl-T binding
+- Multi-select (Tab to toggle, `--multi`)
+- Result preview (`--preview`)
+- Candidate caching / incremental reading for huge inputs
+- DP (Smith-Waterman) scoring to get even closer to fzf v2

fzp-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "fzp"
+version = "0.1.0"
+description = "A minimal fzf clone in Python: custom fuzzy scoring + prompt_toolkit interactive UI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "fzf",
+    "fuzzy",
+    "finder",
+    "cli",
+    "terminal",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.5.1",
+    "prompt-toolkit>=3.0.53",
+]
+
+[[project.authors]]
+name = "r1cardohj"
+email = "2413302357@qq.com"
+
+[project.urls]
+Homepage = "https://github.com/r1cardohj/fzp"
+Repository = "https://github.com/r1cardohj/fzp"
+Issues = "https://github.com/r1cardohj/fzp/issues"
+
+[project.scripts]
+fzp = "fzp.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9.0.1"]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"

fzp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,44 @@
+[project]
+name = "fzp"
+version = "0.1.0"
+description = "A minimal fzf clone in Python: custom fuzzy scoring + prompt_toolkit interactive UI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["fzf", "fuzzy", "finder", "cli", "terminal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+authors = [
+    { name = "r1cardohj", email = "2413302357@qq.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.5.1",
+    "prompt-toolkit>=3.0.53",
+]
+
+[project.urls]
+Homepage = "https://github.com/r1cardohj/fzp"
+Repository = "https://github.com/r1cardohj/fzp"
+Issues = "https://github.com/r1cardohj/fzp/issues"
+
+[project.scripts]
+fzp = "fzp.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"

fzp-0.1.0/src/fzp/__init__.py

@@ -0,0 +1,9 @@
+"""fzp —— 用 Python 写的极简 fzf。
+
+核心是自研的 fuzzy 匹配打分算法，见 :mod:`fzp.fuzzy`。
+"""
+
+from .fuzzy import Match, fuzzy_filter, fuzzy_match
+
+__all__ = ["Match", "fuzzy_filter", "fuzzy_match"]
+__version__ = "0.1.0"

fzp-0.1.0/src/fzp/cli.py

@@ -0,0 +1,122 @@
+"""fzp 命令行入口。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .files import read_candidates, walk_files
+from .fuzzy import fuzzy_filter
+
+
+def _has_tty() -> bool:
+    streams = (sys.stdin, sys.stdout, sys.stderr)
+    return any(stream is not None and stream.isatty() for stream in streams)
+
+
+@click.group(
+    invoke_without_command=True,
+    no_args_is_help=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(package_name="fzp", prog_name="fzp")
+@click.option("-q", "--query", default="", help="Initial query string.")
+@click.option(
+    "--hidden/--no-hidden",
+    default=False,
+    show_default=True,
+    help="Include hidden files when scanning the current directory.",
+)
+@click.pass_context
+def main(ctx: click.Context, query: str, hidden: bool) -> None:
+    """fzp - a tiny fzf in Python: fuzzy-search files or piped input.
+
+    \b
+    Examples:
+      fzp                    # scan the current directory, print the selection
+      ls | fzp               # read candidates from a pipe
+      vim $(ls | fzp)        # hand the selection to another command
+      fzp setup              # install Ctrl-T key-binding into your ~/.bashrc
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    _run_picker(query, hidden)
+
+
+def _run_picker(query: str, hidden: bool) -> None:
+    items: list[str] = []
+    if sys.stdin is not None and not sys.stdin.isatty():
+        items = list(read_candidates(sys.stdin))
+
+    if not items:
+        items = walk_files(".", hidden=hidden)
+
+    items = [item for item in items if item.strip()]
+    if not items:
+        raise click.ClickException("No candidates found")
+
+    # 没有终端（比如在脚本里跑）时退化成纯过滤，方便测试和自动化
+    if not _has_tty():
+        for item, _ in fuzzy_filter(query, items):
+            click.echo(item)
+        return
+
+    from .tui import Picker  # 延迟导入：非交互模式不需要 prompt_toolkit
+
+    selected = Picker(items, query=query).pick()
+    if selected is None:
+        raise SystemExit(130)
+    click.echo(selected)
+
+
+@main.command()
+@click.option(
+    "--show",
+    "show_only",
+    is_flag=True,
+    help="Print the snippet that would be written, don't touch any file.",
+)
+@click.option(
+    "--rc",
+    "rc_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Write to this rc file instead of the one detected from $SHELL.",
+)
+@click.pass_context
+def setup(ctx: click.Context, show_only: bool, rc_path: Path | None) -> None:
+    """Install shell integration: press Ctrl-T on the command line to open fzp.
+
+    Writes a key-binding block (idempotent, wrapped in marker comments) into your
+    shell rc file. bash gets a real Ctrl-T binding; other shells keep the block
+    inert until their integration lands.
+    """
+    from . import setup as setup_mod
+
+    try:
+        rc = rc_path or setup_mod.detect_shell_rc()
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if show_only:
+        old = rc.read_text(encoding="utf-8") if rc.exists() else ""
+        click.echo(setup_mod.render_preview(old), nl=False)
+        return
+
+    try:
+        setup_mod.setup_key_bindings(rc)
+    except OSError as exc:
+        raise click.ClickException(f"Failed to write {rc}: {exc}") from exc
+
+    click.secho(f"✔ Shell integration written to {rc}", fg="green")
+    click.secho(
+        "  Restart your shell, or run:  "
+        + click.style(f"source {rc}", fg="cyan", bold=True),
+    )
+    click.secho("  Then press Ctrl-T on the command line to fuzzy-pick a file.", dim=True)
+
+
+if __name__ == "__main__":  # python -m fzp.cli
+    main()

fzp-0.1.0/src/fzp/files.py

@@ -0,0 +1,56 @@
+"""没有管道输入时，扫描当前目录下的文件，给 fzf 式的体验。"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+# 明显没有意义的目录，直接跳过
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "node_modules",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".idea",
+        ".gradle",
+        "target",
+        "dist",
+        "build",
+    }
+)
+
+MAX_FILES = 200_000
+
+
+def walk_files(root: str = ".", hidden: bool = False) -> list[str]:
+    """返回 root 下所有文件的相对路径，顺序稳定（目录/文件名排序）。"""
+    results: list[str] = []
+    root = os.path.abspath(root)
+
+    for current, dirs, files in os.walk(root):
+        if not hidden:
+            dirs[:] = [d for d in dirs if not d.startswith(".")]
+            files = [f for f in files if not f.startswith(".")]
+        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
+        for name in sorted(files):
+            # 统一用 POSIX 分隔符，Windows 下也输出 src/app.py。
+            path = os.path.relpath(os.path.join(current, name), root)
+            results.append(path.replace(os.sep, "/"))
+            if len(results) >= MAX_FILES:
+                return results
+
+    return results
+
+
+def read_candidates(stream) -> Iterator[str]:
+    """把 stdin 的每一行当成一个候选项。"""
+    for line in stream:
+        yield line.rstrip("\n")

fzp-0.1.0/src/fzp/fuzzy.py

@@ -0,0 +1,144 @@
+"""fzp 的核心：fuzzy 匹配 + 打分。
+
+不依赖任何第三方 fuzzy 库，算法思路参考 fzf v1：
+
+1. 子序列匹配（大小写不敏感）。
+2. 取两种对齐方式里得分更高的那个：
+   - 正向贪心：每个 pattern 字符取最早出现的位置（容易得到连续命中）；
+   - 反向贪心：每个 pattern 字符取最晚出现的位置（容易贴近文件名）。
+3. 按下面的规则打分：
+   - 每命中一个字符                    +SCORE_MATCH
+   - 命中在串首                        +BONUS_HEAD
+   - 命中在分隔符 / 驼峰 / 数字字母边界  +BONUS_BOUNDARY
+   - 与前一个命中相邻                   +BONUS_CONSECUTIVE
+   - 大小写也一致                       +BONUS_CASE_MATCH
+   - 中间跳过字符                       -PENALTY_GAP_START - n * PENALTY_GAP_EXTENSION
+
+   连续命中 + 词首命中的组合得分最高，所以 "app" 会优先命中 `app.py`，
+   而不是 `a_pp_p.py`。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+SCORE_MATCH = 16
+BONUS_BOUNDARY = SCORE_MATCH // 2  # 分隔符/驼峰之后
+BONUS_HEAD = 2 * BONUS_BOUNDARY  # 串首命中
+BONUS_CONSECUTIVE = SCORE_MATCH  # 连续命中
+BONUS_CASE_MATCH = 2  # 大小写一致
+PENALTY_GAP_START = 3  # 第一次跳字符
+PENALTY_GAP_EXTENSION = 1  # 之后每多跳一个字符
+
+# 词边界分隔符
+SEPARATORS = frozenset("/\\._-:;,| \t[](){}<>+=$#@!*?\"'`~&%")
+
+
+@dataclass(frozen=True)
+class Match:
+    """一次成功匹配：总分 + 命中字符下标（用于高亮）。"""
+
+    score: int
+    positions: tuple[int, ...]
+
+
+def _position_bonus(text: str, index: int) -> int:
+    """命中 text[index] 的“位置加成”。"""
+    if index == 0:
+        return BONUS_HEAD
+    prev, cur = text[index - 1], text[index]
+    if prev in SEPARATORS:
+        return BONUS_BOUNDARY
+    if prev.islower() and cur.isupper():  # camelCase
+        return BONUS_BOUNDARY
+    if prev.isdigit() != cur.isdigit() and cur.isalnum():  # a1 / 1a
+        return BONUS_BOUNDARY
+    return 0
+
+
+def _forward_positions(lowered: str, haystack: str) -> list[int] | None:
+    """每个字符取最早出现的位置。"""
+    positions: list[int] = []
+    start = 0
+    for char in lowered:
+        found = haystack.find(char, start)
+        if found < 0:
+            return None
+        positions.append(found)
+        start = found + 1
+    return positions
+
+
+def _backward_positions(lowered: str, haystack: str) -> list[int] | None:
+    """每个字符取最晚出现的位置（从右往左贪心）。"""
+    positions = [0] * len(lowered)
+    limit = len(haystack)
+    for i in range(len(lowered) - 1, -1, -1):
+        found = haystack.rfind(lowered[i], 0, limit)
+        if found < 0:
+            return None
+        positions[i] = found
+        limit = found
+    return positions
+
+
+def _score(text: str, pattern: str, positions: Sequence[int]) -> int:
+    score = 0
+    previous = -2
+    for index, char in zip(positions, pattern):
+        score += SCORE_MATCH
+        if index == previous + 1:
+            score += BONUS_CONSECUTIVE
+        elif previous >= 0:
+            gap = index - previous - 1
+            score -= PENALTY_GAP_START + PENALTY_GAP_EXTENSION * (gap - 1)
+        score += _position_bonus(text, index)
+        if text[index] == char:
+            score += BONUS_CASE_MATCH
+        previous = index
+    return score
+
+
+def fuzzy_match(pattern: str, text: str) -> Match | None:
+    """pattern 是 text 的子序列则返回 Match，否则 None。空 pattern 恒命中。"""
+    if not pattern:
+        return Match(0, ())
+
+    lowered = pattern.lower()
+    haystack = text.lower()
+    if len(lowered) > len(haystack):
+        return None
+
+    candidates = [
+        positions
+        for positions in (
+            _forward_positions(lowered, haystack),
+            _backward_positions(lowered, haystack),
+        )
+        if positions is not None
+    ]
+    if not candidates:
+        return None
+
+    best = max(candidates, key=lambda positions: _score(text, pattern, positions))
+    return Match(_score(text, pattern, best), tuple(best))
+
+
+def fuzzy_filter(pattern: str, items: Sequence[str]) -> list[tuple[str, Match]]:
+    """过滤 + 排序，返回 [(原始条目, Match), ...]。
+
+    空 pattern 保持输入顺序（和 fzf 一样），非空 pattern 按分数降序，
+    同分时更短、更靠前的条目优先。
+    """
+    if not pattern:
+        return [(item, Match(0, ())) for item in items]
+
+    scored: list[tuple[int, int, int, str, Match]] = []
+    for order, item in enumerate(items):
+        match = fuzzy_match(pattern, item)
+        if match is not None:
+            scored.append((-match.score, len(item), order, item, match))
+
+    scored.sort()
+    return [(item, match) for _, _, _, item, match in scored]

fzp-0.1.0/src/fzp/setup.py

@@ -0,0 +1,109 @@
+"""`fzp setup`：把 key-bindings（默认 Ctrl-T）写入 shell 配置文件。
+
+机制与 fzf 的 `key-bindings.bash` 相同：readline 收到 Ctrl-T 时调用
+`__fzp_select`，它先保存当前行内容，清空命令行后运行 fzp，选中结果
+（相对路径）再填回命令行（默认补一个空格，可用 ^ 前缀追加模式）。
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+HEADER = "# >>> fzp key-bindings >>>"
+FOOTER = "# <<< fzp key-bindings <<<"
+
+# 注意：这段脚本由 bash 执行（readline 只支持 bash），
+# 里面用条件判断保证在 zsh 下安静地不生效（zsh 用户请用 fzf 的 zsh 集成）。
+SHELL_SNIPPET = r"""# >>> fzp key-bindings >>>
+# Auto-generated by `fzp setup`. Remove this block to uninstall.
+if [ -n "$BASH_VERSION" ]; then
+  __fzp_select() {
+    local item
+    item="$(__FZP_COMMAND__)" || return
+    if [ -n "$item" ]; then
+      local prefix=${READLINE_LINE:0:READLINE_POINT}
+      local suffix=${READLINE_LINE:READLINE_POINT}
+      if [[ "$prefix" == *\^ ]]; then
+        READLINE_LINE="${prefix%\^} ${item}${suffix}"
+        READLINE_POINT=$(( ${#READLINE_LINE} - ${#suffix} ))
+      else
+        READLINE_LINE="${prefix}${item} ${suffix}"
+        READLINE_POINT=$(( ${#READLINE_LINE} - ${#suffix} ))
+      fi
+    fi
+  }
+  bind -x '"\C-t": __fzp_select'
+fi
+# <<< fzp key-bindings <<<"""
+
+
+def build_shell_snippet(command: str | None = None) -> str:
+    """生成绑定脚本；命令使用安装时的绝对路径，避免交互 shell 的 PATH 差异。"""
+    return SHELL_SNIPPET.replace(
+        "__FZP_COMMAND__", command or detect_fzp_command()
+    )
+
+
+def detect_shell_rc(home: Path | None = None) -> Path:
+    """根据 $SHELL 找到对应的 rc 文件，写不进去的 shell 直接报错。"""
+    import os
+
+    home = home or Path.home()
+    shell_path = os.environ.get("SHELL", "")
+    shell_name = Path(shell_path).name
+    candidates = {
+        "bash": home / ".bashrc",
+        "zsh": home / ".zshrc",
+    }
+    rc = candidates.get(shell_name)
+    if rc is None:
+        raise RuntimeError(
+            f"Unsupported shell {shell_path!r} (supported: bash, zsh). "
+            "You can still use fzp without shell integration."
+        )
+    return rc
+
+
+def inject_snippet(content: str, snippet: str | None = None) -> str:
+    """把 snippet 注入到内容中：已存在则整体替换（幂等），否则追加到末尾。"""
+    snippet = snippet or build_shell_snippet()
+    if HEADER in content:
+        start = content.index(HEADER)
+        end = content.index(FOOTER) + len(FOOTER)
+        return content[:start] + snippet + content[end:]
+    if content and not content.endswith("\n"):
+        content += "\n"
+    return content + "\n" + snippet + "\n"
+
+
+def setup_key_bindings(rc: Path | None = None, home: Path | None = None) -> Path:
+    """写入 rc 文件，返回 rc 路径。重复执行是幂等的。"""
+    rc = rc or detect_shell_rc(home)
+    old = rc.read_text(encoding="utf-8") if rc.exists() else ""
+    rc.write_text(inject_snippet(old), encoding="utf-8")
+    return rc
+
+
+def render_preview(content: str) -> str:
+    """预览将要写入 rc 的内容（setup --show / --preview 用）。"""
+    return inject_snippet(content)
+
+
+def detect_fzp_command() -> str:
+    """返回在交互 shell 中也能工作的 fzp 命令，并进行 shell quoting。
+
+    直接运行入口脚本时记录它的绝对路径；通过 ``python -m fzp.cli``
+    安装时则记录当前解释器，避免依赖虚拟环境是否已加入 PATH。
+    """
+    argv0 = Path(sys.argv[0])
+    if argv0.name in {"fzp", "fzp.exe"} and argv0.is_file():
+        return shlex.quote(str(argv0.resolve()))
+
+    executable = shutil.which("fzp")
+    if executable:
+        return shlex.quote(str(Path(executable).resolve()))
+
+    return f"{shlex.quote(sys.executable)} -m fzp.cli"

fzp-0.1.0/src/fzp/tui.py

@@ -0,0 +1,235 @@
+"""极简 fzf 式交互界面（prompt_toolkit）。界面文案统一用英文。"""
+
+from __future__ import annotations
+
+import sys
+from typing import Sequence
+
+from prompt_toolkit.application import Application, get_app
+from prompt_toolkit.buffer import Buffer
+from prompt_toolkit.input import create_input
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import HSplit, Layout, VSplit, Window
+from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
+from prompt_toolkit.output import create_output
+from prompt_toolkit.styles import Style
+
+from .fuzzy import Match, fuzzy_filter
+
+STYLE = Style.from_dict(
+    {
+        "prompt": "fg:#5f87d7 bold",
+        "pointer": "fg:ansibrightcyan bold",
+        # 选中的行：换颜色 + 加粗（不用背景色）
+        "current": "fg:ansibrightcyan bold",
+        # fuzzy 命中的字符：纯文字高亮（换前景色 + 加粗，不用背景色）
+        "match": "fg:ansibrightgreen bold",
+        "current match": "fg:ansibrightgreen bold underline",
+        "empty": "fg:#808080",
+        "info": "fg:#808080",
+    }
+)
+
+# 界面文案集中在这里，保持全英文
+PROMPT = "❯ "
+NO_MATCH = "<no match>"
+MAX_VISIBLE_RESULTS = 10
+
+
+def status_text(position: int, matches: int, total: int) -> str:
+    """状态栏：当前第几个/匹配数/总数。"""
+    if matches == 0:
+        return f"  0/{total}  ({total} items)"
+    return f"  {position}/{matches}  ({total} items)"
+
+
+class Picker:
+    """在候选列表里 fuzzy 搜索、上下选择、回车确认。
+
+    pick() 返回选中的条目；用户按 Ctrl-C / Esc 时返回 None。
+    """
+
+    def __init__(self, items: Sequence[str], query: str = "") -> None:
+        self.items = list(items)
+        self.results: list[tuple[str, Match]] = []
+        self.pointer = 0
+        self.offset = 0
+        self.app: Application[str] | None = None
+
+        self.query_buffer = Buffer(multiline=False)
+        self.query_buffer.text = query
+        self.query_buffer.on_text_changed += self._on_query_changed
+
+        prompt = Window(
+            FormattedTextControl([("class:prompt", PROMPT)]),
+            width=len(PROMPT),
+            height=1,
+        )
+        query_line = VSplit(
+            [prompt, Window(BufferControl(buffer=self.query_buffer), height=1)]
+        )
+        self.results_window = Window(
+            FormattedTextControl(self._render_results),
+            wrap_lines=False,
+        )
+        status = Window(
+            FormattedTextControl(self._render_status), height=1, style="class:info"
+        )
+
+        layout = Layout(HSplit([query_line, self.results_window, status]))
+        self.app = Application(
+            layout=layout,
+            key_bindings=self._key_bindings(),
+            full_screen=False,
+            erase_when_done=True,
+            mouse_support=False,
+            style=STYLE,
+            input=create_input(always_prefer_tty=True),
+            output=create_output(self._ui_stream()),
+        )
+        self._refresh()
+
+    # ------------------------------------------------------------------ 状态
+
+    def _ui_stream(self):
+        """界面画到 stderr，stdout 只留给最终结果（方便管道/命令替换）。"""
+        if sys.stderr is not None and sys.stderr.isatty():
+            return sys.stderr
+        return sys.stdout
+
+    def _visible_rows(self) -> int:
+        """候选区高度：最多 10 行，少候选时不撑出多余空白。"""
+        if not self.results:
+            return 1
+        try:
+            rows = get_app().output.get_size().rows
+        except Exception:
+            rows = 24
+        return max(1, min(len(self.results), MAX_VISIBLE_RESULTS, rows - 2))
+
+    def _on_query_changed(self, _buffer: Buffer) -> None:
+        self._refresh()
+
+    def _refresh(self) -> None:
+        self.results = fuzzy_filter(self.query_buffer.text, self.items)
+        self.pointer = 0
+        self.offset = 0
+        if self.app is not None:
+            self.app.invalidate()
+
+    def _current(self) -> str | None:
+        if not self.results:
+            return None
+        return self.results[self.pointer][0]
+
+    def _move(self, delta: int) -> None:
+        if not self.results:
+            return
+        self.pointer = min(max(self.pointer + delta, 0), len(self.results) - 1)
+        visible = self._visible_rows()
+        if self.pointer < self.offset:
+            self.offset = self.pointer
+        elif self.pointer >= self.offset + visible:
+            self.offset = self.pointer - visible + 1
+
+    # ------------------------------------------------------------------ 渲染
+
+    @staticmethod
+    def _fragments(text: str, positions: tuple[int, ...], selected: bool):
+        """把一行拆成普通字符 / 命中字符（用于高亮）。"""
+        plain = "class:current" if selected else ""
+        hit = "class:current class:match" if selected else "class:match"
+        fragments = []
+        last = 0
+        for position in positions:
+            if position > last:
+                fragments.append((plain, text[last:position]))
+            fragments.append((hit, text[position]))
+            last = position + 1
+        if last < len(text):
+            fragments.append((plain, text[last:]))
+        return fragments
+
+    def _render_results(self):
+        visible = self._visible_rows()
+
+        if not self.results:
+            return [("class:empty", f"  {NO_MATCH}")]
+
+        self.offset = max(0, min(self.offset, len(self.results) - 1))
+        if self.pointer < self.offset:
+            self.offset = self.pointer
+        elif self.pointer >= self.offset + visible:
+            self.offset = self.pointer - visible + 1
+
+        lines = []
+        end = min(self.offset + visible, len(self.results))
+        for index in range(self.offset, end):
+            text, match = self.results[index]
+            selected = index == self.pointer
+            marker = "> " if selected else "  "
+            lines.append(
+                (
+                    "class:current class:pointer" if selected else "class:pointer",
+                    marker,
+                )
+            )
+            lines.extend(self._fragments(text, match.positions, selected))
+            if index != end - 1:
+                lines.append(("", "\n"))
+        return lines
+
+    def _render_status(self):
+        return status_text(self.pointer + 1, len(self.results), len(self.items))
+
+    # -------------------------------------------------------------- 键位绑定
+
+    def _key_bindings(self) -> KeyBindings:
+        bindings = KeyBindings()
+
+        @bindings.add("down")
+        @bindings.add("c-n")
+        @bindings.add("c-j")
+        def _down(event) -> None:
+            self._move(1)
+
+        @bindings.add("up")
+        @bindings.add("c-p")
+        def _up(event) -> None:
+            self._move(-1)
+
+        @bindings.add("pageup")
+        def _page_up(event) -> None:
+            self._move(-self._visible_rows())
+
+        @bindings.add("pagedown")
+        def _page_down(event) -> None:
+            self._move(self._visible_rows())
+
+        @bindings.add("enter")
+        def _accept(event) -> None:
+            self._exit(self._current())
+
+        @bindings.add("c-c")
+        @bindings.add("c-d")
+        @bindings.add("c-g")
+        @bindings.add("escape")
+        def _abort(event) -> None:
+            self._exit(None)
+
+        return bindings
+
+    def _exit(self, result: str | None) -> None:
+        """幂等退出：快速连按退出键时避免重复调用 Application.exit() 抛异常。"""
+        assert self.app is not None
+        if self.app.future is not None and not self.app.future.done():
+            self.app.exit(result=result)
+
+    # ------------------------------------------------------------------- 入口
+
+    def pick(self) -> str | None:
+        assert self.app is not None
+        try:
+            return self.app.run()
+        except (EOFError, KeyboardInterrupt):
+            return None