Peach: Local-first video metadata scraper and media manager.
refactor(tooling): 精简 README 维护与交付检查
longmeidao8786cd07083e
diff --git a/.claude/skills/peach-worktree/SKILL.md b/.claude/skills/peach-worktree/SKILL.mdindex 7490ca297..9c2910a9e 100644--- a/.claude/skills/peach-worktree/SKILL.md+++ b/.claude/skills/peach-worktree/SKILL.md@@ -5,8 +5,8 @@ description: Peach 代码任务开工,以及创建、提交、集成或回收# 工作树与集成交付-最后复核:2026-10-29-证据来源:工作树入口、交付预检与 PR 绑定回归、集成事故、用户确认的存量生效判据及 0.51.0 发版复盘。+最后复核:2026-11-06+证据来源:工作树入口、交付预检与 PR 绑定回归、集成事故、存量生效判据、0.51.0 发版复盘及用户取消 README 强制声明的要求。## 开工与职责@@ -21,7 +21,7 @@ description: Peach 代码任务开工,以及创建、提交、集成或回收1. 在当前工作树准备独立 venv,按 `docs/TESTING.md` 安装锁定依赖,不复制 venv 或修改正在服务的环境。2. 行为修改先列失败路径与影响域,通过正式入口定向验证;新增或改名测试核对域登记,不能以文件存在代替覆盖。3. 最后交付提交完成后先运行 `agent_worktree.py preflight`,再运行一次 `auto`;未知影响、实际依赖和共享设施用 `full`。预检不签发测试记录。环境、编码、源码定位、记录复用和补测契约统一见 `docs/TESTING.md`,不逐域循环重复公共用例。-4. `ready` 前纳入当前 `master` 并验证最终内容;主线前移后交 `auto` 复用有效记录,不默认重跑全量。提交、声明与记录齐全后取得 `ready` 的实际结果。+4. `ready` 前纳入当前 `master` 并验证最终内容;主线前移后交 `auto` 复用有效记录,不默认重跑全量。提交、署名与记录齐全后取得 `ready` 的实际结果。5. 协调者执行 `integrate --branch <分支>`;入口核对开放 PR 的提交与工作者 HEAD、目标分支一致。等成功退出并核对主线提交,再做适用重启和运行核验。锁忙交入口等待,不手工 merge 绕过,不把分支交接当成验收完成。主检出 master 的直接提交与手工 merge 由 hook 拒收。发布先完成 `docs/TESTING.md`「每次发版检查」的依赖升级批次,再通过 `scripts/release_tag.py` 定版、打标签与发布;更新清单不代表升级完成。发布时机采用 `release_due.py` 及集成入口的同一判据,不额外重复检查。@@ -41,7 +41,7 @@ description: Peach 代码任务开工,以及创建、提交、集成或回收由一个协调会话统一测试与集成;工作树或工作者数量不决定 PR 数,按[交付范围](../peach-issue-delivery/SKILL.md#issue-与-pr-范围)归并,同一目标先汇入一个交付分支再提 PR。先协调各任务停止本批测试、ready、integrate 与重试,核对最终提交,保留无关任务。在专用集成工作树按无冲突、有冲突、自己的顺序合入最终提交。源码冲突只在双方保留项已明确且能全部保留时解,否则中止本次冲突合并,交原任务更新分支。-`web/dist` 冲突保留集成侧,源码合齐后统一构建。最后提交声明整批 README 影响,跑一轮 `auto` 再 ready、integrate。+`web/dist` 冲突保留集成侧,源码合齐后统一构建,跑一轮 `auto` 再 ready、integrate。全站尺寸、字号、命名或控件语义变化须检查全部相关浏览器用例;小改按影响选测。时序超时先用 `agent_worktree.py processes` 排查本任务重叠运行,不在相同失败状态反复全量。## 暂存与提交@@ -51,7 +51,7 @@ description: Peach 代码任务开工,以及创建、提交、集成或回收- 主题为 `type(scope): 中文描述`,类型以 `scripts/commit_subject.py` 为准。- 本机提交者自己的交付提交带 `Co-Authored-By: 工具 (实际模型版本) <厂商 noreply>`,名单见 `scripts/co_author.py`;接力作者并列,人类共同作者保留姓名与邮箱。- 采纳社区补丁时保留原作者为提交作者,写 `Source-PR`、`Original-Commit`,不替贡献者补 AI 署名;只有智能体改写或补充了代码时,才加它自己的署名。-- 最后提交写唯一 `README-Impact`,需要时带 `README-Reviewed`,按 `docs/README_MAINTENANCE.md` 核对中英文。所有 trailer 连续放末尾同一块,块内无空行,块前空一行。+- 署名 trailer 连续放在提交消息末尾同一块,块内无空行,块前空一行。README 修改按 `docs/README_MAINTENANCE.md` 核对实际内容。## 回收与顶层归置diff --git a/AGENTS.md b/AGENTS.mdindex 2b4e55eac..e3e2d64ae 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -46,7 +46,7 @@## 验证与交付门槛- 测试只用当前隔离工作树的 Windows `& .\scripts\test.ps1` 或 macOS/Linux `./scripts/test.sh`。`auto` 按域选测;实际依赖、共享设施和未知影响面用 `full`;环境、登记与记录契约见 `docs/TESTING.md`。`ready` / `integrate` 拒收无有效记录的交付,禁止手工 merge 绕过入口。健康检查只用 `/healthz`。-- 不用 `git add .`、`git add -A`、目录或 glob;逐文件暂存并核对 `git diff --cached --name-status`。实现与对应测试原子提交,署名与 README 影响按 `peach-worktree`。+- 不用 `git add .`、`git add -A`、目录或 glob;逐文件暂存并核对 `git diff --cached --name-status`。实现与对应测试原子提交,署名按 `peach-worktree`。- 预览使用独立真实小样本,启动前通过 `scripts/check_ui_preview.py`;确认与普通、编辑链接按界面技能。HTTPS 验证使用项目 CA 严格校验,失败就报告原始错误与未取得的验收面。- 入口与技能的结构、行数、字节数、单行长度由 `scripts/check_context_budget.py` 强制;职责与清退按 `peach-context-rules`。工作树残留与公开文档中的私有信息由 `tests/test_repo_hygiene.py` 检查。- 文案、注释、docstring、测试名描述当前行为;检查与事故例外见 `docs/WRITING.md`。源码文本断言只减不增;行为与设计测试分工见 `docs/TESTING.md`。diff --git a/README.md b/README.mdindex 317359f8b..b81167ba9 100644--- a/README.md+++ b/README.md@@ -49,7 +49,6 @@ Movie demo data; see [asset credits and licenses](https://peach.video/en/credits- **Cloud download**: search by video code or submit a magnet link, then organize completed downloads into your library.- **Library management**: manage tags, duplicates, versions and parts; permanently delete videos by performer while keeping profiles and photos. Metadata and watch history are stored locally.- **Task center**: pause, resume or cancel local background tasks and view their CPU, GPU and download activity where available.-- **Guided tours**: learn the interface and settings as needed; tutorial progress is shared across devices connected to the same instance.## Download and usediff --git a/README.zh-CN.md b/README.zh-CN.mdindex 3152d5468..0bc51d6c9 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -49,7 +49,6 @@- **云下载**:按影片编号查找或提交磁力,下载完成后整理入库。- **馆藏管理**:管理标签、重复文件、多版本与分卷;按女优批量永久删除影片,保留人物档案和照片。资料和观看记录保存在本机。- **任务中心**:暂停、继续或取消本机后台任务,查看可取得的各任务 CPU、GPU 与下载活动。-- **新手教程**:按需了解界面和设置,连接同一实例的设备共用教程进度。## 下载与使用diff --git a/docs/README_MAINTENANCE.md b/docs/README_MAINTENANCE.mdindex 4b9ec3b6a..f5a1ab43d 100644--- a/docs/README_MAINTENANCE.md+++ b/docs/README_MAINTENANCE.md@@ -1,9 +1,11 @@# README 维护-默认入口 `README.md` 使用英文,简体中文版为 `README.zh-CN.md`;两种语言同批核对。+默认入口 `README.md` 使用英文,简体中文版为 `README.zh-CN.md`。README 展示项目定位、核心能力、安装入口与必要限制。具体功能、参数和交互更新进入变更日志或专题文档。-1. 按下表核对本次涉及的能力、安装方式与限制。-2. 同批核对中英文 README,修改需要调整的内容,保留使用入口和安全说明。+维护范围依据 2026-11-06 用户确认的取舍。只有现有核心能力概括、安装入口、平台支持或必要限制需要修正时,才修改 README,并核对对应的中英文说明。++1. 先判断本次改动是否影响 README 的核心介绍;需要修改时,再按下表核对事实。+2. 修改需要调整的中英文说明,保留使用入口和安全说明。3. 用 documd 提供当前稿的可视化预览,取得用户明确确认后才能推送 README;继续修改时确认对应的新稿。4. 按 [文档与界面文案](WRITING.md#检查与复核) 检查,再运行 [正式测试入口](TESTING.md#正式入口)。@@ -20,36 +22,9 @@ README 面向初次访问项目的人,依次讲它是什么、界面导览与| 当前行为与已部署范围 | 实现与测试、[运行与配置](OPERATIONS.md)、[公开路线图](https://github.com/orgs/peach-mitao/projects/7) || 来源、配置与数据边界 | [docs/SOURCING.md](SOURCING.md)、[docs/OPERATIONS.md](OPERATIONS.md)、[docs/CLOUDDRIVE.md](CLOUDDRIVE.md) |-README 迭代绑定 Codex 与 Claude 共用的工作树交付流程。每次提交前核对暂存差异,-涉及用户可见能力、安装、平台或构建要求时,同批更新中英文。只改变内部实现时保留 README,-在交付分支最后一个提交的 Git trailer 写明原因:+README 改动沿用项目工作树、PR 与验证流程。修改内容时核对中英文的项目定位、核心能力和安装事实,需要修正的部分随改动更新。README 的 Python 下限、语言入口、链接和文案由现有检查验证。-| 判断 | 提交消息末尾的独立字段 |-| --- | --- |-| 已更新两份 README | `README-Impact: updated; 同步了哪些用户说明` |-| 只需修改中文 README | `README-Impact: updated; 中文修改原因`,另加 `README-Reviewed: README.md; 英文无需修改的原因` |-| 只需修改英文 README | `README-Impact: updated; 英文修改原因`,另加 `README-Reviewed: README.zh-CN.md; 中文无需修改的原因` |-| 不影响 README | `README-Impact: none; 具体原因` |--声明与 `Co-Authored-By` 等其它 trailer 连续写在提交消息末尾的同一块里,彼此之间不留空行。-同一块里的署名形态见 `.claude/skills/peach-worktree/SKILL.md`「暂存与提交」。-`git interpret-trailers --parse` 只解析末尾那一块,被空行隔开的 `README-Impact` 属于正文段落,-`commit-msg` 会指出不在末尾同一块的字段,`ready` 也会拒绝未取得唯一声明的交付。--`scripts/check_readme_impact.py` 读取目标分支到交付 HEAD 的实际差异,并使用-`git interpret-trailers --parse` 读取最后提交的声明。涉及运行时代码、前端、迁移、资源、-依赖或安装说明时必须声明;纯测试和其他内部文档不触发。触发清单由脚本统一维护。-README 改动必须核对两种语言;`updated` 至少对应一份实际差异,`none` 不得伴随 README 改动。-仅一份需要调整时,用唯一 `README-Reviewed` 写明未改文件及原因,不能为了满足检查改动正确的译文。-提交后的暂存内容不能满足要求。原因的真实性仍由代码审阅负责,脚本不代替语义判断。--`agent_worktree.py preflight` 在耗时验证前核对这一门槛;`ready/integrate` 在接受测试记录前复用同一检查。检查覆盖本次分支交付,-允许在最后交付提交统一核对整批差异。仓库 `scripts/githooks/commit-msg` 在 `agent/*`-分支提交时检查署名,以及消息中已有 README 声明的格式与分段;中间提交可以不写 README 声明。-合并消息免除署名检查,amend 使用同一套字段判据;钩子只读消息。README 声明与整个分支差异-的一致性由交付门槛检查,未通过的分支不能经项目入口集成。-无需定时任务、账号专属 hook 或额外模型调用。Python 下限、文案和快照校验继续复用现有测试。-结构或品牌调整时重读已登记的参考快照,上游变化只作为参考,计划功能不得写成已实现。+结构或品牌调整时重读已登记的参考快照,上游变化作为参考,能力说明以实际实现为准。## 演示数据集diff --git a/docs/REUSE.md b/docs/REUSE.mdindex 9bde4188e..f0d663f58 100644--- a/docs/REUSE.md+++ b/docs/REUSE.md@@ -1,5 +1,11 @@# 复用清单+## 活动任务速度与分页++任务档位复用 `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 配额归一化。@@ -126,7 +132,7 @@ React 与应用层的 GET 入口共用 `frontend/src/core/library-scope.ts`:## 正式测试记录与中断恢复-交付预检复用已有的提交主题、共同署名与 README 影响检查,不新增规则解释器。合入前的 PR 身份复用 [GitHub CLI 的 `gh pr view`](https://cli.github.com/manual/gh_pr_view),使用工作树仓库上下文和原生 JSON 字段;Peach 只校验开放状态、精确提交及目标分支,不引入 GitHub SDK 或另一套凭据存储。临时 Git 工作树回归覆盖未取得 PR、旧提交、其他目标、远端查询期间内容变化及成功合并回执。+交付预检复用已有的提交主题与共同署名检查,不新增规则解释器。合入前的 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`;版本与许可沿用锁定依赖及第三方许可清单,不新增运行时依赖。Peach 保留输入身份、逐文件覆盖、完成报告、批次来源和 `ready`/`integrate` 验收规则;串行、并行、浏览器与 Vitest 使用同一个恢复模型。@@ -691,7 +697,6 @@ SFW 开关键可在偏好设置的「内容显示」里改。主键按 `Keyboard- 访问密码复用 Python 3.14 的 [hashlib.scrypt](https://docs.python.org/3.14/library/hashlib.html) 与 OpenSSL,浏览器会话复用 [ItsDangerous](https://itsdangerous.palletsprojects.com/en/stable/)(Pallets、BSD-3-Clause、纯 Python、wheel 16 KB、无传递依赖),本机原子配置写入用 tempfile/os.replace 与 filelock;认证入口的访问口令、三种拒绝响应与本机配置守卫照旧复用。Starlette SessionMiddleware 统一时长、随响应续期,满足不了每台设备自选截止时间,所以直接用同源签名库,Peach 管可选密码、截止时间与撤销,不带账户体系与迁移。- Cloudflare Quick Tunnel 用官方 `cloudflared`(Apache-2.0),不自写隧道协议。源码环境只管 PATH/环境变量里的进程;Windows 独立包旁路固定 `2026.9.0`,资产、地址与 SHA-256 在 `scripts/cloudflared-windows.json`,`fetch_cloudflared.ps1` 与构建脚本双重校验。就绪判据是官方 `--pidfile`(首次连上边缘才写),未连上不宣称可用。源码 HTTPS origin 用项目 CA,独立包用回环 HTTP,写请求来源校验带当前进程持有的随机 URL。-- README 交付检查用系统 Git 的 `diff --no-renames -z` 与 [`interpret-trailers --parse`](https://git-scm.com/docs/git-interpret-trailers),挂在 `agent_worktree.py ready/integrate`;Peach 只定义影响文件与双语声明 policy。原生 hook 不随 clone 安装、判断不了文案语义,所以挂在共有的交付入口上([README 维护](README_MAINTENANCE.md))。- 配置访问判定用 ASGI 连接的 `client` / `server` 地址与标准库 `ipaddress`:本机连接匹配回环地址或服务端 IP,Host 只校验托盘配置的域名或绑定地址、不证明调用方在本机。配置保存用修订号校验、原子替换与 `SetupGate` 重载标记,托盘子服务以 `PEACH_TRAY_MANAGED` 声明重载能力。安装检测用 `winreg`、`shutil.which` 与安装目录,媒体工具用 `FFmpegResolver`,脱盘不判为未安装。下载入口 2026-09-06 核验:[CloudDrive](https://www.clouddrive2.com/download.html)、[WinFsp](https://winfsp.dev/rel/)、[macFUSE](https://macfuse.github.io/)、[FFmpeg](https://ffmpeg.org/download.html)、[OpenSSL](https://openssl-library.org/source/)。- 发行身份用各来源解析器与 Seesaa 的原始 DTO,数字前缀等价是 Peach 的领域 policy。查询回退不能承担身份确认([`390JAC-040` 实例](SOURCING.md#依赖与工具实测)),响应按原始查询检查,MGStage 官方详情路径可佐证展示编号别名;外部适配器只取值,首条搜索命中不作 ledger 身份断言。- Seesaa 作品表用 HTTPX、Beautiful Soup 4.15.0(MIT)与现有 `HostLimiter`、番号规范化、字段候选和快照协议。Javinizer-Go `d9724f239d7e127afcb747fa8ce4358685912f50`(MIT)与 MetaTube `6a5e6128c725187aeaf921d48ed7d9cd9f30671b`(Apache-2.0)都没有 Seesaa 适配器(2026-09-06 核对),所以 `peach.sources.seesaa` 承担 EUC-JP、列映射、精确行身份与未知名单保护,消费者是 `scrape_codes --profile seesaa`([站点细节](SOURCING.md#seesaa-wiki-作品证据))。@@ -715,7 +720,7 @@ SFW 开关键可在偏好设置的「内容显示」里改。主键按 `Keyboard定向调试复用标准库 unittest 的按名字加载与现有浏览器夹具,记录复用沿用文件清单、影响域和 FileLock,不新增测试框架或缓存服务。局部成功记录保留未受影响域的原验证时间,失败域不能从历史基线恢复;浏览器失败即停。回归覆盖过期、环境差异、未知与共享文件、失败后再次验证、路径越界及不签调试证明,详见 [测试](TESTING.md#定向调试与局部记录)。-提交消息复用 Git 的 [`interpret-trailers --parse`](https://git-scm.com/docs/git-interpret-trailers),署名与 README 声明判据由 `co_author.py`、`check_readme_impact.py` 共用;`check_commit_message.py` 接到仓库 `commit-msg` 钩子。Git 自身处理注释与多行 trailer,Peach 只检查字段形态和分段。Windows Git 2.55.0.windows.3 的临时仓库回归覆盖拒绝提交、保留暂存、人类与智能体共同署名、amend 和合并消息;不新增解析依赖。具体触发范围见 [README 维护](README_MAINTENANCE.md)。+提交消息复用 Git 的 [`interpret-trailers --parse`](https://git-scm.com/docs/git-interpret-trailers),`co_author.py` 校验署名,`check_commit_message.py` 接到仓库 `commit-msg` 钩子。Git 自身处理注释与多行 trailer,Peach 检查署名字段形态和分段。临时仓库回归覆盖拒绝无署名提交、保留暂存、人类与智能体共同署名、amend 和合并消息;复用现有依赖。### 播放、采集、发布与打包diff --git a/docs/TESTING.md b/docs/TESTING.mdindex aaeb8930f..aa846af6e 100644--- a/docs/TESTING.md+++ b/docs/TESTING.md@@ -194,7 +194,7 @@ macOS 按影响域验证:全量失败后,入口从逐条结果里取出失败的 Python 用例、e2e 文件与 vitest 文件,不超过 6 个文件时用定向入口逐个单独重跑一次。单独重跑通过的,记录照样签为通过,名字写进记录的 `flaky` 字段并打印出来;单独重跑仍失败、失败面更大、或浏览器容器整个没起来的,按真实失败处理。同一用例反复出现在 `flaky` 里,说明它的等待写法或时限需要修。-本机全量验证与代码集成共用 `full-suite.lock`,从取得代码和环境快照一直持有到记录写入完成。仅修改两份 README 或 `docs/` 下 Markdown 的集成只取得 `integration.lock`,仍核对工作树、验证记录、README 声明与冲突,不等待无关全量测试。+本机全量验证与代码集成共用 `full-suite.lock`,从取得代码和环境快照一直持有到记录写入完成。仅修改两份 README 或 `docs/` 下 Markdown 的集成只取得 `integration.lock`,仍核对工作树、验证记录与冲突,不等待无关全量测试。锁忙时按到达先后排队:等待者在锁旁的 `full-suite.lock.queue/` 放一张以纳秒时刻开头的票,前面没有活票时才去抢锁,拿到即撤票;提示里打印持有者与前面排队的个数。票主进程退出后,它的票由后来者清掉。最长等 30 分钟;超时撤票退出,不执行测试或合并。集成事务本身仍由@@ -217,7 +217,7 @@ ffmpeg 起不来是事实,但它不该挡住一次只改文档的 `checks`。### 交付预检与 PR 绑定-最后交付提交完成后,先在当前隔离工作树根目录运行元数据预检,再开始耗时验证或推送。预检核对工作树干净、目标分支已纳入,以及提交主题、署名和 README 声明。+最后交付提交完成后,先在当前隔离工作树根目录运行元数据预检,再开始耗时验证或推送。预检核对工作树干净、目标分支已纳入,以及提交主题和署名。Windows(PowerShell 7)运行预检:@@ -313,7 +313,7 @@ README 的 Python 下限和双语入口由 checks 的安装契约检查,普通首次设置目录 `frontend/src/react/pages/setup/`、素材 `resources/setup/` 和独立页面产物 `web/dist/peach-pages.js`、`web/dist/peach-pages.css` 的补测保留主应用浏览器结果,仍检查首次设置浏览器流程、全部相关 Python 契约、组件与打包。首次设置浏览器用例集中在 `frontend/e2e/setup.test.ts`;新增独立页面浏览器容器时须同步扩充这份对应关系。主应用产物、共享样式或公共组件同时改变时,主应用浏览器结果照常失效。-测试记录格式升级时,主检出的入口可能无法识别新格式。先在工作树通过 `ready`,再由主检出调用该工作树中已验收的 `scripts/agent_worktree.py`,用 `--repo` 指定主检出并执行 `integrate`。该方式仍检查测试记录、README 声明、目标分支和集成锁;不要手工改写记录或跳过门槛。集成后主检出使用同一版本的入口。+测试记录格式升级时,主检出的入口可能无法识别新格式。先在工作树通过 `ready`,再由主检出调用该工作树中已验收的 `scripts/agent_worktree.py`,用 `--repo` 指定主检出并执行 `integrate`。该方式仍检查测试记录、目标分支和集成锁;不要手工改写记录或跳过门槛。集成后主检出使用同一版本的入口。PR 与普通主线的浏览器 CI 根据界面、Web API、认证与浏览器用例选择;普通后端单测不单独触发浏览器任务。工作流按职责选测,发布工作流触发打包验证,看板等管理工作流只触发工具检查。无可用基线、未知影响与手动完整验证覆盖全部 CI 任务,发布演练和制品验收按其独立门槛执行。diff --git a/docs/adr/0128-test-selection-contracts-and-verified-mainline.md b/docs/adr/0128-test-selection-contracts-and-verified-mainline.mdindex 962f921d5..e87a0b332 100644--- a/docs/adr/0128-test-selection-contracts-and-verified-mainline.md+++ b/docs/adr/0128-test-selection-contracts-and-verified-mainline.md@@ -20,4 +20,4 @@ README 修改固定选择整个 tooling 域,双语文件改名还需修改调普通文档提交仍检查文档契约、仓库规范和链接,不运行无关媒体与浏览器回归。共享模块可能选择更多业务域,这是补齐真实消费者的必要成本。直接导入分析不替代动态调用的显式登记;后续新增动态消费者须在对应回归中核对选测。-测试框架自身本批仍须全量验证;README 的可视化确认和提交声明继续适用。已公开提交保留历史,不为补充格式或来源关联改写远端。+测试框架自身本批仍须全量验证;README 内容维护按现行维护文档执行。已公开提交保留历史,不为补充格式或来源关联改写远端。diff --git a/scripts/adopt_dependency_bump.py b/scripts/adopt_dependency_bump.pyindex 714745ad1..178e20d87 100644--- a/scripts/adopt_dependency_bump.py+++ b/scripts/adopt_dependency_bump.py@@ -234,7 +234,7 @@ def working_changes(*, root: Path = ROOT) -> list[str]:def commit_message(key: str, versions: list[str], pr: str | None,signature: str) -> str:- """接管提交的说明。README-Impact 与 Co-Authored-By 必须同一个 trailer 块、中间不空行。+ """生成依赖接管提交的来源、重算步骤与署名。署名由 `--co-author` 传进来,脚本不替谁署名:跑它的可能是任一个智能体,写死一个工具名就是往提交历史里记错人。形态由 `co_author.FORM` 判,这里提前判一次,免得@@ -255,7 +255,6 @@ def commit_message(key: str, versions: list[str], pr: str | None,return (f"chore(deps): 接管 {recipe['label']} 的升级\n\n{why}\n\n"+ ("升级:" + "、".join(versions) + "\n\n" if versions else "")+ (f"Refs #{pr}\n\n" if pr else "")- + "README-Impact: none; 依赖版本与派生产物,README 不涉及。\n"+ f"Co-Authored-By: {signature}\n")diff --git a/scripts/agent_worktree.py b/scripts/agent_worktree.pyindex e38100f7e..69430cc2c 100644--- a/scripts/agent_worktree.py+++ b/scripts/agent_worktree.py@@ -16,7 +16,7 @@ from pathlib import Pathif not __package__:sys.path.insert(0, str(Path(__file__).resolve().parents[1]))__package__ = "scripts"-from . import (changelog, check_public_text, check_readme_impact, co_author, commit_subject,+from . import (changelog, check_public_text, co_author, commit_subject,test_evidence, test_runner, version_bump)from .release_tag import MASTER_WRITER@@ -148,8 +148,7 @@ def require_metadata(worker: Path, target_branch: str) -> str:raise WorkspaceError("验证工作树必须干净")if _git(worker, "merge-base", "--is-ancestor", target_branch, "HEAD", check=False).returncode:raise WorkspaceError("目标分支已前进;请在工作树 rebase 后运行 auto 验证")- problems = (check_readme_impact.check(worker, target_branch)- + co_author.check(worker, target_branch)+ problems = (co_author.check(worker, target_branch)+ commit_subject.check(worker, target_branch))if problems:raise WorkspaceError("; ".join(problems))diff --git a/scripts/check_commit_message.py b/scripts/check_commit_message.pyindex 3a755764d..23a59ea83 100644--- a/scripts/check_commit_message.py+++ b/scripts/check_commit_message.py@@ -21,16 +21,10 @@ def author_mail(repo: Path) -> str:def check(repo: Path, message: str, *, own: bool = True) -> list[str]:parsed = check_readme_impact.trailers(repo, message)problems = co_author.problems("待提交", parsed.get("co-authored-by", []), own=own)- for name in ("Co-Authored-By", "README-Impact", "README-Reviewed"):- mentioned = sum(line.partition(":")[0].casefold() == name.casefold()- for line in message.splitlines())- values = parsed.get(name.casefold(), [])- if mentioned != len(values):- problems.append(f"{name} 须连续放在提交消息末尾的同一块,中间不要留空行。")- if name == "README-Impact" and (mentioned or values):- problems.extend(check_readme_impact.declaration(values)[1])- if name == "README-Reviewed" and (mentioned or values):- problems.extend(check_readme_impact.reviewed_declaration(values))+ mentioned = sum(line.partition(":")[0].casefold() == "co-authored-by"+ for line in message.splitlines())+ if mentioned != len(parsed.get("co-authored-by", [])):+ problems.append("Co-Authored-By 须连续放在提交消息末尾的同一块,中间不要留空行。")return problemsdiff --git a/scripts/check_readme_impact.py b/scripts/check_readme_impact.pyindex 03e67e1b5..cdbbea25f 100644--- a/scripts/check_readme_impact.py+++ b/scripts/check_readme_impact.py@@ -1,4 +1,4 @@-"""核对一次分支交付的 README 影响声明。"""+"""README 安装契约与提交检查共用的 Git 读取。"""from __future__ import annotations@@ -8,13 +8,6 @@ import tomllibfrom pathlib import PathREADMES = {"README.md", "README.zh-CN.md"}-PREFIXES = ("src/peach/", "web/", "frontend/", "migrations/", "resources/")-FILES = {- "pyproject.toml", "package.json", "package-lock.json",- ".github/workflows/release.yml", "docs/FRONTEND.md",- "docs/TESTING_DESKTOP.md", "docs/OPERATIONS.md", "docs/SOURCING.md",- "scripts/build_windows.ps1", "scripts/build_app_entry.py",-}def installation_contracts(repo: Path) -> list[str]:@@ -64,48 +57,3 @@ def trailers(repo: Path, message: str) -> dict[str, list[str]]:name, _, value = line.partition(":")result.setdefault(name.casefold(), []).append(value.strip())return result---def declaration(values: list[str]) -> tuple[str, list[str]]:- """检查声明形态;与 README 文件差异的关系由交付检查核对。"""- if len(values) != 1:- return "", ["交付提交须有唯一 README-Impact: updated; 说明 或 README-Impact: none; 原因"]- status, separator, reason = values[0].partition(";")- if status not in {"updated", "none"} or not separator or not reason.strip():- return "", ["README-Impact 需使用 updated/none,并在英文分号后写具体原因"]- return status, []---def reviewed_declaration(values: list[str], counterpart: str | None = None) -> list[str]:- """另一语言的核对声明必须唯一,指明文件及无需修改的原因。"""- if len(values) != 1:- return ["README-Reviewed 须有唯一的未改 README 文件名和原因"]- name, separator, reason = values[0].partition(";")- allowed = {counterpart} if counterpart else READMES- if name.strip() not in allowed or not separator or not reason.strip():- return ["README-Reviewed 须填写未改 README 文件名,并在英文分号后写明无需修改的原因"]- return []---def check(repo: Path, base: str, head: str = "HEAD") -> list[str]:- """以实际交付差异和最后提交的 Git trailer 为依据。"""- paths = set(git(repo, "diff", "--name-only", "--no-renames", "-z",- base, head).rstrip("\0").split("\0")) - {""}- touched = paths & READMES- relevant = any(path in FILES or path.startswith(PREFIXES) for path in paths)- if not touched and not relevant:- return []- message = git(repo, "show", "-s", "--format=%B", head)- status, problems = declaration(trailers(repo, message).get("readme-impact", []))- if problems:- return problems- if touched and touched != READMES:- reviewed = trailers(repo, message).get("readme-reviewed", [])- other = next(iter(READMES - touched))- if problems := reviewed_declaration(reviewed, other):- return problems- if status == "updated" and not touched:- return ["README-Impact 声明 updated,但交付差异未包含 README"]- if status == "none" and touched:- return ["README-Impact 声明 none,但交付差异包含 README"]- return []diff --git a/tests/test_agent_worktree.py b/tests/test_agent_worktree.pyindex 17546d264..230055fde 100644--- a/tests/test_agent_worktree.py+++ b/tests/test_agent_worktree.py@@ -350,14 +350,13 @@ class PullRequestIntegrationTests(_WorktreeCase):class PreflightTests(_WorktreeCase):- def worker(self, *, declaration=True):+ def worker(self):item = create(self.repo, "Codex", "preflight", self.root / "worktrees")worker = Path(item["path"])path = worker / "src/peach/module.py"path.write_text("VALUE = 1\n", encoding="utf-8")_git(worker, "add", "src/peach/module.py")- trailers = ("README-Impact: none; 内部规则,使用方式不变\n" if declaration else "") + AUTHOR- _git(worker, "commit", "-m", "fix(tooling): 示例规则", "-m", trailers)+ _git(worker, "commit", "-m", "fix(tooling): 示例规则", "-m", AUTHOR)return workerdef test_the_cli_checks_metadata_without_reading_or_signing_test_proof(self):@@ -375,11 +374,14 @@ class PreflightTests(_WorktreeCase):agent_worktree.require_pull_request.assert_not_called()self.assertFalse((self.repo / "build/agent-verification").exists())- def test_a_missing_final_declaration_is_rejected_before_test_proof(self):- worker = self.worker(declaration=False)+ def test_single_readme_change_passes_preflight_with_authorship_only(self):+ worker = self.worker()+ (worker / 'README.md').write_text('# Example\n', encoding='utf-8')+ _git(worker, 'add', 'README.md')+ _git(worker, 'commit', '-m', 'docs: 更新说明', '-m', AUTHOR)with mock.patch.object(agent_worktree.test_evidence, "key") as key:- with self.assertRaisesRegex(WorkspaceError, "README"):- agent_worktree.preflight(worker)+ result = agent_worktree.preflight(worker)+ self.assertEqual(result['metadata'], 'passed')key.assert_not_called()def test_dirty_content_and_a_newer_target_require_preparation(self):@@ -474,23 +476,13 @@ class CommitMessageGuardTests(_WorktreeCase):self.assertEqual(_git(self.worker, "diff", "--cached", "--name-only").stdout.strip(),"worker.txt")- def test_separated_or_malformed_readme_declarations_refuse_the_commit(self):+ def test_optional_readme_trailers_are_accepted_as_commit_text(self):for declaration in ("README-Impact: none; 内部测试\n\n", "README-Impact: none\n",- "README-Impact: none; 内部测试\nREADME-Impact: updated; 文档\n"):+ "README-Impact: none; 内部测试\nREADME-Impact: updated; 文档\n",+ "README-Reviewed: README.zh-CN.md; 已核对\n\n",+ "README-Reviewed: README.zh-CN.md;\n", "README-Reviewed: unknown.md; 已核对\n"):with self.subTest(declaration=declaration):- result = self.attempt("test: check\n\n" + declaration + AUTHOR)- self.assertNotEqual(result.returncode, 0)- self.assertIn("README-Impact", result.stderr)-- def test_counterpart_review_trailer_requires_a_file_reason_and_contiguous_block(self):- for declaration in ("README-Reviewed: README.zh-CN.md; 已核对\n\n",- "README-Reviewed: README.zh-CN.md;\n",- "README-Reviewed: unknown.md; 已核对\n"):- result = self.attempt("test: 核对声明\n\n" + declaration + AUTHOR)- self.assertNotEqual(result.returncode, 0)- self.assertIn("README-Reviewed", result.stderr)- result = self.attempt("test: 核对声明\n\nREADME-Reviewed: README.zh-CN.md; 中文正确\n" + AUTHOR)- self.assertEqual(result.returncode, 0, result.stderr)+ self.assertEqual(check_commit_message.check(self.worker, "test: check\n\n" + declaration + AUTHOR), [])def test_valid_trailers_and_amend_preserve_the_message(self):message = ("test: 中文提交\n\nREADME-Impact: updated; 两种语言\n" + AUTHOR@@ -508,7 +500,7 @@ class CommitMessageGuardTests(_WorktreeCase):self.assertEqual(result.returncode, 0, result.stderr)self.assertEqual(_git(self.worker, "show", "-s", "--format=%B").stdout.strip(), message.strip())- def test_intermediate_commit_can_leave_readme_scope_for_delivery_check(self):+ def test_commit_accepts_authorship_without_readme_trailers(self):result = self.attempt("test: intermediate\n\n" + AUTHOR)self.assertEqual(result.returncode, 0, result.stderr)@@ -519,7 +511,7 @@ class CommitMessageGuardTests(_WorktreeCase):self.assertIn("Co-Authored-By", result.stderr)def test_git_comment_lines_do_not_count_as_declarations(self):- result = self.attempt("test: comments\n\n" + AUTHOR + "\n\n# README-Impact: example\n")+ result = self.attempt("test: comments\n\n" + AUTHOR + "\n\n# Co-Authored-By: example\n")self.assertEqual(result.returncode, 0, result.stderr)def test_merge_messages_are_exempt_from_authorship_trailers(self):@@ -870,99 +862,7 @@ class IntegrationVersionTests(_WorktreeCase):self.assertEqual((report["release"]["entries"], report["release"]["due"]), (0, False))-from scripts.check_readme_impact import check, git---class ReadmeImpactTests(unittest.TestCase):- def setUp(self):- self.temp = tempfile.TemporaryDirectory()- self.addCleanup(self.temp.cleanup)- self.repo = Path(self.temp.name).resolve()- git(self.repo, "init", "-b", "master")- git(self.repo, "config", "user.name", "Test")- git(self.repo, "config", "user.email", "[email protected]")- self.save("README.md", "English")- self.save("README.zh-CN.md", "中文")- git(self.repo, "commit", "-m", "base")- self.base = git(self.repo, "rev-parse", "HEAD").strip()- git(self.repo, "checkout", "-b", "worker")-- def save(self, name, content):- path = self.repo / name- path.parent.mkdir(parents=True, exist_ok=True)- path.write_text(content, encoding="utf-8")- git(self.repo, "add", "--", name)-- def commit(self, trailer=""):- git(self.repo, "commit", "-m", "测试", "-m", trailer)- return check(self.repo, self.base)-- def test_runtime_change_requires_review(self):- self.save("src/peach/example.py", "x = 1")- self.assertTrue(self.commit())-- def test_internal_change_accepts_explained_none(self):- self.save("src/peach/example.py", "x = 1")- self.assertEqual(self.commit("README-Impact: none; 内部缓存实现,使用方式不变"), [])-- def test_single_language_update_requires_counterpart_review(self):- self.save("README.md", "新内容")- self.assertTrue(self.commit("README-Impact: updated; 功能说明"))-- def test_single_language_typo_accepts_explicit_counterpart_review(self):- self.save("README.md", "修正错字")- self.assertEqual(self.commit("README-Impact: updated; 中文错字\n"- "README-Reviewed: README.zh-CN.md; 中文表述正确,无需修改"), [])-- def test_counterpart_review_requires_correct_file_and_reason(self):- self.save("README.md", "修正错字")- for trailer in ("README-Reviewed: README.md; 已核对", "README-Reviewed: README.zh-CN.md;",- "README-Reviewed: README.zh-CN.md; 已核对\nREADME-Reviewed: README.zh-CN.md; 重复"):- self.assertTrue(self.commit("README-Impact: updated; 中文错字\n" + trailer))- git(self.repo, "reset", "--soft", "HEAD^")-- def test_bilingual_update_accepts_review(self):- self.save("README.md", "新内容")- self.save("README.zh-CN.md", "New content")- self.assertEqual(self.commit("README-Impact: updated; 功能说明"), [])-- def test_none_cannot_describe_document_changes(self):- self.save("README.md", "新内容")- self.save("README.zh-CN.md", "New content")- self.assertTrue(self.commit("README-Impact: none; 内部改动"))-- def test_test_only_change_needs_no_declaration(self):- self.save("tests/example.py", "x = 1")- self.assertEqual(self.commit(), [])-- def test_uncommitted_readme_does_not_satisfy_review(self):- self.save("frontend/package.json", "{}")- self.commit("README-Impact: updated; 工具要求")- self.save("README.md", "新内容")- self.save("README.zh-CN.md", "New content")- self.assertTrue(check(self.repo, self.base))-- def test_missing_reason_and_duplicate_trailers_are_rejected(self):- self.save("web/app.js", "x = 1")- for trailer in ("README-Impact: none;",- "README-Impact: none; 原因\nREADME-Impact: updated; 原因"):- git(self.repo, "commit", "--allow-empty", "-m", "测试", "-m", trailer)- self.assertTrue(check(self.repo, self.base))-- def test_deletion_and_rename_trigger_review(self):- self.save("src/peach/example.py", "x = 1")- self.commit("README-Impact: none; 内部实现")- self.base = git(self.repo, "rev-parse", "HEAD").strip()- git(self.repo, "mv", "src/peach/example.py", "example.txt")- self.assertTrue(self.commit())-- def test_gate_rejects_before_accepting_verification(self):- self.save("web/app.js", "x = 1")- self.commit()- with mock.patch.object(agent_worktree.test_evidence, "key") as key:- with self.assertRaisesRegex(agent_worktree.WorkspaceError, "README"):- agent_worktree.require_verified(self.repo, "master", {"web/app.js"})- key.assert_not_called()+from scripts.check_readme_impact import gitfrom scripts import check_commit_message, co_author@@ -1100,7 +1000,7 @@ class CoAuthorTests(unittest.TestCase):self.assertEqual(co_author.check(self.repo, "master"), [])def test_the_signature_gate_runs_before_the_test_evidence_is_read(self):- """署名和 README 影响面在同一处拒收,都不必等到去读测试记录。"""+ """署名在读取测试记录前检查。"""(self.repo / "tests").mkdir()(self.repo / "tests" / "example.py").write_text("x = 1\n", encoding="utf-8")git(self.repo, "add", "--", "tests/example.py")diff --git a/tests/test_dependency_policy.py b/tests/test_dependency_policy.pyindex f9d4511a4..07f816071 100644--- a/tests/test_dependency_policy.py+++ b/tests/test_dependency_policy.py@@ -442,7 +442,7 @@ class DependencyPolicyTests(unittest.TestCase):log = git(repo, "log", "--format=%B", "-2")for number in (1, 2):self.assertIn(f"Dependabot PR #{number} 没有派生产物", log)- self.assertIn("README-Impact: none; ", log)+ self.assertIn(f"Co-Authored-By: {signature}", log)self.assertIn("git commit -F build/adopt-pr-3.txt", stopped["next"])(repo / ".github/workflows/test.yml").write_bytes(workflow(2, 2))@@ -475,22 +475,16 @@ class DependencyPolicyTests(unittest.TestCase):self.assertTrue(adopt.adopted(133, branch, root=repo))self.assertEqual((repo / ".github/workflows/test.yml").read_bytes(), b"a: 2\n")- def test_the_takeover_commit_message_passes_the_readme_impact_gate(self):- """`README-Impact` 与 `Co-Authored-By` 必须同一个 trailer 块、中间不空行。-- 隔一个空行 `git interpret-trailers` 就只认后一个,`ready` 会报「交付提交须有唯一- README-Impact」——这条我在 0.29.0 那次亲手踩过。- """+ def test_takeover_message_includes_source_rebuild_steps_and_the_supplied_author(self):signature = "Claude Code (Opus 5) <[email protected]>"message = adopt.commit_message("web", ["lucide-static 1.38.0 → 1.40.0"],"4", signature)- self.assertIn("\nREADME-Impact: none; ", message)self.assertIn("\nRefs #4\n", message)- self.assertRegex(message, r"README-Impact: none; [^\n]+\nCo-Authored-By: ")self.assertIn("PR #4", message)self.assertIn("npm run vendor:web", message)self.assertIn("lucide-static 1.38.0 → 1.40.0", message)self.assertIn(f"Co-Authored-By: {signature}", message)+ self.assertNotIn("README-Impact:", message)# 署名由调用方给:跑接管的可能是任一个智能体,写死一个工具名就是记错人。with self.assertRaisesRegex(ValueError, "--co-author"):adopt.commit_message("web", [], "4", "Claude Code")diff --git a/tests/test_test_evidence.py b/tests/test_test_evidence.pyindex 9f2656388..78cf077db 100644--- a/tests/test_test_evidence.py+++ b/tests/test_test_evidence.py@@ -974,7 +974,6 @@ class VerificationTests(unittest.TestCase):(worker / "README.zh-CN.md").write_text("Test content\n", encoding="utf-8")evidence.git(worker, "add", "README.md", "README.zh-CN.md")evidence.git(worker, "commit", "-m", "docs: test", "-m",- "README-Impact: updated; 测试文档\n""Co-Authored-By: Codex (GPT-5.5) <[email protected]>")return worker, item["branch"]