# 复用清单 ## 内容与骨架的显示边界 馆藏网格复用 `catalog-grid` 的视口测量和无限加载,首批条目不等待聚合统计;`summary_only=1` 独立读取同口径总数。人物资料先显示身份,作品、照片与新作分别加载;图片等待留在各自的图片格。关注凭据、订阅统计、任务状态与来源信息不阻挡已经取得的主内容,未取得的读数保留占位,操作仍等对应状态确认。 馆藏网格、表格、播放舞台和表单继续复用 `fitSkeleton`、页面模板、`SkeletonContent`、`AsyncText` 与已有形状记忆。[Skullet](reference-snapshots/skullet-content-first.md) 固定为 `0.0.3`,仅在关注概览的六个只读读数中自动测量和记忆形状,随低频页面按需加载。数据就绪即显示,150 ms 仅用于抑制骨架闪现,不延迟真实内容;首次失败显示「未取得」,后台重读保留已有值。 `MeasuredReading` 只接收固定字段、数值与总数;隐藏样本不含请求、Portal、媒体或操作控件。上游持久化填充不替换中文,因此不传入作品名、路径、自由文本或用户资料。微光通过 Shadow DOM 的构造样式表复用 Peach 配色和节奏,减少动效时静止;外层隐藏规则兼顾不支持 `@scope` 的浏览器。原位编辑在骨架之外,形状调试沿用上游 `skullet-debug` 参数;不在大列表的每行创建测量边界。 数据管理的复核计数与完整复核页共用按候选文件版本和账本依赖表失效的精确成员快照。计数不加载卡片旁证、图片和预览;完整卡片先深复制成员,再补展示字段,不能改写共享快照。来源番号身份判断只在同一次投影中复用,来源标识不同仍分别核验;批准仍重新读取原始候选与最新账本。 ## 账本一致性与运行状态恢复 名册资料删除复用 `entity-batch`、名称菜单和批量确认契约,同一弹窗提供仅删资料、馆藏进回收站、永久删除全部三个范围。`web_entity_deletion` 绑定身份、作品范围和媒体路径生成计划,复用 SQLite 备份、字段归属写入与复核历史表,显式清理实体引用。永久删除复用 `stage_purge`、`commit_purge` 和清理回执,未删完的档案保留。头像按批次归档,事务失败时恢复。 删除执行键共用 `attachHoldToConfirm`,React 通过 `HoldButton` 或 `HoldActionButton` 组合既有按钮。按满两秒才提交一次,提前松开、移出、失焦或进入忙态时取消。范围说明沿用确认弹窗,多个删除范围使用 `confirmModal.choices`。填充与复位参考见 [长按删除取证](reference-snapshots/emil-hold-to-delete.md)。 资产删除与个人记录归入复用 `purge_assets()`、`record_rehome.move()` 和既有快照撤回机制,显式维护 `follow_item.asset_id`,不依赖运行连接的外键开关。稍后看沿用偏好写入的事务内资产存在性检查。关闭外键的迁移在提交前检查引用,数据、结构和版本登记一同回滚;备份恢复在暂存升级后及写回后补验外键。 后继结算与升级派发沿用 `TaskRunStore.prune()` 的保留入口,后继的失败项继续保留以供重试;任务历史清退时保留下载状态并清空过期运行链接。恢复旧备份后按任务类型及下载任务的互斥键、后继键核对链接,避免编号复用接到其他任务。迁移 0052 为任务根引用和关注资产引用建立索引,将任务删除清理拆为分别按两列查询,并移除已被现有索引覆盖的四个旧库索引。 自动关注与订阅调度复用 `FollowUpdateScheduler`、APScheduler 和原子状态文件,保存失败次数、运行结论及下次时间;来源冷却在 `FollowMediaResolver` 中以绝对截止时间保存,重启后换算为当前单调时钟。成功检查重置持久失败状态。日期番号的身份审计按资产番号解释 `date-code:<资产 ID>:<字段>`,命名空间不参与来源番号比较。以上均复用标准库与已有依赖。 ## 活动任务速度与分页 任务档位复用 `ProcessingControl` 的低占用、标准、全速参数以及 `TaskRunStore`、`task_control` 的任务归属、后继关系与安全停点。默认档位通过既有设置接口保存,任务创建时固定本轮选择,逐任务改速使用独立原子状态文件;清退任务时回收对应状态。HTTP、媒体探测和 FFmpeg 消费同一档位,已启动媒体步骤的线程选项在下一步骤应用。 活动页复用 `ProcessingMode`、`DataTableFooter`、`Disclosure`、`CollapseRegion` 和现有 Sonner 通知栈。历史与云下载查询沿用既有排序,补充总数、页码与偏移;原游标接口继续服务既有调用方。实现没有新增外部依赖。 ## 跨平台任务资源计量 继续使用 psutil 7.2.2 读取进程 CPU 时间和身份。该版本的 macOS 线程列表使用序号,不能与 Python 原生线程 ID 对应;因此使用系统 `libproc` 的 `PROC_PIDTHREADID64INFO` 取得指定线程的纳秒时间,接口与单位见 [XNU 实现](https://github.com/apple-oss-distributions/xnu/blob/main/osfmk/kern/bsd_kern.c)。Linux 的可用 CPU 容量复用亲和性、控制组成员和挂载信息,按可见 cgroup v1/v2 配额归一化。 Linux GPU 读取 [DRM fdinfo 标准](https://docs.kernel.org/gpu/drm-usage-stats.html)的客户端、设备和引擎忙碌时间;重复描述符去重,计数回退保持高水位,进程重用重新采样。容器沿用当前设备与 PID 命名空间,不要求宿主 PID 权限。macOS 和未提供该计数的 Linux 驱动明确显示未取得,不使用整机 GPU 占用替代任务。实现只调用系统接口,无新增依赖;测试覆盖平台接口、配额、权限、重复客户端和原生线程时间增长。 ## 数据管理层级 数据管理首页按待处理事项看板、扫描与采集、整理与维护、清理与删除排列。日常扫描直接操作,其余工具在独立二级页展开表单和清单;首页只读摘要。工具名称、顺序和地址由 `frontend/src/cleanup-tools.ts` 供首页、路由、面包屑与加载态共用。已分享的工具锚点转到对应二级页,保留查询参数。 数字驱动的人工复核、重复文件、垃圾文件、高清版和回收站在顶部组成看板,复用 `PlainStat` 的大数字样式。整理、维护和批量删除共用 `CleanupEntryCard` 的功能入口样式;首屏加载态复用同一套卡面。入口不执行删除,危险样式留给二级页的执行按钮和确认窗口。 ## 按女优删除影片 数据管理页的「批量删除」复用 `DataTable` 的排序、分页和跨页勾选、女优名册的姓名与头像装配、`confirmModal()`、`purge_assets()` 和缓存清理入口,不新增依赖。`/api/performer/delete-plan` 按所选实体 ID 的并集列出全部视频,包括回收站记录;多人共同出演的文件去重。隔离媒体前和删行的写事务里各核对一次清单摘要,关联、路径或记录版本变化时拒绝旧清单并放回已隔离的文件。永久删除沿用媒体先隔离、账本失败恢复、文件失败保留记录的顺序,保留女优档案、照片与其他人物的独立影片;多人出演的同一文件会从所有关联人物的作品中消失。 ## 教程中心与界面导览 复用 [Driver.js](https://driverjs.com/) `1.10.2`(MIT)的遮罩、箭头和边缘避让,正文与操作复用 Peach 的 React、BoardUI 和弹层组件。步骤绑定组件锚点,布局变化调用 `refresh()`;设置路由复用当前路由定义。教程状态复用账本 `profile.settings_json` 和现有读写事务,通过 `/api/tutorial-progress` 按动作更新,所有设备共用。入口、提示版本与维护边界见 [教程中心](ONBOARDING.md)。 ## 首页筛选聚合与缓存 采用 bbingz 的 [PR #205](https://github.com/peach-mitao/peach/pull/205),固定来源提交 `bbf5aac8e9562211c324c2019bff35888266df84`,许可证沿用本项目 AGPL-3.0-or-later。作品筛选集合先在独立子查询中求出,创作者、标签和演员按既有关系聚合,保留去重计数与标签可见性。没有选中标签时移除无效 `tag_match`,复用既有修订缓存、同键锁与跨连接写入失效机制,不在线改写 SQLite 统计或增加索引迁移。 顶部人物、厂牌的 `q_tops` 复用同一筛选方式:独立求出可用作品集合,再按实体聚合,保留代表作选择、种子抽样、续页和修订缓存。错误统计回归使用临时账本、冷缓存与新连接,按作品数量限制判定调用量,核对默认、JAV、已看及组合范围的输出等价。运行时不写 ledger,不改 SQLite 统计或索引。 头像匹配的 Gfriends 本地索引复用标准库 `lru_cache`,仅保留当前文件身份的解析结果。文件身份包含修改时间、变更时间、大小与文件编号;更新或原子替换后重读,缺失与解析失败沿用既有处理。匹配端只读共享结果,后台刷新与来源优先级保持同一实现。 实体页形状的全库查询按资产展开关系,以存在性判断同台人物;单实体深链沿实体索引读取。全库版本缓存与声明表范围的缓存共用按键计算锁,计算期间的提交由下一次修订核验处理。复用现有 SQLite 查询与聚合缓存,不增加索引、迁移或运行依赖。 采纳 [PR #298](https://github.com/peach-mitao/peach/pull/298) 的后端查询与解析差集:SQLite 纯分类回调按账本实例复用有界结果,库根分类仍沿用当前 `sql_is_local_extra`;馆藏的总数、体积与作品数按筛选集合及媒体根缓存,排序与分页共用。统计在依赖表变动后同步重算,避免新列表配旧统计。卡片展示顺序、统计加载时机和前端布局沿用当前实现。 ## 混合媒体根与模型读取 馆藏采集复用 `platform.within_root` 的 SMB 根身份判断,本地路径保留字面归属比较,不逐影片访问挂载目录。STRM 是链接文件,其大小和推广名不作为远端影片的垃圾证据;垃圾队列读取时重新评分,既有人工决定与回收站记录保持原样。 YuNet 与 SFace 沿用既有模型哈希校验,Python 读取模型字节后交给 OpenCV 的 ONNX buffer 入口,避免 Windows 原生文件读取对非 ASCII 路径的限制。没有新增模型副本、依赖或路径重试。隔离验证用同一哈希的模型分别从普通路径与中文路径加载,并用合成数组执行检测和特征计算。 ## 浏览器添加的本地人物资料 `/api/jav-browser/people` 复用现有专用令牌与浏览器权限检查、规范实体关联和男优排除判据。人物名只读本地账本与发现资料快照;查询单个番号时还可带上详情页的出演者名字,只在账本与快照都没有人物时使用(素人作品入库后账本记真名、页面仍写店铺艺名,不能算成两人),按既有 `resolve_entity` 先规范名后唯一别名匹配,括号里的别名一并尝试,未匹配的只返回名字。头像通过既有 `PreviewService.entity_image` 查找已安装文件,按 `avatar_focus` 的人脸记录沿用 `frontend/src/card-art/face-frame.ts` 的放大与夹持判据取景;已有 Pillow 将其在内存缩为 64px JPEG,不落新头像、不抓外站。未初始化发现资料服务时直接读取快照,避免初始化恢复外站任务。缺头像省略图片字段,缺人物信息返回空数组,接口失败与正常缺失分别反馈。用户脚本显示灰底首字母,不显示作品封面,无新增依赖。 ## README Star 图 `scripts/render_star_history.py` 自行生成,只用标准库与 GitHub CLI,不新增依赖。数据来自 GitHub 原生公开 Star 历史:每周一条记录,其中 `days` 是逐日新增。脚本按日累计,横轴从第一个 Star 当天开始,到生成时刻为止;建库到第一个 Star 之间的空白期不画。曲线用单调三次插值(与 d3 `curveMonotoneX` 相同),不画出回落,也不越过下一天的累计值。画面保留蜜桃色霓虹描边、渐变填充、线性绝对值坐标和浅深双主题。脚本不补造缺失记录,也不把历史累计增加数当作完整取消 Star 的净变化账本。 此前复用 [Star Chart](https://github.com/leereilly/star-chart) v0.3(MIT,固定提交 `e7fa78bdf8f78da6c3feeb3a97b528fd97d62727`)。它只按周累计,不使用 `days` 字段,因此一周内的增速起落会被抹平:2026-10 的单周一万多个 Star 只能画成一级台阶或一段斜坡。调列数改变不了时间粒度,所以改为自行渲染。 独立 `Star History` 工作流每日生成 SVG,只在 `star-history` 分支保存产物,不触发主线测试或阻塞发版。静态 SVG 发布思路参考 SakuraMedia;未复制其受 PolyForm Noncommercial 约束的生成脚本。 ## 复核字段筛选与文本差异 复核文本差异复用 [jsdiff](https://github.com/kpdecker/jsdiff) 的 `diffChars`,前端精确固定 `diff@9.0.0`(BSD-3-Clause,自带类型),按 Unicode 码点比较并仅展示当前文本中的差异片段。当前值和候选相互对照,尚无当前值时对照其他来源;来源依据只比较同名字段。Peach 保留参照选择、语义高亮与字段筛选,不自行实现通用差异算法;原始候选值、提交契约和 ledger 均不改变。 ## 任务历史关联清理 采用 RAAMENN 的 [PR #151](https://github.com/peach-mitao/peach/pull/151),固定来源提交 `eb5f6b49210ed330c767166ea204103a8193250a`,许可证沿用本项目 AGPL-3.0-or-later。复用 SQLite 的 `SET NULL` 语义和删除触发器,在外键开关两种连接下维护父任务与根任务关联。当前迁移编号为 `0049`,只清空不存在的任务引用;任务内容、有效关联、活跃后继和媒体记录保留。隔离回归覆盖旧库升级、重放、批量删除回滚及跨任务类型后继,无新增依赖。 ## 馆藏任务取消、范围与问题导出 取消复用 `ProcessingControl` 的本机原子记录、安全停点与 `BackgroundJob` 结算;`stopping` 等待在途工作退出,`cancelled` 保留结果并阻止自动恢复。安装暂停与用户暂停沿用原语义。新影片范围复用 `ScanResult.new_ids`、`filelock` 和原子 JSON,接回旧扫描检查点;启动时固定为已有的 `asset_ids` 请求,恢复不重新计算范围。退场资产仅退出当前重试集合,来源离线不按文件消失处理;归档只保存提示选择,不删除问题原文或任务历史。 问题导出采用 kevin552216 的 [PR #172](https://github.com/peach-mitao/peach/pull/172) 中 `issue-export.ts` 的分页 JSON 下载思路,固定来源 head `d1803c28e0b1a2a086d9756a67b0ec313387db29`,AGPL-3.0-or-later。Peach 增加日志内容摘要、总数和页偏移校验,拒绝同任务恢复时混合两份记录;旧完整 `issues` 数组可分页读取,缺失或损坏日志不伪装成空清单。复用既有 `useAction`、AbortSignal 和 Blob 下载,不采用该 PR 的单片重抓、字段保护和来源策略改动,无新增依赖。 状态文件写入沿用 `fsutil.atomic_write_text`。补入 FriendlyPasser 的 [PR #120](https://github.com/peach-mitao/peach/pull/120) 固定提交 `b586ff907aa01b48432e51b6101b7ce4bc7f8126` 的 Windows 读句柄验证,检查实际 WinError、读者关闭、完整 JSON 发布和临时文件清理;不增加另一套保存策略。 ## 发布依赖接管来源 依赖清单复用 Dependabot 的独立 PR 差集,版本与完整依赖图由当前清单和锁文件确定。相邻修改保留主线消费者并重算锁;npm vendor 与前端包使用项目入口重建,许可证和来源记录随资源分发。接管器分别识别应用与 amane 桥的清单,并以实际接管提交确认完成;普通 PR 引用不构成采用。 | 来源 PR | 固定来源提交 | | --- | --- | | [#129](https://github.com/peach-mitao/peach/pull/129) | `f8899d626f8ef2b4f3c959eb7668ea3c25c56a16` | | [#133](https://github.com/peach-mitao/peach/pull/133) | `28fb1b8d748183aeb1a912f7c9ef01d9c34cfe09` | | [#147](https://github.com/peach-mitao/peach/pull/147) | `1c436adf6db7105b63306f06bea7f2f2653c50bb` | | [#148](https://github.com/peach-mitao/peach/pull/148) | `6de7bd0767d68434297664597caa18e41601a878` | | [#149](https://github.com/peach-mitao/peach/pull/149) | `eeed8f01cf935574398af2080114f29263fb6274` | | [#179](https://github.com/peach-mitao/peach/pull/179) | `366740dae787c056762afd59c21400d060d1edb0` | | [#180](https://github.com/peach-mitao/peach/pull/180) | `c352663209ced88201679727c87539ff12f41980` | | [#181](https://github.com/peach-mitao/peach/pull/181) | `6611fc77d7ecac7c9e805b508e183a9468f99c28` | | [#182](https://github.com/peach-mitao/peach/pull/182) | `7394cfeab955cbcb0640f57f10e93ae768045fc8` | | [#183](https://github.com/peach-mitao/peach/pull/183) | `437f96d76c14c5fe0a00450a6b3a83b3731811d1` | | [#184](https://github.com/peach-mitao/peach/pull/184) | `3e8960f79220fc29ffe68b5d7aff5ac9f9d88611` | 注册表稳定版本检查补充 FastAPI、Starlette、tzlocal、Sentry 构建依赖和 Python 镜像的更新。Pillow 的兼容与安全说明按[官方发行说明](https://pillow.readthedocs.io/en/stable/releasenotes/13.0.0.html)核对;运行依赖 amane 固定官方稳定版,并按[上游复核](reference-snapshots/upstream-review.md)适配登录失败分类。更新只替换代码、运行环境与构建资源;既有资料继续遵守原字段保护与升级修复契约。 源码与 wheel 的桥安装回执绑定完整依赖锁的 SHA-256;缺少标识或标识不符时,复用现有安装锁和 `uv sync --locked` 重建工具环境,并在离线类加载自检通过后写回执。同一 amane revision 的传递依赖升级也能生效;随包运行环境继续由构建入口按锁生成,不重置媒体、配置或资料。 主应用与独立桥环境共同固定 `curl_cffi 0.17.0`(MIT),采用[官方安全发行说明](https://github.com/lexiforest/curl_cffi/releases/tag/v0.17.0)中的内置 Brotli 1.2.1、证书库及 Windows 撤销列表修正。原生传输在测试中读取实际 libcurl 版本,核对内置 Brotli 的安全版本;Python 的独立 Brotli 包与 libcurl 自带的解码器分别验收。Peach 沿用现有代理、指纹、TLS 和来源边界,不引入 WebSocket 或账户能力。 ## 全屏视频比例 采用 simon1561 的 [PR #155](https://github.com/peach-mitao/peach/pull/155),固定来源提交 `7ee5f2d6e0da03983fe943cb8179bee69c4f5639`,许可沿用本项目 AGPL-3.0-or-later。全屏适配复用现有 CSS `object-fit: contain`,原生全屏、播放器全屏类、属性与 full-window 回退使用同一规则;页面外框、控件和媒体管线保持既有契约,无新增依赖。 社区浏览器用例核对源码及构建样式,在 4:3、16:9 与手机竖屏下检查全屏及退出状态。Windows 由现有完整浏览器入口执行,macOS 的独立入口只加载画面比例用例,不重复运行 Windows 那一份。代码及样式资源替换即可生效,无存量数据转换;视口模拟不代替折叠屏实机验收。 ## 双栈监听与 IPv6 局域网发布 监听复用 uvicorn 0.54.0 的 `Server.run(sockets=...)`:Peach 用标准库 `socket.create_server(dualstack_ipv6=True)` 预先绑好一个双栈 `::` 套接字再交给它,因为 uvicorn 按 `host` 只建单栈套接字,asyncio 的 `create_server` 也会给 IPv6 套接字强制打开 `IPV6_V6ONLY`。代理头仍由 uvicorn 自带的 `ProxyHeadersMiddleware` 处理,信任口径与 uvicorn 默认一致;来源判断用标准库 `ipaddress`。网卡前缀与地址用 `ifaddr==0.2.0`(MIT),它本来就是 zeroconf 的传递依赖,这次改为显式固定,不增加分发体积。 Windows 与 Linux 的 AAAA 记录由 zeroconf 0.151.5 的 `ServiceInfo` 多地址发布,`Zeroconf()` 全网卡监听语义保持 ADR-0009 的已验证基线。macOS 沿用 `dns-sd -P`,它只接受一个地址,因此只发布 A 记录。 Peach 自己负责的部分是局域网来源策略:IPv6 只接受回环、链路本地、ULA、本机网卡同一 /64 前缀,以及 `PEACH_LAN_IPV6_PREFIXES` 列出的前缀。2026-10-29 在一台有运营商 IPv6 前缀的 Windows 10 主机上,用真实套接字验证 IPv4、IPv6 回环与全球 IPv6 地址都能连到同一个 `::` 监听,zeroconf 发布 A 与两条 AAAA,系统解析器取到 AAAA 后经 IPv6 访问成功。Docker 默认网络与关闭 IPv6 的容器都绑得出 `::`,IPv4 映射正常;开启 IPv6 的网络里,容器能看到客户端的 IPv6 来源。 ## 叶子证书密钥标识与存量补签 采用 peach-patcher 的 [PR #177](https://github.com/peach-mitao/peach/pull/177),固定来源提交 `62927d4b975bdad3420ef214bc9330382a4233d6`,许可证沿用本项目 AGPL-3.0-or-later。运行期与两个 TLS 设置脚本复用 OpenSSL 的 [`subjectKeyIdentifier` 和 `authorityKeyIdentifier`](https://docs.openssl.org/3.0/man5/x509v3_config/#authority-key-identifier) 扩展,显式签入叶子证书;标准库 [`ssl.create_default_context`](https://docs.python.org/3.14/library/ssl.html#ssl.create_default_context) 的严格验证策略保持启用。现有签发工具随运行环境提供,无新增依赖。 `certs.reissue_reason` 将缺少 AKI 的叶子证书交给已有补签流程,CA 和已安装信任保持原样;合格叶子沿用 SAN 与到期判据。存量回归采用临时 CA、缺 AKI 的有效叶子、真实严格 TLS 握手和补签后重复检查,核对 CA 保留及叶子备份。社区用例按 OpenSSL 与 LibreSSL 的缺标识签发行为适配,不用跳过测试代替存量验证。未采用 mkcert 或新增 X.509 编码库,现有工具已覆盖签发能力,Peach 仅保留 CA 生命周期和补签策略。 SAN 读取使用两种工具均支持的 `x509 -text`;POSIX 设置脚本允许仅签发本机名称和回环地址,并以成功状态结束。两种签发脚本通过实际执行与严格握手回归验证,不依赖扩展配置的源码字串断言。 ## 测试规划与阶段计时 `scripts/test_resume.py` 的 `ImpactPlan` 在一次恢复规划内缓存域集合、测试导入图与路径影响;调用方用当前快照创建计划,检查点输入改变时重新计算。`scripts/test_runner.py` 的 `local_batches` 统一快速检查、普通分片和内部并行容器的执行顺序,`scripts/test_run_progress.py` 的 `phase` 将阶段墙钟写入正式测试记录。沿用标准库与现有单项证明协议,不改变证明有效期、环境身份或完整批次要求。使用范围与计时口径见 [测试与 CI](TESTING.md)。 ## 首次设置分步框架 首次设置、已有数据恢复与完成态共用 `frontend/src/react/pages/setup/setup-scene.tsx` 的分栏框架。媒体库卡片复用配置页的图标、来源色、处理方式及目录控件,访问范围使用 `ConfigurationChoice`。场景布局参考和来源见 [取证记录](reference-snapshots/arion-onboarding.md),设备素材见 [素材说明](../resources/setup/README.md)。没有新增运行时依赖;提交、校验和源码文案编辑沿用现有入口。步骤标题、场景说明和操作区随步骤独立挂载,防止文案草稿映射串到其他步骤。 独立页面的编辑工具条共用 `components/selection-dock.css` 与 `batch-dock/batch-dock.css`,由 `pages/copy-editor-page.css` 将页面的 BoardUI token 对应到工具条 token,并为页面底部留出空间。编辑器核心及官网、演示站同步产物不涉及本次样式接入。 ## 扫描路径冲突隔离 路径归组复用 Python 3.14 标准库的 [`PureWindowsPath`](https://docs.python.org/3.14/library/pathlib.html#general-properties) 与现有大小写口径,入库复用 SQLite 的 [UPSERT](https://www.sqlite.org/lang_upsert.html)、扫描检查点和单路径摄取入口,未新增依赖。两者均由现有运行时携带,许可与版本沿用运行时声明。路径相等不决定个人记录归属,Peach 负责将歧义组交给现有任务问题清单,保留每条身份及处置,只更新实际观察到的文件时间;不另建路径解析器或自动合并器。 隔离回归使用临时账本与目录,覆盖大小写和斜杠变体、个人记录保留、缺失文件、多根目录、断点配对和自动发现。真实 ledger 未用于修复演练,部署与报告者验收分别记录。 ## 媒体库查询范围与详情类型 React 与应用层的 GET 入口共用 `frontend/src/core/library-scope.ts`:目录和筛选读取当前媒体库,调用方显式提供的 `library` 参数优先,空值表示全部媒体库。查询参数识别复用浏览器原生 `URLSearchParams`,不增加依赖或持久缓存。媒体库选择沿用整页导航,详情按资产 ID 查询并返回账本中的 `medium`,不从文件扩展名推断类型。两项契约随代码与构建资源替换生效,无需数据转换。 ## 升级自动处理与更新提示 本地补修复用 `catalog_rules` 的用户识别规则、`field_owners.write_owned_fields`、r18 文字修复与复合别名拆分判据。两个维护脚本调用同一领域模块。结构迁移、SQLite 备份、文件锁和原子回执继续使用项目现有入口;后台复用 `TaskRunStore`、`FollowupRunner`、`Attempts`、来源冷却和影片处理检查点,未新增运行依赖。 派生图复用现有生成锁与原子替换,按规则、来源身份及文件代际记录签名。版本快照复用已有发行版检查与独立包安装状态;页面提示使用 BoardUI 和项目 Banner,文案编辑使用现有源码保存入口。脚本在独立维护源构建后经正式导出器同步,其元数据检查复用脚本管理器 API 和可信发布入口。运行方式与故障恢复见[升级后的自动处理](OPERATIONS.md#升级后的自动处理),决策见 [ADR-0126](adr/0126-upgrade-effective-repairs.md)。 ## 正式测试记录与中断恢复 交付预检复用已有的提交主题与共同署名检查,不新增规则解释器。合入前的 PR 身份复用 [GitHub CLI 的 `gh pr view`](https://cli.github.com/manual/gh_pr_view),使用工作树仓库上下文和原生 JSON 字段;Peach 只校验开放状态、精确提交及目标分支,不引入 GitHub SDK 或另一套凭据存储。临时 Git 工作树回归覆盖未取得 PR、旧提交、其他目标、远端查询期间内容变化及成功合并回执。 测试结果继续复用 Python ≥3.14 标准库 `unittest`、`hashlib`、`json` 和项目的内容快照、影响域映射与外部测试结果。互斥复用既有 `filelock 4.2.0`,分片退出后回收其进程树复用开发依赖 `psutil 7.2.2`;版本与许可沿用锁定依赖及第三方许可清单,不新增运行时依赖。整机测试名额(ADR-0172)同样用 filelock 文件锁与全量锁的排队票实现,不另引入信号量库或调度服务。Peach 保留输入身份、逐文件覆盖、完成报告、批次来源和 `ready`/`integrate` 验收规则;串行、并行、浏览器与 Vitest 使用同一个恢复模型。 CI 跨作业恢复使用 GitLab Runner 19.5 的原生 [缓存](https://docs.gitlab.com/ci/caching/) 与 [`cache:when`](https://docs.gitlab.com/ci/yaml/#cachewhen),保存正式证明 JSON,按作业、分支及保护状态隔离。缓存可缺失,Peach 仍负责内容、环境、时效与全量批次校验;不引入缓存 SDK 或独立证明存储。GitLab 克隆地址使用标准库 `urllib.parse` 保留仓库身份并规范化认证值,作业令牌及其密码别名按存在性参与环境身份。 候选比较包括官方 [pytest 缓存文档](https://doc.pytest.org/en/stable/how-to/cache.html) 与 [Turborepo 缓存文档](https://turborepo.dev/docs/crafting-your-repository/caching)。pytest 的失败项选择不能替代当前内容绑定的成功覆盖,不迁移测试框架;Turborepo 的任务缓存不能直接接管 Python 用例结果及集成门槛,不引入其运行时或源码。外部源码版本与许可证未作为采用依据,本次未复制这些项目的实现。 临时输入实证覆盖跨工作树运行时、安装锁 JSON、CI 运行信息、多域混合失败及多份记录搜索;行为回归覆盖失败与中断恢复、旧失败阻止成功恢复、原时间继承、外部文件完成证明、Python 容器后置检查及全量来源约束。运行时、实际依赖、共享夹具、未知输入、执行模式、过期或未来时间变化仍使相关证明失效。测试设施不读写真实 ledger。 ## 媒体目录与整理路径映射 PikPak 整理复用项目已有 `PushDiscoverySettings`、`CloudPrefix` 与 `map_cloud_path`,与推送发现共用配置,不引入第二份盘符或 CloudDrive 路径表。CloudDrive RPC 继续使用现有固定版本的 gRPC/protobuf;路径归属与账号内 WebDAV 目录核验属于 Peach 的写入边界。不同盘符、子目录、云端名称、越界与冲突由临时夹具和模拟 RPC 验证,不触碰真实账号或账本。 Windows 系统卷通过系统原生 `GetWindowsDirectoryW` 获取,其他平台使用根卷。此改动没有新增第三方依赖;现有依赖版本与许可继续以 `pyproject.toml`、`uv.lock` 和下文登记为准。 ## 文件名包装与补充回归 论坛 URL 包装与明确 BD Remux 尾部番号参考 [PR #123](https://github.com/peach-mitao/peach/pull/123),固定 revision 为 `edde1fffb2c4690b7b78224dbd70dd7dfed786b3`,沿用本仓库 AGPL-3.0-or-later 许可。包装只解开一层,内部重用现有文件名与用户识别规则;Remux 的括号番号必须是唯一发行身份。普通处理后缀、日期分隔符和「番号+片名」继续由既有解析器处理,不增加另一套处理词表或递归解析。 普通 HTTP 的浏览器和组件回归采用 [PR #119](https://github.com/peach-mitao/peach/pull/119) 的 `90d4972f9edf8b84dd866869a1a562cc7d1d24eb`;状态保存的短暂拒绝、持续拒绝和并发完整性回归采用 [PR #120](https://github.com/peach-mitao/peach/pull/120) 的 `b586ff907aa01b48432e51b6101b7ce4bc7f8126`。两者保留原作者署名,沿用同一仓库许可。正式随机标识继续复用 `core/random-id`;状态写入继续复用 `fsutil.atomic_write_text` 的同目录随机临时文件、十秒重试与失败清理,不新增依赖或真实 ledger 写入。 ## SMB 媒体读写 采用 [smbprotocol 1.17.0](https://github.com/jborean93/smbprotocol/tree/v1.17.0)(MIT,Python ≥3.10,上游测试包含 Python 3.14 与 Windows、macOS、Linux)。固定传递版本见 `uv.lock`;库 wheel 约 128 kB,另有 cryptography、pyspnego 和平台认证依赖。`opensrc path smbprotocol` 未取得源码,改为核对固定 tag 的 `_pool.py`、`_io.py`、`open.py`、`connection.py`。 复用认证、协议消息与解析器、目录分页和偏移读写,以及 `SMBFileTransaction`、`set_info` 和 `FileRenameInformation`/`FileDispositionInformation`/`FileEndOfFileInformation`。Peach 保留固定根目录授权、绝对请求期限、取消、凭据隔离与媒体会话;整理和永久删除沿用既有计划、账本事务与失败恢复。目录条目的 `stat()` 会额外发请求,扫描消费枚举元数据;传输在库响应事件上施加期限,超时取消并断开独占连接。SDK 认证日志保持 WARNING,DFS 与重解析点拒绝。写入不覆盖改名目标、不跨声明根,写权限由共享服务器判定;工具用的回环 HTTP 仍只读。 未采用 fsspec,其 SMB 底层仍是 smbprotocol,无法替代媒体工具输入和取消;pysmb 的 SMB1/2 能力不覆盖同等 SMB3 需求。FFmpeg 原生 SMB 依赖二进制构建,本机工具没有列出该协议,因此使用 HTTP Range 回环桥。隔离回归覆盖认证、读取、并发偏移、配置与扫描配对;实际 FFmpeg 通过合成视频的尾部索引和 seek 抽帧。真实 NAS 吞吐和兼容性未取得,无真实 ledger 写入。 ## 第三方标识的发行边界 `resources/marks/` 保存用于实体身份展示的内置标识,来源记录与文件哈希见同目录 `manifest.json`。来源可追溯不等于取得图片版权或商标授权,图片也不因与应用同仓库就自动适用 AGPL。 厂牌与事务所标识按 ADR-0026 随应用分发,包括裸文件、`icon` 和 `logo` 变体;`scripts/sync_brand_marks.py` 同步文件与来源记录。本机缓存、实体来源链接和缺图时的文字/首字回退由既有预览服务处理。 ## GitLab 与 R2 发布 Windows 构建路径解析复用 PowerShell 7 的原生 [`GetUnresolvedProviderPathFromPSPath`](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.pathintrinsics.getunresolvedproviderpathfrompspath);以当前 PowerShell 工作位置解析尚未创建的文件,无新增依赖或安装体积。安装更新验收使用 GitLab 官方[预定义变量](https://docs.gitlab.com/ci/variables/predefined_variables/)识别受保护版本标签及指定作业,沿用 Windows 注册表的既有安装检查。离线 PowerShell 回归覆盖进程工作目录与脚本工作位置不同的输入;主机检查覆盖受保护作业、未知作业与既有安装登记。 GitLab API、CI 认证和 Release 创建复用官方 [glab 1.124.0](https://gitlab.com/gitlab-org/cli)(MIT,维护中);GitLab CI 的发布写入使用短期 `CI_JOB_TOKEN` 与官方 CI 自动登录。R2 的 S3 上传复用 [rclone 1.75.2](https://rclone.org/)(MIT,维护中),使用单桶对象读写凭据;版本文件不可覆盖,并由独立 HTTPS 下载校验 SHA-256。两者都是构建期 CLI,不进入应用运行时依赖。 演练产物晋级复用上述传输和 GitLab 作业 API;GitHub 通过官方 [Artifacts REST API](https://docs.github.com/en/rest/actions/artifacts)读取服务端摘要,再由标准库 `urllib.request`、`hashlib` 和 `zipfile` 下载、核验与展开。Peach 负责同一提交、版本、平台和验证任务的身份契约,以及已验收镜像的 image ID。媒体缓存沿用固定源码构建器,缓存二进制与对应源码,按实际构建输入和工具链核对,不新增缓存 SDK。协议与回收边界见 [ADR-0127](adr/0127-verified-release-artifact-promotion.md)。 GitGud 双存储副本复用同一版 glab 的原生 `packages upload` 与官方 [Packages API](https://docs.gitlab.com/api/packages/),不另写认证或上传协议。Peach 只核对版本、文件名、大小与 `file_sha256`,复用相同内容并拒绝覆盖冲突;登记未完成最多检查三次。R2 下载表与 GitGud 备用资产链接使用不同的 Release 路径。未新增运行时依赖,离线回归覆盖首次上传、重复执行、内容冲突、未登记终止与双来源链接。 更新与轻量安装器共用 `standalone_update.download`、既有 HTTPX 和内置工具清单;GitHub 与 R2 可切换到同版本、同文件名,每个来源分别按同一份大小与 SHA-256 校验。新安装与同版本更新记录优先 GitHub,R2 保留灾备;工具下载不再另包一层来源重试。发布后空缓存验收复用 `smoke_split_update.py` 与实际冻结程序的 `--installer-tools` 入口,不新增下载器或依赖。 `fetch_release_tools.py` 从固定版本官方发行站读取 SHA-256 清单,仅提取指定二进制。Python 标准库负责制品清单、版本与提交判据,不另实现 GitLab 认证、S3 签名或多段上传协议。Windows 与 macOS 的 CI 入口复用既有测试、构建和独立制品验收脚本。下载后端及费用边界见[运维说明](OPERATIONS.md#gitlab-发布与下载后端)。 CI 大产物中转复用相同的 rclone 1.75.2 与官方 [R2 S3 适配](https://developers.cloudflare.com/r2/examples/rclone/),覆盖 Linux amd64、macOS arm64/x86_64 与 Windows amd64;MIT 许可,仅构建期使用。传输、校验和多段上传由 rclone 负责,Peach 只维护流水线身份、输出路径白名单、SHA-256 清单与桶容量预算。macOS 只传 DMG 和构建清单,展开应用保留在构建机器。GitLab job artifacts 只传 JSON 清单;Generic Package 的单文件配额不能保证前置代理接受同等大小的请求。官方 rclone 归档名称与校验清单按实际输入核验,大文件往返使用独立临时仓库验证,不将传输测试当作正式制品验收。无新增 Python 依赖。源码获取复用共享 User-Agent 与 Peach HTTPX 客户端,针对连接中断、超时及暂时性 HTTP 错误最多尝试三次,完成 SHA-256 校验后才登记缓存;可独立构建的对应源码包使用标准库 urllib,包含共享请求标识及其许可证。 细粒度凭据缺少公开 CI 元数据的读取权限时,发版查询可在官方 API 上进行一次匿名 GET,复用 HTTPX、Peach 代理与项目共用 User-Agent;不扩大凭据权限,也不携带本机认证头。私有资源仍须通过服务端权限检查。 外部 HTTP 请求的连接策略复用 `peach_proxy.client_options`,客户端使用固定的 HTTPX 0.28.1(BSD-3-Clause)与 curl_cffi 0.16.3(MIT),没有新增依赖。共享 `HttpxTransport`、浏览器指纹传输、字幕、PikPak、更新、模型与维护脚本使用同一策略;libcurl 通过 `NOPROXY` 明确表达直连及自定义代理,避免继承相反的环境例外。Sentry 2.72.0 的事件、限流与回执仍由 SDK 维护,最终请求复用 HTTPX,保持测试禁发、无重试和无重定向。临时本机代理验证两种传输的实际请求路径;下载大小、SHA-256、重试次数和独立源码归档继续由行为回归核对。无需引入额外代理库或全局改写第三方网络函数。来源显式直连、网盘挂载、本机控制接口和独立工具的边界见[来源连接设置](SOURCING.md)。 npm 安装沿用 Node.js 24 LTS 附带的官方 [`npm ci`](https://docs.npmjs.com/cli/v11/commands/npm-ci/),锁文件与完整性校验由 npm 维护。`npm_ci.py` 复用既有 `npm_audit.py` 的有限重试方式及 Python 3.14 标准库 `subprocess`(PSF 许可,无额外安装体积),只为明确的 `ECONNRESET`、`ETIMEDOUT`、`EAI_AGAIN` 下载错误重试,最多三次;锁文件、完整性与生命周期错误保留失败。Linux、Windows、macOS CI 和 Windows 打包入口共用此策略,不重试测试失败、不变更包版本。真实锁定安装与注入失败回归覆盖成功、重试耗尽和非网络错误,无新增应用依赖、生产入口或账本改动。 ## 真实样本界面预览 用户验收预览复用项目记忆登记的真实账本小样本和已有缓存。启动入口强制调用 `scripts/check_ui_preview.py`,使用标准库 SQLite 的只读连接核对作品、实体、关联和来源清单,产出样本内容摘要;通用契约见 `docs/UI_PREVIEW.md`。核验与图像查看分别记录,隔离自动化测试夹具保留在测试范围内。没有新增依赖或生产数据写入。 ## 采集磁盘预估 采集磁盘预估复用 `ProcessingTraffic`、`TrafficPlan` 的待执行与完成范围,以及 `typical_size` 的本地缓存采样。`processing_storage` 仅用 Python 标准库 `shutil.disk_usage` 和文件系统设备编号合并同盘、分别核对跨盘容量;输出读数由现有 `TrafficProgress` 同时用于启动弹窗、运行任务卡和任务通知。网盘挂载缓存保持未观测状态,不把流量数直接算成最终磁盘产物。无新增依赖。 ## 状态与同步弹窗 导航位置由 `history/page-navigation.ts` 统一保存与恢复,同一标签页保留各栏目的筛选、分页和内容缓存;普通栏目往返平滑恢复位置,双击导航请求回顶。左侧导航排序复用 `moveSidebarKey` 与现有设置保存入口,指针移动只更新插入提示和避让,松手时保存一次;键盘使用 Alt + 方向键。动效参数与证据边界见[导航拖动参考](reference-snapshots/kubai-sidebar-reorder.md),未新增依赖。 侧栏宽度复用已安装 React Aria 的 `useMove`,数字时长复用 BoardUI 输入组合与现有双滑块、目录和关注筛选入口。常用宽度吸附、浏览器记忆、键盘调节及重置由 Peach 的固定侧栏管理,未新增依赖。热门组件库的实测范围与取舍见[侧栏宽度参考](reference-snapshots/sidebar-resize.md)。 筛选浮窗的排序项复用 `useSidebarReorder`、`NavigationOrderRows`、BoardUI Checkbox 和现有设置保存入口。首页馆藏、JAV 馆藏、关注、新作、发现分别保存显示项与顺序,人物资料页复用对应内容类型的设置;排序行可直接拖动,也可用 Alt + 左右键移动,自定义菜单支持勾选和恢复默认。排序项的按下由重排接管,外层横向滚动在其他区域接受拖动;首页与 JAV 馆藏都提供发行时间。隐藏排序项只改变控件显示,当前排序与方向仍由页面状态和地址决定。偏好通过 `/api/settings` 的 `sortControls` 按组写入 `profile.settings_json`,本地缓存同步更新,加载态使用同一份顺序与隐藏选择,无新增依赖或迁移。 全站滚动区通过 `observeScrollRegions` 按实际 `overflow` 接入现有 `attachOverlayScrollbar`,动态新增子树、样式启用和响应式布局复用同一入口;样式读取与轨道写入分批,行内样式变化只复核当前元素。普通内容区使用同级轨道,定位浮层与原生顶层内的轨道保持在自身层级并补偿滚动位置。组件卸载释放监听、观察器及轨道。横向手势导航保留 `wireHorizontalScroller` 的拖动和渐隐。路由冒烟统一检查所有实际溢出的滚动区,搜索回归覆盖滑块拖动、滚轮、关闭重开和轨道数量。没有新增依赖。 来源筛选与所有表格的显示列弹层共用 `SelectionPopover`,组合现有 React Aria `Popover`、`MenuDialog`、BoardUI `Checkbox` 和按钮。宽度由选项和操作组的内容决定,并受视口上限约束;长选项在限宽内折行。选项靠近触发器,批量操作根据 React Aria 的实际展开方向放在远端,DOM 顺序随之调整。`SelectionActions` 区分短操作并排与长操作铺满整行;来源筛选附带箭头的 `LinkButton` 凭据链接,列设置保留显示全部和默认显示。复核作品样本的全选、清空也复用同一操作条,保留计数及禁用条件。颜色配色器与人物说明浮层的交互含义不同,继续使用各自组件。没有新增依赖。 馆藏和实体作品表格的艺人、媒体库、标签列,以及 JAV 新作表格的艺人、厂牌、标签列,复用 `TableColumnFilter` 的可搜索多选菜单和 BoardUI Checkbox。同列取并集,各列叠加筛选,选择后菜单保持展开。「全部」覆盖完整筛选范围,取消则清空选择。`column_filters` 的分组用数组记录选中项,用 `exclude` 对象记录全选后排除的项,缺少分组表示全选,空数组表示没有选中项,名称中的逗号保持完整。全选状态无需枚举未加载的选项,后续页沿用当前选择。馆藏筛选保存在同一范围的表格状态中,交给服务端筛选和分页;实体身份通过 `scope_kind`、`scope_name` 与列条件求交集。 列头展开时才查询 `/api/facets` 或 `/api/jav/releases` 的 `column` 选项,每批 24 项,向下滚动或点击加载更多时读取下一页。搜索复用 `IndexSearch` 的 300ms 防抖与输入法处理,服务端复用搜索补全的规范名、别名与检索词判据。馆藏选项在 SQL 中分页后附加头像和别名,后端缓存使用有界 LRU;前端查询缓存闲置一分钟后回收,关闭菜单取消未完成请求。新作顶部各组只返回前 24 项,列头提供完整选项分页。媒体库沿用已有清单和 `SourceMark` 图标。艺人头像复用 `entity_ref`、`avatarInner` 和 `SourceAvatar`,图片延迟加载。选项滚动区铺满菜单,覆盖式滚动条贴右缘,搜索框保持固定。筛选为空时保留列头以便恢复。 关注管理使用「关注列表」「添加关注」两个页签。列表复用 `FeedSources` 管理 JAV 订阅,添加页复用 `AddFeed` 的演员卡查询、用户点选与 `follow-name` 写入契约;共享 `FEEDS_KEY` 缓存,开关、移除及拉取各走原接口。来源筛选顶部统一提供凭据设置链接。JavDB 登入页判据复用 `javdb.LOGIN`,主页面与单体作品补拉共用解析入口。脚本检测在桥接文档加载后等待同源回报,加载与回报均有时限;权限指引依据 [Tampermonkey 官方 FAQ](https://www.tampermonkey.net/faq.php#Q209)。没有新增依赖。 连接状态复用 BoardUI `StatusDot` 与 `ConnectionStatus`,圆点和文字保持同一色系;成功为绿、检测中为蓝、离线或待配对为黄、失败为红、未知为灰。稳定任务结果和配置状态复用 `Chip`,由 `StatusLabel` 统一成功、进行、警告、失败和中性状态。暂停状态优先于历史错误;未经检查的来源保持未检查。用户脚本检测与功能启用分开呈现,仍由同源桥接协议核对版本、nonce 和配对回报。HTTP 状态颜色仅表示本次访问结果,删除仍以服务端确认失效的清单为准。 `formModal` 与 `confirmModal` 共用正文覆盖式滚动条,标题及底部操作固定;启动预估的来源明细跟随弹窗正文滚动,运行通知的明细维持独立限高。全部沿用已有组件、主题 token 和依赖。 ## 元数据标题原文 持久元数据候选复用 `metadata.extract_peach_fields` 的原文取值和 `metadata_auto_apply` 的统一写入入口。r18 的纯拉丁字母标题需由同一作品快照的原文侧精确印证;缺少快照或只有英文译文时不进入自动结算,人工批准入口同样拒收。来源原文中的拉丁字母片名保留,不按字符集自动翻译。无新增依赖。 ## 用户脚本的本机取证与进度 用户脚本的请求错误复用 Tampermonkey GM 存储与 `GM_xmlhttpRequest`,服务端复用 `error_reporting.local_event` 的脱敏与 `support_bundle` 的日志导出。独立的 `userscript` stage 仅写本机;受限字段、体积、频率和去重属于 Peach 协议策略,不接入外部遥测 SDK,不增加依赖。队列锁只保护内存与本机状态,网盘提交在锁外执行,提交幂等仍由现有 DownloadService 的共享提交锁处理。 脚本进度由 DownloadStore 的真实任务投影提供,复用 `STATE_LABELS` 与 `POSTPROCESS_LABELS`,不回传磁力、路径或网盘凭据。整体进度组合生产 `frontend/src/react/components/progress.tsx` 的 SVG、6px 高度、100 份比例和刻度,与 `library-processing/library-processing-notice.tsx` 的完成标记和当前阶段语义;BoardUI 明暗主题配色为同许可快照,固定来源为 Peach `44c347573e47cdd3b2294d35719f363ee5305246`。下载段仅填充实际百分比,其他段按里程碑推进;脚本保持零运行依赖,不嵌入 React。 ## 浏览器错误的构建映射 前端复用官方 [`@sentry/vite-plugin` 11.8.0](https://github.com/getsentry/sentry-javascript-bundler-plugins)(MIT,维护中,Node ≥23.2,与项目 Node 24 和 Vite 8 兼容)生成确定性 Debug ID 与 hidden source maps;[`@sentry/cli` 3.8.0](https://github.com/getsentry/sentry-cli)(FSL-1.1-MIT)仅用于构建期本地定位和显式上传。两者精确固定在前端开发依赖,纳入现有 Dependabot;不进入 Python 运行时或独立包依赖。插件的 `@sentry/bundler-plugins` 声明 glob `^13`,经它引入的 minimatch 10 有拒绝服务告警(GHSA-g3hv-75wg-m249),修复只在 minimatch 11;插件只用 `glob()` 的 `absolute`、`nodir`、`ignore`、`root` 选项,`frontend/package.json` 的 `overrides` 将其 glob 固定为 14.0.3。插件自身声明 glob 14 后移除这条 override。 `frontend/scripts/sentry-build.ts` 只保留 Peach 的公开/私有目录边界与产物匹配检查。官方插件禁用遥测、自动上传与 release 注入,普通构建不需要凭据;私有目录保存 JS/CSS/maps,公开目录只复制四个正式 JS/CSS。显式上传复用官方 CLI,先核对分发字节和 map 身份。没有实现自定义 source map 编解码器或上传协议,也没有为此引入浏览器 SDK、页面回放或性能采集。 回归使用真实 Vite 构建与官方 CLI 本地解析 source map,验证源码文件和行号;相同输入两次构建的文件字节一致,Debug ID 与 map 对应,映射源只使用相对路径。构建体积由 Vite 输出,source maps 只增加私有构建产物,不增加页面分发体积。字段与发布配置见[诊断核验](DIAGNOSTICS.md#可选远程诊断);真实接收端符号化独立验收。 ## 索引标题栏 标签、艺人、卖家、厂牌与事务所共用 `IndexPage`、现有 BoardUI Input/Button、收藏入口和版式分段器。标题与操作保留固定宽度,搜索框使用原生 Flex 的剩余空间;窄屏名册计数独占次行。首屏占位复用 `islandSearchInput`、`islandButton` 与相同布局规则,标签管理入口也预留真实尺寸。浏览器几何回归覆盖 320px 至桌面、断点两侧,以及本地/在线和管理模式。没有新增依赖、API 或 ledger 写入。 ## 作品卡片与推荐理由 目录、实体作品区、竖屏条与接着看复用 `MediaCard`。多列网格统一卡片高度,`MediaGrid` 沿用现有 `ResizeObserver` 和 `gridTemplateColumns` 测量方式,单列按实际内容定高。元信息保持一行,容器查询按扣除头像后的文字区宽度决定日期、共演人数与体积的显隐。普通卡片保留最多五枚共演头像,常态按实际紧叠宽度占位,在 45px 至 109px 之间随卡宽压缩。小于 320px 的卡片使用紧凑头像;首页、实体资料页的旧模板新作横排与 React 卡片共用 `--media-avatar-tight`、`-step`、`-max` 几何变量。悬停与键盘聚焦时头像浮于文字上方展开并抬起对应头像,不预留展开空间,标题列位置保持稳定;占位文字始终居中,图片沿用原有头像取景。接着看和竖屏条保留两枚头像。稍后看复用已有动作回调、撤销回执与中性填充 token,同步按钮和卡片底色,不渲染状态色块及观看次数。 新作横排使用 `feedNewCardHtml`/`feedIdentity`,同时影响首页、女优与厂牌详情;JAV 新作、发现使用 `DiscoveryCard`。新作卡的标题、姓名、日期按独立行排列,不使用馆藏虚拟列表的密集行高估计。JAV 卡片页的顶部密度与多选入口由壳路由判定,选择集留在 `JavSelectionProvider`,按番号跨页保留,不混入馆藏资产 ID;卡片、列表共用本页全选及 `SelectionDock`。批量加入想要复用 `/api/wants`,成功项移出选择,失败与未提交项保留;批量查找复用 `WantMagnets` 和既有作品资源接口,查询不自动提交下载。 接着看的推荐理由独占两行,完整内容使用已安装的 React Aria Components 1.22.1(Apache-2.0)`Popover`/`Dialog` 与现有 BoardUI 浮层样式展示,触屏、键盘与鼠标共用同一入口。没有新增依赖、API、迁移或 ledger 写入。 ## 空状态与操作入口 React 页面复用 `EmptyState`,HTML 页面复用 `emptyStateHtml`。图标统一为 32px、图标框为 54px;标准区域最小高度为 320px,紧凑区域为 240px,字体、背景和边框共用。统计页上下区域采用标准尺寸。空状态按原因提供添加内容、清除筛选、重试或返回浏览等操作;正常完成状态不增加操作。 已有添加表单使用 `EmptyFocusButton` 聚焦原输入框。筛选清除保留当前页面、版式和本地或在线范围。关注检查复用 `useBackgroundJob` 与 `startCheck`;实体页仅提交该实体绑定且有效的来源 ID,不以空 ID 列表发起全量检查。没有新增依赖或自动采集任务。 同页页签切换调用页面已有状态与地址回调。站内锚点链接由 `navigationLinkPath` 按 `routeMetaOf` 的路由登记统一交给客户端导航;下载、外站、新窗口、修饰键及普通页内锚点保留浏览器行为。不按按钮文字或某条固定地址单独拦截。 ## 标签身份与管理 标签浏览与管理复用 `DataTableFooter` 和既有页码算法,每页默认 100 个,可选 50、100、200 个;`useTagPagination` 统一筛选重置与页码边界。搜索输入复用 `IndexSearch`,标签正文与页脚的占位复用 `tagSkeletonHtml`。本地和在线详情的选择器通过 `useOverlayScrollbar` 接入既有覆盖轨道,搜索标题与滚动正文分层,不新增依赖。 标签复用 `entities.merge_entity`、实体别名、兼容投影、SQLite 事务及在线备份。字符宽度归一使用 Python 标准库 `unicodedata.normalize('NFKC', ...)`;同义词和用户别名属于 Peach 的身份规则。当前树、标签改名脚本与 Git 历史提供了关系迁移能力,无需引入通用模糊匹配库;语义近似不足以自动合并。隔离用例覆盖重叠关系、来源证据、隐藏偏好、旧名入库、过期计划和备份。 页面复用已安装的 React Aria 1.22.1、BoardUI Button/Input/Select、标签云和选择操作条。编辑字段沿用同步任务表单的 React portal 接法,外壳共用 `formModal` 与 `confirmModal`,按顺序打开。没有新增依赖。 在线标签复用 `profiles.read_settings` 与 `profile.settings_json` 保存本机名称、来源词成员和隐藏状态;账本版本触发器负责缓存失效,无新增表。读取投影复用 `_follow_tag_index` 的发布组计数和来源类型,标签索引、关注卡片、详情、筛选项与旧名查询共用 `OnlineTagPolicy`,不改写来源 metadata。合并限制在相同来源类型;事务、影响范围预览、过期计划和备份复用标签管理端点。归类属于 Peach 的用户决定,不引入模糊匹配或外部同义词服务。 在线标签收藏复用 `FavoriteButton`、`libraryShortcuts` 设置和既有读写端点,以 `scope=online` 与稳定来源词键区分本地实体;收藏快照经在线归类解析并去重。收藏面板沿用标签分类,以「在线标签」标明去处,链接打开 `/follow` 标签筛选;馆藏实体收藏快照继续供研究和实体标注使用。未新增依赖或存储表。 在线手动标签与内容屏蔽复用 `OnlineTagPolicy`、`profile.settings_json`、`FollowStore.group`、现有标签预览确认端点及账本版本缓存。手动标签以来源和内容编号定位,在读取副本中叠加;来源 metadata 保持独立。内容屏蔽在分页、计数及来源筛选前按完整作品组执行,任一版本命中就隐藏整组;直接详情保留标签管理入口。当前树、标签偏好与 Git 历史已有身份和事务能力;新增部分只定义 Peach 的用户选择与影响范围,无需外部规则引擎或模糊匹配依赖。界面沿用 BoardUI Input/Button、`useAction`、标签云和 `SelectionDock`,无新增依赖、存储表或迁移。 ## 播放器触摸手势 复用沉浸播放器的方向锁定、合成点击隔离和“拖动预览、松手定位”判据,以及同一枚原生 video 的时间、倍速和音量状态。触摸单击切换控制条,左右双击定位十秒,横滑一屏宽度定位二十分钟,长按临时至少两倍速,长按左侧双击区则停住画面、目标每秒回退两秒,松手定位并恢复原播放状态;鼠标左键在画面上共用长按与横向拖动定位,未移动的单击、双击与右键菜单照旧;全屏右半区竖滑调音量,不支持的软件音量控制提示使用设备音量键。实际 PointerEvent 输入类型区分触摸与鼠标,菜单、原生滑条和按钮保留自身行为。浏览器原生 Pointer Events、指针捕获与 AbortSignal 负责事件生命周期;不新增手势库或运行依赖。单元测试覆盖取消、切源、多指、倍速恢复和鼠标切换,独立浏览器用真实触摸输入验证合成点击与拖动提交。沉浸模式的长按倍速读同一项 `holdRate`;字幕键复用 `SubtitleControls` 与设置菜单的面板样式(`subtitlePanels`);全屏看横版复用舞台的横屏锁(`lockLandscape`),锁不上时转内容层,手势坐标按转后的内容坐标系换算。 ## 检查输入与源码文案 测试差异复用 Git 文件快照、Python AST、标准库 TOML/JSON 解析器及现有 filelock。Python 注释和清单说明字段通过有效内容比较识别;真实依赖、执行模式和无法解析的输入保留完整验证。完整批次按测试文件保存结果,仅补齐受影响范围,不延长结果有效期。 JS/TS 文案复用 [Oxc parser](https://oxc.rs/docs/guide/usage/parser),开发依赖固定 `oxc-parser@0.154.0`,MIT 许可,来源为 [Oxc 官方仓库](https://github.com/oxc-project/oxc)。项目 Vite/Oxlint 工具链已有 Oxc;独立 Node 检查器解析注释、字符串、模板与 JSX,不进入应用运行包。前端源码解析错误为零。Tree-sitter 的试用在具名元组成员与 JSX 查询参数处产生错误,未采用;不新增 Python 解析器依赖。中文和英文判据集中于 `scripts/copy-rules.json`,含糊词语只提示人工核对。 ## 界面翻译 界面文案的翻译复用 [i18next](https://www.i18next.com/),运行依赖固定 `i18next@27.0.1`,MIT 许可,来源为 [i18next 官方仓库](https://github.com/i18next/i18next),没有传递依赖。它提供插值、按 `Intl.PluralRules` 选复数形式、缺键回落源语言,资源格式 i18next JSON v4 也是 Weblate、POEditor 直接支持的格式,换平台不用转换。只用核心库:界面语言在页面载入时定下,换语言整页重载,用不到 `react-i18next` 的响应式能力。写死中文的计数和术语扫描复用上一节的 Oxc parser;术语表用 Weblate 能读出禁用标记的 TBX,前端测试用 happy-dom 自带的 `DOMParser` 解析,后端不新增解析依赖。后端发给界面的文字带 `message_code`,由前端同一份 i18next 实例在 `server` 命名空间里翻译;后端中文的计数复用标准库 `ast`。决策见 [ADR-0156](adr/0156-interface-translation.md)。 ## macOS 独立构建 macOS 发行包复用 Windows 固定的 FFmpeg 9.0.2、x264、dav1d 1.5.4 和 untrunc `9d86ec9` 源码锁、下载 SHA-256 校验与 `media_tool_bundle.validate`。untrunc 单独静态链接兼容的 FFmpeg 8.1.3;其 [上游 Makefile](https://github.com/anthwlock/untrunc/blob/9d86ec9ef2ffed1bf8131abe80742c0574db52b6/Makefile)提供 macOS 编译依据。头文件用 `-idirafter` 保留 C++ 标准头 `version` 的优先级。FFmpeg/x264 按 GPL-3.0-or-later、dav1d 按 BSD-2-Clause、untrunc 按 GPL-2.0-or-later 分发;完整对应源码归档包含全部上游源码、构建脚本和许可。Peach 仅维护目标架构、静态库组合、清单与拒收判据,不复制 Homebrew dylib。macOS 编译启用 VideoToolbox、AudioToolbox 与 Secure Transport,硬件转码选择仍服从已有产品策略。 编译工具复用 Meson 1.12.1(Apache-2.0)、Ninja 1.13.2(Apache-2.0)、pkgconf 3.0.7.post0(ISC)和 NASM 3.02(BSD-2-Clause),由 `setup_macos_media_tools.py` 安装到构建目录,应用运行无需这些工具。源码提供完整配置,两个架构分别编译;Intel 二进制可在 Rosetta 下验收,但不能视为 Intel 真机测试。对应源码与二进制的体积、架构和系统最低版本由实际产物核对。 cloudflared 采用 [Cloudflare 官方 2026.9.0 发行](https://github.com/cloudflare/cloudflared/releases/tag/2026.9.0)的双架构归档(Apache-2.0);固定资产 SHA-256 读取官方 Release API 的 `digest`,与发布正文中的旧摘要分别核对。Peach 保留下载校验、包内查找、ad-hoc 签名与进程归属,不新增隧道协议。原生验收运行 `--version`,不因此宣称已连通公网隧道。没有新增 Python 应用运行依赖;合成媒体验收与临时目录不接触真实 ledger。 Windows、macOS 与 wheel 通过 `bundle_resources.data_files` 共用桥脚本、依赖清单和锁文件。桌面制品额外使用项目已有的 PyInstaller 6.22.3 构建独立 amane 运行环境;Docker 在构建阶段按同一锁预装独立 venv。两者随附固定 revision、版本与可执行文件清单,保持子进程边界。源码与 wheel 在首次实际需要时通过 uv 按锁自动安装到数据目录,安装锁复用 FileLock,下载代理复用 Peach 代理并通过子进程环境交给 uv 与 Git。资源定位复用 `settings_file.PROJECT_ROOT`,覆盖源码、wheel 的 `_resources` 和 PyInstaller 的资源根。打包机制沿用官方 [PyInstaller 数据文件约定](https://www.pyinstaller.org/en/stable/runtime-information.html)与 [uv 环境目录配置](https://docs.astral.sh/uv/concepts/projects/config/#project-environment-path),不新增应用依赖。分发决策见 [ADR-0124](adr/0124-amane-runtime-preparation.md)。 独立应用复用项目已有的 PyInstaller 6.22.3(GPL-2.0-or-later,带发行例外),由 macOS 原生 bootloader 承载 Python 3.14 与 Cocoa 菜单栏,资源与 CLI 入口沿用现有桌面实现。镜像使用系统自带的 `hdiutil`,无需新增运行时依赖。构建与签名依据 [PyInstaller macOS 文档](https://www.pyinstaller.org/en/stable/usage.html)和 [Apple 分发文档](https://developer.apple.com/documentation/xcode/packaging-mac-software-for-distribution)。 Peach 负责独立数据目录、首启、构建身份和资源清单。arm64 与 x86_64 使用各自的 Python 和原生扩展,按 [PyInstaller 架构约束](https://pyinstaller.org/en/stable/feature-notes.html#macos-multi-arch-support)分别生成;不使用 lipo 合并冻结程序。应用不安装系统组件,采用 DMG 拖放安装;PKG 的系统级安装流程不属于这条路径。源码运行的 LaunchAgent 外壳继续使用自己的构建入口。独立制品的启动与读写验收使用隔离数据目录,不改变真实 ledger 或双机配置。 ## 硬件转码后端 macOS 复用 FFmpeg 的 VideoToolbox H.264 编码及 H.264、HEVC、AV1 解码,沿用现有 `HardwareTranscoder` 的合成帧探测、命令尝试顺序和软件回退;不新增视频框架或 Python 运行依赖。`-allow_sw 0` 要求编码器实际使用硬件,AV1 硬解显式选择 FFmpeg 原生解码器,软件回退继续使用 dav1d。依据 [FFmpeg 硬件解码选项](https://ffmpeg.org/ffmpeg.html#Advanced-Video-options)和当前固定源码中的 `videotoolbox_av1.c`、`videotoolboxenc.c`;具体可用能力依赖设备与系统,不按 Intel 或 M 系列名称推断。抽帧的编码格式探测复用 `media_probe.probe_file`,按文件世代有界缓存,失败后在同一超时预算内软解。两种加速偏好复用 `media-processing.json`、`FileLock` 与原子写入,抽帧与播放各自保存;服务端新任务读取本机偏好,不调整浏览器解码器,不更改 ledger。桌面和手机自动化回归验证独立切换与保存恢复,合成片分别验收硬件可用路径及失败回退。 ## HLS 请求断开清理 断开监听与子进程回归采用 [PR #122](https://github.com/peach-mitao/peach/pull/122) 的固定提交 `b49806a8685e128088a3c4825891fd425e279db1`,沿用本仓库 AGPL-3.0-or-later 许可与原作者署名。Peach 保留主线的会话校验、硬件后端和转码异常契约。 HLS 分片请求复用 Range 传输的 ASGI 断开监听、Python 3.14 的 `asyncio.wait` 与既有 `HlsSegmentService._run` 清理:请求断开时取消该请求的生成任务,终止并等待子进程退出,再移除临时分片。取消以单个请求为单位,同一播放会话的其他请求可继续生成;排队请求退出后不启动转码。 进程管理沿用标准库的 [`asyncio.subprocess`](https://docs.python.org/3.14/library/asyncio-subprocess.html)(PSF 许可,无新增安装体积),不引入进程扫描库或 FFmpeg 命令包装层。当前树、REUSE 与 Git 历史的复用检索确认,分片和整片已具备会话取消,断开监听由传输层提供。临时文件与真实 Python 子进程回归覆盖断开退出、并发隔离、排队取消及同会话重试;macOS 的临时 HTTP 服务用合成 HEVC 和 FFmpeg 8.1.1 实测,断连后子进程退出、临时分片与登记清理完成。Windows 报告环境与真实 GPU 播放验收未取得。无新增依赖、生产入口或真实 ledger 写入。 ## 播放转码的硬件选择 整片 MP4 与 HLS 复用现有 FFmpeg 的 CUDA / NVENC、VAAPI、`scale_vaapi` 与 `hwupload`,不引入 Python 命令包装库。Windows 发行工具固定为 FFmpeg 9.0.2(GPL-3.0-or-later,来源清单见 `scripts/ffmpeg-sources.json`);Linux 镜像使用 Debian trixie 的 FFmpeg、`mesa-va-drivers` 与 `vainfo`,随 Debian 安全更新取得版本,不另行复制驱动代码。Mesa 按上游各组件许可证分发,驱动增加的镜像体积由构建决定,AMD 需要宿主机 amdgpu 与固件。设备参数和硬件解码接口依据 [FFmpeg 官方文档](https://ffmpeg.org/ffmpeg.html#Advanced-Video-options),驱动范围依据 [Debian VAAPI 说明](https://wiki.debian.org/HardwareVideoAcceleration)。 Peach 只保留设备选择、一次性合成帧探测、命令尝试顺序与失败回退;探测结果由两个服务共享。复用检索覆盖当前 NVENC 链、媒体工具解析器与 Git 历史,没有独立 VAAPI 路径。FFmpeg 已覆盖编解码与滤镜,ffmpeg-python 一类包装层不提供设备驱动或硬件可用性判定,因此沿用项目 subprocess 入口,不新增 Python 依赖。回归用合成输入与进程替身验证 Linux 节点选择、权限和超时、10-bit 转 NV12、整片及分片回退。2026-10-19 的 Windows NVENC 实测使用 640×360 合成帧完成探测,合成 10-bit HEVC 经整片 MP4 与 HLS 两条 CUDA / NVENC 路径输出 H.264 `yuv420p`;128×128 不满足该编码器的最低尺寸,因此探测统一用 640×360。目标 AMD GPU 的驱动初始化、解码与播放验收未取得。无生产入口或真实 ledger 写入。 Windows 复用 FFmpeg 的 D3D11VA 解码与 `h264_amf`、`h264_qsv` 编码,沿用同一套合成帧探测与回退顺序,不新增依赖。D3D11VA 不指定 `-hwaccel_output_format`,解出的帧回到内存,能接任意编码器,只对 H.264、HEVC、VP9、AV1 开启,名单与 CUDA 相同。AMF 从 D3D11 设备派生上下文,只认 AMD 显卡;混合显卡机器的默认序号常是另一块卡,所以用 `-init_hw_device d3d11va=peach:N` 加 `hwupload` 按序号探测,派生失败时退回软件解码加 AMF。Media Foundation 的 `h264_mf` 在 NVIDIA 加 AMD 的实测机器上无论软硬解码都报 `MF_E_UNSUPPORTED_D3D_TYPE`,未接入。QSV 全硬件链沿用 Jellyfin 在 Windows 上的写法:`-init_hw_device d3d11va=…:,vendor=0x8086` 按厂商号选 Intel 卡,派生 QSV 设备,D3D11VA 解码输出 `d3d11` 帧,经 `hwmap=derive_device=qsv,vpp_qsv=format=nv12` 交给 `h264_qsv`,帧不回内存,10 位片源由 `vpp_qsv` 转 NV12;解码池加 `-extra_hw_frames 16`,否则 AV1 报 `Static surface pool size exceeded` 并丢帧。派生 QSV 设备在 Windows 服务与 SSH 所在的 Session 0 里报 `MFX session: -9`(同机 Jellyfin 的 FFmpeg 8.1.3 也一样),在登录用户的会话里正常,因此单独探测一次:通过才把全硬件链放在最前,其后是 D3D11VA 解码回内存加 QSV、软件解码加 QSV。2026-10-29 在 Intel UHD Graphics(8086:46d1,驱动 32.0.101.7088)的 Windows 10 上,用随包 FFmpeg 9.0.2 对 20 秒 1080p 合成片测进程 CPU 时间:10 位 HEVC 从 libx264 的 37.3 秒、软件解码加 QSV 的 11.6 秒、D3D11VA 解码回内存加 QSV 的 7.9 秒降到全硬件链 3.3 秒,耗时 4.0 秒;AV1、8 位 H.264、10 位 VP9 的全硬件链为 2.2–3.0 秒。四种片源的整片 MP4 与 6 秒 HLS 分片都输出完整帧数的 H.264 `yuv420p`。Peach 探测在登录会话里选中全硬件链,在 Session 0 里跳过它并用回退链完成转码。QSV 解码器(`hevc_qsv` 等)在同一会话里 10 位 HEVC 的 CPU 时间与全硬件链相当,但需要按编码挑解码器,未接入。 随包 FFmpeg 编入 NVENC、AMF、QSV 与 D3D11VA,四条路径都不依赖 PATH 上的第三方构建。AMF 只需 GPUOpen 发布的 `AMF-headers` 头文件包,运行时由 AMD 驱动提供 `amfrt64.dll`;QSV 经 FFmpeg 的 `--enable-libvpl` 接入,libvpl 调度器用 MinGW 编成静态库,运行时由 Intel 驱动提供实现。两者都是 MIT 许可,固定版本和哈希写在 `scripts/ffmpeg-sources.json`,许可证随发行目录与对应源码包分发,整体仍按 GPL-3.0-or-later。交叉编译做法参照 [BtbN/FFmpeg-Builds](https://github.com/BtbN/FFmpeg-Builds) 的 `50-amf.sh` 与 `50-onevpl.sh`:libvpl 的 C++ 调度器静态链接时要带 `libstdc++`,Peach 在 CMake 里给它未定义的 `CXX_LIB` 赋值,让生成的 `vpl.pc` 自带这一项,不改写安装后的文件。2026-10-23 在 Ubuntu 24.04 容器里按发布流程的同一组软件包跑通 `build_ffmpeg_windows.sh`,产物列出 `h264_amf`、`hevc_amf`、`av1_amf` 与 `h264_qsv` 等编码器,`-hwaccels` 含 `cuda`、`dxva2`、`qsv`、`d3d11va`、`amf`,发行包校验通过。在 NVIDIA 独显加 AMD 核显的 Windows 机器上,随包构建的 `h264_amf` 与 `h264_nvenc` 都完成 640×360 合成帧编码,D3D11 序号 1 上传加 AMF 可用、序号 0 报 `No such device`;Peach 自动探测得到 NVENC、AMF(序号 1)与 D3D11VA。该机没有 Intel 显卡,`h264_qsv` 报 libvpl 找不到实现(`MFX_ERR_UNSUPPORTED`),探测按预期跳过;QSV 实际编码未取得。 2026-10-23 在 NVIDIA 独显加 AMD 核显的 Windows 机器上,用 gyan FFmpeg 9.0.1 对 20 秒 1080p 10 位 HEVC 合成片测进程 CPU 时间:纯软件解码 21.9 秒、D3D11VA 解码 1.6 秒;libx264 转码 62.0 秒、D3D11VA 解码加 libx264 41.9 秒;软件解码加 AMF 23.3 秒、AMD 序号上的 D3D11VA 加 AMF 3.4 秒;CUDA 加 NVENC 0.7 秒。单帧抽帧在同一片源上从 7.7 秒降到 0.7 秒。整片与 HLS 经自动、AMF、仅 D3D11VA、软件四种配置输出的都是 H.264,时长与片源一致。 ## 文件名噪声清理 整理模板与 `scripts/clean_names.py` 共用 `organize_templates.clean_name_symbols` 和 `clean_filename`。字符分类复用 Python 标准库 `unicodedata`,按 Unicode 类别清除装饰图形、emoji、替代字符、控制字符和私用区噪声;Peach 保留常用标点、文字组合音标、单位、算术符号、扩展名与空名称保护。不新增依赖。 外部候选核对了 [pathvalidate 的文件名清洗](https://pathvalidate.readthedocs.io/en/latest/pages/examples/sanitize.html)与 [ftfy 的编码修复](https://ftfy.readthedocs.io/en/latest/)。前者主要处理文件系统非法字符,其通用符号替换还会删掉番号连接号和扩展名句点;后者通过启发式还原编码,超出本次删除噪声的范围,因此不引入。隔离用例覆盖装饰符号、复合 emoji、不可见字符、乱码替代字形、正常中日文与重音字母、空名称、重复执行和改名回滚;馆藏只读盘点与逐条预览保存在数据目录的复核产物中。 目录范围复用 `platform.resolve_root`、`location_mounts` 与标准库路径组件比较。界面复用 BoardUI Input、IconButton、已有 `FolderSearchIcon` 和 `/api/pick-folder`;预览、执行及后台任务恢复共用 `path` 参数,目录模板以所选目录为起点。空路径表示整个来源,目录边界按组件匹配,不按文本前缀匹配。 ## 独立页面的请求反馈 请求错误文案复用 `core/request-error.ts`,实体登记复用 `core/entity-links.ts`。API 直接引用这两个模块,首启与登录页不加载主界面的路由和字素分段初始化;主界面仍通过 `core/index.ts` 导出同一份错误文案。冷启动导入回归核对 API 不构造界面分段器,既有反馈测试覆盖状态码、超时与服务端中文原因。无新增依赖。 ## GitHub 项目看板 用户反馈和维护者任务都在应用仓库 `peach-mitao/peach`,共用一个公开 Project;原规划仓库已归档,旧编号由迁移映射接到转移后的 Issue。集中在应用仓库处理 PR、主线与发布事件,每小时同步 Issue,不逐次响应 Issue 的编辑、标签与开闭事件,凭据仅保留在应用仓库。应用仓库的新 Issue 复用 `issue_intake.verdict` 的模板准入判定;已有条目因待补模板关闭时,以 GitHub `closedAt` 为起点保留 2 小时修改窗口,再按当前状态同步。Issue 关联使用仓库名与编号,迁移映射兼容已存在的关联行;交付版本始终按应用仓库的主线提交和发布制品核验。 看板同步复用 GitHub CLI 的已登录认证、GraphQL Projects API 和 Git 的提交祖先校验;不新增 Python 依赖。官方 [Projects Actions 自动化](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions)支持独立项目凭据,仓库默认令牌不能写组织 Project。项目原生状态工作流没有发布标签与制品归属判定;通用自动加卡 Action 也不覆盖验收和发布的分别记录,因此由 `scripts/project_board.py` 保留 Peach 的状态规则,传输与认证交给系统已安装的 `gh`。运行依赖是官方维护、MIT 许可的 GitHub CLI 和 GPL-2.0 Git,使用 GitHub 托管 runner 内置版本;本机只读 GraphQL 与标签祖先验证后再应用。无生产服务、ledger 或媒体写入。 ## JAV 用户脚本添加 下载渠道复用 `media_sources` 注册表、媒体库名称、`clouddrive_proxy.media_remote_path` 的挂载与推送路径关联,以及现有 CloudDrive2 gRPC 客户端的 `canOfflineDownload` 与 `supportOfflineDownloadManagement` 能力。`LibraryChannels` 在只读探测后生成渠道,PikPak 直连仍使用已有客户端;配置区与专属检查按已声明媒体来源显示。支持任务管理时查询远端列表,仅支持提交时按文件落地确认;取消按钮随渠道能力显示。挂载点关联复用 `CloudPrefix` 和 `map_cloud_path` 完成入库路径转换。渠道标识与媒体来源分别用于提交和落地后处理,未新增依赖、账本表或迁移。账号未实际验证时不把模拟能力视为网盘验收。版本要求与安装入口由上游发布清单传给配置页;配置页安装当前 Peach 随附的同版脚本。 用户脚本由 [peach-mitao/peach-userscript](https://github.com/peach-mitao/peach-userscript)(AGPL-3.0-or-later)独立维护,使用 [Tampermonkey 官方 GM API](https://www.tampermonkey.net/documentation.php) 的本机存储、菜单与 `GM_xmlhttpRequest`;SPA 通知依据 `window.onurlchange` 契约。上游使用 Node.js 24 LTS 内置模块确定性构建,运行时零依赖。Peach 的 `web/integrations/` 消费同一发布的完整安装脚本与站点快照,固定版本、上游提交与 SHA256 见 `jav-userscript-release.json`。安装端点直接返回制品,后端独立校验已登记域名与作品参数;上游导出工具在隔离工作树同步这两份制品和来源记录。Sleazy 热门脚本只提供显式域名与镜像发现证据,不复制其实现或执行第三方代码。宿主扩展由用户安装,兼容性以实际浏览器及脚本管理器授权为准;模拟 GM API 的真实 Chromium 页面完成回归,DMM 与 MGS 实页通过隔离只读 GM 适配核验番号、页面浮层与设置窗口。真实扩展、Peach 与网盘联合下载验收未取得。 Peach 保留页面粗提取与身份冲突提示,服务端复用 `catalog_rules` 的唯一番号规则、`feeds.scan_code`、`web_resource_search.q_resource_search` 的来源顺序与质量排序、`submit_offline_download` 的 infohash 幂等、现有云下载落地与后处理。浏览器添加在共享提交锁内按番号接管已有任务,覆盖其他入口同时提交不同磁力的情况。失败原因直接复用下载任务的 `FAILURE_KINDS` 分为磁力与网盘两类;换磁力把失败任务的 infohash 记入该番号的跳过名单,带名单的搜索不在 manko.fun 高清命中处短路,并在直连与索引器结果中一并排除;候选挑选沿用同一番号判据。专用令牌经 `CredentialStore` 仅保存 SHA-256 摘要,不声明跨机同步字段。队列用已有 `atomic_write_text` 保存本机运行状态,关闭功能会撤销令牌并停止尚未提交的添加。 DMM / MGS 的只读商品号识别复用 `sources.dmm` 的 CID 结构与 `catalog_rules.release_code_from_product`。浏览器提交净化后的详情地址及可选厂家番号;DMM 的目录数字头按来源解释,MGS 保留三位发行前缀,尾字母和日期分隔符保留为身份。`release_code_from_text` 继续处理普通文件名的字幕与画质标记,不用文件名噪声规则改写明确商品身份。资源名称的完整商品号匹配复用同一编目模式,元数据身份校验与 DMM 搜索核对尾字母。运行时不新增 HTTP 请求或依赖;已有 DMM/OpenAver 取证与来源协议足以覆盖转换,不引入第二套外部番号库。完整脚本连接临时账本的真实识别接口,联合验证 DMM/MGS 桌面与手机场景;保留基于模拟响应的跨站交互回归。 配置页继续使用 BoardUI Button / Input / Select 与共享 Note。配对信息复用当前页面 origin、签发响应和浏览器 Clipboard API,脚本在用户粘贴时填表,保存后写入 GM 存储。同源子框架桥接只回报脚本版本和当前地址的配置状态,父窗口、origin、协议版本与一次性 nonce 均须匹配,不回传令牌。未收到回报显示「未检测到」,不推断安装列表。桥接路径窄匹配与来源站顶层注入分别处理;实际脚本管理器权限和扩展联合验收未取得。无新增运行依赖、迁移或 ledger 写入。 书签不能执行云下载流程;完整浏览器扩展增加发布与权限管理面;现有外部下载器不承接 Peach 的网盘目标、入库和后处理,因此未引入。临时账本与模拟 115/PikPak 的 API 回归验证搜索、重复点击、重启恢复、失败重试和凭据隔离;用户脚本及配置页通过桌面与 390×844 浏览器回归。无新增 ledger 表或迁移。 ## 长跑任务的结果显示 资料采集与关注检查复用已有字段判据、事务和候选复核。全部本地 NFO 先读取并按影片提交;在线资料按来源返回时提交,候选 CSV 仍按时间合并写入文件。关注列表的安全 partial 行与逐项详情分别保存,历史边界和整页游标沿用连接器规则。中断保留已提交结果,停止后不再落库。 显示层复用 SQLite `ledger_revision` 触发器、候选与图片目录版本,以及 TanStack Query 5.104.3(MIT)查询失效和任务轮询;不新增推送服务或依赖。应用根按结果版本刷新相关读缓存,任务心跳不使资料失效;慢请求期间的新版本排队,保留当前内容。资源同步扫描同时显示已完成来源,清理仍需完整扫描和确认。隔离账本、暂停的来源调用与手动放行的 Promise 验证中间结果可见及中断保留;无真实抓取或真实 ledger 写入。 ## STRM 与挂载来源 MKV 的关键帧索引复用 [ebmlite 3.4.1](https://pypi.org/project/ebmlite/3.4.1/)(MIT,纯 Python,93,430 字节 wheel,无运行时依赖)的 `decoding.readElementID`/`readElementSize`。Peach 只解释 SeekHead、Info、首条视频轨与 Cues,元数据读取上限 16 MiB,限制元素数与定位次数,遇到 Cluster 就停止顺序读取、按 SeekHead 跳到尾部索引;取不到索引时不猜关键帧,退回按 6 秒重编码。逐包 ffprobe 要遍历媒体,不用于网盘上的索引。MKV 分片的定位预卷先落本地临时片段,再由 FFmpeg segment muxer 在关键帧上裁齐,相邻两段时间轴连续。ebmlite 的 wheel 附带同名顶层 `tests` 包,仓库的 `tests/` 因此显式成包(`tests/__init__.py`),`tests.support` 不被遮蔽。实现采用 simon1561 的 [PR #158](https://github.com/peach-mitao/peach/pull/158);分级策略参考 [Plex Direct Stream](https://support.plex.tv/articles/200250387-streaming-media-direct-play-and-direct-stream/) 与 [Jellyfin 容器兼容说明](https://jellyfin.org/docs/general/clients/codec-support/#container-compatibility)。 诊断输出共用 `reporting_identity` 的环境身份和 `diagnostic_exceptions` 的有限错误分类。媒体 stderr 在通用路径脱敏前归类,SQLite 使用结构化错误码与固定原因类别;本机日志、支持包和远程投影按各自字段契约消费,不引入另一套错误监控 SDK。访问日志只放行固定技术路由与协议状态,查询串整体移除;其余路径继续复用通用脱敏。 任务恢复复用固定版 APScheduler 3.11.3(MIT)和标准库 `datetime.timezone.utc`,与现有关注调度器使用同一时区选择方式。一秒间隔检查不依赖本地 IANA 时区数据库;隔离回归令系统时区读取抛错,仍能创建调度器并注册任务。未新增依赖。 日志的实际主机时区名称复用 `tzlocal` 5.4.4(MIT,纯 Python,支持 Windows、macOS、Linux)的 `get_localzone_name()`,仅读名称,不为取证构造 `ZoneInfo`。该包已由 APScheduler 安装,直接使用处在主依赖中显式固定归属,无新增安装包;本地时间和 UTC 偏移复用 `datetime.astimezone()`,名称读取失败保留可用偏移。浏览器使用标准 `Intl` 与 `Date.getTimezoneOffset()`,与服务主机时区分别保存。 响应头策略复用 Starlette 1.8.0(BSD-3-Clause,项目已有固定依赖)的 `MutableHeaders` 与官方 [ASGI 中间件模式](https://www.starlette.io/middleware/#pure-asgi-middleware),只在 `http.response.start` 阶段设置缓存、安全及机器人策略。文件响应继续使用同一 `receive` 的断连消息,真实异常直接传播,不维护异常文本匹配或统一忽略网络错误的分支。整片转码继续复用 FFmpeg 和现有回退链,Peach 只保留有界本机证据与隐私投影,无新增依赖。 本机诊断继续复用项目的脱敏日志与 ZIP 导出,浏览器使用标准 `canPlayType()`、MSE、Resource Timing 和有界的 [UA Client Hints](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorUAData/getHighEntropyValues),服务端复用 Python 3.14 标准库的依赖元数据、磁盘余量、系统信息以及现有媒体探测缓存。字段白名单和本机证据汇总属于 Peach 的诊断边界;浏览器监控 SDK 会扩大依赖与采集范围,不承担本机导出流程。依赖沿用 Video.js 10.4.0 与现有 FFmpeg,不增加运行时依赖,不为导出执行媒体读取或硬件压力探测。能力声明与真实播放的区别按 [MDN `canPlayType()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canPlayType) 和 [Video.js 媒体来源契约](https://videojs.org/docs/framework/html/guides/media-sources)核对,隔离回归覆盖无视频请求、编码能力缺失、错误状态、脱敏和仅本机写入。 STRM 采用文本指针、播放时解析的通用行为,参考 SmartStrm 文档、OpenList 的 `drivers/strm` 与 Jellyfin 的 STRM 探测入口;固定 revision、许可证与实际读取位置见 [取证记录](reference-snapshots/strm-source-evidence.md)。SmartStrm 核心闭源,源码未取得。Peach 独立实现受限 HTTP(S) 指针,复用 HTTPX、现有 Range 传输、`m3u8` 解析与播放器计划;无新增运行依赖,也不复制上游应用代码。 光鸭、OneDrive 与其他网盘复用声明挂载根、路径翻译、扫描、文件整理与回滚、隔离删除和空目录清理。所有挂载来源统一开放读写,底层权限或不支持的操作由挂载工具报错;网盘登录与平台 API 由飞牛 OS 原生远程挂载、CloudDrive2 或 OpenList 等挂载工具提供,不新增 SDK 或依赖。本地文件先隔离再提交账本;rclone FUSE 通过挂载表识别并直接删除,避免部分后端的远端改名触发复制,账本事务失败时保留可重试的回收站记录。飞牛 OS 原生挂载 115 的实际文件系统可报告为 `fuse.rclone`,不等于用户单独部署 rclone;其他挂载方式仍须分别验证。临时文件与账本回归覆盖三个来源的整理、回滚、删除、权限拒绝和空目录清理;真实账号兼容性见待办。挂载目录可单独设置代理流量保护,成本投影与批处理使用同一规则。STRM、ISO 跳过后台媒体读取,普通媒体保留按来源策略执行的探测;九宫格和时间轴共用本机视频预览开关。 回收站复用 `platform.translate_ledger_path`、声明来源根与 Python 标准库 `stat`,只将 `FileNotFoundError` 视为文件缺失,权限或 I/O 错误保留记录。Linux 挂载判定读取原生 `/proc/self/mountinfo`,字段、父挂载关系与文件系统类型按 [Linux man-pages 6.19](https://man7.org/linux/man-pages/man5/proc_pid_mountinfo.5.html);采用最深挂载点,覆盖挂载按父子关系选择,不依赖文本行顺序。转义解码与路径比较属于 Peach 的删除策略,没有复制外部实现。rclone 挂载能力参考其[官方文档](https://rclone.org/commands/rclone_mount/),不新增 rclone 运行服务;现有 psutil 7.2.2 仅是开发依赖,不为读取一份 Linux 原生挂载表增加运行依赖。未知挂载信息保留本地隔离流程,临时文件回归覆盖带空格挂载点、父目录路径、覆盖挂载、删除失败与混合批次事务失败。 Actions 工作流静态检查复用 actionlint 1.7.12(MIT,`rhysd/actionlint:1.7.12` 官方 Docker 镜像),由本地 Docker action 使用,独立 Docker 目录纳入 Dependabot 与接管入口。GitHub Actions 生态不更新 `docker://` 镜像引用。Windows 官方二进制按发布校验和完成本地 POC;CI 在 Linux 容器检查语法、表达式、任务依赖与脚本。Python 与浏览器回归继续使用现有统一入口及 Playwright;六片浏览器权重来自 [已通过的 CI](https://github.com/peach-mitao/peach/actions/runs/38981261189) 的 69 份 TAP,记录在 `scripts/ci-browser-timings.json`,没有新增应用运行依赖。 目录浏览的 `media_folders` 复用 `PureWindowsPath`、媒体库配置的目录前缀和账本路径,不访问媒体挂载。`folder_rules` 复用 profile 偏好、规范实体、字段归属、身份断言、逐件归属否定和扫描登记入口;规则以 `user:directory-<目录标识>` 保存独立来源,预览摘要绑定资产版本与关系,撤回只处理本来源。已有明确归属保持独立。目录栏复用覆盖式滚动条,按筛选条下沿、目录实际位置与可见视口计算高度;共用查询的错误由正文或手机目录弹窗呈现一次,独立请求保留各自的重试。 界面逐字采用 MIT 许可的 BoardUI Tree View、Breadcrumb 与 Direction,固定源码 SHA-256 见 `frontend/src/react/boardui/ORIGIN.md`;复用现有 React 19.3.0、React Aria Components 1.22.1、Motion 14.1.0 与 Remix Icon 4.9.0,无新增依赖。Peach 的原生链接适配上游 `next/link` 槽,领域逻辑仅承担目录归属、冲突保留、范围确认和来源撤回。能力检索覆盖当前媒体库分组、目录否定、字段归属和 `media_libraries.py` 的 Git 历史;物理目录整理继续使用既有入口。验证只使用临时账本与合成馆藏。 Linux Docker 容器复用 Docker 官方 Python `3.14.8-slim-trixie`、uv `0.13.1`(MIT/Apache-2.0),以及 Docker 官方 Buildx、login-action 和 build-push-action 的「先验收再发布」流程。Python 镜像许可证随上游组件保留,FFmpeg 使用 Debian 包及其许可证。Peach 差异仅为配置重载、资料处理请求与持久化路径;不引入新 Python 依赖,不改写真实 ledger。CloudDrive2 使用其官方独立服务,不复制其代码或打包进 Peach。部署与证据范围见 [Docker 部署](DOCKER.md)。 Docker 一键更新复用 [nicholas-fedor/watchtower](https://github.com/nicholas-fedor/watchtower) 1.24.0(Apache-2.0,`nickfedor/watchtower:1.24.0`,2026-11-04 发布;原 `containrrr/watchtower` 已于 2025-12 归档)完成拉取与重建,作为 compose 的可选 profile 独立运行,版本由 Dependabot 的 docker-compose 生态更新。2026-11-14 对照 v1.23.2 与 v1.24.0 源码:`POST /v1/update?async=true` 立即回 202,更新处理器只改了内部包名;令牌经 `getSecretFromFile` 从文件读取,停容器时按容器自己的 `StopTimeout`。Peach 只保留开放条件、本机令牌与触发请求,传输复用 HTTPX。镜像仓库核对复用共享 `HttpxTransport`(跨源跳转时丢掉 `Authorization`),按 [Docker Registry HTTP API](https://distribution.github.io/distribution/spec/api/) 匿名 `HEAD` manifest 比较摘要,做法参照 [JavBoss `internal/update/container.go`](https://github.com/Solr159/JavBoss)(GPL-3.0,只参照协议用法,未复制代码)。拒绝给 Peach 容器挂 Docker socket 与自写更新容器的理由见 [ADR-0140](adr/0140-docker-one-click-update-via-watchtower.md);无新增 Python 或前端依赖。 收藏窗口复用 React Aria 外壳、Peach 设置弹层布局及共用关闭控件 `SettingsDialogClose`。入口为中性星形按钮;实体分类和保存的筛选分别显示,已标记与稍后看位于导航底部。收藏图像复用实体引用、厂牌标识、本地代表作与已绑定在线来源的本地头像代理,通过全站图片回退链逐项尝试,不写入偏好。原始 BoardUI 源码哈希见 `docs/BOARD_UI.md`。Rule34 视频封面使用来源缩略图,图片保留原文件扩展名;失败图片在关注数据刷新时重新尝试。无新增运行时依赖或真实 ledger 写入。 关注封面代理复用来源登记的媒体主机白名单;第三方图片地址及重定向继续执行公网 DNS 校验。 收藏弹层的导航复用设置页液态玻璃、`useViewGlide`、`attachOverlayScrollbar`、入场与退场关键帧及落影,桌面和手机检查实际计算样式。官方预告复用 amane `cc42cee6ecf290cf05af1caa347d2dc2d5aeffcd` 的 Prestige SKU→UUID 协议,通过官方返回的作品身份与公开 MP4 字段取得地址;读取复用既有来源传输、限制和媒体代理,无新增依赖。 媒体 indicator 复用关注详情的半透明灰底胶囊:`rgba(0,0,0,.5)` 底色、无描边、`--pill-radius` 圆角及既有圆点间距。滚动内容复用 `wireHorizontalScroller`、`data-overflow-left/right` 和 `board.css` 的左右渐隐,底衬保持完整。预告优先读取 DMM/厂牌官方声明,其次读取同一番号的 JavDB 详情,匿名 WebUI 作为备选。DMM 复用 `DmmSource` 的 CID 搜索、身份核对、GraphQL、`SourceTransport` 和媒体 Range 代理;`sample2DMovie.highestMovieUrl` 字段已按同一 amane 固定 revision(GPL-3.0,仅作协议证据)及真实官方响应核对,不引入上游代码或新依赖。DMM、JavDB 的正负缓存按来源隔离、每天可再检查;预告缺失与连接失败分别返回。`RCTD-764` 已通过 1 KiB Range 请求确认 206、`video/mp4` 和 MP4 文件头,身份不匹配、来源优先级、WebUI 失败、缓存与媒体主机边界由行为测试覆盖。 ## 设计准则参考 Open Claude UI(MIT)只用于[设计准则](DESIGN_GUIDELINES.md)与[源码取舍](reference-snapshots/open-claude-ui.md),原文锁定在 `reference-sources.json`。采用减少重复外框、语义排版、容器适配、输入法保护、保持阅读位置、可恢复手势、锚点缩放与真实反馈等原则;组件复用现有 BoardUI、React Aria、Motion、Swiper 和滚动入口。示例任务终态、全局样式、宿主、语音与专有协议不进入运行时。源码审阅完成,浏览器 POC 未取得;无新增依赖、生产设置或 ledger 写入。 ## 加载态语义动画 不定时长的后台推进按做的事画 [loading.dev](https://github.com/jakubkrehel/loading) 的五种动画:排队与等外部用 Clock,搜索、检查与探测用 Radar,传输用 LinearDots(兼做语义不明的通用后台推进),写入入库用 Gather,整理与分析用 Blocks。上游是 npm 包 `loading-dev` 0.3.6(MIT,revision `755235bf7eea3dfb05ec4c3661088e3521ee2d75`),与用户脚本 peach-jav 用同一 revision、同一次移植;许可原文在 `web/vendor/loading-dev-LICENSE.txt`,上游原文锁在 `reference-sources.json` 的 `loading-dev-*` 几条。不引入 npm 包:上游是带运行时 `