Merge remote-tracking branch 'origin/v3' into codex/optimize-pr-6849

# Conflicts:
#	docs/architecture-overview.md
#	docs/refactor/optimization-checklist.md
#	tests/fixtures/architecture/dependency-baseline.json

scripts/bootstrap-local.sh

@@ -457,6 +457,24 @@ ensure_python() {
   fi
 }
 
+# 一键安装准备本机编译器；扩展失败只降级检索，不阻断主程序安装。
+ensure_cjk_compiler() {
+  if command -v cc >/dev/null 2>&1 || command -v gcc >/dev/null 2>&1 || command -v clang >/dev/null 2>&1; then
+    return 0
+  fi
+  case "$PACKAGE_MANAGER" in
+    apt-get) install_system_packages build-essential ;;
+    dnf|yum|zypper) install_system_packages gcc glibc-devel ;;
+    pacman) install_system_packages base-devel ;;
+    apk) install_system_packages build-base ;;
+    brew)
+      echo "中文索引扩展需要 Xcode Command Line Tools，请执行 xcode-select --install 后重试 moviepilot install cjk。" >&2
+      return 1
+      ;;
+    *) return 1 ;;
+  esac
+}
+
 ensure_prereqs() {
   if [[ "$OS_NAME" == "Windows" ]]; then
     echo "检测到当前环境为 Windows shell，建议改用 WSL、Linux 或 macOS 终端运行。" >&2
@@ -467,6 +485,9 @@ ensure_prereqs() {
     python_install_hint
     exit 1
   fi
+  if ! ensure_cjk_compiler; then
+    echo "C 编译器尚未就绪，Agent 中文检索将暂用回退路径；安装后可用 moviepilot install cjk 补装。" >&2
+  fi
 }
 
 prompt_text() {

scripts/local_setup.py

@@ -2969,12 +2969,29 @@ def install_deps(*, python_bin: str, venv_dir: Path, recreate: bool) -> Path:
         else:
             expose_uv_to_venv(uv_bin, venv_dir)
         install_browser_runtime(venv_python)
+        install_cjk(venv_python, required=False)
         return venv_python
     finally:
         if temporary_uv_dir is not None:
             temporary_uv_dir.cleanup()
 
 
+def install_cjk(venv_python: Path, *, required: bool = True, check: bool = False) -> None:
+    """由目标解释器安装和验收扩展；自动安装失败明确告警，单独补装失败返回错误。"""
+    command = [str(venv_python), str(ROOT / "native/fts5_cjk/install.py")]
+    if check:
+        command.append("--check")
+    try:
+        result = subprocess.run(command, check=True, capture_output=True, text=True, timeout=180, cwd=ROOT)
+        print_step(result.stdout.strip())
+    except (OSError, subprocess.SubprocessError) as error:
+        detail = error.stderr.strip() if isinstance(error, subprocess.CalledProcessError) and error.stderr else str(error)
+        message = f"CJK 扩展安装/检查失败：{detail}"
+        if required:
+            raise RuntimeError(message) from error
+        print_step(f"{message}；历史检索暂用 trigram/LIKE 回退，可运行 moviepilot install cjk 重试")
+
+
 def install_browser_runtime(venv_python: Path) -> None:
     """
     预下载 CloakBrowser 浏览器内核，避免首次仿真登录时才拉取大文件。
@@ -3785,6 +3802,7 @@ def uninstall_local(
 
 
 def _git_output(*args: str) -> str:
+    """读取当前源码仓库的 Git 命令输出。"""
     return capture(["git", *args], cwd=ROOT)
 
 
@@ -3822,14 +3840,16 @@ def _ensure_git_clean() -> None:
 
 
 def _update_backend_ref(ref: str, *, fetch: bool = True) -> str:
-    """同步后端 Git 引用；分支快进到远端，离线标签不访问网络。"""
+    """同步后端 Git 引用；在线强制同步标签、分支仅快进，离线不访问网络。"""
     if not (ROOT / ".git").exists():
         raise RuntimeError("当前目录不是 Git 仓库，无法更新后端代码。")
 
     _ensure_git_clean()
     if fetch:
         print_step("获取远端更新")
-        run(["git", "fetch", "--tags", "origin"], cwd=ROOT)
+        run(["git", "fetch", "--no-tags", "origin"], cwd=ROOT)
+        # Release 重建可能移动同名标签；强制覆盖仅用于标签引用。
+        run(["git", "fetch", "--no-tags", "origin", "+refs/tags/*:refs/tags/*"], cwd=ROOT)
     else:
         # Release 下载阶段已获取并验证标签，重启安装不得再次依赖网络。
         run(
@@ -3992,6 +4012,10 @@ def build_parser() -> argparse.ArgumentParser:
         "--config-dir", help="配置目录，默认使用程序目录外的系统配置目录"
     )
 
+    cjk_parser = subparsers.add_parser("install-cjk", help="补装并验证 Agent 中文全文索引扩展")
+    cjk_parser.add_argument("--venv", default=str(ROOT / "venv"), help="目标虚拟环境目录")
+    cjk_parser.add_argument("--check", action="store_true", help="只验证已安装扩展，不编译或修改文件")
+
     frontend_parser = subparsers.add_parser(
         "install-frontend", help="下载前端 release 并安装本地运行时"
     )
@@ -4218,6 +4242,10 @@ def main() -> int:
     )
 
     try:
+        if args.command == "install-cjk":
+            install_cjk(get_venv_python(Path(args.venv).expanduser().absolute()), check=args.check)
+            return 0
+
         if args.command == "install-deps":
             venv_python = install_deps(
                 python_bin=args.python,