AsterDock（星栈）

基于 .NET 10 与 Avalonia 12 的 Windows/macOS 跨平台应用容器。容器包含默认主页、窗口、导航和模块加载；发票打印助手、设备信息、网络加速、Android 投屏、串口调试和 U远程作为独立轻应用加载。主页代码与 XAML 直接编译到 AsterDock.Host，启动时始终先显示主页，不依赖 Apps/Home 或单独的 Home.Module.dll。

• 发票打印助手：PDF/图片导入、A4 每页两张预览、虚线分隔及直接打印；打印或手动触发后自动识别每张小票的类型（如 A 类）、金额与编号，支持导出 CSV。
• 设备信息：CPU、GPU、内存、磁盘与网络状态，支持桌面右上角透明常驻监控窗。
• 网络加速：使用 sing-box JSON 订阅，支持规则/全局/直连、TUN 模式、节点切换与延迟测试。
• 主页：常用应用、最近使用、设备概览和容器快捷操作。
• Android 投屏：在应用内显示并控制 Android 设备，支持 USB、无线配对、设备选择、截图与剪贴板；核心自动下载，声音保留在手机。
• VMCUBE：本机 QEMU 虚拟机创建与管理、SSH 远程 KVM 管理，以及内置 SPICE/VNC 桌面控制台。本机模式无需额外服务器或 virsh；远程模式使用目标主机的 virsh。见 VMCUBE。
• 串口调试：支持单口标签页与多口对照、独立的收发 HEX/文本格式、日志过滤、自定义快捷指令、定时发送与停止、Ctrl/⌘ + Enter 发送和工作区配置保存。

容器提供系统托盘入口。关闭主窗口时程序隐藏到托盘；通过托盘可以重新打开星栈、显示或隐藏设备监控窗，选择“退出”才会结束进程。

容器启动后每天至多静默检查一次 AsterDock 官方 GitHub Releases，也可以在“设置 → 软件更新”中手动检查。发现新版本后会按当前系统与架构下载对应的 MSI 或 DMG；安装包必须带有 GitHub Release 提供的 SHA-256 digest，下载完成并校验通过后才会打开系统安装程序。

发布入口是 .github/workflows/release.yml。Nightly 和正式版共用这个文件：Nightly 版本号是 1.0.<该工作流的运行编号>。GitHub 按工作流文件累计这个编号；把定时任务挪到新文件会从 1 重新计数，低于已经发布的 1.0.69，客户端不会把它当成更新。

• Nightly：每天 14:00 UTC。只有最新提交的上海日期是当天才会发布。workflow_dispatch 可以忽略日期补跑，但自动化调用经常收到 403，定时和推送标签更可靠。手动触发也仍然是 Nightly，不会因为当前 ref 是标签就变成正式版。标签形如 v1.0.<运行编号>-nightly-<YYYYMMDD>-<提交号>。更新器只比较第一个连字符前的数字，并与 MSI、DMG 和宿主程序集对齐。只有日期和提交号的旧 nightly-* 标签不能参与比较。
• 正式版：推送干净标签 vMAJOR.MINOR.PATCH（git tag v1.2.3 && git push origin v1.2.3）。带 -nightly-、-rc 或其他后缀的标签不会走正式发布。打标签前可以把发行说明放在 .github/release-notes/vX.Y.Z.md；没有该文件时，正文是安装包清单。

两条路径都会把该 Release 标为 Latest，并共用同一条队列，避免同时改写 Latest。打包任务图在 .github/workflows/package-release.yml。下载文件名与 v1.0.69 相同，包括 AsterDock-win-*.msi、AsterDock-osx-*.dmg、AsterDock-linux-*.deb / .rpm、SHA256SUMS-linux-*.txt、AsterDock-App-<应用 id>.appbundle、app-catalog.json 和 VMCUBE-QEMU-<rid>.zip。

Linux 提供 x64/arm64 的 deb、rpm 安装包，可从 Releases 下载；内置主页，其他轻应用通过应用目录安装。Linux 可检查新版本并打开发布页面，暂不提供自动下载安装。安装包的实际桌面兼容性仍需在目标发行版验证。

应用开发与打包要求请参阅：星栈应用开发规范。

环境要求

• .NET 10 SDK
• Windows 10/11，或受支持的 macOS 版本
• Windows TUN 模式需要在启动加速时允许一次 UAC 提权
• macOS 正式分发需要 Apple Developer 签名与公证

项目不要求预先安装 sing-box。网络加速应用可以在界面内下载与当前平台和架构匹配的核心，并校验官方 Release 资产提供的 SHA-256 摘要。

工程结构

asterdock/
├─ src/
│  ├─ AsterDock.Contracts/  # 容器与应用之间的稳定契约
│  ├─ AsterDock.UI/         # Semi/Ursa 主题、设计令牌与共享控件
│  ├─ AsterDock.Host/       # Avalonia 容器外壳与模块加载器
│  ├─ AsterDock.NetworkElevatedHost/ # Windows TUN 最小权限辅助进程
│  ├─ AndroidScreen.Module/      # 基于 scrcpy 的 Android 投屏与控制
│  ├─ DeviceInformation.Module/  # 设备信息 UI 与透明悬浮窗
│  ├─ DeviceInformation.Core/    # 容器共享的跨平台硬件采集实现
│  ├─ Home.Module/               # 默认主页与容器工作台
│  ├─ InvoicePrinter.Module/     # 可独立加载/打包的发票应用
│  ├─ InvoicePrinter.Core/       # PDF 解析与 A4 排版
│  ├─ NetworkAccelerator.Module/ # sing-box 网络加速 UI 模块
│  ├─ NetworkAccelerator.Core/   # 订阅、配置、核心进程与 Clash API
│  └─ SerialDebugger.Module/     # 多串口调试与联调工作区
├─ scripts/
└─ AsterDock.slnx

运行容器

dotnet run --project src/AsterDock.Host/AsterDock.Host.csproj

首次运行前可以恢复并构建整个解决方案：

dotnet restore AsterDock.slnx
dotnet build AsterDock.slnx -c Release --no-restore

仓库不会提交 bin、obj、artifacts、运行日志、用户配置、订阅内容或本地下载的 sing-box 核心。

从旧版“应用中心”升级时，星栈会在首次访问相应目录时，将 %LOCALAPPDATA%\ApplicationHub（macOS 上对应旧的 Application Support 目录）中的用户应用和模块数据复制到新的 AsterDock 目录。旧目录不会被删除，可用于回退。

构建宿主时，内置应用模块会分别复制到 Apps/InvoicePrinter、Apps/DeviceInformation、Apps/NetworkAccelerator、Apps/AndroidScreen 和 Apps/SerialDebugger。设备信息应用只依赖容器契约；硬件采集实现由宿主统一持有。设备信息应用的核心输出结构为：

AsterDock.Host/bin/<Configuration>/net10.0/Apps/DeviceInformation/
├─ app.json
├─ DeviceInformation.Module.dll
└─ AsterDock.Contracts.dll

宿主不引用具体应用模块，只扫描 Apps 目录下的 app.json，再通过独立 AssemblyLoadContext 加载入口程序集。主页、设备信息页和桌面悬浮窗通过容器提供的同一个 ISystemMetricsService 订阅设备数据；首个订阅者启动采集，全部退订 8 秒后自动休眠。

界面基线由 AsterDock.UI 统一提供：宿主加载 Semi.Avalonia 与 Ursa Semi 主题，模块通过共享控件、App* 设计令牌和 ad-* 语义样式复用页面标题、卡片、分段按钮、状态徽标、紧凑输入等外观。页面只保留业务专属样式。加载状态使用 AdLoadingIndicator / AdLoadingOverlay；错误、确认和短暂提示使用 IApplicationContext.Feedback，说明见 docs/user-feedback.md。

网络加速应用首次使用时，可在页面内点击“安装核心”。应用会从 SagerNet 官方 Release 下载与当前 Windows/macOS 架构匹配的 sing-box 稳定版，并使用 GitHub Release 资产自带的 digest 校验 SHA-256；核心安装在该应用的数据目录，不写入容器安装目录。订阅输入支持 HTTPS 地址或本地 sing-box JSON 配置文件。

Windows 开启 TUN 后，在“开始加速”时会弹出一次 UAC。应用容器本身保持普通权限，只有独立的网络辅助进程和 sing-box 获得管理员权限；停止加速通过受控信号完成，不会再次弹出 UAC。

应用包

开发阶段可以直接放置应用文件夹；分发阶段可以生成 .appbundle（ZIP 格式）：

powershell -ExecutionPolicy Bypass -File scripts/package-invoice-app.ps1 -RuntimeIdentifier win-x64

bash scripts/package-invoice-app.sh Release 1.0.0 osx-arm64

也可以在“设置 → 应用管理 → 发现”中浏览仓库发布的轻应用并直接下载安装。发现页读取最新 GitHub Release 附带的 app-catalog.json，安装时从目录指定的 GitHub Release 下载 .appbundle，校验 Release 的 SHA-256 digest 以及包内 app.json 的应用 id 和版本后再安装。旧 Release 尚未附带目录时，兼容读取仓库根目录的旧目录。

把应用目录或 .appbundle 放入用户应用目录后重启容器：

• Windows：%LOCALAPPDATA%\AsterDock\Apps
• macOS：~/Library/Application Support/AsterDock/Apps

应用包会经过路径与大小检查，安全解包到用户缓存后加载。

发布流程会自动打包 src/*.Module/app.json 中除内置主页之外的所有轻应用，文件名为 AsterDock-App-<应用 id>.appbundle。发布流程从实际包内的清单生成目录，与应用包一起上传到同一个 Release；新增应用、更新版本无需手工维护目录。可在本地打包后生成目录，例如：

python scripts/generate-app-catalog.py artifacts/release/apps --release-tag v1.0.123-nightly-YYYYMMDD-COMMIT

macOS 容器

bash scripts/package-macos.sh osx-arm64
bash scripts/package-macos.sh osx-x64

产物位于 artifacts/macos/<RID>/星栈.app。正式分发前仍需 Apple Developer 证书签名和公证。

主页属于容器内置页面，旧版外部 home 应用包不会覆盖内置主页。启动时会在后台初始化已安装的 U远程，让被控继续按其设置运行，而不切换离开主页。