# file-shelf

**Repository Path**: monoseven/file-shelf

## Basic Information

- **Project Name**: file-shelf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FileShelf 文件管理器

Windows 上的 WinUI 3 通用文件管理器，支持本地文件夹、FTP、显式 FTPS 和 SMB 共享。打开任意受支持的位置后，可以浏览和管理文件，并按文件名关键词与自动提取的标签进行检索。无需数据库。

## 功能

- FTP / 显式 FTPS、被动模式、UTF-8 中文文件名。可填写主机名、IP 或 `ftp://host:21/video` 地址；URL 中的端口与目录优先。
- SMB：填写 `\\server\video\电影`、`smb://server/video/电影`，或分别填写主机与共享名称。支持服务器账户、`域\用户名`、UPN 和当前 Windows 登录凭据；目录、检索及文件操作与 FTP 共用。
- 浏览当前目录的文件与文件夹，双击文件夹或按 Enter 进入；支持手动路径、上一级、起始文件夹和刷新。
- “添加到常用文件夹”会把当前目录加入左侧常用列表，点击即可快速切换。连接参数保存至 `%LOCALAPPDATA%\FileShelf\connection.json`，密码只在会话内保存。
- 文件名关键词搜索，空格分隔的多个词须同时匹配，不区分英文大小写。
- 自动扫描**起始文件夹及全部子目录**中所有文件的标签，显示文件计数；支持多标签全部匹配（AND）或任一匹配（OR），可与关键词同时使用。
- 点击标签或输入关键词，检索整个起始文件夹范围的文件，显示实际所在目录；支持一键打开所在文件夹。
- 双击媒体文件、选择后点击“播放”，或按 Enter，打开内置播放器。本地文件夹、FTP / FTPS / SMB 均可播放；远程协议使用流式读取，无需先下载整个视频。
- 播放器默认铺满窗口客户区，支持置顶小窗（画中画）和屏幕全屏。
- 上传、下载、新建文件夹、重命名文件或文件夹、确认后删除单个文件。传输显示进度并可取消。同名上传与重命名被阻止。
- 下载成功后才将临时文件替换到目标；上传先写临时名称，再移动为最终名称。
- 地址栏、刷新、扫描及文件操作集中在顶部一行图标工具栏，悬停显示功能名称；漏斗按钮可收起/展开筛选区，保留当前筛选条件。
- 标签按钮按内容宽度自动换行，完整显示标签名与文件数量。
- 相册页聚合起始根目录及全部子目录中的图片，支持按日期分组浏览、顶部粘性月份、右侧全高日期快速滚动轴、所有图片 / 相册文件夹两种模式、5 档缩略图、选择与批量下载、图片预览及右键文件操作。本地文件夹和可由 Windows 直接访问的 SMB 图片优先使用拍摄日期，读取不到时回退文件修改时间；FTP / FTPS 当前使用文件修改时间。相册直接复用现有扫描缓存，进入页面不会无条件重新扫描；展示模式、排序和缩略图大小会自动记忆。

## 标签规则

支持分类标签，例如 `远行[A=张三,李四][T=剧情][X=收藏].mp4`。类别为任意单个英文字母，不区分大小写；A 可用于演员、T 可用于类型，也可以自行使用 X、Y、Z 等类别。分类标签内多个值用英文/中文逗号、顿号或分号分隔，首尾空格自动去除，姓名中的空格保留。相同类别内的同名标签忽略大小写去重，不同类别互不混淆。

没有“字母=”前缀的 `[剧情][4K]` 独立归入“默认标签”，不归入 T。在搜索框右侧选择标签类别，下方只显示该类别的标签和文件数量。类别列表来自起始文件夹及全部子目录实际扫描到的文件；选择“默认标签”也可以筛选旧标签。每次只允许一个类别的标签生效，切换类别会清空已选标签（切回也不会恢复旧选择），保留关键词和全部/任一匹配方式。

例如 `001.山海之间.林川[纪录片][4K HDR].mkv` 解析为编号 `001`、影视名称 `山海之间`、演员 `林川`，以及 `纪录片`、`4K`、`HDR` 三个标签。

只支持英文半角方括号和多个标签块；中文括号 `【标签】`、全角方括号 `［标签］` 不提取标签，保留为文件名文本。旧格式的默认标签块内仍按空白、英文/中文逗号、顿号、分号、竖线拆分。没有标准命名的文件也完整展示并可搜索，分类标签可放在文件名任意位置。前两个点号用于分隔编号、影视名和演员；原始文件名始终保留，不自动修改远程文件。

首次打开位置时优先读取本地扫描缓存，没有可用缓存才递归扫描起始文件夹。点击“扫描标签”会重新扫描并更新缓存；普通文件管理操作只刷新当前目录，不自动触发全盘扫描。只从文件名提取标签，不从文件夹名提取。符号链接/重解析点不跟随，以避免循环；无权限或读取失败的子目录会显式显示“扫描部分完成”。取消或根目录失败不会把未完成结果显示为完整索引。

没有筛选时展示当前浏览目录的文件与文件夹；点击标签或输入关键词后，展示起始文件夹及所有子目录中的匹配文件，不混入文件夹。同名文件分别保留，通过“所在目录”区分。切换浏览目录清除筛选，但标签范围仍为起始文件夹。常用文件夹列表只负责快速跳转，不改变标签扫描范围。

文件被其他软件修改时，可点击“扫描标签”更新。索引持久保存至 `%LOCALAPPDATA%\FileShelf\cache`，并按本地根目录或远程连接参数及起始目录隔离，重启软件后仍可使用。缓存损坏时自动重新扫描；取消扫描保留原索引。大目录扫描会显示进度并支持取消。

## 构建与运行

安装 .NET 10 SDK 后，运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\dev.ps1`，即可通过菜单安装依赖、开发编译、运行、打包和生成 ZIP。

首次克隆请从 [开发入门指南](DEVELOPMENT.md) 开始，包含环境安装、依赖恢复、测试、运行和打包。已有环境的快速命令见 [编译与 ZIP 便携打包说明](BUILD.md)。

需要 Windows 10 1809 或更新系统（x64）及 .NET 10 SDK。项目使用 `net10.0-windows10.0.26100.0` 编译，同时保留 Windows 10 1809（10.0.17763.0）作为最低运行版本。使用 Visual Studio 时需 Visual Studio 2026 18.0 或更新版本并安装 WinUI / Windows 应用开发组件；也可直接使用命令行构建。

```powershell
./build.ps1
# 输出可分发目录（包含 .NET 与 Windows App SDK 运行时）
./build.ps1 -Publish
./artifacts/FileShelf/FileShelf.exe
```

首次构建需要联网还原 NuGet 包。请分发整个 `artifacts/FileShelf` 目录。可直接在 Visual Studio 打开 `FileShelf.sln`，选择 x64 启动项目 `FileShelf`。

运行核心行为、递归索引、本地文件服务及播放 HTTP 范围读取测试：

```powershell
dotnet run --project FileShelf.Tests -c Release
```

可选的本机 FTP 集成测试需要 Node.js。在两个终端分别执行：

```powershell
# 终端 1：仅监听本机的临时 FTP 服务，Ctrl+C 停止
npm.cmd ci --prefix FileShelf.Tests/ftp-fixture
npm.cmd start --prefix FileShelf.Tests/ftp-fixture
# 终端 2：检查连接、中文路径、上传/下载、重命名、删除和取消
dotnet run --project FileShelf.Tests -c Release -- --ftp
```

测试文件只写入 `FileShelf.Tests/ftp-fixture/root`，不连接外部设备。

SMB 集成测试使用已有共享中的专用测试目录，并使用当前 Windows 凭据：

```powershell
dotnet run --project FileShelf.Tests -c Release -- --smb '\\server\test-share\file-shelf-tests'
```

先创建该专用测试目录并授予读写权限。测试在其中创建独立的随机目录，检查中文文件传输、重命名、删除、取消和同名保护，然后清理自身创建的文件。本机回环共享只能验证文件操作，无法验证远端密码拒绝行为；远端测试还会尝试一个随机的不存在账号，以验证错误凭据。

## 使用

1. 选择“本地文件夹”可直接浏览本机目录；使用 FTP / SMB 时，请先在目标设备或服务器上启用相应服务并授予目录权限。
2. 选择打开方式并填写信息。FTP / FTPS 填写地址、端口、用户名、密码和起始文件夹；SMB 填写服务器与共享；本地模式直接选择文件夹。不支持 SFTP 或隐式 FTPS。FTPS 使用系统证书验证，私有 CA 需先在 Windows 中受信任。
3. 双击文件夹进入，或在地址栏输入当前来源允许的路径。点击工具栏“添加到常用文件夹”可把当前位置加入快速切换列表。
4. 等待起始文件夹扫描完成，输入关键词或点击标签筛选；多选标签时可切换并集 / 交集。
5. 双击视频文件播放，单击只选中。管理文件时可单击选中行，再点击下载、重命名或删除；上传和新建文件夹作用于路径栏所示的当前浏览目录。搜索结果中的重命名和删除作用于文件的真实所在目录。

FTP 明文传输凭据和内容，服务器支持时建议选择 FTPS。网络或权限错误显示在界面底部。操作取消后可刷新或重新打开当前位置。服务端突然断线时，可能残留 `.uploading` 临时文件，需要手动清理。

## SMB 连接

例如共享地址是 `\\192.168.1.10\video\电影`：

1. 选择“SMB（Windows 共享）”，直接将完整 UNC 地址粘贴到“服务器地址”；也可以填地址 `192.168.1.10`、共享名称 `video`、共享内起始文件夹 `/电影`。
2. 输入服务器的用户名和密码（域账户可写 `DOMAIN\user` 或 `user@domain`），或勾选“使用当前 Windows 登录凭据”。勾选后用户名和密码输入框禁用。
3. 连接后，路径栏显示完整 UNC 路径；可输入同一共享内的 UNC 路径、`smb://` 地址或 `/子目录`。要切换其他共享，请断开后重新连接。

SMB 使用 Windows 自带客户端及系统 SMB 协商，使用标准端口 445；本版主机输入支持 DNS 主机名与 IPv4。它不会自动启用旧版 SMB1，也不会更改 Windows 的来宾访问或安全策略。目标设备需要支持当前 Windows 允许的 SMB 版本与认证方式。

显式账户使用 `LOGON32_LOGON_NEW_CREDENTIALS` 和 `WindowsIdentity.RunImpersonatedAsync` 创建应用自己的出站登录上下文，不挂载盘符，也不主动断开资源管理器已有连接。选择当前 Windows 凭据时，共享访问由当前登录会话处理。应用自身不将密码写入配置文件。

Windows 的连接、目录枚举和部分文件操作是同步系统调用：它们在后台线程执行，界面保持响应；点击取消后，正在进行的系统请求可能需要等到 Windows 返回或网络超时。传输过程中按块取消，成功前保留临时文件；断网可能残留 `.part` 文件。

开发或自动化测试可设置 `FILESHELF_PROFILE_DIR` 指向独立配置目录，避免覆盖正常连接设置。

## 播放器

打开任意受支持的位置后，双击支持的媒体文件即可打开播放器。

| 模式 | 行为 | 快捷键 |
| --- | --- | --- |
| 普通窗口（默认） | 视频铺满窗口客户区，播放状态和文件名显示在系统标题栏，可调整窗口大小 | Esc |
| 小窗 | 无标题栏，默认置顶，可切换置顶，按住画面移动窗口、拖动边缘或角落调整大小 | F9，再按一次返回普通窗口 |
| 全屏 | 占满所在屏幕，隐藏窗口边框和任务栏 | F11，再按一次返回普通窗口 |

底部控件支持暂停、音量、进度和播放速度，并集成小窗、全屏两个图标按钮。每个按钮在原位置切换进入/退出图标，再次点击（或再次按对应快捷键）返回普通窗口；Esc 也可以退出其他模式。原“窗口全屏”布局成为默认布局，移除其按钮与 F10 切换。双击播放后焦点保持在播放器，重复打开同一文件会激活已有播放器。打开视频后按原始宽高比调整播放区域高度（系统标题栏和边框另计），若超出屏幕工作区则等比例缩小。关闭播放器释放媒体读取资源；关闭当前位置或主窗口也会关闭对应播放器。

控制栏四角圆角，左右及底部留出 12 像素逻辑边距，呈悬浮效果。音量位于左侧，后退 10 秒、播放/暂停、前进 10 秒位于中间，窗口模式和“更多”位于右侧；播放速度等选项收纳在“更多”中。按钮保持同一行，宽度不足时，小窗右侧只保留“恢复窗口”按钮，减少遮挡。按钮使用居中的圆角悬停背景，图标四周留白一致。

鼠标移入播放窗口底部控制区域时显示控制栏，移出后 1 秒隐藏；单击其他视频区域切换控制栏显示/隐藏，双击暂停或继续播放。双击识别间隔为 240 毫秒，第二次按下时立即响应；单击等待该间隔后执行，避免双击同时触发显隐。

小窗中按住画面移动鼠标可拖动窗口；松开且没有拖动时才识别单击或双击，避免拖动误触播放操作。底部进度条及按钮保持原有操作。

鼠标移入小窗时，右上角显示带半透明背景的置顶和关闭图标，移出后隐藏。置顶按钮可切换是否保持在其他普通窗口上方；退出小窗后恢复普通窗口的层级与尺寸，再次进入小窗会记住小窗位置、大小及置顶选择。拖动窗口边缘或四角可调整小窗大小。

拖动进度条、调整音量或选择播放速度期间，控制栏保持可用；结束操作且鼠标离开控制区域后再延时隐藏。控制区域随实际布局调整，适用于普通窗口、小窗和全屏。

播放使用 Windows MediaPlayer/MediaPlayerElement，识别 MP4、MKV、WMV、AVI、MOV、WebM、TS 等文件扩展名，实际解码取决于 Windows 已安装的编解码器。HEVC、特殊音轨或不受支持的封装会在播放器中给出错误提示，不保证每种扩展名下的全部编码都可播放。

每个播放器使用独立文件读取服务和仅监听 `127.0.0.1` 的临时媒体入口，地址包含随机令牌；按 HTTP 字节范围读取文件来支持跳转。FTP 服务器需要支持文件大小查询和 REST 断点读取；远程服务还需允许足够的同时连接数。不会建立整部影片的磁盘缓存。当前不支持 ISO 光盘导航、外挂字幕管理和播放历史。

当前版本不提供文件夹批量传输，也不会扫描起始文件夹之外的其他位置。文件夹删除会递归删除其中内容，文件列表使用虚拟化显示。

## 工程

- `FileShelf`：WinUI 3 界面、共用文件服务接口、本地 / FTP / SMB 实现、流式播放服务、播放器及连接设置。
- `FileShelf.Core`：文件名解析、递归标签索引、筛选、路径和字节范围规则，无 UI 依赖。
- `FileShelf.Tests`：无需测试框架依赖的核心行为回归测试，包括本地文件服务回归。

技术参考：[WinUI 3 非打包部署](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/unpackage-winui-app)、[FluentFTP](https://github.com/robinrodricks/FluentFTP)、[Windows 出站登录凭据](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-logonuserw)、[Windows MediaPlayer 播放](https://learn.microsoft.com/en-us/windows/apps/develop/media-playback/play-audio-and-video-with-mediaplayer)。