ASCII Tree | Michaell Alavedra

ASCII Tree 是一款旨在解决技术文档中常见问题的工具：即文件系统直观、结构化且易读的视觉呈现。

作为一名工程师，我构思了本项目，旨在提供一个干净、快速的界面，将缩进的纯文本转换为 ASCII 树状图，从而无需使用庞大的绘图工具或繁琐的手动字符绘制。

业务实用性与通用工作流

该项目的业务价值在于其即时性与精准度。在软件开发、技术文章编写或文档创建的场景中，展示目录层级结构是一项频繁出现的需求。

该工具通过三步工作流解决此问题：

结构化输入： 用户输入纯文本，利用缩进（空格或制表符）来定义文件和文件夹的层级嵌套级别。
确定性处理： 系统解析文本，过滤空行，识别特殊字符（如 Markdown 列表符号），并在内存中构建树状数据模型。
参数化渲染： 生成引擎处理该树并渲染静态 ASCII 表示。用户可以实时修改参数，例如包含完整路径 (fullpath)、高级 UTF-8 字符 (fancy) 或目录斜杠后缀 (trailing slash)。

所有这些都在浏览器本地运行，提供实时响应、本地持久化和国际化支持，使其对技术与非技术人员皆具实用价值。

整体架构

项目遵循适应 Frontend 环境的 领域驱动设计 (DDD) 原则以及 Astro 原生提供的 群岛架构 (Islands Architecture) 进行构建。

该设计的技术考量在于将业务逻辑（树的解析与生成）与用户界面层完全隔离。这确保了应用的逻辑核心纯粹、可测试，且与所使用的视觉框架无关。

职责分离

领域层 (src/lib/tree-generator/)： 包含接口定义 (FileStructure)、词法解析器 (parse-input.ts) 和渲染引擎 (generate-tree.ts)。它是无视觉依赖的纯 TypeScript 代码。
应用与状态层： 应用状态持久化通过 IndexedDB 进行异步管理，并由 Dexie 库封装 (src/lib/db.ts)。这允许在重新加载之间即时恢复用户会话，将存储责任委托给客户端（Offline-first）。
呈现层： 使用 Astro 的静态与动态组件 (src/components/)，直接通过嵌入的 Vanilla JS 处理文本编辑器和配置控件的交互性，从而避免了在这种体量的应用中使用 React 或 Vue 等响应式框架带来的额外开销。
国际化系统 (i18n)： 基于目录路由 (Folder-based routing) 和中央字典 (src/i18n/ui.ts)。文案定义与组件解耦，在编译期注入翻译。

graph TD
    UI[呈现层: Astro 组件]
    State[状态管理: IndexedDB / Dexie]
    Parser[解析器: Input -> 内存中的树]
    Renderer[渲染器: 树 -> ASCII 字符串]

    UI --> |文本与选项| Parser
    UI <--> |同步| State
    Parser --> |FileStructure| Renderer
    Renderer --> |结果| UI

数据建模与逻辑

应用核心对层级系统进行建模。核心实体为 FileStructure。

实体图表

classDiagram
    class FileStructure {
        +String name
        +FileStructure[] children
        +Number indentCount
        +FileStructure parent
    }

数据转换流程

语法解析分为两个阶段。首先，将输入字符串拆分为行，并使用基于正则表达式的词法解析器确定每一节点的缩进级别和基本名称，忽略表面字符（如 Markdown 连字符）。

随后，执行重建算法，维护包含当前节点的栈 (path)，遍历平铺列表并仅基于 indentCount 的数学差异分配父子关系。

sequenceDiagram
    participant User as 用户
    participant Editor as UI / 编辑器
    participant Parser as parseInput()
    participant Renderer as generateTree()
    participant Dexie as IndexedDB

    User->>Editor: 编写缩进文本
    Editor->>Parser: 发送 Raw String
    Parser->>Parser: 转换为平铺对象数组
    Parser->>Parser: 重建关系 (Parent/Children)
    Parser-->>Renderer: 返回根 FileStructure 对象
    Renderer->>Renderer: 深度优先遍历 (DFS) + 选项 (Fancy, Root)
    Renderer-->>Editor: 返回最终 ASCII 字符串
    Editor->>Dexie: 持久化 Input 与选项
    Editor->>User: 显示渲染后的图表

用于持久化和生成共享 URL 的应用状态由 Dexie 中的平铺模型管理：

erDiagram
    TreeState {
        int id PK
        string content
        boolean fancy
        boolean fullpath
        boolean trailing
        boolean root
    }

该抽象允许通过在 URL 中将此对象编码为 Base64 来共享图表的精确状态。

技术栈

技术选型优先考虑性能、开发体验 (DX) 和严格类型。

工具	架构角色	设计考量
Astro v5.2	框架 / 静态站点生成器	提供路由、群岛架构及快速渲染，默认只发送极小 HTML。
TypeScript v5.7	主要开发语言	保证数据模型 (`FileStructure`) 完整性并在编译期预防解析器错误。
Dexie.js	状态持久化	IndexedDB 的简洁抽象，异步保存用户进度而不阻塞主线程。
Tailwind CSS v4	样式层	允许敏捷、响应式且统一的设计，并处理复杂的亮/暗主题变化。
Biome.js	Linter 与 Formatter	替代经典的 ESLint+Prettier 组合，以极速运行提供统一的代码规范。
Vitest	测试环境	用于验证词法解析器内的纯确定性与边界情况。

这些技术的协同架构带来了一个稳健的工具，拥有完全独立于客户端的领域核心，并置于一个无需多余依赖即可扩展的架构之中。层级处理逻辑与交互呈现之间的严格分离确保了代码的长远可维护性。