Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

chore(context): 精简规则并统一上下文预算

longmeidaocd08b833acc5
diff --git a/.claude/skills/peach-batch-jobs/SKILL.md b/.claude/skills/peach-batch-jobs/SKILL.md
index 52e8bb949..d83ff993b 100644
--- a/.claude/skills/peach-batch-jobs/SKILL.md
+++ b/.claude/skills/peach-batch-jobs/SKILL.md
@@ -1,77 +1,31 @@
---
name: peach-batch-jobs
-description: 在用户说抽帧、九宫格、probe、sheets、creator_boards、刮削、批量、长任务、限流、续跑、流量预算或磁盘余量时使用。
+description: 运行长时采集、探测、抽帧等批处理,或排查限流、续跑、磁盘与流量时使用。
---
-# 长跑批处理与流量边界
+# 批处理预检与续跑
-最后复核:2026-10-18
-证据来源:`scripts/probe.py`、`scripts/sheets.py`、`scripts/traffic_watch.py`、`src/peach/jobs.py`、相关单元测试与 ADR-0015。
+最后复核:2026-10-26
+证据来源:`scripts/probe.py`、`scripts/sheets.py`、流量守卫、`peach.jobs`、单机复制开关与批次事故。
-## 失败值
+## 起跑
-测量失败不能写成下游可误认的正常值。`probe.py` 曾把「ffprobe 无时长」写成 `duration=0`,
-数据因此同时退出 `duration IS NULL` 队列又进不了 `duration>2` 队列。失败一律写 `-1`,
-并提供 `--redo zero|failed|all`。
+1. 核对任务范围、真实数据授权、当前数据根与写入资格。开启复制时必须是 writer;关闭复制的独立实例按可写状态判断,不能因 `ledger_sync=disabled` 拒绝。
+2. 按 `peach-ledger-write` 备份真实账本;核对迁移、目标来源可达性、已有同类任务和实时队列。代码验证按实际影响域,不因启动批次机械重跑全量。
+3. 用当前来源、实际出口与采样方法估算流量和磁盘成本,批次范围、阈值与结果写仓库外运行记录,不把某晚额度或来源安排写成永久默认。
+4. 按 `traffic_watch.py` 当前参数与连接计量决定是否包含直连;计费来源走直连时必须计入。不要从来源名称猜代理路径。
-两组状态数字看似矛盾时,先查是否存在两边查询都遗漏的状态,不要直接判定其中一组错误。
-待办数量统一报告「可执行 / 被阻塞 / 合计」。
+## 运行边界
-## 磁盘闸门
+- 运行期使用 `DiskGuard` 复查系统盘实际余量,触线停止领新任务、保存结果并保留非零退出码;不只检查产物盘或起跑余量。第三方块缓存也会占系统盘。
+- `HostLimiter` 按主机限流,等待可处理其他来源;短测不能证明长跑稳定。来源反机器人与速率边界按 `docs/SOURCING.md`,不在封禁期轮换出口连打。
+- 单项网络或媒体失败独立记录,允许其余任务推进;账本、结果保存等公共环节失败须中断。失败不能伪装成空结果或成功,状态数字不一致时先查遗漏状态。
+- 定期持久化检查点,续跑只跳过已成功项目;限流或网络造成的暂时未取得不能冻结成永久无结果。
+- 时长失败值、重探选择器、抽帧颜色重试等细节以对应脚本、`peach.media_probe` 和回归为准,不推广成所有任务通用的返回值契约。
+- 接入抽帧前复用路径转换与大小写解析;色彩元数据异常仅重试失败帧,不覆盖全部输入。
+- 不在真实库写入批次中切换写入端、复制账本或启动冲突批次。重启按任务恢复能力和项目授权边界执行。
+- 导入运维脚本无文件、网络或数据库副作用。只停止自己拥有且命令行匹配的进程树,禁止全机终止 FFmpeg。
-起跑前一次 `require_free_space` 不是运行期闸门。`DiskGuard` 默认每 20 秒复查系统盘实际余量;
-`probe.py`、`sheets.py`、`creator_boards.py` 触线后停止领新任务、保留已完成结果并返回退出码 3,
-不得伪报正常完成。
+## 验收
-CloudDrive 的稀疏读取缓存可能占用系统盘,与产物所在盘不同。CloudDrive 退出可能重写配置,长跑前后都要复核缓存上限和淘汰策略,不能把
-历史配置值当成当前事实。
-
-## 限流
-
-- 限流按主机管理。`HostLimiter` 为每个主机记录下次可发时刻,等待期间可处理其他来源。
-- 限流参数按批次规模验证,不能用短测成功推断长跑稳定;测量记录留在仓库外。
-- 被 Cloudflare 拦的站一律放弃,不绕过机器人检测。按出口 IP 计的速率配额是另一类:那道判的是
- 「这个出口发得太快」而不是「你是不是机器人」,换节点可用,来源下限和撞 403 收工照守,不在
- 封禁期里换着节点连打。通用来源边界见 `docs/SOURCING.md`。
-
-## 续跑
-
-长任务必须能续跑。一次未捕获的 TLS EOF 曾让 62 分钟结果归零:网络异常降级为空值而不是抛出,
-结果定期写入文件,`--resume` 只把成功判定当作已完成:`no_name` 这类多半是限流假阴性,冻结进
-复核文件就再无重试机会。
-
-## 流量与进程
-
-- 200 GB 守卫默认只统计代理流量,覆盖 PikPak,看不到直连 115;需要覆盖直连时显式
- `--count-direct`,且不要在同一计量窗口混跑不同来源。
-- 流量估算使用当前来源、实际出口和采样方法;测量结果保存在私有批次记录中。
-- `-probesize`/`-analyzeduration` 无法减少 CloudDrive 固定块预取;未知时长时创作者板可回退到
- 60 秒 seek,不需要先做全量 PikPak probe。
-- Windows 查询已消失 PID 可能抛 `OSError(winerror=87)` 而不是 `ProcessLookupError`,
- `PidFileLock` 必须识别为陈旧锁并安全清理。
-- 长任务只停止自己拥有且命令行匹配的 Python/FFmpeg 进程树,禁止全机终止 FFmpeg。
-- 导入运维脚本不得触发文件、网络或数据库副作用。
-
-## 抽帧路径
-
-`scripts/sheets.py`、`scripts/probe.py` 的 worker 直接用账本路径跑 FFmpeg,不走 MediaEngine。
-修大小写敏感挂载层的失败必须先把 `peach.media.resolve_case_insensitive` 接入这两个 worker。
-`sheets.py` 遇 `prim:reserved` 非法色彩元数据会带 bt709 声明重试,只在失败帧重试,不得无条件
-给所有输入加色彩覆盖。
-
-## 真实库批次的预检与验收
-
-- 真实批次只在 ledger writer 上跑(`/healthz` 回 `ledger_sync=writer`、`db=available`);reader 只做
- 代码验证和副本抽样。起跑前逐项核对,缺一项就不接管写入端:工作区干净且已纳入 master、全量测试
- 通过、`peach migrate status` 正常、目标网盘盘符能列目录、没有同类 `probe`/`sheets`/
- `traffic_watch` 进程、系统盘余量高于 `--min-free`,并按 `peach-ledger-write` 用 SQLite backup API
- 备份账本。队列数字开跑前用 `scripts/job_status.py` 现算,不抄进文档:写死的基线只在生成那一刻成立。
-- 先在独立窗口起流量守卫(`scripts/traffic_watch.py --limit 200 --warn 120`,PikPak 要加
- `--count-direct`),再按封面 → `probe` → `sheets` 的顺序跑;`probe` 非零退出就不进九宫格。
- 同一晚只跑一个来源,期间不做 Ledger 同步、接管、托盘重启或别的真实库批处理。
-- 全量缩略图先按当前队列与来源成本估算。触发流量或磁盘闸门是安全中止不算失败,
- 下次用原命令续跑,不为完成率调高预算。
-- 次日先 `scripts/job_status.py` 打印实时队列,读两类任务的最新日志,再跑 `PRAGMA integrity_check`
- 与 `PRAGMA foreign_key_check`;任何一项不过就不同步共享副本。报告固定给:完成/仍失败/待处理、
- 守卫累计下载、实际出口 chain、系统盘余量、备份路径、退出码、是否触发闸门;少一项就判不了下一晚
- 该续跑还是先查问题。
+取得实际退出状态,读取实时队列与日志;真实账本批次核对完整性和外键。报告完成、仍失败、待处理、是否安全中止,以及适用的流量、出口、磁盘与备份证据。触发闸门不伪报正常完成,也不为完成率提高已约定阈值。
diff --git a/.claude/skills/peach-context-rules/SKILL.md b/.claude/skills/peach-context-rules/SKILL.md
index e3b2bb421..4d248cd62 100644
--- a/.claude/skills/peach-context-rules/SKILL.md
+++ b/.claude/skills/peach-context-rules/SKILL.md
@@ -1,116 +1,43 @@
---
name: peach-context-rules
-description: 新增、修改或清退智能体规则、入口文件与技能时使用;普通产品文档编辑无需加载。
+description: 新增、修改或清退智能体规则、技能、入口与预算时使用。
---
-# 上下文写作与清退
+# 上下文归属与清退
-最后复核:2026-10-18
-证据来源:ADR-0015、`scripts/check_context_budget.py`、`tests/test_context_budget.py`、用户于
-2026-08-17 提供的 `My AGENTS.md & SKILLS.md Breakdown` 逐字稿。
+最后复核:2026-10-26
+证据来源:ADR-0015、预算检查器、规则与实现对照审查、用户确认的精简范围。
-判据与理由的完整版在 `docs/adr/0015-agent-context-layering.md`,本文件只给操作步骤。
+## 判定归属
-## 新增一条规则
+按 [ADR-0015](../../../docs/adr/0015-agent-context-layering.md) 判断:
-按顺序回答,第一个命中的就是归属:
+1. 各类任务都可能触发,遗漏会损坏真实数据、生产或结论:项目入口留短边界与可执行入口。
+2. 某类任务的执行顺序、判断与停止条件:对应项目技能。
+3. 通用用法、字段、组件规范、算法与设计理由:文档、实现或 ADR,技能按任务路由到章节。
+4. 跨项目偏好与边界:用户级入口;成套流程进入用户级技能,机器事实进入按需参考。
+5. 单次任务、部署事实、个人待办与复核记录:仓库外数据根。
-1. 不遵守会直接损坏真实数据、破坏生产或产出假结论,且任何任务都可能触发?
- → `AGENTS.md`,一行祈使句 + 指向可执行入口。
-2. 只有某类任务才需要,且是「步骤」?→ 新建或补充 `.claude/skills/<name>/SKILL.md`。
-3. 是通用契约、复用依据或架构取舍?→ 对应产品文档、`docs/REUSE.md` 或 ADR。
- 本机运行事实、馆藏盘点、个人待办与交接只存 `<数据根>/state/project-context/` 等仓库外目录。
-4. 与仓库无关、跨项目成立?→ 当前智能体全局入口(Codex 为 `~/.codex/AGENTS.md`,
- Claude 为 `~/.claude/CLAUDE.md`);成套流程进入对应用户级技能,事实进入按需参考文档。
-5. 只对本次对话有效?→ 不写入任何文件。
+规则必须对应可指认的项目失败或用户决策,上游材料只作证据。保留约束防住的后果;案例只选能改变判断的坏例与好例。
-补充要求:
+## 编写与检查
-- 规则必须来自本项目的真实失败或真实决策。禁止照搬外部模板或别人的 `AGENTS.md`:
- 别人的条文对应的是别人的失败模式,抄来的规则没有可指认的来源,第一次复核就该删。
-- 能配一对**坏例 / 好例**就配上,比抽象形容词有效得多。仓库里已有的范例:`bba0b77` 的
- 测试与实现拆分提交、`duration=0` 与失败值 `-1`、`ABW` 与 `ABW 番号` 的搜索推荐词。
-- 同一事实只能有一处真相。技能引用文档路径,不复制数字。
-- 一条规则如果能变成脚本拒绝、测试失败或 hook 行为,就先把门槛做出来,散文只留一行指路。
-- `AGENTS.md` 不是 `README.md`:README 讲这个项目是什么、怎么跑;`AGENTS.md` 讲改动它之前
- 必须知道什么。同一段内容不要两边都写。
+- 同一事实维护一处,不复制实现常量、完整覆盖清单和安装手册。只读当前模式需要的参考,不把整套参考变成必读。
+- description 只写触发与边界;与项目索引一致,不用泛化关键词吸引无关任务。
+- 技能不新增审批,不删除真实数据、凭据、外发、预览确认与生产入口的既有边界。
+- 可稳定检测的失败由脚本、测试或 hook 强制;语义判断留在指令中,不声称技能触发本身是门槛。
+- frontmatter 使用目录同名的 `name` 与 `description`,正文写复核日期和证据来源;新增技能同步项目索引。
+- 预算唯一真相在 `scripts/check_context_budget.py`。现有预算不因写超而抬高;变更须说明职责无法下沉的理由并遵守天花板。
+- 中文与最终状态写法、检查覆盖、词表与事故例外按 [WRITING.md](../../../docs/WRITING.md)。
-## 写 description
+## 复核与清退
-description 会常驻上下文,**技能没被触发时也在消耗预算**。所以它的任务是「让模型知道什么时候
-把这份技能拉进来」,不是解释技能内容。
+相关实现变化、同类失败重复、预算失败或 minor 发布前:
-- 简短说明具体任务与适用边界;关键词须对应真实使用场景,不因相邻主题触发。
-- description 不塞步骤,多流程技能用最小路由指向按需参考。
-- 坏例:`Peach 并行代码任务的 Git worktree 隔离、暂存边界、测试入口与集成流程。`
-- 好例:`创建、提交、集成或回收 Peach 工作树时使用。`
-- 一个技能同时管两件常被单独需要的事(例如「写 PR」和「盯 PR」)就拆成两个,各写各的触发词。
+1. 读取当前实现、测试与准确错误;有证据缺口才查历史,不按模型名称批量删除约束。
+2. 删除失效条文,把重复内容合并到所属位置,同步修复引用和触发范围。
+3. 核对数据、候选、生产、预览与进程保护边界,避免用绝对化短句改变授权语义。
+4. 更新实际复核过的日期,运行预算检查并通过项目测试入口验证相关域。
+5. 用文档小改、行为修复和真实数据操作等代表性请求检查路由、停止条件与交付范围。静态通过不证明模型效率改善。
-## 新建技能
-
-```text
-.claude/skills/<name>/SKILL.md
-```
-
-- frontmatter 只有 `name`(与目录同名)和 `description`(≤ 200 字符)。
-- 正文前两行固定为 `最后复核:YYYY-MM-DD` 和 `证据来源:`。
-- 正文预算以 `scripts/check_context_budget.py` 为准。超出时按职责下沉通用事实,私有信息移出仓库。
-- 在 `AGENTS.md` 的技能索引表加一行触发条件与路径,Codex 靠这张表按需读取。
-
-行数、字节数、单行长度与 description 的预算由同一检查器维护,本技能不复写数值。
-
-## 预算只能降不能升
-
-调低随时可以。上调必须在 `scripts/check_context_budget.py` 的 `BUDGET_CHANGES` 追加
-「值 / 日期 / 理由」,理由要说明这些内容为什么无法下沉到 `docs/` 或技能;写「初始值」或留空
-判错。`MAX_EVER` 是天花板,不因为写超了而调整。
-
-## 触发是概率性的,别拿技能当门槛
-
-Claude 只把每个技能的 name+description 预加载进系统提示,读不读正文由模型按 description 判断;
-Codex 完全不自动加载 `.claude/skills`,只能靠 `AGENTS.md` 索引表主动读。所以「必须每次成立」的
-规则不能只写成技能,必须同时有脚本、测试或 hook 强制。技能写「怎么做」,门槛写「必须做」。
-
-## 文案只写最终状态
-
-界面字串、注释、docstring、测试名与文档只描述现在成立的行为和约束,不叙述被否掉的做法,
-也不做改动前后对比,因为版本演进由 Git 记录,读者要的是当前这一份怎么用。
-
-- 门槛是 `scripts/check_copy_final_state.py`,由 `tests/test_copy_final_state.py` 在 tooling
- 与 web 两个域执行;词表、覆盖面与临时例外文件清单都在脚本顶部,改判据就改那里。
-- 覆盖面:`web/` 的字串与注释、`frontend/`,`src`/`scripts`/`tests` 的注释、docstring、
- 字符串字面量与测试函数名,以及 `README.md`、`docs/*.md`(不含 `docs/adr/`)、`AGENTS.md`
- 和各技能正文。ADR 正文按定义要记录决策过程,不在覆盖面内。
-- 约束的理由必须留下。把它写成反事实句「这样做的话,会……」,说清失败模式而不点名某一版实现,
- 既保住教训又不需要放行标记。
-- 真实事故记录才放行:那一行结尾加 `copy-lint-disable-line`,Markdown 写成 HTML 注释、
- Python 用 `#`、JS 用 `//`;这个标记与用户级 `lint_copy_rules.py` 共用,一处标记两边都认。
- 放行前先试着改写成「现在的规则 + 它防住的后果」,多数记录不需要标记。
-
-## 失败模式审计
-
-规则的来源应该是统计,不是印象。定期(每次 minor 发布前,或连续踩同类坑时)让智能体审计
-本机的会话历史与 Git 历史,按模型和 harness 分类统计高频失败:误杀进程、跑错测试入口、
-只改一个影响面、把候选当真相、把提醒当门槛。产出一份可核对的清单,再决定:
-
-- 高频且可自动检测 → 做成门槛(脚本 / 测试 / hook)。
-- 高频但只能靠判断 → 写进 `AGENTS.md` 硬门槛或对应技能,并配坏例/好例。
-- 低频且已被门槛覆盖 → 直接清退。
-
-任务耗时或产出明显偏离预期时,核对工具记录与实际失败,判断是否有无关读取、重复验证或授权歧义。
-精简后用文档小改、行为修复、真实数据操作等代表性场景复核触发、完成标准和授权边界;
-静态检查只证明结构与门槛成立,不证明模型效率改善。
-
-## 清退
-
-触发时机:相关实现被删除或重写、规则已被可执行门槛覆盖、预算检查失败、每次 minor 版本发布、
-失败模式审计给出新结论。
-
-步骤:
-
-1. 运行 `python scripts/check_context_budget.py`:退出码 0 通过,1 有超预算或结构错误,3 只有 `最后复核` 超过 180 天的条目。
-
-2. 逐条问:这条规则的事故或证据还能指认吗?对应实现还在吗?已经有门槛了吗?
-3. 该删就整段删除,不留「已废弃」注释,Git 就是归档。被 ADR 取代的段落只留一行指向 ADR。
-4. 复核但保留的技能更新 `最后复核` 日期。
-5. 结构与预算由 `tests/test_context_budget.py` 在 `& .\scripts\test.ps1` 中强制执行。
+预算检查退出码:0 为通过,1 为结构或预算错误,3 为仅复核超期。耗时偏离预期时核对无关读取、重复验证与授权歧义,不新建定时任务规避本轮交付。
diff --git a/.claude/skills/peach-cross-platform/SKILL.md b/.claude/skills/peach-cross-platform/SKILL.md
index 48fa951d2..795d756c2 100644
--- a/.claude/skills/peach-cross-platform/SKILL.md
+++ b/.claude/skills/peach-cross-platform/SKILL.md
@@ -1,117 +1,31 @@
---
name: peach-cross-platform
-description: 在 macOS 上开工、改动路径解析或挂载判定、遇到 git status 与 git diff 结果不一致,或要把改动交回 Windows 那台时使用。
+description: macOS、跨平台路径与挂载、双机任务交接或 Git 状态异常时使用。
---
-# 跨 Windows / macOS 双机开发
+# 跨平台路径与部署核对
-最后复核:2026-10-24
-证据来源:`src/peach/platform.py`、ADR-0017、2026-08-19 的 macOS 迁移实测、
-2026-08-21 的 Windows 现状核对,以及 2026-09-14 用 junction 复现的临时目录别名。
+最后复核:2026-10-26
+证据来源:`peach.platform`、`peach.scan`、`peach.ffmpeg`、ADR-0017、独立包与 Git 状态复核。
-## 何时使用
+## 路径与部署
-- 当前工作目录在 macOS 上(`~/Desktop/<用户目录>/peach/peach-app`),或改动要交回 Windows 那台继续。
-- 改动涉及 `asset.path` 解析、`allowed_media_roots`、挂载可达性或磁盘闸门;`git status` 显示大量文件被修改,但 `git diff` 是空的。
+- ledger 路径保持 Windows 形态,不改写成 POSIX,也不从 macOS 写 `asset.path`;映射由 `asset.location` 和媒体配置声明,不从盘符猜来源。操作细节按 [路径配置](../../../docs/OPERATIONS.md#在-macos-上对应-windows-路径mediamounts)。
+- 读取复用 `peach.platform`:授权根比较考虑文件系统身份,挂载在线以目录实际可读判断,磁盘闸门用 `system_volume()`。脱盘是来源级状态,媒体缺失、来源离线与权限错误分别处理。
+- 先确认源码部署、独立包或 Docker。媒体工具由 `FFmpegResolver` 按显式配置、随包工具、数据目录和 PATH 查找;独立 macOS 包不要求 Homebrew,源码开发外壳的 LaunchAgent 不能推广到所有安装方式。
+- 安装、端口、工具与启动方式以 `docs/OPERATIONS.md` 和 `docs/DOCKER.md` 当前章节为准,现场核对,不复制另一部署的目录。
-## 路径口径
+## 代码与账本交接
-账本里的 `asset.path` **一律是 Windows 形态**,例如 `R:\Media\...`。
-盘符与目录由媒体来源配置声明,来源与盘符没有固定对应关系。
+- 每台机器独立持有代码、venv、数据与工作树;任务分支提交、推送后在对端 fetch 并创建本机工作树,不复制 `.git` 指针或运行目录。
+- 先用 `scripts/sync_status.sh` 核对代码与账本状态;代码落后时保护当前改动再更新,不能把 pull/rebase 作为无条件开工命令。
+- 双机复制按 [ADR-0017](../../../docs/adr/0017-dual-host-local-runtime-and-sync-boundaries.md) 和运行文档:唯一写入端、显式复制与接管、冲突由用户选边,不做 SQLite 三方合并。
+- 复制使用 SQLite backup API,活跃 WAL 数据库不直接复制文件;SMB 传输副本不能当运行账本,macOS 只以 immutable 方式读取已关闭快照。同步点不可达不等于本地媒体脱盘。
+- mDNS 名取本机配置且两端不同。按 `peach.mdns` 的平台发布路径处理,用终端的 `scripts/check_mdns.py` 和 `/healthz` 验证;服务自己探测不能证明局域网可达。权限排查按当前主机运维参考。
-不要为了 macOS 把账本改写成 POSIX 路径。翻译只发生在读取期,收敛在
-`src/peach/platform.py` 一处;写回账本的索引脚本仍只在 Windows 上跑,路径口径
-因此保持单一。**禁止从 macOS 写 `asset.path`**。
+## 测试与 Git
-来源映射按 `asset.location` 而不是盘符。声明根在设置文件的 `[media.locations]`,本机落点在 `[media.mounts]`;不要从其他部署复制挂载路径。
-
-用 `PEACH_MEDIA_MOUNTS=local=/mnt/res,115=/mnt/115` 覆盖;数据目录用 `PEACH_DATA_ROOT`。
-CloudDrive 在 Windows 是盘符、在 macOS 是 macFUSE 挂载点,这层不是可选优化。
-
-运行目录不跟着媒体盘符走。代码、数据、venv 和 worktree 各机独立保存,媒体挂载点由配置声明。
-
-## 三条只在 Windows 成立的假设
-
-- **授权根比较不能只看字面**。账本写 `R:\Media`,macOS 侧授权根是
- `<mounts.local>`;pathlib 区分大小写而 exFAT/NTFS 不区分,字面比较会把
- 全部本地资产判成越权。`within_root` 在字面不匹配时改用 inode 比较,交给文件系统
- 判定。
-- **挂载点「在不在」的判据是能否列出第一个条目**,不是 `is_dir()`。CloudDrive 掉线后
- 挂载点目录仍然存在,读一个条目才会报 `Device not configured`。见 `root_online`。
-- **磁盘闸门看系统盘**:Windows 从系统目录查询所在卷、macOS 使用 `/`,用 `system_volume()`。CloudDrive 的
- 下载块缓存在两个平台都落在系统盘;写死 `C:/` 会让 macOS 侧直接抛 `FileNotFoundError`。
-
-另外 `PidFileLock._running` 要吞掉 `OverflowError`:Windows 写下的 PID 可能超出 POSIX
-的 `pid_t`,`os.kill` 会崩掉整轮任务,而超界的 PID 一定不是本机活进程。
-
-## 脱盘模式
-
-脱盘是**来源级**的,不是全局开关。外置盘拔掉只影响 `local`,115/PikPak 的可达性单独判断;
-CloudDrive 掉线不影响仍可读取的本地来源。
-
-判据只有 `GET /api/sources` 一份。媒体层把整盘不可达从 `MediaUnavailable` 里分出
-`MediaOffline`,HTTP 回 503 加 `X-Peach-Offline: 1`,和「单个文件缺失」的 404 分开。
-前端据此置灰脱盘来源的筛选(数量仍然显示:脱的是盘不是账本),详情页换成脱盘面板
-而不是挂一个必然失败的播放器。
-
-## 运行环境
-
-macOS 的 FFmpeg 走 PATH(`brew install ffmpeg`);Windows 的 FFmpeg bundle 留在 Windows
-本机 `peach-data/tools`。菜单栏走 LaunchAgent,服务使用非特权端口 8900。
-
-测试入口:Windows `scripts/test.ps1`,macOS/Linux `scripts/test.sh`。两者契约相同。
-**两边都必须绿**;只在一台上通过的改动不算完成。Windows 托盘专属的 DPI 声明和单实例
-锁在非 Windows 上按 `skipUnless` 跳过,不要改成在 macOS 上伪造通过。
-
-用例里的临时根一律先 `.resolve()` 再交给被测代码:被测那边多半自己也 `resolve()`,而 CI runner
-的临时目录是别名(Windows 的短名与 junction、macOS 的 `/var` 软链),本机两边相等、runner 上
-不等,包含关系与路径断言于是本机全绿、CI 全红。本机复现它:拿 `mklink /J` 做一个 junction,
-把 `TEMP` / `TMP` 指过去再跑那几条用例。
-
-## 账本复制
-
-目标是两台机器各持本地工作副本,Windows 内置盘上的专用 SMB 目录提供共享传输副本。
-**不是多主实时同步**,因为 SQLite 没有安全的自动三方合并。见 ADR-0017、`src/peach/sync.py`
-与 README「数据属于自己」。
-
-- 服务启动只观察世代和写入端,不自动拉取或推送,也没有定时同步;marker 的 `device` 是唯一写入端、另一台只读,复制与「接管 Ledger 写入」只能由托盘显式执行,两边都动过就转只读报冲突、由人选一边。
-- 同步点不可达时本地仍可运行;媒体盘是否插入与账本同步无关。
-- 复制走 SQLite backup API,**不要复制 `.db` 文件**:WAL 里已提交未 checkpoint 的
- 事务会丢,还可能和目标残留的 `-wal` 拼成损坏的库。
-- Windows 本地工作副本与内置盘共享副本已分离;线上 `/healthz` 用 `writer` / `reader` /
- `conflict` 报告角色。macOS 从 SMB 拉取时,共享 DB 只能作为 immutable 已关闭快照读取。
-- 冲突不能靠合并解决,只能选一边:复制其一覆盖另一份,或删掉一侧 `.sync.json`
- 重新播种。别写「已同步」这种含糊结论。
-
-## 代码同步
-
-代码在 `origin` 指向的那个仓库,两台机器手动 push/pull,**不自动推送**。
-开工前先 `sh scripts/sync_status.sh`:落后远端就先 `git pull --rebase`,别在旧代码上接着
-写;账本走另一套同步(`peach.sync`),同一个脚本会一并报告。
-
-worktree 目录不跨机器复制。需要交接的任务分支先 commit/push,另一台 fetch 后重新创建本机
-worktree;`.venv`、`peach-data`、构建产物和 worktree 的 `.git` 指针都不进 GitHub。
-
-## macOS 的 mDNS
-
-从终端起正常、改由 launchd 起就没人应答:「本地网络」隐私门按进程判,launchd 作业是另一个
-主体且没有弹窗可点,自己发的多播被**静默**丢弃(设置里给 Python 放行没用,不是这个主体)。
-macOS 因此用 `dns-sd -P` 请系统 mDNSResponder 代发,Windows 继续用 zeroconf。
-
-**别让服务进程自证可达**:它发不出多播,探自己必然失败,会把好的判成不可达。验证用
-`scripts/check_mdns.py`(从终端跑)。排查手法:同一条命令分别从 shell 和 launchd 起各查一次,
-差异只在启动者时就是这个门。
-
-主机名取本机 `server.mdns_name`,用 `/healthz` 与 `check_mdns.py` 核对广播名称及可达性;两台机器不得同名。
-
-## Git 陷阱
-- **换行**由 `.gitattributes` 的 `* text=auto eol=lf` 固定,不要依赖各自的
- `core.autocrlf`。2026-08 之前 Windows 侧把 105 个已跟踪文件整体改写成 CRLF,
- `git status` 长期显示 117 个文件被修改、16213 行增删,而真正有实质改动的只有 1 个,
- 未提交的工作被假 diff 完全埋掉。
-- **从 exFAT 复制过来的文件权限是 `rwx------`**(exFAT 没有 POSIX 权限位,macOS 挂载时
- 统一合成)。这会让 git 的 stat 缓存长期对不上:`git status` 显示上百个文件被修改,
- `git diff` 却是空的,`git hash-object` 和 HEAD 逐字节相同。
- `git update-index --refresh` **只会报 `needs update`,修不好**;用 `git add` 重写
- stat 缓存才行。
-- 判断真实差异一律看 `git diff HEAD --name-only`,**不要看 `git status`**。
+- 测试使用项目正式入口,涉及跨平台行为须取得 Windows 与 macOS 的适用证据;缺少一端就明确未验证,不伪造平台跳过结果。
+- 临时根先 `.resolve()`,覆盖短路径、junction 与 `/var` 等别名;PID 存活探测复用 `peach.jobs.process_alive`,不在调用方重复实现 Windows 或 POSIX 判断。
+- 换行由 `.gitattributes` 决定。状态异常时联合核对 `git status`、工作区与暂存 diff、内容哈希和未跟踪文件;`git diff HEAD` 不能代替未跟踪文件检查。
+- exFAT 权限或 stat 缓存异常时,先证明内容与 HEAD 一致,再逐文件刷新索引;仍遵守任务归属与暂存边界,不以批量 add 修复状态。
diff --git a/.claude/skills/peach-issue-delivery/SKILL.md b/.claude/skills/peach-issue-delivery/SKILL.md
index 1dd02363a..c45af443f 100644
--- a/.claude/skills/peach-issue-delivery/SKILL.md
+++ b/.claude/skills/peach-issue-delivery/SKILL.md
@@ -5,7 +5,7 @@ description: 处理 Peach 的 GitHub issue、关联修复 PR、合并交付或
# Issue 交付与验证
-最后复核:2026-10-19
+最后复核:2026-10-26
证据来源:用户确认的 issue 沟通与验收约定、[issue #95](https://github.com/peach-mitao/peach/issues/95)、[PR #96](https://github.com/peach-mitao/peach/pull/96)、[项目看板状态判据](../../../scripts/project_board.py)。
## 沟通与标记
diff --git a/.claude/skills/peach-jav-cover-workflow/SKILL.md b/.claude/skills/peach-jav-cover-workflow/SKILL.md
index dd788c475..df7e98716 100644
--- a/.claude/skills/peach-jav-cover-workflow/SKILL.md
+++ b/.claude/skills/peach-jav-cover-workflow/SKILL.md
@@ -1,120 +1,37 @@
---
name: peach-jav-cover-workflow
-description: 在用户说 JAV 封面、高清封面、缺封面、封面刮削、重探、来源比较或继续抓取时使用。
+description: 获取、重探或比较 JAV 封面来源,以及维护人脸和正封取景产物时使用。
---
-最后复核:2026-10-18
-证据来源:`scripts/fetch_jav_covers.py`、`scripts/audit_cover_artwork.py`、`tests/test_jav_covers.py`、`tests/test_jav_poster_crop.py` 与 ADR-0107。
+# JAV 封面获取与验收
-# JAV 封面获取流程
+最后复核:2026-10-26
+证据来源:封面获取与审计脚本、取景实现及测试、ADR-0107。
-目标是取得可证明属于当前番号的最大官方封套。封面是可重建产物,不写 ledger;
-`cover-fetch-log.csv` 是来源与尺寸证据,必须保留。
+## 起跑
-## 起跑前
+目标是取得可证明属于当前番号的最大合格封面,不写 ledger。保留 `cover-fetch-log.csv` 的来源与尺寸证据。先核对运行方式与已有同类进程,避免重复批次。
-1. 读 [运行与配置](../../../docs/OPERATIONS.md) 与 `docs/REUSE.md` 的 JAV 封面条目。
-2. 检查是否已有 `fetch_jav_covers.py` 进程;不得重复起跑。
-3. 运行只读盘点,记录番号、已解码、缺失、损坏和宽度分布:
+1. 用 `scripts/fetch_jav_covers.py --audit` 只读盘点缺失、损坏、解码与尺寸分布。
+2. 先复用成功的元数据快照和上次日志的精确 URL,再查询缺少的官方候选;既有成功快照不重复请求。
+3. DMM URL 变体由当前脚本生成;有 Prestige 厂牌证据才使用对应 MGS、Prestige 查询。按实际尺寸比较,不设置主机名固定优先级。
+4. 反机器人拦截不绕过;DUGA 批量搜索需要应用 ID。Amazon 日本在真实 POC、身份无歧义并登记来源后才成为候选,放大图或水印不证明原始高清。
- ```powershell
- & .\.venv\Scripts\python.exe .\scripts\fetch_jav_covers.py --audit
- ```
+## 获取与替换
-## 候选来源
+- 通过脚本的解码、身份、最小尺寸与图像类型检查后,按像素面积选择;同尺寸优先商品图。只在合格且更大时原子替换,失败保留原图。
+- Range 读取先量尺寸,胜出后下载完整文件;JavDB 仅作核验证据,不安装、显示或作为缺图兜底。
+- 单条网络异常记录失败并继续,确认无候选与瞬时失败分别保存;每条完成后持久化日志,磁盘与流量按 `peach-batch-jobs`。
+- `--retry-misses` 重探缺失;`--upgrade-existing` 与 `--upgrade-max-width` 限定已有封面的升级范围,参数按当前脚本核对,批次额度不写成固定默认。
-所有候选都量尺寸,不设「某主机永远优先」的固定链:
+## 取景产物
-1. 先离线复用 `sources/metadata/javinizer-go/<番号>/*.json` 的 `cover_url` 与
- `content_id`,不要为已有成功快照重复请求元数据站。
-2. 从 DMM URL 生成并实测 modern `awsimgsrc.dmm.com/dig/...`、legacy
- `awsimgsrc.dmm.co.jp/pics_dig/...` 和原始 URL;覆盖 `digital/video`、
- `digital/amateur`、`mono/movie`。
-3. 有 Prestige 厂牌证据时,再直连 MGS `EnlargeImage` 与 Prestige
- `api/search` → `api/product` → `packageImage`。
-4. 把上轮成功日志的精确 URL 加回候选,保住已发现的 DUGA 等图片。
-5. AVBase 被 Cloudflare 拦截时放弃,不绕过。DUGA 批量搜索没有代理店应用 ID 时不调用。
-6. Amazon 日本只有完成真实 POC、匹配无歧义并登记来源后才进候选;4K/8K 水印或放大图不算原始高清封面。
+取景算法、适用图像、边车契约与回归样例见 [封面取景](../../../docs/COVER_ARTWORK.md),只在取景或边车任务时读取。源码中的版本与阈值是唯一真相,不在技能复制算法常量。
-坏例:按主机名直接覆盖 1000×674 的 DUGA 图,换成 800×539 的 DMM 图。
-好例:Range 读取图片头,校验可解码和宽度门槛,按像素面积选最大者。
+- 新封面补算 `scripts/detect_cover_faces.py` 与 `scripts/poster_crop_boxes.py` 的相应产物,原图保持完整;手工取景保留。
+- 默认处理缺失、过期或尺寸不符的记录,只有明确全算时使用 `--redo`;写入与 `--apply` 先按脚本当前边界核对。
+- 算法改变同步版本与消费者,先重算产物再切换适用服务;不能把取景坐标、安装封面与真实 ledger 写入混为一项。
-## 下载与替换门槛
+## 验收
-- 宽度低于 700、无法解码、缩略图、剧照、关联作品图都拒绝。
-- Range 最多先取 64 KiB 量尺寸,胜出后才下载完整图片。
-- 正式封面按实际像素面积择优,同尺寸优先商品图;JavDB 图片只作核验,不安装或显示兜底。
-- 单条网络异常写失败并换连接池,任务继续;确认无候选与瞬时失败分开记录。
-- `DiskGuard` 运行期守住系统盘;每条完成后重写可续跑日志。
-
-## 取景 sidecar
-
-新封面写入后补算人脸,否则页面只能用写死的锚点:
-
-```powershell
-& .\.venv\Scripts\python.exe .\scripts\detect_cover_faces.py
-```
-
-- 算法版本与尺寸匹配的记录默认跳过,过期记录自动重算;`--redo` 全量重算,未检出时页面居中。
-- sidecar 的 `cx` 和 `cy` 都要留着。用哪个轴由容器比例决定:`object-fit:cover`
- 一次只裁一个轴,16:9 官方剧照在大图版式里裁的是横向,纵向锚点在那里不生效。
-- 版式判据(1.2 / 1.65 两个分界)的真相在 `peach.jav_poster_crop`,`frontend/src/card-art/framing.ts` 的 `coverAnchor`
- 另有一份,改一处必须改两处,否则脚本按封套丢掉左半边的脸、页面却按剧照用那张脸取景。
-
-大图卡片要的是另一样东西:书脊折痕在哪,同目录写 `<番号>.poster.json`:
-
-```powershell
-& .\.venv\Scripts\python.exe .\scripts\poster_crop_boxes.py
-& .\.venv\Scripts\python.exe .\scripts\poster_crop_boxes.py --apply
-```
-
-- 判据在 `peach.jav_poster_crop`:Sobel 列梯度找书脊折痕,HEYZO/FC2/六位日期/韩国 MIB
- 不裁;16:9 只认满高拼接缝(覆盖 ≥75% 行)夹出的居中正封(PASN 等),原图不动。
- DVD 比例的居中正封还须双侧接缝满高,且两侧纹理均低于正封四分之一;无书脊的 4:3、√2:1 画布保留整幅。
-- **折痕按「切出来的正封形状对不对」认,不按它落在全宽的百分之几**。正封宽高比是印刷面的物理常数
- (DVD 135×190mm = 0.711);折痕在全宽里的位置随背面留白与书脊厚度飘。
- 只在 `PANEL_ASPECT_MIN`~`PANEL_ASPECT_MAX` 窗口里
- 找峭壁,窗外再强的边是画面内容,按它切会削掉一截大标题:KBI-036 的背面分栏线与正封内一道边恰好关于中线对称。
-- **窗里够强的边不止一条时按形状挑,不按谁更强**(`FOLD_RIVAL_RATIO`,到窗内最强边七成的
- 都算候选,相邻列归并成一条边)。厚书脊两条边都在窗里,左边那条挨着封底留白常更强,按它切
- 整条书脊留在框里。ABP-968 的厚书脊是对应回归样例。
-- **峰是斜坡最陡的那一列,不是斜坡尽头**。书脊最后一两列还压在峰的右边,按峰切正封左缘留一条
- 竖线。选定后往右走到梯度落回窗内中位数(`FOLD_SETTLE_LIMIT`,最多源图宽 1%),基线每张各算。
-- **切点不满高、右边窗内还有满高缝时正封从缝的下一列起**(`_seam_beyond`,只向右、不再走斜坡)。厚书脊里
- 竖排文字的边和折痕一样陡,ABW-147 按形状仍选中文字边;文字边不满高,折痕从上贯到下。切点自身满高不动
- (正封边框也满高),书脊左缘也满高所以不往左看;TKM-005 正封左侧黑边跟着切掉是已知代价。
-- **缝也没有时看孤立尖峰**(`_sharp_beyond`):书脊与正封同底色的封套,折痕只在书脊内容的行里存在,是周围中位数
- 3 倍以上、左比右忙的窄峰(IPZ-602);正封内容的起笔正相反(PPT-018)。ABP-627 的低对比折痕是已知边界。
-- 框就是正封本身:`x0` 是折痕列,右下角就是源图右下角。框里不另取子区域,因为卡片的
- 容器比例只有页面知道,在这一侧先按某个形状切一刀,只会把正封两侧各削掉一圈。
-- 默认只算边车缺失、版本落后或尺寸对不上的封面,重探换大图后再跑即重算;`--redo` 才全算。
- 改了判据要进 `ALGORITHM_VERSION`,重算完再重启服务,否则旧服务整批拒收新边车、全站框消失。
-- 页面只用框里的 `x0`:`frontend/src/card-art/framing.ts` 的 `posterPanel` 把它换算成 `--panel-clip` 与
- `--panel-left`,图片按卡片高度铺满、`clip-path` 切掉折痕以左的封底,正封居中摆。
-- **正封容器比例定在 0.75**:一行卡片等高,正封完整居中,比例差异处保留卡片纯色底。
- 整幅大封在竖版按主脸填满、横版完整显示,均不使用模糊补边(ADR-0107)。
-- 找不到折痕的按 `PANEL_ASPECT` 从右缘量回去,记 `ratio`;形状仍是正封的物理比例。
-- **宽封套由厂牌开门、比例决定走不走**(`WIDE_SLEEVE_LABELS`:CWPBD、SMBD)。Blu-ray 模板
- 750×419 与 mgstage 16:9 剧照只差 1%,比例与满高缝无法单独区分两者;
- 厂牌在名单且比例在 1.75~1.85 才按正封 0.85 先验在 0.83~0.87 窄窗找折痕,DVD 比例照旧走上一档。
-
-## 正式批次
-
-先重探所有缺失,包括旧的确认落空:
-
-```powershell
-& .\.venv\Scripts\python.exe .\scripts\fetch_jav_covers.py --retry-misses
-```
-
-再重探宽度低于 1200 的已有封面;只会升级,不会降级:
-
-```powershell
-& .\.venv\Scripts\python.exe .\scripts\fetch_jav_covers.py --upgrade-existing --upgrade-max-width 1199
-```
-
-## 收尾
-
-1. 再跑 `--audit`,报告前后缺失、损坏、尺寸分布、取得、保留与失败。
-2. 抽查新增来源 URL 与本地图片尺寸,确认番号精确匹配。
-3. 代码变更跑 `& .\scripts\test.ps1 -Scope metadata`;跨域时跑 full。
-4. 分开报告代码/测试、真实封面产物、生产服务和 ledger;本流程正常不重启、不写 ledger。
+重跑只读审计,比较取得、保留、缺失、损坏与失败,抽查番号、精确 URL 和实际像素。代码按影响域走正式测试入口;分别报告代码、封面产物、适用服务与 ledger 状态。纯封面批次通常无需重启服务。
diff --git a/.claude/skills/peach-ledger-write/SKILL.md b/.claude/skills/peach-ledger-write/SKILL.md
index 149bec348..49dbf66eb 100644
--- a/.claude/skills/peach-ledger-write/SKILL.md
+++ b/.claude/skills/peach-ledger-write/SKILL.md
@@ -1,11 +1,11 @@
---
name: peach-ledger-write
-description: 在用户说迁移、migrate、--apply、合并实体、merge_entity、改真相字段、批量删除、清空回收站,或任何要写真实 ledger 的动作之前使用。
+description: 执行真实 ledger 迁移、真相字段写入、实体合并或不可逆删除前使用;临时测试库不属于真实写入。
---
# 真实 ledger 写入流程
-最后复核:2026-10-17
+最后复核:2026-10-26
证据来源:[开发约定](../../../AGENTS.md)、ADR-0005、ADR-0015、ADR-0017、ADR-0052、ADR-0091、ADR-0106。
真实库:当前写入者本机 `PEACH_DATA_ROOT/database/ledger.db`(WAL)。绝不能把共享传输副本或
@@ -18,9 +18,7 @@ description: 在用户说迁移、migrate、--apply、合并实体、merge_entit
3. `PRAGMA integrity_check`。
4. `peach migrate status` 核对版本。
5. 应用后重复计数并做服务 smoke test,前后差异逐条解释。
-6. 复核通过后清退旧备份:`scripts/prune_ledger_backups.py --apply`(缺省只列计划)。规则在
- `peach.ledger_backups`:最近 5 份、24 小时内、比 `ledger.db` 更新的都留,其余连同 `-wal`/`-shm`
- 删;账本 `integrity_check` 不是 ok 一份都不删。Windows 托盘每次启动按同一规则自动跑。
+6. 复核通过后清退旧备份:`scripts/prune_ledger_backups.py --apply`(缺省只列计划)。保留与清退条件以 `peach.ledger_backups` 为准;账本完整性检查不是 ok 时拒绝清退。Windows 托盘启动复用同一规则。
Windows 写者的托盘在启动与「重启服务」时、子服务停着的间隙自动跑 `migrate upgrade`,
备份、失败通知与 reader 不迁移见 ADR-0091。上面六步用于手工迁移与托盘之外的账本。
@@ -50,8 +48,7 @@ Windows 写者的托盘在启动与「重启服务」时、子服务停着的间
- `entity(kind, normalized_name)` 唯一约束冲突通常不是 bug,而是同一人的新旧艺名信号。
- 合并走 `peach.entities.merge_entity`:保留作品多的一侧,迁移关系、别名、外部引用、链接和
- 搜索词,旧称全部留作别名。`entity_external_ref` 每个 provider 只保留一条,同源第二条丢弃
- 并报告,不静默覆盖。
+ 搜索词,旧称全部留作别名。`entity_external_ref` 保留同一 provider 的多个独立页面;仅实际约束冲突无法迁移的引用计入 `dropped_refs` 并报告,见 `tests/test_entity_merge.py`。
- 合并不可逆:先取得用户授权并备份。唯一的自动路径是补别名后继(ADR-0064):minnano-av 或
av_neme 名字栏把两条女优实体列成同一个人时,后继自己备份到数据库目录再合;别的判据不得照搬。
- 两条实现陷阱:sqlite 连接默认 `foreign_keys=OFF`,子表行必须在函数内显式 DELETE,否则留下
diff --git a/.claude/skills/peach-reference-evidence/SKILL.md b/.claude/skills/peach-reference-evidence/SKILL.md
index a3091679b..49c9bd19b 100644
--- a/.claude/skills/peach-reference-evidence/SKILL.md
+++ b/.claude/skills/peach-reference-evidence/SKILL.md
@@ -1,11 +1,11 @@
---
name: peach-reference-evidence
-description: 在用户说模仿、参考、对齐、复刻、照着某个网站或 App 做,给出外部产品截图要求照做,或追更参考来源时使用。
+description: 复现或对齐外部产品界面、登记参考取证、更新已锁定参考来源时使用。
---
# 参考产品取证与登记
-最后复核:2026-10-18
+最后复核:2026-10-26
证据来源:`AGENTS.md`、[开发约定](../../../AGENTS.md)、ADR-0015、
jakubkrehel/skills 的 explain-interface(证据分级)。
@@ -27,13 +27,7 @@ jakubkrehel/skills 的 explain-interface(证据分级)。
`docs/reference-snapshots/` 顶层,正文写明不登记并指向对应 upstream 文件。`accept` 会用线上字节整个覆盖
`snapshot`,把笔记登记成 snapshot 就等于下一次接受时把笔记删光。
-范例格式(现有条目照此写):
-
-> **Beeg 卡片控件(2026-08-15)**:加载 `.../main.9442c3b8.css`(SHA-256 `E585...`),
-> 计时圈 36 px、上/右 12 px、`rgba(0,0,0,.24)`、2 px 白色圆环;Peach 按用户要求改为连续
-> 悬停 5 秒才放大,并保留自己的居中控件。
-
-## 失败报告规则
+## 失败与版本接受
- 浏览器工具拒绝 URL 不等于公网不可达;本机 `curl.exe` 的 Schannel 握手失败也不等于代理失效。
换一条可复现通道再下结论,并写明用了哪条。
@@ -52,8 +46,4 @@ jakubkrehel/skills 的 explain-interface(证据分级)。
4. 需要改 Peach 时,同一提交包含实现、回归测试、对应公开文档与锁定快照;私有核验记录留在数据根。
5. 人工审完后才运行 `accept`,同时传当前完整 SHA-256;Git 来源还必须传完整 revision。
-## 纠正记录
-
-已发生过的错误结论要写回登记,不要只删旧句:
-「取到 frost token」曾被误写成「全部表面已对齐」;旧代码注释里无证据的 `Rule34-style`
-声明已删除。
+纠正错误结论时同步更新证据登记与引用,不以删除一句话替代派生结论核对。
diff --git a/.claude/skills/peach-reuse-first/SKILL.md b/.claude/skills/peach-reuse-first/SKILL.md
index c9460b787..348d54686 100644
--- a/.claude/skills/peach-reuse-first/SKILL.md
+++ b/.claude/skills/peach-reuse-first/SKILL.md
@@ -1,50 +1,30 @@
---
name: peach-reuse-first
-description: 在新增、恢复或重写 Peach 功能,尤其涉及外部协议、解析器、抓取、媒体、锁、调度和跨平台基础设施时使用。
+description: 新增、恢复或重写 Peach 功能、外部协议、抓取、媒体与基础设施能力时使用。
---
-# 先找成熟实现,再写 Peach 差异
+# 复用与实现范围
-最后复核:2026-09-16
-证据来源:ADR-0010、`docs/REUSE.md`、FANBOX 传输与正文解析事故、2026-08-28 全仓自研实现审计。
+最后复核:2026-10-26
+证据来源:ADR-0010、`docs/REUSE.md`、FANBOX 与浏览器数据复用事故、用户确认的复杂度与调查停止条件。
-## 强制顺序
+## 选择路径
-1. **按能力找现有代码**:先搜当前树、`docs/REUSE.md` 和 Git 历史。不要用旧文件名是否存在
- 判断能力是否存在。
-2. **找外部轮子**:查官方协议与 SDK、PyPI/npm、维护中的 GitHub 项目和系统原生能力。至少记录
- 维护状态、许可证、固定版本、Python/平台兼容性、依赖体积和已知故障。读候选的实现源码用
- `opensrc path <包名>`(全局 CLI,装法 `npm i -g opensrc`;支持 npm、PyPI、crates 与 GitHub 仓库,
- 拉到 `~/.opensrc` 后直接 `rg`),不拿类型定义或记忆里的 API 顶替真实实现。
-3. **跑最小实证**:用本任务的真实输入做无写入 POC;比较输出完整性、失败模式、流量、耗时和
- 打包可用性。登录 Cookie、token、URL 查询参数和真实内容不得出现在日志或文档。
-4. **只选一种正式路径**:
- - 成熟依赖完整覆盖基础能力 → 直接复用,Peach 只保留领域 policy 和 DTO;
- - 没有合适库但有成熟开源实现 → 固定 revision,复用其数据模型/算法边界并登记许可证;
- - 外部实现不满足可验证约束 → 保留自研,但把不采用的候选、实证和特殊约束写进 REUSE。
-5. **同批交齐**:依赖、首个真实消费者、隔离测试和 `docs/REUSE.md` 必须同批提交。候选依赖不得
- 因为「以后可能用」提前进入运行时。
+1. 按能力搜索当前树、`docs/REUSE.md`;有证据缺口再查 Git 历史,不以旧文件名缺失判断能力不存在。
+2. 已有实现覆盖需求时直接复用,验证本次差异后停止调查;局部修复不自动触发外部依赖评选。
+3. 确需新基础能力时比较官方协议、SDK、维护中的库与系统能力;实际候选核对维护、许可、固定版本、平台兼容、体积与已知故障。
+4. API 定义不足以决定方案时才读候选源码,可用已安装的 `opensrc`,不把工具安装设成固定前置。
+5. 用无真实写入的最小 POC 验证会改变选型的约束。Cookie、token、查询凭据与真实内容不进入日志或公开文档。
-## 判断边界
+成熟依赖覆盖基础能力时只保留 Peach 领域 policy 和 DTO;复用开源模型或算法固定 revision 并遵守许可。外部方案不满足已验证约束时保留自研,在 `docs/REUSE.md` 说明理由。
-Peach 应自研的是实体身份、跨来源绑定、凭据隔离、候选复核、成本/隐私、任务语义和产品交互。
-通用 HTTP 指纹、站点公开数据模型、浏览器数据库解析、文件锁、媒体提取、编解码、播放器、图标、
-轮播和调度默认不自研。
+## 复杂度边界
-「外部项目不是可直接安装的库」不等于忽略它。先判断能否复用稳定的协议模型、解析分支、测试样本
-或算法边界;若照着实现,必须固定来源 revision 并遵守许可证,不能凭记忆抄一份。
+- 新兜底、重试、兼容或竞态分支须有可触达输入、失败结果与依据;无依据的理论分支默认省略,必要的范围扩展由用户决定。
+- 未知输入在负责的边界校验,内部沿用已成立的类型和契约;新信任边界仍须校验。失败与无结果分别表达,不用默认值伪造成功。
+- 单次使用的 helper 在表达独立概念或隔离复杂边界时才抽;注释说明非明显约束及后果。
+- 实体身份、跨来源绑定、凭据隔离、候选复核、任务语义与交互属于 Peach 差异;通用传输、解析、锁、媒体编解码与控件优先复用。
-## 坏例 / 好例
+## 交付
-- 坏例:FANBOX 详情连续补 User-Agent、Cookie 和错误文案,却没有先检查成熟客户端怎样处理传输指纹
- 与 `image`、`file`、`article`、`video` 等正文类型。
-- 好例:传输复用固定版 `curl_cffi`;正文模型先对照 PixivUtil2 的成熟 FANBOX 分支,再只实现 Peach
- 所需的规范化 DTO、凭据边界和媒体队列。
-- 坏例:看到 Chromium 与 Firefox 的 SQLite 表不一样,就各写一套发现、快照和查询代码。
-- 好例:先用真实 Chrome、Firefox、Zen 数据库验证 `browserexport`,Peach 只保留隐私存储、Takeout
- 导入和口味分析。
-
-## 收尾报告
-
-明确列出:采用的外部实现及固定版本、保留的 Peach 差异、拒绝的候选及原因、POC 证据、是否新增
-依赖、是否改变生产和 ledger。没有合适轮子时也要给出检索与拒绝证据,不能只写「未找到」。
+新增依赖、首个消费者、行为验证、锁文件与复用记录同批提交,不提前引入未来消费者。报告采用实现、领域差异、关键拒绝理由与实证;没有新增选型时不重做整份调查。
diff --git a/.claude/skills/peach-shell-commands/SKILL.md b/.claude/skills/peach-shell-commands/SKILL.md
index b29b42e86..795cff964 100644
--- a/.claude/skills/peach-shell-commands/SKILL.md
+++ b/.claude/skills/peach-shell-commands/SKILL.md
@@ -1,75 +1,30 @@
---
name: peach-shell-commands
-description: 在写 PowerShell 或 Bash 命令、交给用户在终端跑命令、拼多行内容、用 rg 或 Python CLI、在测试里造临时目录,或命令报了看不懂的语法与编码错误时使用。
+description: 编写 Peach shell 命令、多行内容,处理路径、编码或测试临时目录时使用。
---
-# 命令与路径的形态
+# Peach 命令与路径
-最后复核:2026-10-13
-证据来源:`tests/test_agent_worktree.py` 与 `tests/test_scripts.py` 里临时目录 `.resolve()`
-和正斜杠路径的注释、`scripts/test.ps1` 与 `scripts/test.sh` 的编码约定、Git 历史里被
-heredoc 转义损坏的那几次补丁、`scripts/test_runner.py` 的外部工具预检,以及 2026-07 至 09
-Claude 与 Codex 会话记录里交给用户、被贴回报错截图的 39 条命令。
+最后复核:2026-10-26
+证据来源:命令故障记录、正式测试入口、临时目录别名与 Windows 权限边界。
-## 交给用户跑的命令
+## 执行前
-用户终端在 Windows 上是 PowerShell 7,在 Mac 上是 zsh,都不是智能体自己工具里的那个 shell。
-通用的错法与写法见用户级技能 `user-terminal-commands`(`~/.agents/skills/`)。Peach 专属的几条:
+- 确认当前主机与 shell;本机 PowerShell 使用 7.x,默认单引号,需要展开时才用双引号。交给用户的命令另按用户级 `user-terminal-commands` 核对,Windows 为 PowerShell、Mac 为 zsh。
+- 用户终端目录不确定时,项目 venv 与脚本写绝对路径或先进入已核实的项目目录。不要把自己的 shell 写法直接交给用户。
+- 参数查当前入口,不凭记忆:集成需要 `integrate --branch`,手动迁移使用 `migrate upgrade --yes`。备份文件名含时间戳,重跑不覆盖已生成备份。
+- `rg` 路径参数不含通配符,筛文件用 `-g`;退出码 1 表示无匹配。Python CLI 加 `-X utf8`,PowerShell 读取 UTF-8 文本加 `-Encoding utf8`。
-- 终端不一定在 peach-app,出现过停在 `.claude\worktrees\<会话>` 里的情况。所以 venv 与脚本写绝对路径:
- `& <用户目录>\Desktop\peach\peach-app\.venv\Scripts\python.exe -X utf8 <同上>\scripts\x.py`,
- 写出时把占位换成实际路径。也可以在命令开头加 `Set-Location <peach-app 绝对路径>;`。
-- 不能凭记忆写的参数:`agent_worktree.py integrate --branch <分支>`;迁移要写
- `peach.exe migrate upgrade --yes`,只写 `migrate` 只会打印状态。
-- `--apply --backup` 的备份文件名带 `$(Get-Date -Format yyyyMMdd-HHmmss)`:上一次失败前备份已经写出,
- 同名重跑会报 `FileExistsError`。
-- 交出前确认前提成立:`restart_windows_tray.py` 需要托盘已经在运行;`uv sync` 碰到运行中的
- `peach.exe` 会报拒绝访问;不要让用户删本会话终端的启动目录。
+## 文件与转义
-## 何时使用
+- 修改用编辑工具。多行命令、消息与文档先保存成 UTF-8 文件再交入口读取,不用 heredoc 或多层 shell 转义拼接。
+- 跨 shell 路径使用正斜杠;变量使用任务专属名称,不覆盖系统变量。PowerShell 的 `foreach` 结果先保存,再交管道格式化。
+- 测试临时目录先 `.resolve()` 再交给被测代码和断言,避免 runner 路径别名产生假差异。
+- 递归删除或移动前核对绝对目标与归属,保留运行中的终端目录、真实数据与他人文件;按本任务 PID 清理,不按进程名批量结束。
-在这台机器上写任何 shell 命令之前。这些不是风格偏好,每一条都对应真实重犯过的失败;
-违反后多数当场报错,少数(多行内容的转义)是静默损坏,那一类的核心判据留在 `AGENTS.md`。
+## Windows 权限与失败
-## 按当前 shell 写
-
-- PowerShell 的 `cat`、`ls`、`where` 是别名,语义与 Unix 同名命令不同;Bash 没有
- `Get-ChildItem`。写命令前先确定自己在哪个 shell 里。
-- PowerShell 只用 `pwsh` 7.x。从 Bash 调用时加 `-NoProfile`。
-- 默认单引号,需要展开才用双引号,有歧义时写 `${name}`。
-- `rg` 的路径参数不含 `*`,要筛文件用 `-g`;退出码 1 表示无匹配,不是失败。
-- Python CLI 加 `-X utf8`;PowerShell 读 UTF-8 日志显式加 `-Encoding utf8`。编码要在输出端
- 固定,只给读取端指定编码挡不住乱码。
-
-## Windows Codex 沙箱
-
-- `windows.sandbox = "elevated"` 是隔离模式,不是管理员权限。项目测试、npm/PyInstaller 构建、
- Git common directory 写入需要正常 PowerShell 权限时,从第一次调用就用受控提权和窄命令前缀;
- 不先在沙箱里制造一次 `WinError 5`。
-- `_winapi.CreateProcess` 或 `.git/**/index.lock` 返回拒绝访问时,原样重跑统一入口;不拆成单测、
- 不改断言、不跳过用例。`scripts/test.ps1` 会在分片前报告无法启动的外部工具。
-- `danger-full-access` 是取消隔离,不是「提权沙箱」。除非用户明确要求承担全局风险,否则保留沙箱,
- 只给当前项目入口所需的命令授权。
-- 测试、构建与媒体任务直接使用项目入口,不外套 CPU、内存、进程数或重任务槽位守卫;任务范围与取消按本机 `resource-budget.md`,进程清理只按本任务 PID。
-
-## 多行内容一律先写成文件
-
-多行内容用写入工具或脚本写成文件,再让命令读那个文件,不要用 heredoc。反斜杠会被吃掉一层,
-换成带引号的定界符也挡不住所有情形,而损坏是静默的:命令照常退出 0,写进去的内容已经变形。
-提交消息同理,写进临时文件再 `git commit -F`。
-
-Windows 与 Git Bash 之间传路径时统一写正斜杠(`Path.as_posix()`)。`C:\Users\...` 落进
-shell 脚本后反斜杠会被当成转义符吃掉,`exec` 拿到的是一个粘在一起的名字。Git Bash 也不按
-shebang 找 Windows 上的 Python,解释器要显式写出来。
-
-## PowerShell 变量与管道
-
-- 变量必须用任务专属名称。禁止声明 `$HOME`、`$home`、`$CODEX_HOME` 等系统变量的任何
- 大小写变体。
-- `foreach {}` 的结果先存进任务专属数组,再单独接管道格式化。禁止在闭合花括号后直接写管道。
-
-## 测试里的临时目录
-
-一律先 `.resolve()` 再喂给被测代码和断言。CI runner 的临时目录都是别名:macOS 的 `/var`
-软链到 `/private/var`,Windows 的 `RUNNER~1` 短名展开成 `runneradmin`。开发机没有这层别名,
-拿未 resolve 的路径断言只会在 CI 上红,本机怎么跑都是绿的。
+- Git common directory 写入、项目测试与构建需要正常权限时,从首次调用走受控授权和窄命令,不把隔离模式当管理员权限。
+- 创建子进程或 `index.lock` 拒绝访问时,原样重跑正式入口;不拆测试、不改断言、不跳过门槛。不修改 ACL 或关闭隔离来绕过失败。
+- 主检出依赖同步可能被运行中的 `peach.exe` 占用;按重启入口处理,工作树使用自己的 venv。`restart_windows_tray.py` 先确认托盘确实在运行。
+- 测试、构建与媒体直接使用项目入口,不外套 CPU、内存、线程、进程数或机器级槽位限制;本机任务范围与取消按用户级 `resource-budget.md`。
diff --git a/.claude/skills/peach-surfaces/SKILL.md b/.claude/skills/peach-surfaces/SKILL.md
index 130229c70..16d16b259 100644
--- a/.claude/skills/peach-surfaces/SKILL.md
+++ b/.claude/skills/peach-surfaces/SKILL.md
@@ -1,35 +1,26 @@
---
name: peach-surfaces
-description: 在改完界面、API、契约、数据层或用户可见文案,准备收尾、报告完成、验收或提交前使用;用户说漏了、别的页面没改、只改了一半时也用。
+description: 界面、API、数据层、契约或用户可见文案改动的验收与交付前使用。
---
-# 每个影响面都要过一遍
+# 影响面验收
-最后复核:2026-10-25
-证据来源:[开发约定](../../../AGENTS.md) 各次事故记录、`AGENTS.md` 语义契约门槛、ADR-0015。
+最后复核:2026-10-26
+证据来源:跨页面遗漏记录、`docs/TESTING.md`、用户确认的升级生效判据与范围审查。
-本仓库最常见的缺陷是「改动在你测试的那条路径上成立,在别的影响面缺失」。收尾前逐项声明
-**适用并已处理** 或 **不适用及原因**,不要跳过不适用的项。
+## 检查
-## 清单
+先列本次真实影响。检查不等于修改;不受影响的层保持原样,不为填清单增加代码。
-1. **数据层**:ledger 查询、迁移、`entity` 与兼容投影是否需要同步?只改显示文本而数据层未动,
- 多半是漏了。
-2. **API 契约**:`/api/*` 的请求参数、返回字段、404 行为;写入端点是否有对应的读端点。
-3. **页面**:核对所有复用该组件或契约的页面与入口,路由以 `docs/ROUTES.md` 为准。
- 一个交互改了首页卡片,通常也要改实体页卡片。
-4. **反向状态**:加了「进入某状态」就必须有「退出该状态」。稍后看/已标记/回收站/隐藏标签
- 都成对存在。
-5. **视口**:桌面默认视口与 390×844 手机各看一遍,横向溢出与文字折行分开报告。
-6. **测试**:按影响面验证实际行为:数据层调用真函数或接口,页面用组件或浏览器测试;
- 同一失败模式优先在能真实触发它的最小层验证。源码检查的范围见 `docs/TESTING.md`。
- 修复的存量生效条件按 [升级生效范围](../peach-worktree/SKILL.md#修复的升级生效范围) 判断,不以技术层划分是否需要迁移验收。
-7. **文档**:公开文档说明通用用法、契约与复用,ADR 记录架构取舍;公开需求进路线图。
- 本机运行态、个人待办、馆藏盘点与私有证据只保存在仓库外,不进入提交。
-8. **两个智能体入口**:新规则或新流程是否需要进 `AGENTS.md` 索引或某个技能,Codex 才能读到。
-9. **生产**:服务是否已真的切换并复核端口与进程归属。没重启就不能说已上线。
+1. **数据层**:查询、迁移、实体与兼容投影是否受影响?纯显示文案不自动扩展为数据改动。
+2. **API**:请求、返回、缺失和错误状态是否一致?用户操作需要的读写入口是否完整?
+3. **页面**:按 `docs/ROUTES.md` 找复用组件或契约的全部调用方。
+4. **状态**:可逆操作有退出或撤销路径;永久删除和终止状态不伪造逆操作。核对加载、空态、错误和完成态。
+5. **视口**:有布局影响时核对桌面与 390×844 手机,分别判断溢出与折行;纯接口或规则修改不要求页面验收。
+6. **测试**:同一失败模式在最便宜且能真实触发它的层验证,分工见 `docs/TESTING.md`。存量生效按 [升级生效范围](../peach-worktree/SKILL.md#修复的升级生效范围)。
+7. **文档**:用法、契约、复用、决策各归所属;规则变化检查入口与技能路由,个人记录留在仓库外。
+8. **生产**:任务包含运行切换时核验实际进程、资源与生效状态,执行适用重启;不以提交或测试代替上线证据。
-## 验证分开报告
+## 报告
-静态/单元/API、桌面浏览器、390×844 手机、生产是否已重启,四项分别给结论。
-任一项未做就写「未验证」,不得用其中一项冒充另一项。
+记录各项「已处理」或「不适用及原因」。交付突出实际结果、关键未验证项与用户动作,不机械展开无关清单。静态、单元/API、桌面、手机与生产结论分别使用对应证据;未执行的适用项写「未验证」。
diff --git a/.claude/skills/peach-web-ui/SKILL.md b/.claude/skills/peach-web-ui/SKILL.md
index 53db467f7..4a1dfff6a 100644
--- a/.claude/skills/peach-web-ui/SKILL.md
+++ b/.claude/skills/peach-web-ui/SKILL.md
@@ -1,112 +1,40 @@
---
name: peach-web-ui
-description: 在新增、修改、预览或复核 Peach 页面、控件、提示、错误、数据面板、响应式布局或视觉样式时使用。
+description: 新增、修改或验收 Peach 页面、控件、页面文案、布局与视觉状态时使用。
---
-# Peach Web UI 复用门槛
+# 界面实现与预览验收
-最后复核:2026-10-25
-证据来源:现有 UI 契约、`docs/TESTING.md`、本机重复文案与异步轮询回归记录、jakubkrehel/skills 与 emilkowalski/skills 摘录、`docs/reference-snapshots/open-claude-ui.md`、用户真实小样本预览、明确确认后测试及所有预览默认接入 `?edit` 的约定。
+最后复核:2026-10-26
+证据来源:三端维护约定、UI 契约、真实小样本预览、用户明确确认后测试的授权边界。
-## 开工顺序
+## 开工
-先完整读取用户级 `peach-ui-consistency`(`~/.codex/skills/peach-ui-consistency/SKILL.md`),统一生产应用、官网与演示站的共用能力和验收。交付每个页面时,同时提供普通预览链接与启用编辑器的链接;两者指向同一代码、数据和路由,分别核对查看与编辑能力。
+1. 完整读取用户级 `peach-ui-consistency`,统一生产应用、官网与演示站的维护源、同步和预览交付。
+2. 核对相关路由、已有控件与调用方。React 复用 BoardUI 与 Peach 组合件,遗留 DOM 复用 ui-kit;不要把遗留颜色、组件名称或 CSS 规则套到 BoardUI。
+3. 检索项目记忆「界面预览与真实样本」,读取已登记入口;样本、来源核验、编辑保存按 `docs/UI_PREVIEW.md`。用户验收只用真实小样本与缓存,合成夹具用于隔离自动化测试。
+4. 按下表只读相关章节。外部产品被点名参考时执行 `peach-reference-evidence`;未取得当前证据就明确未取得,不猜动画、间距或行为。
-0. 先检索项目记忆“界面预览与真实样本”,读取已有入口及覆盖清单。用户验收预览只用真实小样本及现有缓存;来源核验与交付门槛见 `docs/UI_PREVIEW.md`、`scripts/check_ui_preview.py`。来源未取得就停止交付,合成夹具仅用于隔离自动化测试。
-1. 读取相关页面、`frontend/src/ui-kit/`、`web/css/` 与 `tests/test_web_ui.py`,先找现成控件、token 和行为;按 `docs/DESIGN_GUIDELINES.md` 对应章节核对层级、容器、输入、滚动、手势与反馈,验收参数仍以本技能和现有契约为准。
-2. 外部产品被称为参考时同时执行 `peach-reference-evidence`;没有当前可复现证据就写 `未取得`,不补动画、间距或交互猜测。
-3. 视觉与交互先过 `docs/reference-snapshots/vercel-web-interface-guidelines.md` 的 Focus States、Forms、Animation、Content 四节,以及 `vercel-report-design.md`(即 `vercel.com/design.md`)的「Reject generated-design reflexes」;第三方逆向测量的 DESIGN.md(如 design-bites)不作证据。
-4. 新控件先检查 `docs/reference-snapshots/vercel-geist-controls-measured.md`、`vercel-geist-semantics-measured.md`、`vercel-geist-note-progress-switch-analytics.md`、`vercel-geist-command-search-loading.md`、`vercel-geist-button-icons.md` 与 `vercel-geist-split-button.md`。
-5. 收尾前用 `docs/reference-snapshots/jakubkrehel-interface-skills.md` 与 `emilkowalski-skills.md` 的检测表自查,组件按「极端内容场景」挑轴、按「极端值要真实」取值写夹具;与本技能冲突时以本技能为准。
- 用 `break-ui`、`/state-machine` 时,临时页和演示开关只建在本任务工作树里,交付前删掉。
+| 当前任务 | 参考 |
+| --- | --- |
+| 控件选择、颜色与组件体系 | `docs/UI_COMPONENT_CONTRACTS.md` 的「适用组件体系」「组件选择」「组件与视觉」,React 同时查 `docs/BOARD_UI.md` 对应条目 |
+| 加载、进度、错误、成功与撤销 | 组件契约的「等待与回执」,文案按 `docs/WRITING.md` |
+| 输入、菜单、弹层、确认与键盘 | 组件契约的「表单与浮层」,`docs/DESIGN_GUIDELINES.md` 对应章节 |
+| 标签、播放器与导航异步状态 | 组件契约的「媒体与页面状态」及相关域实现 |
+| 新布局、对齐参考、极端内容 | 设计准则、已登记的对应来源快照;只选本次相关轴,不要求读取全部参考集合 |
-## 组件选择
+## 实现与预览
-| 需求 | 使用 | 不要使用 |
-| --- | --- | --- |
-| 字段、卡片、分区旁的持久反馈 | Note | Toast、空状态 |
-| 页面/系统级问题与恢复动作 | Banner | Note |
-| 短暂操作回执 | Toast | 持久 Note |
-| 写操作前的确认 | `confirmModal()` | 原生 `confirm()`、Toast |
-| 一个主动作加 1–4 个近亲做法 | Split Button(主动作在左,第一项菜单项与它同名同事) | 把变体摊平成并排按钮、把破坏性动作当主动作 |
-| 一行内的重排 | `wireDragReorder()` 拖动 | 上下移动按钮 |
-| 已知总量的进行状态 | Progress | 装饰性蓝条 |
-| 用户触发动作等待结果 | Spinner | 旋转原操作图标、Loading Dots |
-| 后台任务仍在推进 | Loading Dots | Spinner、假百分比 |
-| 整页或大区块首次等待内容结构 | Skeleton | Spinner、Loading Dots |
-| 2–3 个互斥视图 | Switch(radio) | Toggle |
-| 布尔开关 | Toggle | Switch |
-| 无布局高度变化的菜单 | Menu/Listbox;开合走 `presentMenu`/`dismissMenu`,动效只在 Board 层那一份 | Collapse 动画、自己再写一份 150ms |
-| 带搜索语义的输入 | Search Input(搜索图标前缀;搜索中原位换 Spinner) | 无图标裸输入 |
-| 全屏命令/设置覆盖层 | 有锁定证据的 Dialog motion | 把同一动画套给普通菜单 |
-| 展开正文或分组 | Collapse | 自造 easing |
-| 一组输入/候选及其底部动作 | Fieldset | 自造卡片 Footer |
-| 固定高度区域中的溢出内容 | Scroller | 页面级滚动或嵌套滚动区 |
-| 没有数据或结果 | Empty State(图标、标题、说明同组) | 裸灰字或把说明拆到组件外 |
-| 图标含义与补充说明 | Tooltip | 让浮层撑宽页面 |
-
-## 实现门槛
-
-- 优先扩展 `frontend/src/ui-kit/`,不要为同一语义复制一次性 class 和模板。
-- 数据表统一用 TanStack Table 驱动 BoardUI `Table`,具备全集排序、分页、跨页选择与批量操作;工具栏、分页和批量栏按关注列表复用 `data-table.tsx`、`table-controls.tsx`、`DataTableFrame` 与 `SelectionDock`,默认每页 20 条,同页只保留当前表格的选择。
-- 管理页单面板分区的标题放在面板内,不在框外重复;多卡片分组可用框外标题。同级分区标题用 `text-title-2-medium`,加载态与内容态共用 500 字重、20px 字号和 26px 行高。
-- 控件高度只取 `--control-h-inline`/`-compact`/`--control-h`/`-large` 四档,同一行的同类控件同档;与文字同行的图标用 `--icon-inline`,单独图标按控件档取固定值;下拉不点开也要看得出在选什么(上方标签、触发键前缀或格子选择器的弹层标题三选一)。判据与坏例见 `docs/DESIGN_GUIDELINES.md` 第 2、10、11 节。
-- 颜色、字号、圆角、浮层层级只用 `:root` 已有 token;新 token 必须证明现有词汇无法表达。
-- 字重只有 400/500/600 三档,标题按既定层级选择 medium 或 semibold;圆角只用 `--badge-radius`/`--control-radius`/`--surface-radius`/`--floating-radius`/`--pill-radius` 加 `50%` 与 `0`,带边框容器里的头尾条用 `calc(… - 1px)` 保持同心。两者的字面值由 `tests/test_web_ui.py` 拒绝,归属判据见 `:root` 注释。
-- 单色优先:`--tungsten` 只给焦点环、链接、进度/数据与 Toggle 开态。主动作用 `--ink` 底 `--ground` 字且每屏最多一个。标题悬停下划线不变蓝,计数徽章中性灰。其它选择器引用 `--tungsten` 由 `tests/test_web_ui.py` 拒绝;实测见 `vercel-geist-semantics-measured.md`「选中态与开关色」「Button 全变体与状态」。
-- 选中态只有填充:一律 `--hover` 底 `--ink` 字,不加边框、不加 `inset` 一圈线、不加字重(Geist Switch/Tabs 的类名里三样都没有)。填充既然专属选中,**同一排横向**互斥选项的未选中项悬停就只提文字色到 `--ink`;没有选中态的按钮和没有并排邻居的孤立开关悬停照旧抬填充。侧栏导航(`.edge`/`.dnav`)分工相反:实测 Geist 左栏是悬停抬填充、当前项握着文字与图标色,别把横排那条推广过去。清单见同一份快照的「选中态与它的悬停」和「侧栏导航是例外」。
-- 按钮悬停只抬填充:次级到 `color-mix(in srgb,var(--ink) 8%,var(--ground))`(Geist gray-200 那一档,全站同一个值),主动作到 `color-mix(in srgb,var(--ink) 88%,var(--ground))`,边框与文字色都不动。主动作那条悬停规则要自己写上 `color:var(--ground)`,否则同组更宽的通用 hover 里那句 `color:var(--ink)` 无人竞争,浅色实底上落成白字白底。禁用走 `--surface` 底、`--border-15` 边、`--muted` 字,不用 `opacity`;按下不加 `scale`。三条都有 Geist Button 源规则佐证。
-- `outline:0`/`outline:none` 只允许出现在同一规则给出替代焦点样式的地方(`box-shadow` 或子元素 outline),或输入框由带 `:focus-within` 的容器接管焦点时;reduced motion 由全局 `@media (prefers-reduced-motion:reduce)` 统一关闭,不逐处补。
-- Progress 必须有真实 `value/max`、可见单位与 `aria-valuemin/max/now`;分隔线放在完整指标(含进度条)之后。
-- Switch 必须共享 radio `name`、初始一个 `checked`、键盘可用;布尔状态继续使用 Toggle。
-- 菜单每项包含与入口相同的图标和文字,菜单内部滚动、`overscroll-behavior:contain`,不得把浏览器页面撑出滚动条。锚定菜单一律走 `wireAnchoredMenu`:高度压到触发钮那一侧真正剩下的空间(上沿是 `--topH` 顶栏下缘),装不下就在菜单内滚,不横跨触发钮;页面滚动关掉菜单,菜单自身的滚动不关。
-- 只读查询(搜索、筛选)不配提交按钮:回车即执行,忙态落在表单自己身上(`form[aria-busy]` 加前缀原位换 Spinner)。有副作用的提交必须有按钮,且回车同样要能提交。表单里除这个输入框外还有别的字段时浏览器不做隐式提交,回车要自己接管 `requestSubmit()` 并跳过 `isComposing`。判据与实测见 `docs/reference-snapshots/vercel-forms-submit-affordance.md`。
-- Spinner 只反馈用户直接触发的动作,触发器统一调用 `setActionBusy()`:写入 `aria-busy=true` 与 `aria-disabled=true`、视觉变灰、拦截重复触发,同时保持可聚焦;请求等待期不得再用原生 `disabled`,它只留给缺输入、无权限等动作确实不可执行的状态。未知时长的后台抓取使用 Loading Dots。整页或大区块首次取数使用 Skeleton 预留最终结构。Spinner/Loading Dots 保留可见状态文字;Skeleton 只保留给辅助技术的状态名,不另画「正在读取」文案。三者都尊重 reduced motion。
-- 确认弹层一律走 `confirmModal()`:原生 `<dialog>` 承载,标题是陈述句,正文先说后果并点名
- 涉及的两个值,主按钮是与标题同一动词的「动词+名词」,取消键就写「取消」,成功 Toast 与主
- 按钮的动词一一对应。写入交给 `onConfirm`,忙态落在主按钮上,失败时弹层不关、原因留在正文
- 下方等重试。形状与文案判据见 `docs/reference-snapshots/vercel-geist-modal-measured.md`。
-- 用户写操作只在服务端终态成功后调用共享 `actionReceipt()` 发一条过去时 Toast;可由安全逆操作完整恢复的状态提供 8 秒「撤销」,永久删除、凭据、保存到账本等不伪造撤销。仅打开面板/菜单/Dialog 不算操作完成,不发 Toast;失败除短 Toast 外仍在原位置保留原因与重试入口。
-- 同一次页面进入只呈现一段等待态;深链启动与页面取数复用同一个 Skeleton,禁止 Spinner 再切换成 Loading Dots 或 Skeleton。
-- Skeleton 只覆盖真正等待的内容区;静态标题、导航和能同步得到的筛选控件立即显示。骨架必须复用最终容器的宽度、列数与对齐方式:卡片网格横向铺满,居中面板仍居中,不得用一列通用占位替代不同页面结构。
-- 骨架里的占位不接指针、没有任何悬停反馈(`09-skeleton.css` 一处关掉);要等数据才能执行的键用原生 `disabled` 加 `data-skeleton-action`,呈全站共用的禁用面(`--surface` 底、`--border-15` 环、`--muted` 字、not-allowed),不用 opacity,也不伪装成可点的最终档。
-- 关注来源标签先服从来源记录的类型:只有明确标为 `general` 的标签才能进入卡片、顶部筛选和在线标签页,`artist`/`character`/`copyright`/`metadata` 与未知类型不得靠词形猜成 `general`。通用词清理是第二道门槛,只处理已经确认的 `general`;详情可显示全部来源标签,并按真实类型着色。
-- 危险动作的悬停态一律 `--drop` 实底加白字。只描红边、红字的话,静止态和悬停态在暗色底上几乎一样亮,按下去之前看不出这是不可逆动作;带文字的销毁按钮全站一个写法,纯图标删除键不适用。Geist 的 error Button 同样是实心红填充,只是它静止态就红。实测见 `vercel-geist-controls-measured.md`。
-- 下拉框的用途用框内左侧 16px 前缀图标标明,不在同一行挂一个文字标签:Geist 的文字 Label 是块级、排在控件上方,行内并排那种写法它没有,而工具行没有上方空间。无障碍名称改由 `aria-label` 承担。
-- 按钮的前置图标只在图标指向对象(来源站点、当前选中项、平台)或形态方向(触发器右侧的 `chevron-down`)时出现;文字已经把动词说完的不加,`+ 添加`、`↻ 刷新`、`✓ 保存` 这枚多余字形会把同一行主次动作的视觉重量拉平。图标键必须给 `aria-label`,名称点出动作和对象、不描述图标形状。判据与 Geist Button 文档正文见 `docs/reference-snapshots/vercel-geist-button-icons.md`;官方 Geist 图标 SVG 没有可直取的入口,同一份快照记了原因。
-- 同一行里的输入框和按钮共用 `--control-h`,不各写一个像素数:两个控件差 3px 就不是一行了,而差值往往来自窄屏那条防放大规则只抬其中一个。
-- 一枚字形只代表一个意思,同一个意思也只有一枚字形。取字形先问它指的是哪个名词或哪个方向:文件类型取 `file-*`,本地取 `hard-drive`、订阅源取 `rss`,往下接一页取 `chevron-down`,原地换一批取 `shuffle`,`refresh-cw` 只归「去问一遍来源有没有更新」;筛不出结果和一次比对没有发现是两个空态,不能共用一枚。图标语义结合控件的可访问名称与实际操作复核。没有使用者的 symbol 从 `scripts/vendor_web_dependencies.mjs` 的名单和雪碧图里一起删,用户点名留的备用件在名单旁说明用途。
-- 播放器控制条的窄屏折叠按播放器自身宽度判定(`ResizeObserver` 观察 `player.el()`),不用媒体查询:同一个视口下影院模式和普通视图的播放器宽度差一大截,用视口判据会在影院模式下白折叠、在普通视图下继续超框。门槛与提示外观见 `youtube-player-controls-user-screenshot.md`。
-- 分页末尾、空页和「没有更多内容」是中性终止状态,用可关闭 Note;只有需要恢复或处理的故障才能进入红色 error Note。
-- 弹层标题栏与滚动正文分层:标题分隔线属于卡片全宽,滚动条只属于正文。
-- 没有直接证据不得新增动效。菜单开合的证据是 boardui `menu-styles.ts`(`docs/BOARD_UI.md`),已落在 board.css 的共用规则里;旧版 Geist 层仍无动画。
-- Fieldset 的正文统一 20px 内边距;标题条与底部操作条同为 `--fieldset-bar-h`(52px)、竖直居中、左 20px 右 16px。标题放在框体里,不用原生 `<legend>`:它会在上边框上开缺口,同组卡片内容高度不同时缺口位置也跟着不齐。同组卡片必须同高,变化内容只放一个纵向 Scroller。
-- 界面不解释数字是怎么算出来的。口径、免责、隐私声明、「不会做什么」和「按什么汇总」都不写:这个库只有一个用户,定口径的就是他本人。只留他要据以决定或操作的东西:读数本身、不可逆动作的作用范围、正在发生的事。单位跟着数字走(`497 项`),不另起一行说明。
-- 上一次跑完的结果不常态显示。它是那一刻的快照,进页面就铺开会被读成现在的状态,而页面上没有任何东西说它是旧的;只有仍在进行的任务才自动接管页面。
-- Empty State 的标题和说明必须同处组件内;全页空态与上方工具条统一留 16px,不得再套一层空卡片。
-- 任何先请求再重绘整页的入口都必须绑定导航代际;只比较 `location.pathname` 不能防住「离开后快速返回同一路径」的旧响应。
-
-## 验收门槛
-
-- 监听预览端口前由启动入口调用 `check_ui_preview.py`,取得成功的 `real-ledger-subset` 报告;提供地址时说明已读约定、实际样本与已查看场景。缺少清单、伪造字段或关联、图像缓存缺失均拒收,不以进程就绪代替实图验收。
-- 交给用户的预览同时提供普通版和 `edit` 版链接,普通版在前;覆盖首次设置、登录、错误页、主界面及演示站。复用现有编辑器,按 `docs/UI_PREVIEW.md`「文案编辑」核对工作树归属、浮条与保存生效链路。
-- 预览前核对标题、说明、持久提示与操作回执的职责,同一事实只在承担该职责的位置说明;检查加载、空态、错误和完成态,避免重复说明与残余内容。
+- 复用真实组件、语义 token 与既有编辑器;临时压力测试页或演示开关只留本任务工作树,交付前清理。
+- 预览启动前取得 `scripts/check_ui_preview.py` 的成功 `real-ledger-subset` 报告,核对代码、数据、图像缓存与端口归属;来源未取得时不交付伪预览。
+- 普通与编辑模式分别核对;每个交付页面提供指向同一代码、数据、路由的普通链接和 edit 链接,普通版在前,保留可访问服务。进入详情前关闭自动播放。
- 界面改动先构建并保留可访问的预览,提供地址;只有用户明确确认当前预览后才能运行测试,确认绑定该预览与范围,范围内沿用。发出地址、用户继续纠正和等待超时都不算确认;收到界面新纠正时停止本任务运行中及排队的测试,修好后重新等待确认。确认前只做实现、预览构建与视觉查看;用户明确只要图片时才仅提供截图。
-- UI 标签、身份、反馈状态和搜索推荐属于语义契约:按实际影响验证数据层、组件或浏览器行为。
- 推荐词上线前对真实 `/api/items` 验证至少一个命中,说明性后缀不得
- 混入搜索词(坏例 `ABW 番号`,好例 `ABW`)。
-开发中通过标准测试入口显式选择最小影响域;浏览器问题只跑对应 E2E 分片,先取得失败证据,再修到通过。
-相关分片通过且代码不再变化后运行一次 `auto`;它选择 `full` 时,不为每次局部修复重复全量测试。
-环境或资源失败先修环境并重跑失败域,最后只保留一次覆盖最终代码的有效 `auto`/`full` 记录。
+## 验证与交付
-1. 先确认失败模式与现有覆盖,再选择组件、API/数据层或浏览器测试;检查关闭后停止轮询时,在关闭及相关导航完成后记录请求基线,再观察有无新请求。纯文案、等价重构不补源码文本断言;通用规范由 lint 或集中扫描检查,具体分工见 `docs/TESTING.md`。
-2. Windows 从隔离 worktree 根运行 `& .\scripts\test.ps1`,默认 `auto`;按影响域补测,规则见 `peach-worktree`。
-3. 桌面与 390×844 的通用不变量(无横向溢出、无越出视口的元素、等待态会结束、控制台无错误、无失败请求)由 `web` 域的 `tests/test_web_e2e.py` 执行,不再逐页手测;新路由加进 `frontend/e2e/smoke.test.ts` 的 `ROUTES`,分区 tab 由用例逐格切过去再测。用例靠 `aria-busy` 与 `data-skeleton` 判断页面稳定,React 子树也要写:BoardUI 组件不带加载态,由 Peach 包装件补上。浏览器里发现的可判定问题(几何、computed style、状态切换),先在 `frontend/e2e/` 写出失败用例再修。页面迁到 React 时,旧源码断言按 ADR-0031 分三类再删:设计决定进 `frontend/e2e/design-*.test.ts` 或 lint,行为进 vitest,布局与运行期进冒烟。
-4. 浏览器取证只留给用例表达不了的:新布局首次成形、对齐外部参考、hover/focus 与观感判断。默认用 `agent-browser`(全局 CLI,装法 `npm i -g agent-browser`;
- 环境变量 `AGENT_BROWSER_EXECUTABLE_PATH` 指向本机 Chrome,`AGENT_BROWSER_SESSION=<任务名>` 隔离会话):`open <url>` → `wait <选择器>` → `snapshot -i -c -s <选择器>`/`get styles <选择器>`/`eval <js>`/`screenshot <文件>`,验完 `close`。
- Bash 工具里每条命令加 `</dev/null` 或把输出重定向到文件:接管道时 CLI 会等 stdin 直到工具超时。残留守护进程核对任务归属后按 PID 清理,不按进程名批量结束。
- 托盘服务发的是主检出的 `web/`;界面预览复用项目记忆登记的启动入口,指定当前代码工作树及独立真实样本,通过来源核验后才监听端口。不要直接启动连接原账本的服务。进入详情前关闭 `peach.settings.v1.detailAutoplay`,避免发声。
-5. 接口字段、sidecar 取值和锚点算术走 Python 严格 HTTPS(项目 CA 加 `ProxyHandler({})`)核对,不进浏览器。浏览器只留给布局后才成立的事实:`getComputedStyle`、真实裁切几何、hover/focus 态和实际像素;用读源码顶替这几样是降精度。
-6. 一轮验收要读的页面状态先列全,再合成一次 `agent-browser eval` 取回一个 JSON。桌面应用的 Browser 面板只在要让用户当场看画面时才开:私有网络主机(`.local` 与 `10.`/`172.16-31.`/`192.168.` 段的局域网 IP 归同一类)在那里只能逐次授权,站点级放行只给只读工具,点击与执行 JS 拿不到常驻许可,每多发一次调用就多一次弹窗。
-7. 按 `peach-surfaces` 报告数据层、API、页面、契约、测试与文档各影响面;未部署不得称为生产已生效。
+1. 确认失败模式与现有覆盖,按 `docs/TESTING.md` 在组件、API 或浏览器层验证;代码冻结后运行一次 `auto`,不逐域重复全量。
+2. 通用桌面和 390×844 不变量由正式 web 域执行,新路由接入 `frontend/e2e/smoke.test.ts`;几何和 computed style 问题先写可失败用例,语义行为不补源码措辞断言。
+3. 人工浏览器留给新布局、参考对齐与观感判断,使用当前环境支持且符合用户偏好的浏览器入口,不把某个 CLI 的安装或历史权限行为设为固定前置。
+4. 接口、sidecar 和算术可用严格校验项目 CA 的独立请求核对;布局、裁切、hover/focus 必须用浏览器证据。工具失败及时报告准确错误和未验证范围。
+5. 同页所需状态先列全,再批量读取;不以进程就绪、静态通过或源码推断代替实图验收。搜索推荐词对真实 `/api/items` 核对命中,说明性后缀不混入关键词。
+6. 按 `peach-surfaces` 核对真实影响,分别报告验证与生产状态;未切换不得称已生效。
diff --git a/.claude/skills/peach-worktree/SKILL.md b/.claude/skills/peach-worktree/SKILL.md
index b9c8f1227..d1093b158 100644
--- a/.claude/skills/peach-worktree/SKILL.md
+++ b/.claude/skills/peach-worktree/SKILL.md
@@ -1,110 +1,53 @@
---
name: peach-worktree
-description: 在用户说并行、工作树、暂存、提交、ready、集成、生产重启,或任何要写 Peach 代码的任务开始时使用。
+description: Peach 代码任务开工,以及创建、提交、集成或回收工作树时使用。
---
-# 并行 worktree 与提交边界
-
-最后复核:2026-10-25
-证据来源:[开发约定](../../../AGENTS.md)、`README.md`、ADR-0015、ADR-0017、本机工作树与沙箱工具记录、测试域登记失败与交付中断复盘、2026-10-22 多分支集成复盘。
-
-## 是否委派与何时使用
-单一功能域、局部改动或预计 30 分钟内完成的任务,由协调者在自己的隔离工作树直接完成;只有任务可独立并行、需要隔离环境,或长跑过程能明确缩短总耗时才委派。
-默认最多一个工作者;多个工作者只用于彼此无依赖的任务。委派只传目标、相关文件、边界和验收命令,不转交完整对话。
-协调者只在完成、阻塞或至少五分钟的检查点读取状态,不做分钟级轮询,也不重复工作者完成的搜索、浏览器检查和测试。
-跨对话消息仅用于对方需要处理的具体依赖;发送前核对状态与职责。授权不等于同步义务,不唤醒已结束对话只为报进度或收确认;交付以 Git 和共享证据为准。
-任何会写入当前机器 `peach-app` 的代码任务都使用隔离工作树。主目录只做集成,不做并行编辑;worktree 本机重建,不跨机器复制目录。
-
-## 流程
-1. 协调者在主目录创建隔离工作树:`& .\.venv\Scripts\python.exe -X utf8 scripts\agent_worktree.py create --agent claude --task <task>`。它建在 `peach-worktrees/`,Codex 和 Claude 共用这一个目录。**不要用 Claude Code 内置的工作树机制(`.claude/worktrees/`)**:它在分支被集成后会被回收,目录却留在原地。
- Windows Codex 对 `create`/`ready`/`integrate`/`prune --apply`、`git add` 与 `git commit`
- 从第一次调用就按 `peach-shell-commands` 的沙箱规则使用受控提权;它们会写主检出的
- Git common directory,工作树目录可写不代表 `.git/worktrees/**` 可写。
-
-2. 工作者只在自己的工作树内编辑。行为修复先列触发条件、成功与失败路径、对应回归及影响域;复现用例与实现同步交付,纯文案按既有检查验收。`create` 自动锁定工作树,成功集成后解锁;不复制 `.venv`;用 `uv sync --locked --all-extras` 创建自己的测试环境。
-3. 测试在当前工作树根目录运行:Windows `& .\scripts\test.ps1`,macOS/Linux `./scripts/test.sh`。默认 `auto` 按改动文件取影响域并集;文档及无改动检查 `checks`,未知影响面、共享测试设施和实际依赖选 `full`。域清单唯一真相在 `scripts/test_runner.py`;局部调试可显式选域。
- 两者契约相同:优先当前树 venv,缺失时从 Git common directory 定位主项目 venv,强制 `PYTHONPATH=<当前工作树>/src`,
- 核对 `peach.__file__` 后运行标准库 `unittest`。禁止手工拼接 venv 路径或调用 pytest。
- 测试入口固定 `PYTHONIOENCODING=utf-8`,覆盖标准输出、错误输出及子进程;其他 Python CLI 使用 `-X utf8`。
- 安装依赖和构建完成后再验证;测试期间不改变环境。测试期间静默等待,完成或确需用户处理的阻塞时统一汇报。
- 新增或改名测试时,用正式入口定向运行 `test_scripts.OperationalScriptTests.test_every_test_file_is_registered_in_a_scope` 检查登记;测试文件存在不代表 `auto` 会选中。
- 用 `-Focus` / `--focus` 先验证相关 Python 或浏览器用例,调试不签记录;冻结改动后只运行一次 `auto`,不另写逐域循环。失败先定向修复,再让 `auto` 复用未受影响的记录;记录有效期、补测与 `-Fresh` 的口径见 `docs/TESTING.md`。
-4. `ready` 前将当前 `master` 纳入工作树并运行 `auto`。相同内容可复用记录;目标变化重算影响域。`ready` / `integrate` 拒绝缺记录、范围不足或目标分支未纳入的提交。
-5. 协调者接到工作者的 `ready` 后继续完成授权范围内的 `integrate`、适用重启与运行核验;分支交接不等于任务验收完成。`integrate` 在锁内复查并合并固定提交;取得成功退出状态并核对主线提交后才重启。锁忙交给入口等待,禁止直接 merge;提示带持锁方的 pid、开始时间与范围,不反复数进程。运行记录写到仓库外的私有上下文;工作者按文件分工,共享文件安排顺序。
- 版本号不在这里动:推进与打标签只走 `scripts/release_tag.py`(`--bump auto --apply` 定版待人确认措辞,`--ship --apply` 提交、推送、等 Test 转绿、打标签,ADR-0012 修订;停在半路就重跑同一条)。
- 「该发一版了」只由 `release_due.py` 的 Stop 钩子说,`integrate` 输出的 `release` 是同一判据,收尾不重复。
- CI 分片、系统覆盖与发布复用见 `docs/TESTING.md`;合并完成不机械追加全量。
- 主检出 master 上的直接提交与手工 merge 由 `scripts/githooks/` 拒收;它统一入口而非权限隔离,`--no-verify` 等仍可绕过。
+# 工作树与集成交付
-## 修复的升级生效范围
-
-证据来源:用户于 2026-10-25 确认,按修复生效条件限定升级验收范围。
-
-- 前后端使用同一判据。替换代码或资源并正常刷新、重启即可生效的修复,运行对应行为回归,不强制增加迁移或新装/升级双轨检查。
-- 既有数据、配置、任务断点、缓存或派生产物需要转换、补修、失效或重算才能让修复生效时,复用相应机制并用临时旧样本验证,保留人工资料和个人记录。
-- 涉及安装器、依赖分发、数据目录或升级协议时,再按影响验证覆盖升级;源码或单元回归不代替相应制品验收。
-
-## 多分支一起合入
-两条以上分支同时待合时,由一个协调会话统一测试与合入:先让各会话停掉自己的 `auto`、`ready`、`integrate` 与重试循环并报最终版尖端。
-各自跑全量会轮番占住全量测试锁,`integrate` 等满 30 分钟拿不到锁,满载又让时序用例随机超时;每合一条,其余分支还得重新 rebase、重跑全量。
-做法:`create --task integration-batch`,按「无冲突、有冲突、自己的」顺序 `merge --no-ff` 各最终版尖端;`web/dist` 冲突取集成侧、末尾统一 `npm run build`。
-源码冲突只在两边主人交代了保留项、能逐项全保留时才解,否则 `merge --abort` 排下一轮由主人 rebase。末提交带整批的 README-Impact,跑一轮 `auto`,再 `ready`、`integrate`。
-全站性的尺寸、字号或命名改动(控件高度档、行内图标、分区改名)交付前搜 e2e 里写死的旧值与旧名,并跑全部 e2e,不能只跑定向用例。
-改按钮文案或把按钮换成链接时,搜旧文案在测试里的每一处,以及该组件 e2e 里按 `button`、`button:nth-of-type` 取元素的写法。
-单条 vitest 超 5 秒、e2e 等待超 30 秒先看 `agent_worktree.py processes` 里有几个 `test_runner`,满载时单跑确认,不在满载下反复全量。
-
-## 暂存与提交
-- 每个提交主题写成 `type(scope): 中文描述`,类型清单在 `scripts/commit_subject.py` 的 `TYPES`;写歪的后果是变更日志静默漏条,`ready` / `integrate` 拒收。
+最后复核:2026-10-26
+证据来源:工作树入口、交付门槛、集成与回收事故、用户确认的存量生效判据。
-- 交付分支最后提交加 `README-Impact: updated; 说明` 或 `README-Impact: none; 原因`;只改一份 README 时另加 `README-Reviewed: 未改文件名; 原因`,细节见 `docs/README_MAINTENANCE.md`。
- 它与 `Co-Authored-By` 连续写成末尾同一块:块内隔空行、或块与正文之间不空行,都会被当成正文,报「须有唯一 README-Impact」。
+## 开工与职责
-- 每个提交署名 `Co-Authored-By: 工具 (模型 版本) <厂商 noreply>`,如 `Claude Code (Opus 5) <[email protected]>`、`Codex (GPT-5.5) <[email protected]>`;
- 括号里的模型版本用来事后分辨是哪一代写的。名单在 `scripts/co_author.py` 的 `VENDORS`,`ready` / `integrate` 逐个提交判;接力写成时并列署名,人类共同作者写「姓名 <邮箱>」。
+代码任务使用 `scripts/agent_worktree.py create --agent <当前智能体> --task <任务>` 的本机隔离工作树,主目录只负责集成;不使用 Claude 内置工作树机制,不跨机器复制目录。
+创建、暂存、提交、集成与回收按 `peach-shell-commands` 取得所需权限。编辑前核对 `git rev-parse --show-toplevel`、注册状态和文件归属,目录存在不代表工作树有效。
-- 禁止 `git add .`、`git add -A`、目录路径或 glob。只暂存任务明确拥有的文件。
-- 提交前用 `git diff --cached --name-status` 与任务边界逐条对照。干净的 `git status`
- 不能证明归属正确。
-- 实现与其测试必须原子提交。反例 `bba0b77`:测试被误判为本任务文件而进入提交,对应
- `probe.py` 未暂存,HEAD 出现「测试指向不存在实现」。
+单域局部任务由协调者直接完成;只有独立并行或隔离能缩短总耗时时才委派,默认最多一个工作者。只传目标、相关文件、边界与验收,不转交完整对话。状态只在完成、阻塞或至少五分钟检查点读取,不重复工作者已完成的搜索与验证。
+跨对话消息只处理具体依赖,须有用户授权;不唤醒已结束对话只为报进度。工作者不自行集成、真实写入、把候选升级、修改迁移或 ADR、重启生产;协调者负责完整交付。
-## 工作者禁止事项
-自行 merge、执行 `--apply`、把候选标为 `approved`、修改迁移或 ADR、重启生产服务。
-这些属于协调者。
+## 验证与集成
-## 已知陷阱
+1. 在当前工作树准备独立 venv,按 `docs/TESTING.md` 安装锁定依赖,不复制 venv 或修改正在服务的环境。
+2. 行为修改先列失败路径与影响域,通过正式入口定向验证;新增或改名测试核对域登记,不能以文件存在代替覆盖。
+3. 冻结改动后运行一次 `auto`;未知影响、实际依赖和共享设施用 `full`。环境、编码、源码定位、记录复用和补测契约统一见 `docs/TESTING.md`,不逐域循环重复公共用例。
+4. `ready` 前纳入当前 `master` 并验证最终内容。提交、声明与记录齐全后取得 `ready` 的实际结果。
+5. 协调者执行 `integrate --branch <分支>`,等成功退出并核对主线提交,再做适用重启和运行核验。锁忙交入口等待,不手工 merge 绕过,不把分支交接当成验收完成。
-- **工作树会悄无声息地失效,目录却还在**:分支被集成后注册消失,目录成了主检出里的旧副本,在里面跑的 git 全作用于主检出的 master,
- 得出的是假结论而不是报错。判据只看 `git rev-parse --show-toplevel` 与 `git worktree list` 里有没有你那一行。
-- 生产重启只用 `scripts/restart_windows_tray.py`;用 Computer Use 点托盘、强杀或另起 `.venv\Scripts\peach.exe` 会让 `_owned` 失真。
-- 落后很久的分支 rebase 到本地 `master` 时只移植仍需要的独有改动:共享文件上旧的那一侧解错冲突,会把已上线的修复回退掉。
+主检出 master 的直接提交与手工 merge 由 hook 拒收。版本推进、标签与发布只走 `scripts/release_tag.py`,发布核对按运行文档与 `docs/TESTING.md`;发布时机采用 `release_due.py` 及集成入口的同一判据,不额外重复检查。
-## 回收与顶层归置
+## 修复的升级生效范围
-工作树用完要回收:`python scripts/agent_worktree.py prune` 列出分支已并入 master 且工作区
-干净的工作树,加 `--apply` 才真的删。
-脏的一律拒收并单独列出:分支已合入不等于工作区
-里没东西,实测就有工作树的分支早已并入 master、里面却躺着一份成形的未提交改动。
-被 Git 忽略的 `build/` 里还有文件、或者还有进程开在里面(会话、终端、服务)的,也进 `kept`:
-2026-10-24 一次回收删掉了一个会话正开着的工作树,`build/` 里的日志和复盘报告没有备份。
+- 替换代码或资源并正常刷新、重启即可生效的修复,跑对应行为回归,不强制增加迁移或新装、升级双轨检查。
+- 既有数据、配置、断点、缓存或派生产物需要转换、补修、失效或重算时,复用相应机制,用临时旧样本验证并保留人工资料与个人记录。
+- 安装器、依赖分发、数据目录或升级协议变化再验证对应制品;源码或单元回归不代替制品验收。
-一个工作树失败不影响其它工作树:`residue` 是连脚本也删不掉的目录,分支照样删,`holders` 列出占着它的进程(`orphan` 为真是父进程已退出的残留),
-按 PID 结束自己起的再重跑;`processes` 子命令列出两处落点下的全部活进程。`failed` 是注册还没摘掉,分支保留。未登记的目录归 `swept`:`peach-worktrees/`
-与 `.claude/worktrees/` 两处都扫,只删空的,有文件的进 `kept` 等人确认,因为那种目录和真
-工作树长得一模一样,在里面跑 git 全作用于主检出的 master,门槛在 `tests/test_repo_hygiene.py`。
+## 多分支一起合入
-`prune` 保留锁定的活动工作树。不要手动解锁正在编辑的工作树;任务中止时先核对任务归属、
-改动与提交,再决定是否解锁回收。
+由一个协调会话统一测试与集成。先协调各任务停止本批次的测试、ready、integrate 与重试,核对最终提交;不停止无关任务。
+在专用集成工作树按无冲突、有冲突、自己的顺序合入最终提交。源码冲突只在双方保留项已明确且能全部保留时解,否则中止本次冲突合并,交原任务更新分支。
+`web/dist` 冲突保留集成侧,源码合齐后统一构建。最后提交声明整批 README 影响,跑一轮 `auto` 再 ready、integrate。
+全站尺寸、字号、命名或控件语义变化须检查全部相关浏览器用例;小改按影响选测。时序超时先用 `agent_worktree.py processes` 排查本任务重叠运行,不在相同失败状态反复全量。
-`Desktop\peach` 顶层只放 ADR-0017 定义的四个运行时目录加一个 `attic/`:
+## 暂存与提交
- peach-app peach-data peach-sync peach-worktrees attic
+- 逐文件暂存后核对 `git diff --cached --name-status` 与任务边界,不使用目录、glob、`git add .` 或 `git add -A`。实现与对应测试原子提交。
+- 主题为 `type(scope): 中文描述`,类型以 `scripts/commit_subject.py` 为准。
+- 每个交付提交带 `Co-Authored-By: 工具 (实际模型版本) <厂商 noreply>`,名单见 `scripts/co_author.py`;接力作者并列,人类共同作者保留姓名与邮箱。
+- 最后提交写唯一 `README-Impact`,需要时带 `README-Reviewed`,按 `docs/README_MAINTENANCE.md` 核对中英文。所有 trailer 连续放末尾同一块,块内无空行,块前空一行。
-`peach-` 前缀专属那四个,不再新增;别的东西按性质进 `attic/` 的 `builds`/`evidence`/
-`instances`/`tools`/`reviews`,目录名写成 `YYYYMMDD-主题`,顶层不放散落文件,
-由 `test_repo_hygiene` 守住。这条规则只写在仓库外的 `../attic/README.md` 时,在 peach-app 里
-干活的人根本看不到它,清完两天又堆回三个违规目录。 <!-- copy-lint-disable-line -->
+## 回收与顶层归置
-`attic/` 不等于可以随便删:`instances/` 常带 100 MB 量级的 ledger 副本,`tools/` 的
-`runtime.json` 会留 token。账本副本、复核产物和取证归档按 AGENTS.md 的保留清单对待,
-删除要单独确认。
+用 `prune` 预演,`prune --apply` 仅回收入口判定安全的目录。脏文件、锁定活动树、忽略的 build 文件或占用进程均保留;不能因分支已合入就解锁或删除。检查失败不绕过门槛。
+`residue`、`failed`、`holders`、`swept` 以入口结果解释:只按 PID 清理本任务残留,未登记目录只自动删空目录,有文件留待确认。完成回收后核对注册列表与目录状态。
+项目父目录只放 `peach-app`、`peach-data`、`peach-sync`、`peach-worktrees` 与 `attic`;归档按用途放 attic 子目录,不新增 peach 前缀落点。归档中的账本、复核产物与可能含凭据的工具状态仍受保护,删除单独授权。
diff --git a/AGENTS.md b/AGENTS.md
index e097c283e..3d262a3d5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,87 +1,59 @@
# Peach 智能体工作契约
-本文件是 Codex 与 Claude 共用的唯一项目约定入口;项目与运行方式见 `README.md`。
-分层判据、写作规范与清退机制见 `docs/adr/0015-agent-context-layering.md`,不要默认追加到本文件。
+本文件是 Codex 与 Claude 共用的项目约定入口;项目与运行方式见 `README.md`。分层与清退见 `docs/adr/0015-agent-context-layering.md`,不要默认追加规则。
+公开文档与技能正文使用中文,技术标识保留英文;写作按用户级 `tech-doc-style-chinese` 和 `docs/WRITING.md`。回复简洁,结尾包含「我做了什么」「你需要做什么」。
-公开文档与项目技能正文统一使用中文。
-代码标识、命令、协议名、库名和无法准确翻译的专有名词保留英文;不要为了智能体处理方便混写英文叙述。
-中文写作风格按用户级技能 tech-doc-style-chinese 执行;项目覆盖与检查入口见 `docs/WRITING.md`。
-回复用日常语言讲清结果、原因、处理和验证,技术细节按需展开;结尾保留「我做了什么」「你需要做什么」。
+## 授权与保护
-风格与流程默认服从用户当场指令。在授权范围内完成修改、必要验证和失败修复。
-写真实 ledger、不可逆删除、换生产入口(端口、主机、二进制或版本)、处理凭据与私钥,必须在同一轮取得明确授权。
-已提交且测试通过的代码直接用 `restart_windows_tray.py` 重启并核验;进行中的任务都能续跑就直接重启,手动或 CLI 发起的主任务在跑才先问。
-`agent_worktree.py prune --apply` 可直接回收脚本判定已合入且干净的工作树。
+- 在授权范围内完成修改、必要验证和失败修复,保留用户改动。真实 ledger 写入、不可逆删除、生产入口切换、凭据与私钥操作,须在同一轮取得明确授权。
+- 保留真实媒体、ledger 行、行为历史、凭据、网络与防火墙状态及无关长跑任务。测试使用临时数据库和临时媒体。
+- ledger 的 `asset.path` 保持 Windows 形态,由 `src/peach/platform.py` 读取转换;不得改写成 POSIX 路径或从 macOS 写 `asset.path`。
+- 代码判据确定、能按来源整批撤回的断言按 ADR-0052 落库;LLM 输出、打分、冲突与多候选只产生候选,不得自行标为 `approved`。真实写入执行 `peach-ledger-write`。
+- 编辑前核对 `git status`。代码任务使用 `scripts/agent_worktree.py create` 的隔离工作树,主检出负责集成;先读 `peach-worktree`。
+- 服务、端口或重启操作先核对监听与进程归属。已提交且测试通过的适用代码用 `restart_windows_tray.py` 重启并核验;手动或 CLI 发起的主任务仍在跑时先问,其余任务均能续跑时直接重启。
+- `agent_worktree.py prune --apply` 可回收入口判定安全的工作树;只按 PID 清理本任务创建的进程,保护活动工作树、忽略文件与其他任务。
-## 术语表
+## 术语
-同一件事只用一个词,回话时也用这些词,不要换成同义说法。
-
-- **你**:正在读本文件并改动 Peach 的智能体(Codex 或 Claude)。**我 / 用户**:在这台机器上部署、使用并维护 Peach 的人;每个部署只有一人。 <!-- copy-lint-disable-line -->
-- **ledger / 账本**:每台机器 `peach-data/database/ledger.db` 的本地工作副本,唯一真相源。**真相字段**:直接构成 ledger 断言的列。
-- **候选 candidate**:带来源与置信度、未经复核的断言。只有用户复核后才 `approved`,工作者不得自行升级。
-- **复核产物**:CSV 等可机读、可重放的中间结果;结论必须落在这里,不能只存在于对话。
-- **实体 entity**:女优、厂牌、创作者、系列的规范身份;扁平 `asset_tag`、creator/studio 字段只是兼容投影。
-- **影响面 surface**:一次改动可能需要同时覆盖的位置(数据层、API、页面、契约、测试、文档)。
-- **门槛**:由脚本、测试或 hook 强制的拒绝行为,区别于只写在文档里的提醒。
-- **协调者 / 工作者**:主目录里负责集成和验收的一方 / 隔离工作树里负责执行的一方。
-- **抽帧 / 九宫格**:FFmpeg 采样帧 / 九帧拼成的汇总图。**未取得**:取证失败的固定写法,不得用推测顶替。
+- **你**:改动 Peach 的智能体;**我 / 用户**:部署、使用并维护 Peach 的人,每个部署只有一人。 <!-- copy-lint-disable-line -->
+- **ledger / 账本**:当前实例数据根 `database/ledger.db` 的本地工作副本,唯一真相源;**真相字段**:直接构成 ledger 断言的列。
+- **候选 candidate**:带来源与置信度、未经用户复核的断言;**复核产物**:承载逐项结论、可重放的 CSV 等文件。
+- **实体 entity**:女优、厂牌、创作者、系列的规范身份;扁平 `asset_tag`、creator/studio 字段是兼容投影。
+- **影响面 surface**:改动涉及的数据层、API、页面、契约、测试、文档;**门槛**:脚本、测试或 hook 的拒绝行为,区别于文档提醒。
+- **协调者 / 工作者**:负责集成验收的一方 / 隔离工作树中执行的一方;**抽帧 / 九宫格**:FFmpeg 采样帧 / 九帧汇总图;**未取得**:取证失败的固定写法,不用推测替代。
## 按任务读取
-项目与运行方式见 `README.md`;部署读 `docs/OPERATIONS.md`,复用读 `docs/REUSE.md`,来源采集读 `docs/SOURCING.md`,架构边界读相关 ADR。只展开当前任务需要的部分。
-本机交接、运行记录、个人待办与复核产物只存 `<数据根>/state/project-context/` 等仓库外目录;公开文档只保留通用用法、契约与脱敏证据,禁止提交个人路径、主机坐标、馆藏盘点或私有日志。
-
-## 技能索引
-
-按需读取;Claude 按 description、Codex 按触发条件加载。
+部署读 `docs/OPERATIONS.md`,复用读 `docs/REUSE.md`,采集读 `docs/SOURCING.md`,架构取舍读相关 ADR。只展开本任务需要的章节。
-| 触发条件 | 文件 |
+| 触发条件 | 技能 |
| --- | --- |
-| 并行任务、创建工作树、暂存与提交、集成分支、回收工作树、顶层目录归置 | `.claude/skills/peach-worktree/SKILL.md` |
-| issue、PR 交付 | `.claude/skills/peach-issue-delivery/SKILL.md` |
-| 迁移、`--apply`、实体合并、批量删除等真实 ledger 写入 | `.claude/skills/peach-ledger-write/SKILL.md` |
-| 改完界面、API、契约或文案后声明影响面 | `.claude/skills/peach-surfaces/SKILL.md` |
-| 长跑批处理、刮削、限流、磁盘与流量预算 | `.claude/skills/peach-batch-jobs/SKILL.md` |
-| JAV 封面、高清封面、缺封面、封面刮削、重探与来源比较 | `.claude/skills/peach-jav-cover-workflow/SKILL.md` |
-| 模仿、参考或对齐外部产品的界面与行为 | `.claude/skills/peach-reference-evidence/SKILL.md` |
-| 界面必读:`~/.codex/skills/peach-ui-consistency/SKILL.md` 及本行技能 | `.claude/skills/peach-web-ui/SKILL.md` |
-| 在 macOS 上开工、改路径解析或挂载判定、git status 与 diff 不一致 | `.claude/skills/peach-cross-platform/SKILL.md` |
-| 写 PowerShell 或 Bash 命令、交给用户跑命令、拼多行内容、测试里造临时目录 | `.claude/skills/peach-shell-commands/SKILL.md` |
-| 新增、修改或清退智能体规则、入口与技能 | `.claude/skills/peach-context-rules/SKILL.md` |
-| 新增、恢复或重写实现,尤其协议、解析器、抓取、媒体与基础设施 | `.claude/skills/peach-reuse-first/SKILL.md` |
-
-## 工作规则
-
-- 应用、官网、演示站分仓托管于 `peach-mitao`;数据、工作树、构建输出、媒体与挂载不进 Git,见 ADR-0017、0085。
-- ledger 路径统一为 Windows 形态(`R:\Media\...`、`A:\...`、`B:\...`),由 `src/peach/platform.py` 读取时转换;不得改写成 POSIX 路径或在 macOS 写 `asset.path`。
-- `peach-data/database/ledger.db` 是真相源,真实写入按 `peach-ledger-write`。代码判据确定、可按来源整批撤回的结果直接落库(ADR-0052);LLM 输出、打分、冲突与多候选只产生带来源与置信度的候选。测试只用临时数据库,可直接运行并修复本次改动造成的失败。
-- 保留真实媒体、ledger 行、行为历史、凭据、网络与防火墙状态及无关长跑任务。
-- 预览先读项目记忆,真实小样本须过 `scripts/check_ui_preview.py`。
-- 编辑前核对 `git status`;涉及服务、端口或重启时核对监听与进程归属。生产结论须有实际切换与核验证据。
-- Peach 是单人自托管应用;替代实现验证通过后移除无用代码和兼容层,历史由 Git 保存。
-- 架构边界:模块化单体与磁盘分界(ADR-0017)、Stash 适配器关闭(0021)、前端迁往 React + BoardUI(0031)、分发阶段(0023);改变决策须新增 ADR。
+| 代码任务、创建或交付工作树、暂存、提交、集成、回收、顶层归置 | `.claude/skills/peach-worktree/SKILL.md` |
+| issue、PR 交付与关闭 | `.claude/skills/peach-issue-delivery/SKILL.md` |
+| 迁移、实体合并、真相字段、真实 ledger 写入与删除 | `.claude/skills/peach-ledger-write/SKILL.md` |
+| 界面、API、数据层、契约或用户可见文案的影响面验收 | `.claude/skills/peach-surfaces/SKILL.md` |
+| 长跑批处理、刮削、磁盘、流量、限流与续跑 | `.claude/skills/peach-batch-jobs/SKILL.md` |
+| JAV 封面获取、重探、来源比较与取景产物 | `.claude/skills/peach-jav-cover-workflow/SKILL.md` |
+| 模仿或对齐外部产品的界面与行为 | `.claude/skills/peach-reference-evidence/SKILL.md` |
+| 界面、文案、控件或预览;同时完整读取 `~/.codex/skills/peach-ui-consistency/SKILL.md` | `.claude/skills/peach-web-ui/SKILL.md` |
+| macOS、路径、挂载、双机交接或 Git 状态异常 | `.claude/skills/peach-cross-platform/SKILL.md` |
+| shell 命令、多行内容、路径与临时目录 | `.claude/skills/peach-shell-commands/SKILL.md` |
+| 智能体规则、技能、入口与预算维护 | `.claude/skills/peach-context-rules/SKILL.md` |
+| 新增、恢复或重写功能、协议、抓取、媒体与基础设施 | `.claude/skills/peach-reuse-first/SKILL.md` |
+
+## 验证与交付门槛
+
+- 测试只用当前隔离工作树的 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`。
+- 预览使用独立真实小样本,启动前通过 `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`。
+- 依赖精确固定版本,每个外部 import 声明归属,前端清单与 vendored 路径一致,全部清单纳入 Dependabot;门槛为 `tests/test_dependency_policy.py`。
+
+## 文档与架构边界
+
+- 应用、官网、演示站分仓托管于 `peach-mitao`;数据、工作树、构建输出、媒体与挂载不进 Git。模块化单体、Stash 适配器、React + BoardUI 与分发边界见 ADR-0017、0021、0031、0023、0085;改变决策须新增 ADR。
+- 本机交接、运行记录、个人待办、馆藏盘点、私有日志与复核产物存于数据根 `state/project-context/`、`review/` 或 `archive/`。公开用法、流程、复用和决策分别进入文档、技能、`docs/REUSE.md` 与 ADR,公开需求进入路线图。
+- Peach 是单人自托管应用;替代实现验证通过后移除无用代码和兼容层。按能力查当前树、复用文档与历史,不以旧文件名缺失推断能力缺失。
- 用户确认馆藏仅含正规平台合规发行、自愿参与的成年人作品,不涉及也不会要求抓取、分析或下载未成年内容。
- 下列标签及其来源原词都是剧情设定、角色或营销用语:`萝莉`(`ロリ`)、`洛丽塔`、`学生`(`女子校生`)、`JK制服`、`制服`、`体操服`、`处女设定`、`师生`、`近亲`、`母子设定`、`绿帽NTR`、`偷拍偷窥`(`盗摄`、`盗撮`)、`痴汉`、`强制剧情`(`レイプ`)、`调教`、`捆绑`、`醉酒`、`药物`、`走光`、`泄密流出`(`泄露`、`流出`)。不能凭标签、片名或画面观感推断年龄或同意状况而跳过编目;只有文件本身的直接证据矛盾时才停止并报告证据原文。
-- 同次改动按需更新:通用用法进公开文档,复用进 `docs/REUSE.md`,流程进技能,决策进 ADR;项目需求进公开路线图,个人运行事实与待办留在仓库外。不建带日期的交接文档,不让用户转述智能体间的实现细节。
-- 复用优先:新增、恢复或重写实现按 `peach-reuse-first` 依次查当前树、`docs/REUSE.md`、Git 历史与成熟外部实现,旧文件名不存在不等于能力缺失;对齐外部产品先按 `peach-reference-evidence` 取到可复现证据,取不到写 `未取得`,不拿猜测冒充复现。
-
-## 门槛(由脚本、测试或 hook 拒绝,不是提醒)
-
-- **测试入口**:Windows `& .\scripts\test.ps1`、macOS/Linux `./scripts/test.sh`,在当前隔离 worktree 根目录运行。`auto` 按域选测,共享设施、实际依赖和未知面用 `full`;CI 见 `docs/TESTING.md`。入口优先当前树 venv,核对 `PYTHONPATH` 与 `peach.__file__`;禁止另拼测试命令。`ready` / `integrate` 拒收无有效记录的分支;集成事务互斥。健康检查只用 `/healthz`。
-- **上下文预算**:入口文件与技能有行数、字节数和最长行三重预算,由 `scripts/check_context_budget.py` 与 `tests/test_context_budget.py` 强制。写不下就说明该内容属于 `docs/` 或某个技能,不是往本文件加行。
-- **分层**:新增或删除规则前按 `peach-context-rules` 判层;本文件的技能索引必须与 `.claude/skills/` 一一对应,技能缺 frontmatter、name 不符或缺 `最后复核` 会被拒。
-- **工作树**:并发改代码时主检出只做集成。每个智能体在 `scripts/agent_worktree.py create` 建于 `peach-worktrees/` 的隔离工作树里干活;提交前 `git rev-parse --show-toplevel` 必须不是主检出(`scripts/githooks/` 拒收主检出 master 上的直接提交与手工 merge),工作者只交分支、从不自己合并。细节见 `peach-worktree`。
-- **仓库整洁**:`peach-worktrees/` 与 `.claude/worktrees/` 下都不得留未在 `git worktree list` 注册的目录(`tests/test_repo_hygiene.py`);`prune --apply` 扫空目录,有文件的报出来等人看。不用 `git add .`、`git add -A`、目录路径或 glob,只暂存本任务拥有的文件再核对 `git diff --cached --name-status`;实现与它的测试原子提交。交付提交须署名(`scripts/co_author.py`)。
-- **文案只写最终状态**:界面字串、注释、docstring、测试名与文档不写改动前后对比,例外逐行加 `copy-lint-disable-line`(`tests/test_copy_final_state.py`)。
-- **测试写法**:读仓库文件再 `assertIn` 一段写法的源码文本断言按文件计数只减不增(`tests/test_source_assertion_ratchet.py`);行为、设计决定各归何处见 `docs/TESTING.md`「写什么测试」。
-- **依赖策略**:Python 依赖精确固定版本,每个被 import 的外部模块要有声明的归属,前端清单与实际 vendored 路径一致,所有清单都进 Dependabot(`tests/test_dependency_policy.py`)。
-
-## 常犯错误(没有自动拦截,都是真实重犯过的)
-
-- 改文件直接用编辑工具,让 diff 可审阅;脚本仅用于生成、批量变换或需解析定位的算法任务,须可重复执行且遍历、重试有终止条件。退出 0 或打印成功不能证明内容正确。
-- 多行内容先用写入工具保存成文件,再交给命令读取,禁止 heredoc;转义损坏可能静默成功。其它 shell 与路径问题见 `peach-shell-commands`。
-- 交给用户跑的命令按用户终端写(Windows PowerShell、Mac zsh),不照搬自己的 shell;写前按 `peach-shell-commands` 核对。
-- 收尾前按 PID 结束本任务起的调试服务、浏览器守护进程和后台命令,不按进程名批量结束;机器变卡时先跑 `agent_worktree.py processes`,看运行时长、CPU、内存和父进程是否还在,清掉自己的残留再起新的。
-- HTTPS 结论必须使用项目 CA 做严格校验;Schannel、浏览器或取证入口失败时,立即报告原始错误和未取得的验收面,不能改用 HTTP 成功来声称 HTTPS 已通过。
-- 界面、API、契约、数据层或用户可见文案改动,收尾按 `peach-surfaces` 核对各影响面并报告适用性;纯指令文档改动检查文档、入口与相关门槛。
diff --git a/docs/COVER_ARTWORK.md b/docs/COVER_ARTWORK.md
new file mode 100644
index 000000000..2b4b1876a
--- /dev/null
+++ b/docs/COVER_ARTWORK.md
@@ -0,0 +1,29 @@
+# 封面取景与边车契约
+
+封面获取流程见 [JAV 封面技能](../.claude/skills/peach-jav-cover-workflow/SKILL.md)。本文件用于取景或边车任务;来源与算法实证见 [来源采集](SOURCING.md),正式判据、阈值和版本在 `peach.jav_poster_crop` 与 `peach.face_detect`。
+
+## 生产者与消费者
+
+| 产物 | 生成入口 | 消费与保护 |
+| --- | --- | --- |
+| 人脸坐标 | `scripts/detect_cover_faces.py` | 保留归一化 `cx`、`cy` 和图像尺寸;裁切轴由容器比例决定,无脸时居中 |
+| 正封边车 | `scripts/poster_crop_boxes.py`、`peach.jav_poster_crop` | 保存原图坐标和算法版本,原图保持完整;手工框不被自动重算覆盖 |
+| 页面取景 | `frontend/src/card-art/framing.ts`、`frontend/src/jav-artwork.ts` | 复用边车和共享版式,不在页面抄写检测算法 |
+
+默认仅重算缺失、版本过期或尺寸不符的产物,`--redo` 表示明确全算。算法改变时同步版本、生产者与消费者,并验证旧边车的接收与重算;运行中服务需要切换时使用项目入口。
+
+## 折痕判据
+
+Sobel 列梯度寻找的是能切出合理正封形状的折痕,不按全宽固定百分比选最强边。窗口、突出度和形状阈值均读取源码常量。
+
+- 厚书脊存在竞争峰时按正封形状选择,不按谁更强;代表回归为 ABP-968。
+- 梯度斜坡的峰与终点分别处理;切点不满高时核对右侧满高接缝,避免把书脊文字边当折痕。ABW-147 覆盖文字边情形,TKM-005 对应已知黑边代价。
+- 无满高缝时结合孤立尖峰、左右纹理方向和局部基线,避免切掉正封内容;IPZ-602、PPT-018 与 ABP-627 覆盖对应输入。
+- 只有两侧接缝与纹理共同证明居中正封时裁中间;数字发行拼图、明确整幅图像与不满足判据的输入沿用当前版式判断。
+- 宽封套结合来源、版次与图片比例,不仅凭接近 16:9 的外形判断。厂牌、比例窗口与例外以当前实现为准。
+
+## 页面投影与验收
+
+框表达正封本身,页面容器负责最终比例和摆放,不在后端先裁成页面形状。传统正封完整居中,比例留白使用当前共享派生背景;整幅大封竖版按主脸填满、横版完整显示,不使用模糊补边。手工框与明确整幅布局保留。
+
+验证算法与前端投影时,同时检查人脸轴、图像尺寸、版本、正封边界和实际容器裁切。行为回归以 `tests/test_jav_poster_crop.py` 与前端卡片取景用例为准;通过坐标算术不能代替浏览器实际像素证据。
diff --git a/docs/DESIGN_GUIDELINES.md b/docs/DESIGN_GUIDELINES.md
index 042ac253b..3fd00223f 100644
--- a/docs/DESIGN_GUIDELINES.md
+++ b/docs/DESIGN_GUIDELINES.md
@@ -1,6 +1,6 @@
# Peach 设计准则
-本文件用于设计和审阅页面、控件、媒体查看器与任务反馈。组件选择、token 和强制门槛见 [Web UI 技能](../.claude/skills/peach-web-ui/SKILL.md),BoardUI 的采用范围见 [BoardUI 适配](BOARD_UI.md)。这些准则指导后续实现,不表示所有页面已逐项验收。
+本文件用于设计和审阅页面、控件、媒体查看器与任务反馈。组件选择与 token 见 [组件契约](UI_COMPONENT_CONTRACTS.md),执行与验收见 [Web UI 技能](../.claude/skills/peach-web-ui/SKILL.md),BoardUI 的采用范围见 [BoardUI 适配](BOARD_UI.md)。这些准则指导后续实现,不表示所有页面已逐项验收。
Open Claude UI 提供本文件的补充参考。采用范围与源码缺口见 [阅读与取舍](reference-snapshots/open-claude-ui.md);它对 Claude 官方实现的描述属于第三方自述,Peach 只采用可以解释自身需求的原则。实际参数服从项目已有 token、组件契约与本机验收。
@@ -64,7 +64,7 @@ Open Claude UI 提供本文件的补充参考。采用范围与源码缺口见 [
## 8. 反馈来自真实状态
- 操作区域先显示对象、范围和当前状态,细节按需展开。待执行、运行、等待来源、成功、失败、取消和部分完成保持各自语义;授权提示只在真实权限边界需要时出现。
-- Spinner、Loading Dots、Skeleton、Progress、Toast 与持久错误按 Web UI 技能选择。已知总量显示真实读数,估算明确标明;动画计时与模拟响应不能产生成功结论。
+- Spinner、Loading Dots、Skeleton、Progress、Toast 与持久错误按组件契约选择。已知总量显示真实读数,估算明确标明;动画计时与模拟响应不能产生成功结论。
- 失败保留输入、对象和原因,并给出当前可行的恢复动作。自动重试只用于已有策略允许的操作,界面显示服务端实际等待状态;刷新或打开面板不额外启动重试。
- 折叠详情不改变任务的运行状态。流式输出可以保持区域结构稳定,用户仍能收起不必持续阅读的日志;不因为任务运行就强制展开所有内容。
- 增量内容只更新受影响区域,异步结果绑定当前请求与对象,保留阅读位置和选择;不为每个新增片段重建整个内容区。
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 954ecf4e3..9cbabd0e9 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -111,7 +111,7 @@ Mac 与 Windows 托盘的首层只显示简短状态与提醒数量,展开状
单机设置默认关闭账本复制,不需要 Windows、SMB、LaunchAgent 或系统端口转发。各台电脑各自保存数据;共享馆藏仍按下文的[双机复制](#两台电脑之间的复制)配置,离线修改不能自动合并。已有数据目录不会自动导入。
-这条构建路径使用本地 ad-hoc 签名,未完成 Developer ID 签名和 Apple 公证,不作为已签名发行包发布。DMG 只分发应用,不安装系统服务;需要集中部署系统组件时再评估 PKG。转码与抽帧使用本机 FFmpeg,本测试包未内置媒体工具、cloudflared 或 macOS 在线更新安装器。
+这条构建路径使用本地 ad-hoc 签名,未完成 Developer ID 签名和 Apple 公证,不作为已签名发行包发布。DMG 只分发应用,不安装系统服务;需要集中部署系统组件时再评估 PKG。独立包内含媒体工具与 cloudflared,工具位置与验证见「macOS 独立测试包」;源码开发外壳使用本机环境。macOS 在线更新安装器不包含在本测试包中。
## 首次运行与设置文件
diff --git a/docs/REUSE.md b/docs/REUSE.md
index f4ac12ad7..01f1e1ad0 100644
--- a/docs/REUSE.md
+++ b/docs/REUSE.md
@@ -853,7 +853,7 @@ A 盘垃圾隔离使用短名称 `peach-purge-<32 位 UUID>.peach-quarantine`,
| 人脸取景 | `opencv-python-headless==5.0.0.93`(Apache-2.0)的 `cv2.FaceDetectorYN` + opencv_zoo 定版模型 `face_detection_yunet_2023mar.onnx`(MIT,opencv_zoo 提交 `48b10fa5`,sha256 `8f2383e4…52fa4`,232 KB,随安装包放 `tools/face-models/`,没带时放 `peach-data/tools/yunet/`,不进 Git);MetaTube SDK `6a5e6128c725187aeaf921d48ed7d9cd9f30671b` 的主脸聚类只作算法参考 | 头像/封面离线脚本共用 `peach.face_detect`(主脸、归一化焦点与 sidecar)。`detect` 按长边 320/640/1280 各检一次、分数取中位数;`main_face` 先筛掉分数落后最好那张 0.1 以上的框,再取最大。不用 Haar 级联(OpenCV 5 wheel 里没有、检出率低)与 Pigo v1.4.6(有无脸误报)。[实测](SOURCING.md#人脸与水印实测) |
| 人脸比对 | 同一 OpenCV 的 `cv2.FaceRecognizerSF` + opencv_zoo 定版模型 `face_recognition_sface_2021dec.onnx`(Apache-2.0,同一提交,sha256 `0ba9fbfa…34e79`,与 LFS 指针的 oid 一致,37 MB,随安装包放 `tools/face-models/`,没带时放 `peach-data/tools/sface/`,不进 Git) | `peach.face_match` 提特征、算余弦,阈值用 SFace 官方的 0.363;补头像后继拿图库候选与单人封面截到的脸比(ADR-0056),小脸先放大再检(ADR-0070)。检脸用 `peach.face_detect`,取模型先认随包那份(`bundled_model`,校验 SHA-256,进程内按文件大小与修改时间缓存结论),再走同一条 `fetch_model`;随包文件由 `scripts/fetch_face_models.py` 取齐并附两个目录的 LICENSE,Docker 镜像用 `ADD --checksum` 取同一组文件。不引 `face_recognition`/dlib(要编译、体积大)与 InsightFace(模型限非商用、需 onnxruntime)。[实测](SOURCING.md#人脸与水印实测) |
| 头像水印检出 | 同一 OpenCV 的 `cv2.dnn.TextDetectionModel_DB` + opencv_zoo 定版模型 `text_detection_en_ppocrv3_2023may.onnx`(sha256 `03f550c6…66587`,2.4 MB,放 `peach-data/tools/ppocr/`,不进 Git) | `peach.avatar_watermark` 检出,`scripts/scrub_avatar_watermarks.py` 复核与移除。不用 MSER 自写启发式(抓不到半透明水印)。`MIN_SCORE` 0.9、框宽占图宽 ≥ 4%、框整体落在距边 15% 带内;半透明水印给不出框,所以检出只是候选,人看标注图确认、漏的自己补框。移除优先裁边、不 inpaint。[实测](SOURCING.md#人脸与水印实测) |
-| 正封取景 | 同一 OpenCV 的 `cv2.Sobel` 求列向梯度;NeoAVDC `c7a430c64013c97a0213cd8a57e2ff5696793a86`(MIT)与 sakuramediabe `9c6a31915c9a364c9d6717798575daf9445916bd`(GPL-3.0,只作算法边界参考)的封套几何实测值 | `peach.jav_poster_crop` 给出正封取景框(折痕列到右下角、满高),`scripts/poster_crop_boxes.py` 批量写边车,产物是坐标不是图片。折痕判据见 `peach-jav-cover-workflow`,外部参照、实测与手工框规则见 [取证](SOURCING.md#正封取景实测) |
+| 正封取景 | 同一 OpenCV 的 `cv2.Sobel` 求列向梯度;NeoAVDC `c7a430c64013c97a0213cd8a57e2ff5696793a86`(MIT)与 sakuramediabe `9c6a31915c9a364c9d6717798575daf9445916bd`(GPL-3.0,只作算法边界参考)的封套几何实测值 | `peach.jav_poster_crop` 给出正封取景框(折痕列到右下角、满高),`scripts/poster_crop_boxes.py` 批量写边车,产物是坐标不是图片。折痕判据与边车契约见 [封面取景](COVER_ARTWORK.md),外部参照、实测与手工框规则见 [取证](SOURCING.md#正封取景实测) |
| 115 文件清单 | `p115client==0.0.9.6.5.1`(MIT) | 只在显式 SHA-1 对账脚本中安装,Peach 负责 ledger 事务、备份与写入门槛 |
| 视频出处/片尾证据 | 现有 FFmpeg 抽帧 + Windows.Media.Ocr WinRT Provider(Windows PowerShell 5.1 固定适配器) | 有界首尾采样、缓存、来源/Full version 分类、健康统计与人工复核 |
| 参考产品行为 | 当前线上交互 + 有版本的公开 DOM/CSS/JS;取不到源码时用精确截图测量 | 证据登记、无障碍、Peach 差异、回归检查 |
diff --git a/docs/UI_COMPONENT_CONTRACTS.md b/docs/UI_COMPONENT_CONTRACTS.md
new file mode 100644
index 000000000..4b9264adc
--- /dev/null
+++ b/docs/UI_COMPONENT_CONTRACTS.md
@@ -0,0 +1,85 @@
+# 界面组件契约
+
+本文件维护组件选择与交互约束;执行流程见 [界面技能](../.claude/skills/peach-web-ui/SKILL.md),层级与布局原则见 [设计准则](DESIGN_GUIDELINES.md)。按当前任务读取对应章节。
+
+## 适用组件体系
+
+React 与 BoardUI 的组件、颜色和尺寸采用 [BoardUI 适配](BOARD_UI.md) 与 ADR-0031,保留既定蓝色主动作和原始组件约束。遗留 Geist 的 `--ink`、`--ground`、`--tungsten` 和 DOM class 只约束使用这些词汇的既有控件,不覆盖 BoardUI token。
+
+下表的 Switch、Toggle 和 DOM helper 名称需结合体系理解:BoardUI Switch 是布尔输入,遗留 Switch 是 radio 分段器。修改既有控件复用其实现,不能为满足旧命名规则重写另一体系。涉及数值、媒体比例与取景时,以当前实现及对应测试为准。
+
+## 组件选择
+
+| 需求 | 使用 | 不要使用 |
+| --- | --- | --- |
+| 字段、卡片、分区旁的持久反馈 | Note | Toast、空状态 |
+| 页面/系统级问题与恢复动作 | Banner | Note |
+| 短暂操作回执 | Toast | 持久 Note |
+| 写操作前的确认 | `confirmModal()` | 原生 `confirm()`、Toast |
+| 一个主动作加 1–4 个近亲做法 | Split Button(主动作在左,第一项菜单项与它同名同事) | 把变体摊平成并排按钮、把破坏性动作当主动作 |
+| 一行内的重排 | `wireDragReorder()` 拖动 | 上下移动按钮 |
+| 已知总量的进行状态 | Progress | 装饰性蓝条 |
+| 用户触发动作等待结果 | Spinner | 旋转原操作图标、Loading Dots |
+| 后台任务仍在推进 | Loading Dots | Spinner、假百分比 |
+| 整页或大区块首次等待内容结构 | Skeleton | Spinner、Loading Dots |
+| 2–3 个互斥视图 | 遗留 Switch(radio)或现有分段组件 | Toggle |
+| 布尔开关 | 遗留 Toggle 或 BoardUI Switch | radio 分段器 |
+| 无布局高度变化的菜单 | Menu/Listbox;开合走 `presentMenu`/`dismissMenu`,动效只在 Board 层那一份 | Collapse 动画、自己再写一份 150ms |
+| 带搜索语义的输入 | Search Input(搜索图标前缀;搜索中原位换 Spinner) | 无图标裸输入 |
+| 全屏命令/设置覆盖层 | 有锁定证据的 Dialog motion | 把同一动画套给普通菜单 |
+| 展开正文或分组 | Collapse | 自造 easing |
+| 一组输入/候选及其底部动作 | Fieldset | 自造卡片 Footer |
+| 固定高度区域中的溢出内容 | Scroller | 页面级滚动或嵌套滚动区 |
+| 没有数据或结果 | Empty State(图标、标题、说明同组) | 裸灰字或把说明拆到组件外 |
+| 图标含义与补充说明 | Tooltip | 让浮层撑宽页面 |
+
+## 组件与视觉
+
+- React 页面优先扩展现有 BoardUI 组合件;遗留 DOM 页面复用 `frontend/src/ui-kit/`,不为同一语义复制一次性 class 与模板。
+- 需要全集排序、分页、跨页选择与批量操作的数据表复用 TanStack Table、BoardUI Table、`DataTableFrame` 与 `SelectionDock`;少量静态关系沿用现有简单表格,不强加分页与选择。默认页大小与选择范围以实际页面契约为准。
+- 管理页单面板分区的标题放在面板内,不在框外重复;多卡片分组可用框外标题。同级分区标题用 `text-title-2-medium`,加载态与内容态共用 500 字重、20px 字号和 26px 行高。
+- 控件高度只取 `--control-h-inline`/`-compact`/`--control-h`/`-large` 四档,同一行的同类控件同档;与文字同行的图标用 `--icon-inline`,单独图标按控件档取固定值;下拉不点开也要看得出在选什么(上方标签、触发键前缀或格子选择器的弹层标题三选一)。判据与坏例见 `docs/DESIGN_GUIDELINES.md` 第 2、10、11 节。
+- React 使用 BoardUI 语义 token,遗留样式使用对应 `:root` token;新增 token 须说明现有词汇无法表达的语义。
+- 字重只有 400/500/600 三档,标题按既定层级选择 medium 或 semibold;圆角只用 `--badge-radius`/`--control-radius`/`--surface-radius`/`--floating-radius`/`--pill-radius` 加 `50%` 与 `0`,带边框容器里的头尾条用 `calc(… - 1px)` 保持同心。两者的字面值由 `tests/test_web_ui.py` 拒绝,归属判据见 `:root` 注释。
+- 遗留 Geist 层单色优先:`--tungsten` 只给焦点环、链接、进度/数据与 Toggle 开态。主动作用 `--ink` 底 `--ground` 字且每屏最多一个。标题悬停下划线不变蓝,计数徽章中性灰。其它选择器引用 `--tungsten` 由 `tests/test_web_ui.py` 拒绝;实测见 `vercel-geist-semantics-measured.md`「选中态与开关色」「Button 全变体与状态」。
+- 选中态只有填充:一律 `--hover` 底 `--ink` 字,不加边框、不加 `inset` 一圈线、不加字重(Geist Switch/Tabs 的类名里三样都没有)。填充既然专属选中,**同一排横向**互斥选项的未选中项悬停就只提文字色到 `--ink`;没有选中态的按钮和没有并排邻居的孤立开关悬停照旧抬填充。侧栏导航(`.edge`/`.dnav`)分工相反:实测 Geist 左栏是悬停抬填充、当前项握着文字与图标色,别把横排那条推广过去。清单见同一份快照的「选中态与它的悬停」和「侧栏导航是例外」。
+- 按钮悬停只抬填充:次级到 `color-mix(in srgb,var(--ink) 8%,var(--ground))`(Geist gray-200 那一档,全站同一个值),主动作到 `color-mix(in srgb,var(--ink) 88%,var(--ground))`,边框与文字色都不动。主动作那条悬停规则要自己写上 `color:var(--ground)`,否则同组更宽的通用 hover 里那句 `color:var(--ink)` 无人竞争,浅色实底上落成白字白底。禁用走 `--surface` 底、`--border-15` 边、`--muted` 字,不用 `opacity`;按下不加 `scale`。三条都有 Geist Button 源规则佐证。
+- `outline:0`/`outline:none` 只允许出现在同一规则给出替代焦点样式的地方(`box-shadow` 或子元素 outline),或输入框由带 `:focus-within` 的容器接管焦点时;reduced motion 由全局 `@media (prefers-reduced-motion:reduce)` 统一关闭,不逐处补。
+- 危险动作的悬停态一律 `--drop` 实底加白字。只描红边、红字的话,静止态和悬停态在暗色底上几乎一样亮,按下去之前看不出这是不可逆动作;带文字的销毁按钮全站一个写法,纯图标删除键不适用。Geist 的 error Button 同样是实心红填充,只是它静止态就红。实测见 `vercel-geist-controls-measured.md`。
+- 按钮的前置图标只在图标指向对象(来源站点、当前选中项、平台)或形态方向(触发器右侧的 `chevron-down`)时出现;文字已经把动词说完的不加,`+ 添加`、`↻ 刷新`、`✓ 保存` 这枚多余字形会把同一行主次动作的视觉重量拉平。图标键必须给 `aria-label`,名称点出动作和对象、不描述图标形状。判据与 Geist Button 文档正文见 `docs/reference-snapshots/vercel-geist-button-icons.md`;官方 Geist 图标 SVG 没有可直取的入口,同一份快照记了原因。
+- 同一行里的输入框和按钮共用 `--control-h`,不各写一个像素数:两个控件差 3px 就不是一行了,而差值往往来自窄屏那条防放大规则只抬其中一个。
+- 一枚字形只代表一个意思,同一个意思也只有一枚字形。取字形先问它指的是哪个名词或哪个方向:文件类型取 `file-*`,本地取 `hard-drive`、订阅源取 `rss`,往下接一页取 `chevron-down`,原地换一批取 `shuffle`,`refresh-cw` 只归「去问一遍来源有没有更新」;筛不出结果和一次比对没有发现是两个空态,不能共用一枚。图标语义结合控件的可访问名称与实际操作复核。没有使用者的 symbol 从 `scripts/vendor_web_dependencies.mjs` 的名单和雪碧图里一起删,用户点名留的备用件在名单旁说明用途。
+- 没有直接证据不得新增动效。菜单开合的证据是 boardui `menu-styles.ts`(`docs/BOARD_UI.md`),已落在 board.css 的共用规则里;旧版 Geist 层仍无动画。
+- 界面优先显示读数、当前状态与可执行动作,省略无助于决策的实现细节。费用、估算限制、隐私上传同意与不可逆操作的范围必须保留;单位跟随数字,必要口径放适当帮助入口。
+
+## 等待与回执
+
+- Progress 必须有真实 `value/max`、可见单位与 `aria-valuemin/max/now`;分隔线放在完整指标(含进度条)之后。
+- Spinner 只反馈用户直接触发的动作,触发器统一调用 `setActionBusy()`:写入 `aria-busy=true` 与 `aria-disabled=true`、视觉变灰、拦截重复触发,同时保持可聚焦;请求等待期不得再用原生 `disabled`,它只留给缺输入、无权限等动作确实不可执行的状态。未知时长的后台抓取使用 Loading Dots。整页或大区块首次取数使用 Skeleton 预留最终结构。Spinner/Loading Dots 保留可见状态文字;Skeleton 只保留给辅助技术的状态名,不另画「正在读取」文案。三者都尊重 reduced motion。
+- 用户写操作只在服务端终态成功后调用共享 `actionReceipt()` 发一条过去时 Toast;可由安全逆操作完整恢复的状态提供 8 秒「撤销」,永久删除、凭据、保存到账本等不伪造撤销。仅打开面板/菜单/Dialog 不算操作完成,不发 Toast;失败除短 Toast 外仍在原位置保留原因与重试入口。
+- 同一次页面进入只呈现一段等待态;深链启动与页面取数复用同一个 Skeleton,禁止 Spinner 再切换成 Loading Dots 或 Skeleton。
+- Skeleton 只覆盖真正等待的内容区;静态标题、导航和能同步得到的筛选控件立即显示。骨架必须复用最终容器的宽度、列数与对齐方式:卡片网格横向铺满,居中面板仍居中,不得用一列通用占位替代不同页面结构。
+- 骨架里的占位不接指针、没有任何悬停反馈(`09-skeleton.css` 一处关掉);要等数据才能执行的键用原生 `disabled` 加 `data-skeleton-action`,呈全站共用的禁用面(`--surface` 底、`--border-15` 环、`--muted` 字、not-allowed),不用 opacity,也不伪装成可点的最终档。
+- 分页末尾、空页和「没有更多内容」是中性终止状态,用可关闭 Note;只有需要恢复或处理的故障才能进入红色 error Note。
+- 上一次跑完的结果不常态显示。它是那一刻的快照,进页面就铺开会被读成现在的状态,而页面上没有任何东西说它是旧的;只有仍在进行的任务才自动接管页面。
+- Empty State 的标题和说明必须同处组件内;全页空态与上方工具条统一留 16px,不得再套一层空卡片。
+
+## 表单与浮层
+
+- 遗留 Switch 分段器共享 radio `name`、初始一个 `checked` 并支持键盘;布尔状态使用对应体系的布尔控件,BoardUI Switch 不采用 radio 契约。
+- 菜单每项包含与入口相同的图标和文字,菜单内部滚动、`overscroll-behavior:contain`,不得把浏览器页面撑出滚动条。锚定菜单一律走 `wireAnchoredMenu`:高度压到触发钮那一侧真正剩下的空间(上沿是 `--topH` 顶栏下缘),装不下就在菜单内滚,不横跨触发钮;页面滚动关掉菜单,菜单自身的滚动不关。
+- 只读查询(搜索、筛选)不配提交按钮:回车即执行,忙态落在表单自己身上(`form[aria-busy]` 加前缀原位换 Spinner)。有副作用的提交必须有按钮,且回车同样要能提交。表单里除这个输入框外还有别的字段时浏览器不做隐式提交,回车要自己接管 `requestSubmit()` 并跳过 `isComposing`。判据与实测见 `docs/reference-snapshots/vercel-forms-submit-affordance.md`。
+- 确认弹层一律走 `confirmModal()`:原生 `<dialog>` 承载,标题是陈述句,正文先说后果并点名
+ 涉及的两个值,主按钮是与标题同一动词的「动词+名词」,取消键就写「取消」,成功 Toast 与主
+ 按钮的动词一一对应。写入交给 `onConfirm`,忙态落在主按钮上,失败时弹层不关、原因留在正文
+ 下方等重试。形状与文案判据见 `docs/reference-snapshots/vercel-geist-modal-measured.md`。
+- 下拉框的用途用框内左侧 16px 前缀图标标明,不在同一行挂一个文字标签:Geist 的文字 Label 是块级、排在控件上方,行内并排那种写法它没有,而工具行没有上方空间。无障碍名称改由 `aria-label` 承担。
+- 弹层标题栏与滚动正文分层:标题分隔线属于卡片全宽,滚动条只属于正文。
+- Fieldset 的正文统一 20px 内边距;标题条与底部操作条同为 `--fieldset-bar-h`(52px)、竖直居中、左 20px 右 16px。标题放在框体里,不用原生 `<legend>`:它会在上边框上开缺口,同组卡片内容高度不同时缺口位置也跟着不齐。同组卡片必须同高,变化内容只放一个纵向 Scroller。
+
+## 媒体与页面状态
+
+- 关注来源标签先服从来源记录的类型:只有明确标为 `general` 的标签才能进入卡片、顶部筛选和在线标签页,`artist`/`character`/`copyright`/`metadata` 与未知类型不得靠词形猜成 `general`。通用词清理是第二道门槛,只处理已经确认的 `general`;详情可显示全部来源标签,并按真实类型着色。
+- 播放器控制条的窄屏折叠按播放器自身宽度判定(`ResizeObserver` 观察 `player.el()`),不用媒体查询:同一个视口下影院模式和普通视图的播放器宽度差一大截,用视口判据会在影院模式下白折叠、在普通视图下继续超框。门槛与提示外观见 `youtube-player-controls-user-screenshot.md`。
+- 任何先请求再重绘整页的入口都必须绑定导航代际;只比较 `location.pathname` 不能防住「离开后快速返回同一路径」的旧响应。
+
diff --git a/docs/adr/0015-agent-context-layering.md b/docs/adr/0015-agent-context-layering.md
index 1bec35575..ee1931334 100644
--- a/docs/adr/0015-agent-context-layering.md
+++ b/docs/adr/0015-agent-context-layering.md
@@ -35,7 +35,7 @@
### 预算
-预算、天花板与变更理由由 `scripts/check_context_budget.py` 统一维护,其他文档不复写数值。入口同时检查行数、字节数和单行长度;技能检查正文长度、description、frontmatter 与复核日期。
+预算、天花板与变更理由由 `scripts/check_context_budget.py` 统一维护,其他文档不复写数值。入口同时检查行数、字节数和单行长度;技能同时检查行数、UTF-8 字节数、单行长度、description、frontmatter 与复核日期。规范和算法参考按任务读取,不因移到文档就要求每次完整展开。
预算可以收紧。上调须留下日期和理由,说明内容为何无法按职责下沉,不得越过天花板。写不下时先清退重复内容、下沉流程或移出私有记录。
diff --git a/scripts/check_context_budget.py b/scripts/check_context_budget.py
index 860997530..990f72fd3 100644
--- a/scripts/check_context_budget.py
+++ b/scripts/check_context_budget.py
@@ -52,10 +52,15 @@ LINE_BUDGET = {name: changes[-1][0] for name, changes in BUDGET_CHANGES.items()}
# 字节天花板同样只在官方或项目口径变化时才动。
MAX_EVER_BYTES = {
"AGENTS.md": 16 * 1024,
+ "CLAUDE.md": 2 * 1024,
+ "SKILL.md": 8 * 1024,
}
# 字节预算的变更记录,语义与 BUDGET_CHANGES 完全一致:只能降,上调要写明理由。
BYTE_BUDGET_CHANGES = {
+ "CLAUDE.md": [
+ (2 * 1024, "2026-10-26", "入口仅保留导入与 Claude 专有边界,流程按职责读取技能"),
+ ],
"AGENTS.md": [
(12 * 1024, "2026-09-03", "初始值"),
# 清退腾出来的余量留着不动,等于把位置空出来让散文回填——这个文件就是这么长到
@@ -73,6 +78,8 @@ BYTE_BUDGET = {name: changes[-1][0] for name, changes in BYTE_BUDGET_CHANGES.ite
MAX_LINE_CHARS = 400
SKILL_MAX_LINES = 120
+# 组件规范与算法细节按任务进入参考,正文保留流程与必要边界。
+SKILL_MAX_BYTES = 8 * 1024
DESCRIPTION_MAX_CHARS = 200
REVIEW_MAX_DAYS = 180
@@ -139,6 +146,10 @@ def check_budget_history() -> list[str]:
problems.append(
f"SKILL.md 预算 {SKILL_MAX_LINES} 越过天花板 {MAX_EVER['SKILL.md']}"
)
+ if SKILL_MAX_BYTES > MAX_EVER_BYTES["SKILL.md"]:
+ problems.append(
+ f"SKILL.md 字节预算 {SKILL_MAX_BYTES} 越过天花板 {MAX_EVER_BYTES['SKILL.md']}"
+ )
if DESCRIPTION_MAX_CHARS > MAX_EVER["description"]:
problems.append(
f"description 预算 {DESCRIPTION_MAX_CHARS} 越过天花板 {MAX_EVER['description']}"
@@ -173,12 +184,13 @@ def check_byte_budgets(root: Path) -> list[str]:
def check_line_lengths(root: Path) -> list[str]:
- """入口文件的单行长度按字符数算,不按字节:中文一个字算一个。"""
+ """入口与技能的单行长度按字符数计算,中文一个字算一个。"""
problems: list[str] = []
- for name in BYTE_BUDGET:
- path = root / name
+ paths = [*(root / name for name in BYTE_BUDGET), *_skill_files(root)]
+ for path in paths:
if not path.is_file():
continue
+ name = path.relative_to(root).as_posix()
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
if len(line) > MAX_LINE_CHARS:
problems.append(
@@ -194,6 +206,10 @@ def check_skills(root: Path) -> tuple[list[str], list[tuple[str, datetime.date]]
rel = path.relative_to(root).as_posix()
text = path.read_text(encoding="utf-8")
+ size = len(path.read_bytes())
+ if size > SKILL_MAX_BYTES:
+ problems.append(f"{rel}: {size} 字节,超出技能预算 {SKILL_MAX_BYTES} 字节")
+
count = _count_lines(text)
if count > SKILL_MAX_LINES:
problems.append(f"{rel}: {count} 行,超出技能预算 {SKILL_MAX_LINES} 行")
diff --git a/tests/test_context_budget.py b/tests/test_context_budget.py
index de1dbc85c..8e81fd68a 100644
--- a/tests/test_context_budget.py
+++ b/tests/test_context_budget.py
@@ -49,6 +49,9 @@ class ContextBudgetTests(unittest.TestCase):
)
for name, budget in self.checker.BYTE_BUDGET.items():
self.assertLessEqual(budget, self.checker.MAX_EVER_BYTES[name], name)
+ self.assertLessEqual(
+ self.checker.SKILL_MAX_BYTES, self.checker.MAX_EVER_BYTES["SKILL.md"]
+ )
def test_raising_a_budget_without_a_reason_is_reported(self):
original = dict(self.checker.BUDGET_CHANGES)
@@ -167,6 +170,46 @@ class ContextBudgetTests(unittest.TestCase):
problems, _ = self.checker.check_skills(root)
self.assertTrue(any("description" in problem for problem in problems), problems)
+ def test_skill_utf8_bytes_are_checked_within_the_line_limit(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp).resolve()
+ skill_dir = root / ".claude" / "skills" / "sized"
+ skill_dir.mkdir(parents=True)
+ header = SKILL_TEMPLATE.format(
+ name="sized", description="描述", reviewed="2026-10-26"
+ )
+ limit = self.checker.SKILL_MAX_BYTES
+ row = "字" * 100 + "\n"
+ rows = (limit - len(header.encode("utf-8"))) // len(row.encode("utf-8"))
+ within = header + row * rows
+ path = skill_dir / "SKILL.md"
+ path.write_text(within, encoding="utf-8", newline="\n")
+ self.assertLess(len(within.splitlines()), self.checker.SKILL_MAX_LINES)
+ problems, _ = self.checker.check_skills(root)
+ self.assertEqual(problems, [])
+ path.write_text(within + row, encoding="utf-8", newline="\n")
+ problems, _ = self.checker.check_skills(root)
+ self.assertEqual(len(problems), 1, problems)
+ self.assertIn("字节", problems[0])
+ self.assertEqual(self.checker.check_line_lengths(root), [])
+
+ def test_skill_line_length_is_checked_independently_of_total_bytes(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp).resolve()
+ skill_dir = root / ".claude" / "skills" / "line"
+ skill_dir.mkdir(parents=True)
+ text = SKILL_TEMPLATE.format(
+ name="line", description="描述", reviewed="2026-10-26"
+ )
+ path = skill_dir / "SKILL.md"
+ path.write_text(text + "字" * self.checker.MAX_LINE_CHARS, encoding="utf-8")
+ self.assertEqual(self.checker.check_line_lengths(root), [])
+ path.write_text(text + "字" * (self.checker.MAX_LINE_CHARS + 1), encoding="utf-8")
+ self.assertLess(path.stat().st_size, self.checker.SKILL_MAX_BYTES)
+ problems = self.checker.check_line_lengths(root)
+ self.assertEqual(len(problems), 1, problems)
+ self.assertIn(".claude/skills/line/SKILL.md", problems[0])
+
def test_index_and_files_must_match(self):
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)