feat(plugin): 建立可信来源准入与安装恢复 (#6462)

app/adapters/external/market.py

@@ -16,7 +16,7 @@ import traceback
 import uuid
 import zipfile
 from pathlib import Path, PurePosixPath, PureWindowsPath
-from typing import Dict, List, Optional, Tuple, Set, Callable, Awaitable, Iterator, Sequence
+from typing import Any, Dict, List, Optional, Tuple, Set, Callable, Awaitable, Iterator, Sequence
 from urllib.parse import parse_qs, quote, unquote, urlparse, urlsplit
 
 import aiofiles
@@ -84,6 +84,14 @@ VERSION_BACKWARD_COMPATIBLE_FLAGS: Dict[str, List[str]] = {
 }
 
 InstalledPluginsProvider = Callable[[], List[str]]
+PluginInstallGateway = Callable[
+    [str, str, Optional[str], Optional[str], bool],
+    Tuple[bool, str],
+]
+AsyncPluginInstallGateway = Callable[
+    [str, str, Optional[str], Optional[str], bool],
+    Awaitable[Tuple[bool, str]],
+]
 
 
 @dataclass(frozen=True)
@@ -101,6 +109,34 @@ def _empty_installed_plugins() -> List[str]:
 
 _installed_plugins_provider: InstalledPluginsProvider = _empty_installed_plugins
 
+
+def _unconfigured_plugin_install_gateway(
+    _pid: str,
+    _repo_url: str,
+    _package_version: Optional[str],
+    _release_version: Optional[str],
+    _force_install: bool,
+) -> Tuple[bool, str]:
+    """在组合根尚未装配来源门禁时拒绝插件包写入。"""
+    return False, "插件安装服务尚未完成初始化"
+
+
+async def _unconfigured_async_plugin_install_gateway(
+    _pid: str,
+    _repo_url: str,
+    _package_version: Optional[str],
+    _release_version: Optional[str],
+    _force_install: bool,
+) -> Tuple[bool, str]:
+    """在组合根尚未装配来源门禁时拒绝异步插件包写入。"""
+    return False, "插件安装服务尚未完成初始化"
+
+
+_plugin_install_gateway: PluginInstallGateway = _unconfigured_plugin_install_gateway
+_async_plugin_install_gateway: AsyncPluginInstallGateway = (
+    _unconfigured_async_plugin_install_gateway
+)
+
 def configure_installed_plugins_provider(
     provider: InstalledPluginsProvider,
 ) -> None:
@@ -109,6 +145,24 @@ def configure_installed_plugins_provider(
     _installed_plugins_provider = provider
 
 
+def configure_plugin_install_gateway(
+    *,
+    install: PluginInstallGateway,
+    async_install: AsyncPluginInstallGateway,
+) -> None:
+    """由启动组合根装配公开兼容安装入口的来源门禁。"""
+    global _plugin_install_gateway, _async_plugin_install_gateway
+    _plugin_install_gateway = install
+    _async_plugin_install_gateway = async_install
+
+
+def reset_plugin_install_gateway() -> None:
+    """恢复未装配状态，供隔离测试清理进程级安装入口。"""
+    global _plugin_install_gateway, _async_plugin_install_gateway
+    _plugin_install_gateway = _unconfigured_plugin_install_gateway
+    _async_plugin_install_gateway = _unconfigured_async_plugin_install_gateway
+
+
 def normalize_plugin_market_repo_url(repo_url: str) -> Optional[str]:
     """规范化插件仓库地址，便于跨来源合并去重。"""
     repo_url = (repo_url or "").strip().rstrip("/")
@@ -518,6 +572,11 @@ class PluginHelper(metaclass=WeakSingleton):
                     candidate["repo_order"] = repo_order
                     candidate["repo_path"] = repo_path
                     candidate["path"] = plugin_dir
+                    candidate["repo_url"] = self.make_local_repo_url(
+                        pid,
+                        repo_path,
+                        package_version or None,
+                    )
                     self.annotate_plugin_system_version(candidate)
                     candidate_version = str(candidate.get("version") or "0")
 
@@ -583,6 +642,11 @@ class PluginHelper(metaclass=WeakSingleton):
                         candidate["repo_order"] = repo_order
                         candidate["repo_path"] = local_repo_path
                         candidate["path"] = plugin_dir
+                        candidate["repo_url"] = self.make_local_repo_url(
+                            candidate_pid,
+                            local_repo_path,
+                            current_package_version or None,
+                        )
                         if not is_compatible:
                             candidate["compatible"] = False
                             candidate["skip_reason"] = (
@@ -798,11 +862,34 @@ class PluginHelper(metaclass=WeakSingleton):
         releases.extend(cls.__normalize_plugin_release_response(payload))
         return len(payload) >= 100
 
+    @cached(maxsize=128, ttl=1800)  # type: ignore[misc]  # 缓存装饰器暂未提供泛型签名
+    def get_plugin_index_result(
+            self,
+            repo_url: str,
+            package_version: Optional[str] = None,
+    ) -> Optional[Dict[str, Dict[str, Any]]]:
+        """读取插件索引；404 返回 None，读取失败由调用方记录。"""
+        request = self._build_plugin_index_request(repo_url, package_version)
+        if request is None:
+            raise ValueError("插件仓库地址无效")
+        package_url, headers = request
+        res = self.__request_with_fallback(package_url, headers=headers)
+        if res is None:
+            raise RuntimeError("插件索引请求失败：连接失败")
+        if res.status_code == 404:
+            return None
+        if res.status_code != 200:
+            raise RuntimeError(f"插件索引请求失败：HTTP {res.status_code}")
+        payload = self.__parse_plugin_index_response(res.text)
+        if payload is None:
+            raise RuntimeError("插件索引响应格式无效")
+        return payload
+
     @cached(maxsize=128, ttl=1800)
     def get_plugins(self, repo_url: str,
                     package_version: Optional[str] = None) -> Optional[Dict[str, dict]]:
         """
-        获取Github所有最新插件列表
+        获取 Github 插件列表，保留旧的 dict/{}/None 兼容返回。
         :param repo_url: Github仓库地址
         :param package_version: 首选插件版本 (如 "v2", "v3")，如果不指定则获取 v1 版本
         """
@@ -955,16 +1042,32 @@ class PluginHelper(metaclass=WeakSingleton):
                 release_version: Optional[str] = None, force_install: bool = False) \
             -> Tuple[bool, str]:
         """
-        安装插件，包括版本检查、内容准备、生效清单依赖安装和失败恢复。
+        通过宿主统一 Gateway 安装插件，保留第三方插件使用的同步兼容 API。
         :param pid: 插件 ID
         :param repo_url: 插件仓库地址
         :param package_version: 首选插件版本 (如 "v2", "v3")，如不指定则默认使用系统配置的版本
         :param release_version: 指定安装的 release 资产版本；未指定时安装当前索引版本
-        :param force_install: 是否强制安装插件，默认不启用，启用时不进行备份和恢复操作
+        :param force_install: 是否替换已存在的插件载荷
         :return: (是否成功, 错误信息)
         """
+        return _plugin_install_gateway(
+            pid,
+            repo_url,
+            package_version,
+            release_version,
+            force_install,
+        )
+
+    def __install_package(self, pid: str, repo_url: str, package_version: Optional[str] = None,
+                          release_version: Optional[str] = None, force_install: bool = False) \
+            -> Tuple[bool, str]:
+        """执行已通过来源准入的同步包安装，不负责身份或运行态提交。"""
         if self.is_local_repo_url(repo_url):
-            return self.install_local(pid=pid, repo_url=repo_url, force_install=force_install)
+            return self.__install_local_package(
+                pid=pid,
+                repo_url=repo_url,
+                force_install=force_install,
+            )
 
         if SystemUtils.is_frozen():
             return False, "可执行文件模式下，只能安装本地插件"
@@ -1045,8 +1148,24 @@ class PluginHelper(metaclass=WeakSingleton):
         return self.__install_flow_sync(pid, force_install, prepare_filelist, repo_url)
 
     def install_local(self, pid: str, repo_url: str = "", force_install: bool = False) -> Tuple[bool, str]:
+        """通过宿主统一 Gateway 安装本地插件。"""
+        target_repo = repo_url or self.make_local_repo_url(pid)
+        return _plugin_install_gateway(
+            pid,
+            target_repo,
+            self.parse_local_repo_package_version(target_repo),
+            None,
+            force_install,
+        )
+
+    def __install_local_package(
+        self,
+        pid: str,
+        repo_url: str = "",
+        force_install: bool = False,
+    ) -> Tuple[bool, str]:
         """
-        从本地插件仓库目录安装插件
+        执行已通过来源准入的本地插件包安装。
         """
         local_pid = self.parse_local_repo_url(repo_url) if repo_url else pid
         if not local_pid or local_pid.lower() != pid.lower():
@@ -2158,7 +2277,6 @@ class PluginHelper(metaclass=WeakSingleton):
                 logger.warn(f"{pid} 已清理对应插件目录，请尝试重新安装")
             return False, dep_msg
 
-        self.refresh_persistent_plugin_backup(pid)
         if backup_dir:
             shutil.rmtree(backup_dir, ignore_errors=True)
         return True, ""
@@ -2433,11 +2551,37 @@ class PluginHelper(metaclass=WeakSingleton):
         logger.error(f"[GitHub] 所有策略均请求失败，URL: {url}，请检查网络连接或 GitHub 配置")
         return None
 
+    @cached(maxsize=128, ttl=1800)  # type: ignore[misc]  # 缓存装饰器暂未提供泛型签名
+    async def async_get_plugin_index_result(
+            self,
+            repo_url: str,
+            package_version: Optional[str] = None,
+    ) -> Optional[Dict[str, Dict[str, Any]]]:
+        """异步读取插件索引；404 返回 None，读取失败由调用方记录。"""
+        request = self._build_plugin_index_request(repo_url, package_version)
+        if request is None:
+            raise ValueError("插件仓库地址无效")
+        package_url, headers = request
+        res = await self.__async_request_with_fallback(
+            package_url,
+            headers=headers,
+        )
+        if res is None:
+            raise RuntimeError("插件索引请求失败：连接失败")
+        if res.status_code == 404:
+            return None
+        if res.status_code != 200:
+            raise RuntimeError(f"插件索引请求失败：HTTP {res.status_code}")
+        payload = self.__parse_plugin_index_response(res.text)
+        if payload is None:
+            raise RuntimeError("插件索引响应格式无效")
+        return payload
+
     @cached(maxsize=128, ttl=1800)
     async def async_get_plugins(self, repo_url: str,
                                 package_version: Optional[str] = None) -> Optional[Dict[str, dict]]:
         """
-        异步获取Github所有最新插件列表
+        异步获取 Github 插件列表，保留旧的 dict/{}/None 兼容返回。
         :param repo_url: Github仓库地址
         :param package_version: 首选插件版本 (如 "v2", "v3")，如果不指定则获取 v1 版本
         """
@@ -3042,17 +3186,34 @@ class PluginHelper(metaclass=WeakSingleton):
                             release_version: Optional[str] = None,
                             force_install: bool = False) -> Tuple[bool, str]:
         """
-        异步安装插件，包括版本检查、内容准备、生效清单依赖安装和失败恢复。
+        通过宿主统一 Gateway 安装插件，保留第三方插件使用的异步兼容 API。
         :param pid: 插件 ID
         :param repo_url: 插件仓库地址
         :param package_version: 首选插件版本 (如 "v2", "v3")，如不指定则默认使用系统配置的版本
         :param release_version: 指定安装的 release 资产版本；未指定时安装当前索引版本
-        :param force_install: 是否强制安装插件，默认不启用，启用时不进行备份和恢复操作
+        :param force_install: 是否替换已存在的插件载荷
         :return: (是否成功, 错误信息)
         """
+        return await _async_plugin_install_gateway(
+            pid,
+            repo_url,
+            package_version,
+            release_version,
+            force_install,
+        )
+
+    async def __async_install_package(
+            self,
+            pid: str,
+            repo_url: str,
+            package_version: Optional[str] = None,
+            release_version: Optional[str] = None,
+            force_install: bool = False,
+    ) -> Tuple[bool, str]:
+        """执行已通过来源准入的异步包安装，不负责身份或运行态提交。"""
         if self.is_local_repo_url(repo_url):
             return await _await_thread_operation(
-                self.install_local,
+                self.__install_local_package,
                 pid,
                 repo_url,
                 force_install,
@@ -3187,7 +3348,6 @@ class PluginHelper(metaclass=WeakSingleton):
                     logger.warning(f"{pid} 已清理对应插件目录，请尝试重新安装")
                 return False, dep_msg
 
-            await _await_thread_operation(self.refresh_persistent_plugin_backup, pid)
             return True, ""
         except asyncio.CancelledError:
             logger.warning(

app/adapters/external/plugin/client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from app.adapters.external.market import PluginHelper as _PluginHelper
 from app.runtime.cache import async_fresh, fresh
@@ -21,7 +21,7 @@ class PluginMarketClient:
         repo_url: str,
         package_version: Optional[str] = None,
         force: bool = False,
-    ) -> Optional[dict[str, dict]]:
+    ) -> Optional[dict[str, dict[str, Any]]]:
         """同步读取指定仓库和代际的插件索引。"""
         with fresh(force):
             return self._helper.get_plugins(repo_url, package_version)
@@ -36,6 +36,35 @@ class PluginMarketClient:
         async with async_fresh(force):
             return await self._helper.async_get_plugins(repo_url, package_version)
 
+    def get_plugin_index_result(
+        self,
+        repo_url: str,
+        package_version: Optional[str] = None,
+        force: bool = False,
+    ) -> Optional[dict[str, dict]]:
+        """读取插件索引的三态结果，供库存读取保留失败事实。"""
+        with fresh(force):
+            return cast(
+                Optional[dict[str, dict[str, Any]]],
+                self._helper.get_plugin_index_result(repo_url, package_version),
+            )
+
+    async def async_get_plugin_index_result(
+        self,
+        repo_url: str,
+        package_version: Optional[str] = None,
+        force: bool = False,
+    ) -> Optional[dict[str, dict[str, Any]]]:
+        """异步读取插件索引的三态结果，供库存读取保留失败事实。"""
+        async with async_fresh(force):
+            return cast(
+                Optional[dict[str, dict[str, Any]]],
+                await self._helper.async_get_plugin_index_result(
+                    repo_url,
+                    package_version,
+                ),
+            )
+
     def get_local_candidates(self) -> dict[str, dict]:
         """返回全部本地插件仓库候选。"""
         return self._helper.get_local_plugin_candidates()

app/adapters/system/plugin/package.py

@@ -2,32 +2,47 @@
 
 from __future__ import annotations
 
+import hashlib
 import re
 import shutil
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional, cast
 
 from app.adapters.external.market import PluginHelper as _PluginHelper
+from app.adapters.system.host import SystemUtils
 from app.runtime.execution import (
     run_in_threadpool_to_completion as _await_thread_operation,
 )
 from app.runtime.log import logger
 from app.runtime.settings import RuntimeSettingsCompat
 
-
 # 保留旧模块级入口，插件本地同步测试和旧扩展仍可能覆盖这些设置。
 settings = RuntimeSettingsCompat()
 
 @dataclass(frozen=True, slots=True)
 class PluginPackageCheckpoint:
-    """记录一次插件包变更前可用于补偿恢复的文件快照。"""
+    """记录运行目录快照及待提升的容器恢复备份。"""
 
     plugin_id: str
     plugin_dir: Path
+    persistent_backup_dir: Path
+    backup_staging_dir: Path | None
+    backup_previous_dir: Path | None
     transaction_dir: Path
-    existed: bool
+    plugin_existed: bool
+    persistent_backup_existed: bool
+
+    @property
+    def existed(self) -> bool:
+        """保留旧调用方读取运行目录存在状态的兼容属性。"""
+        return self.plugin_existed
+
+    @property
+    def rollback_marker(self) -> Path:
+        """返回文件补偿完成标记，供 PREPARED 重放保持幂等。"""
+        return self.transaction_dir / ".rollback-complete"
 
 
 class PluginPackageManager:
@@ -40,7 +55,7 @@ class PluginPackageManager:
         self._helper = helper or _PluginHelper()
 
     @staticmethod
-    def _plugin_dir(plugin_id: str) -> Path:
+    def __plugin_dir(plugin_id: str) -> Path:
         """解析插件运行目录并拒绝越出宿主插件根目录的标识。"""
         plugins_root = (
             Path(settings.ROOT_PATH) / "app" / "plugins"
@@ -50,18 +65,44 @@ class PluginPackageManager:
             raise ValueError(f"非法插件ID：{plugin_id}")
         return plugin_dir
 
-    def checkpoint(self, plugin_id: str) -> PluginPackageCheckpoint:
-        """在包变更前创建独立快照，供后续提交或补偿恢复。"""
-        plugin_dir = self._plugin_dir(plugin_id)
-        transaction_dir = (
-            Path(settings.TEMP_PATH)
-            / "plugin_transactions"
-            / f"{plugin_id.lower()}-{uuid.uuid4().hex}"
+    def checkpoint(
+        self,
+        plugin_id: str,
+        transaction_id: Optional[str] = None,
+    ) -> PluginPackageCheckpoint:
+        """在包变更前保存运行目录；持久事务使用配置目录承载恢复材料。"""
+        plugin_dir = self.__plugin_dir(plugin_id)
+        durable = transaction_id is not None
+        persistent_backup_dir = (
+            Path(settings.CONFIG_PATH) / "plugins_backup" / plugin_id.lower()
+        ).resolve()
+        backup_staging_dir = (
+            persistent_backup_dir.parent
+            / f".{plugin_id.lower()}.staging-{transaction_id}"
+            if durable and SystemUtils.is_docker()
+            else None
         )
-        existed = plugin_dir.exists()
+        backup_previous_dir = (
+            persistent_backup_dir.parent
+            / f".{plugin_id.lower()}.previous-{transaction_id}"
+            if durable and SystemUtils.is_docker()
+            else None
+        )
+        transaction_root = (
+            Path(settings.CONFIG_PATH)
+            if durable
+            else Path(settings.TEMP_PATH)
+        )
+        transaction_dir = (
+            transaction_root
+            / "plugin_transactions"
+            / (transaction_id or f"{plugin_id.lower()}-{uuid.uuid4().hex}")
+        )
+        plugin_existed = plugin_dir.exists()
+        persistent_backup_existed = persistent_backup_dir.exists()
         try:
             transaction_dir.mkdir(parents=True, exist_ok=False)
-            if existed:
+            if plugin_existed:
                 shutil.copytree(plugin_dir, transaction_dir / "package")
         except Exception:
             shutil.rmtree(transaction_dir, ignore_errors=True)
@@ -69,18 +110,77 @@ class PluginPackageManager:
         return PluginPackageCheckpoint(
             plugin_id=plugin_id,
             plugin_dir=plugin_dir,
+            persistent_backup_dir=persistent_backup_dir,
+            backup_staging_dir=backup_staging_dir,
+            backup_previous_dir=backup_previous_dir,
             transaction_dir=transaction_dir,
-            existed=existed,
+            plugin_existed=plugin_existed,
+            persistent_backup_existed=persistent_backup_existed,
         )
 
-    async def async_checkpoint(self, plugin_id: str) -> PluginPackageCheckpoint:
+    def restore_checkpoint(
+        self,
+        *,
+        plugin_id: str,
+        transaction_id: str,
+        plugin_existed: bool,
+        persistent_backup_existed: bool,
+    ) -> PluginPackageCheckpoint:
+        """按受控根目录和事务 ID 重建崩溃回放所需的文件引用。"""
+        plugin_dir = self.__plugin_dir(plugin_id)
+        persistent_backup_dir = (
+            Path(settings.CONFIG_PATH) / "plugins_backup" / plugin_id.lower()
+        ).resolve()
+        durable_backup = SystemUtils.is_docker()
+        return PluginPackageCheckpoint(
+            plugin_id=plugin_id,
+            plugin_dir=plugin_dir,
+            persistent_backup_dir=persistent_backup_dir,
+            backup_staging_dir=(
+                persistent_backup_dir.parent
+                / f".{plugin_id.lower()}.staging-{transaction_id}"
+                if durable_backup
+                else None
+            ),
+            backup_previous_dir=(
+                persistent_backup_dir.parent
+                / f".{plugin_id.lower()}.previous-{transaction_id}"
+                if durable_backup
+                else None
+            ),
+            transaction_dir=(
+                Path(settings.CONFIG_PATH)
+                / "plugin_transactions"
+                / transaction_id
+            ),
+            plugin_existed=plugin_existed,
+            persistent_backup_existed=persistent_backup_existed,
+        )
+
+    async def async_checkpoint(
+        self,
+        plugin_id: str,
+        transaction_id: Optional[str] = None,
+    ) -> PluginPackageCheckpoint:
         """在线程池中创建插件包文件快照。"""
-        return await _await_thread_operation(self.checkpoint, plugin_id)
+        return cast(
+            PluginPackageCheckpoint,
+            await _await_thread_operation(
+                self.checkpoint,
+                plugin_id,
+                transaction_id,
+            ),
+        )
 
     @staticmethod
     def commit(checkpoint: PluginPackageCheckpoint) -> None:
-        """确认包变更成功并清理临时快照。"""
-        shutil.rmtree(checkpoint.transaction_dir, ignore_errors=False)
+        """清理已完成事务的运行目录快照和残余替换材料。"""
+        if checkpoint.backup_staging_dir and checkpoint.backup_staging_dir.exists():
+            raise RuntimeError("持久备份尚未提升，不能清理插件安装事务")
+        if checkpoint.backup_previous_dir and checkpoint.backup_previous_dir.exists():
+            raise RuntimeError("旧持久备份尚未清理，不能结束插件安装事务")
+        if checkpoint.transaction_dir.exists():
+            shutil.rmtree(checkpoint.transaction_dir, ignore_errors=False)
 
     async def async_commit(self, checkpoint: PluginPackageCheckpoint) -> None:
         """在线程池中清理已提交的插件包快照。"""
@@ -88,17 +188,30 @@ class PluginPackageManager:
 
     @staticmethod
     def rollback(checkpoint: PluginPackageCheckpoint) -> None:
-        """删除当前包并把变更前文件快照恢复到运行目录。"""
-        snapshot_dir = checkpoint.transaction_dir / "package"
-        if checkpoint.existed:
-            if not snapshot_dir.is_dir():
-                raise FileNotFoundError(
-                    f"插件 {checkpoint.plugin_id} 的补偿快照不存在：{snapshot_dir}"
-                )
-        if checkpoint.plugin_dir.exists():
-            shutil.rmtree(checkpoint.plugin_dir)
-        if checkpoint.existed:
-            shutil.copytree(snapshot_dir, checkpoint.plugin_dir)
+        """兼容旧调用方，恢复运行目录和持久备份后清理恢复材料。"""
+        PluginPackageManager.restore(checkpoint)
+        PluginPackageManager.cleanup(checkpoint)
+
+    @staticmethod
+    def restore(checkpoint: PluginPackageCheckpoint) -> None:
+        """恢复运行目录和提交前持久备份，并保留快照直到 journal 删除。"""
+        if checkpoint.rollback_marker.is_file():
+            return
+        PluginPackageManager.__restore_tree(
+            target=checkpoint.plugin_dir,
+            snapshot=checkpoint.transaction_dir / "package",
+            existed=checkpoint.plugin_existed,
+            label=f"插件 {checkpoint.plugin_id} 运行目录",
+        )
+        PluginPackageManager.__rollback_persistent_backup(checkpoint)
+        if checkpoint.backup_staging_dir and checkpoint.backup_staging_dir.exists():
+            shutil.rmtree(checkpoint.backup_staging_dir, ignore_errors=False)
+        checkpoint.transaction_dir.mkdir(parents=True, exist_ok=True)
+        checkpoint.rollback_marker.touch(exist_ok=True)
+
+    @staticmethod
+    def cleanup(checkpoint: PluginPackageCheckpoint) -> None:
+        """在 journal 已删除后清理恢复材料；重复调用保持幂等。"""
         if checkpoint.transaction_dir.exists():
             shutil.rmtree(checkpoint.transaction_dir, ignore_errors=False)
 
@@ -106,6 +219,243 @@ class PluginPackageManager:
         """在线程池中恢复插件包文件快照。"""
         await _await_thread_operation(self.rollback, checkpoint)
 
+    async def async_restore(self, checkpoint: PluginPackageCheckpoint) -> None:
+        """在线程池恢复插件状态，并保留 journal 仍需引用的材料。"""
+        await _await_thread_operation(self.restore, checkpoint)
+
+    async def async_cleanup(self, checkpoint: PluginPackageCheckpoint) -> None:
+        """在线程池清理已失去 journal 所有权的恢复材料。"""
+        await _await_thread_operation(self.cleanup, checkpoint)
+
+    @staticmethod
+    def __rollback_persistent_backup(
+        checkpoint: PluginPackageCheckpoint,
+    ) -> None:
+        """把已激活但尚未提交的持久备份恢复到事务前状态。"""
+        previous = checkpoint.backup_previous_dir
+        staging = checkpoint.backup_staging_dir
+        if previous is None or staging is None:
+            return
+
+        target = checkpoint.persistent_backup_dir
+        if previous.exists():
+            discarded = target.parent / f".{target.name}.discard-{uuid.uuid4().hex}"
+            try:
+                if target.exists():
+                    target.replace(discarded)
+                previous.replace(target)
+                if discarded.exists():
+                    shutil.rmtree(discarded, ignore_errors=False)
+            except Exception:
+                if not target.exists() and discarded.exists():
+                    discarded.replace(target)
+                raise
+            finally:
+                if target.exists() and discarded.exists():
+                    shutil.rmtree(discarded, ignore_errors=True)
+            return
+
+        if staging.exists():
+            return
+        if checkpoint.persistent_backup_existed:
+            if target.exists():
+                return
+            raise FileNotFoundError(
+                f"插件 {checkpoint.plugin_id} 的旧持久备份恢复材料不存在"
+            )
+        if target.exists():
+            shutil.rmtree(target, ignore_errors=False)
+
+    @staticmethod
+    def __restore_tree(
+        *,
+        target: Path,
+        snapshot: Path,
+        existed: bool,
+        label: str,
+    ) -> None:
+        """用同级 staging 替换目录，失败时保留替换前的当前目录。"""
+        if existed and not snapshot.is_dir():
+            raise FileNotFoundError(f"{label}补偿快照不存在：{snapshot}")
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        staging = target.parent / f".{target.name}.restore-{uuid.uuid4().hex}"
+        previous = target.parent / f".{target.name}.previous-{uuid.uuid4().hex}"
+        try:
+            if existed:
+                shutil.copytree(snapshot, staging)
+            if target.exists():
+                target.replace(previous)
+            if existed:
+                staging.replace(target)
+            if previous.exists():
+                shutil.rmtree(previous)
+        except Exception:
+            if not target.exists() and previous.exists():
+                previous.replace(target)
+            raise
+        finally:
+            if staging.exists():
+                shutil.rmtree(staging, ignore_errors=True)
+            if target.exists() and previous.exists():
+                shutil.rmtree(previous, ignore_errors=True)
+
+    @classmethod
+    def stage_persistent_backup(cls, checkpoint: PluginPackageCheckpoint) -> None:
+        """把新载荷复制到持久配置目录的独立 staging，不覆盖现有备份。"""
+        staging = checkpoint.backup_staging_dir
+        if staging is None:
+            return
+        if not checkpoint.plugin_dir.is_dir():
+            raise FileNotFoundError(
+                f"插件 {checkpoint.plugin_id} 运行目录不存在"
+            )
+        staging.parent.mkdir(parents=True, exist_ok=True)
+        if staging.exists():
+            shutil.rmtree(staging, ignore_errors=False)
+        shutil.copytree(
+            checkpoint.plugin_dir,
+            staging,
+            ignore=shutil.ignore_patterns(*cls._COPY_IGNORE),
+        )
+
+    async def async_stage_persistent_backup(
+        self,
+        checkpoint: PluginPackageCheckpoint,
+    ) -> None:
+        """在线程池准备新载荷的容器恢复备份。"""
+        await _await_thread_operation(self.stage_persistent_backup, checkpoint)
+
+    @staticmethod
+    def activate_persistent_backup(checkpoint: PluginPackageCheckpoint) -> None:
+        """在数据库提交前激活新备份，并保留上一份备份供失败补偿。"""
+        staging = checkpoint.backup_staging_dir
+        previous = checkpoint.backup_previous_dir
+        if staging is None or previous is None:
+            return
+
+        target = checkpoint.persistent_backup_dir
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if staging.exists():
+            if target.exists() and not previous.exists():
+                target.replace(previous)
+            if not target.exists():
+                staging.replace(target)
+        elif not target.exists():
+            raise FileNotFoundError(
+                f"插件 {checkpoint.plugin_id} 的持久备份 staging 不存在"
+            )
+
+    async def async_activate_persistent_backup(
+        self,
+        checkpoint: PluginPackageCheckpoint,
+    ) -> None:
+        """在线程池激活新持久备份，同时保留失败补偿材料。"""
+        await _await_thread_operation(self.activate_persistent_backup, checkpoint)
+
+    @staticmethod
+    def finalize_persistent_backup(checkpoint: PluginPackageCheckpoint) -> None:
+        """数据库提交后清理上一份持久备份；重复调用保持幂等。"""
+        staging = checkpoint.backup_staging_dir
+        previous = checkpoint.backup_previous_dir
+        if staging is None or previous is None:
+            return
+        if staging.exists():
+            raise RuntimeError("新持久备份尚未激活")
+        if not checkpoint.persistent_backup_dir.is_dir():
+            raise FileNotFoundError(
+                f"插件 {checkpoint.plugin_id} 的已提交持久备份不存在"
+            )
+        if previous.exists():
+            shutil.rmtree(previous, ignore_errors=False)
+
+    async def async_finalize_persistent_backup(
+        self,
+        checkpoint: PluginPackageCheckpoint,
+    ) -> None:
+        """在线程池清理数据库提交后的旧持久备份。"""
+        await _await_thread_operation(self.finalize_persistent_backup, checkpoint)
+
+    def payload_receipt(self, plugin_id: str) -> str:
+        """按稳定相对路径和文件内容计算已安装载荷收据。"""
+        plugin_dir = self.__plugin_dir(plugin_id)
+        if not plugin_dir.is_dir():
+            raise FileNotFoundError(f"插件 {plugin_id} 运行目录不存在")
+        return self.__tree_receipt(plugin_dir)
+
+    @classmethod
+    def persistent_backup_receipt(
+        cls,
+        checkpoint: PluginPackageCheckpoint,
+    ) -> str:
+        """计算已提升持久备份的内容收据，供崩溃回放确认终态。"""
+        if not checkpoint.persistent_backup_dir.is_dir():
+            raise FileNotFoundError(
+                f"插件 {checkpoint.plugin_id} 持久备份不存在"
+            )
+        return cls.__tree_receipt(checkpoint.persistent_backup_dir)
+
+    @classmethod
+    def __tree_receipt(cls, root: Path) -> str:
+        """对插件目录使用稳定路径和文件内容生成审计收据。"""
+
+        digest = hashlib.sha256()
+        for path in sorted(
+            root.rglob("*"),
+            key=lambda item: item.relative_to(root).as_posix(),
+        ):
+            relative = path.relative_to(root).as_posix()
+            if cls.__ignored_receipt_path(path, root):
+                continue
+            encoded_path = relative.encode("utf-8")
+            digest.update(len(encoded_path).to_bytes(4, "big"))
+            digest.update(encoded_path)
+            if path.is_symlink():
+                digest.update(b"L")
+                target = path.readlink().as_posix().encode("utf-8")
+                digest.update(len(target).to_bytes(4, "big"))
+                digest.update(target)
+            elif path.is_dir():
+                digest.update(b"D")
+            elif path.is_file():
+                digest.update(b"F")
+                with path.open("rb") as file_handle:
+                    for chunk in iter(lambda: file_handle.read(1024 * 1024), b""):
+                        digest.update(chunk)
+        return f"sha256:{digest.hexdigest()}"
+
+    async def async_payload_receipt(self, plugin_id: str) -> str:
+        """在线程池计算插件载荷收据。"""
+        return cast(
+            str,
+            await _await_thread_operation(self.payload_receipt, plugin_id),
+        )
+
+    async def async_committed_payload_receipt(
+        self,
+        checkpoint: PluginPackageCheckpoint,
+    ) -> str:
+        """读取数据库已提交载荷在当前部署模式下的恢复事实。"""
+        if checkpoint.backup_staging_dir is not None:
+            return cast(
+                str,
+                await _await_thread_operation(
+                    self.persistent_backup_receipt,
+                    checkpoint,
+                ),
+            )
+        return await self.async_payload_receipt(checkpoint.plugin_id)
+
+    @classmethod
+    def __ignored_receipt_path(cls, path: Path, root: Path) -> bool:
+        """排除不会进入运行载荷和持久备份的派生文件。"""
+        relative_parts = path.relative_to(root).parts
+        return any(
+            part in {"__pycache__", "node_modules", ".DS_Store"}
+            or part.endswith(".pyc")
+            for part in relative_parts
+        )
+
     def install(
         self,
         plugin_id: str,
@@ -115,12 +465,15 @@ class PluginPackageManager:
         force_install: bool = False,
     ) -> tuple[bool, str]:
         """同步安装插件包，下载过程继续复用既有市场兼容策略。"""
-        return self._helper.install(
-            pid=plugin_id,
-            repo_url=repo_url,
-            package_version=package_version,
-            release_version=release_version,
-            force_install=force_install,
+        return cast(
+            tuple[bool, str],
+            cast(Any, self._helper)._PluginHelper__install_package(
+                pid=plugin_id,
+                repo_url=repo_url,
+                package_version=package_version,
+                release_version=release_version,
+                force_install=force_install,
+            ),
         )
 
     async def async_install(
@@ -132,18 +485,21 @@ class PluginPackageManager:
         force_install: bool = False,
     ) -> tuple[bool, str]:
         """异步安装插件包，下载过程继续复用既有市场兼容策略。"""
-        return await self._helper.async_install(
-            pid=plugin_id,
-            repo_url=repo_url,
-            package_version=package_version,
-            release_version=release_version,
-            force_install=force_install,
+        return cast(
+            tuple[bool, str],
+            await cast(Any, self._helper)._PluginHelper__async_install_package(
+                pid=plugin_id,
+                repo_url=repo_url,
+                package_version=package_version,
+                release_version=release_version,
+                force_install=force_install,
+            ),
         )
 
     def sync_local(self, plugin_id: str, source_dir: Path) -> bool:
         """用本地仓库内容原子替换运行副本，失败时恢复原目录。"""
         source_dir = source_dir.resolve()
-        plugin_dir = self._plugin_dir(plugin_id)
+        plugin_dir = self.__plugin_dir(plugin_id)
         if source_dir == plugin_dir:
             return True
         checkpoint = self.checkpoint(plugin_id)
@@ -181,8 +537,8 @@ class PluginPackageManager:
         icon: Optional[str] = None,
     ) -> tuple[bool, str]:
         """复制并改写插件分身文件，任一步失败都删除不完整目标。"""
-        original_dir = self._plugin_dir(plugin_id)
-        clone_dir = self._plugin_dir(clone_id)
+        original_dir = self.__plugin_dir(plugin_id)
+        clone_dir = self.__plugin_dir(clone_id)
         if not original_dir.is_dir():
             return False, f"原插件目录 {original_dir} 不存在"
         if clone_dir.exists():