架构与技术选型
状态:实现基线(2026-10-31)。桌面 UI 以 TKCode.Arc 作为首选组件库,Vox 只维护产品特有的布局与语义扩展。
解决方案结构
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+ sidecarslug.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.AvaloniaEdit12.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,全部通过后再搭正式骨架。