Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(agent): 将测试登记与交付复盘融入技能步骤

longmeidaoe86d83105a5c
diff --git a/.claude/skills/peach-web-ui/SKILL.md b/.claude/skills/peach-web-ui/SKILL.md
index 70da6bab6..e8df278bb 100644
--- a/.claude/skills/peach-web-ui/SKILL.md
+++ b/.claude/skills/peach-web-ui/SKILL.md
@@ -5,8 +5,8 @@ description: 在新增、修改或复核 Peach 页面、控件、提示、错误
# Peach Web UI 复用门槛
-最后复核:2026-10-20
-证据来源:现有 UI 契约、`docs/TESTING.md`、2026-09-19 本机会话工具记录、jakubkrehel/skills 与 emilkowalski/skills 摘录、`docs/reference-snapshots/open-claude-ui.md`、2026-10-20 用户要求明确确认预览后才能测试。
+最后复核:2026-10-21
+证据来源:现有 UI 契约、`docs/TESTING.md`、本机重复文案与异步轮询回归记录、jakubkrehel/skills 与 emilkowalski/skills 摘录、`docs/reference-snapshots/open-claude-ui.md`、用户明确确认预览后才能测试的约定。
## 开工顺序
@@ -84,7 +84,8 @@ description: 在新增、修改或复核 Peach 页面、控件、提示、错误
## 验收门槛
-- 界面改动先构建并保留可访问的预览,提供地址;只有用户明确确认当前预览后才能运行测试。发出地址、用户继续纠正和等待超时都不算确认;收到新纠正时停止本任务运行中及排队的测试,修好后重新等待确认。确认前只做实现、预览构建与视觉查看;用户明确只要图片时才仅提供截图。
+- 预览前核对标题、说明、持久提示与操作回执的职责,同一事实只在承担该职责的位置说明;检查加载、空态、错误和完成态,避免重复说明与残余内容。
+- 界面改动先构建并保留可访问的预览,提供地址;只有用户明确确认当前预览后才能运行测试,确认绑定该预览与范围,范围内沿用。发出地址、用户继续纠正和等待超时都不算确认;收到界面新纠正时停止本任务运行中及排队的测试,修好后重新等待确认。确认前只做实现、预览构建与视觉查看;用户明确只要图片时才仅提供截图。
- UI 标签、身份、反馈状态和搜索推荐属于语义契约:按实际影响验证数据层、组件或浏览器行为。
推荐词上线前对真实 `/api/items` 验证至少一个命中,说明性后缀不得
混入搜索词(坏例 `ABW 番号`,好例 `ABW`)。
@@ -93,7 +94,7 @@ description: 在新增、修改或复核 Peach 页面、控件、提示、错误
相关分片通过且代码不再变化后运行一次 `auto`;它选择 `full` 时,不为每次局部修复重复全量测试。
环境或资源失败先修环境并重跑失败域,最后只保留一次覆盖最终代码的有效 `auto`/`full` 记录。
-1. 先确认失败模式与现有覆盖,再选择组件、API/数据层或浏览器测试。纯文案、等价重构不补源码文本断言;通用规范由 lint 或集中扫描检查,具体分工见 `docs/TESTING.md`。
+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`;
diff --git a/.claude/skills/peach-worktree/SKILL.md b/.claude/skills/peach-worktree/SKILL.md
index 8c5e8ceb2..14812d2d5 100644
--- a/.claude/skills/peach-worktree/SKILL.md
+++ b/.claude/skills/peach-worktree/SKILL.md
@@ -5,8 +5,8 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
# 并行 worktree 与提交边界
-最后复核:2026-10-20
-证据来源:[开发约定](../../../AGENTS.md)、`README.md`、ADR-0015、ADR-0017、本机工作树与沙箱工具记录、用户于 2026-10-20 确认的进度播报成本与汇报约定。
+最后复核:2026-10-21
+证据来源:[开发约定](../../../AGENTS.md)、`README.md`、ADR-0015、ADR-0017、本机工作树与沙箱工具记录、测试域登记失败与交付中断复盘。
## 是否委派与何时使用
单一功能域、局部改动或预计 30 分钟内完成的任务,由协调者在自己的隔离工作树直接完成;只有任务可独立并行、需要隔离环境,或长跑过程能明确缩短总耗时才委派。
@@ -21,7 +21,7 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
从第一次调用就按 `peach-shell-commands` 的沙箱规则使用受控提权;它们会写主检出的
Git common directory,工作树目录可写不代表 `.git/worktrees/**` 可写。
-2. 工作者只在自己的工作树内编辑。`create` 自动锁定工作树,成功集成后解锁;不复制 `.venv`;用 `uv sync --locked --all-extras` 创建自己的测试环境。
+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。
@@ -29,12 +29,12 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
安装依赖和构建完成后再验证;测试期间不改变环境。主检出与隔离工作树均默认自动选测。例行进度播报与频繁日志轮询会消耗 token;测试期间静默等待,完成或确需用户处理的阻塞时统一汇报,用户追问时再提供进度。
PowerShell 读 UTF-8 日志显式加 `-Encoding utf8`;编码在输出端固定,不能只给读取端指定编码。
记录绑定完整代码内容、依赖环境和范围,24 小时有效;失败撤销对应范围,运行中改动只保留未受影响的完整批次文件结果。
+ 新增或改名测试时,先核对域清单或既有文件名模式,并用正式入口定向运行 `test_scripts.OperationalScriptTests.test_every_test_file_is_registered_in_a_scope` 检查登记;测试文件存在不代表 `auto` 会选中。
用 `-Focus` / `--focus` 先验证相关 Python 或浏览器用例,调试不签记录;冻结改动后只运行一次 `auto`,不另写逐域循环。失败先定向修复,再让 `auto` 复用未受影响的记录,详见 `docs/TESTING.md`。
- 同环境基线按有效内容差异补测;纯注释选 checks。完整批次补齐缺少文件后恢复全量,局部批次不能拼成全量;共享逻辑或未知文件仍跑全量。
- 差异补测不延长全量基线有效期;版本号行单独变化归 tooling,包内其他逻辑变化仍按源码判断。
+ 同环境基线按有效内容差异补测,补测不延长基线有效期;纯注释选 checks,版本号行单独变化归 tooling,包内其他逻辑仍按源码判断。完整批次补齐缺少文件后恢复全量,局部批次不能拼成全量;共享逻辑或未知文件仍跑全量。
相同状态复用记录;Windows `-Fresh`、POSIX 第二参数 `--fresh` 强制重跑;显式 `full` 总是实际执行。
4. `ready` 前将当前 `master` 纳入工作树并运行 `auto`。相同内容可复用记录;目标变化重算影响域。`ready` / `integrate` 拒绝缺记录、范围不足或目标分支未纳入的提交。
-5. 协调者统一运行 `integrate`:锁内复查、合并固定提交。取得成功退出状态并核对主线提交后才重启;锁忙交给入口等待,禁止直接 merge;提示带持锁方的 pid、开始时间与范围,不反复数进程。运行记录写到仓库外的私有上下文;工作者按文件分工,共享文件安排顺序。
+5. 协调者接到工作者的 `ready` 后继续完成授权范围内的 `integrate`、适用重启与运行核验;分支交接不等于任务验收完成。`integrate` 在锁内复查并合并固定提交;取得成功退出状态并核对主线提交后才重启。锁忙交给入口等待,禁止直接 merge;提示带持锁方的 pid、开始时间与范围,不反复数进程。运行记录写到仓库外的私有上下文;工作者按文件分工,共享文件安排顺序。
版本号不在这里动,`integrate` 只报当前值:推进与打标签都走 `scripts/release_tag.py`,
它是唯一入口。`--bump auto --apply` 推版本、定版变更日志并把那一节带在输出里给人确认,
落盘前自动检查上游、依赖与非 manual 参考来源;审阅 `build/release-review.json`,采用范围见 `docs/TESTING.md`。