ai-folder-organize

AI File Organizer for Firefly AI Folder. Analyze, categorize, tag, organize files by AI. Search files, monitor analysis progress, manage virtual directories, smart organization plans. / 萤核智能文件夹AI整理助手。AI分析、智能分类、自动打标、自动描述、文件搜索、进度监控、虚拟目录管理、整理方案生成。个人与工作文件智能管理。

与萤核智能文件夹桌面客户端通信，查询文件分析状态、搜索文件、生成整理方案、查看工作区仪表盘。

快速开始

js

// 1. 发现 API
const { baseUrl } = JSON.parse(await exec({ cmd: 'node', args: ['{baseDir}/discover.js'] }).stdout)

// 2. 查询工作区
const ws = await fetch(baseUrl + '/api/workspaces').then(r => r.json())

// 3. 查看分析进度
const progress = await fetch(baseUrl + '/api/analysis/progress').then(r => r.json())

API 发现

每次使用前必须先执行发现脚本获取 API 地址：

js

const discovery = JSON.parse(await exec({ cmd: 'node', args: ['{baseDir}/discover.js'] }).stdout)
const API = discovery.baseUrl // e.g. "http://127.0.0.1:3002"

如果发现失败（脚本退出码非 0），告知用户"萤核智能文件夹桌面客户端未运行，请先启动应用"。

API 端点

端点	方法	用途
/api/workspaces	GET	获取所有工作区
/api/analysis/queue-status	GET	获取分析队列积压状态
/api/analysis/progress	GET	获取分析进度百分比
/api/files/analysis-data	GET	查询文件分析数据
/api/files/search	GET	全文搜索文件
/api/organize/templates	GET	获取整理方案提示词
/api/organize/apply-plan	POST	应用整理方案到客户端整理页面弹窗
/api/virtual-directories	GET	查询虚拟目录列表

完整 API 参考见 REFERENCE.md。

工作流

工作区查询

用户问"我有哪些工作区？"或类似问题时：

1. fetch(API + '/api/workspaces')
2. 以自然语言列出工作区名称、路径和类型

分析进度查询

用户问"分析进度如何？"、"系统在忙吗？"时：

1. 同时调用 /api/analysis/queue-status 和 /api/analysis/progress
2. 整合系统是否空闲、队列积压数、分析进度百分比后汇报

搜索文件

用户想搜索或查找文件时：

1. fetch(API + '/api/files/search?keyword=xxx&scope=real')
2. 以列表形式展示匹配的文件名和路径

获取文件分析详情

用户想了解某个文件的分析结果时：

1. 先搜索找到文件 ID
2. fetch(API + '/api/files/analysis-data?fileId=123')
3. 展示描述、标签、评分等信息

生成整理方案（重要：需要 AI 二次推理）

用户要求"生成整理方案"、"按 xxx 视角整理"时：

1. fetch(API + '/api/organize/templates?workspaceId=1&userInstruction=xxx')
2. 接口返回 { systemPrompt, userPrompt } — 这是给你的提示词，不是直接结果
3. 关键：你就是"当前 AI 模型"。将 systemPrompt 作为 system 消息、userPrompt 作为 user 消息，在当前对话中直接推理（不要调用任何外部 LLM API，不要寻找 /v1/chat/completions 等端点，Desktop 应用不提供 LLM 代理）
4. 极其重要：只基于 userPrompt 中 API 提供的文件数据（这些文件已智能命名，可能与原始文件名不同）进行归类整理，不得自行去工作目录下列文件；即使只有 1 个文件也按此规则处理
5. 生成的目录树结构只能包含目录，不得出现文件名
6. 模型返回 3 份整理方案（含名称、视角、策略树）
7. 对方案润色后以自然语言展示给用户

应用整理方案到客户端（自定义虚拟目录弹窗）

用户对某份方案满意，想让客户端打开整理页面预览时：

1. 从之前模板推理返回的 plans 中找到用户选中的那份方案，完整保留 name / perspective / strategy 原文（不允许修改或重写策略树，strategy 已经包含完整树形文本+JSON 结构）
2. 数据编码要求：请求必须以 UTF-8 格式传输（Header 设置 Content-Type: application/json; charset=utf-8）。若在 Windows PowerShell (Invoke-RestMethod) 环境中发送，须使用 [System.Text.Encoding]::UTF8.GetBytes($json) 将 JSON 字符串转为 UTF-8 字节数组后再传输，或者对中文/Unicode 字段使用 encodeURIComponent() 编码：fetch(API + '/api/organize/apply-plan', { method: 'POST', body: JSON.stringify({ name: encodeURIComponent(name), perspective: encodeURIComponent(perspective || ''), strategy: encodeURIComponent(strategy) }) })
3. 客户端将自动切换到整理页面的"方案选择"阶段，弹出自定义虚拟目录弹窗，预填方案数据
4. 告知用户"已在整理页面打开自定义虚拟目录弹窗，请确认后继续"

仪表盘数据（返回给 AI）

用户想看总览面板、仪表盘或系统概览时（如"系统状态如何？"、"给我看仪表盘"）：

先获取 API 地址，然后并行调用以下端点收集数据，最后将结构化的数据以文本形式返回给 AI 呈现给用户：

js

const { baseUrl } = JSON.parse(await exec({ cmd: 'node', args: ['{baseDir}/discover.js'] }).stdout)
const [ws, queue, prog, vds] = await Promise.all([
  fetch(baseUrl + '/api/workspaces').then(r => r.json()),
  fetch(baseUrl + '/api/analysis/queue-status').then(r => r.json()),
  fetch(baseUrl + '/api/analysis/progress').then(r => r.json()),
  fetch(baseUrl + '/api/virtual-directories?workspaceId=1&depth=3').then(r => r.json())
])

返回的数据结构及使用说明：

• 工作区列表 ws.data：包括每个工作区的名称、路径、类型（private/speedy），数量反映管理范围
• 队列状态 queue：systemIdle 表示系统是否空闲，queueLength 表示待分析文件积压数量，currentProcessingFile 表示当前正在处理的文件名
• 分析进度 progress.analysis.progressPercentage：0~100 的百分比
• 虚拟目录（整理方案） vds.data：已有的整理方案目录结构

展示规范：将以上数据整理为结构化的文本格式，包含以下部分：

1. 系统状态：空闲/忙碌 + 队列积压数
2. 分析进度：百分比 + 进度条示意（如 ███████░░░ 70%）
3. 工作区清单：名称、类型、路径
4. 整理方案速览：方案名称列表（如有）

不要使用 HTML 渲染，直接以纯文本 + emoji 标记输出给用户。