维声 文档
dotnet9
维声 / 文档 / 架构与技术选型

架构与技术选型

⏱ 预计阅读 6 分钟 平台:windows / macos / linux 同步于 2026-11-08 来源: Vox · docs/架构.md ✎ 在 GitHub 编辑此页

状态:实现基线(2026-10-31)。桌面 UI 以 TKCode.Arc 作为首选组件库,Vox 只维护产品特有的布局与语义扩展。

解决方案结构

text
Vox.slnx
├── src/
│   ├── Vox.Core   ← 纯逻辑,零 Avalonia 依赖,全部可单测
│   ├── Vox.Git    ← git 能力层,隔离原生与外部进程细节
│   └── Vox.App    ← Avalonia 桌面壳
└── tests/
    ├── Vox.Core.Tests
    └── Vox.Git.Tests

三项目起步,痛了再拆。不引入 Prism.DryIoc 等重量级框架,DI 用 Microsoft.Extensions.DependencyInjection。

Vox.Core

  • 中立领域模型:Article、ArticleMeta、ImageAsset、SiteData——不含 yml/路径等仓库细节,UI 与业务只面对这些类型(决策 D4)
  • 仓库画像(RepoProfile):CodeWF 的目录约定(YYYY/MM/slug.md + sidecar slug.yml)、元数据字段、图片映射规则,写死但隔离在此模块,为第二目标"通用文章管理器"留抽取缝
  • 扫描与索引:全库扫描建内存索引(536 篇文章 / 4200+ 图规模完全可内存承载)+ FileSystemWatcher 增量维护
  • 链接策略:相对路径 ↔ CDN URL 双形态模型、互转、首选形态配置
  • 体检规则引擎:规则可注册、可批量执行、产出结构化问题(定位 + 修复建议),输入来自索引
  • 图片入库规则:slug 前缀命名、年月目录落位、封面字段回写

Vox.Git

  • LibGit2Sharp 为基座:status / 暂存 / 提交 / 历史 / diff / HTTPS+PAT 推送,进程内完成
  • SSH 推送降级:优先调用系统 PATH 中的 git(复用用户既有密钥配置),其次使用随 Vox 分发的 MinGit(Git for Windows 官方免安装精简版,含 OpenSSH,仅 Windows 捆绑;Linux/macOS 使用发行版包管理器安装的系统 git)
  • 凭据:PAT 存操作系统级凭据库(ICredentialStore 抽象:Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service,后者缺席时回退加密文件并提示),不进仓库、不上传(决策 D5)

Vox.App

  • 壳与导航:左导航七页(见 信息架构.md),优先采用 Arc 组件与主题;Arc 未覆盖的产品专属结构才用 Avalonia 原生控件组合。Arc Foundation 主题(强调色 / 明暗 / 动效级别);Vox 自有 Arc/Pixel 风格由 VoxTheme 令牌控制,Pixel 模式只改变 Vox 自有控件圆角,不覆盖 Arc 控件模板
  • 预览:CodeWF.Avalonia.Markdown MarkdownViewer + 增量渲染;相对路径图片按当前 Markdown 文件目录解析;MarkdownTypographyThemes 使用 CodeWF.Avalonia 自带排版主题,与 Arc 主题分别管理
  • 编辑器:AvaloniaEdit(Vex 同款,Avalonia.AvaloniaEdit 12.0.0 已在 Avalonia 12.1.4 + NativeAOT 生产验证)+ TextMate 插件(与 StreamMark 同源 TextMateSharp,编辑/预览高亮一致)——TextMate 版本对齐待 spike。集成注意(Vex 踩过的坑):AvaloniaEdit 的 Simple 主题要求宿主主题提供字体令牌,Arc 主题下需像 Vex 那样自行补齐
  • MVVM:CommunityToolkit.Mvvm(源生成器、AOT 友好)

依赖与锁版

依赖 版本 说明
.NET net11.0 SDK 由 global.json 固定;框架默认值见 build/ProjectDefaults.props
Avalonia 12.1.5 官方 Arc 当前精确要求 12.1.4,保留 NU1608 并验证兼容性
TKCode.Arc(+Fonts/Icons.Lucide) 0.3.2-preview.2(以 build/Versions.props 为准) 只使用官方 NuGet,不从源码构建;WithArcFonts() + UseArc(arc => arc.UseArcControls().WithTheme(...)) 注册
CodeWF.Avalonia.Markdown / MindView build/Versions.props 中的统一候选版本 固定源码提交重建自研 NuGet;MarkdownFullThemes 与 MindViewThemes 独立加载
AvaloniaEdit + AvaloniaEdit.TextMate 12.0.0 TextMateSharp 统一 2.0.4(与 StreamMark 依赖链同源,Spike #2 已收敛)
CodeWF.Toolkit.Lang / Avalonia.Lang(.Generator) 1.1.2 / 统一自研候选版本 界面 i18n:JSON 资源 + I18n 标记扩展 + 编译期强类型键(决策 D13)
YamlDotNet 18.1.0 slug.yml sidecar 读写(收拢在 Vox.Core)
LibGit2Sharp 0.32.0 自带各 RID 原生 libgit2
CommunityToolkit.Mvvm 8.4.2

Arc 控件使用约定

  • 先查 Arc,再写控件:新增或重构 UI 前,先查 Arc AI 入口、TKCode.Arc 技能 与在线 Gallery;按需查看 components.md、checklist.md。
  • 优先级:Arc 现成组件 > Avalonia 原生控件(仅用于 Arc 未覆盖或不适合的场景)> Vox 自定义控件。不得为了快速实现而复制 Arc 已有控件的模板、动效或交互。
  • 样式边界:Arc 控件使用 Arc 自身的设计令牌与主题(ArcTokens.Bind / ArcDesignTokenResource);VoxStyles.axaml 只为 Vox 自有语义类(如 .btn、.vinput、.navit)提供样式,不用宽泛选择器覆盖 Arc 控件默认模板。
  • 注册入口:统一在 Program.BuildAvaloniaApp() 中调用 WithArcFonts()、UseArc(arc => arc.UseArcControls());不要在页面或 App.axaml 再注册一遍。
  • 控件命名冲突:Arc 的 Button、Calendar、TreeView、DatePicker 等与 Avalonia 同名时,用命名空间别名明确选择,不依赖 using 顺序。
  • 动效与主题:明暗、Arc 强调色和动效级别走 ArcTheme.Apply(...) / ArcMotion;产品自有语义色、密度和 Arc/Pixel 风格通过 VoxTheme 桥接,避免两套 token 各自漂移。
  • 复用现状:写作模式切换、发布中心分页、MCP 分页和标题栏外观选项(Arc/Pixel、密度、明暗、动效)已使用 Arc SegmentedControl;图标使用 TKCode.Arc.Icons.Lucide。

约束:Arc 大量控件与 Avalonia.Controls 同名(Button、Calendar、TreeView、DatePicker 等),同文件需命名空间别名;不可启用 InvariantGlobalization;目标 NativeAOT 零警告(StreamMark 的 CI 门槛标准)。

跨平台(五 RID)

目标平台:win-x64、linux-x64、linux-arm64、osx-x64、osx-arm64。

依赖就绪度:Arc 声明支持 Windows/macOS/Linux 桌面;StreamMark 的 RaTeX 原生库自带 win/linux/osx × x64/arm64;LibGit2Sharp 自带各 RID 的 libgit2;AvaloniaEdit 为纯托管控件。TextMateSharp(Oniguruma)的原生覆盖在 CI 中例行验证即可。

平台差异处理:

事项 Windows Linux / macOS
凭据存储 凭据管理器 macOS 钥匙串 / Linux Secret Service;缺席回退加密文件
git 降级推送 捆绑 MinGit 系统 git(包管理器几乎必有),缺失则提示安装
字体 Geist / Inter 随包分发,无系统字体依赖(全平台一致) 同左

发布与安装:本地仅构建 win-x64 NativeAOT;五平台由 GitHub Actions 原生 runner 在 release tag 触发。分发只走 GitHub Releases(决策 D11),安装/卸载遵循各平台惯例(原型:design/安装器-*.html / 卸载-*.html):Windows 为 Arc 品牌自绘向导(捆绑 MinGit);macOS 为标准 DMG 拖拽安装(DMG 背景图品牌位,签名 + 公证),卸载即拖入废纸篓、不内置卸载器;Linux 的 .deb / .rpm 由系统软件中心与包管理器接管,另有 AppImage 通用包。应用内「检查更新」从 Releases 下载新版本替换,不经应用商店。品牌资产 logo.svg / png / ico 在仓库根目录统一维护(决策 D12)。

链接策略管线

同一图片两种合法形态,映射规则:https://img1.dotnet9.com/<路径> ↔ 仓库文件 <路径>。

  • 编辑期:插入相对 md 文件目录的路径(同年月即文件名,跨目录 ../);预览按文章目录为基准解析本地文件(StreamMark ImageBaseUri 随文章切换)
  • 发布期:改写为 CDN URL——改写时机待定(开放问题 #2:若站点端能解析相对路径则可省略;否则在 git push 前由 Vox 完成改写)
  • 体检:两种形态均合法,按设置的"首选形态"提示规范化,提供批量互转命令

性能与规模假设

  • 单仓库 ≤ 数千文章、≤ 数万图片:全量内存索引 + 后台增量,无数据库(M3 的 SQLite 仅用于发布状态)
  • 图片缩略图按需生成并缓存,不阻塞列表

动工前验证

见 技术验证Spike.md——4 个半天级 spike,全部通过后再搭正式骨架。