维刻 Vex 需求说明书

需求回答“为什么做、给谁用、什么结果才算合格”，不先规定按钮要由哪个类实现。

版本基线：0.2.2+4，整理日期：2026-10-18。本篇区分已确认方向、已有实现与仍待验收。它不是无条件的完成声明。

1. 产品与用户

维刻 Vex 是以本地 Markdown 文件为中心的写作空间，slogan 是“写下想法，看见脉络”。保留原 V 形标识，使用品牌墨青。

当前不包含账户、云同步服务、多人实时协作、SQLite 笔记数据库。用户可自行备份文件，但不要把“本地文件”误解为软件已经实现云同步。

2. 用户旅程

flowchart LR
  A[打开文件或新建草稿] --> B[记录想法]
  B --> C[调整章节与结构]
  C --> D[阅读和检查]
  D --> E[保存 Markdown]
  E --> F[按需导出分享]
  D --> B

一个常见场景：打开本套教程文件夹，阅读 01；切到源码查看表格；新建自己的学习笔记；用标题建立大纲；保存后导出一份 PDF。每一步都要有清楚的成功、取消和失败行为。

3. 功能需求与验收口径

七类主菜单

文件、编辑、段落、格式、视图、工具、帮助。主题与排版等放在对应视图入口中；macOS 另按系统习惯安放应用级设置和关于。菜单表达用户动作，而不是列出内部类名。手机使用触控适配的菜单形式，不照搬桌面悬停多级菜单。

Mermaid 与原生导图不是一回事

• Mermaid：用户在代码围栏里写图表语言，渲染流程图、时序图、甘特图、类图等。当前模板目录含 22 类示例，入口和演示应可发现。
• Vex 导图：把 Markdown 章节投影为可交互结构，切换布局、选节点、返回章节。

“模板有入口”不等于 Mermaid 所有版本语法、全部扩展都已逐项验收。复杂图表与各导出格式的表现必须单独检查。

4. 默认值也是需求

恢复草稿开着，不代表正在修改磁盘里的原文件。 这是两个不同机制。

5. 平台与尺寸要求

小屏优先保证内容可读和操作可达：对话框固定标题和关闭区，只滚动中间正文；设置不能突然切成桌面宽度；弹出菜单不能制造水平滚动条。平板最多双栏，桌面允许三栏，但实际窄窗口仍会降级。

6. 非功能需求

可靠性

1. 同一文档异步保存串行，不允许旧写入覆盖新写入。
2. 保存期间继续输入，新增内容仍显示未保存。
3. 中文输入法候选阶段不误提交、不被界面刷新吞掉。
4. 草稿保存失败时，不直接关闭并宣称保留成功。

性能与舒适

隐藏的导图不重复生成树和布局；界面重建按状态范围收敛。长文性能应在明确文档规模、设备和最坏延迟下测量，当前不编造帧率或耗时承诺。

视觉目标为接近已确认原型，但“98%”尚无统一量化评测结果。文字对比度、焦点、键盘操作、滚动、错误恢复比单张截图更重要。

安全

本地 MCP 也要鉴权、范围约束和修改确认。当前开发分支令牌通过平台安全存储保存，不再写普通设置；客户端配置仍含敏感令牌，公开日志和备份前应检查敏感信息。配置和能力范围见 MCP 指南。

7. 状态说明

• 有分层源码、三个独立包与自动测试。
• 有 Windows 一键本地打包入口和多平台 CI 发布配方。
• 有防覆盖保存、恢复队列、输入与布局回归测试。
• 完整的真实中文输入法和跨设备验收。
• 所有导出内容在目标阅读器的视觉验收。
• MCP 与目标真实客户端的完整互通验收。
• 按统一基准测量长文性能与原型还原度。
• iOS、HarmonyOS 的可安装分发包。

下一篇：概要设计。