Peach: Local-first video metadata scraper and media manager.
docs(writing): 文档里的「兜底」「落盘」「闭环」「链路」改写成具体说法并由文案检查拦住
longmeidao3378269a642d
diff --git a/.claude/skills/peach-jav-cover-workflow/SKILL.md b/.claude/skills/peach-jav-cover-workflow/SKILL.mdindex df7e98716..2d129466f 100644--- a/.claude/skills/peach-jav-cover-workflow/SKILL.md+++ b/.claude/skills/peach-jav-cover-workflow/SKILL.md@@ -20,7 +20,7 @@ description: 获取、重探或比较 JAV 封面来源,以及维护人脸和## 获取与替换- 通过脚本的解码、身份、最小尺寸与图像类型检查后,按像素面积选择;同尺寸优先商品图。只在合格且更大时原子替换,失败保留原图。-- Range 读取先量尺寸,胜出后下载完整文件;JavDB 仅作核验证据,不安装、显示或作为缺图兜底。+- Range 读取先量尺寸,胜出后下载完整文件;JavDB 仅作核验证据,不安装、不显示,缺图时也不拿来补用。- 单条网络异常记录失败并继续,确认无候选与瞬时失败分别保存;每条完成后持久化日志,磁盘与流量按 `peach-batch-jobs`。- `--retry-misses` 重探缺失;`--upgrade-existing` 与 `--upgrade-max-width` 限定已有封面的升级范围,参数按当前脚本核对,批次额度不写成固定默认。diff --git a/.claude/skills/peach-reuse-first/SKILL.md b/.claude/skills/peach-reuse-first/SKILL.mdindex 348d54686..416339f7d 100644--- a/.claude/skills/peach-reuse-first/SKILL.md+++ b/.claude/skills/peach-reuse-first/SKILL.md@@ -20,7 +20,7 @@ description: 新增、恢复或重写 Peach 功能、外部协议、抓取、媒## 复杂度边界-- 新兜底、重试、兼容或竞态分支须有可触达输入、失败结果与依据;无依据的理论分支默认省略,必要的范围扩展由用户决定。+- 新增后备、重试、兼容或竞态分支须有可触达输入、失败结果与依据;无依据的理论分支默认省略,必要的范围扩展由用户决定。- 未知输入在负责的边界校验,内部沿用已成立的类型和契约;新信任边界仍须校验。失败与无结果分别表达,不用默认值伪造成功。- 单次使用的 helper 在表达独立概念或隔离复杂边界时才抽;注释说明非明显约束及后果。- 实体身份、跨来源绑定、凭据隔离、候选复核、任务语义与交互属于 Peach 差异;通用传输、解析、锁、媒体编解码与控件优先复用。diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.mdindex 6b87d60b2..ffc0e501b 100644--- a/docs/DIAGNOSTICS.md+++ b/docs/DIAGNOSTICS.md@@ -34,7 +34,7 @@## 证据链-| 链路 | 持久证据与核验 |+| 环节 | 持久证据与核验 || --- | --- || 启动、CLI、托盘 | 配置及可选依赖加载前安装异常钩子;主线程、后台线程、unraisable、asyncio 和 warning/error 日志写入 `errors-*.log`,原生故障写入 `crash-*.log`;不可写时使用备用目录 || HTTP 请求 | 未处理异常与 HTTP 5xx 记录 traceback、方法、路由模板、状态码和 `error_id`;响应头 `X-Peach-Error-ID` 与记录关联;请求参数、正文和鉴权头不作为上下文采集 |@@ -104,7 +104,7 @@ SQLite 错误复用本机与远程的结构化错误码;能够确定时附缺`state/remote-reporting-delivery.json` 保存各技术用途最后一批(错误事件、计数日志或版本统计)的本机回执,配置 API 的 `remote_reporting.delivery` 提供相同的脱敏状态。`queued` 仅表示准备入队;`accepted` 表示传输取得 HTTP 2xx,不保证接收端长期保留;`failed` 表示明确拒绝或本机队列/限流阻断;`unknown` 表示未取得可靠结果,网络异常也可能发生在接收之后。HTTP 2xx 同时带限流头时按未知处理。回执不保存服务端正文、请求网址或载荷;旧事件与旧同意版本的回执不能覆盖当前记录。传输回执不把入队计数改写成接收计数,也不触发补传。-两项均通过公开 DSN 发送到 Sentry 托管服务,接收服务会接触连接 IP。客户端不发送 IP 字段、用户身份、设备标识、观看记录、媒体信息、凭据、完整日志或诊断 ZIP。日志与会话条目由 Peach 自行组装,不经过 SDK 的日志与会话通道,主机名、SDK 名称与追踪上下文不进入载荷;传输闸门只放行带当前同意凭据的这两类条目。SDK 发送队列不落盘,本机聚合文件仅存技术投影和次数;后台发送前复查本机同意版本。关闭或重新选择会清除未提交聚合,并让排队旧事件失效;已在途或已接收的请求无法撤回。本机 ZIP 导出独立可用。+两项均通过公开 DSN 发送到 Sentry 托管服务,接收服务会接触连接 IP。客户端不发送 IP 字段、用户身份、设备标识、观看记录、媒体信息、凭据、完整日志或诊断 ZIP。日志与会话条目由 Peach 自行组装,不经过 SDK 的日志与会话通道,主机名、SDK 名称与追踪上下文不进入载荷;传输闸门只放行带当前同意凭据的这两类条目。SDK 发送队列不写入磁盘,本机聚合文件仅存技术投影和次数;后台发送前复查本机同意版本。关闭或重新选择会清除未提交聚合,并让排队旧事件失效;已在途或已接收的请求无法撤回。本机 ZIP 导出独立可用。接收端由维护者配置:源码运行使用 `PEACH_SENTRY_DSN` 或检出根的 `sentry.json`;Windows、macOS 打包与 Docker 镜像由 `scripts/write_reporting_config.py` 从同名环境变量(Docker 为同名构建参数)写入包根 `sentry.json`,镜像里位于 wheel 的 `peach/_resources/`,容器运行时设置的同名环境变量优先。发行流水线从 GitGud 项目 CI/CD 变量 `PEACH_SENTRY_DSN` 与 `PEACH_LIBRARY_SENTRY_DSN` 读取,两者为受保护变量、环境作用域 `release`;缺失或不合法时发行构建失败,本地构建写空值,安装后显示上传服务未配置。只接受 Sentry 的公开 HTTPS DSN(含 US / DE 区域),不需要 API token。没有 DSN 时不会创建 SDK 客户端。SDK 自动框架集成、自带的日志与会话采集、性能追踪和指标均关闭。账号套餐和总量以 [Sentry 订阅页](https://sentry.io/settings/) 为准。diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex 8a912039a..b2f5a8d29 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -300,7 +300,7 @@ Windows 测试包默认使用 `%LOCALAPPDATA%\Peach\peach-data`。首次设置| 任务 | 保存与恢复的单位 || --- | --- || 扫描文件 | 来源根、待遍历目录和目录内的已提交文件批次;保留文件数、字节数与字幕配对资料 |-| 读取配套资料、采集元数据与预览 | 已读取的本地证据、已落盘候选与已登记预览;保留完成影片和问题记录 |+| 读取配套资料、采集元数据与预览 | 已读取的本地证据、已写入的候选与已登记预览;保留完成影片和问题记录 || 拉取关注更新、历史回抓 | 固定来源集合、成功来源与已提交页码;从头回抓任务沿用本次保存的页码 || 新作订阅、想要资料、发现卡资料 | 已完成来源或番号、已保存资料与封面;发现卡同时保留已消耗请求与流量预算 || 后继任务、下载后处理 | 原有持久队列与同一条任务记录;批量资料与样张保存原始番号集合和成功项目 |@@ -703,7 +703,7 @@ PikPak 官方核验通道使用「推送发现」中该媒体根对应的唯一### 首次设置的内部流程- 首次设置的「Peach 代理」支持跟随环境、直连和自定义 HTTP/SOCKS 代理。自定义地址与端口沿用配置页校验,凭据存于所选数据目录的本机 secrets;读题接口只返回连接方式和是否已保存地址。Docker 中填写回环代理地址时提示改用容器可访问的宿主机地址。配置页「网络与访问」可随时修改。-- `GET /api/setup/questions` 的 `peach_proxy` 包含 `mode`、`proxy_saved`、`needs_selection`;`docker` 表示部署是否为 Docker。`POST /api/setup` 的 `peach_proxy` 接收 `{mode, proxy}`,`mode` 为 `environment`、`direct` 或 `proxy`,缺省为 `environment`。校验错误放在 `errors.peach_proxy`。代理先于 `config.toml` 和首扫请求落盘,保证托盘切换后使用所选连接方式。+- `GET /api/setup/questions` 的 `peach_proxy` 包含 `mode`、`proxy_saved`、`needs_selection`;`docker` 表示部署是否为 Docker。`POST /api/setup` 的 `peach_proxy` 接收 `{mode, proxy}`,`mode` 为 `environment`、`direct` 或 `proxy`,缺省为 `environment`。校验错误放在 `errors.peach_proxy`。代理设置先于 `config.toml` 和首扫请求写入磁盘,保证托盘切换后使用所选连接方式。- 托盘启动时读一次设置文件,由 `tray.needs_setup()` 判断:**没有 `config.toml` 且没有数据库**才算需要首次设置。不用 `PeachConfig.configured` 判断:托盘的单实例锁一启动就会在 Peach 数据目录下建出 `state/`,一次失败的启动就可能让下一次误判成已配置;反过来,没有 `config.toml` 的老部署数据库还在,不能被拖进首次设置。- 需要设置时,托盘不构建正常的服务规格(全新机器上 `build_service_specs()` 会因为缺 TLS 材料抛 `FileNotFoundError`),而是启动 `peach serve --setup --host 127.0.0.1 --port <设置里的端口,默认 8900> --no-mdns --no-ledger-sync`,再把浏览器打开到 `http://127.0.0.1:<端口>/`。这条引导服务没有 TLS,口令强制为空,安全边界就是回环绑定地址。- 首页是首次设置表单:`GET /` 回一张薄壳(`routes_pages.setup_shell()`),表单由页面包 `/dist/peach-pages.js` 画出,题目与提交都走下面两条 JSON 接口。完成态的入口带 `/?onboarding=1`;选了导入浏览器历史则先去 `/taste?onboarding=1`。安装教程通过专用状态接口读取各项的实际状态。diff --git a/docs/RESOURCE_SEARCH.md b/docs/RESOURCE_SEARCH.mdindex 2eb462a31..a017ff388 100644--- a/docs/RESOURCE_SEARCH.md+++ b/docs/RESOURCE_SEARCH.md@@ -34,7 +34,7 @@ Peach 通过 Prowlarr 或 Jackett 提供的 Torznab 接口查询资源。先在2. 检查候选的番号、体积、做种与质量信息。3. 选中所需候选后提交下载。-有候选表示搜索链路可用;提交下载还需要独立配置 115 或 PikPak。CloudDrive2 的设置见 [完整配置与调优说明](CLOUDDRIVE.md)。+有候选表示搜索功能可用;提交下载还需要独立配置 115 或 PikPak。CloudDrive2 的设置见 [完整配置与调优说明](CLOUDDRIVE.md)。## 常见问题diff --git a/docs/REUSE.md b/docs/REUSE.mdindex 989ca642d..c4900f597 100644--- a/docs/REUSE.md+++ b/docs/REUSE.md@@ -329,11 +329,11 @@ DMM / MGS 的只读商品号识别复用 `sources.dmm` 的 CID 结构与 `catalo配置页继续使用 BoardUI Button / Input / Select 与共享 Note。配对信息复用当前页面 origin、签发响应和浏览器 Clipboard API,脚本在用户粘贴时填表,保存后写入 GM 存储。同源子框架桥接只回报脚本版本和当前地址的配置状态,父窗口、origin、协议版本与一次性 nonce 均须匹配,不回传令牌。未收到回报显示「未检测到」,不推断安装列表。桥接路径窄匹配与来源站顶层注入分别处理;实际脚本管理器权限和扩展联合验收未取得。无新增运行依赖、迁移或 ledger 写入。-书签不能执行云下载链路;完整浏览器扩展增加发布与权限管理面;现有外部下载器不承接 Peach 的网盘目标、入库和后处理,因此未引入。临时账本与模拟 115/PikPak 的 API 回归验证搜索、重复点击、重启恢复、失败重试和凭据隔离;用户脚本及配置页通过桌面与 390×844 浏览器回归。无新增 ledger 表或迁移。+书签不能执行云下载流程;完整浏览器扩展增加发布与权限管理面;现有外部下载器不承接 Peach 的网盘目标、入库和后处理,因此未引入。临时账本与模拟 115/PikPak 的 API 回归验证搜索、重复点击、重启恢复、失败重试和凭据隔离;用户脚本及配置页通过桌面与 390×844 浏览器回归。无新增 ledger 表或迁移。## 长跑任务的结果显示-资料采集与关注检查复用已有字段判据、事务和候选复核。全部本地 NFO 先读取并按影片提交;在线资料按来源返回时提交,候选 CSV 仍按时间合并落盘。关注列表的安全 partial 行与逐项详情分别保存,历史边界和整页游标沿用连接器规则。中断保留已提交结果,停止后不再落库。+资料采集与关注检查复用已有字段判据、事务和候选复核。全部本地 NFO 先读取并按影片提交;在线资料按来源返回时提交,候选 CSV 仍按时间合并写入文件。关注列表的安全 partial 行与逐项详情分别保存,历史边界和整页游标沿用连接器规则。中断保留已提交结果,停止后不再落库。显示层复用 SQLite `ledger_revision` 触发器、候选与图片目录版本,以及 TanStack Query 5.104.3(MIT)查询失效和任务轮询;不新增推送服务或依赖。应用根按结果版本刷新相关读缓存,任务心跳不使资料失效;慢请求期间的新版本排队,保留当前内容。资源同步扫描同时显示已完成来源,清理仍需完整扫描和确认。隔离账本、暂停的来源调用与手动放行的 Promise 验证中间结果可见及中断保留;无真实抓取或真实 ledger 写入。@@ -347,7 +347,7 @@ DMM / MGS 的只读商品号识别复用 `sources.dmm` 的 CID 结构与 `catalo响应头策略复用 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.3.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)核对,隔离回归覆盖无视频请求、编码能力缺失、错误状态、脱敏和仅本机写入。+本机诊断继续复用项目的脱敏日志与 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.3.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` 解析与播放器计划;无新增运行依赖,也不复制上游应用代码。@@ -463,7 +463,7 @@ JAV 作品详情与馆藏视频共用 `IdentityCell` 的头像、标识和首字配置页中的来源凭据复用 `Section`、`Stack` 与 `SettingsSectionLabel`;独立凭据页面保留自己的面板层级。自定义来源表单和卸载开关只使用一层正文间距,列表与表单操作区复用 `Footer`;空来源列表的添加入口放在 `Stack` 正文中。PikPak 直接显示账号表单,两种登录动作同排。在线、离线等连接状态复用 BoardUI `StatusDot`;权限、任务和凭据结果复用 `Chip`。作品资料站点标识经 `/site-mark` 读取本地缓存,资源搜索帮助直达 [详细配置说明](RESOURCE_SEARCH.md)。不新增运行时依赖,不修改凭据内容或 ledger。-账号归属复用 `review_decision`、`creator_collection_base`、`write_owned_fields` 和全库归属审计。明确拒绝的资产与账号组合在自动摄取时跳过;用户写入保留复核入口。网黄博主只命中可信个人、内容创作者或发布账号断言,未分类账号保留全部名册入口。`attach_avatar_availability` 集中处理资料页、索引、搜索与统计的作品头像:发布账号缺少本人或出演职业证据时作品帧照常兜底,另标 `avatar_stand_in`,已安装图片独立保留。个人博主的补头像复用 `avatar_cover_face.face_square`、`readable_cut` 与 ADR-0074 的 `agreeing` 两部互证,画面取自接触印相九格(ADR-0099)。来源核查清单、逐关系回执和备份存于 `peach-data/review/`。+账号归属复用 `review_decision`、`creator_collection_base`、`write_owned_fields` 和全库归属审计。明确拒绝的资产与账号组合在自动摄取时跳过;用户写入保留复核入口。网黄博主只命中可信个人、内容创作者或发布账号断言,未分类账号保留全部名册入口。`attach_avatar_availability` 集中处理资料页、索引、搜索与统计的作品头像:发布账号缺少本人或出演职业证据时照常用作品帧代替,另标 `avatar_stand_in`,已安装图片独立保留。个人博主的补头像复用 `avatar_cover_face.face_square`、`readable_cut` 与 ADR-0074 的 `agreeing` 两部互证,画面取自接触印相九格(ADR-0099)。来源核查清单、逐关系回执和备份存于 `peach-data/review/`。`entity_identity_research` 与 `apply_entity_identity_research.py` 复用规范实体写入、字段归属保护、只读预览、SQLite 备份及冻结计划。逐行撤回回执核对后续修改,新增实体有额外引用时拒绝删除;观看历史和人工判断不被回滚覆盖。资料站调研复用 `performer_alias_followup.WikiSitePages`(包着 `sources/seesaa.py` 的 `WikiPages`,加 404 记忆与按站冷却)、作品表解析 `rows()` 与 `person_profile`,以及 EUC-JP 页名直取写法,不新增依赖;`creator_identity_followup` 的后继壳照抄补厂牌、补别名两条。@@ -625,10 +625,10 @@ OneJAV、Free JAV Torrent 只给种子链接。这类条目经索引器同源的- 任务起跑与安装预约复用已固定的 filelock 4.2.0(MIT,Windows/macOS/Linux,无额外依赖)和原子 JSON。`update_tasks` 在同一数据目录内串行登记任务和预约安装,覆盖各服务进程、任务中心、后继领取和 `job_main` 批处理。安装请求触发采集任务在检查点保存并暂停,任务中心保留 `pending` 行;新采集请求进入等待。安装入口等在途步骤保存进度,随后停止自己的服务,不要求用户等待整轮任务结束。源码批处理保留 PID 锁,写完在途批次后等待安装,结束后由原进程继续。- 安装器在临时目录展开随包运行时,以 `--installer-prepare` 承接馆藏处理状态并暂停任务;预约归安装器持有,完成或取消时释放。在线更新将预约交给更新助手,切换目录和迁移完成后释放,失败回滚也释放。恢复轮询复用 APScheduler,安装取消时现有服务也会接回任务。不采用新任务队列或更新框架:任务语义、PyInstaller 目录切换和 Inno Setup 生命周期继续由已有实现承担。-- `job_recovery` 保存馆藏处理范围、阶段、指定影片、时间轴密度、单部封面、关注、订阅和想要资料的请求;服务启动或安装结束后只领取未完成记录。暂停任务复用任务中心的同一行,已完成、失败和主动停止的任务不循环重试。馆藏预览在产物登记后保存影片检查点,元数据检查点跟随候选 CSV 成功落盘;未取得结果的项目不记完成。时间轴复用已有索引判定。恢复领取和新任务起跑共用安装闸门,数据仍留在本机 state 目录,不引入 ledger 迁移。+- `job_recovery` 保存馆藏处理范围、阶段、指定影片、时间轴密度、单部封面、关注、订阅和想要资料的请求;服务启动或安装结束后只领取未完成记录。暂停任务复用任务中心的同一行,已完成、失败和主动停止的任务不循环重试。馆藏预览在产物登记后保存影片检查点,元数据检查点跟随候选 CSV 成功写入;未取得结果的项目不记完成。时间轴复用已有索引判定。恢复领取和新任务起跑共用安装闸门,数据仍留在本机 state 目录,不引入 ledger 迁移。- 自动更新设置用 APScheduler(见「必须复用」表的定时轮询)、共享 HTTPX 发行查询、filelock 与原子 JSON 写入,安装走 `standalone_update`。按 [interval trigger](https://apscheduler.readthedocs.io/en/3.x/modules/triggers/interval.html) 每分钟查是否到期,本机持久时间与文件锁协调多个服务;关闭、6/24/168 小时间隔与源码下载限制归 Peach。默认关闭,下载只准备安装,重启仍需确认;设置存 state 目录的 `automatic-updates.json`。-- 版本与资产信息用 [GitHub Releases REST API](https://docs.github.com/en/rest/releases/assets)(测试通道含预发布),查询与流式下载用项目 HTTPX,ZIP 解压用标准库,互斥用 FileLock。只有已上传完整独立包的发布才进更新,优先选择 `*-update.zip`,历史完整 ZIP 保留原名供旧客户端更新。`package_windows_release.py` 从同一构建目录生成完整包、应用更新包与 FFmpeg、untrunc、cloudflared、人脸模型(`face-models`)工具包;更新包内清单固定工具文件哈希、工具包大小与 SHA-256,运行时只复用校验相符的文件,按需下载不符的工具。清单可以多出本版不认得的工具,读取时只留本版认得的那些,认得的一个都不能少;新增工具包由该工具自己的运行时兜底补齐,不让旧版更新器拒收整个更新包。工具包路径限于对应工具目录,补齐后再次校验并沿用同卷暂存与目录回滚。复用已有 HTTPX、hashlib、zipfile、copy2,无新增依赖;不引入 Velopack 的包格式或二进制差分机制。隔离回归用实际生成的 ZIP 验证工具复用、独立补下载与失败保留现有安装,不使用真实 ledger。+- 版本与资产信息用 [GitHub Releases REST API](https://docs.github.com/en/rest/releases/assets)(测试通道含预发布),查询与流式下载用项目 HTTPX,ZIP 解压用标准库,互斥用 FileLock。只有已上传完整独立包的发布才进更新,优先选择 `*-update.zip`,历史完整 ZIP 保留原名供旧客户端更新。`package_windows_release.py` 从同一构建目录生成完整包、应用更新包与 FFmpeg、untrunc、cloudflared、人脸模型(`face-models`)工具包;更新包内清单固定工具文件哈希、工具包大小与 SHA-256,运行时只复用校验相符的文件,按需下载不符的工具。清单可以多出本版不认得的工具,读取时只留本版认得的那些,认得的一个都不能少;新增工具包由该工具在运行时自行补齐,不让旧版更新器拒收整个更新包。工具包路径限于对应工具目录,补齐后再次校验并沿用同卷暂存与目录回滚。复用已有 HTTPX、hashlib、zipfile、copy2,无新增依赖;不引入 Velopack 的包格式或二进制差分机制。隔离回归用实际生成的 ZIP 验证工具复用、独立补下载与失败保留现有安装,不使用真实 ledger。- Windows 源码运行在配置页安装 FFmpeg、untrunc(`media_tools.py`)复用同一批工具包和更新器的下载、签名摘要与解压路径检查;没有更新包清单,逐文件摘要取工具包自带的 `manifest.json`。工具包与程序版本无关,取两个发布源里最新的那份,不按源码版本号拼地址。- 安装策略与进度归 Peach:下载校验后在程序同卷暂存,用户确认重启,复制出来的包内助手等原托盘退出再切换完整目录;失败保留或恢复旧目录。配置、数据库与媒体不进更新包。- 轻量安装包复用应用更新包的工具清单、`standalone_update.prepare_tools` 与既有 HTTPX、hashlib、zipfile。Inno Setup 6.7.3 用 [external 文件](https://jrsoftware.org/ishelp/topic_filessection.htm)安装临时目录中已验证的工具,用[滚动进度页](https://jrsoftware.org/ishelp/topic_isxfunc_createoutputmarqueeprogresspage.htm)显示准备状态;官方 API 已于 2026-10-17 核对。工具先在预检目录准备,成功后才暂停任务并覆盖安装;安装包旁的工具 ZIP 同样按清单校验,不读取馆藏配置或增加依赖。不引入另一套下载器或更新框架,校验及解压路径与在线更新共用。@@ -646,7 +646,7 @@ JAV 默认封面(官方封面/预览图)与视频默认大小(大图/图片尺寸档复用 `previews.DerivedImageService`:实体图默认取长边 640 的 `/entity-image?thumb=1`,只有资料页大位取原件;卡片封面按屏幕像素密度从 `/cover?thumb=2`(长边 800)或 `thumb=1`(长边 1600)起步,`framing.upgradeCover` 量过显示尺寸再逐档换到原件。两档封面同在 `generated/cover-thumbs/`,按长边分文件名、按需生成。侧栏与登录卡的站标用 `scripts/generate_brand_assets.py` 缩出的 64 与 128 px 小图,以 `srcset` 挑选。-新作封面复用 `best_cover` 的官方候选与 `cover_artwork.install_cover`,保存本地封面、正封框、人脸坐标与来源证据。JavDB 图片仅作来源复核证据,不进入安装、封面索引、详情封面投影或缺图兜底;`scripts/quarantine_javdb_covers.py` 将有来源证据的历史图片及边车移入可恢复归档。未取得合格来源时显示未取得状态,详见 ADR-0107。+新作封面复用 `best_cover` 的官方候选与 `cover_artwork.install_cover`,保存本地封面、正封框、人脸坐标与来源证据。JavDB 图片仅作来源复核证据,不进入安装、封面索引、详情封面投影或缺图时的后备;`scripts/quarantine_javdb_covers.py` 将有来源证据的历史图片及边车移入可恢复归档。未取得合格来源时显示未取得状态,详见 ADR-0107。无快照的有码作品由封面入口复用现有 `DmmSource` 的 GraphQL 查询与精确身份核验;成功快照直接展开 DMM 图片候选,r18.dev 与 DMM 使用同一份目录证据。FC2 来源快照通过 `storage_original` 提取发行方存储原件,排除社区图床。目录查询沿用来源冷却,HTTP、网络与解析失败分别保留未取得状态。@@ -903,7 +903,7 @@ A 盘垃圾隔离使用短名称 `peach-purge-<32 位 UUID>.peach-quarantine`,- 番号取封面(`POST /api/avatar-code-cover` → `avatar_picker.code_cover`)不要求番号在馆藏:本机封面目录优先,没有才走 `jav_cover_fetch.best_cover`,按番号只存对象、不写证据,之后的 `cover:<番号>` 只读本机。- 默认框围着 `avatar_picker.cover_focus` 取景:有脸取 `avatar_cover_face.face_square`(要边车里有脸宽与 `px`,缺的 `detect_cover_faces.py --redo`),没脸取 `jav_poster_crop` 的正封,前端不另抄判据。- 整张作品封面不装成头像:单人作品关联不证明画面里是谁,`cover_fallback` 标身份未核实,采集脚本的安装闸门拒收。图库给不出唯一人像时,补头像后继(`peach.avatar_followup`)从单人作品封面截脸周围一块方图(`peach.avatar_cover_face`,YuNet 脸框放大 2.4 倍),按脸宽像素挑封面、最差是缩略图,其余检得出脸的封面各截一张进候选缓存(至多 8 张)。面具、眼罩照样算脸,检不出的不降门槛去捞(低分框多落在手和身体上)。来源记 `cover-face` 与 `identity_verified: false`。- - 图库同名多张时先按脸认人(`peach.face_match`,互证与小图作证见 ADR-0056、0057、0062、0066);封面未匹配时仍允许不同来源、不同照片的图库多数独立互证(ADR-0104)。短边至少 300 像素的档案小图优先于封面裁片(ADR-0102),更小的图在封面落空时兜底。身份判据复用 `match_gallery`,来源标 `gallery_small`,可升级至标准图库人像。+ - 图库同名多张时先按脸认人(`peach.face_match`,互证与小图作证见 ADR-0056、0057、0062、0066);封面未匹配时仍允许不同来源、不同照片的图库多数独立互证(ADR-0104)。短边至少 300 像素的档案小图优先于封面裁片(ADR-0102),更小的图只在没有封面时作为后备。身份判据复用 `match_gallery`,来源标 `gallery_small`,可升级至标准图库人像。- 自动封面头像可换为合格档案人像或更清晰封面,人挑的不碰;候选列表按本机内容及默认裁切哈希去重,保留在用状态、具体来源与作品全部底图。展示去重不参与身份判断,不联网取图,不删除历史缓存。- 外部来源 genre 只在 `peach.genre_taxonomy` 投影:JavDB `類別` 与日英来源词共用词表,非内容分类排除,未收录原文回传登记;查表只有 `resolve_genre` 一处,抓取与复核折叠共用。r18dev 取 `categories[].name_ja`,日文取不到才用英文。有码标签的来源选择复用 `metadata_policy.preferred_tag_source(code)`,排序、采集与复核一致;替换走 `metadata_auto_apply` 的来源归属与人工判断保护(ADR-0100),不另写直写流程。- 中文来源词的有限简体别名由 `generate_genre_simplified.py` 使用已有开发依赖 OpenCC 1.4.2(Apache-2.0)生成,冲突拒绝;别名保存在 `genre_taxonomy` 的独立区块,历史词表从同一个 Git 版本读取完整规则,运行时无需 OpenCC。覆盖全部登记词的繁简投影测试保留人工决定优先级和未知词出口,无新增依赖或真实账本写入。@@ -1020,7 +1020,7 @@ amane 查询与桥环境重建也使用 `CREATE_NO_WINDOW`,保留标准输出抽帧与拼图通过现有 Pillow 12.3.0(HPND)完整解码输出图像,不按压缩文件大小推断有效性。复用既有 FFmpeg、色彩元数据重试与 `support_bundle`:失败记录包含采样秒数、时长、退出码、超时、工具来源和各次尝试的错误输出,错误原文截断并脱敏。诊断 ZIP 收集处理状态、最近 8 份问题清单及启动、更新、隧道证据。普通日志读取尾部 96 KiB,JSONL 按完整近期记录取尾;完整 JSON 在 16 MiB 内解析,脱敏后按 96 KiB 投影并优先保留任务状态与计数。超限、空文件与坏 JSON 在清单中明确标记,媒体名称留在本机。有效的不足 1 KiB JPEG、中文路径、失败重试和诊断导出均有回归;FFmpeg 参数依据[官方文档](https://ffmpeg.org/ffmpeg.html),不引入 ffmpeg-python 等命令包装层,不写真实 ledger。核验范围见 [日志与诊断核验](DIAGNOSTICS.md)。-Windows FFmpeg 9.0.2 静态链接 VideoLAN dav1d 1.5.4(BSD-2-Clause,官方源码 1,038,852 字节,Meson + NASM,支持 Windows x64 与 8/10-bit AV1)。版本、HTTPS 来源与 SHA256 固定在 `scripts/ffmpeg-sources.json`,源码和许可证随对应源码归档分发;完整工具的 FFmpeg 二进制增加约 3 MiB,不新增 Python 运行依赖。原生 `av1` 包装器依赖硬件解码,浏览器可播放不能作为 FFmpeg 软件解码证据;CPU 解码直接采用维护中的 dav1d,不为当前仅需解码的链路引入 libaom 编码库。发行验收使用合成 AV1 片段确认 CPU 解码与抽帧。构建参数依据 [FFmpeg libdav1d 文档](https://ffmpeg.org/ffmpeg-codecs.html#libdav1d) 和 [VideoLAN 固定发行源码](https://download.videolan.org/pub/videolan/dav1d/1.5.4/)。+Windows FFmpeg 9.0.2 静态链接 VideoLAN dav1d 1.5.4(BSD-2-Clause,官方源码 1,038,852 字节,Meson + NASM,支持 Windows x64 与 8/10-bit AV1)。版本、HTTPS 来源与 SHA256 固定在 `scripts/ffmpeg-sources.json`,源码和许可证随对应源码归档分发;完整工具的 FFmpeg 二进制增加约 3 MiB,不新增 Python 运行依赖。原生 `av1` 包装器依赖硬件解码,浏览器可播放不能作为 FFmpeg 软件解码证据;CPU 解码直接采用维护中的 dav1d,不为当前只需解码的场景引入 libaom 编码库。发行验收使用合成 AV1 片段确认 CPU 解码与抽帧。构建参数依据 [FFmpeg libdav1d 文档](https://ffmpeg.org/ffmpeg-codecs.html#libdav1d) 和 [VideoLAN 固定发行源码](https://download.videolan.org/pub/videolan/dav1d/1.5.4/)。macOS CI 的抽帧与 AV1 软件解码回归使用 [Homebrew FFmpeg formula](https://formulae.brew.sh/formula/ffmpeg) 提供的原生工具,随非 core 测试域安装;实际版本和解码能力由安装日志与媒体回归核对。Windows CI 保留固定版本的 setup-ffmpeg,发布包继续使用自构建工具;不新增 Python 依赖,不改生产入口或真实 ledger。@@ -1113,7 +1113,7 @@ Python 源文件纳入 `src/peach/library_sharing.py` 与 `src/peach/library_pro逐轮资源读数复用 psutil 的 native thread ID、线程 CPU 时间和已登记子进程身份,按本机总 CPU 容量归一化;父子汇总按计数器身份去重。Windows GPU 使用标准库 ctypes 调用 [PDH GPU 引擎计数器](https://learn.microsoft.com/en-us/windows/win32/perfctrs/performance-counters-portal),按物理引擎汇总所属子进程并显示最忙引擎;不把共享服务的 GPU 占用分配给单一任务。网络复用现有 HTTPX 下载字节计量,以相邻采样差分取得下载速度,挂载和无法归属的传输明确未取得。资源归属沿任务控制上下文登记,以原子 JSON 支持命令行任务;读取校验服务 PID 与创建时间,历史任务不保留过期实时数值。界面复用 BoardUI `Chip` 的蓝、紫、青与红色状态 token,取消确认复用现有 `confirmModal`。未新增依赖。-长时任务续跑复用 `job_recovery` 的本机原子记录、`BackgroundJob.checkpoint` 与 `TaskRunHandle.checkpoint`。主任务保留原 `job_id`、`run_id`、开始时间、处理范围和领域检查点;后继重排保留原进度。扫描复用现有 `os.scandir`、SQLite 批次提交、`filelock` 和 `fsutil.atomic_write_text`,保存遍历栈、文件名游标及字幕配对资料。本地资料按影片保存小份证据边车,候选成功落盘后才提交元数据完成集合;整理逐项原子保存同一批次的日志。`scrape_codes.py` 复用流式 CSV 与原始来源快照,续跑只保留已确认完成的番号,未完成番号可以重放。+长时任务续跑复用 `job_recovery` 的本机原子记录、`BackgroundJob.checkpoint` 与 `TaskRunHandle.checkpoint`。主任务保留原 `job_id`、`run_id`、开始时间、处理范围和领域检查点;后继重排保留原进度。扫描复用现有 `os.scandir`、SQLite 批次提交、`filelock` 和 `fsutil.atomic_write_text`,保存遍历栈、文件名游标及字幕配对资料。本地资料按影片保存小份证据边车,候选成功写入后才提交元数据完成集合;整理逐项原子保存同一批次的日志。`scrape_codes.py` 复用流式 CSV 与原始来源快照,续跑只保留已确认完成的番号,未完成番号可以重放。当前树、扫描与采集的 Git 历史,以及现有任务队列均已核对;不引入新的调度或工作流依赖。项目已固定的 APScheduler 3.11.3(MIT)负责派发,其持久 job store 记录调度任务,不能保存函数执行到哪一条影片或来源页,见[上游调度说明](https://apscheduler.readthedocs.io/en/3.x/userguide.html#adding-jobs)。结果替换沿用 Python 3.14 标准库 [`os.replace`](https://docs.python.org/3.14/library/os.html#os.replace)(PSF),锁沿用项目固定的 `filelock`,没有新增运行时体积或平台要求。隔离实证覆盖目录与目录内批次中断、关注回抓游标、固定来源集合、原任务标识与计数、候选 CSV 保留及同批整理日志;不读取真实媒体、不访问外部采集来源,也不写真实 ledger。diff --git a/docs/TESTING.md b/docs/TESTING.mdindex c4760a6f3..aaeb8930f 100644--- a/docs/TESTING.md+++ b/docs/TESTING.md@@ -166,7 +166,7 @@ Windows 隔离 E2E 浏览器对 [Chromium 572515601](https://issuetracker.google录制按「方法 + 规范化 URL + 请求体 SHA-256」匹配,不比请求头。响应只存状态、最终地址与 `content-type`;图片只存尺寸与哈希,回放时生成同尺寸灰图;视频只存字节数。录制里的 payload 是当日解析器的输出、经人工过目,用例另核番号、标题、日期、女优、厂牌与封面地址的形状。-录制只由 `scripts/record_source_fixtures.py 来源:番号` 联网取得,CI 里该脚本直接拒绝。它把代理设置、连接设置与生产冷却记录复制进临时根再请求,冷却期内的站照样不发;不写 ledger,也不写生产冷却。默认不带 Cookie;`--with-credentials` 只用于不登录拿不到作品页的站,Cookie 值、CSRF 令牌与账号标识换成固定假值。去掉脚本、样式等与解析无关的区块后,脱敏与瘦身两步各回放一次,结局变了就不采用这一步。连接失败、冷却、限流、验证页、封禁与地区限制不落盘,记为「未取得」。已有录制要加 `--update` 才重录。番号取站上公开作品,不从个人馆藏挑选。+录制只由 `scripts/record_source_fixtures.py 来源:番号` 联网取得,CI 里该脚本直接拒绝。它把代理设置、连接设置与生产冷却记录复制进临时根再请求,冷却期内的站照样不发;不写 ledger,也不写生产冷却。默认不带 Cookie;`--with-credentials` 只用于不登录拿不到作品页的站,Cookie 值、CSRF 令牌与账号标识换成固定假值。去掉脚本、样式等与解析无关的区块后,脱敏与瘦身两步各回放一次,结局变了就不采用这一步。连接失败、冷却、限流、验证页、封禁与地区限制不写入录制文件,记为「未取得」。已有录制要加 `--update` 才重录。番号取站上公开作品,不从个人馆藏挑选。## 正式入口diff --git a/docs/UI_PREVIEW.md b/docs/UI_PREVIEW.mdindex d56305aa3..88542548c 100644--- a/docs/UI_PREVIEW.md+++ b/docs/UI_PREVIEW.md@@ -30,7 +30,7 @@源码预览的页面、`PROJECT_ROOT`、文案来源、备份和构建产物必须指向本任务隔离工作树。预览仍拦截业务写入,只向本机同源编辑器放行 `POST /dev/copy-save` 和 `POST /dev/copy-apply`;沿用认证、来源摘要校验与备份。Python 文案的重载只针对本任务预览进程,不交给生产托盘。演示站沿用浏览器草稿,不宣称已写回源码。-提供预览前,在目标页面确认「文案编辑」浮条、悬停范围、原位输入和取消操作可用。首次接入或保存链路变化时,用隔离的临时源码副本核对保存、构建或重载、刷新后生效及 `edit` 参数保留;同一工作树和入口的有效证据可复用。核对后恢复临时文案,保留用户修改。未取得某项能力时说明具体页面和错误,不宣称可编辑预览已就绪。+提供预览前,在目标页面确认「文案编辑」浮条、悬停范围、原位输入和取消操作可用。首次接入或保存流程变化时,用隔离的临时源码副本核对保存、构建或重载、刷新后生效及 `edit` 参数保留;同一工作树和入口的有效证据可复用。核对后恢复临时文案,保留用户修改。未取得某项能力时说明具体页面和错误,不宣称可编辑预览已就绪。布局验收和控件操作使用普通查看状态;文案编辑版可通过「暂停编辑」操作页面。编辑器产生的源码修改纳入当前任务的 diff、回归和集成,不写真实账本或修改生产配置。diff --git a/docs/WRITING.md b/docs/WRITING.mdindex b9f725358..621d37d98 100644--- a/docs/WRITING.md+++ b/docs/WRITING.md@@ -64,6 +64,8 @@ uv run --locked --extra dev seiso policy最终状态检查共用 `scripts/copy-rules.json`。明确叙述实现变更、测试名称描述变更过程时拒绝通过;可能属于条件说明的词语只提示人工核对。合法条件说明不需要添加豁免标记。明确需要保留的事故原文仍用 `copy-lint-disable-line` 逐行说明例外。+Markdown 里的「兜底」「落盘」「闭环」「链路」意思含糊,检查拒绝通过,改写成具体机制,如后备来源、写入磁盘、下载流程;「链路本地」是网络地址类别,保留。`对齐`、`复盘` 是项目术语与技能触发词,`DOM/CSS/JS` 是证据三元组的固定写法,均保留。 <!-- copy-lint-disable-line -->+Python 检查读取 AST 字符串、f-string 静态片段及注释;HTML 读取正文、注释和可见属性。JS/TS 由 `frontend/scripts/copy-check.mjs` 使用 Oxc 解析注释、字符串、模板及 JSX,忽略变量名、静态属性键和模块路径。前端文案检查随正式入口的前端 lint 用例执行,CI 由 `web-bundle` 执行;纯 Python 文档检查不要求安装 Node。提交模板不是成稿;`docs/reference-snapshots/upstream/` 保存第三方原文,相对链接属于上游仓库。这两类在配置中排除。Peach 自己撰写的取证摘要、ADR、技能和依赖来源说明仍接受检查;构建目录、依赖安装目录不属于项目文档。diff --git a/scripts/check_copy_final_state.py b/scripts/check_copy_final_state.pyindex ed7e22750..66f5ebcd3 100644--- a/scripts/check_copy_final_state.py+++ b/scripts/check_copy_final_state.py@@ -56,6 +56,8 @@ def scan_lines(path: str, source: str, *, skip_code_fences: bool) -> list[Findincontinueif fence is None:found.extend(_scan_text(path, line_no, raw))+ # 只查 Markdown;源码注释与界面字串不在此列。+ found.extend(_scan_text(path, line_no, raw, group="doc_terms"))return found@@ -122,7 +124,7 @@ def scan_html(path: str, source: str) -> list[Finding]:def targets(root: Path) -> list[Path]:- picked = [root / name for name in ("AGENTS.md", "README.md", "README.zh-CN.md")]+ picked = [root / name for name in ("AGENTS.md", "CONTRIBUTING.md", "README.md", "README.zh-CN.md")]picked.extend(sorted((root / "docs").glob("*.md")))picked.extend(sorted((root / ".claude/skills").glob("*/SKILL.md")))picked.extend(sorted((root / "web").glob("*.html")))diff --git a/scripts/copy-rules.json b/scripts/copy-rules.jsonindex 0141ebb1d..aaa993662 100644--- a/scripts/copy-rules.json+++ b/scripts/copy-rules.json@@ -13,5 +13,8 @@],"test_names": [["_no_longer_|_previously_|_formerly_|_used_to_", "测试名称说明当前契约", "error"]+ ],+ "doc_terms": [+ ["兜底|落盘|闭环|链路(?!本地)", "改写成具体机制,如后备、写入磁盘、流程", "error"]]}diff --git a/tests/test_copy_final_state.py b/tests/test_copy_final_state.pyindex 1def142ef..094f54460 100644--- a/tests/test_copy_final_state.py+++ b/tests/test_copy_final_state.py@@ -70,6 +70,15 @@ class CopyFinalStateTests(unittest.TestCase):found = checker.scan_lines("sample.md", source, skip_code_fences=True)self.assertEqual([item.line for item in found], [5])+ def test_markdown_rejects_vague_jargon_but_keeps_link_local(self):+ source = "失败时兜底\n结果落盘\n```\n兜底\n```\n拒绝链路本地地址\n"+ found = checker.scan_lines("sample.md", source, skip_code_fences=True)+ self.assertEqual([(item.line, item.term, item.severity) for item in found],+ [(1, "兜底", "error"), (2, "落盘", "error")])++ def test_source_comments_are_outside_the_markdown_jargon_rule(self):+ self.assertEqual(checker.scan_python("sample.py", "# 失败时兜底\n"), [])+def test_every_rule_reports_file_line_and_term(self):found = checker.scan_lines("sample.md", "# 曾经有另一种做法\n",skip_code_fences=True)@@ -81,7 +90,7 @@ class CopyFinalStateTests(unittest.TestCase):def test_the_scan_covers_every_declared_surface(self):"""扫描面写死成 glob 就会漏掉新目录,所以直接核对它收到了哪些文件。"""picked = {path.relative_to(ROOT).as_posix() for path in checker.targets(ROOT)}- for required in ("AGENTS.md", "README.md", "docs/WRITING.md",+ for required in ("AGENTS.md", "CONTRIBUTING.md", "README.md", "docs/WRITING.md","web/index.html","src/peach/web_entity.py","tests/test_web_ui.py",