内容
# 档案管理器
一款极简、跨平台的文件管理器，旨在取代访达（macOS）和Windows文件资源管理器 —— 快速、轻量级、免费且功能精简。
一个像命令调色板一样的文件管理器，而不是文件柜：优先搜索导航，零杂乱，键盘优先，即时一切。完整设计规格：[`docs/SPEC.md`](docs/SPEC.md)。
## 目标
- 快速启动，低资源占用
- 键盘优先导航，完全支持鼠标
- 跨平台：至少支持macOS和Windows（Linux作为延伸目标）
- 清洁、极简的UI —— 没有不必要的杂乱或功能蔓延
- 在每个目标平台上感觉原生
## 技术栈
- **Shell:** Wails v3（Go后端 + 原生网页视图）
- **前端：** React 18 + TypeScript + Tailwind CSS，虚拟列表/网格通过TanStack Virtual， Zustand用于UI状态，Shiki用于代码预览语法高亮
- **搜索：** Go侧模糊匹配器（`sahilm/fuzzy`）超过内存索引的主目录，按匹配质量 → 最近 → 频率排名；通过`fsnotify`进行增量更新
- **回收站：** 平台原生的回收站/回收站适配器 —— 永远不会永久删除
- **缩略图：** 图片缩略图在磁盘上解码/调整大小/缓存，由有界的Go工作线程池
## 架构
```
main.go Wails应用入口：窗口、主题、服务注册
cmd/vault-mcp/ MCP服务器入口点（Claude Desktop / Cursor / MCP客户端）
internal/core/ 平台中立：目录列表、文件操作、搜索索引、频率、fsnotify监视器、缩略图生成 —— 没有OS特定API
internal/platform/ NewTrasher（）构建标签调度共享给main.go和cmd/vault-mcp
internal/platform/darwin/ macOS适配器：回收站（~/.Trash）
internal/platform/windows/ Windows适配器：回收站（SHFileOperationW）—— 跨编译但在运行时未经验证（这里没有Windows开发/CI环境）
internal/service/ 薄Wails绑定服务（文件、搜索、固定）暴露给前端；仅调用internal/core
internal/mcp/ MCP工具服务器（9个工具）包装internal/core用于cmd/vault-mcp
frontend/ React + TypeScript + Tailwind UI；通过生成的Wails绑定（frontend/bindings/）与internal/service通信；lib/chatTools.ts +
lib/llmClient.ts + components/ChatPanel.tsx是嵌入式AI助手，调用相同的lib/vault.ts操作
```
参见[`.cursor/rules/architecture.mdc`](.cursor/rules/architecture.mdc)获取完整的边界规则（核心保持UI无关；OS特定行为保持在一个适配器中每个OS）。
## 快捷键映射
| 键 | 操作 |
|-----|--------|
| 任意位置输入 | 搜索（启动时顶部栏始终聚焦） |
| `Esc` | 清除搜索，返回首页 |
| `↑` `↓` | 在列表/搜索结果中移动选择 |
| `←` `→` `↑` `↓` | 在网格视图中移动选择 |
| `Enter` | 打开选择 |
| `Cmd/Ctrl` + `Enter`（在搜索中） | 在应用中显示结果的文件夹 |
| `Cmd/Ctrl` + `↑` | 进入父文件夹 |
| `Space` | 快速预览（图像/视频/音频/PDF/文本/代码） |
| `←` `→` `↑` `↓`（预览打开） | 移动到上一个/下一个文件 |
| `Cmd/Ctrl` + `K` | 命令面板 |
| `F2` | 重命名选择 |
| `Cmd/Ctrl` + `N` | 新文件夹 |
| `Cmd/Ctrl` + `C`（通过面板"复制"）/ `Cmd/Ctrl` + `V` | 复制 / 粘贴 |
| `Cmd/Ctrl` + `Z` | 撤销（仅重命名/移动） |
| 将文件/文件夹拖放到固定轨道 | 固定它；拖动到轨道中重新排序 |
## 非目标（MVP）
没有标签、分割窗格、云集成、网络驱动器、大规模元数据编辑、通用第三方插件系统或文件标记。参见`docs/SPEC.md` §7获取完整列表 —— 这不排除下面描述的AI集成，它是一个定义的、一方特有的功能。
## AI集成
档案管理器暴露了相同的9个文件操作（列表目录、搜索、读取文件、移动、重命名、粘贴到、新文件夹、回收站、列表固定）两种方式 —— 参见`docs/SPEC.md` §10获取设计原理：
### MCP服务器（Claude Desktop、Cursor和其他MCP客户端）
```sh
make mcp-build # 构建bin/vault-mcp
./bin/vault-mcp --root ~/Projects # 可选：限制在目录内（默认为$HOME）
./bin/vault-mcp --http :8090 # 可选：通过可流式HTTP服务而不是stdio
```
将其添加到**Claude Desktop**的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"vault": {
"command": "/absolute/path/to/bin/vault-mcp"
}
}
}
```
或添加到**Cursor**的`.cursor/mcp.json`（项目级）或`~/.cursor/mcp.json`（全局）：
```json
{
"mcpServers": {
"vault": {
"command": "/absolute/path/to/bin/vault-mcp"
}
}
}
```
文件操作仅限于`--root`（默认为$HOME）—— 路径之外被拒绝。
删除始终进入操作系统回收站，从不永久删除。
### 嵌入式聊天面板
点击顶部栏中的助手图标，然后在设置中设置提供商（Claude或ChatGPT）和API密钥。密钥存储在浏览器的`localStorage`中 —— 参见`docs/STATUS.md`获取明文存储的注意事项。
## 性能
针对`docs/SPEC.md` §8中的四个目标进行测量 —— 冷启动、200k文件时的搜索延迟、50k条目时的滚动、空闲RAM —— 在Apple M3 Pro上，生产构建：
其中三个舒适地清除了目标；搜索延迟大多清除了，但有一个最坏的情况（一个广泛的查询，限定在文件夹内，匹配每个条目） —— 参见[`docs/PERFORMANCE.md`](docs/PERFORMANCE.md)获取完整数字、注意事项和确切的生成方式（所有可复制：一个提交的Go基准测试加上三个手动程序）。
## 状态
所有十个构建顺序步骤（包括AI集成）都已实现并验证。参见[`docs/STATUS.md`](docs/STATUS.md)获取检查清单和已知限制列表（Windows运行时验证、视频缩略图、“打开方式…”、`.msi`打包、聊天API密钥存储）。
## 开发
- 设计规格和非目标：[`docs/SPEC.md`](docs/SPEC.md)
- 编码约定和工作流程位于`.cursor/rules/`（TDD、核心/UI/平台适配器边界、提交纪律、响应样式）
- 提交由AI工具准备，但始终由人类审查和执行（`.cursor/rules/git-commits.mdc`）
### 设置
```sh
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha2.117 # 一次，如果wails3不在PATH中
cd frontend && npm install && cd ..
```
### 运行
```sh
wails3 dev # 开发模式，热重载
wails3 build && ./bin/vault # 生产构建，直接运行
```
### 打包
```sh
wails3 package # bin/vault.app（临时签名）
wails3 task package:dmg # bin/vault.dmg（仅macOS，通过hdiutil）
wails3 task windows:package GOOS=windows # NSIS .exe安装程序（交叉编译；参见docs/STATUS.md）
```
### 测试
```sh
go build ./...
go vet ./...
go test -race -cover ./... # internal/core, internal/mcp, internal/service, internal/platform/darwin
GOOS=windows go build ./... && GOOS=windows go vet ./... # Windows适配器编译检查
cd frontend
npx tsc --noEmit
npx vitest run
npm run build
```
`golangci-lint`在此环境中未安装；如果您有，请运行`golangci-lint run`。
## 许可证
[MIT](LICENSE)
