# YarSharker **Repository Path**: defiphoenix/yar-sharker ## Basic Information - **Project Name**: YarSharker - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-10-29 - **Last Updated**: 2026-10-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # YarSharker Workbench 一个可以整目录带走的 Windows 桌面工作台。主面板为空白，右侧工具箱提供 **智能抠图**、**像素化**、**图片压缩**、**图片Resize**、**图片裁剪**、**图片切分**、**视频抽帧** 和 **图集生成**，各工具独立使用；图片切分逐张编辑，其他图片处理工具支持批量处理。界面运行在独立 Electron 桌面窗口中，视频和图片由本机进程处理，无需账号、API Key 或云端服务。 ## 启动 1. 双击 **`启动工作台.vbs`** 或根目录的 **`YarSharkerWorkBench.exe`**，先显示轻量启动窗口，再在后台启动 PowerShell 检查环境和打开工作台，不显示控制台。启动窗口会展示环境检查、首次下载准备和工作台启动状态，主面板显示后自动关闭；启动失败则保留错误提示。也可以双击 `start.bat`。启动器约 14 KiB，使用 Windows 自带的 .NET Framework，不安装新依赖，沿用已选择的主题。直接启动 `.runtime` 中的 Electron EXE 也会在处理服务启动前显示加载页。 2. 首次运行只从已配置镜像下载并校验主页必需的 Python、pip 和 Electron，然后进入工作台。图片处理库、FFmpeg、AI 依赖和模型在首次使用对应功能时下载，也可在设置中提前下载；已准备好的工具可离线使用。无需全局安装环境，源码 ZIP 请先完整解压到可写目录。 3. 点击右侧 **智能抠图**，选择单张或多张图片进行抠图；视频使用 **视频抽帧** 导出 PNG 序列帧，再按需使用图片处理及图集工具。 4. 图片点击 **开始图片抠图**，拖动分隔线对比原图与成品；视频抽帧可查看序列帧动画，多张图片可用 **图集生成** 打包。处理完成后手动导出图片文件或文件夹。 ## 工具间继续处理 工具生成图片后，产物区会显示 **继续处理 ▾**。可选择当前图片、全部产物或勾选部分图片，选择下一个工具并发送，无需导出再导入。目标工具已有素材时可选择追加或替换；图片切分只接收一张图片，视频抽帧不接收图片，不兼容的目标会提示原因。未下载资源的目标需先在设置中下载。 也可拖动“继续处理”旁的小缩略图，或直接拖动产物缩略图，到顶部工具标签或右侧节点库的工具按钮；拖入空工具直接载入，已有素材时先选择追加或替换。多图可在继续处理窗口中勾选，再拖动“拖动选中产物”。 传递使用独立的文件数据，关闭来源标签页不会使目标素材失效。切换到目标工具仍沿用该工具的参数；像素化按其原有规则自动处理。传递不是导出，不会把任务记为已导出的有效任务。单次最多传递 100 张、合计 500 MB；目标工具自身的数量限制仍生效。 ## 图片切分 导入一张图片（也可拖入左侧画布），用直线、折线、曲线或手绘线定义分区，点击 **生成切片**。直线和手绘按住左键拖动；折线和曲线逐点点击，双击、Enter 或“完成绘制”结束。端点自动吸附图片边缘与已有分界线，点击起点可闭合；未连接的端点会标红并提示补齐。 绘制时第一次按下即显示橙色落点，白底深色描边突出起点；折线 / 曲线逐点点击后保留已放置的控制点，缩放时标记保持屏幕大小。普通工具和蓝图节点共用此反馈；完成或取消绘制后清除草稿标记。 选择 / 编辑模式可拖动整条线或控制点，双击线段添加控制点，右键控制点删除控制点；可撤销、重做、删除选中线或清空。右键空白处平移画布，滚轮或缩放按钮调整视图。原图与切片对比预览均显示 px 坐标轴。 切片按原始像素输出透明 PNG；不规则轮廓外为透明背景，不缩放原图。右侧分页查看各切片，下方拖动指针对照原料与产物。可设置文件名前缀，逐张导出或导出全部到文件夹；导出时仍会要求确认已填充默认值的文件名 / 文件夹名称，不导出 ZIP。 蓝图节点库也提供 **图片切分**。在节点详情点击“编辑分割线”，使用上游图片或自选参考图片绘制；相对位置应用到此节点收到的每张图片，所有切片可继续传给图集生成等后续节点。参考图片不替代实际输入素材。切分最多支持 100 条线、256 份切片及 4000 万源像素，仅依赖共享 Pillow；没有额外模型或下载项。 ## 窗口关闭行为 设置 → 常规 → 窗口行为中提供 **关闭后最小化**，默认不勾选，修改后立即保存。勾选后点击窗口 X 会最小化到 Windows 任务栏，处理、下载和导出继续进行，不触发退出缓存清理；点击任务栏图标或重新启动入口可恢复窗口。取消勾选后，关闭窗口仍按原流程退出。 需要真正关闭软件时，点击同一区域的 **退出工作台**，仍会检查未完成的任务、下载和导出，并按原流程确认、停止服务和清理缓存。该设置保存在项目内 `data/desktop/settings.json`，搬迁目录后也会保留。 ## 按需下载 设置中提供 **常规 / 下载** 两个页面。资源未全部准备好时显示“下载”，按工具列出就绪状态、下载按钮和下载进度（百分比、已下载体积、网络速度）；下载可以取消、失败后可以重试。处理任务首次需要缺失资源时会自动准备，切换页面不影响下载。 右侧节点库中，尚未准备好基础资源的工具显示灰色遮罩，中央提供“下载”按钮；下载时遮罩直接显示进度及网速，完成后自动解除。遮罩期间不能打开工具或拖入节点，失败后可点击“重试”。该入口与设置页共用下载状态，共享依赖准备好后相关工具一起恢复使用。 下载状态区分连接镜像、查找依赖、下载、安装和校验，并显示已等待时间；连接超时重试也会提示。智能抠图下载结束只校验必要运行组件和模型文件，不预先初始化完整抠图库；首次实际处理图片时仍需加载模型及初始化抠图库。 - 像素化、图片压缩、图片Resize、图片裁剪、图片切分和图集生成共用 Pillow，下载一次即可。 - 视频抽帧另需 FFmpeg；不会顺带下载 AI 环境和模型。 - 智能抠图按所选模式准备环境：纯色抠图仅需 NumPy；AI 抠图共用推理依赖，并只下载所选的 U²-Net 轻量版、BiRefNet Lite 或 BiRefNet General 模型。可在下载页切换模型分别准备。 资源全部保存在项目目录的 `.runtime`、`models` 和 `.cache` 中。已有资源会复用，下载不会记入最近任务；关闭软件会停止尚未完成的下载，重开后可重试。安装日志位于 `.cache/desktop-logs/dependencies.log`。 已校验的依赖安装包保存在 `.cache/resources/wheels/`，即使整组依赖尚未安装完成，关闭并重新打开后仍会复用。未完成的依赖包及在线模型保留 `.partial` 文件，重试时请求断点续传；镜像不接受续传时仅重新下载当前文件，校验失败则丢弃损坏的缓存。退出时继续清理临时文件和预览缓存，但保留资源安装包及断点文件。这些资源缓存已被 `.gitignore` 排除，不会随代码上传到仓库。 ## 工具标签页 点击右侧工具，在主面板上方打开对应的小标签页。每个工具只有一个页面，侧边栏和标签页均切换到同一实例；再次点击保留当前文件、参数、预览和任务。切换到其他工具、主面板或设置时，已打开的工具保持运行，页面状态也继续保留。图集生成用于静态图片；旧视频图集记录仍可查看和导出。 可分别配置多个工具并提交任务，实际处理在本地队列中串行执行。排队和处理中的标签页显示状态圆点，切换页面不改变队列或中断任务。 标签页右侧的 **×** 用于关闭。运行、上传或等待自动更新时，先确认“停止并关闭”；选择“继续处理”保留任务。关闭后停止该工具本次页面创建的任务，清理遮罩临时预览及其他未导出缓存，释放页面内文件。全局上次打开的一个任务（包括未导出任务）的原始素材、参数及产物保留用于恢复；已成功导出的历史任务及磁盘上的导出文件保留。正在保存的导出会等待桌面下载结束，再按导出是否成功保留记录或清理临时产物。 各标签页的任务使用独立会话归属，关闭时只清理自己的缓存；关闭期间还在接收的上传也会停止，后台收尾后清理。设置、模型和运行环境继续保留。标签页支持方向键切换，`Delete` 请求关闭当前标签页；最近任务打开对应工具的现有标签页。 `tests/tool_tabs.test.cjs` 验证页面复用、切换保留、关闭确认、重开与失败处理；`tests/test_workspaces.py` 和 `tests/workspace_integration.py` 验证按会话停止、排队、上传收尾、预览与任务目录清理，以及导出中的保护和历史保留。 ## 图片Resize 点击工具箱 **图片Resize**，拖入或选择单张、多张静态图片，设置后点击 **开始Resize**。支持 PNG、JPG / JPEG、WebP、BMP、TIFF、静态 GIF，每批最多 100 张、每张最大 500 MB。使用项目内按需下载的共享 Pillow 图片库。 - **按倍率**：0.01–16 倍，例如 0.5 倍使宽高各减半、2 倍使宽高各翻倍；提供 0.25×、0.5×、1×、2×、4× 快捷选择。 - **目标最长边**：设置 1–16384 px，每张图片按自身宽高比例调整，既可放大也可缩小。像素取整可能造成约 1 px 的比例误差，宽高至少为 1 px；输出最长边最多 16384 px，总像素最多 4000 万。 - **缩放效果**：普通图片使用平滑缩放（Lanczos），像素图可选择保留像素块（最近邻）。平滑缩放使用预乘透明度，避免原图透明位置的隐藏颜色污染边缘。普通插值放大不恢复原图缺失的真实细节。 输出 PNG 并保留透明背景，界面显示原始尺寸与成品尺寸，支持原图 / Resize成品对照、滚轮缩放、放大后左键拖动、双击恢复。成品保存在 `data/jobs/<任务ID>/images/*_resized.png`，可单张导出或将当前参数下完成的成品保存到命名文件夹。处理完成不自动导出；沿用导出后保存有效任务、另保留上次打开任务的规则。改参数后从原始素材重新处理，避免重复缩放旧成品。切换标签页保留状态，关闭标签页会停止任务并清理其他未导出缓存，全局上次任务保留用于恢复。 ## 图片压缩 点击右侧 **图片压缩**，拖入或选择单张、多张静态图片（PNG、JPG / JPEG、WebP、BMP、TIFF、GIF），统一设置后点击 **开始压缩**。每批最多 100 张、每张最大 500 MB；不支持动画或多页图片。全程使用项目内共享的 Pillow 编码器，首次使用按需下载，无需全局安装。 - **压缩倍率**：1–100 倍，目标体积 = 输入文件字节数 ÷ 倍率。例如 2 倍约为原文件的一半，不缩放图片尺寸。 - **最低画质 / 最高画质**：1–100 的整数，最低值不能超过最高值。优先在指定区间寻找满足目标体积的较高编码质量；最低画质仍无法满足目标时，输出该画质的结果并明确提示，不突破用户设置的下限。画质参数是编码器等级，不是客观画质百分比。 - **输出格式**：WebP 保留原有透明度；JPEG 将透明区域合成到白色背景。参数改变后点击开始重新压缩，历史已导出的产物保持不变。 预览可切换原图与成品，显示文件体积、实际倍率、输出尺寸、编码质量及是否达到目标；较小原文件重新编码后也可能变大，界面会如实提示。支持 滚轮缩放、放大后左键拖动及双击恢复。可以停止批处理，已经完成且符合当前参数的结果仍可导出。 成品保存在 `data/jobs/<任务ID>/images/*_compressed.webp` 或 `*_compressed.jpg`，不自动导出。**导出当前成品**保存单张图片，**导出 N 张成品**保存为文件夹，同名文件以序号区分。沿用导出成功后保存有效任务、另保留上次打开任务的规则，历史可重新打开、更改参数并用原始素材处理。关闭标签页会停止任务并清理其他未导出缓存，全局上次任务保留用于恢复。 ## 图片像素化 点击右侧 **像素化**，拖入或选择单张、多张图片，可继续添加或从队列移除；一次最多 100 张、每张最大 500 MB。支持 PNG、JPG / JPEG、WEBP、BMP、TIFF 和静态 GIF，动画图片与 MP4 不支持此工具。 **长边像素数** 可设置为 1–2048，滑块常用范围 1–512，并提供 16、32、64、128、256 快捷值。数值越小，像素块越大。全部图片共用参数，按原图比例取整为像素网格；小图不会额外放大网格来增加细节。导出可选择 **保持原图尺寸**（缩小后用最近邻放回原尺寸），或 **像素网格尺寸**（直接保存小尺寸图片）。保留透明背景，颜色平均采用预乘透明度，避免透明区域隐藏的颜色污染像素边缘。不安装新依赖或模型。 选择或拖入图片后立即自动处理，不需要点击开始按钮。修改长边像素数（滑块、数字输入、快捷值）或导出尺寸后，停顿约 0.4 秒便会自动更新整批图片。处理中仍可调整参数，当前图片结束后会采用最新参数处理，避免旧设置继续排队；输入临时为空或超出范围时等待修正，不会提交无效任务。 追加图片时跳过已经完成且参数相同的成品；导出前重复调整会更新同一个临时任务并复用原图。开始导出后，该版本保持不变；后续调整参数会创建新的临时任务，保留原导出版本。打开最近任务只查看现有结果，修改参数时才更新。处理中和等待更新时暂时隐藏导出按钮，完成后再允许导出，避免保存旧参数的结果。 界面显示每张状态与总进度，可停止当前自动处理与后续排队，已完成且符合当前参数的结果仍可导出；再次调整参数或添加图片后继续自动处理。点击队列缩略图查看不同成品，切换 **原图 / 像素化成品** 对照。预览支持滚轮缩放、放大后左键拖动、双击恢复。 处理结果写入各自 `data/jobs/<任务ID>/images/<原文件名>_pixelated.png`，不会自动导出。点击 **导出当前成品** 保存 PNG，或 **导出 N 张成品** 将当前队列已完成的 PNG 一并保存为文件夹（用序号区分同名文件）。桌面保存对话框默认使用设置中的导出目录。最近任务会标记“像素化”，点击后可以查看并使用保留的原图重新处理；右键删除沿用任务及文件清理流程。 ## 视频抽帧 点击右侧 **视频抽帧**，拖入或选择单个 MP4（最大 500 MB），设置抽帧帧率、起始时间、截取时长和输出最长边，再点击 **开始抽帧**。支持 1–60 FPS，截取 0.1–120 秒，单次最多 500 帧。按原始比例缩小到最长边限制，较小的视频不会放大。原视频可在源视频卡片中展开播放。 抽帧结果使用同一播放器，默认按抽帧帧率循环播放，可暂停、拖动进度、长按上一帧 / 下一帧连续切换；保留原始画面与背景，按 `frame_000001.png` 顺序编号；拖动预览进度条或点击上一张 / 下一张逐帧查看。点击 **导出序列帧** 手动保存文件夹，包含 `frames/` 下的 PNG、`frames.json` 帧列表及 `settings.json` 参数。修改参数后需重新抽帧，再导出对应结果。 沿用已导出有效任务加上次打开任务的保存规则；历史项标记“视频抽帧”，点击可重新查看全部帧和导出，右键可删除任务及文件。除上次打开任务外，其他未导出缓存关闭时清理。再次处理历史视频需要重新选择原文件。视频抽帧使用项目内 FFmpeg，不安装新依赖或模型。图集生成仅接收图片；视频可先抽帧，按需处理图片后再生成图集。 `tests/video_frames_integration.py` 在临时项目验证真实 MP4 的帧率、时间范围、尺寸、原始背景、序列编号、ZIP、错误处理、导出历史和重启恢复，并回归 MP4 转图集；`tests/video_frames.test.cjs` 检查独立面板的选图、预览、取消和历史切换。 ## 图集生成 此工具仅将单张或多张静态图片打包为图集，不再提供视频抠图图集模式，也不会在拖入 MP4 时自动切换。视频可先使用 **视频抽帧** 导出图片，再分别交给图片工具处理。旧视频图集记录仍可查看、播放和导出已有产物，不能在旧页面新建或重新处理视频。 点击右侧 **图集生成**，可选择或拖入单张、多张静态图片，并继续添加、移除或清空。支持 PNG、JPG / JPEG、WEBP、BMP、TIFF、静态 GIF，一次最多 100 张、合计最大 500 MB。队列每组显示 4 张，通过上一组 / 下一组浏览，避免滚动长列表。 设置 **图集最大尺寸**（512、1024、2048、4096）、**每侧留白**（0–16 px）和 **裁去图片透明边缘**，点击 **开始生成图集**。保留原图颜色与透明度，不改变图片大小；超过单页尺寸的图片会提示增大图集或先缩小图片。放不下时自动分页，画布按实际占用裁紧。透明边缘裁剪会在 JSON 中保存原始尺寸、裁剪尺寸和偏移，便于还原；同名图片会自动生成不同的图集键名，避免坐标覆盖。 预览区可选择不同图集分页。点击 **导出图集与坐标**，选择 Cocos 或 Unity、填写文件基础名，再确认保存位置。Cocos 导出 PNG + 原生 `.plist` + JSON，可按用户输入的 Creator 版本同步生成 `.anim` 与资源引用 `.meta`；Unity 导出 PNG + Multiple Sprite `.png.meta` + JSON。图集文件直接位于导出文件夹根目录。图片或参数修改后需重新生成，再导出对应结果；旧图集历史也支持新的导出设置。 最近任务保留已成功导出的有效任务，并额外保留上次打开的任务；其他未导出缓存关闭时清理。历史图集可以查看、导出、移除部分原图片并调整参数重新生成；每次重新生成创建新任务，保留原来导出的图集。历史状态下选择新文件会建立新的图片队列。右键最近任务可删除图集与对应的原图片、预览和参数。 独立工具复用现有图集排列与坐标生成逻辑，无需新增环境、依赖或模型。`tests/atlas_generator_integration.py` 在临时项目验证多图上传、同名文件、透明度与裁边还原、分页、JSON / ZIP、历史重新生成、导出保存、重启与删除；`tests/atlas_generator.test.cjs` 验证面板交互和上传数据。 ## 动画预览 图集预览、视频抽帧预览及多帧遮罩编辑统一复用 `desktop/ui/frame-player.js`。同一组件只负责有序图片的展示与控制：上一帧 / 下一帧、播放 / 暂停、长按连续切帧、进度拖动与循环。输入为 `{ key, frames, fps, imageRendering }`；`frames` 按传入顺序播放，每帧提供图片 `src` 或返回图片 / canvas 的异步 `load(signal)`。播放器不读取任务、工具或图集格式；图集解析及透明边缘帧还原由独立的 `atlas-sequence.js` 适配后交给播放器。切换工具、隐藏页面、取消任务或更换任务时会停止当前计时和长按，返回后保留原先的播放意图与位置。 序列帧预览默认按抽帧帧率循环播放。可用播放 / 暂停按钮控制播放；拖动进度条会暂停并定位到对应帧，方向键也可逐帧调整进度条。**上一帧 / 下一帧** 短按切换一帧，长按约 0.3 秒后连续切帧；松开、切换预览或到达首尾时停止，并保持暂停。键盘长按空格或 Enter 也支持连续切帧。当前帧数显示在进度条右侧。取消勾选 **循环** 后，播放到最后一帧会自动暂停，再次播放会从头开始。切换到其他预览标签再返回时，会保留当前帧与播放状态。 ## 最近任务 最近任务由**导出成功的有效任务**和**上次打开的一个任务**组成；如果上次打开的任务已导出，只显示同一条记录。未导出记录标为“上次打开 · 未导出”，置于列表最前；点击历史任务、切回有任务的工具标签页或创建新任务都会更新上次打开记录，后台轮询不会更新。有效任务仍以成功导出为准：以桌面保存对话框确认后、文件实际保存完成为准。仅生成、预览、取消保存或导出失败都不计入；批量导出成功时记录其中的所有图片，多次导出同一版本不会重复记条目。除置顶的上次打开记录外，历史按首次成功导出时间排列。 未导出任务中仅保留上次打开的那一次，包括原文件、参数、预览和已生成的产物；重启后可从最近任务打开。退出时仍在处理的任务会停止，不会在下次启动时自动运行。其他未导出缓存正常退出时清理，异常中断后下次启动继续清理。关闭工具标签页会停止任务并清理其他未导出缓存，但保留全局上次任务用于恢复；不会为每个工具另存一份未导出任务。手动删除记录仍会删除对应缓存，即使是上次任务也不会重新出现。已导出任务的原图、参数、预览和产物会保留，供重启后查看、对比与重新处理。旧版没有可靠导出标记的记录会隐藏，但原有文件保留；旧版已有成功自动导出路径的记录会迁移保留。 右侧最近任务支持右键菜单（键盘可用 Shift+F10），选择 **删除任务及文件** 并确认后，会同时移除任务记录和 `data/jobs/<任务ID>/` 中的原文件、预览及产物，无法撤销；请先手动导出需要保留的结果。保存到其他目录的导出文件会保留。正在处理的任务与正在运行的批量任务不允许删除。旧版本标记为已删除的任务会在下次启动时自动清理；文件被占用时暂存于项目 `.cache/deleting-jobs/`，下次启动继续清理，避免任务记录重新出现。 ## 图片自动抠图 支持 PNG、JPG / JPEG、WEBP、BMP、TIFF、静态 GIF。图片可一次多选，也可一次拖入多张。此工具仅接受静态图片，MP4 请先使用视频抽帧工具导出图片；视频抽帧、图集及动画相关参数不再在智能抠图中显示，只保留 AI / 纯色抠图设置。图片按 EXIF 方向校正后保留原始尺寸，不裁边、不拼图集；原图已有的透明区域也会保留。 所有图片统一输出透明 PNG，文件名为 `原文件名_cutout.png`。JPG 本身不支持透明通道，所以 JPG 输入也会生成 PNG。结果提供 **导出抠图图片** 和 **导出完整素材包**（PNG + 处理参数）按钮。点击后确认保存位置，默认使用设置中的导出目录。 多图使用同一组抠图参数，点击“开始批量抠图”后依次处理，避免同时加载多张大图占满内存。图片队列展示每张的处理状态，失败的图片不会阻止后续图片；完成后点击队列中的文件查看、缩放、拖动预览或单独保存 PNG。每张产物先保存在项目任务目录中用于预览，用户可选中队列中的图片，再点击导出按钮保存。“停止批量处理”会取消当前任务并停止剩余图片，已完成产物保留；也可重新开始整批处理。尚未提交的图片队列保留在当前窗口中，关闭或刷新后需要重新选择。 图片不再单独显示源图或原图标签页；结果区域以成品为底图、原图为覆盖层，默认各显示一半。左右拖动分隔指针可切换完整原图、完整成品或任意对比比例，也支持方向键微调、Home / End 查看两端。滚轮缩放和放大后的左键平移会同步作用于两层，保持像素对齐；切换图片后对比分隔线回到中间。 单张图片最多 4000 万像素；动态 GIF、动态 PNG / WEBP、多页 TIFF 会提示转换为静态图片或 MP4 后再处理。 ## 遮罩保护 选择图片后，点击源素材区域的 **遮罩保护**。编辑器会临时显示校正方向后的原图，绿色区域表示原样保留；保存后仍回到原图 / 成品的滑动对比界面。 - **矩形 / 椭圆**：按住左键拖出区域，可画多个形状。 - **多边形**：逐点点击，双击、Enter 或点击“完成圈选”闭合。Esc 取消未完成的圈选。 - **自由圈选**：按住左键沿边缘圈画，松开后自动闭合。 - **撤销 / 重做 / 清空**：也支持 Ctrl+Z、Ctrl+Y、Ctrl+Shift+Z；“取消”放弃本次编辑，保留之前保存的遮罩。 - **缩放 / 平移**：使用 Ctrl+滚轮或缩放按钮，切到“平移”工具后左键拖动。区域始终按原图坐标保存，不受编辑器缩放、窗口大小影响。 点击 **保存遮罩** 后，再点击 **开始图片抠图 / 开始批量抠图**。批量模式下先在图片队列选择一张，再编辑它的遮罩；每张独立设置，其他图片不会继承。尚未提交的遮罩随当前选图队列保留，关闭窗口或重新选择文件后需要重新设置；已处理任务的遮罩会写入任务和导出参数，重启后可从历史任务恢复。 历史图片可直接进入遮罩编辑器，点击 **重新处理图片** 会复用任务目录里的原文件并创建新任务，不覆盖之前的成品。原文件被清理后需要重新选择。修改遮罩后会提示重新处理，旧成品的手动导出按钮暂时隐藏，防止将未应用新遮罩的旧结果当作新成品。 保护区域内的**原始颜色、背景和透明度全部保留**。AI 仍整图推理，随后按遮罩还原保护区域；区域外正常抠图。本版为硬边保护，不含边缘羽化；需要调整已画区域时可撤销重画。每张最多 128 个区域，单个圈选最多 2048 个点，所有圈选合计最多 8192 个点。 打开遮罩编辑器时先展示加载页和图片准备进度，全部帧准备完成后自动进入；加载失败可重试，加载过程中可取消。动画复用整段已解码的播放帧，不再逐帧请求或生成预览；播放帧使用独立的 128 MiB 像素预算，暂停编辑时按需准备最长边 2048 像素的精细编辑缓冲，保存的遮罩仍使用原图归一化坐标，关闭编辑器释放本次内存缓存。遮罩编辑页显示抠图后的产物，接收多张图片时，自动按顺序循环播放，并复用通用播放器的播放 / 暂停、上一帧 / 下一帧、长按连续切帧、拖动进度条及循环开关。普通图片默认 12 FPS，绘制时自动暂停。每帧分别保留遮罩及撤销记录，切帧不会丢失编辑，点击“保存遮罩”统一应用本次修改，取消则放弃本次修改。 遮罩页支持 **取反**（交换抠图保留部分与被抠掉的部分，独立于手画保护遮罩）、**整块保护**（点击抠图后待裁剪的连通区域，红色斜线提示）和 **橡皮擦**（1–200 原图像素）。已完成任务优先复用缓存的基础抠图产物；未处理素材或抠图参数变更后，使用当前 AI / 纯色抠图参数生成临时产物预览，循环时复用预览，不创建任务或导出；连通区域按四邻域识别，包含透明度被削减的半透明像素；完整保留或原本透明的像素不会误选为新裁剪区域。预览最长边不超过 2048 像素。选择整块后可用橡皮擦细修，也可将形状操作切到“去除保护”，以矩形、椭圆或圈选精确扣掉多余遮罩；再添加保护可局部补回。取反、整块、擦除均支持撤销 / 重做，并独立保留到对应帧。取反以原图透明度减去基础抠图透明度计算，被抠掉的区域恢复，原先保留的区域隐藏；原图本来透明的位置不变。保护遮罩随后独立应用，保存后重新处理的产物与编辑预览使用相同取反规则。 带遮罩任务额外导出 `protection-mask.png`（白色为保护区域，黑色为正常处理区域），并写入导出文件夹；`settings.json` 中的 `protection_regions` 保存归一化形状数据。空遮罩保持原有 PNG + 参数导出结构。PNG 成品不会叠加编辑器的绿色提示色。 编辑器的方向校正预览保存在项目 `.cache/image-previews/`，可以随其他缓存一起清理；不安装额外环境或模型，不上传素材到外部服务。 ## 选择界面主题 点击右上角 **设置 → 外观主题**，选择以下三个主题之一，立即切换并自动保存，不需要额外点击“保存设置”： | 主题 | 配色 | 适用体验 | | --- | --- | --- | | Light+（默认） | 白色画布、蓝色强调 | 明亮清晰 | | Dark+ | 提亮深灰、浅蓝强调 | 保留深色风格，提高文字和边框辨识度 | | Quiet Light | 暖灰背景、柔和紫色 | 明亮但柔和 | 配色参考 VS Code 的 [Light+](https://github.com/microsoft/vscode/blob/main/extensions/theme-defaults/themes/light_plus.json)、[Dark+](https://github.com/microsoft/vscode/blob/main/extensions/theme-defaults/themes/dark_plus.json) 与 [Quiet Light](https://github.com/microsoft/vscode/blob/main/extensions/theme-quietlight/themes/quietlight-color-theme.json)，并针对工具面板调整。正文、辅助文字和控件均已提亮，辅助字号也有提高。 主题与导出路径一起保存在项目设置中，重启后保留；切换主题不会保存或覆盖尚未提交的导出路径。窗口与系统文件对话框同步使用浅色或深色外观。`desktop/ui/themes.js` 是界面、桌面主进程共用的主题定义。 ## 设置导出路径 点击窗口右上角 **设置**，进入设置页面。点击 **选择文件夹** 或输入完整路径，然后点击 **保存设置**。可以用 **恢复默认路径** 将路径改回项目 `data/exports/`，再点击保存。 工具处理完成后只生成预览与项目任务文件，不会自动写入导出目录或弹出保存窗口。图片点击 **导出抠图图片** 保存透明 PNG，也可点击 **导出全部文件** 保存 PNG 与参数的文件夹；旧 MP4 图集点击 **导出全部文件** 选择 Cocos 或 Unity 后保存对应图集文件夹。 设置保存在项目 `data/desktop/settings.json`，重启后继续生效。每次点击导出按钮时读取当前路径，保存对话框默认打开该目录，可自行修改文件名和保存位置；取消对话框不会导出。处理过程中修改设置也会对下一次手动导出生效。项目内部目录按相对路径保存，便于整目录迁移；外部目录保存完整路径。 导出目录不可用时，桌面端会提示检查设置，处理结果仍保留在项目任务目录，可修正路径后再次点击导出。 需要 Windows 10/11 x64。Electron 自带 Chromium，不要求安装浏览器、Node 或 WebView2。首次联网准备主页基础环境，工具依赖和所选模型按需准备，之后资源齐全时可离线启动和处理。窗口有独立任务栏入口，可以缩放、最大化；再次启动会聚焦已有窗口。 关闭桌面窗口会停止后台服务；如果有未完成处理或导出，会先提示是否退出。确认退出后，取消未完成导出，等待已完成导出的历史写入，再停止服务并清理除上次打开任务外的未导出缓存。桌面进程异常结束时，后台也会检测父进程并退出；已导出历史保留。 根目录的 `YarSharkerWorkBench.exe` 是轻量启动器，`启动工作台.vbs` 和 `start.bat` 都直接启动它，迁移后仍然有效。它先绘制启动窗口，再检查和恢复项目环境，最后打开 `.runtime/electron/YarSharkerWorkBench.exe`。首次部署或环境缺失时自动从镜像下载；已有完整的本地环境或旧离线包则直接复用。维护者修改 `desktop/launcher.cs` 后，使用 Windows PowerShell 执行 `scripts/build-launcher.ps1`，将重新生成的根目录 EXE 和源码一并提交；普通用户无需编译。启动器的首次绘制、环境检查和主窗口交接时间记录在 `.cache/desktop-logs/startup.log`。 项目仅提供桌面应用入口。Electron 加载 `desktop/ui/` 中的界面资源，并启动项目内 Python 处理服务；内部通信地址由应用自动管理。 ## 当前功能 - 智能抠图仅处理静态图片，输出原尺寸透明 PNG；图集生成支持图片拼图集，视频请先通过视频抽帧工具导出图片。 - FFmpeg 抽帧：设置帧率、开始时间、截取时长、最长边；不会放大小视频。 - AI 批量抠图：本地 CPU 推理，使用 U²-Net 的轻量模型 `u2netp`，不上传素材。复杂背景、发丝和逐帧边缘稳定性仍需检查。 - 纯色批量抠图：选择背景颜色、容差、柔和度，适合绿幕等纯色素材。 - 透明 PNG 图集：自动裁透明边缘，保留偏移和原始画布尺寸；多页排列，不旋转，不修改帧顺序。 - 每页一份 TexturePacker 风格 JSON Hash，同时提供 `animation.json` 保存跨页帧顺序和帧率。 - 任务进度、取消、最近任务持久保存、结果文件 / 文件夹导出。 - 设置页面支持保存导出路径、选择文件夹与恢复默认；处理完成后手动导出 PNG / 文件夹。 单次文件上限 500 MB。视频最多 500 帧、截取时长最多 120 秒，默认 12 FPS、5 秒、最长边 512 px。图集尺寸是**每页上限**，实际按内容裁小，不强制 2 的幂。图集导出支持 Cocos `.plist` 和 Unity `.png.meta` 切片；不输出 Spine 专用 `.atlas` 文本。固定尺寸、旋转紧密打包、边缘扩展尚未提供。 ## 文件都放在哪里 ```text YarSharkerWorkBench/ ├─ 启动工作台.vbs # 无控制台桌面启动入口 ├─ start.bat # 桌面启动入口，缺失环境时从镜像下载 ├─ setup.bat # 联网准备 / 修复项目内环境 ├─ scripts/ # 只修改进程环境，不改系统 PATH/注册表 ├─ backend/ # 桌面内部处理服务、独立任务进程和处理链路 ├─ desktop/ # Electron 主进程、图标和运行时版本/校验锁 │ └─ ui/ # 桌面界面 HTML / CSS / JS，无构建步骤 ├─ plugins/mp4-atlas/ # 首个工具的描述与扩展约定 ├─ requirements.txt # 直接依赖版本 ├─ requirements.lock.txt # 可从国内镜像恢复的完整依赖版本锁 ├─ vendor/runtime-win-x64/ # 旧离线包兼容清单；分卷不纳入 Git ├─ .runtime/python/ # 独立 Python、pip、库、FFmpeg 可执行文件 ├─ .runtime/electron/ # 独立桌面引擎及 YarSharkerWorkBench.exe ├─ .cache/ # 下载、pip、临时文件及 numba 缓存 ├─ models/u2netp.onnx # 本地 AI 模型 └─ data/jobs/<任务ID>/ ├─ source.mp4 ├─ settings.json ├─ frames/ # 原始序列帧 ├─ cutouts/ # 透明序列帧 ├─ atlas/ # PNG、每页 JSON、animation.json ├─ result.zip # 内部图集缓存；按用户所选引擎另行生成导出包 ├─ job.json # 任务状态 ├─ ffmpeg.log └─ worker.log ``` 桌面窗口尺寸和配置在 `data/desktop/`，Chromium 会话与日志在 `.cache/electron-session/`、`.cache/desktop-logs/`，不写入用户的全局浏览器配置。Electron 安装包临时保存在 `.cache/electron-download/`，下载后按 `desktop/runtime-lock.json` 的 SHA-256 校验；安装完成会清理安装包，不依赖全局 npm 安装。 生成过程与预览文件暂存在 `data/jobs/`，点击导出按钮后才向用户选择的位置保存 PNG / 文件夹；导出成功才成为有效历史；上次打开任务额外保留，其他未导出缓存会在关闭时清理。 上述任务目录展示视频任务。图片任务保存 `source.<原扩展名>`、`settings.json`、`previews/original.png`、`images/<原文件名>_cutout.png`、`result.zip`、`job.json` 和 `worker.log`，不生成序列帧或图集目录。 不创建全局 Python、Node、npm、pip 包，不使用全局虚拟环境。Python 搜索路径是相对路径，缓存与模型位置在启动时按项目位置重新计算。操作系统自身产生的临时记录不属于项目依赖。 ## 清理与体积 每次正常关闭工作台，确认停止未完成任务后，窗口会隐藏，程序先停止处理服务，再清理 Chromium 图片缓存，并静默调用本地清理脚本，完成后退出。清理下载包、pip 缓存、预览和测试临时文件、Python 编译缓存、依赖自带的无用测试目录，以及 Electron 多余语言包（保留简体中文、繁体中文和英语）。不弹出命令行窗口。被占用的文件跳过，下次退出继续清理；脚本超过 15 秒会停止本次清理，避免阻止退出。最近一次结果记录在 `.cache/desktop-logs/cleanup.log`。强制结束进程或断电时无法执行退出清理。 根目录的 `清理缓存.bat` 仍可手动运行；运行中会保留浏览器缓存与临时目录。可用 `清理缓存.bat -Preview` 仅查看预计释放空间。 清理保留已导出任务、上次打开的任务、设置与用户导出的文件、`models/`、实际运行依赖、许可证和项目自己的测试。除上次打开任务外，其他未导出任务缓存由处理服务在退出时清理，异常中断时下次启动重试。桌面运行时不再写入 Python 编译缓存；安装依赖时关闭 pip 下载缓存与预编译，并在成功安装后自动执行精简。清理后第一次抠图会重新生成必要的运行缓存。 Electron 桌面引擎、FFmpeg 视频编解码器和 AI 推理依赖仍占主要体积，需要随目录迁移，才能在没有全局环境的电脑上离线运行。 ## 搬到另一台电脑 **离线整目录迁移**：退出桌面工作台，将整个文件夹复制到另一台 Windows x64 电脑，包括隐藏的 `.runtime` 和 `models`。双击 `启动工作台.vbs` 或 `start.bat` 即可。不需要重新安装 Python、Electron 或 Node。可以不复制 `data`，仅保留工具；也可不复制 `.cache`，节省下载缓存空间。迁移到不同 CPU 时可删除 `.cache/numba` 使其重新生成。 **通过 Gitee 下载**：源码仓库不再携带可重新下载的运行环境和模型二进制。首次双击启动时，从 npmmirror / 阿里云 PyPI 下载固定版本的 Python、Electron、依赖和 FFmpeg 到项目内 `.runtime/`；轻量模型准备至 `models/`，大型模型首次使用时从 HF-Mirror 入口按需下载。下载完整校验后复用，已有本地环境和模型不会因 Git 移除跟踪而删除。首次需联网，资源齐全后可离线运行；无全局安装，也不需要用户预装 Python / Node / FFmpeg。 下载来源、固定校验及兼容规则见 [vendor/README.md](vendor/README.md)。仓库保留少量 app-local Microsoft VC++ DLL（约 1.57 MiB）、许可证和下载清单。`.runtime/`、`.cache/`、`data/`、模型及离线分卷均被 Git 忽略。需要离线搬迁时复制已经准备好的整个项目目录。 旧版运行包和模型分卷若已存在本机，可以继续离线复用；后续不要重新加入 Git。移除当前版本中的大文件不会抹掉旧提交，已有仓库仍需单独清理历史才能缩小 `.git` 和完整克隆体积。 ## 启动或环境异常 - 缺少或损坏分卷 / 模型：重新下载完整仓库。启动脚本会报出出错文件，不会联网安装。 - 仅检查或修复环境、不打开桌面：`powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/start.ps1 -PrepareOnly -Verify`。 - 强制从本地包恢复：先关闭工作台，再运行 `powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/restore-runtime.ps1 -Repair`。只替换 `.runtime/`，保留任务、设置和导出文件。 - Windows 10/11 x64 是目标平台；不能将此环境用于 macOS、Linux 或 Windows ARM64。请勿直接在 ZIP 内运行，也不要把工作台放进只读目录。 - `setup.bat` 保留给维护者主动联网重建和升级依赖；普通启动不会调用。升级依赖后需重新打包并提交完整分卷、模型及锁文件。 - 抠图失败可查看对应任务的 `worker.log`。选定时间段无帧、文件损坏、参数越界都会明确报错。 - 任务串行执行以控制内存。取消任务会结束该任务的处理进程树；上次打开的任务可在最近任务中恢复，其余未导出文件关闭后清理。 ## 开发与验证 界面无需构建，编辑 `desktop/ui/` 后重新打开工作台。处理服务与桌面主进程编辑后重启。运行测试： `powershell.exe -NoProfile -Sta -ExecutionPolicy Bypass -File tests/startup_ui.ps1` 可在临时目录验证启动页主题、后台准备期间界面响应、显示主窗口后的交接和启动错误提示，不启动实际工作台或修改用户数据。`-PrepareOnly` 环境检查保持无界面，便于脚本验证。 `tests/launcher_integration.py` 从含空格和中文路径的临时副本实际执行 VBS，验证启动窗口首次绘制早于 PowerShell、主窗口可见后交接，以及失败提示可关闭，并输出从 VBS 入口观察到首次绘制的时间；使用临时桌面替身，不启动用户的工作台。`tests/startup.test.cjs` 验证直接运行 Electron 时的加载页主题与显示、关闭顺序。 ```powershell .\.runtime\python\python.exe -m unittest discover -s tests -v ``` 桌面处理链路冒烟测试（先打开桌面工作台，脚本自动读取内部服务地址）： ```powershell .\.runtime\python\python.exe tests\smoke.py ``` 如需 AI 实测，传入本地人物或物体参考图片：`--ai-image D:\path\subject.jpg`。测试视频和结果放在 `.cache/smoke` 与 `data/jobs`，不会写到系统目录。 `tests/backend_checks.py` 验证损坏视频、无帧时间段、参数限制与取消后恢复（先运行一次 smoke.py 生成测试视频）。退出桌面工作台并复制整个项目后，可运行 `tests/verify_portable.py`；它会临时启动副本内部服务，检查迁移后的完整处理流程并自动关闭测试服务。 `tests/desktop_lifecycle.py` 在临时项目目录验证桌面界面资源加载、关闭接口的权限和父进程退出后的后台清理，不操作桌面窗口。 `tests/export_integration.py` 在临时项目中使用桌面设置模块保存中文自定义路径，再实际生成视频图集，验证生成完成后导出目录保持不变、手动下载 ZIP 可保存，以及导出设置不可用时仍可处理。运行 `tests/settings.test.cjs` 可验证设置持久化、主题与导出路径互不覆盖、无效目录和相对路径迁移；`tests/themes.test.cjs` 检查三个主题的语义颜色是否完整、主要及辅助文字与背景是否达到 4.5:1 的对比度。使用项目内 Electron 的 Node 模式即可： ```powershell $env:ELECTRON_RUN_AS_NODE = '1' .\.runtime\electron\YarSharkerWorkBench.exe --test tests/settings.test.cjs tests/themes.test.cjs | Out-Host Remove-Item Env:ELECTRON_RUN_AS_NODE ``` `tests/image_integration.py` 在临时项目中验证八种静态图片扩展名、透明 PNG、原图尺寸、中文文件名、图片直接下载、自定义导出目录、损坏 / 动态图片报错，并回归 MP4 图集流程。可额外传入 `--ai-image D:\path\subject.jpg` 实测项目内 AI 模型： ```powershell .\.runtime\python\python.exe tests\image_integration.py ``` `tests/protection_integration.py` 在临时项目中验证四种区域的像素保护、RGBA 透明度、方向校正预览、大于 64 KiB 的自由圈选参数、历史图片重处理、清空遮罩及 PNG / ZIP / 遮罩 / 参数文件的导出。可传入 `--ai-image D:\path\subject.jpg` 验证真实 AI 推理。`tests/protection_editor.test.cjs` 检查编辑器的坐标换算、自由圈选、撤销和点数限制；可加入前述 Electron Node 模式的测试命令运行。 ## 依赖来源与许可 运行包保留原始依赖许可证和包元数据；完整来源、VC++ app-local 文件说明见 [vendor/THIRD_PARTY_NOTICES.md](vendor/THIRD_PARTY_NOTICES.md)。 - [Python embeddable package](https://www.python.org/downloads/release/python-31210/)：PSF 许可。 - [rembg 2.0.67](https://pypi.org/project/rembg/2.0.67/)：[MIT](https://github.com/danielgatis/rembg)，模型来自 [U²-Net](https://github.com/xuebinqin/U-2-Net)（Apache 2.0）。 - [Pillow](https://python-pillow.github.io/)：HPND；[NumPy](https://numpy.org/)：BSD；[ONNX Runtime](https://onnxruntime.ai/)：MIT。 - [imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg)：BSD；其内置 [FFmpeg](https://ffmpeg.org/legal.html) 可执行文件具有独立许可。分发整个运行时前应一并保留包内许可证并核对 FFmpeg 的构建许可。 - [Electron](https://www.electronjs.org/)：MIT，Chromium 和其他第三方许可保留在 `.runtime/electron/LICENSE` 与 `LICENSES.chromium.html` 中。 升级依赖后，应重建离线运行包并在全新目录验证。`tests/test_offline_bundle.py` 验证首次解压、复用、缺失与损坏、锁文件 / 模型校验、异常回滚以及路径安全；`tests/offline_distribution.py` 可在已恢复的全新仓库副本中验证离线依赖、实际 AI 推理和各工具处理链路。 ### 图片裁剪 可选择矩形、圆形、椭圆，独立工具与蓝图节点均支持。圆形锁定等宽高，修改任一宽高或拖动边角会同步调整；圆形和椭圆外侧透明，边缘抗锯齿并保留原始透明度。输出仍为 PNG，形状设置随任务、蓝图保存，修改形状后重跑会复用未变化的上游产物。 裁剪框移动按原图坐标吸附至 0.1 px，坐标显示一位小数；方向键移动 0.1 px，Shift + 方向键移动 1 px。宽高保持整数像素，导出位置沿用最近整数像素取整，不插值或改变原始像素。 裁剪工具和蓝图裁剪节点公用同一个裁剪编辑器和自动适配逻辑，支持拖动框内移动、拖动四边和四角修改宽高，以及缩放和 px 标尺。初次载入图片时，两处的默认裁剪尺寸都会缩至原图范围内（例如 548 × 116 px 原料上的 256 × 256 px 默认框会适配为 256 × 116 px）；手动输入过大尺寸时保留用户输入并显示提示，可点击“适应原图”恢复有效选区。 支持单张或批量静态图片。设置目标宽高（像素），在原图预览中拖动裁剪框，或填写 0–1 的水平、垂直位置（0 起点、0.5 居中、1 末端）。批量共用宽高，每张图片的位置独立保存；方向键微调，Shift 加速。裁剪保留原始像素和透明度，不缩放、不补边；目标尺寸超过原图会报错，可先使用图片Resize。输出 PNG，单张导出或批量文件夹；仅手动导出后保存有效任务。 ### 统一图片对照预览 智能抠图、像素化、图片压缩、图片Resize、图片裁剪共用原图/成品分隔预览，左右拖动指针或使用方向键、Home/End 对照。鼠标位于预览框内时直接滚动滚轮缩放，无需 Ctrl；放大后左键拖动画面，双击适应窗口。框外滚轮仍滚动页面。顶部 X 轴和左侧 Y 轴使用图片像素坐标（px），原点为图片左上角，缩放和平移时同步更新；鼠标位于图片内时显示像素坐标。Resize 等工具标注当前成品坐标，裁剪对照使用原图坐标。裁剪预览按原图坐标显示保留区域，编辑裁剪框仍在“调整裁剪区域”页。图集页共用缩放拖动，保留分页与动画。 ### 工具打开方式 启动工作台显示主面板，不自动打开历史任务。从工具箱首次打开工具或关闭标签页后重新打开时，显示空白工具页面；切换已有标签页保留当前文件、参数和任务。需要恢复历史时，手动点击右侧最近任务。最近任务仍只保留已导出的有效任务及全局上次打开的一个任务（无论是否导出），不为每个工具单独保留未导出任务。 工作链功能已移除，旧工作链记录不再进入任务列表；已有任务文件及 `data/workflow-templates.json` 保留在原目录，不参与自动清理。 ### 本地抠图模型 独立“智能抠图”的“本地模型”及蓝图抠图节点均可选择 U²-Net 轻量版（默认）、BiRefNet Lite、BiRefNet General。模型选择随任务及蓝图 JSON 保存；旧任务和旧蓝图默认使用 U²-Net 轻量版。纯色背景抠图不加载 AI 模型。不同节点可选择不同模型，节点执行及遮罩预览按所选模型切换，内存中只保留一个预览模型。 三个模型均使用项目内已有 `rembg 2.0.67`、`onnxruntime 1.22.1` CPU 环境，不需要全局安装、额外 Python 环境或 GPU。权重存放于 `models/u2netp.onnx`、`models/birefnet-general-lite.onnx`、`models/birefnet-general.onnx`，原始文件分别约 4.6 MB、224 MB、973 MB。BiRefNet 的模型加载、推理耗时和内存占用高于轻量模型，运行中会显示所选模型的加载进度。 模型现使用校验固定的镜像按需下载，完整 ONNX 与旧离线分卷均不进入 Git。默认轻量模型首次准备，大型模型首次选用时下载至项目内 `models/`；已有完整模型和离线分卷继续复用。详细来源和校验见 `backend/models.py` 与 `vendor/README.md`。 ### 主面板蓝图 画布空白处按住左键拖动可框选多个节点，右键拖动平移画布；Ctrl / Shift + 左键可增减选择。多选后拖动任一选中节点会整体移动，按 Delete 删除全部所选节点及相关连接。右键平移保留选择，空白处左键单击清除选择；节点端口继续使用左键连线。 蓝图运行后修改参数、素材或连接，会保留各节点上次运行的产物及预览，将受影响节点和下游标记为“待重新运行”；未受影响的上游和分支继续显示原状态。旧产物会明确标注，流程发生处理变更时暂时隐藏最终导出入口，重新运行完成后恢复。修改名称、移动节点、自动布局不影响产物有效性；恢复为上次执行的相同参数和素材也会恢复导出。上次结果的帧率和图集预览按原执行配置显示。重新运行按输入文件内容、节点参数和有序连接复用未变节点，仅重算变化节点及下游；复用节点显示“已复用”。缓存文件缺失、校验失败或此前节点未完成时会从对应节点重新计算。每次任务持有自己的缓存副本，删除旧任务不会损坏新任务。 主面板提供浅色蓝图画布，首次进入为空。节点库以每行三个的方形图标展示，悬停显示名称。点击工具图标打开独立工具；点击图标右上角“+”或拖动工具到画布添加处理节点，文件输入及文件输出也使用方形图标。点击节点库左侧箭头可收起或展开，箭头随状态切换，收起后画布扩展，任务及下载继续；每种节点和工具栏均使用本地图标。拖动节点移动位置，右键拖动平移画布；Ctrl 加滚轮缩放，也可使用缩放、适应画布及自动布局按钮。 处理节点详情采用左侧参数、右侧预览布局；图集生成直接循环播放生成的图集动画，不显示原料对比、分隔指针或原料/产物标签，其余图片处理节点使用原料 / 产物对比，打开详情后直接预览，无需另开产物窗口。左侧原料来自该节点直接收到的上游输入；尚未运行时可预览已选择的图片，产物侧显示等待处理。图集工具页、蓝图节点详情和节点产物窗口复用同一套图集动画适配器与通用播放器；已完成的多张图片也使用该播放器，提供播放 / 暂停、上一帧 / 下一帧、长按连续步进及拖动进度；对比分隔指针、滚轮缩放、放大后拖动及 X/Y 像素坐标轴保持一致。修改节点参数后保留上次执行的原料与产物，并标注旧结果。指针详情展示挂载路径上游节点的对比；文件输入、文件输出仍沿用节点内拖放和导出设置，不进入详情。 图片裁剪节点详情另设“裁剪区域编辑”窗口，显示本节点直接接收的原料。左键拖动裁剪框内部同步调整位置，拖动四边或四角可修改宽高，反向一侧保持不动；拖动尺寸按原图像素取整并限制在原图内，宽高及位置参数同步更新，也可直接填写宽高调整选区；支持居中、方向键按像素微调、Shift 加速、滚轮缩放、右键平移和双击空白复位，X/Y 标尺单位为 px。多张原料可从下拉框切换参考图片，节点共用裁剪尺寸和相对位置；已有上游产物未更新时会明确标注。尺寸超出原料时隐藏裁剪框并提示；运行或暂停中的任务锁定编辑。修改选区不自动处理，点击蓝图“运行”生成新产物，右侧仍可对比上次结果。 从节点右侧输出端口拖到下一节点左侧输入端口建立连接，也支持依次点击两个端口。允许分支和合并，禁止循环；双击节点、点击节点上的“详情”或选中后按 Enter，在节点详情窗口编辑名称与参数，点击删除图标或按 Delete 删除节点及其连接。选择连接后按 Delete 可单独删除。运行要求所有节点形成有效路径，包含文件输入和文件输出，文件类型在处理工具处校验。 文件输入和文件输出没有节点详情。文件输入节点内直接提供大文件拖放区，点击可多选文件，继续拖入会追加；节点右上角可清空。文件输出节点点击即打开导出设置；最终只有一个普通文件时填写默认已填充的文件基础名，直接保存为文件；单张图片可选 PNG、JPEG、WebP、BMP、TIFF、静态 GIF，默认跟随最终产物所属分支最初导入的图片类型（视频来源等不适用时使用产物类型），导出会实际编码转换，不改变缓存产物。JPEG/BMP 透明区填白，PNG/WebP/TIFF 保留透明度，GIF 使用有限调色板和完全透明/不透明。多个最终产物则填写文件夹名称，保存为文件夹。判断依据最终产物数量，一张输入图切分成多张时仍导出文件夹。单文件的“文件名”与所选文件类型组合为最终名称，填写时实时预览。图集导出填写“图集名称”，PNG、plist、JSON、anim 和相关 .meta 共用名称，多页按 -000、-001 添加页码，引用信息同步匹配。图集继续选择 Cocos / Unity、文件基础名及动画选项。流程完成且产物有效时才可导出，保存成功后仍只记录一次有效任务。 文件输入支持多文件。点击运行按连接顺序处理，执行中的节点高亮；选择已完成节点可查看该节点产物，多图和图集动画共用通用播放器。支持停止执行。完成后手动导出，仍只在文件实际保存成功后记录有效任务；最近任务另外保留全局上次任务，可手动恢复并复用原素材重新运行。启动时保持空画布。 文件输入、文件输出右侧提供 **指针**。将它拖到连接箭头附近（屏幕距离 20 px 内），目标线会高亮加粗，松手即吸附挂载暂停点；也可点击指针后点击目标连线。已有指针可拖动到同一条线的新位置或其他连线上，离线松手则保留原位置；指针不能放在空白画布中。双击连线可在连接详情中挂载指针。每条线可挂一个，单击查看详情，双击线上指针即可移除；也可在详情中移除或按 Delete 删除，连接本身继续保留。保存和导入蓝图会保留指针；自动连线保留端点相同的已有指针。 执行到带指针的路径时，上游先完整完成，整条蓝图随即暂停，其他分支也等待。指针高亮，指针详情中可“查看上游产物”；多图和图集继续使用通用播放器。顶部“运行”变成“继续”，点击后在同一个任务中从暂停位置执行，不重做已完成节点。暂停时处理进程退出并释放执行队列，其他独立工具可继续工作；停止按钮可取消暂停任务。暂停位置和产物校验信息保存在该任务目录，保留为全局上次任务时可在重启后手动恢复并继续。暂停本身不会导出或记为有效任务；仍需最终导出成功后记录。 顶部“自动连线”按节点从左到右、同列从上到下的顺序重新连接相邻节点，不移动节点、不调整缩放。现有连线会替换成该顺序的连接；若输入 / 输出端口或类型不兼容，会提示具体节点并保留原连线。运行或载入蓝图期间不能自动连线。 在右侧名称框填写蓝图名称，点击“保存蓝图”会保存到工作台本地 `data/blueprints/`，不再弹出文件保存窗口。顶部“已保存的蓝图”下拉框列出本地定义，选择后自动载入节点、位置、参数和连接；旧版本已保存于该目录的蓝图也会列出。载入后再次保存更新同一份蓝图，修改名称也更新当前记录；点击“新建蓝图”后保存则新增一份。重启后本地列表保留，画布仍默认空白，不自动运行或载入历史任务。若当前画布有未保存修改，载入其他蓝图前会确认是否放弃修改。 “导入”继续读取外部 JSON 文件，导入后可点击“保存蓝图”加入本地列表。定义不包含输入素材或处理产物，载入后需重新选择素材；保存定义本身不记为处理任务，也不清除当前画布的素材和产物。最终输出含图集时，导出窗口选择 Cocos / Unity 并填写名称；文件直接保存在所选文件夹根目录，混合输出的其他文件保留在 `outputs/`。纯图片等批量产物同样导出为文件夹。旧工作链仍保持移除，独立工具通过节点库的工具图标按钮进入，右侧“+”用于添加蓝图节点，已有工具标签页继续保留状态。 ### 导出文件命名 所有导出均弹出保存窗口，并预填建议名称；初始目录取设置中的导出路径。单张图片和蓝图 JSON 直接保存文件，批量图片、视频抽帧、图集和蓝图处理产物直接保存为命名文件夹，不向用户导出 ZIP。图集文件直接位于导出文件夹根目录，不再附加 cocos 或 unity 一层。目标文件夹重名时需换一个名称，以免覆盖已有文件；取消或失败不会记录有效任务，完整保存成功后才记录。 格式参考：[Cocos Atlas](https://docs.cocos.com/creator/3.4/en/asset/atlas.html)、[Unity 官方多 Sprite 纹理元数据示例](https://github.com/Unity-Technologies/2d-extras/blob/master/Samples~/PipeRuleTile/Sprites/Pipes.png.meta)、[Electron 保存对话框](https://www.electronjs.org/docs/latest/api/dialog)。 ### 图集按引擎导出 独立图集工具、历史视频图集和蓝图最终输出含图集时，点击导出先选择 **Cocos Creator / Unity**，再填写统一文件基础名（默认 `YarSharker`，无需扩展名）。文件夹只包含选中引擎的文件，不附加引擎子目录；单页为 `YarSharker.png`，分页为 `YarSharker-000.png` 等，配套清单为 `YarSharker.json`。多个图集会按编号放入独立子目录，混合蓝图的其他最终文件保留在 `outputs/`。 Cocos 选择项目实际 Creator 版本（完整 `2.4.x` 或 `3.0.x`–`3.8.x`）。勾选“同步生成 .anim 文件”后，导出 PNG、原生 `.plist`、JSON、`.anim`，以及维持 SpriteFrame UUID 引用所需的 `.meta`。2.4 使用 `curveData`，3.0–3.5 使用旧曲线序列，3.6–3.8 使用 ObjectTrack；帧序与帧率沿用处理结果，默认循环。导入时将导出的整个文件夹复制到 Assets，保留所有 `.meta`；动画作用于当前节点的 `cc.Sprite.spriteFrame`，需在该节点上添加 Animation 组件并指定动画。Unity 导出 PNG、Multiple Sprite `.png.meta` 与 JSON。 版本格式与资源结构依据 [Cocos 官方 2.x 示例](https://github.com/cocos/example-projects/blob/master/assets/res/animation/sheep_run.anim)、[3.0 示例](https://github.com/cocos/cocos-test-projects/blob/v3.0.2/assets/cases/ui/13.sprite-anim/run.anim)、[3.6 示例](https://github.com/cocos/cocos-test-projects/blob/v3.6/assets/cases/ui/13.sprite-anim/run.anim) 与 [3.8 示例](https://github.com/cocos/cocos-test-projects/blob/v3.8.7/assets/cases/ui/13.sprite-anim/run.anim)。不同小版本可能升级导入器元数据；目前完成文件结构、引用关系及下载流程测试，尚未在安装的 Cocos Creator 编辑器中逐版本实际导入验证。 导出转换在临时目录进行，不改写处理缓存及蓝图增量复用标记；选择选项、取消保存、仅下载请求本身均不会记作有效任务，桌面端确认保存完成后才记录。 ### 所有预览窗口的像素坐标轴 图片处理、视频抽帧、图集及动画、蓝图节点产物、遮罩编辑和原视频预览统一显示顶部 X 轴、左侧 Y 轴，单位 **px**，原点是当前素材左上角。空白或加载中的预览保留轴方向及单位，素材可用后显示真实刻度；缩放、平移、调整窗口或切换不同尺寸的帧时同步更新。鼠标停留在图像内显示 X/Y 像素位置。裁剪对照使用原图坐标；遮罩播放即使使用缩小的预览缓存，也按原始素材尺寸标注，保护区域仍按原有规则编辑。 ### 所有预览统一使用原料 / 产物对照 除图集动画外，图片预览框都有可左右拖动的分隔指针，左侧为原料，右侧为当前产物。可用方向键微调、Home/End 查看任意一侧；空白预览也保留指针，尚未生成的右侧显示“等待产物”，无法读取原料时明确标注，不拿成品冒充原料。图片处理、视频抽帧、蓝图图片节点、遮罩编辑和原视频窗口使用同一套对比分隔与 px 标尺；图集生成只播放动画，保留 px 标尺、缩放、拖动和完整播放控制，不加载对比原料。缩放和平移对两层同步生效，切帧保留指针位置；遮罩窗口继续使用原有绘制和平移工具，拖动指针不会画入保护区域。 蓝图左侧使用该次执行中当前节点的直接输入，保留旧产物预览时沿用旧参数。图集动画按清单顺序还原被裁紧的帧，在透明画布上播放，跨多页图集仍按统一帧顺序展示。视频原料使用相同起始时间与 FPS 过滤器一次预备匹配帧（预览最长边 768 px），播放器等待当前帧两侧就绪再展示，避免错帧；原视频窗口按时间选择对应的抽帧产物。输入/产物尺寸不同的对照按同一显示区域对齐，裁剪对照继续保留原图位置。 派生原料预览放在对应任务的 `comparisons/` 中，随任务删除清理，关闭软件时也会清理这些派生预览；不改变处理产物、增量节点缓存或导出包；查看与拖动指针不记作有效导出。 首次启动下载失败时，会自动重试并切换备用镜像：Python 使用 npmmirror / 华为云，pip 引导包使用阿里云 / 清华镜像；Electron 支持 npmmirror / 华为云备用来源，模型下载也支持网络错误重试。所有下载仍按固定 SHA-256 校验。失败提示会包含资源名称、HTTP 状态或校验原因，详细记录位于 `.cache/desktop-logs/downloads.log`。检查网络后再次双击启动入口即可重试，已校验成功的下载包会复用，无需删除整个环境。 加载页下载时显示当前文件、已下载/总大小、文件下载百分比和实时速度（KB/s、MB/s），覆盖 Python、pip 引导包、Python 依赖、Electron 和首次准备的模型。无法取得总大小时显示“大小未知”，不显示估算百分比；网络暂时没有数据时显示 0 B/s。校验、安装阶段与下载阶段分别提示。更新加载页源码后须重新运行 `scripts/build-launcher.ps1`，同步根目录 EXE 到其他电脑才能生效。 启动加载页支持“取消启动”；取消或强制结束启动器时，Windows 会停止本次环境准备及其下载子进程，释放环境锁。重复启动会回到已有加载窗口。下次准备时会识别同一项目中已失去父进程的旧准备任务并清理其进程树；其他仍在运行的准备任务会明确显示等待状态，最长等待 45 秒后给出提示。环境检查显示文件计数；未完成环境不会被当成已就绪环境，已缓存且校验通过的安装包可继续复用。