Skip to content

armgit / peach

Public Imported from GitHub
0

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

docs(skills): peach-worktree 清退重复条目并补多分支一起合入

longmeidao1f96bf7fdc53
diff --git a/.claude/skills/peach-worktree/SKILL.md b/.claude/skills/peach-worktree/SKILL.md
index 14812d2d5..551399468 100644
--- a/.claude/skills/peach-worktree/SKILL.md
+++ b/.claude/skills/peach-worktree/SKILL.md
@@ -5,8 +5,8 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
# 并行 worktree 与提交边界
-最后复核:2026-10-21
-证据来源:[开发约定](../../../AGENTS.md)、`README.md`、ADR-0015、ADR-0017、本机工作树与沙箱工具记录、测试域登记失败与交付中断复盘。
+最后复核:2026-10-23
+证据来源:[开发约定](../../../AGENTS.md)、`README.md`、ADR-0015、ADR-0017、本机工作树与沙箱工具记录、测试域登记失败与交付中断复盘、2026-10-22 多分支集成复盘。
## 是否委派与何时使用
单一功能域、局部改动或预计 30 分钟内完成的任务,由协调者在自己的隔离工作树直接完成;只有任务可独立并行、需要隔离环境,或长跑过程能明确缩短总耗时才委派。
@@ -26,48 +26,33 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
两者契约相同:优先当前树 venv,缺失时从 Git common directory 定位主项目 venv,强制 `PYTHONPATH=<当前工作树>/src`,
核对 `peach.__file__` 后运行标准库 `unittest`。禁止手工拼接 venv 路径或调用 pytest。
测试入口固定 `PYTHONIOENCODING=utf-8`,覆盖标准输出、错误输出及子进程;其他 Python CLI 使用 `-X utf8`。
- 安装依赖和构建完成后再验证;测试期间不改变环境。主检出与隔离工作树均默认自动选测。例行进度播报与频繁日志轮询会消耗 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,包内其他逻辑仍按源码判断。完整批次补齐缺少文件后恢复全量,局部批次不能拼成全量;共享逻辑或未知文件仍跑全量。
- 相同状态复用记录;Windows `-Fresh`、POSIX 第二参数 `--fresh` 强制重跑;显式 `full` 总是实际执行。
+ 安装依赖和构建完成后再验证;测试期间不改变环境。测试期间静默等待,完成或确需用户处理的阻塞时统一汇报。
+ 新增或改名测试时,用正式入口定向运行 `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、开始时间与范围,不反复数进程。运行记录写到仓库外的私有上下文;工作者按文件分工,共享文件安排顺序。
- 版本号不在这里动,`integrate` 只报当前值:推进与打标签都走 `scripts/release_tag.py`,
- 它是唯一入口。`--bump auto --apply` 推版本、定版变更日志并把那一节带在输出里给人确认,
- 落盘前自动检查上游、依赖与非 manual 参考来源;审阅 `build/release-review.json`,采用范围见 `docs/TESTING.md`。
- 确认后 `--ship --apply` 一次做完提交、推送、等 Test 转绿、打标签(ADR-0012 修订)。
- 人只判断措辞,不记流程;停在半路就再跑一次同一条命令。
- 「该发一版了」由 `release_due.py` 的 Stop 钩子一家说,收尾那段不要跟着说第二遍:
- `integrate` 输出里的 `release`(`changelog.due()`)与它同一个判据,而钩子按 master 的 sha
- 闩住、集成后的干净主检出正好满足它那四道闸,两边都说就是一屏里两条一样的话。判据是
- 每周一次、攒够提前、破坏性变化与安全修复不等周期,只数使用者看得见的条目。
- CI 分片、系统覆盖与发布复用见 `docs/TESTING.md`;合并完成不机械追加全量。耗时和慢测试记录在主目录 `build/agent-verification/`。
- 主检出 master 上的直接提交与手工 merge 由 `scripts/githooks/` 拒收,`core.hooksPath`
- 由 `create` / `integrate` 自动指过去;只有 `integrate` 与 `release_tag.py` 带放行标记。
- 记录、锁和 hook 约束统一入口,不是权限隔离;`--no-verify`、快进合并或篡改记录仍可绕过,
- 不能宣称绝对防绕过。
+ 版本号不在这里动:推进与打标签只走 `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` 等仍可绕过。
+
+## 多分支一起合入
+两条以上分支同时待合时,由一个协调会话统一测试与合入:先让各会话停掉自己的 `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): 中文描述`,如 `fix(web): 补齐图标声明与兜底路径`。
- 类型的封闭清单在 `scripts/commit_subject.py` 的 `TYPES`;`feat` / `fix` / `perf` 会进变更日志,
- scope 被 `scripts/changelog.py` 换成区域标签,所以写歪的后果是日志静默漏条,不是报错。
- `ready` / `integrate` 拒收形状不对、类型不在清单的主题;从 master 合进来的 merge 不算。
-
-- 提交前核对 README 影响;交付分支最后提交加 `README-Impact: updated; 说明` 或 `README-Impact: none; 原因`。
- 只改一份 README 时另加 `README-Reviewed: 未改文件名; 无需修改的原因`,保留双语核对。
- 它与 `Co-Authored-By` 等 trailer 连续写在消息末尾同一块里,中间隔一个空行就只算正文,解析不到。
- `commit-msg` 检查署名与已有声明格式;`ready/integrate` 核对交付差异,细节见 `docs/README_MAINTENANCE.md`。
-
-- 分支上每个提交都要署名,形态是 `Co-Authored-By: 工具 (模型 版本) <厂商 noreply>`:
- `Claude Code (Opus 5) <[email protected]>`、`Codex (GPT-5.5) <[email protected]>`。
- 括号里那一段是重点:事后翻这一行是要知道哪个模型写的,同一个工具换代模型,写出来的
- 代码差别比换工具本身还大。工具与地址的名单在 `scripts/co_author.py` 的 `VENDORS`,
- `ready` / `integrate` 逐个提交判,拒收缺失、形态不对、工具未登记和地址与工具不配四种;
- 合进来的 merge 与已在 `origin/master` 上的提交(网页上直接改的那种,签不了名)不算。
- 智能体接力写成时并列署名;人类共同作者使用「姓名 <邮箱>」,与智能体署名同块保留。
+- 每个提交主题写成 `type(scope): 中文描述`,类型清单在 `scripts/commit_subject.py` 的 `TYPES`;写歪的后果是变更日志静默漏条,`ready` / `integrate` 拒收。
+
+- 交付分支最后提交加 `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` 逐个提交判;接力写成时并列署名,人类共同作者写「姓名 <邮箱>」。
- 禁止 `git add .`、`git add -A`、目录路径或 glob。只暂存任务明确拥有的文件。
- 提交前用 `git diff --cached --name-status` 与任务边界逐条对照。干净的 `git status`
@@ -81,15 +66,10 @@ description: 在用户说并行、工作树、暂存、提交、ready、集成
## 已知陷阱
-- **工作树会惄无声息地失效,目录却还在**。2026-08-26 实例:分支被集成后,
- `.claude/worktrees/<task>` 的注册消失,目录变成主检出里一份旧副本。提示符和文件列表看不出
- 任何差别,但在里面跑的每一条 git 都作用于主检出的 master。后果不是报错而是假结论:
- 那一轮里智能体一直报告「还没推」,实际上提交已经被另一个智能体的 push 顺带到了 origin。
- 判据不看目录名,只看 `git rev-parse --show-toplevel`;等于 `peach-app` 就是在主检出里。
- 实测入口:`git worktree list` 里没有你那一行,就是已经没了。
-- Windows 源码改动生效时,禁止用 Computer Use 操作系统托盘。只用与托盘「重启服务」等价的项目命令;入口必须让现有托盘执行重启,或完整重启托盘并重新取得子服务所有权。直接强杀/另启 `.venv\Scripts\peach.exe` 会让 `_owned` 失真,不算等价;仓库缺少安全命令时先补入口,不能退回托盘 UI。
-- 工作者报 `ready` 前必须 rebase 到当前 `master`。落后十天的分支不要指望协调者去 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` 时只移植仍需要的独有改动:共享文件上旧的那一侧解错冲突,会把已上线的修复回退掉。
## 回收与顶层归置