Skip to content

armgit / peach

Public Imported from GitHub
0

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.md
index 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.yml
index 41ccbe9b5..57e0212d4 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -150,29 +150,28 @@ jobs:
with:
enable-cache: true
cache-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_tools
with:
node-version: "24"
cache: npm
cache-dependency-path: frontend/package-lock.json
- name: 安装前端依赖
- if: matrix.scope != 'core'
+ if: matrix.runtime_tools
run: npm --prefix frontend ci
# 抽帧与 AV1 软件解码回归在两端执行;浏览器冒烟的 Chrome 仅在 Windows 装配。
- name: 安装固定版本 FFmpeg
uses: FedericoCarboni/setup-ffmpeg@v3
- if: runner.os == 'Windows' && matrix.scope != 'core'
+ if: runner.os == 'Windows' && matrix.runtime_tools
with:
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_tools
run: brew install ffmpeg
- name: 指定 e2e 用的 Chrome
- if: runner.os == 'Windows' && matrix.scope != 'core'
+ if: runner.os == 'Windows' && matrix.runtime_tools
shell: pwsh
run: |
$peachChrome = Join-Path $env:ProgramFiles 'Google\Chrome\Application\chrome.exe'
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 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.py
index 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.py
index 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 runner
scopes, _ = 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 1
for 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.py
index 64f5644c3..37744cf05 100644
--- a/tests/test_agent_worktree.py
+++ b/tests/test_agent_worktree.py
@@ -5,7 +5,10 @@ import sys
import tempfile
import time
import unittest
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
from pathlib import Path
+from threading import Event
from unittest import mock
from 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.py
index 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'),