维声 文档
dotnet9
维声 / 文档 / 决策记录(ADR-lite)

决策记录(ADR-lite)

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

记录关键决策的背景与理由,避免将来"当时为什么这么定"失忆。格式:背景 → 决策 → 代价/备选。

D1 · 不做国际化(2026-10-23)

  • 背景:Assets.Dotnet9 的 site/ 下有 zh-CN/en/ja/zh-tw 四份数据,多语言文件系早期 AI 生成,无实际意义。
  • 决策:仓库按纯 zh-CN 对待;en/ja/zh-tw 文件不在 Vox 计划内,由作者后续批处理删除。
  • 代价:若未来重启多语言,站点数据模块需重开多语言视图。

D2 · 技术底座 = TKCode.Arc + StreamMark(2026-10-23)

  • 背景:Vex 系(CodeWF.Avalonia / CodeWF.Toolkit / Semi.Avalonia / Ursa.Avalonia)是旧技术路线;Arc 提供 Avalonia 原生组件 + 独立 Foundation 主题 + 动效,StreamMark 提供高性能 Markdown 预览(RefreshMarkdown 增量刷新、源码偏移映射、任务复选框、NativeAOT 零警告门槛)。
  • 决策:Vox 使用 TKCode.Arc 与 CodeWF.Avalonia 的 Markdown/MindView 控件,与 Vex 技术栈保持产品独立。Arc 版本随上游升级,Markdown 与脑图由 CodeWF.Avalonia 包提供。
  • 代价:两库均处 preview 期,API 会变;Avalonia 12.1.4 被 Arc 精确锁定。

D3 · Vox 定位"完整写作环境",与 Vex 独立(2026-10-23)

  • 背景:"VS Code 直接开仓库就能改文件,为什么要用 Vox?"
  • 决策:Vox 的价值 = VS Code 做不到的四层:图片入库管线、仓库语义视图、体检与修复、发布闭环。编辑动作与仓库知识焊在一起(改封面是点击动作,不是编辑 yml)。Vox 做好了可完全不用 Vex。
  • 代价:纯 md 源码编辑体验不追平 VS Code,不以此为设计目标。

D4 · 仓库画像先写死 CodeWF,领域模型保持中立(2026-10-23)

  • 背景:第一目标只有一个仓库(n=1),第二目标是通用文章管理器。第一天就抽象有"凭一个样本猜错抽象形状"的风险。
  • 决策:中间路线——CodeWF 规矩(目录约定、sidecar yml、图片映射)写死但隔离在 Vox.Core 的画像模块;内部类型中立(Article 而非 YmlSidecar),yml 读写收拢独立。将来抽接口只换隔离模块,UI 与业务零改动。
  • 备选:day-1 IRepoProfile 接口化(推迟,等见过第二个仓库再抽)。

D5 · git 内置,分层降级(2026-10-23)

  • 背景:站点直接读仓库,git push 即"发布";写作流要闭环到"推完网站就更新",且不能要求用户安装 git。
  • 决策:LibGit2Sharp 为基座(本地操作 + HTTPS+PAT 推送);SSH 推送降级调外部 git——优先系统 PATH 已装的 git,其次随 Vox 分发的 MinGit(官方免安装精简版,含 OpenSSH,本机无需安装)。凭据存操作系统级凭据库(ICredentialStore:Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service,缺席回退加密文件)。
  • 代价:LibGit2Sharp 的 SSH 支持弱,故 SSH 走外部进程;MinGit 增加安装包体积(仅 Windows)。

D6 · 图片是一等公民,链接双形态(2026-10-23,经作者确认修订)

  • 背景:"站点直接读仓库,git push 即发布";仓库即图床(img1.dotnet9.com ↔ 仓库路径一一对应),4203 张图 vs 536 篇文章;存量 527 孤儿图、58 死链。
  • 决策:图片库独立成页;正文图片引用以「相对 md 文件所在目录」的路径为唯一规范形态(同年月即文件名,跨目录 ../ 形态),CDN 域名是可配置的投影,站点渲染时按域名拼接,Vox 不在发布期改写正文(原"发布期改写 CDN"取消,同时回答需求开放问题 #2);存量 CDN URL 经设置页「整库规范化」改写为相对路径;体检的引用面包含 site 数据防误报。
  • 代价:需要一次整库规范化把存量 CDN URL 清干净,否则两种形态会并存一段时间。

D7 · 删除永远走 git(2026-10-23)

  • 背景:存量治理需要删除低质/过期文章与孤儿图。
  • 决策:删除 = git 暂存变更 → 预览 → 提交 → 推送,全程可回滚;无"确认删除?"式物理删除。
  • 代价:依赖内置 git 层的可靠性(先过 spike)。

D8 · 存量治理:系统给线索,人工拍板(2026-10-23)

  • 背景:"过期技术 / 低质文章"无法可靠自动判定。
  • 决策:体检只提供线索列表(年份、字数、引用数、缺口),作者用文章级标记(重写/退役/删除)逐篇决策;批量仅限无争议项(如扩展名配对修复、专辑补全确认)。

D9 · MVVM = CommunityToolkit.Mvvm + MEDI(2026-10-23)

  • 决策:不引入 Prism.DryIoc/ReactiveUI(旧 README 遗留口径);源生成器 + AOT 友好 + 依赖注入用 Microsoft.Extensions.DependencyInjection。

D10 · 编辑器 = AvaloniaEdit + TextMate(2026-10-23,经 Vex 预验证)

  • 背景:StreamMark 是只读渲染器,明确"从不编辑源文本";编辑器曾选型悬空。经查证 Vex 生产代码:Avalonia.AvaloniaEdit 12.0.0 已在 Avalonia 12.1.4 + NativeAOT(win-x64 本地发布)下稳定使用,兼容性顾虑消除;Vex 的着色走 CodeWF.Avalonia.Markdown 自研 highlighting,未用 TextMate。
  • 决策:AvaloniaEdit + TextMate 插件(与 StreamMark 同源 TextMateSharp,编辑/预览高亮一致)。集成注意:AvaloniaEdit 的 Simple 主题要求宿主提供字体令牌(Vex 的 App.axaml 有现成处理先例)。
  • 剩余风险:仅 TextMate 插件与 Arc 依赖链的 TextMateSharp 版本对齐,见 技术验证Spike.md。

D11 · 分发只走 GitHub Releases,安装体验按平台惯例(2026-10-23,经评审修正一次)

  • 背景:需要分发渠道可控与品牌一致;应用商店审核重、约束多。初版曾定"三平台全 Arc 品牌自绘安装器",评审后修正:在 macOS / Linux 上自绘安装向导反而在目标平台显得不正规。
  • 决策:三平台全部经 GitHub Releases 分发(不经应用商店),但安装/卸载遵循各平台惯例:
    • Windows:Arc 品牌自绘向导(Windows 惯例即品牌化安装器),捆绑 MinGit,卸载器含"保留用户数据"选项;
    • macOS:标准 DMG 拖拽安装(DMG 背景图为唯一品牌位,这是惯例允许的),签名 + 公证;卸载 = 拖入废纸篓,不内置卸载器,残留清理写文档提供命令;
    • Linux:系统软件中心 / 包管理器接管(.deb / .rpm,软件中心内呈现常规页面),另有 AppImage 通用包;无自绘安装/卸载器;
    • 更新统一由应用内「检查更新」从 Releases 下载替换。
  • 代价:macOS 需长期维护 Developer ID 签名与公证;Windows SmartScreen 信誉需安装量积累;放弃商店流量入口;品牌表达被限制在安装包图标、DMG 背景与软件内。

D12 · 品牌资产根目录单一维护(2026-10-23)

  • 决策:logo.svg / logo.png(512)/ logo.ico(16–256 多尺寸)放仓库根目录;HTML 原型以 ../logo.svg 相对引用,后续 Avalonia 实现以同样方式引用根目录资产,不在任何子目录复制副本。
  • 原因:单一事实源,改 logo 只动一处。

D13 · 界面国际化 = CodeWF Lang 三件套 + 源生成器(2026-10-23)

  • 背景:原型设置页含「语言 / Language」切换(界面双语);数据层仍纯 zh-CN(D1 不变)。作者的两个候选:① 各项目用 JSON + T4(Language.tt)生成强类型 ResourceKeys 提交进仓库;② CodeWF.Avalonia.Lang.Generator 源生成器(JSON 作 AdditionalFiles,编译期生成)。
  • 决策:应用侧用 ② Generator。理由:Vox 界面文案会高频增改,Generator 让 JSON 改完即生效、键永不过期(T4 需要记得跑 dotnet tool run t4 再提交,忘了就 CI 才发现);纯 dotnet build 工作流无 T4 工具链依赖;生成器是 DevelopmentDependency 分析器,不影响运行时与 AOT。T4 继续服务各库仓库自身(其 JSON 内嵌 + CI -Check 校验的模式合理)。键规范:4 段 Vox.区域.组.键(生成器按前两段生成命名空间,3 段键会把「区域」变成命名空间,曾与 TKCode.Arc.Dialog 类冲突)。
  • 代价:键结构受生成器「≥3 段」约束;多一层 Roslyn 分析器依赖(preview 版跟随 CodeWF.Avalonia 版本)。

D14 · 主题与外观切换全走 ArcTheme(2026-10-31 修订)

  • 决策:设置页的明暗(亮/暗/跟随系统)、强调色(ArcAccentPreset)、动效级别(ArcMotionLevel)统一经 ArcTheme.Apply(...) 热切换,持久化到 settings.json 并在主窗口初始化后重放。Arc 0.3.2 自带独立 Foundation 主题,不再使用 AtomUI ThemeManager。Markdown/MindView 的排版主题由 CodeWF.Avalonia 自己管理,不与 Arc 共享主题运行时。
  • 代价:Arc 负责系统明暗跟随;Vox 自绘令牌仍由 VoxTheme 同步更新,Markdown 与脑图的视觉融合需在 UI 验收中检查。

D15 · Arc 是 UI 控件唯一首选来源(2026-10-31)

  • 背景:Vox 曾通过 Program.BuildAvaloniaApp() 注册旧版 UseDesktopControls() 与 UseArc();Arc 0.3.2 已迁移到 UseArcControls(),但部分页面仍保留 Vox 自定义按钮、输入框、弹层和表格样式。继续随意扩展会造成 Arc 与 Vox 两套控件体系并行,后续维护和视觉一致性成本上升。
  • 决策:新增/重构控件前先阅读 https://docs.tkcode.si/llms.txt、https://docs.tkcode.si/skills/tkcode-arc/SKILL.md,并参考 components.md、checklist.md 与在线 Gallery。Arc 有对应能力时优先使用 Arc;只有产品特有布局或 Arc 不覆盖的场景才使用 Avalonia 原生控件或 Vox 自定义控件。
  • 样式边界:Arc 控件沿用 Arc token、模板和交互;VoxStyles.axaml 仅作用于 Vox 语义类,禁止使用全局宽泛样式覆盖 Arc 控件。主题与动效统一通过 ArcTheme.Apply(...) / ArcMotion。
  • 已落地基线:启动注册集中在 Program.cs(WithArcFonts、UseArc、UseArcControls);写作、发布中心、MCP 和标题栏外观使用 Arc SegmentedControl;发布中心、发布对话框、平台账户弹窗和设置页的主要操作按钮已切换为 TKCode.Arc.Button,按主/次/幽灵/危险动作映射 ButtonVariant;图标使用 Arc Lucide 包。
  • 升级记录(2026-10-31):已升级到 Arc 0.3.2-preview.2;启动入口迁移为 UseArc(arc => arc.UseArcControls().WithTheme(...)),主题服务迁移为 ArcTheme.Apply(...),移除 Vox 对 AtomUI 的直接引用。筛选下拉由自定义 Popup 改为 Arc Select,设置/文章库/图片库/发布中心的单行输入改为 Arc Input。Arc 仍是 preview 版本,升级需核对迁移说明并构建验证。

D16 · 界面风格 Arc / Pixel 与原型保持一致(2026-10-31)

  • 背景:design/Vox.html 的外观弹层包含 Arc / Pixel 两种界面风格;此前 Avalonia 实现只有密度、明暗、动效和强调色,缺少风格切换入口。
  • 决策:新增 VoxSettings.UiStyle 持久化设置,默认 Arc;标题栏外观弹层提供 Arc / Pixel 分段切换。Arc 使用密度对应的柔和圆角,Pixel 将 Vox 自有语义控件的圆角令牌置零;Arc 控件仍由 Arc 自己的模板和主题管理,不通过 Vox 全局样式覆盖。
  • 范围:本次已覆盖 VoxStyles 中的按钮、输入框、分段容器、导航项、菜单、弹层、卡片、缩略图等语义类;页面中直接在代码里设置的个别圆角和 Arc 控件内部圆角仍需实机视觉验收,不能宣称已完全复刻 CSS 的 Pixel 选择器。

D17 · Markdown 源码与阅读排版严格对齐原型(2026-10-31)

  • 背景:源码编辑器和阅读预览虽然已使用 CodeWF.Avalonia.Markdown,但控件默认配色、行高、留白和阅读列宽并不等同于 design/Vox.html / app.css。
  • 决策:源码区显式设置 Geist Mono 优先字体、11.5px 基准字号、1.95 倍行高、12px 上下留白和 44px 行号区域;MarkdownEditorPalette 的语义画刷统一从 VoxTheme 注入,明暗/强调色变化时通过控件支持的 ThemeVariant 变更触发重新着色。阅读区正文最大宽度 720px 并居中,标题层级、段落间距与代码块字号显式按原型设定;字号档位和阅读主题仍由用户设置控制。
  • 边界:CodeWF 包当前锁定版本不公开行号画笔键等部分较新 API,Vox 不依赖未发布属性;行号内部字体仍由控件包管理。视觉验收仍需在目标 Windows 字体环境下做截图叠图。