维刻 Vex 仓库地图与目录说明
目标：看见一个路径时，知道它属于源码、工具输出、安装文件，还是自己的数据。
1. 先看仓库外面
text
D:\github\
└─ apps\ 你用来收纳软件项目的父目录
├─ Vex\ 另一份 Vex 项目，不是当前 Flutter 子项目
├─ Vex-Flutter\ 当前独立 Git 仓库
│ └─ docs\ 本套学习笔记、设计与验收文档，随 Git 管理
└─ 其他项目\ 与本项目没有自动的编译依赖关系第一层 apps 是你电脑的收纳习惯。仓库内部第二层 apps/vex 是项目作者的组织方式。名字重复不代表项目套错了层级，Flutter 并不要求你的仓库必须放在 D:\github\apps。
路径 D:\github\apps\Vex-Flutter\apps\vex\lib\main.dart 可以分解为：
| 片段 | 含义 |
|---|---|
D:\github\apps |
本机项目收纳位置，可换 |
Vex-Flutter |
当前 Git 仓库根目录 |
apps/vex |
仓库里的最终应用 |
lib |
Dart 正式运行代码 |
main.dart |
普通启动入口 |
后文没有盘符的源码路径，都相对于 D:\github\apps\Vex-Flutter。
2. 仓库根目录
text
Vex-Flutter/
├─ .github/workflows/ GitHub 自动检查、构建和发布配方
├─ apps/vex/ 最终应用：界面、文件、设置、平台宿主
├─ packages/
│ ├─ vex_markdown_core/ 纯 Dart 文档结构与历史
│ ├─ vex_editor/ Flutter 编辑、源码、阅读控件
│ └─ vex_mindmap/ 通用思维导图控件
├─ design/ HTML/CSS/JS 原型，不是应用运行引擎
├─ docs/ 编号入门文档、设计、验收、发布说明及配图
├─ scripts/ 构建、资源同步、安装器、校验工具
├─ .dart_tool/ 工具生成，依赖解析和缓存
├─ build/ 工具生成的构建产物，可能不存在
├─ artifacts/ 工具生成的安装包、截图和日志
├─ .signing/ 本机发行签名材料，忽略但必须保护
├─ pubspec.yaml 整个 Dart 工作区的声明
├─ pubspec.lock 已锁定依赖版本，已提交 Git
├─ analysis_options.yaml 代码静态检查规则
├─ .flutter-version 当前固定 Flutter SDK 版本
├─ build-windows.bat 双击制作 Windows 安装包
├─ logo.svg / logo.png / logo.ico 品牌源资源
├─ README.md 仓库首页
├─ CONTRIBUTING.md 贡献与开发约定
├─ SECURITY.md 安全反馈约定
└─ LICENSE MIT 许可Pub workspaces 是什么
这是 Dart 自带的多包工作区机制。根 pubspec.yaml 统一列出应用、三个包以及两个示例项目，根 pubspec.lock 锁定整组依赖。它不是六个彼此无关、各装一份依赖的工程。
yaml
# 根 pubspec.yaml 的结构摘要，不是让你替换原文件
name: vex_workspace
publish_to: none
workspace:
- apps/vex
- packages/vex_markdown_core
- packages/vex_editor
- packages/vex_mindmap
- packages/vex_editor/example
- packages/vex_mindmap/examplepublish_to: none 表示不把这个工作区本身发布到 pub.dev，不妨碍制作和发布软件安装包。
3. 最终应用里面有什么
text
apps/vex/
├─ lib/
│ ├─ main.dart 启动、组装真实服务、加载状态
│ ├─ app.dart 应用外壳、主题、语言、provider
│ ├─ domain/ 文档、布局、文件格式、导出等模型
│ ├─ data/
│ │ ├─ repositories/ 设置和恢复数据的持久化
│ │ └─ services/ 文件、导出、图片、桌面窗口、MCP
│ ├─ ui/
│ │ ├─ core/ 共用主题、颜色、字体、基础控件
│ │ └─ workspace/ 主界面、菜单、偏好、演示和工作区协调
│ └─ l10n/
│ ├─ app_*.arb 翻译原文，主要修改这里
│ └─ generated/ 国际化工具生成的 Dart，当前受 Git 管理
├─ assets/ 字体、Logo、内置文档等随应用打包的资源
├─ test/ 单元测试、组件测试
├─ integration_test/ 真正启动平台应用的集成测试
├─ windows/ Windows C++ 宿主与资源配置
├─ macos/ macOS 原生宿主与配置
├─ linux/ Linux 宿主与配置
├─ android/ Android Gradle、Manifest 和宿主
├─ ios/ iOS Xcode 工程与配置
├─ build/ 编译生成，可重建
├─ pubspec.yaml 应用名、版本、依赖、资源声明
└─ l10n.yaml 国际化生成配置平台目录是源码，不是缓存。 Flutter 负责大量跨平台界面，但窗口、权限、图标、应用标识和签名仍依赖平台工程。当前没有可据此宣称完成的 HarmonyOS 原生工程。
最先认识的源码文件
| 文件 | 你要找什么时读它 |
|---|---|
lib/main.dart |
软件怎样从零启动 |
lib/ui/workspace/workspace_screen.dart |
工作区外壳、动作与对话框 |
lib/ui/workspace/workspace_panes.dart |
源码、即时、阅读、导图如何摆放 |
lib/ui/workspace/workspace_view_model.dart |
打开、保存、恢复、布局和状态协调 |
lib/domain/workspace.dart |
一份文档和布局的数据结构 |
lib/data/services/file_service.dart |
文件选择、读写、外部冲突保护 |
lib/data/repositories/settings_repository.dart |
设置保存在哪里、怎样序列化 |
lib/data/repositories/recovery_repository.dart |
恢复草稿怎样落盘 |
lib/ui/workspace/preferences_dialog.dart |
偏好设置界面 |
lib/ui/core/app_theme.dart |
Flutter 主题规则 |
4. 三个独立包有什么区别
| 包 | 是否依赖 Flutter | 主要职责 | 不该负责什么 |
|---|---|---|---|
vex_markdown_core |
否，纯 Dart | Markdown 结构、源码范围、章节操作、统一撤销 | 不弹保存框 |
vex_editor |
是 | 编辑控制器、选区、输入、阅读、代码、表格、数学与 Mermaid | 不决定用户数据目录 |
vex_mindmap |
是 | 节点、布局、绘制、缩放、选择、通用导图交互 | 不读取磁盘 Markdown |
它们都不依赖最终应用的 provider 状态。
每个包的 lib/包名.dart 是推荐公开入口；lib/src 是包内实现约定，src 不表示自动生成。应用尽量通过公开入口导入，不随意越过包边界引用内部文件。
example 是演示组件的可运行小应用，用来独立验证包，不是正式 Vex 的另一个版本。test 也是源码，应提交，不要当作中间产物删除。
5. 哪些能重建，哪些不能当缓存
| 目录 / 文件 | 性质 | 处理原则 |
|---|---|---|
.dart_tool、**/build |
依赖与编译输出 | 关闭构建进程后可按需清理，再解析依赖和构建 |
**/ephemeral、Pods、.symlinks、.kotlin |
平台工具输出 | 可重建，但需要对应平台工具链和网络 |
coverage、artifacts、__pycache__ |
覆盖率、截图、日志、安装包、Python 缓存 | 确认不需要留证或分发后才清理 |
pubspec.lock |
工具生成但受版本管理 | 应保留，避免依赖在不同电脑漂移 |
l10n/generated |
生成且当前受版本管理 | 改 ARB 后用 flutter gen-l10n，核对差异 |
apps/vex/assets/generated/documents、design/assets/generated/documents-data.js |
从 docs 生成，Git 忽略 |
运行 python scripts/sync_builtin_documents.py 重建；只维护 docs 中的正文 |
| 平台插件注册文件 | Flutter 管理，是否跟踪依平台而异 | 让工具生成，不凭文件名成批删除 |
assets、平台图标、安装器位图 |
运行资源或已提交的派生资源 | 不是临时目录，必要时用专用脚本同步 |
.signing、keystore、证书 |
敏感的发行身份 | 不进 Git；加密备份，不可按缓存删除 |
.git |
仓库历史和本地提交 | 不是缓存；删掉会失去本地版本管理信息 |
%APPDATA%\Vex |
用户设置、恢复草稿 | 不属于源码清理；先关闭应用并备份 |
你的 .md 与图片目录 |
用户内容 | 永远不作为构建垃圾清理 |
.gitignore 只控制默认不跟踪哪些文件，不是“可删除清单”。清理前先执行 git status --short；它也不能显示所有忽略目录里的重要数据。
6. 文件名大小写为什么不同
- 产品对外名称：维刻 Vex。
- Dart 包名、Linux 包名、导入名：通常小写
vex或vex_editor。 - Dart 类型名：大驼峰，例如
WorkspaceViewModel。 - Dart 文件名：小写下划线，例如
workspace_view_model.dart。 - Windows 安装器和品牌文件：可使用
Vex，以实际规范为准。
Dart 标识符和包导入区分大小写。Windows 文件系统常见的不敏感行为不能代表 Linux CI；package:Vex/... 不能代替 package:vex/...。
7. 脚本与自动化速查
脚本是开发辅助工具，不会因为放在 scripts 就自动运行。看清入口和副作用后再执行，特别是签名与安装测试。
| 文件 / 文件组 | 作用 |
|---|---|
scripts/packaging/build.py |
本机和 CI 的统一构建入口，按目标检查工具链、测试、编译和校验 |
build-windows.bat → scripts/packaging/win-x64/build.bat |
Windows 双击快捷入口，完整流程位于同目录 build.ps1 |
scripts/packaging/win-x64/install_inno.ps1 |
准备固定版安装器编译工具，不安装 Vex |
scripts/packaging/win-x64/package.ps1、scripts/installer/Vex*.iss |
将已有 Windows Release 程序制作成安装包；ISS 拆分外观、注册和平台细节 |
test_windows_installer.ps1 |
可能真实安装 / 修复 / 卸载的专用验证，不是普通单元测试 |
scripts/packaging/osx/ |
macOS 通用 DMG 制作、Finder 布局检查与锁定依赖；各架构快捷入口仍生成同一通用包 |
scripts/packaging/linux-x64/、linux-arm64/、linux/ |
各架构构建入口及共享 DEB 制作逻辑，需对应架构 Linux 电脑 |
scripts/packaging/android/ |
三架构 APK 构建、收集、签名验证；签名材料不能进 Git |
scripts/packaging/shared/release_tools.py |
版本元信息、安装包白名单、SHA-256 和发布校验 |
sync_brand_assets.py |
从根 Logo 同步各平台品牌资源 |
prepare_installer_assets.py、prepare_macos_installer.py |
生成安装器品牌图片资源，已提交产物通常无需重做 |
sync_design_tokens.py、sync_project_info.py |
同步设计令牌和项目信息，不把 HTML 当 Flutter 运行引擎 |
sync_builtin_documents.py |
从 docs 唯一正文源生成应用内置文档及原型离线数据 |
prepare_*fonts.py |
准备字体资源，涉及体积和许可 |
scripts/tests |
上述发布、品牌、安装器等契约测试 |
.github/workflows/ci.yml 做常规 CI；installer-check.yml 检查安装器；release.yml 对正式 tag 执行完整构建发布。这些配方在 GitHub runner 上运行，不是你本机的目录清理器。
8. 一次自测
- 修改界面按钮，应该先找
ui，不是去改design。 - 找不到编译输出，可以重新构建，不代表源码没了。
- 改中文翻译，应修改 ARB，再生成国际化代码。
- 换电脑要带签名材料，但不要把它提交给公开仓库。
- 学习笔记在仓库
docs中，提交并推送后可随源码迁移；用户笔记和配置仍需独立备份。
下一篇：需求说明书。
💬 评论暂未开启
有疑问或建议，欢迎到 GitHub 提交 Issue 参与讨论。
有疑问或建议，欢迎到 GitHub 提交 Issue 参与讨论。