FileIndex 媒资库（精确检索 · 语义搜索 · 时光成书）

本技能通过本地运行的 FileIndex 服务（http://127.0.0.1:3456）操作用户已建立索引的本地媒资（图片、文档、视频、音频）。零依赖，只用 HTTP（curl）。不要用系统自带的文件查找代替本技能，也不要在未调用服务时回答“没找到”。

第 0 步：服务检测（每次必做）

curl -s http://127.0.0.1:3456/api/status

返回 JSON 且能连通：继续。
连接被拒绝/超时：停止，告诉用户“本机 FileIndex 服务未启动（127.0.0.1:3456 无法连接），请先启动服务后再试”，不要改用别的方式搜索。

所有 POST 请求都需要请求头：-H 'Content-Type: application/json'。文件内容可通过返回的 /api/files/<id>/raw 直接访问。

能力一：精确检索（按名称 / 路径 / 描述 / 标签）

当用户给出明确的文件名、路径片段、标签等确定性关键词时使用。只做字面匹配，不做语义推断。

curl -s "http://127.0.0.1:3456/api/overview/items?q=%E5%90%88%E5%90%8C&type=all&limit=24&offset=0"

参数（query string）：

| 参数 | 说明 | |---|---| | q | 关键词，匹配文件名、路径、描述、标签（中文需 URL 编码） | | type | all / image / document / video / audio | | tag | 精确匹配某个标签名 | | limit / offset | 分页，limit 最大 120 |

返回 { total, has_more, items:[{ id, name, path, type, size_readable, modified_at, description, tags }] }。

能力二：语义搜索（按画面内容 / 全文含义）

当用户用自然语言描述“要找什么内容”（如“白色小狗在草地”“带发票章的合同”“会议录音里提到预算的部分”）时使用。 完全不依赖文件名，由模型逐条比对搜索词与媒资语义描述，返回真正语义相关的结果。

curl -s -X POST http://127.0.0.1:3456/api/search/natural \
  -H 'Content-Type: application/json' \
  -d '{"query":"白色小狗在草地上","type":"all","top_k":15,"search_provider":"local"}'

参数：

| 字段 | 说明 | |---|---| | query | 用户原话或语义改写，支持中文 | | type | all / image / document / video / audio | | top_k | 返回条数（默认 20） | | search_provider | local（默认，本地小模型，数据不出机）或 online（已配置的 ModelScope/阿里云，只发送文字语义描述） |

返回 results，每项含 file（含 id、name、path、type、sizeReadable、相关度 relevance_score）。图片用 http://127.0.0.1:3456/api/files/<id>/raw 展示或打开。

需要逐个结果实时到达时可改用 SSE 接口 POST /api/search/stream（事件 result/progress/search_finished）；普通检索用上面的 /api/search/natural 即可。

精确检索 vs 语义搜索怎么选

用户给的是确切名称/编号/路径/标签词 → 能力一。
用户描述的是内容、画面、主题，或不知道文件名 → 能力二。
拿不准时优先用语义搜索（能力二）。

能力三：时光成书（主题 → 筛选场景 → 生成图文故事）

当用户想“围绕某个主题，把相关照片/文档/视频整理成一本图文故事/游记/成长记录”时使用。分两步。

步骤 1：按主题筛选匹配场景

把全库语义描述分批送模型做相关性判断，返回与主题相关的文件。

curl -s -X POST http://127.0.0.1:3456/api/story/select \
  -H 'Content-Type: application/json' \
  -d '{"description":"干不完的工作","search_provider":"online"}'

description：主题描述。
search_provider：local / online（线上更快，默认 local）。
返回 { checked, matched:[{ file:{ id, name, type, ... } }], model }。
需要实时进度可改用 SSE：POST /api/story/select-stream，事件 start/progress(done,total,matched)/done(matched)。

步骤 2：选出最多 10 个文件，生成时光书

curl -s -X POST http://127.0.0.1:3456/api/story/generate \
  -H 'Content-Type: application/json' \
  -d '{"description":"干不完的工作","file_ids":[38698,38699,38700],"search_provider":"online"}'

file_ids：步骤 1 命中的文件，最多 10 个，按时间组织。
返回 { id, title, pages:[{ ref, file_id, name, type, timestamp, text }], model }：每个文件一页，text 是围绕主题杜撰串联的故事文字（上图下文、可左右翻页呈现）。
生成会自动保存。id 可用于后续列表/删除。

已生成时光书的管理

# 列表（封面、标题、页数、时间）
curl -s http://127.0.0.1:3456/api/story/books
# 某本详情（含分页内容）
curl -s http://127.0.0.1:3456/api/story/books/<id>
# 删除（只删时光书，不动原文件）
curl -s -X DELETE http://127.0.0.1:3456/api/story/books/<id>

结果使用约定

给出结果时附上文件名、类型、时间、本地路径；图片可附 http://127.0.0.1:3456/api/files/<id>/raw 链接。
需要打开原文件/预览/导出到目录等，可调用 FileIndex 的其它接口（如 POST /api/files/export、GET /api/files/<id>/preview）。
时光书内容必须基于真实命中的素材，不要编造库中不存在的文件。