从零认识维刻 Vex 的 Flutter 仓库

维刻 Vex：写下想法，看见脉络。

本套文档写给第一次接触 Flutter、第一次打开本仓库的你。先建立地图，再读代码，不需要先认识所有技术名词。

编写日期：2026-10-18。 对照项目版本 0.2.2+4 与当日源码。这里是学习资料，不是“所有平台都已验收完成”的承诺；代码变化后，实际源码、测试和发行产物优先。

1. 你手里其实有四样东西

安装好的软件是运行工具，.md 是你的内容。二者不应该绑在同一个安装目录里。

2. 建议阅读顺序

进阶连接：MCP 使用与接口指南，包含权限说明、35 个工具和官方 Inspector 测试方法。

完整入口：文档导航，还可找到 更新日志、鸣谢、原型设计 与 打包脚本。文档正文以中文名集中维护，其他目录只保留导航链接；内置文档资源在构建时自动生成。

从 v0.4.0 起可在阅读视图中直接打开相对 .md、.markdown、.txt 链接，也支持 另一篇.md#章节；即时编辑中可通过链接菜单打开。链接相对于当前文档所在目录解析，不会覆盖已打开文档的未保存修改。未保存的草稿和手机系统选择器提供的无路径副本没有可用的相对目录，此时需先保存文档；也可用「打开文件夹」选择本目录，从文件树浏览。

3. 先记住这十个词

不要一开始就背缩写。第一次看不懂是正常的，遇到它时回来查即可。

4. 三种“文档”有什么区别

1. 需求文档：说清楚“用户需要什么、怎么验收”。例如自动保存默认关闭。
2. 设计文档：说清楚“由哪些模块、通过什么数据流实现”。例如文件服务负责写磁盘，界面不直接操作文件。
3. 用户 Markdown：使用软件编辑的内容。例如这篇文章。它不是项目代码，也不自动加入软件安装包。

本套需求、设计文档是对当前实现和已确认产品方向的梳理，不是从零虚构的未来架构。

5. 第一小时可以这样学

• 用 Vex 打开本文件夹，切换源码和阅读视图。
• 读 01，在资源管理器里找到 apps/vex/lib/main.dart。
• 读 02，挑三个最关心的用户场景。
• 读 05 的启动流程，先不研究编辑器复杂布局。
• 按 06 运行一个测试，而不是马上改大功能。
• 按 07 找到配置目录，但不修改、不公开里面的令牌。
• 复制 08 成为自己的练习稿，再练撤销、表格、图表和导出。

6. 学习时的三个边界

测试通过，不等于所有设备没有问题。 模拟手机尺寸不能替代真实手机；Windows 运行成功不能替代 macOS 验收。

恢复草稿，不等于版本备份。 真正重要的内容仍要保存到 .md，并备份整个笔记和附件目录。

被 Git 忽略，不等于可以删除。 build 可以重建；.signing 里的发行密钥不可随意重建或丢失。

本套文档与配图 docs/assets 已纳入源码仓库，提交并推送后，换电脑克隆仓库即可取得。尚未提交的练习修改仍需提交或单独备份；用户笔记、配置和签名材料不会因此自动进入 Git。

7. 本次核验范围

2026-10-18：文档已用当前 Markdown 核心解析，并校验相对文件 / 图片链接、Mermaid 场景。还通过真实 Windows Flutter 窗口阅读九篇文档，抽查代码、公式、图片、图表和 390 宽度明暗主题，共保留 19 张截图。

这属于 Windows 原生窗口与手机宽度模拟，不是 iPhone / Android 真机验证；也不代表 PDF / Word 的全部内容已逐页验收。阅读时发现的减少动态效果下图表缩放异常已修复并补充回归测试。