完善安装更新与多系统引导，迁移 APK 依赖并支持视频播放

.github/workflows/build-pages.yml

@@ -69,6 +69,9 @@ jobs:
           git -C third_party/musl rev-parse --verify HEAD
           git submodule status --recursive
 
+      - name: Check both documentation manuals
+        run: python3 tools/test_documentation.py
+
       - name: Import APK signing key
         id: signing_key
         env:

.github/workflows/check-docs.yml

@@ -0,0 +1,53 @@
+name: Check documentation
+
+on:
+  push:
+    paths: &documentation_paths
+      - 'Documentation/**'
+      - 'kernel/reliefnt'
+      - 'Makefile'
+      - 'configs/build-version'
+      - 'scripts/build-docs.sh'
+      - 'scripts/reliefos/Makefile.site'
+      - 'tools/build/docs-page.sh'
+      - 'tools/test_documentation.py'
+      - '.github/workflows/check-docs.yml'
+      - '.github/workflows/build-pages.yml'
+  pull_request:
+    paths: *documentation_paths
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: reliefos-docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        sphinx: ['5.3.*', '7.2.6', '9.*']
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Checkout kernel documentation
+        run: git submodule update --init kernel/reliefnt
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install documentation dependencies
+        run: python -m pip install -r Documentation/requirements.txt 'Sphinx==${{ matrix.sphinx }}'
+
+      - name: Check both manuals and the documentation portal
+        run: python tools/test_documentation.py

.gitmodules

@@ -1,30 +1,15 @@
 [submodule "third_party/litehtml"]
 	path = third_party/litehtml
 	url = https://github.com/litehtml/litehtml.git
-[submodule "third_party/mbedtls"]
-	path = third_party/mbedtls
-	url = https://github.com/Mbed-TLS/mbedtls.git
 [submodule "third_party/busybox"]
 	path = third_party/busybox
 	url = https://github.com/mirror/busybox.git
 [submodule "third_party/pl_editor"]
 	path = third_party/pl_editor
 	url = https://github.com/Leonmmcoset/pl_editor.git
-[submodule "third_party/zlib"]
-	path = third_party/zlib
-	url = https://github.com/madler/zlib.git
-[submodule "third_party/libpng"]
-	path = third_party/libpng
-	url = https://github.com/pnggroup/libpng.git
 [submodule "third_party/stardustui"]
 	path = third_party/stardustui
 	url = https://github.com/xingji-studio/StardustUI.git
-[submodule "third_party/sqlite"]
-	path = third_party/sqlite
-	url = https://github.com/sqlite/sqlite.git
-[submodule "third_party/sl"]
-	path = third_party/sl
-	url = https://github.com/mtoyoda/sl.git
 [submodule "third_party/portablegl"]
 	path = third_party/portablegl
 	url = https://github.com/rswinkle/PortableGL.git
@@ -34,9 +19,6 @@
 [submodule "third_party/mimalloc"]
 	path = third_party/mimalloc
 	url = https://github.com/microsoft/mimalloc.git
-[submodule "third_party/ncurses"]
-	path = third_party/ncurses
-	url = https://github.com/ThomasDickey/ncurses-snapshots.git
 [submodule "kernel/ntclks"]
 	path = kernel/reliefnt
 	url = https://github.com/ReliefOSProject/ReliefNT.git

Documentation/admin-guide/installation.rst

@@ -22,6 +22,9 @@
 引导方式、分区和账户，最后确认安装。TTY 同样在分区之前选择引导方式。
 Xorg 桌面默认安装，也可选择纯控制台系统。
 
+图形向导在语言选择后显示 Apache License 2.0 英文原文，可滚动阅读全文。
+该文本直接取自仓库的 ``LICENSE``，中文界面也保留许可证原文。
+
 新安装默认同时安装 BIOS、UEFI 引导器，可分别取消。两者都取消时不写入
 可直接启动的 loader，必须另行配置引导。自动 GPT 布局根据所选引导方式生成：
 
@@ -61,19 +64,101 @@ AHCI SATA 设备上的专用文件或未挂载分区，再使用 ``mkswap`` 初
 才能执行。``swapoff`` 需要先恢复仍被引用的页面，内存不足时可能失败并保留
 活动区域；不能把失败当成已卸载，也不保证所有后续分配立即成功。
 
+共享 ESP 与多系统
+=================
+
+与已有系统共存时选择手动分区，为 ReliefOS 指定单独的根分区。
+所选根分区会格式化；已有 FAT32 ESP 默认保留，不要求它达到自动方案的
+128 MiB，但必须有足够剩余空间。只有显式勾选格式化 ESP 才会清除其中的
+所有 EFI 文件。TTY 对应 ``format-esp yes`` / ``format-esp no``。
+自动分区仍是明确的整盘擦除方案，不是保留其他系统的并列安装。
+
+新安装将物理 ESP 挂到 ``/efi``，并把
+``/efi/reliefos/instances/<根分区 PARTUUID>`` bind 到 ``/boot``。
+每个实例有独立的 GRUB 配置、根分区绑定、A/B 内核状态和版本文件；
+内核包更新检查实例所有权，拒绝把当前根的内核发布到另一个实例。
+initramfs 在切换真实根之前按 fstab 完成两层挂载。
+
+UEFI 文件位于 ``/EFI/ReliefOS/<根分区 PARTUUID>/grubx64.efi``；
+标准厂商入口 ``/EFI/ReliefOS/grubx64.efi`` 指向一个已有安装，其菜单可选择其他实例。
+已有的其他系统 EFI 文件和未知的 ``/EFI/BOOT/BOOTX64.EFI`` 保持不变。
+只有空的 fallback 路径，或内容摘要和所有权记录均匹配的 ReliefOS fallback，
+才会被安装或更新。固件启动变量和 BootOrder 不由此文件复制过程修改；
+若固件没有显示新入口，使用完成页显示的 EFI 文件路径添加启动项。
+
+GRUB 在启动时枚举其他 ReliefOS 实例；UEFI 菜单识别常见的 Windows、
+shim/GRUB 和 systemd-boot 文件，BIOS 菜单支持 Windows 分区引导及其他
+系统的 GRUB 配置。其他系统的配置只在用户选择相应条目后执行。
+BIOS 安装会替换所选整盘的主引导代码；只需 UEFI 共存时可取消 BIOS。
+旧预制磁盘若没有 ESP 上的 ``core.img`` 副本，更新器会校验 MBR 中的
+GRUB 核心位置及 BIOS Boot 分区内的块列表，识别实际嵌入的引导器。
+新预制镜像同时保存该副本，保持与安装器生成的布局一致。
+
+Live 只有一个普通启动项。安装介质保留图形和控制台两个安装入口；
+磁盘保留普通启动及高级选项中的日志暂停、关闭内核日志颜色和有效旧内核回退。
+不再展示失效的 debug/autospawn 参数、重复日志条目或同内核副本伪装的回退。
+ISO 优先从固件交接的实际介质加载菜单，Live 与 Installer 的后备标记相互独立。
+
+独立磁盘镜像身份
+================
+
+``IMAGE_INSTANCE_ID``（也可在 menuconfig 中设置 ``DISK_INSTANCE_ID``）
+决定预制磁盘的 GPT 磁盘和分区身份，并同步生成 fstab、GRUB 根绑定和查找标记。
+同一输入、同一实例标识保持可重现；需要同时连接的镜像应使用不同标识，例如::
+
+    make O=out/desktop-a defconfig
+    make O=out/desktop-a IMAGE_INSTANCE_ID=desktop-a image-vmdk
+    make O=out/desktop-b defconfig
+    make O=out/desktop-b IMAGE_INSTANCE_ID=desktop-b image-vmdk
+
+逐字节复制一张已有磁盘仍会复制其 UUID，不能把这样的副本当作独立安装同时连接。
+正式安装到不同根分区时使用各自 GPT 身份，不依赖预制镜像的实例标识。
+
+
 更新已有系统
 ============
 
 更新不自动重分区。旧两分区 UEFI 磁盘保持原有布局，缺少 BIOS Boot
 空间时增加 BIOS 引导的请求应在写入前失败。先备份用户文件和引导分区，
-检查已安装 APK 数据库、信任密钥及所选更新介质。
-磁盘探测完成后进入引导方式页，默认选中已检测到的引导器，再进入更新确认页；
-返回引导方式页不会覆盖用户刚修改的选择。未选中的现有引导器会保留。
+检查已安装 APK 数据库、信任密钥及所选更新介质。正常关闭已安装系统后，
+再从安装介质启动。
+在安装器中选择更新和目标磁盘后，独立的后台进程只读检查已安装系统、桌面
+类型、软件包数据库、安装介质和空间。确认页列出当前版本、介质版本、根分区、
+ESP 和空间需求，并默认选中已检测到的 BIOS/UEFI 引导器。核对后点击更新。
+同盘有多个安装时，可在目标磁盘页选择明确的根分区和 ESP；留空 ESP 时读取
+所选根的 fstab，不能简单取磁盘上第一个 ESP。显式选择与该根的 fstab 不一致时
+拒绝更新，避免把引导文件写到其他系统的分区。旧的 ``/boot`` 直接挂载 FAT32
+布局继续兼容，更新不强制改变现有挂载布局。
+旧布局中未能通过所有权验证的现有 EFI 可执行文件及相邻配置会保留，
+不会因系统更新而覆盖。兼容命令 ``reliefos-grub-installer`` 现直接转交原生
+CLI，需要明确的 ``--disk``、``--boot-directory`` 和根分区身份；
+不再接受无法绑定安装实例的旧式单个 ESP 路径复制操作。
+TTY 入口使用相同的后端，并在显示摘要和引导选项后通过 ``y/N`` 确认。
+
+检查过程使用私有 APK 数据库和已安装系统的信任密钥，验证签名索引、完整
+软件包归档以及离线依赖。确认后的执行会再次核对磁盘、分区 UUID、索引和
+已安装包数据库及 world 选择；目标已经变化时需要重新检查。已被其他路径挂载的分区、
+无法唯一识别的根分区或 ESP，以及早于已安装系统的介质会在写入前被拒绝。
 
 根文件系统使用 APK 更新，保留外部包、world 选择和受保护配置；新默认配置
 可能以 ``.apk-new`` 出现。根事务成功后才发布引导文件。
+离线更新只从安装介质的签名仓库取得新软件包。``world`` 中已有的
+``@testing``、``@alpine`` 等标签在本次事务的私有配置中注册到该仓库，
+使已安装的外部软件包可以继续满足依赖，不要求原仓库在线或保留索引缓存。
+原有仓库配置和标签选择保持不变；介质和已安装软件包无法满足的版本约束
+仍会在预检查时拒绝，不会强制忽略依赖。
 更新保留现有 fstab 和 swap 设置，不会自动添加或更改交换文件。
+更新详情显示软件包和引导操作的实际输出，完整日志位于安装器运行环境的
+``/var/log/installer-update.log``。失败页面提供重新检查入口。
+
+目标系统的 ``/var/lib/reliefos/installer-update/state`` 持久记录软件包、根同步、
+引导提交和完成阶段。同一介质的引导提交失败后，重新检查会核对已完成的根
+事务，再继续引导提交；软件包阶段失败则重新预检并执行包事务。旧内核模块
+保留与 A/B 内核发布继续使用共同的原生引导接口。更新期间由独立进程持有
+安装器更新锁，释放目标挂载后才报告完成。APK 已记录为损坏的系统包会先通过
+已验证的归档执行定向修复，再执行升级；已有的外部包错误保留并在日志中说明。
+
 单文件原子替换不等于全部包、ESP 和 BIOS 写入的整体断电原子事务。
-旧回滚内核可能不认识 PARTUUID，不能假定所有旧菜单都能自动恢复。
+回退条目只使用通过完整性检查的匹配内核与 initramfs，不把当前内核的别名当作回退。
 
 运行验证和未覆盖范围见 :doc:`limitations`。

Documentation/admin-guide/packages.rst

@@ -23,6 +23,23 @@
 同名外部命令使用 GNU 入口，旧路径由 APK 管理并转发；详情与验收方法见
 :doc:`coreutils`。
 
+基础依赖
+========
+
+sl、ncurses、zlib、libpng、SQLite、mbedTLS 3 由签名 Alpine APK 提供。
+系统直接请求官方命令、终端工具/数据和 SQLite 命令/运行库，不再生成本地包装包。
+文件所有权可通过
+``apk info --who-owns /usr/bin/sl``、``/usr/bin/tput``、``/usr/lib/libsqlite3.so.0`` 查询。
+离线更新器在预检时将旧包装包的 world 请求转换为官方包，保留其他包和配置；
+正式事务自动卸载旧包，完成后清除离线缓存中的旧包装包归档。
+新的自有包使用第 4 代版本前缀，保证从第 2、3 代包按正常版本顺序升级。
+旧的 ``sqlite.so.3`` ABI 已移除。
+依赖旧自定义 SQLite VFS 或厂商内部符号的外部程序需要重新编译。
+
+RPR 本地发布树继续包含完整的签名索引、原始上游 APK 和自有包，构建
+``rpr-pages`` 不等于部署到线上。运行库因新增 ELF NEEDED 而得到真实 APK
+依赖，不能只复制新的 ``libreliefos.so.2`` 而遗漏配套库。
+
 内核与模块更新
 ==============
 

Documentation/applications/reliefplayer.rst

@@ -2,20 +2,22 @@
 ReliefPlayer
 ============
 
-ReliefPlayer 是独立的 FLTK 本地音频播放器，位于“网络和多媒体”应用分组，
+ReliefPlayer 是独立的 FLTK 本地音视频播放器，位于“网络和多媒体”应用分组，
 不属于 ReliefOffice。使用系统中文字体和 FLTK 默认 gtk+ 控件。
 
 .. code-block:: sh
 
     reliefplayer
     reliefplayer /home/test/music.mp3
     reliefplayer /home/test/recording.wav
+    reliefplayer /home/test/movie.mp4
 
-点击“打开音频”选择文件，打开后自动播放。支持播放/暂停、停止、拖动进度、
+点击“打开媒体”选择文件，打开后自动播放。支持播放/暂停、停止、拖动进度、
 前后跳转 10 秒、软件音量和静音。窗口显示文件名、格式、采样率、声道、位深、
-已播放时间和总时长。文件管理器中的 MP3、WAV 默认使用本程序打开。
+已播放时间和总时长。MP4 视频在窗口中保持比例显示，支持常见的直角旋转元数据。
+文件管理器中的 MP3、WAV、MP4 默认使用本程序打开。
 
-- Ctrl+O：打开音频。
+- Ctrl+O：打开媒体。
 - 空格：播放或暂停。
 - 左右方向键：前后跳转 10 秒。
 - Home：回到开头。
@@ -31,15 +33,31 @@ MP3 使用仓库已有 minimp3，支持单/双声道 MPEG Layer III，包括可
 首次打开扫描帧索引以确定总时长，定位时预解码恢复状态。时间按音频帧统计，
 不裁切编码器延迟和尾部 padding。会跳过 ID3 和 APEv2 标签边界，
 不读取封面或展示标签信息。
-APEv2 边界布局参考 `FFmpeg 的官方实现 <https://www.ffmpeg.org/doxygen/4.2/apetag_8c_source.html>`_，
-不引入 FFmpeg 作为运行时依赖。
+APEv2 边界布局参考 `FFmpeg 的官方实现 <https://www.ffmpeg.org/doxygen/4.2/apetag_8c_source.html>`_。
 
 WAV 支持 RIFF 中的单/双声道 PCM 8、16、24、32 位和 IEEE float32；
 支持容器位深与有效位深相同的对应 WAVE_FORMAT_EXTENSIBLE 子格式。
 采样率范围 8–192 kHz，不支持其他 WAV 压缩编码、RF64 或多声道源文件。
 最多打开 2 GiB 的文件；MP3 索引最多 100 万帧。
 
+MP4 使用锁定的官方 FFmpeg 8.1.3 LGPL 精简共享库，支持 H.264、MPEG-4 Part 2、
+HEVC 视频及 AAC、MP3 音轨；音频最多 8 声道，转换为 48 kHz 立体声。
+无音轨的视频使用单调时钟播放，不需要打开音频设备。含音轨的视频按音频设备
+已经播放的帧同步画面，定位会刷新解码器并丢弃关键帧到目标位置之间的预解码数据。
+不支持的编码、损坏文件和解码失败会报告错误。
+
+视频使用软件解码，源画面最多 4096 × 2160，显示快照最多 1280 × 720 像素
+（竖屏时可交换边长）。不含硬件加速、HDR 色调映射、字幕或多音轨选择；
+高分辨率视频的流畅程度取决于虚拟机性能。
+
+``make fetch`` 下载锁定源码，``upstream-ffmpeg`` 离线构建五个解码共享库。
+播放器启用时，运行库及 LGPL 许可证随 ``reliefos-media-codecs`` APK 一起进入镜像；
+开发头文件留在独立构建目录。库名及 SONAME 带有 ``-reliefplayer`` 后缀，
+可以与 Alpine 的完整 FFmpeg/VLC 依赖共存。FFmpeg 不构建命令行程序、网络协议或外部编码器。
+
 解码、文件读取和音频写入由独立子进程执行，GUI 通过非阻塞管道控制。
+视频通过有界共享内存发布 RGB 快照，GUI 保存自己的画面副本；双方只尝试获取
+复制锁，不等待对方，也不在锁内读文件或解码。
 采样率和设备不同时使用线性插值；设备输出为 S16_LE，使用前置立体声，
 额外硬件声道置零。非阻塞短写、设备回压和排空均保留未完成数据；
 播放失败不会把进度伪装为完成。设备连续 5 秒既无写入也无播放进展时报告错误。

Documentation/kbuild/building.rst

@@ -17,6 +17,12 @@ Clang 必须包含 x86_64 compiler-rt builtins。典型 Debian/Ubuntu 依赖为:
 HTML 文档另需 Sphinx，见 :doc:`../process/documentation`。Sphinx 仅服务文档；
 内核和用户态生产编译不因此改用 Python、Meson 或 Ninja。
 
+``make test-build`` 中的播放器宿主检查另需 ``ffmpeg``、``libavformat-dev``、
+``libavcodec-dev``、``libavutil-dev``、``libswresample-dev`` 和 ``libswscale-dev``。
+这些是宿主检查依赖；生产播放器使用锁定源码构建的 musl 库。
+可通过 ``PLAYER_TARGET_BUILD=/绝对路径/out/x86_64/release sh tests/build/test-reliefplayer-mp4.sh``
+在 Linux 宿主上同时运行实际精简库和 musl 版本的解码/控制检查；这不等于来宾播放验证。
+
 构建顺序
 ========
 

Documentation/kbuild/sdk.rst

@@ -7,7 +7,7 @@ SDK 与用户态移植
 
 SDK 为可重定位 musl sysroot，C 驱动 ``reliefos-musl-cc`` 按自身位置找头与库。
 验证时必须真正编译、链接和运行适当探针，覆盖带空格的重定位路径、动态与
-``STATIC=1``；成功列出归档成员不能替代消费验证。
+``-static``；成功列出归档成员不能替代消费验证。
 公开头通过白名单导出，不复制内核私有头。
 
 库与 ABI
@@ -17,3 +17,9 @@ SDK 为可重定位 musl sysroot，C 驱动 ``reliefos-musl-cc`` 按自身位置
 装载依赖，不用宿主 glibc 库冒充目标产物。旧库与旧转发头的兼容范围见
 :doc:`../userspace-api/abi`。新接口需同步公开头、运行库、内核实现、消费者、
 头导出及包归属，不能只改声明。
+
+SDK 同时携带锁定版本的 zlib、libpng、SQLite、mbedTLS 3 头文件、动态库和静态库。
+驱动为扩展库补全 PNG、zlib、mbedTLS 的传递链接依赖；直接使用 SQLite 的程序
+仍需传入 ``-lsqlite3``。开发包的来源元数据位于 ``share/reliefos/sdk/apk``，
+许可位于 ``share/licenses``。所有 mbedTLS 消费者必须使用随包配置头，不能使用
+旧私有 ``MBEDTLS_CONFIG_FILE`` 配置改变结构布局。