Peach: Local-first video metadata scraper and media manager.
fix(ci): 对齐文档选测与集成锁边界
longmeidaoc50fba2cb07b
diff --git a/.claude/skills/peach-shell-commands/SKILL.md b/.claude/skills/peach-shell-commands/SKILL.mdindex 795cff964..125d7f06e 100644--- a/.claude/skills/peach-shell-commands/SKILL.md+++ b/.claude/skills/peach-shell-commands/SKILL.md@@ -5,8 +5,8 @@ description: 编写 Peach shell 命令、多行内容,处理路径、编码或# Peach 命令与路径-最后复核:2026-10-26-证据来源:命令故障记录、正式测试入口、临时目录别名与 Windows 权限边界。+最后复核:2026-10-28+证据来源:命令故障记录、迁回流程中的原生命令失败掩盖与输出截断、正式测试入口和 Windows 权限边界。## 执行前@@ -14,6 +14,8 @@ description: 编写 Peach shell 命令、多行内容,处理路径、编码或- 用户终端目录不确定时,项目 venv 与脚本写绝对路径或先进入已核实的项目目录。不要把自己的 shell 写法直接交给用户。- 参数查当前入口,不凭记忆:集成需要 `integrate --branch`,手动迁移使用 `migrate upgrade --yes`。备份文件名含时间戳,重跑不覆盖已生成备份。- `rg` 路径参数不含通配符,筛文件用 `-g`;退出码 1 表示无匹配。Python CLI 加 `-X utf8`,PowerShell 读取 UTF-8 文本加 `-Encoding utf8`。+- PowerShell 复合命令同时启用 `$ErrorActionPreference='Stop'` 与 `$PSNativeCommandUseErrorActionPreference=$true`;`rg` 无匹配和 Git 祖先判断等布尔退出码单独解释,不让后续成功掩盖前一步失败。+- 长任务先保存完整工具响应和会话标识,再输出摘要;每次日志读取限于当前阶段。启动回执不作成功证明,依赖结果时取得最终退出码并核对产物;项目测试仍直接走正式入口。## 文件与转义diff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex 41ccbe9b5..57e0212d4 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -150,29 +150,28 @@ jobs:with:enable-cache: truecache-dependency-glob: uv.lock- # `web` 与 `packaging` 域里的 tsc、lint、vitest 和浏览器冒烟在 CI 缺前置条件时判失败- # (`tests/support/conditions.py`)。`core` 不含这些用例,其余域都要装齐。+ # checks 只验收文档与仓库契约;运行时域保留完整工具,未知输入使用全量。- uses: actions/setup-node@v7- if: matrix.scope != 'core'+ if: matrix.runtime_toolswith:node-version: "24"cache: npmcache-dependency-path: frontend/package-lock.json- name: 安装前端依赖- if: matrix.scope != 'core'+ if: matrix.runtime_toolsrun: npm --prefix frontend ci# 抽帧与 AV1 软件解码回归在两端执行;浏览器冒烟的 Chrome 仅在 Windows 装配。- name: 安装固定版本 FFmpeguses: FedericoCarboni/setup-ffmpeg@v3- if: runner.os == 'Windows' && matrix.scope != 'core'+ if: runner.os == 'Windows' && matrix.runtime_toolswith:ffmpeg-version: "9.0.1"github-token: ${{ github.token }}- name: 安装 macOS FFmpeg- if: runner.os == 'macOS' && matrix.scope != 'core'+ if: runner.os == 'macOS' && matrix.runtime_toolsrun: brew install ffmpeg- name: 指定 e2e 用的 Chrome- if: runner.os == 'Windows' && matrix.scope != 'core'+ if: runner.os == 'Windows' && matrix.runtime_toolsshell: pwshrun: |$peachChrome = Join-Path $env:ProgramFiles 'Google\Chrome\Application\chrome.exe'diff --git a/docs/TESTING.md b/docs/TESTING.mdindex 5137967be..c458cdcae 100644--- a/docs/TESTING.md+++ b/docs/TESTING.md@@ -8,6 +8,8 @@ Release 工作流还在干净的 Windows runner 上运行 `smoke_update_tasks.py## 环境与锁文件+纯文档 CI 仍在 Windows 和 macOS 执行 checks,但不安装前端依赖、FFmpeg 或配置 Chrome;混合运行时改动与未知输入保留完整工具。集成按同一选测边界识别文档,显式映射到运行时验收的 Markdown 不豁免全量锁。代码集成先等待全量锁,再取得集成锁,避免等待中的代码任务阻挡文档交付。+依赖由 uv 按锁文件精确复现。源码安装用 `uv sync --locked`。开发、测试和构建在隔离工作树里建自己的 `.venv`,工作树不碰正在服务的环境;主检出的依赖同步与迁移由重启流程负责,见 [运行与配置](OPERATIONS.md) 的「刷新源码运行态」一节(ADR-0091)。安装全部测试依赖(先完成前端依赖安装和构建,再开始正式验证):diff --git a/scripts/agent_worktree.py b/scripts/agent_worktree.pyindex 6519cb0f0..69b0e56cb 100644--- a/scripts/agent_worktree.py+++ b/scripts/agent_worktree.py@@ -152,17 +152,15 @@ def integrate(repo: Path, worker_branch: str, target_branch: str = "master", *,folder = test_evidence.evidence_dir(repo)folder.mkdir(parents=True, exist_ok=True)try:- with test_evidence.held(folder / "integration.lock",- branch=worker_branch, root=str(repo)):- base = _git(repo, "merge-base", target_branch, worker_branch).stdout.strip()- files = _lines(_git(repo, "diff", "--name-only", f"{base}..{worker_branch}"))- documents = bool(files) and all(- path in {"README.md", "README.zh-CN.md"}- or path.startswith("docs/") and path.endswith(".md") for path in files)- guard = nullcontext() if documents else test_evidence.held(- folder / "full-suite.lock", wait_seconds=lock_timeout,- scope="integrate", branch=worker_branch, root=str(repo))- with guard:+ documents = _documents_only(repo, worker_branch, target_branch)+ guard = nullcontext() if documents else test_evidence.held(+ folder / "full-suite.lock", wait_seconds=lock_timeout,+ scope="integrate", branch=worker_branch, root=str(repo))+ with guard:+ with test_evidence.held(folder / "integration.lock",+ branch=worker_branch, root=str(repo)):+ if documents and not _documents_only(repo, worker_branch, target_branch):+ raise WorkspaceError("等待集成期间分支影响面改变;本次未修改分支,请重试")return _integrate_locked(repo, worker_branch, target_branch)except test_evidence.Timeout as error:raise WorkspaceError(@@ -170,6 +168,15 @@ def integrate(repo: Path, worker_branch: str, target_branch: str = "master", *,"本次未修改分支,请等待后重试") from error+def _documents_only(repo: Path, worker_branch: str, target_branch: str) -> bool:+ """文档沿用选测的显式覆盖;需要运行时验收的 Markdown 仍取得全量锁。"""+ from . import change_impact+ base = _git(repo, "merge-base", target_branch, worker_branch).stdout.strip()+ files = _lines(_git(repo, "diff", "--name-only", f"{base}..{worker_branch}"))+ return bool(files) and all(change_impact.documentation(path) for path in files) \+ and test_runner.scopes_for_changes(files)[0] == ("checks",)++def _integrate_locked(repo: Path, worker_branch: str,target_branch: str = "master") -> dict[str, object]:"""把工作者分支并进 target。diff --git a/scripts/ci_plan.py b/scripts/ci_plan.pyindex c14993376..923ae9a71 100644--- a/scripts/ci_plan.py+++ b/scripts/ci_plan.py@@ -73,6 +73,7 @@ def plan(event: str, paths: list[str], contents: dict | None = None) -> dict:from . import test_runner as runnerscopes, _ = runner.scopes_for_changes(paths, contents=contents)wide = event == "workflow_dispatch" or "full" in scopes+ runtime_tools = wide or scopes != ("checks",)rows = []for system in ("macos-latest", "windows-latest"):scope = "full" if wide else "auto"@@ -80,6 +81,7 @@ def plan(event: str, paths: list[str], contents: dict | None = None) -> dict:shards = (4 if system == "windows-latest" else 2) if scope == "full" else 1for index in range(shards):rows.append({"os": system, "python": "3.14", "scope": scope,+ "runtime_tools": runtime_tools,"shard_index": index, "shard_count": shards})wheels = [{"os": "windows-latest", "python": "3.14"},{"os": "macos-latest", "python": "3.14"}]diff --git a/tests/test_agent_worktree.py b/tests/test_agent_worktree.pyindex 64f5644c3..37744cf05 100644--- a/tests/test_agent_worktree.py+++ b/tests/test_agent_worktree.py@@ -5,7 +5,10 @@ import sysimport tempfileimport timeimport unittest+from concurrent.futures import ThreadPoolExecutor+from contextlib import contextmanagerfrom pathlib import Path+from threading import Eventfrom unittest import mockfrom scripts import agent_worktree, release_tag@@ -104,6 +107,65 @@ class AgentWorktreeTests(_WorktreeCase):agent_worktree.require_verified.assert_called_once_with(worker, "master", {"README.md"})self.assertEqual((self.repo / "README.md").read_text(encoding="utf-8"), "# Example\n")+ def test_other_document_paths_use_the_same_checks_boundary(self):+ for index, name in enumerate(("CONTRIBUTING.md", ".github/PULL_REQUEST_TEMPLATE.md")):+ with self.subTest(path=name):+ result = create(self.repo, "Codex", f"document-{index}", self.root / "worktrees")+ worker = Path(result["path"])+ (worker / name).parent.mkdir(parents=True, exist_ok=True)+ (worker / name).write_text("# Example\n", encoding="utf-8")+ _git(worker, "add", name)+ _git(worker, "commit", "-m", "docs: example")+ folder = agent_worktree.test_evidence.evidence_dir(self.repo)+ with agent_worktree.test_evidence.held(folder / "full-suite.lock", scope="full"):+ report = integrate(self.repo, str(result["branch"]), lock_timeout=0)+ self.assertEqual(report["files"], [name])++ def test_runtime_markdown_still_waits_for_full_suite(self):+ result = create(self.repo, "Codex", "runtime-document", self.root / "worktrees")+ worker = Path(result["path"])+ name = "frontend/src/react/boardui/ORIGIN.md"+ (worker / name).parent.mkdir(parents=True)+ (worker / name).write_text("# Origin\n", encoding="utf-8")+ _git(worker, "add", name)+ _git(worker, "commit", "-m", "docs: origin")+ folder = agent_worktree.test_evidence.evidence_dir(self.repo)+ with agent_worktree.test_evidence.held(folder / "full-suite.lock", scope="full"), \+ self.assertRaisesRegex(WorkspaceError, "全量验证"):+ integrate(self.repo, str(result["branch"]), lock_timeout=0)+ self.assertFalse((self.repo / name).exists())++ def test_waiting_code_integration_does_not_block_documents(self):+ code = create(self.repo, "Codex", "queued-code", self.root / "worktrees")+ worker = Path(code["path"])+ (worker / "worker.txt").write_text("code\n", encoding="utf-8")+ commit(worker, "worker change")+ docs = create(self.repo, "Codex", "parallel-docs", self.root / "worktrees")+ (Path(docs["path"]) / "README.md").write_text("# Example\n", encoding="utf-8")+ _git(Path(docs["path"]), "add", "README.md")+ _git(Path(docs["path"]), "commit", "-m", "docs: example")+ folder = agent_worktree.test_evidence.evidence_dir(self.repo)+ waiting = Event()+ held = agent_worktree.test_evidence.held++ @contextmanager+ def observed(lock, **kwargs):+ if kwargs.get("branch") == code["branch"] and lock.name == "full-suite.lock":+ waiting.set()+ with held(lock, **kwargs):+ yield++ with ThreadPoolExecutor() as executor, mock.patch.object(+ agent_worktree.test_evidence, "held", observed):+ with held(folder / "full-suite.lock", scope="full"):+ future = executor.submit(integrate, self.repo, str(code["branch"]), lock_timeout=120)+ self.assertTrue(waiting.wait(5), "代码集成尚未进入全量锁等待")+ report = integrate(self.repo, str(docs["branch"]), lock_timeout=0)+ self.assertEqual(report["files"], ["README.md"])+ self.assertFalse(future.done())+ self.assertEqual(future.result(timeout=60)["files"], ["worker.txt"])+ self.assertEqual((self.repo / "worker.txt").read_text(encoding="utf-8"), "code\n")+def test_code_integration_waits_for_full_suite_without_changing_master(self):result = create(self.repo, "Codex", "code", self.root / "worktrees")worker = Path(result["path"])diff --git a/tests/test_test_planning.py b/tests/test_test_planning.pyindex 65efc8302..f3afc225f 100644--- a/tests/test_test_planning.py+++ b/tests/test_test_planning.py@@ -97,6 +97,21 @@ class CIFrontendOwnershipTests(unittest.TestCase):class TestPlanningTests(unittest.TestCase):+ def test_checks_ci_omits_runtime_tool_installation_and_keeps_platforms(self):+ for path in ("README.md", "CONTRIBUTING.md", ".github/PULL_REQUEST_TEMPLATE.md", "docs/TESTING.md"):+ with self.subTest(path=path):+ result = ci_plan.plan("push", [path])+ rows = result["matrix"]["include"]+ self.assertEqual({row["os"] for row in rows}, {"windows-latest", "macos-latest"})+ self.assertTrue(all(not row["runtime_tools"] for row in rows))+ self.assertIn("python", result["required_jobs"])+ self.assertFalse(result["browser"])+ for event, paths in (("workflow_dispatch", ["README.md"]),+ ("push", ["README.md", "src/peach/server.py"]),+ ("push", ["frontend/src/react/boardui/ORIGIN.md"]),+ ("push", ["unknown.runtime"])):+ self.assertTrue(all(row["runtime_tools"] for row in ci_plan.plan(event, paths)["matrix"]["include"]))+def test_comments_and_display_metadata_select_checks_without_hiding_logic(self):fixtures = {'tests/support/ledger.py': ('x = 1\n', '# 说明\nx = 1\n'),