From 9d223be5caadacd289224479a5813c868cf09ed4 Mon Sep 17 00:00:00 2001
From: KiriAky 107 <KiriAky107@qq.com>
Date: Sun, 30 Aug 2026 09:57:31 +0800
Subject: [PATCH] =?UTF-8?q?docs(frontend):=20=E8=A1=A5=E5=85=85=E5=86=99?=
 =?UTF-8?q?=E4=BD=9C=E4=BD=93=E9=AA=8C=E4=BC=98=E5=8C=96=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/前端写作体验优化开发说明.md | 75 ++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 docs/前端写作体验优化开发说明.md

diff --git a/docs/前端写作体验优化开发说明.md b/docs/前端写作体验优化开发说明.md
new file mode 100644
index 0000000..250c589
--- /dev/null
+++ b/docs/前端写作体验优化开发说明.md
@@ -0,0 +1,75 @@
+# 前端写作体验优化开发说明
+
+## 1. 本次目标
+
+本次优化聚焦笔记写作主流程，不调整后端接口：
+
+- 将界面中的装饰性 Emoji 统一替换为 Element Plus 图标；
+- 将“写作”模式由 Markdown 源码与预览双栏改为单一可视化编辑区；
+- 为写作区增加标题、加粗、斜体、有序列表、无序列表工具栏；
+- 使用 Shiki 为 Markdown 代码块提供亮色、暗色双主题高亮。
+
+## 2. 实现说明
+
+### 2.1 图标体系
+
+新增 `AppIcon.vue` 作为轻量图标出口，页面直接传入 `@element-plus/icons-vue` 组件。侧边栏、文件树、Vault 入口、主题按钮、空状态及扩展列表不再使用 Emoji 表达操作含义。
+
+这样处理后，图标尺寸、颜色和主题状态都由 CSS 统一控制，也避免不同系统 Emoji 字体造成的显示差异。
+
+### 2.2 可视化 Markdown 编辑器
+
+写作模式使用 Milkdown Crepe 渲染 Markdown 文档，磁盘中仍保存标准 Markdown 文本。编辑器监听 Markdown 更新并写回 Pinia 状态，继续复用原有自动保存逻辑。
+
+“源码”模式保留为独立模式，便于需要精确编辑 Markdown 的用户使用；写作模式中不再同时展示 Markdown 源码。
+
+编辑器按当前文件路径重新挂载，保证切换文件、切换源码模式后，展示内容与 Store 中的最新 Markdown 一致。
+
+### 2.3 Markdown 工具栏
+
+写作区顶部提供以下基础格式操作：
+
+- 二级标题；
+- 加粗；
+- 斜体；
+- 有序列表；
+- 无序列表。
+
+工具栏调用 Milkdown Command 修改当前选区或块级结构，不通过字符串拼接修改 Markdown，因此能正确处理光标、选区和嵌套列表。
+
+### 2.4 Shiki 高亮与主题适配
+
+代码高亮使用 Shiki 的 JavaScript 正则引擎，并只注册第一阶段常用语言：Markdown、HTML、CSS、JavaScript、TypeScript、JSON、Python、Shell 和 SQL。未知语言回退为 Markdown 语法展示，不阻塞整篇内容渲染。
+
+高亮结果同时生成 `github-light` 和 `github-dark` 颜色变量。根节点的 `data-theme` 变化后由 CSS 选择对应颜色，因此切换主题无需重新解析整篇 Markdown。
+
+Shiki 应用于：
+
+- 写作编辑器中的代码块高亮预览；
+- AI 对话中的 Markdown 代码块。
+
+Markdown HTML 仍在写入 DOM 前经过 DOMPurify 清理。
+
+## 3. 新增依赖
+
+- `@element-plus/icons-vue`：统一界面图标；
+- `@milkdown/crepe`、`@milkdown/kit`：可视化 Markdown 编辑器及命令；
+- `shiki`、`@shikijs/langs`、`@shikijs/themes`、`@shikijs/engine-javascript`：代码高亮和按需语言注册。
+
+## 4. 验证记录
+
+在 `frontend` 目录执行：
+
+```bash
+pnpm build
+```
+
+验证结果：TypeScript 类型检查与 Vite 生产构建均通过。开发服务器根页面返回 HTTP 200。
+
+本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步和亮暗主题下的代码块显示。
+
+## 5. 后续建议
+
+- 根据真实文档规模评估 Milkdown 与 Shiki 的懒加载拆包；
+- 为工具栏补充撤销、重做、引用、行内代码和链接；
+- 增加编辑器选区命令与文件切换的组件测试。