# i-finder

**Repository Path**: coder_hanbin/i-finder

## Basic Information

- **Project Name**: i-finder
- **Description**: 为mac的finder增加类似windows的地址栏
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iFinder —— Finder 地址栏

为 macOS 访达（Finder）增加类 Windows 地址栏的原生悬浮应用。菜单栏常驻，实时跟随最前面的 Finder 窗口，在窗口顶部显示可交互的路径地址栏。

## 功能

- **地址栏跟随**：自动吸附到当前 Finder 窗口顶部（工具栏下方），随窗口移动/缩放/切换 Space 实时同步；Finder 不在前台或被遮挡时自动隐藏
- **面包屑路径**：路径分段显示（首段为卷名），任意一段可点击直接跳转；过长时左侧自动收起为「…」菜单
- **编辑模式**：点击面包屑（或按 `⌘L`）进入编辑，输入完整路径回车直达；支持 `Tab` 补全、`↑↓` 选择候选、点击候选补全
- **导航按钮**：后退（`⌘[`）、前进（`⌘]`）、上一级（`⌘↑`），每个 Finder 窗口独立记忆历史
- **效率工具**：一键复制路径（`⌘C`）、在终端打开（优先 iTerm2，其次 Terminal）、常用位置快捷菜单（桌面/文稿/下载等）
- **位置微调**：状态栏菜单可上/下微调吸附位置（±4pt），适配不同 Finder 显示偏好
- **开机自启**：菜单栏勾选「开机自动启动」（需 App 位于 /Applications）

## 系统要求

- macOS 13.0 及以上（在 macOS 26 上开发验证）
- 首次运行需授予两项系统权限（见下）

## 截图效果

![](./image/2757061c-d217-443c-bbde-466a8fe2eb36.jpg)

## 首次运行：授权

App 启动时会弹出「iFinder 权限设置」引导窗口，需要两项权限：

1. **辅助功能** —— 用于追踪 Finder 窗口位置与路径
   系统设置 → 隐私与安全性 → 辅助功能 → 打开 iFinder
2. **自动化（Apple Events）** —— 用于让 Finder 跳转目录
   首次点击跳转（或首次读路径）时，系统会弹出「iFinder 想要控制 Finder」，点击**允许**即可

授权完成后在引导窗口点「重新检测」，地址栏即出现在 Finder 窗口顶部。

## 使用

| 操作 | 效果 |
| --- | --- |
| `⌘L` | 聚焦地址栏并进入编辑（全局快捷键） |
| 点击面包屑分段 | 跳转到该级目录 |
| 编辑模式下输入 + `Tab` | 补全路径（唯一候选直接补全） |
| 编辑模式下 `↑` / `↓` | 在补全候选中移动 |
| 编辑模式下回车 | 跳转；文件路径则用默认应用打开 |
| `Esc` | 退出编辑 |
| 状态栏图标菜单 | 显示/隐藏、常用位置、位置微调、权限、开机自启、退出 |

## 构建

### 方式一：Xcode（推荐开发调试）

```bash
xcodegen generate      # 首次克隆后生成 iFinder.xcodeproj
open iFinder.xcodeproj
```

在 Xcode 中选中 iFinder scheme，⌘R 运行。签名已配置为 ad-hoc（`CODE_SIGN_IDENTITY: -`），本地运行无需开发者账号。

### 方式二：命令行脚本（无需 Xcode）

```bash
./scripts/build.sh           # 产物: build/iFinder.app
./scripts/build.sh debug     # 调试构建
```

## 工程结构

```
iFinder/
├── project.yml              # xcodegen 工程定义（改配置后重新 generate）
├── iFinder/
│   ├── Info.plist
│   └── Sources/
│       ├── main.swift                # 入口
│       ├── AppDelegate.swift         # 状态栏菜单、全局快捷键、开机自启、权限轮询
│       ├── FinderWindowTracker.swift # AX + CGWindowList 窗口追踪与路径解析
│       ├── AppleScriptRunner.swift   # Finder 路径读取 / 跳转
│       ├── PathBarController.swift   # 地址栏面板与交互逻辑
│       ├── BreadcrumbView.swift      # 面包屑视图（分段点击、溢出收起）
│       ├── SuggestionWindow.swift    # 自动补全候选弹窗
│       ├── NavigationHistory.swift   # 每窗口独立前进/后退历史
│       ├── GlobalHotkey.swift        # Carbon 全局快捷键
│       ├── OnboardingWindow.swift    # 权限引导
│       └── Favorites.swift           # 常用位置
└── scripts/
    ├── build.sh             # swiftc 命令行构建打包
    └── make_icon.swift      # 图标生成（AppKit 离屏绘制 → icns）
```

## 技术要点与已知限制

- 实现方式：**悬浮面板 + 辅助功能 API**（Finder 不开放插件接口，FinderSync 也无法注入地址栏）
- 窗口追踪：AX 通知（焦点窗口/标题/移动/缩放）驱动 + 60ms CGWindowList 轮询兜底；路径经 AppleScript 读取（防抖 120ms 合并）
- 多显示器：跨屏跟随；全屏模式下显示在工具栏下方
- 已知限制：Finder 的「最近使用/共享/废纸篓」等非普通文件夹窗口无法读取路径（保留上一路径并隐藏导航）；App 未签名公证（ad-hoc），若需分发到其他机器请配置 Developer ID 签名并公证

## 后续方向

- 自定义全局快捷键（当前固定 `⌘L`）
- 常用位置支持用户自定义增删
- 拖拽文件/文件夹到地址栏定位
- App 图标替换、深色模式微调、TestFlight 分发