CDriveShiftAI

简体中文使用说明 · 更新记录

CDriveShiftAI 是一个 Windows 桌面端磁盘整理工具，用于：

• 搜索本机所有固定磁盘中的文件名、目录名和文件夹名；
• 在用户明确指定的目录内建立本地全文索引，快速搜索文本、代码、配置与日志内容；
• 分析任意目录更可能属于哪个已安装应用、应用数据还是用户/开发数据；
• 把任意磁盘中的目录安全迁移到另一个磁盘，并在原路径建立 Windows 符号链接或目录联接；
• 记录每一次迁移，并把数据恢复到原始位置。

当前版本完全使用自研索引管线，不调用 Everything。

当前正式版本：0.0.6。安装包与便携包见 GitHub Releases。

已实现能力

全电脑名称搜索

• 自动发现本机固定磁盘和可移动本地磁盘；
• NTFS 卷优先读取 MFT 元数据，快速建立名称索引；
• 无法读取 MFT、没有相应权限或遇到其他文件系统时，自动降级为多线程目录扫描；
• 索引持久化；仅首次运行、开机后的首次启动、缓存损坏、手动刷新或距离上次全量刷新超过 24 小时时重建；
• 窗口隐藏或最小化到托盘后，名称/内容索引重活会协作式暂停，回到前台后从原阶段继续；Canvas 与 CSS 装饰动画也会停止；
• 名称索引使用只读内存映射、紧凑元数据和固定大小名称签名；多百万条记录不会在内存中复制多份完整路径；
• 使用 Windows 递归文件变更通知维护新增、删除、改名与移动结果；
• 支持多盘符、多文件类型、多个扩展名、文件大小、修改时间、完整路径、大小写、完整单词和正则表达式组合筛选；
• 同组条件按“或”匹配，不同筛选组按“且”匹配；结果可按相关度、名称、路径、类型、大小或修改时间排序；
• 结果固定展示类型、大小和修改时间。文件大小直接读取元数据；文件夹大小在结果出现后后台批量递归统计，超时或无权限时使用 ≥ 已统计大小 明确标记不完整值；
• 主题化右键菜单会高亮当前结果并显示完整目标信息，支持默认打开、资源管理器定位、打开方式、目录内搜索、归属分析、安全迁移、复制路径/名称、复制到、同名查找、扩展名过滤、重命名、属性和删除到回收站；
• 搜索模式、关键词、组合筛选、排序、内容目录范围、当前结果和选中项会自动保存到项目数据目录；切换页面或重启应用后自动恢复，并在结果栏显示恢复状态；
• 大目录创建/删除的增量更新使用共享读取与分批写入，避免长时间阻塞前台查询。

指定目录内容搜索

• 用户必须显式选择目录，不会默认扫描整台电脑的文件正文；
• 支持常见文本、代码、配置、日志、CSV、JSON、XML、脚本等格式；
• 使用本地 SQLite FTS5 trigram 全文索引，支持中文和任意正文片段；
• 内容结果展示文件大小和修改时间；
• 单文件上限 8 MB，跳过二进制文件、重解析点和无权限条目；
• 默认跳过 node_modules、.git、dist、build、target、缓存和虚拟环境等依赖或生成目录；
• 每个目录使用独立数据库，可随时手动刷新。

数据存储位置

应用不会把持久化数据写入 %APPDATA%\CDriveShiftAI。开发工作区中的配置、缓存、日志、迁移记录、名称索引和内容索引统一存放在：

<项目根目录>\.cdriveshiftai-data

便携版优先使用 PORTABLE_EXECUTABLE_DIR；如果从当前仓库的 release-ready 运行，会向上识别项目根目录并共用上述数据目录。安装版使用安装目录旁的 .cdriveshiftai-data，因此安装时应选择具有写权限的非系统盘目录。也可以通过 CDRIVESHIFTAI_DATA_DIR 环境变量指定绝对数据目录。

单文件便携版由 NSIS 在应用启动前解包，可能由打包器短暂使用 Windows 临时目录。若要求运行阶段也不产生这类系统临时文件，请直接运行 release-ready\win-unpacked\CDriveShiftAI.exe。

应用与数据归属分析

本地分析会交叉使用：

• Windows 卸载注册表与 AppX/MSIX 包中的应用名、发布者和安装位置；
• 目录路径、一级项目、扩展名分布、文件数量和空间；
• AppData、缓存、开发依赖、用户数据与应用安装目录规则。

AI 是可选的二次判断层，支持三类真实协议：

• OpenAI 兼容接口：OpenAI、DeepSeek、Moonshot/Kimi、智谱 GLM、阿里云百炼、火山方舟、腾讯混元、百度千帆、MiniMax、SiliconFlow、OpenRouter、Mistral、Groq、xAI，以及用户自定义服务；
• Anthropic 原生 Messages API；
• Google Gemini 原生 Models / GenerateContent API；
• 本地 OpenAI 兼容服务：Ollama 与 LM Studio。

设置流程为“选择厂商 → 填写或修改 Base URL 与 API Key → 从服务端获取模型 → 选择模型 → 发送最小测试对话 → 保存”。厂商与模型列表都使用应用内自绘的可搜索、限高选择器，并随三套视觉主题切换，不调用系统原生白色下拉菜单。模型输入框会显示远程列表建议；如果某个兼容服务没有实现模型列表接口，也可手动填写该服务公布的模型 ID，再用测试对话验证。URL、Key 或模型发生变化后必须重新测试，未通过测试的配置不能启用。默认关闭；默认隐私模式仅发送脱敏元数据，不发送文件正文。

磁盘目录归属地图

• 独立页面按盘符扫描根目录、Program Files、ProgramData、当前用户目录和 AppData；
• 明确区分应用安装目录、应用数据、缓存、系统组件、用户数据、开发数据和待识别目录；
• 应用归属不受盘符限制，例如可以识别“程序安装在 F 盘，但运行数据保存在 C 盘”的关系；
• 快速地图不递归读取文件正文；耗时取决于注册表、AppX 包数量和磁盘状态，当前机器冷扫描通常为数秒；
• 每个条目可以在文件资源管理器中定位、进入详细 AI 归属分析或转入安全迁移。
• 归属地图右键菜单为应用内自绘菜单，会高亮对应目录并展示分类、风险、所属应用与本地证据，材质和颜色随方块、科技、晶境主题切换。

跨磁盘安全迁移

迁移不限制源盘符，只要求目标目录位于另一个磁盘。目标目录直接使用源目录名称，不再附加盘符和完整源路径：

源：E:\Apps\Example\Data
目标基础目录：D:\Archive
实际目标：D:\Archive\Data
原路径：E:\Apps\Example\Data -> 符号链接 -> 实际目标

事务顺序：

1. 校验源目录、目标磁盘空间、保护路径和重解析点；
2. 使用 Robocopy 多线程复制到临时目录；
3. 比较文件数、目录数和总字节数；
4. 在源目录同级执行原子重命名；
5. 创建目录符号链接；权限不允许时降级为 Windows 目录联接；
6. 验证原路径真实指向目标；
7. 删除已经验证的源盘旧副本，实际释放空间；
8. 写入迁移记录。

应用异常退出时会检查未完成事务并尝试恢复。回滚会先把数据完整复制回源盘、校验并移除链接，再删除已验证不再需要的目标盘副本；同一条记录可在“恢复”和“再次迁移”之间往返，并累计迁移次数。

更新与安装

• 首次运行安装包时可自行选择安装路径；
• 使用相同 appId 的后续安装包会读取已安装项的 InstallLocation，沿用原路径覆盖升级；
• 每次打开主界面时只检查一次官方 GitHub Release，不在托盘后台循环联网；
• 更新检查、清单与下载使用 Windows 系统网络会话，自动遵循系统代理/PAC；没有代理时使用直连；
• 设置入口右侧绿点表示当前没有发现更新，红点表示存在更高版本；主题化悬浮提示会显示当前版与最新版；
• 安装版支持静默原路径升级，便携版支持原文件自替换；下载中断后按已有字节断点续传并最多自动重试三次；
• 更新包由主程序和独立更新助手分别执行 SHA-512 校验，文件大小或摘要不符时拒绝安装；
• 替换前在同一磁盘的安装目录外备份旧程序；只有新版本成功启动并回报正确版本后才删除更新包与备份，失败时自动恢复旧版本；
• 设置页使用与方块、科技、晶境主题一致的分段进度界面，显示下载量、速度、重试次数以及下载、校验、备份、替换和清理阶段；
• 覆盖安装会保留用户此前“不创建桌面快捷方式”的选择；登录时启动可单独配置为直接最小化到托盘；
• 当前安装包未使用商业 Authenticode 证书，Windows 可能显示 SmartScreen“未知发布者”提示。

全局快捷唤起

• 主窗口与独立极速搜索分别使用 Windows 全局快捷键，录入时会试注册并检查应用内重复、系统或其他程序占用；冲突配置不会保存；
• 独立极速搜索也可通过鼠标后退侧键、前进侧键或中键长按唤起，时长可在 0.5–10 秒之间配置，也可以完全关闭；
• 鼠标快捷操作使用 Windows Raw Input 被动监听，只在达到长按阈值时触发，不拦截原程序的短按前进、后退或中键行为；
• 所有快捷设置在控件失焦或选择完成后自动保存并立即生效，并提供实际唤起测试按钮。

性能与进程生命周期

• 主窗口优先完成首帧显示，全盘索引在界面可交互后延迟启动，加载内容和搜索准确率不变；
• 磁盘盘符、文件系统和空间信息合并查询并短时缓存，避免空间总览为每个盘符重复拉起 PowerShell；
• 非首页功能按需加载，降低首次启动时 Chromium 解析的 JavaScript 数量和渲染进程常驻内存；
• 像素湖境、未来中枢和月白晶境在交互期间保持流畅，闲置或失焦时自动降低背景帧率，最小化后完全暂停；
• 关闭到通知区域后释放 Chromium 渲染进程和 GPU 表面；原生增量索引、文件变化监听、托盘菜单与全局快捷键继续运行；
• 原生索引在载入和全量构建期间使用较低 Windows 进程优先级，完成后恢复正常搜索优先级；
• 托盘退出会先关闭索引通信管道并等待原生进程退出，避免 write EPIPE 主进程异常。

安全边界

• 盘符根目录、Windows 目录、系统卷信息、回收站、默认/公共用户目录和关键 Microsoft 系统数据会被硬性拦截；
• 普通应用安装子目录允许分析，但迁移会标记为高风险；
• 不跟随源目录中的符号链接或目录联接，避免循环与越界复制；
• 源盘与目标盘必须不同；
• 目标空间需要额外保留 3% 或至少 512 MB 安全余量；
• AI 不能覆盖本地系统路径硬拦截；
• API Key 只在 Electron 主进程中使用，并通过 safeStorage 调用 Windows 安全存储加密；渲染进程只能看到“是否已保存”，不能读回明文 Key；
• 模型测试会发送固定的最小文本，不包含磁盘路径、文件名或正文；测试通过后主进程签发短时一次性验证标识，只有完全相同的 URL、Key 和模型才能保存；

迁移应用安装目录前，应优先使用应用自带的“移动”或重新安装功能。包含服务、驱动、数据库、同步器或持续更新器的目录即使能通过符号链接运行，也可能被厂商更新程序按真实路径处理。

界面特效

• 像素湖境：蓝天湖水、像素远山、泥土与植被点缀，以及阶梯式交互反馈；
• 未来中枢：全息透视网格、扫描光带、HUD 环和数据节点；
• 月白晶境：明亮雾面玻璃、等高线与柔和微光。

三套效果可以在顶栏或设置中即时切换，并尊重 Windows 的“减少动画”辅助功能。

开发与构建

要求：

• Windows 10/11 x64；
• Node.js 20+；
• Rust 1.75+；
• Visual Studio 2022 C++ 工具；
• Windows SDK。构建脚本会先查找标准 Windows SDK，也兼容工作区旁已存在的 xwin SDK。

npm install
npm run dev

检查与构建：

npm run lint
npm test
npm run build:native
npm run test:native
npm run test:indexer
npm run build:app
npm run dist

安装包输出在 release-ready。当前本地安装包未使用商业代码签名证书，Windows 可能显示 SmartScreen 提示；正式发布前应配置 Authenticode 证书。

项目结构

electron/              Electron 主进程、IPC、安全存储、分析与迁移事务
native/indexer/        Rust 多磁盘名称索引、变更监听、全文索引
src/                   React 界面、纯搜索逻辑模块和三套视觉效果
scripts/               原生构建与索引联调脚本
tests/                 路径保护单元测试
docs/                  架构和安全设计

详细设计见 架构说明。