快速开始

影库管家（VideoButler）是一款本地优先的视频/图片/文章管理软件，结合 AI 大模型提供智能分类、标签生成、元数据刮削、语义搜索、局域网分享等能力。所有数据保存在本地，隐私可控。按以下 4 步即可上手。

1.1 软件概述与系统要求

• 核心价值：视频、图片、文章、演员统一管理；AI 自动分类与标签；数据本地存储支持隐藏加密；内置 Web 服务器局域网多端访问；灵活接入多家 AI 平台 API。
• 系统要求：Windows 10/11 (64 位)；内存 8GB 以上（推荐 16GB）；至少 12GB 可用空间；NVIDIA GPU 可开启 AI 加速（可选）；联网后可用 AI API 与数据刮削。
• 技术架构：本地数据库存储，基础功能无需联网；AI 功能调用云端大模型 API，无需本地显卡；内置 HTTP 服务器支持跨设备浏览器访问。

1.2 安装与注册激活

1. 下载软件压缩包并解压到非中文路径目录。
2. 如遇运行问题，先安装 VC_redist.x64-14.38.33135.exe 运行库。
3. 双击 影库管家.exe 启动软件。
4. 软件首次启动显示"获取注册码"提示，点击按钮查看机器码。
5. 支付 99 元购买注册码（一机一码，永久使用，无限免费更新），在弹窗中输入注册码并点击"确定"完成激活。

1.3 首次配置

1. 激活成功后进入主界面，点击左侧菜单"基础配置"。
2. 配置 API 端口和网页端口（默认值通常无需修改，两端口不能设为同一个值）。
3. 按需设置"软件密码"（设置后启动软件和从最小化恢复时需输入密码）。
4. 点击页面右上角"保存配置"。

1.4 下载/接入 AI 大模型

软件 AI 能力（自动标签、视觉分类、语义搜索）依赖外部大模型 API。推荐使用「快速配置」一步到位。

1. 进入"基础配置"→"AI 大模型配置"卡片，在「快速配置」区域的"供应商模板"下拉选择平台（推荐 硅基流动，新用户注册有免费额度：点击领取）。
2. 选好模板后，"接口地址""语言模型""视觉模型"会自动填好推荐值；本地服务（LMStudio、Ollama）选「自定义」可留空。
3. 把平台后台创建的 API Key 粘贴到「API Key」输入框。
4. （可选）点「测试连接」用当前参数请求 /models 接口验证可用性。
5. 点「一键配置」：自动创建供应商、添加对应语言模型和视觉模型，并自动选为"当前使用模型"，完成后提示"快速配置完成"。

最小方案：只想体验文字类 AI（标签、翻译、分析），只填 API Key、视觉模型留空、点「一键配置」即可。需要视频视觉分类或截图分析时再补视觉模型。

下一步：到"分类管理"创建分类（AI 任务会读取分类列表匹配），再到"导入视频"导入文件夹即可。详见后续各章。

主页与全局功能

主页是软件的控制中心，集中展示服务状态、模型状态、后台任务，并提供全局功能入口。标题栏承载常用快捷操作。

2.1 首页概览

• 服务器地址：主页显示局域网访问地址（如 http://192.168.x.x:端口），点击"浏览器打开链接"可本机访问；同局域网手机/平板/电视用相同地址即可访问。点"运行"启动 Web 服务，按钮变为"运行中"。
• 模型状态卡：展示当前选用的语言模型、视觉模型及供应商连接状态，便于一眼确认 AI 是否就绪。
• 任务面板：主页右侧"任务"区域集中显示后台任务队列（封面生成、tag 生成、刮削、演员识别、向量索引、Bot 监听等）的运行状态、进度和剩余数量；可一键暂停所有后台任务。
• 联机计算面板：主页右侧提供"作为数据端""作为计算端"入口（详见第 13 章）。
• 发现首页：集中展示推荐内容、最近入库、灵感图片和收藏演员；视频/图片/文章列表顶部各有"为你推荐"区域。

2.2 标题栏全局功能

视频管理

视频模块是"本地视频 + 远程采集 + AI 辅助整理"一体化工作区。本章覆盖浏览、检索、播放、详情编辑、字幕隐私、批量编辑、标签与去重。

3.1 视频列表与视图

入口：左侧导航 → 视频管理。右上角三种视图切换：

• 默认列表：信息最完整，适合管理与编辑。
• 竖版封面：海报墙样式，适合浏览电影类。
• 横版封面：适合剧集、综艺或横版封面资源。
• 另有海报墙视图，分页器可切换每页数量，"显示尺寸"滑块调整卡片大小。
• 开启视频推荐且无筛选条件时，顶部显示"为你推荐"区域。

3.2 检索与筛选

3.2.1 搜索模式

3.2.2 多维筛选

• 分类/标签/热门演员/年份/视频时长（5/10/20/30/60/180 分钟以上区间）/视频来源（本地/远程）/评分（1-5 分）。
• 自定义筛选显示（v2.3.0）：点筛选栏右侧"自定义筛选"勾选常用项、关闭用不到项，配置自动记忆。
• 排序：发布时间、文件创建日期、评分、时长、文件名、随机，支持升/降序；未观看只看尚未观看内容。

3.3 播放与预览

1. 点击视频卡片即播放，默认打开内置播放器。
2. 基础配置开启"使用系统自带播放器播放视频"后，本地单集视频改用系统默认播放器；剧集和远程视频仍走内置播放器。
3. 内置播放器支持快捷键，A 键触发当前人物的快速演员检索。
4. 悬停预览：已生成预览片段时，鼠标移到封面即可播放预览。
5. 字幕标记：卡片左下角显示"字幕"标记；来源标记：远程视频带单独图标。

3.4 视频详情与 AI 工具

入口：视频卡片点"编辑"进入详情页。左侧显示封面、评分、文件路径、来源链接、文件信息、已匹配演员和简介；右侧表单编辑核心字段。

• 编辑信息：视频名称、年份、分类、标签、来源、演员、简介；本地视频支持"修改文件名"同步写回真实文件。
• 任务状态面板：详情页顶部显示刮削、封面生成、演员识别、AI 生成 Tag、预览生成等任务的运行状态、进度、耗时和结果。
• 元数据与封面：刮削（从数据源抓取标题/演员/标签/封面/简介）、生成封面（输入截取秒数）、上传封面（选本地图片或拖入替换）。
• AI 辅助整理：识别演员、重新识别（跳过缓存）、AI 生成 Tag、视频分析（抽多张截图交视觉模型生成建议标题/分类/标签/简介）、一键插入（批量写入编辑表单）。
• 其他维护：生成预览、隐藏/恢复、打开目录、下载远程视频（远程视频详情页"下载"按钮创建下载任务）。

3.5 字幕与隐私

3.5.1 生成字幕

1. 本地单集视频卡片点"字幕"按钮。
2. 选择视频语言（可自动检测，或手动指定日语/英语/韩语/中文）。
3. 按需决定是否翻译为简体中文。
4. 点"开始生成"加入后台队列自动处理。

3.5.2 视频隐藏与隐私保护

• 导入时开启"隐藏视频文件"直接进入隐私模式（视频重命名为随机 .dat 并隐藏，原始信息备份在同目录 .backup 文件）。
• 后续可在视频详情页手动"隐藏"或"恢复"。
• 在视频库删除单个视频即可恢复其文件名；移除整个导入文件夹会自动还原隐藏文件。
• 移动文件或手动改名时请谨慎，避免与数据库记录不一致。

3.6 批量编辑（v2.4.0 新功能）

入口：左侧菜单"批量编辑"进入独立窗口，勾选多个视频后在工具栏使用以下能力。

重命名归档可用字段（共 21 个）

可用修饰器（共 7 种）

• 安全字符：替换 Windows 非法字符为 _，删除零宽/方向控制符（默认开启）。
• 大写/小写、去空格、截断（默认 40 字符）、补零（默认 3 位）、前缀/后缀。

3.7 标签管理（tag-manage.html，v2.3.0）

入口：左侧菜单或主页"标签管理"。对全库标签集中维护。

1. 顶部展示标签总数、视频覆盖数等统计。
2. 支持搜索（实时筛选）、排序（自定义/按数量/按名称）。
3. 可视化标签画布支持拖动调整，全选/反选/清空选择。
4. 批量操作：合并把多个标签合并为一个（视频自动归并）；删除批量移除无用标签。

3.8 视频去重（/dedup）

1. 视频列表筛选栏点"批量编辑"旁的"视频去重"进入独立页面，基于 pHash 检测相似或重复。
2. 首次使用前先点"生成 Hash"，未生成的视频数量显示在页面顶部。
3. 点"刷新数据"查看分组结果。
4. "自动选择"默认保留体积较大的文件，自动勾选可删除项。
5. 确认后删除选中项。

图片管理

图片库支持单图、图集、漫画三种类型，提供混合/向量/全文三种搜索，以及相似与重复去重。

4.1 图片列表

4.1.1 搜索模式

• 混合搜索：结合向量与全文，默认推荐，兼顾准确率与召回率。
• 向量搜索：基于 AI 语义搜图，直接输入描述词如"蓝天白云""海边夕阳""黑色长发"。
• 全文搜索：基于标题、标签等文本字段匹配。

4.1.2 筛选与视图

• 类型筛选：全部、单图、图集、漫画四种范围。
• 分类/收藏筛选：按分类缩小范围，或只看已收藏。
• 排序：发布时间或评分，支持升/降序。
• 视图：竖版封面（等高行，快速浏览）、瀑布流（保留原始宽高比）。
• 卡片操作：悬停可直接执行喜欢、不喜欢、收藏、编辑。无筛选时顶部显示推荐图片。

4.2 图集详情

点击图集或漫画进入图集详情页，左右分栏布局：

• 左侧信息栏：封面、标题、描述、图片数、总大小、评分、浏览量、创建时间、备注；操作按钮支持收藏、编辑、删除。
• 右侧内容区：图片列表，支持网格视图（缩略图快速预览）、列表视图（含尺寸/格式/大小详细信息）、幻灯片播放、网格模式全选。

4.3 漫画（/comic/:id）

漫画是图片的 comic 类型，从图片列表点击漫画图集进入漫画详情页（路由 /comic/:id），支持章节阅读。

• 章节目录：漫画详情左侧显示章节列表、封面、话数与已读状态。
• 切换章节：点击左侧章节切换当前内容。
• 上下话导航：支持"上一话""下一话"快速翻页。

4.4 图片编辑

单张图片点编辑进入编辑页：左侧预览区（大图、类型徽章、文件信息、路径、人脸识别结果）；顶部操作栏（返回/保存/删除）；右侧四个标签页。

• 基本信息：名称、分类、图集、排序、状态、评分、收藏、备注。
• 标签：查看/删除/批量添加；AI 自动标签显示 AI 标记与置信度。
• 图片属性：宽高、格式、色彩空间、位深度、方向、缩略图路径、特征/人脸/标签标记。
• EXIF 信息：相机、镜头、曝光、ISO、GPS 等元数据查看与编辑。

4.5 图片去重（/image-dedup）

• 相似图片：查找视觉上相似的图片，可设阈值控制匹配严格程度。
• 重复图片：查找完全重复的图片文件。

1. 图片列表右上角点"图片去重"进入去重页。
2. 选择"相似图片"或"重复图片"模式。
3. 首次使用先点"生成 Hash"建立哈希数据。
4. 点"刷新数据"查看分组结果。
5. "一键选中小图"快速勾选较小或分辨率较低的图片，或手动选择。
6. 点"删除选中图片"完成清理。

文章管理

遇到喜欢的内容，单独保存图片或视频无法满足时，可存为文章——视频、图片、文本一并保存。可把微博、头条、小红书、Twitter/X 等平台内容保存到本地，对方删文或封号也不受影响。使用前请先在基础配置设置文章数据目录。

5.1 文章功能特性

5.2 文章列表管理

1. 左侧菜单"文章"进入，卡片流展示发布者头像、名称、发布时间、正文摘要、媒体预览和标签。
2. 单张媒体大图显示，多张九宫格展示，视频显示播放标记。
3. 正文较长默认折叠三行，点"全文"展开/收起。
4. 右下角提供回到顶部、刷新、回到底部快捷按钮。

搜索文章

• 混合搜索：顶部搜索框选"混合搜索"，输入自然语言或关键词按相关性返回。
• 关键词搜索：切换后按关键字查找。
• 分类筛选：顶部切换"全部""推荐"和各分类。
• 发布者筛选：按指定发布者查看某作者全部内容。

5.3 发布者管理

1. 选择发布者：右侧"文章发布者（筛选）"区域选择当前发布者；未选中时系统提示先选择再发布或采集。顶部"按发布者筛选"下拉用于列表筛选，右侧列表用于当前发文身份选择。
2. 新建发布者：右侧输入昵称，可选上传头像，点"添加"创建。
3. 删除发布者：鼠标移到右侧发布者列表项显示删除按钮，确认后不可恢复。

5.4 创建与编辑文章

1. 先在右侧选择一个发布者。
2. 页面中间输入框填写正文，支持粘贴或拖拽图片/视频到输入区。
3. 上传中媒体显示加载状态，失败可重试，已添加可单独移除。
4. 右侧"文章属性"设置分类、发布时间和标签（多个标签英文逗号分隔）。
5. 点"发布"保存为文章；编辑状态下按钮变"更新"并显示"取消"。

• 编辑文章：卡片右上角更多菜单选"编辑"，加载内容到编辑区，修改后点"更新"。
• 媒体预览：点图片或视频缩略图打开全屏预览，可切换上下张、查看底部缩略图列表、"在文件夹中显示文件"；视频用内置播放器，图片可调用系统默认程序。
• 删除："删除"仅删记录不清理媒体；"彻底删除"同步删媒体文件，不可恢复。
• 转为视频/图片：更多菜单选"转为视频"（含视频时）或"转为图片"（含图片时），选目标导入文件夹，点"确认迁移"复制到对应库，成功后文章从列表移除。

5.5 网址采集发布

输入网址直接采集文字、图片和视频，下载到本地后自动发布为文章。私密内容需登录的，先配置 Cookie。

1. 右侧选择发布者作为采集发布身份。
2. 右侧"网址采集发布"区域输入目标网址，点"采集发布"。
3. 任务创建成功提示任务编号，后台下载完成后自动发布到文章列表。
4. 如平台限制访问或需登录，先配置对应网站 Cookie。

Cookie 配置（用于私密内容）

1. 安装 Chrome 浏览器（已安装可跳过）。
2. 安装扩展"Get cookies.txt LOCALLY"：插件页面，点"添加至 Chrome"。
3. Chrome 登录目标平台账号（微博或 X），保持该网站标签页打开，点插件图标，点 Copy 复制 Cookie。
4. 回到软件，Cookie 输入框粘贴，网站输入框填对应网址（weibo.com 或 x.com），点"保存"。

5.6 文章数据目录与网页访问密码

• 数据目录：基础配置页面找到文章/图片/视频保存目录配置项，设置存储文章媒体文件的文件夹路径，点"保存配置"。必须配置，否则采集的媒体文件无法保存。
• 网页访问密码：基础配置"软件密码"输入密码保存后重启软件生效。网页访问时需先输入密码，局域网其他设备访问同样需要。忘记密码删除运行目录 pwd 文件重置。

5.7 常见问题

Q: 采集失败怎么办？

• 检查网络连接；确认链接正确可访问；私密内容需配置 Cookie；检查文章数据目录已配置且有写入权限。

Q: 上传的图片或视频一直转圈、或上传失败？

• 等待上传完成再点发布；失败媒体点重试或删除后重新粘贴/拖拽；检查磁盘空间和存储目录可写。

Q: 混合搜索没有结果或结果不理想？

• 尝试更短更明确的关键词；确认是否启用了分类或发布者筛选，必要时切回"全部"；可切换"关键词搜索"再试。

Q: 文章中的图片/视频无法显示？

• 检查文章数据目录是否存在；确认媒体文件完整下载；检查文件权限。

演员管理

演员模块从单一录入页升级为完整工作区：演员列表、演员工具、演员详情、演员编辑四部分，适合持续维护演员资料与人脸数据。

6.1 演员列表与常用操作

1. 左侧菜单"演员管理"进入列表。顶部工具：搜索框（按名称筛选）、收藏按钮（只看收藏）、刷新、识别（进工具页人脸识别）、导入演员（进工具页批量导入）。
2. 卡片形式显示，滚动到底部自动加载更多。
3. 点封面进详情页；悬停卡片可直接"编辑"或"删除"；右上角星标快速收藏/取消。

6.2 演员工具

6.2.1 批量导入演员

1. 点右上角"导入演员"。
2. 准备演员照片文件夹，按"一个文件夹对应一个演员"整理： 根文件夹/演员A名称/照片1.jpg, 照片2.jpg ...
3. 路径输入框填根目录，点"导入"。
4. 导入完成后后台提取人脸特征并显示进度，剩余数量为 0 时该批演员人脸数据准备完成。

6.2.2 人脸识别

1. "演员工具"页切换"人脸识别"标签。
2. 拖入图片或点击上传，系统先检测人脸位置再自动匹配。
3. 识别到演员后右侧显示：最佳匹配演员和其他候选、匹配视频列表、关联图片列表、相关文章列表。
4. 点结果中演员卡片直接进详情页。
5. 没找到匹配可输入名称，点"保存为新演员"创建档案。

6.3 演员详情页

顶部显示头像、姓名、别名、国籍、生日、身高、三围、罩杯、简介。下方标签页展示三类关联内容：

• 参演视频：可直接点开对应视频（v2.4.0 已修复详情页视频无法播放问题）。
• 相关图片：查看单图、图集或漫画。
• 相关文章：查看文章中的图片和视频媒体。
• 每个标签页支持"加载更多"。

合作关系图（v2.4.0）

• 以当前演员为中心，展示前 6 位合作演员节点，节点大小按合作次数渲染。
• 点击合作演员节点跳转该演员详情页；右侧列表完整展示所有合作演员及合作次数。

6.4 编辑演员与人脸维护

1. 列表卡片点"编辑"进入编辑页。
2. 可修改基础资料：姓名、别名、国籍、胸围/腰围/臀围/罩杯、个人简介、封面图（点重新选择或拖入替换）。
3. 人脸数据区域：清空人脸（删除已有数据，适合重录）、选择人脸图片（批量追加）、拖拽上传（多张拖入）。
4. 点右上角"保存"，先保存资料再统一上传新增人脸图片。

6.5 使用建议

• 识别不准时优先补充更清晰、更多角度的人脸图片，而不是只改名称。
• 录错人脸先在编辑页"清空人脸"再重新上传。
• 识别页的相关视频/图片/文章适合反向检查演员匹配是否正确。
• 视频自动演员识别依赖基础配置开关，请先确认已开启对应能力。
• v2.4.0 修复：视频人脸没匹配到演员时不再重置已手动输入的演员，手动填写信息会保留。

导入管理

本章统一说明本地视频与图片的导入方式与文件夹规则。入口：左侧导航"导入视频""导入图片"。

7.1 视频导入

7.1.1 添加本地视频文件夹

1. 左侧菜单"导入视频"，在"添加视频文件夹"区域输入路径，或直接拖拽文件夹到拖放区。
2. 点"获取数据"扫描文件夹，显示扫描结果、封面/字幕状态及是否包含特殊字符。
3. 设置导入选项：
   • 隐藏视频文件：视频重命名为随机 .dat 并隐藏（备份原始信息），保护隐私。
   • 标题包含文件夹名称：标题带上上级目录信息（如 c:/蜡笔小新/1.mp4 → "蜡笔小新_1"）。
   • 文件夹作为分类：第一级子文件夹名写入分类，不存在的自动创建。
   • 跳过最小文件(MB)：过滤太小的样片/预告/无效文件（默认 1 MB）。
   • 文件自动重命名：替换文件名禁止字符（如 ! * ' 等）为"-"。
4. 点"发布视频"完成入库，显示进度条和日志（成功/失败/已存在）。导入后自动触发已开启的任务。

7.1.2 添加剧集

独立的"添加剧集"区域，适合电视剧、综艺或系列课程。

1. 输入剧集根目录路径（如 F:\电视剧），可指定默认分类。
2. 点"发布剧集"，系统把每个子文件夹识别为一个系列，自动解析集数。

支持的集数命名示例：

S01E01 / S2 E3 / 1x03 / EP08
Season 1 Episode 2
第1集 / 第二季第三集 / 第12期
20240820 / 001 / 002
E01-E04（多集合集）

目录结构示例：

根：输入的文件夹
├── 海绵宝宝
│   ├── 第一集.mkv
│   └── 第二集.mkv

7.1.3 管理已导入文件夹

• 监控：开启后软件运行期间监听目录新增/删除变化。
• 刷新数据：重新扫描同步新增、删除、更新。
• 导出 NFO：导出当前目录视频元数据为 NFO 文件。
• 修改路径：换盘符、移机或目录搬迁后修正数据库路径。
• 删除：移除该目录对应视频；如使用了隐藏模式会尝试恢复文件状态。

7.2 图片导入

1. 左侧菜单"导入图片"，在输入框填写图片文件夹路径，或拖拽文件夹到拖拽区。
2. 选择归属分类，点"开始导入"。导入过程显示日志，图片较多时后台继续生成缩略图。

文件夹结构规则（单图与图集混合自动识别）

图片根目录/
├── photo1.jpg (识别为单图)
├── photo2.png (识别为单图)
├── 图集A/ (识别为图集)
│   ├── img01.jpg
│   └── img02.jpg
└── 图集B/ (识别为图集)
    ├── img01.jpg
    └── img02.jpg

• 根目录图片：自动识别为单图。
• 根目录子文件夹：自动识别为图集，文件夹内所有图片归入该图集。
• 隐藏目录：以 . 开头的隐藏文件夹自动跳过。
• 支持格式：JPG、PNG、GIF、WEBP、BMP 等常见格式。

已导入文件夹管理

• 查看统计：每个导入目录对应的图片数、图集数、漫画数和首次导入时间。
• 监控开关：开启后文件夹新增/删除图片自动同步数据库。
• 删除目录：移除导入记录及关联数据，删除前请确认。

分类·收藏·播放列表

本章汇总媒体分组相关功能：分类管理、收藏夹、播放列表，便于组织与回看内容。

8.1 分类管理（/category）

入口：左侧导航"分类管理"。AI 自动生成标签和分类任务会读取分类列表，根据视频标题匹配最合适分类。

1. 点"添加分类"。
2. 输入分类名称（如"动作片"），选择分类类型（视频）。
3. 点"立即创建"添加。重复添加多个分类。

8.2 收藏夹（/favorite）

入口：左侧导航媒体分组 → 收藏夹（/favorite）。可收藏视频、图片、文章，支持分类查看。

• 在视频/图片/文章卡片上点"收藏"按钮即可加入收藏夹。
• 收藏夹页支持按媒体类型（视频/图片/文章）和分类筛选查看。
• 视频列表筛选栏有"收藏筛选"，图片列表有"收藏筛选"，演员列表有"只看收藏"。

8.3 播放列表

8.3.1 创建与编辑播放列表

1. 左侧菜单"播放列表"，点"新建列表"。
2. 输入播放列表名称，点"创建"完成。
3. 在播放列表项目上点编辑按钮，可修改名称、设置封面。

8.3.2 管理播放列表内容

• 添加视频：视频列表点视频"添加"按钮，选择目标列表确认。
• 移除视频：播放列表视图点视频删除按钮确认移除（不删除原文件）。
• 播放列表预览：显示前 4 个视频缩略图，鼠标悬停可预览，显示视频总数。

8.3.3 播放列表批量编辑（v2.4.0）

对播放列表内视频批量"移动、删除、合并"。

1. 进入"播放列表"页打开目标列表。
2. 勾选视频（支持 Ctrl/Shift 多选）。
3. 底部批量操作栏选择：
   • 移动：把选中视频移动到其他播放列表。
   • 删除：从当前播放列表移除选中视频（不删除视频文件本身）。
   • 合并：把选中视频合并为一个新的播放列表。
4. 确认后立即生效，顺序自动更新。

全局搜索

语义搜索已升级为统一智能检索能力，按内容类型使用向量、全文或混合检索，覆盖视频、文章、图片三个页面，并支持台词搜索。

9.1 统一搜索栏（/search）与搜索范围

9.2 使用前准备

1. 确保视频、文章或图片数据已正常导入。
2. 进入系统设置确认搜索相关服务可用。
3. 首次搜索提示未初始化时，先构建对应内容的搜索索引。
4. 之前正常但现在异常，可尝试重建索引修复。

重建视频或文章索引

1. 进入"基础配置"页面。
2. 找到"重构视频 LanceDB"按钮，确认后重建所有视频搜索索引。
3. 如文章索引入口启用，同样方式重建文章索引。
4. 等待重建完成，返回列表页搜索测试。

9.3 台词搜索（v2.4.0）

通过字幕文件搜索视频台词位置并跳转到对应时间点，支持模糊搜索。入口：主页顶部搜索框输入台词文本（支持中英文模糊匹配）。

• 结果按台词匹配度排序，每条显示台词原文、所在视频、时间码。
• 点结果跳转到该视频对应时间点直接播放。

9.4 搜索示例与建议

• 优先使用自然语言短句，不必强行拆成零碎关键词。
• 兼顾召回率和准确度优先选"混合搜索"。
• 只想精确词匹配切换"关键词搜索"或"全文搜索"。
• 视频和文章叠加过多筛选条件会回到普通列表筛选逻辑，不再走纯语义搜索。

9.5 常见问题

Q: 语义搜索没有结果？

• 确认当前页面已有对应类型数据；尝试更短更直接的自然语言描述；检查索引是否已初始化，必要时执行重构；确认未被额外筛选条件限制。

Q: 搜索结果不准确？

• 补充或修正标题、简介、标签、摘要等信息；优先尝试"混合搜索"；同一意思换几种表达测试；索引长期未更新可尝试重建。

Q: 为什么图片库能选"向量搜索"，视频和文章没有？

• 这是新版页面设计差异；视频和文章主打"混合搜索"和"关键词搜索"；图片额外开放纯向量模式便于更强语义搜图。

Q: 提示"语义搜索服务未初始化，请先构建索引"怎么办？

• 进入基础配置执行对应内容的索引重建，等待构建完成后重新搜索；仍失败检查后端搜索服务是否正常运行。

视频采集

视频采集位于"导入视频"页面，用于接入苹果 CMS 资源站，把远程视频信息同步到软件。采集到的是远程视频记录和播放地址；如需保存到本地，还需在视频详情页单独创建下载任务。

10.1 使用前准备

采集规则本身不依赖本地目录即可入库；只有准备下载远程视频到本地时才需配置下载目录。

1. 左侧菜单"系统设置"。
2. 找到"采集视频下载目录"配置项，至少添加一个启用状态的保存目录。
3. 如需缓存采集封面图，开启"缓存采集视频封面图"并设置封面保存地址。
4. 点"保存"。

10.2 添加采集接口

1. 左侧菜单"导入视频"，找到"添加采集接口"区域。
2. "采集 API 地址"填写站点地址，必须以 http:// 或 https:// 开头。
3. 推荐填站点根地址（如 http://www.xxxx.com），不要手动补 /api.php/provide/vod/ 等固定路径。
4. "规则名称"可选，便于识别；"采集源标识"可选，不填默认用域名作标识。
5. 点"高级选项"可设调度方式、执行时间、并发页面数、并发详情数，及是否启用增量采集。
6. 确认后点"添加采集"保存规则。

10.3 采集接口管理

• 启用/禁用：开关切换；禁用后停止自动采集，当前任务也会同步停止。
• 绑定分类（重要）：点规则右侧"绑定分类"，系统读取远程分类列表弹出绑定窗口，对每个远程分类点"绑定"选本地分类，可"解绑"取消，全部设置后点"生成绑定"保存。
• 自动绑定：只绑定名称相同的分类，不新增本地分类。
• 自动绑定并创建：名称相同的直接绑定；本地不存在时自动创建分类后再绑定。
• 测试：检查当前规则能否正常访问接口。
• 启动采集：按当前规则配置执行，通常用于日常增量采集。
• 全部采集：执行一次全量采集，适合首次接入或重扫全部远程数据。
• 停止：手动终止当前正在运行的采集任务。

10.4 执行方式

• 手动规则：仅在点"启动采集"或"全部采集"时执行。
• 定时规则：规则启用且调度方式为"每小时/每天/每周"时按设置自动执行。
• 增量采集：适合日常更新，只抓取最近一段时间内的新增内容。
• 全量采集：适合首次接入、规则调整后重扫、或怀疑远程数据漏采时使用。

10.5 下载远程视频到本地

采集成功后远程视频出现在视频库。进入该视频详情页点"下载"按钮，系统创建下载任务并写入"采集视频下载目录"中的启用目录。

10.6 常见问题

Q1: 采集失败怎么办？

• 先点规则右侧"测试"确认接口可访问；检查地址是否以 http:// 或 https:// 开头；确认填的是站点地址，不要重复拼接 /api.php/provide/vod/；确认资源站没维护、封禁或网络不可达。

Q2: 视频下载失败怎么办？

• 确认"系统设置"已添加至少一个启用状态的"采集视频下载目录"；检查磁盘空间和写入权限；确认该远程视频播放地址仍有效。

Q3: 采集的视频如何分类？

• 优先在"分类管理"准备好本地分类；然后在采集规则用"绑定分类"或"自动绑定"；想省事可直接"自动绑定并创建"。

Q4: "启动采集"和"全部采集"有什么区别？

• "启动采集"按当前规则执行，通常用于日常增量更新；"全部采集"重新全量扫描远程数据，耗时更长但覆盖更完整。首次接入新站点建议先做一次"全部采集"，后续再用普通"启动采集"。

基础配置

基础配置是软件正常运行的关键，包括端口、AI、刮削、目录、Telegram Bot、WebDAV、任务、重置、备份等。入口：左侧导航"基础配置"。

11.1 基本配置

• 端口配置：API 端口建议保持默认，冲突时再改，改后可点"检查端口"确认；网页端口用于浏览器访问；两端口不要设成同一个值。
• 软件密码：输入新密码点"保存配置"生效；清空输入框再保存可取消密码；忘记密码删除运行目录 pwd 文件重启软件重置。
• 视觉模型配置：视频帧数控制精度与速度平衡；分辨率控制送审图片宽度，过大增加耗时过小影响识别；附加提示词适合填写希望模型长期遵循的补充要求。这些参数只有在"AI 大模型配置"选好当前视觉模型后才生效。

11.2 AI 大模型配置

采用「快速配置」+「供应商管理」模式。配置思路：① 快速配置选模板 + API Key → ② 一键配置自动创建供应商和模型 → ③ 当前使用模型确认选用 → ④ 高级用户到供应商管理手动增删改。

11.2.1 支持的供应商模板

11.2.2 快速配置操作步骤

1. 选择供应商模板：下拉选目标平台（推荐 硅基流动，新用户注册有免费额度：点击领取）。
2. 确认自动填充："接口地址""语言模型""视觉模型"自动填上推荐值。
3. 填写 API Key：把平台后台创建的密钥粘贴到"API Key"输入框；本地服务（LMStudio、Ollama 兼容接口）选"自定义"可留空。
4. （可选）测试连接：点"测试连接"用当前参数请求 /models 接口，成功提示"API 连接测试成功"并显示可用模型数，401/403 多半是 Key 无效或过期。
5. 一键配置：点"一键配置"自动创建供应商、添加对应语言模型和视觉模型，并自动选为"当前使用模型"。

11.2.3 当前使用模型

• 语言：用于标签生成、文本分析、翻译、刮削内容整理等文字类任务。
• 视觉：用于视频截图分析、图片内容理解、视频视觉分类等需要识别画面的任务。
• 点任一卡片弹出"选择模型"弹窗，从已有供应商和模型里挑选；带"使用中"标签的为当前正在调用的模型。

11.2.4 供应商管理（高级）

快速配置模板不能满足需求时（如接本地 LMStudio、换模型名、禁用某模型），可在"供应商管理"手动维护。

• 添加供应商：点"添加供应商"，填供应商 ID（英文小写，如 siliconflow）、供应商名称、接口地址（如 https://api.siliconflow.cn/v1）、API Key，点"保存"。
• 添加模型：供应商卡片点"添加模型"，选"模型用途"（语言/视觉），填模型真实名称（如 deepseek-ai/DeepSeek-V3、Qwen/Qwen2.5-VL-32B-Instruct、gpt-4o），其他参数默认。
• 选用：模型行点"选用"弹窗选"语言"或"视觉"，确认后出现在"当前使用模型"。
• 编辑：可改模型名称、视觉能力开关、是否启用。
• 删除：删除模型记录；如正被"当前使用模型"使用需先切换。
• 测试：供应商卡片右上角"测试"验证接口是否可用。
• 编辑供应商：点"编辑"改名称、接口地址、API Key、启用状态，改后点"保存修改"。

配置示例（以硅基流动为例）

1. 进入"基础配置"→"AI 大模型配置"卡片。
2. "供应商模板"选 硅基流动，接口地址自动填 https://api.siliconflow.cn/v1，语言模型 deepseek-ai/DeepSeek-V3.2，视觉模型 Qwen/Qwen3-VL-32B-Instruct。
3. 填 API Key，（可选）点"测试连接"确认可用。
4. 点"一键配置"，成功后到"当前使用模型"确认语言/视觉模型已显示。
5. 返回"任务配置"启用需要的自动任务，AI 功能即可生效。

11.3 StashDB 元数据刮削

StashDB 是第三方元数据数据库，用于刮削视频详细信息（标题、演员、标签、封面、简介等），只能刮削本地视频。

1. 在 https://docs.stashapp.cc/metadata-sources/stash-box-instances/ 申请。JAVStash 需要加入 Discord 获取邀请码，其他的邀请码在链接里面。
2. 点"添加配置"，输入 GraphQL Endpoint（API 地址，如 https://stashdb.org/graphql）和 API key（从 StashDB 官网申请）。
3. 点"测试"验证配置。支持添加多个刮削源。
4. 注意：支持 JAVStash、PMV Stash、StashDB，不支持 ThePornDB。部分站点需科学上网才能访问。
5. 元数据刮削器配置的邀请码（网上公开，失效请自行申请）：
   • JAVStash：32addee3-9604-4e0f-a41c-7d8507342540
   • PMV Stash：07ead09e-3c50-46db-87d0-5afadf7ab413
   • StashDB：8a161d1d-1027-4ffa-afc3-ef55abbafb28

• 自动刮削：开启"刮削视频元数据"任务，系统自动获取视频详细信息（标题、演员、标签、封面、简介），支持翻译刮削内容为中文。

11.4 采集与文章目录配置

• 采集视频下载目录：下载采集视频时保存本地目录地址，支持添加多个目录并启用/禁用。缓存采集视频封面图可将采集到的视频封面图缓存到本地磁盘，可设保存地址。
• 文章视频图片保存目录：发布文章时把文章里的图片和视频保存在文章数据目录。目录替换可把文章里的图片和视频目录替换成新文件夹目录。

11.5 Telegram Bot 配置

配置后可通过 Telegram 机器人自动接收和下载媒体文件，发送给 Bot 的图片、视频会自动下载到指定目录，并可自动发布到文章系统。

配置步骤

1. Telegram 中搜索 @BotFather，发 /newbot 创建新机器人获取 Bot Token（格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz）。
2. 访问 my.telegram.org，登录后点"API development tools"，在"Create new application"填应用信息（App title、Short name、Platform 选 Desktop），创建后获取 api_id（数字）和 api_hash（字符串）。
3. 在软件"基础配置"→"Telegram Bot 配置"区域填写信息（见下表），点"保存配置"。
4. 在"自动启动"开关切换为"启用"后再次"保存配置"，软件启动时自动开启监听。

网络代理说明（重要）

• 推荐方式：代理软件启用"系统代理"，软件保持"自动检测代理"启用，保存后用"测试连接"检查连通；网络环境变化时 Telegram 会自动重连。
• 自动检测优先级：① 系统代理 → ② 检测到的本地代理地址 → ③ 手动填写的代理地址（关闭自动检测后使用）。
• 手动填写场景：代理软件没写入系统代理但提供本地 HTTP/SOCKS5 端口；希望 Telegram 固定走指定代理；自动检测未识别到可用代理。

11.6 WebDAV 静态服务配置

WebDAV 服务提供视频、图片等资源的统一 HTTP 访问，局域网设备可直接访问。

• 启用服务：开关 WebDAV 服务。
• 服务端口：默认 8090。
• 自动启动：软件启动时自动启动 WebDAV 服务。
• 挂载文件夹：将本地文件夹挂载到 WebDAV 目录下，通过 /dav/ 路径直接访问。名称不能为"视频"、"图片"等保留名称。

11.7 任务配置

在任务配置区域可开启或关闭各种自动处理功能。配置保存后，相关任务会在后台自动运行。

• 生成视频封面：启用后自动为视频生成封面图（保存为视频同目录、同文件名 .picu）。
• 视频截取第几秒：设置封面截取时间（默认 3 秒）。
• 开启自动生成 tag 和分类：AI 根据视频标题生成标签和分类建议（读取分类列表匹配）。
• 视频分类失败后使用视觉模型分类：文件名无意义时通过大模型 API 视觉分析视频截图智能判断分类，消耗 API token，无需本地显卡。
• 刮削视频元数据：从已配置数据源抓取元数据（不能与自动生成 tag 同时运行）。

11.8 重置失败任务

• 重置 Tag 和分类任务：重置所有失败的和没获取到 tag 的任务，已完成的不受影响。
• 重置刮削任务：重置所有已刮削过但演员、Tag、简介都没数据的任务，也可全部重置。
• 重置演员识别任务：重置所有没识别到演员的任务。
• 重新识别图片演员：演员数据更新后可重新识别所有图片或仅重置未匹配的图片。
• 重构视频 LanceDB：重建视频 LanceDB 向量数据库索引，用于修复搜索功能异常。

11.9 数据备份与恢复

• 数据库备份：所有数据存储在软件目录的 db 文件夹中，支持手动备份整个 db 文件夹，建议定期备份重要数据。
• 配置备份：软件配置存储在运行目录 db 文件中。软件升级或移到其他地方请先备份 db 目录，重装软件后可恢复原有配置。

插件管理

插件系统提供可扩展的能力，允许第三方或用户自定义脚本来增强或替换软件功能。入口：左侧底部 → 插件管理（/plugins）。

12.1 插件安装与配置

1. 左侧底部点"插件管理"进入插件列表页。
2. 点击"安装插件"，选择插件文件或填写插件来源地址。
3. 安装完成后插件出现在列表中，点击插件进入详情页。
4. 在详情页可配置插件参数（根据插件类型不同提供不同配置项），保存后生效。

12.2 权限隔离

每个插件运行在独立权限沙箱中，按需申请能力，未授权的能力不可访问：

• 数据库：读写本地数据库的权限（可限制可访问的表）。
• 文件系统：读写指定目录的文件权限。
• 网络：发起 HTTP/WebSocket 网络请求的权限（可限制可访问域名）。
• 原生能力：调用软件原生 API（播放器、任务调度、AI 模型调用等）的权限。

12.3 触发器类型

插件通过 5 种触发器与软件交互：

12.4 日志与维护

• 查看日志：插件详情页"日志"标签查看运行日志（含错误堆栈），便于排查问题。
• 启用/禁用：列表中切换插件启用状态，禁用后所有触发器停止响应。
• 卸载：移除插件及其配置，已授予权限一并撤销。

局域网与联机计算

本章介绍局域网访问、联机计算与 WebDAV 三类网络能力，让您的媒体库跨设备使用，并用高性能电脑协助低性能电脑处理重负载任务。

13.1 局域网访问

13.1.1 启动 Web 服务

1. 主页点"运行"按钮启动服务，按钮变为"运行中"。
2. "浏览器网址"区域查看访问地址，点"浏览器打开链接"可直接访问。

13.1.2 局域网设备访问

• 其他设备使用相同 IP 地址和端口访问，支持手机、平板、其他电脑。
• 提供完整 Web 播放功能，注意网页播放只支持 MP4、Ogg、WebM 等网页支持的视频格式。
• 设置网页访问密码后，局域网其他设备访问同样需要输入密码。

13.2 联机计算

联机计算适合用高性能电脑协助其它低性能电脑处理计算量大的任务。一般把低性能、存放素材的电脑作为"数据端"，把性能更强的电脑作为"计算端"，由计算端负责预览生成、人脸识别、向量索引等高负载任务。

13.2.1 使用前准备

1. 准备两台电脑：一台保存素材库，另一台提供算力；两台都需能正常运行本软件。
2. 确保两台电脑在同一局域网，或计算端能直接访问数据端的 IP 和端口。
3. 建议先在保存素材库的电脑上完成基础配置，确认视频、图片、文章数据可用。
4. 如需认证令牌，提前约定同一串令牌，计算端连接时必须与数据端填写一致。
5. 确认防火墙已放行默认端口：TCP 50051 用于连接，UDP 50052 用于局域网扫描发现。

13.2.2 作为数据端

1. 打开素材库所在电脑的软件，进入主页右侧"联机计算"面板。
2. 点"作为数据端"。
3. 弹窗中填写监听端口，默认可用 50051。
4. 如需限制连接可填认证令牌；不填则任何能连到该端口的计算端都可尝试连接。
5. 点"启动"后页面显示监听端口、连接状态及已连接的计算端信息。保持电脑在线等待计算端接入。

13.2.3 作为计算端

1. 打开性能更强的电脑，在主页右侧"联机计算"面板点"作为计算端"。
2. "连接远端数据端"对话框中可先点"扫描设备"自动发现局域网内已启动的数据端。
3. 扫描到设备直接点击设备卡片，系统自动填入远端地址和端口。
4. 没扫描到也可手动填写远端地址、远端端口和可选的认证令牌。
5. 点"连接"，成功后显示远端地址、连接状态和会话 ID。

13.2.4 远程任务使用方法

1. 计算端连接成功后下方出现"远程任务"列表。
2. 每个任务卡片显示待处理数量、批次进度、最后更新时间、当前对象、当前文件和运行消息。
3. 需要处理哪类任务点对应卡片"启动"；也可用顶部"全部启动"一次性启动所有远程任务。
4. 临时不想继续点对应任务"暂停"，或用顶部"全部暂停"。
5. 任务异常时卡片显示错误信息，建议先排查数据、模型或网络问题再重启。

13.2.5 状态说明

• 未启动：任务尚未开始执行。
• 启动中：计算端正在初始化该任务。
• 拉取任务：正在从数据端获取待处理数据。
• 等待任务：当前没有立即可处理的数据，系统会继续轮询。
• 处理中：正在进行识别、预览生成或向量计算。
• 提交结果：已处理完成，正在把结果写回数据端。
• 已暂停：任务被手动停止，可随时再次启动。
• 异常：任务执行失败，需先处理报错原因。

13.2.6 注意事项与常见问题

• 数据端或计算端一旦进入联机计算模式，本机原有任务调度会自动暂停，避免本地与远程任务互相抢占资源。
• 计算端执行"断开连接"会中断当前正在处理的远程任务。
• 认证令牌只用于连接校验，两端必须完全一致，否则无法建立连接。
• 远程任务依赖数据端已有的数据、配置和模型环境；某类任务一直失败先检查对应功能在本机是否能正常使用。
• 长时间运行建议优先使用稳定的有线网络，避免无线网络波动导致任务中断。

Q: 为什么扫描不到数据端？

• 确认数据端已启动而非停留在普通模式；确认两台电脑在同一局域网，没被访客网络或虚拟网卡隔离；检查防火墙是否拦截 UDP 50052 广播和 TCP 50051 连接；仍扫描不到可直接手动填写数据端 IP 和端口连接。

Q: 连接成功后为什么没有任务可跑？

• 说明当前数据端没有对应类型的待处理内容或该类任务已处理完成；先确认数据端确实存在需要生成预览、人脸识别或索引的数据；也可回到相关列表或配置页确认任务开关和数据状态。

Q: 任务一直异常怎么办？

• 先查看任务卡片错误信息确认是网络中断、模型缺失还是数据异常；模型相关任务请先确保本地模型或依赖环境准备完成；处理完问题后重新启动该任务，必要时先断开再重新连接。

13.3 WebDAV 服务

WebDAV 提供视频、图片等资源的统一 HTTP 访问，便于外部播放器或文件管理器接入。详细配置见第 11.6 节。

• 启用服务与端口：默认端口 8090，可设自动启动。
• 挂载文件夹：将本地文件夹挂载到 WebDAV 目录下，通过 /dav/ 路径直接访问，名称不能为"视频""图片"等保留名称。
• 手机、平板、电视或其他电脑的播放器、文件管理器可直接通过 WebDAV 协议接入浏览资源。

常见问题

按"安装启动""功能使用""注册码"三类汇总。如遇无法解决的问题，请保存错误信息联系微信获取帮助。

14.1 安装和启动问题

Q: 软件无法启动或卡在加载界面

• 确保软件目录路径不包含中文字符。
• 安装 VC_redist.x64-14.38.33135.exe 运行库。
• 以管理员权限运行软件。
• 检查防火墙和杀毒软件设置。

Q: 提示端口被占用

• 在基础配置中修改 API 端口和网页端口（两端口不能一样）。
• 选择未被占用的端口号。
• 重启软件使配置生效。

Q: 网页打不开，修改端口无效

• 在基础配置中修改 API 端口和网页端口，不能一样。
• 检查端口是否被占用。
• 确认是否在同一个局域网下。
• 主页点"运行中"按钮停止服务，等几秒重启服务，或重启软件。
• 修改端口无效需要重启软件。

14.2 功能使用问题

Q: 人脸识别准确率低

• 提高演员照片质量（清晰、正面、单人）。
• 调整识别参数（匹配度阈值）。
• 增加演员照片数量（多角度）。
• 使用高质量视频进行识别。

Q: AI 功能无法使用

• 检查 AI API 配置是否正确。
• 验证 API Key 是否有效。
• 确保网络连接正常。
• 检查 API 额度是否充足。
• 确认"当前使用模型"已选中语言或视觉模型。

Q: 软件运行缓慢 / CPU 使用率过高

• 大多数任务本地运行，视频截图、生成预览、人脸提取、视觉识别都比较耗资源。
• 先一个一个任务跑，关闭不必要的后台任务。
• 开启 GPU 加速功能（需 NVIDIA 显卡）。
• 升级电脑硬件配置。

Q: 没有生成封面

• 检查基本设置是否开启了生成封面，开启后需要重启生效。

Q: 如何保护隐私

• 使用视频隐藏功能（导入时开启或详情页手动隐藏）。
• 设置软件密码保护。
• 定期备份重要数据。

Q: 忘记软件密码

• 删除软件运行目录下的 pwd 文件。
• 重启软件即可重置密码。
• 重新设置新密码。

Q: 重新下载后注册码不见了

• 扫码购买用户直接点击购买会生成新的注册码，不会二次扣费。
• 微信转账购买用户联系客服重新生成。

14.3 注册码相关问题

Q: 如何获取注册码？

• 打开软件，左上角点"获取注册码"按钮。
• 弹窗显示机器码，点"立即购买注册码"支付 99 元即可获取。
• 支付完成后系统自动生成注册码并显示在页面中。
• 填入"注册码"输入框点"确定"完成激活。
• 一台电脑对应一个注册码，永久使用，无限免费更新。

Q: 重装系统后注册码还能用吗？

• 重装系统后机器码可能变化。
• 扫码购买用户直接点"立即购买注册码"，系统生成新注册码，不会二次扣费。
• 微信转账购买用户请联系客服提供新机器码重新生成。
• 建议购买时保留好订单信息方便后续查询。

Q: 能不能多台机器使用同一个注册码？

• 不可以，注册码采用一机一码授权方式。
• 每台电脑机器码唯一，注册码与机器码绑定，一个注册码只能在一台电脑上使用。
• 多台电脑使用需为每台单独购买注册码，每台仅 99 元，永久使用，无限免费更新。

Q: 更换硬件后注册码会失效吗？

• 更换部分硬件（如内存、硬盘）通常不影响机器码。
• 更换主板或 CPU 等核心硬件机器码可能变化，原注册码将无法使用。
• 扫码购买用户可直接重新获取新注册码（不扣费）。
• 微信转账用户请联系客服重新生成。

Q: 注册码丢失了怎么办？

• 扫码购买点"立即购买注册码"按钮即可查看历史注册码或生成新注册码。
• 微信转账购买请联系客服提供机器码查询历史注册码。
• 建议将注册码保存在安全的地方，如密码管理器或云笔记。

Q: 软件提示"注册码无效"怎么办？

• 检查注册码是否输入正确，注意区分大小写和数字 0 与字母 O。
• 确认当前机器码与购买时提供的机器码是否一致。
• 机器码变化后需重新获取对应新机器码的注册码。
• 如仍有问题请联系客服协助解决。

Q: 购买后多久能收到注册码？

• 扫码支付是自动化的，支付完成后立即显示注册码，无需等待，即买即用。