Peach: Local-first video metadata scraper and media manager.
fix(tray): 兼容允许脱离的桌面 Job 并验收独立性
longmeidao3a8f29bc9113
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.mdindex c32bab2ec..2af8348f6 100644--- a/docs/OPERATIONS.md+++ b/docs/OPERATIONS.md@@ -372,6 +372,8 @@ curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' https://peach.local/healtWindows 托盘独立于启动它的终端和智能体运行。启动、重启与异常恢复由当前会话的 Windows 桌面进程承接父身份;关闭 Codex、Claude 或终端不会停止托盘。直接从 Job 中运行托盘入口时,托盘在取得单实例锁和启动子服务前完成交接。数据根、源码路径和启动参数保持一致;未取得桌面进程或独立启动失败时明确报错,不在启动器的 Job 中继续运行。+桌面进程可以处于允许脱离的 Job 中。托盘先挂起创建子进程,确认已脱离 Job 后才执行代码;仍继承 Job 时,回收这次子进程并显式请求脱离一次。若 Windows 拒绝请求,启动报告保留 `CreateProcessW(breakaway)` 与系统错误码;子进程不执行托盘代码,不创建服务或重复交接。+Windows 托盘在取得单实例锁后启动独立监视器。监视器用 Win32 进程句柄等待托盘退出,核对进程创建时间,避免 PID 复用;意外退出(包括未登记退出意图的零退出码)按 2、5、10 秒延迟恢复,5 分钟内至多 3 次。恢复保持当前数据根和源码入口,以静默模式启动。新托盘的监视器就绪后完成交接;导入或启动失败计入同一重试预算。手动启动的新实例会取消旧实例尚未执行的恢复。达到上限后保持停止,需检查日志后手动启动。菜单退出、更新、卸载、外部停止消息和系统会话结束都会登记退出意图并停止监视器。正常重启由重启脚本负责拉起,监视器不参与依赖同步与换包。`tray-lifecycle.log` 每行是一条 JSON,包含 UTC 时间、实例标识、托盘及监视器 PID、启动父进程、退出意图、外部消息发送者 PID、异常退出码和恢复结果。强制结束进程时,记录的操作者为 `unknown`,不能从退出码判断是谁关闭了它。diff --git a/docs/REUSE.md b/docs/REUSE.mdindex ffdf9bffb..2e085d62a 100644--- a/docs/REUSE.md+++ b/docs/REUSE.md@@ -44,9 +44,9 @@ Folia(`chthollyphile/folia-major`,AGPL-3.0,revision `9a01e788ed52d25ea01b1## Windows 常驻托盘-独立启动复用 Windows `CreateProcessW`、`STARTUPINFOEX` 与 [`PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute),经标准库 `ctypes` 调用;父身份取当前会话的桌面进程,创建前后均核对 Job。官方系统 API 无额外包、固定版本或第三方许可,适用于项目支持的 Windows,2026-10-07 核对。Peach 保留参数、数据根、源码与 PyInstaller 环境处理、单实例交接及启动验收。+独立启动复用 Windows `CreateProcessW`、`STARTUPINFOEX` 与 [`PROC_THREAD_ATTRIBUTE_PARENT_PROCESS`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute),经标准库 `ctypes` 调用;父身份取当前会话的桌面进程。子进程挂起创建,确认不属于 Job 后才用 [`ResumeThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-resumethread) 执行;允许自动脱离的桌面 Job 直接通过,仍继承 Job 或创建被拒绝时再尝试一次 `CREATE_BREAKAWAY_FROM_JOB`。禁止脱离时回收未执行代码的子进程并保留系统错误。官方系统 API 无额外包、固定版本或第三方许可,适用于项目支持的 Windows,2026-10-15 核对。Peach 保留参数、数据根、源码与 PyInstaller 环境处理、单实例交接及启动验收。-当前树与 Git 历史已有 `windows_restart`、`tray_lifecycle` 和 `process_job`,继续复用各自的重启、恢复及子服务清理行为。`DETACHED_PROCESS` 只脱离控制台;`CREATE_BREAKAWAY_FROM_JOB` 依赖外层 Job 允许脱离,不能覆盖禁止脱离的启动器;[`Win32_Process.Create`](https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects) 可以独立创建,但额外引入 WMI 命令与环境交接;`pywin32` 不属于运行依赖,监视器又必须只加载标准库,因此采用原生 API,无新增依赖。源码托盘直接调用基础解释器,按 [CPython 3.14.7 venv 启动器](https://github.com/python/cpython/blob/v3.14.7/PC/venvlauncher.c) 的 `__PYVENV_LAUNCHER__` 协议保留虚拟环境身份,避免 venv 启动器自己的 kill-on-close Job 导致重复交接。仅参照协议,没有复制 PSF 许可源码。回归在临时目录创建禁止脱离的 kill-on-close Job:关闭 Job 后普通子进程退出,独立子进程保持运行;同时核对 Unicode 参数、环境、工作目录、虚拟环境身份和实际解释器的 Job,并清理全部测试进程。+当前树与 Git 历史已有 `windows_restart`、`tray_lifecycle` 和 `process_job`,继续复用各自的重启、恢复及子服务清理行为。`DETACHED_PROCESS` 只脱离控制台;`CREATE_BREAKAWAY_FROM_JOB` 依赖所选父进程的 Job 允许脱离;[`Win32_Process.Create`](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/create-method-in-class-win32-process) 额外引入 WMI 命令、环境交接及服务自身 Job 配额,未采用;`pywin32` 不属于运行依赖,监视器又必须只加载标准库,因此采用原生 API,无新增依赖。源码托盘直接调用基础解释器,按 [CPython 3.14.7 venv 启动器](https://github.com/python/cpython/blob/v3.14.7/PC/venvlauncher.c) 的 `__PYVENV_LAUNCHER__` 协议保留虚拟环境身份,避免 venv 启动器自己的 kill-on-close Job 导致重复交接。仅参照协议,没有复制 PSF 许可源码。临时 Job 回归覆盖启动器禁止脱离、桌面允许自动或显式脱离、桌面禁止脱离三类情况:普通子进程随启动器退出,独立子进程保持运行,受限子进程不执行代码且被完整回收;同时核对 Unicode 参数、环境、工作目录、虚拟环境身份和实际解释器的 Job,并清理全部测试进程。真实 Explorer 不加入测试 Job。## 西方人像与官方封面diff --git a/src/peach/tray_detached.py b/src/peach/tray_detached.pyindex bfc6a3713..e8677e754 100644--- a/src/peach/tray_detached.py+++ b/src/peach/tray_detached.py@@ -8,6 +8,8 @@ import sysfrom ctypes import wintypesfrom pathlib import Path+_CREATE_SUSPENDED = 0x00000004+class _StartupInfo(ctypes.Structure):_fields_ = [@@ -48,6 +50,7 @@ def _kernel():wintypes.LPVOID, wintypes.LPVOID, wintypes.BOOL, wintypes.DWORD,wintypes.LPVOID, wintypes.LPCWSTR, ctypes.POINTER(_StartupInfoEx),ctypes.POINTER(_ProcessInfo)]),+ "ResumeThread": (wintypes.DWORD, [wintypes.HANDLE]),}for name, (result, arguments) in signatures.items():function = getattr(kernel, name)@@ -124,6 +127,34 @@ class DetachedProcess:self.close()+def _create_verified(kernel, executable, argv, cwd, block, startup, flags):+ """挂起创建,在用户代码执行前验收 Job 归属,再恢复主线程。"""+ child = _ProcessInfo()+ command = ctypes.create_unicode_buffer(subprocess.list2cmdline([os.fspath(a) for a in argv]))+ if not kernel.CreateProcessW(str(executable), command, None, None, False,+ flags | _CREATE_SUSPENDED, block, os.fspath(cwd),+ ctypes.byref(startup), ctypes.byref(child)):+ operation = "CreateProcessW(breakaway)" if flags & subprocess.CREATE_BREAKAWAY_FROM_JOB else "CreateProcessW"+ raise _windows_error(operation)+ process = DetachedProcess(child.hProcess, child.dwProcessId)+ verified = False+ try:+ if _in_job(kernel, child.hProcess):+ return None+ if kernel.ResumeThread(child.hThread) == 0xFFFFFFFF:+ raise _windows_error("ResumeThread")+ verified = True+ return process+ finally:+ kernel.CloseHandle(child.hThread)+ if not verified:+ try:+ process.terminate()+ process.wait(timeout=5)+ finally:+ process.close()++def launch_detached(argv, *, cwd, env=None) -> DetachedProcess:"""由当前会话桌面进程承接父身份;失败明确报错,不回退到启动器 Job。"""if os.name != "nt":@@ -153,10 +184,7 @@ def launch_detached(argv, *, cwd, env=None) -> DetachedProcess:if not parent:raise _windows_error("OpenProcess(desktop)")initialized = False- child = _ProcessInfo()try:- if _in_job(kernel, parent):- raise OSError("Windows 桌面进程属于 Job,无法保证托盘独立运行")size = ctypes.c_size_t()kernel.InitializeProcThreadAttributeList(None, 1, 0, ctypes.byref(size))attributes = ctypes.create_string_buffer(size.value)@@ -174,21 +202,18 @@ def launch_detached(argv, *, cwd, env=None) -> DetachedProcess:block = ctypes.create_unicode_buffer("\0".join(f"{key}={value}" for key, value in sorted(environment.items(), key=lambda row: row[0].upper())) + "\0\0")- command = ctypes.create_unicode_buffer(subprocess.list2cmdline([os.fspath(a) for a in argv]))flags = 0x00080000 | 0x00000400 | subprocess.DETACHED_PROCESS- if not kernel.CreateProcessW(str(executable), command, None, None, False,- flags, block, os.fspath(cwd), ctypes.byref(startup), ctypes.byref(child)):- raise _windows_error("CreateProcessW")- kernel.CloseHandle(child.hThread)- process = DetachedProcess(child.hProcess, child.dwProcessId)try:- if _in_job(kernel, child.hProcess):- raise OSError("托盘进程仍属于 Job,独立启动未成立")- except OSError:- process.terminate()- process.wait(timeout=5)- process.close()- raise+ process = _create_verified(kernel, executable, argv, cwd, block, startup, flags)+ except OSError as error:+ if getattr(error, "winerror", None) != 5 or getattr(error, "peach_operation", "") != "CreateProcessW":+ raise+ process = None+ if process is None:+ process = _create_verified(kernel, executable, argv, cwd, block, startup,+ flags | subprocess.CREATE_BREAKAWAY_FROM_JOB)+ if process is None:+ raise OSError(f"托盘进程仍受 Windows Job 约束,独立启动未成立(桌面 PID:{pid.value})")return processfinally:if initialized:diff --git a/tests/test_tray_detached.py b/tests/test_tray_detached.pyindex 5028fc5d0..b7b3ffb60 100644--- a/tests/test_tray_detached.py+++ b/tests/test_tray_detached.py@@ -1,5 +1,6 @@from __future__ import annotations+import ctypesimport jsonimport osimport subprocess@@ -7,6 +8,7 @@ import sysimport tempfileimport timeimport unittest+from ctypes import wintypesfrom pathlib import Pathfrom unittest import mock@@ -16,6 +18,24 @@ from peach.process_job import assign_to_job, close_job, create_kill_on_close_jobROOT = Path(__file__).resolve().parents[1]+class _JobBasicLimits(ctypes.Structure):+ _fields_ = [("times", ctypes.c_longlong * 2), ("flags", wintypes.DWORD),+ ("working_set", ctypes.c_size_t * 2), ("active_limit", wintypes.DWORD),+ ("affinity", ctypes.c_size_t), ("priority", wintypes.DWORD),+ ("scheduling", wintypes.DWORD)]+++class _JobLimits(ctypes.Structure):+ _fields_ = [("basic", _JobBasicLimits), ("io", ctypes.c_ulonglong * 6),+ ("memory", ctypes.c_size_t * 4)]+++class _JobAccounting(ctypes.Structure):+ _fields_ = [("times", ctypes.c_longlong * 4), ("page_faults", wintypes.DWORD),+ ("total", wintypes.DWORD), ("active", wintypes.DWORD),+ ("terminated", wintypes.DWORD)]++class DetachedLaunchTests(unittest.TestCase):def test_source_sync_restarts_for_detachment_and_lifecycle_changes(self):from peach.tray import tray_restart_required@@ -145,6 +165,89 @@ time.sleep(60)process.wait(timeout=10)process.close()+ @unittest.skipUnless(os.name == "nt", "Windows 桌面 Job 的实际继承与脱离")+ def test_child_escapes_desktop_jobs_that_allow_automatic_or_explicit_breakaway(self):+ for flags in (0x1000, 0x0800):+ with self.subTest(flags=hex(flags)):+ self._desktop_job_launch(flags, allowed=True)++ @unittest.skipUnless(os.name == "nt", "Windows 桌面 Job 的实际继承与脱离")+ def test_restricted_desktop_job_never_executes_the_child(self):+ self._desktop_job_launch(0, allowed=False)++ def _desktop_job_launch(self, flags, *, allowed):+ with tempfile.TemporaryDirectory() as directory:+ root = Path(directory).resolve()+ job = create_kill_on_close_job()+ self.assertIsNotNone(job)+ kernel = tray_detached._kernel()+ kernel.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int,+ wintypes.LPVOID, wintypes.DWORD]+ limits = _JobLimits()+ limits.basic.flags = 0x2000 | flags+ self.assertTrue(kernel.SetInformationJobObject(job, 9, ctypes.byref(limits), ctypes.sizeof(limits)))+ desktop = child = None+ try:+ desktop = tray_detached.launch_detached(+ [sys._base_executable, "-c", "import time; time.sleep(60)"], cwd=root)+ assign_to_job(job, desktop)+ self.assertTrue(tray_detached._in_job(kernel, desktop._handle))+ user = mock.Mock()+ user.GetShellWindow.return_value = 1++ def desktop_pid(_window, output):+ ctypes.cast(output, ctypes.POINTER(wintypes.DWORD)).contents.value = desktop.pid+ return 1++ user.GetWindowThreadProcessId.side_effect = desktop_pid+ native_dll = ctypes.WinDLL++ def load_dll(name, *args, **kwargs):+ return user if name == "user32" else native_dll(name, *args, **kwargs)++ marker = root / "executed"+ code = "from pathlib import Path; import sys, time; Path(sys.argv[1]).touch(); time.sleep(60)"+ with mock.patch.object(ctypes, "WinDLL", side_effect=load_dll):+ if allowed:+ child = tray_detached.launch_detached(+ [sys._base_executable, "-c", code, str(marker)], cwd=root)+ else:+ with self.assertRaises(OSError):+ tray_detached.launch_detached([sys._base_executable, "-c", code, str(marker)], cwd=root)+ if allowed:+ deadline = time.monotonic() + 10+ while not marker.exists() and time.monotonic() < deadline:+ self.assertIsNone(child.poll())+ time.sleep(.05)+ self.assertTrue(marker.exists(), "通过独立性检查后应执行子进程")+ self.assertFalse(tray_detached._in_job(kernel, child._handle))+ close_job(job)+ job = None+ desktop.wait(timeout=10)+ self.assertIsNone(child.poll(), "关闭桌面 Job 后独立子进程必须存活")+ else:+ self.assertFalse(marker.exists(), "受限子进程必须在执行代码前停止")+ kernel.QueryInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int,+ wintypes.LPVOID, wintypes.DWORD, wintypes.LPVOID]+ accounting = _JobAccounting()+ self.assertTrue(kernel.QueryInformationJobObject(+ job, 1, ctypes.byref(accounting), ctypes.sizeof(accounting), None))+ self.assertGreaterEqual(accounting.total, 2, "必须按实际子进程结果判断独立性")+ self.assertEqual(accounting.active, 1, "拒绝的子进程必须完整回收")+ finally:+ close_job(job)+ for process in (child, desktop):+ if process is not None:+ if process is desktop and job is not None:+ try:+ process.wait(timeout=10)+ except subprocess.TimeoutExpired:+ pass+ if process.poll() is None:+ process.terminate()+ process.wait(timeout=10)+ process.close()+if __name__ == "__main__":