跳到主要内容

模板系统需求分析

最后更新：2026-02-15
状态：生效中

1. 执行摘要​

本文说明 DistroNexus 为什么需要模板系统，并定义支撑其存在的业务与工程需求。

DistroNexus 解决了 WSL 生命周期管理，但仅有生命周期操作并不能解决环境标准化问题。模板系统用于打通实例创建与可直接投入开发的环境之间的差距。

2. 问题陈述​

没有模板时，团队需要反复执行相同的安装后配置：

  • 语言/运行时安装，
  • 包管理器引导，
  • 开发工具初始化，
  • 以及项目级版本固定。

这会导致五类反复出现的问题：

  1. 上手成本高：新成员需要数小时复刻本地环境。
  2. 配置漂移：不同机器随时间逐步偏离。
  3. 可复现性差：难以在本地复现类似 CI 的行为。
  4. 运维风险高：人工步骤导致结果不一致。
  5. 可审计性弱：缺少统一描述和验证链路。

3. DistroNexus 为什么需要模板系统​

模板系统之所以必要，是因为它提供了环境引导的一等、显式契约：

  • 声明式元数据（config/templates.json）用于发现与治理；
  • 脚本化执行用于在 WSL 实例中完成真实配置；
  • 版本/通道控制支持现代多 SDK 场景；
  • 预检机制覆盖 GPU/systemd/容器模式等受限场景；
  • 自动化运行器用于可重复验证与证据产出。

简而言之：生命周期管理负责“创建实例”，模板系统负责“创建可用环境”。

4. 干系人与主要用例​

4.1 干系人​

  • 使用 WSL 日常开发的个人开发者；
  • 关注一致性上手结果的团队负责人；
  • 验证环境可复现性的 QA/发布工程师；
  • 维护模板目录和脚本的维护者。

4.2 主要用例​

  1. 在安装发行版实例后应用一个内置模板。
  2. 选择语言通道/版本（如 .NET 通道、Node LTS/current）。
  3. 通过变量覆盖应用环境特定选项。
  4. 在模板改动后验证单个或多个模板。
  5. 执行全目录 dry-run/实跑并归档证据。

5. 功能需求​

5.1 目录与发现​

  • 模板应可从 config/templates.json 被发现。
  • 每个模板应定义 ID、分类、描述、兼容性与脚本。
  • 检索至少支持按 ID 与分类过滤。

5.2 执行与编排​

  • 系统应支持将模板应用到目标 WSL 实例。
  • 脚本应按定义顺序执行。
  • 脚本超时与失败继续行为应可配置。
  • 执行过程中应可上报进度与状态。

5.3 版本感知配置​

  • 版本感知模板应支持 VersionOptions 与 DefaultSelections。
  • 模板应用应支持运行时变量覆盖。

5.4 预检与能力约束​

  • 脚本执行前应运行预检。
  • 必需检查应快速失败。
  • 可选检查应告警并继续。
  • 在自动化执行中，能力受限场景应支持 Blocked 分类。

5.5 历史与可追溯性​

  • 模板应用历史应持久化。
  • 自动化执行应输出机器可读与 Markdown 产物。

6. 非功能需求​

6.1 安全性​

  • 必须拒绝绝对脚本路径。
  • 必须阻止路径穿越。
  • 脚本解析必须限制在允许根目录内。

6.2 可靠性​

  • 在可行范围内脚本应具备幂等性。
  • 应支持取消与超时处理。

6.3 可复现性​

  • 对相同输入，模板元数据与执行行为应尽可能确定。
  • 验证输出应可持久化并可审计。

6.4 本地优先验证​

  • 自动化测试套件以本地 WSL2 为主。
  • CI 执行为受保护、显式覆盖后才允许。

7. 范围边界​

7.1 范围内​

  • 内置模板目录与元数据模型。
  • 桌面端 + PowerShell 的模板应用流程。
  • 本地自动化验证运行器与产物。

7.2 范围外​

  • 云资源编排。
  • 第三方在线模板市场。
  • 在 CI 中强制执行全部本地运行时模板。

8. 当前状态摘要​

  • 当前内置目录共 15 个模板。
  • 已实现分类：Development、Platform、CloudNative、Database、DataAndAI。
  • 扩展需求中提及 DevOps 分类目标，但当前尚无独立内置 DevOps 分类。

9. 成功标准​

模板系统版本可视为成功发布的条件：

  1. 模板目录合法且可加载。
  2. 应用流程可稳定上报进度并记录历史。
  3. 安全防护规则得到执行。
  4. 桌面端与 PowerShell 入口保持一致。
  5. 存在“指定模板 + 全目录”两类自动化验证证据。

10. 相关文档​

  • docs/development/template-system-comprehensive-guide.md
  • docs/specs/template-system-requirements.md
  • docs/specs/built-in-template-expansion-requirements.md
  • docs/specs/built-in-template-automation-test-suite-requirements.md