# tag-file

**Repository Path**: airms/tag-file

## Basic Information

- **Project Name**: tag-file
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 需求文档：基于 Everything 的标签化快速文件搜索工具

## 1. 核心目标
开发一款轻量级 Windows 桌面工具，以 **Everything 引擎**为底层索引，通过**文件名嵌入标签**的方式实现可移植的标签管理，并利用 **SQLite 缓存标签结构与关系**，结合 **UTOOL AI 能力**提供智能搜索与打标体验。

---

## 2. 文件命名规范（权威数据源）

- 文件采用格式：
  ```
  <原始文件名>#<标签1>#<标签2>#...#<标签N>.<扩展名>
  ```
- 示例：  
  `Q4报告#财务#2025.xlsx`  
  `设计稿#工作/项目A#UI.png`
- 规则说明：
    - 标签之间及与原始文件名之间用 `#` 分隔
    - 扩展名保留在最后，不受标签影响
    - 支持层级标签：使用 `/` 表示上下级（如 `工作/项目A`）
    - 不含 `#` 的文件视为无标签，完全兼容
    - 标签中允许中文、英文、数字、空格，禁止 Windows 非法字符（由软件自动过滤）

> ✅ 标签信息完全内嵌于文件名，确保卸载后重装仍可识别，支持跨设备迁移。

---

## 3. 标签管理系统（基于 Utool.DB）

### 3.1 数据库作用
- **非权威存储**：真实标签始终以文件名为准
- **加速与增强**：缓存标签树、父子关系、使用统计、AI 建议等

### 3.3 标签层级构建逻辑
- 启动或刷新时，扫描文件系统，解析所有 `#...#` 标签
- 对每个标签（如 `"工作/项目A"`），按 `/` 拆分为路径节点
- 自动在 `tags` 表中递归创建缺失的父/子标签，并建立父子关系
- 允许用户后期手动调整层级（如拖拽修改 parent_id）

---

## 4. Everything 集成

- 利用 Everything 的 ETP 协议或命令行接口（如 `es.exe`）获取搜索结果
- 支持原生语法：`name:"#财务#" ext:pdf`
- 应用层提供友好搜索语法转换：
    - 输入 `tag:财务` → 自动转为 `name:"#财务#"`
    - 输入 `tag:"工作/项目A"` → 转为 `name:"#工作/项目A#"`

---

## 5. UTOOL AI 集成场景

| 场景 | 功能描述 |
|------|--------|
| **智能打标** | 用户选中文件 → 调用 UTOOL AI 分析内容 → 返回推荐标签列表 → 自动重命名为 `原名#标签1#标签2.ext` |
| **语义搜索** | 用户输入自然语言（如“上季度的合同”）→ AI 转为关键词+标签 → 拼接 Everything 查询 |
| **标签联想** | 输入框中键入“proj” → AI 或本地缓存返回建议标签（如“项目A”） |

> 🔐 隐私提示：若涉及文件内容上传，需明确告知用户并提供本地模式选项。

---

## 6. 用户界面（UI）关键要求

- **文件列表显示**：仅展示“原始文件名 + 扩展名”（隐藏 `#标签#` 部分），提升可读性
- **左侧标签面板**：以树形结构展示从 `tags` 表构建的标签层级（支持折叠/展开）
- **右键菜单**：
    - “添加到标签…”（支持多选）
    - “用 AI 智能打标”
- **全局快捷键**：如 `Ctrl+Space` 呼出搜索框
- **批量操作**：支持为多个文件统一添加标签前缀

---

## 7. 同步与维护机制

- 启动时增量扫描：仅处理新增或修改时间晚于上次扫描的文件
- 定期清理 `file_tag_index` 中已不存在的文件路径
- 提供“重建标签缓存”功能（强制全盘解析）
- 文件重命名由软件执行，确保格式合规

---

## 8. 技术栈建议

- **前端**：Electron / Tauri / WinUI 3（Windows 原生优先）
- **后端逻辑**：Rust / C# / Python（任选，需支持 SQLite 和 Everything 通信）
- **Everything 通信**：ETP 协议（推荐）或 `es.exe` 命令行
- **AI 接入**：通过 HTTP 调用 UTOOL API，带超时与重试机制

---

## 9. 非功能性要求

- **轻量**：启动时间 < 1 秒，内存占用 < 100MB
- **可靠**：文件重命名前可选备份原名（如写入 NTFS 备注或日志）
- **安全**：不修改文件内容，仅重命名；支持只读模式（仅解析，不写入）
- **兼容**：支持长路径（>260 字符），适配 Windows 10/11

---

> 此工具的核心价值：**让标签随文件走，让搜索快如闪电，让 AI 为你分类。**