【文档，逻辑】更新核心逻辑文档和版本号

- 重构 doc/logic.md 文档结构，增加项目概述和详细架构说明
- 完善 doc/scripts.md 和 doc/workflow.md 技术文档
- 更新 index.html 版本号至 1.20.3
- 优化文档格式和排版，符合盘古之白排版规范

Author: PJ-568

doc/logic.md

@@ -1,106 +1,294 @@
 # 核心逻辑实现
 
-## 功能模块说明
+## 项目概述
+
+MARKDOWN.HTML 是一个低依赖、一键部署的 Markdown 网页渲染解决方案。项目通过单一 HTML 文件实现完整的 Markdown 渲染功能，支持代码高亮、Mermaid 图表、多语言翻译、深色模式等特性。
+
+## 核心架构
+
+项目采用客户端渲染架构，主要包含以下核心模块：
 
 ```mermaid
-classDiagram
-    class ContentLoader {
-        +showMarkdown(mdPath, response)
-        +getMarkdown()
-        +handleError()
-        +updateContent()
-    }
-    class NavigationHandler {
-        +initPJAX()
-        +initCustomPJAXResponse()
-        +initCustomPJAXEventListener()
-        +customPushState()
-    }
-    class TranslationSystem {
-        +initTranslate()
-        +refreshTranslate()
-        +infoTranslate()
-    }
-    class UIStateManager {
-        +loadingState 计数器
-        +startLoad()
-        +endLoad()
-        +initDarkmode()
-    }
-    class PathProcessor {
-        +decodeMDPath()
-        +formatMDPath()
-        +getDirectory()
-        +isRelativePath()
-    }
-    
-    ContentLoader --> NavigationHandler : 使用PJAX导航
-    ContentLoader --> PathProcessor : 路径处理
-    ContentLoader --> TranslationSystem : 内容翻译
-    NavigationHandler --> ContentLoader : 触发加载
-    UIStateManager --> ContentLoader : 加载状态控制
+graph TB
+    A[HTML 入口文件] --> B[Markdown 渲染引擎]
+    A --> C[资源内联系统]
+    A --> D[构建处理系统]
+    B --> E[marked.js]
+    B --> F[highlight.js]
+    B --> G[mermaid.js]
+    C --> H[Rust 构建工具]
+    D --> I[GitHub Actions]
 ```
 
-## 核心流程
+## 1. HTML 渲染逻辑
 
-```mermaid
-sequenceDiagram
-    participant 用户
-    participant 浏览器
-    participant ContentLoader
-    participant NavigationHandler
-    
-    用户->>浏览器: 访问页面
-    浏览器->>ContentLoader: DOMContentLoaded
-    ContentLoader->>PathProcessor: decodeMDPath(URL)
-    alt 路径有效
-        ContentLoader->>ContentLoader: fetchMD(路径)
-        ContentLoader->>ContentLoader: 解析 Markdown
-        ContentLoader->>ContentLoader: 处理内部链接转换
-        ContentLoader->>UIStateManager: startLoad()
-        ContentLoader->>DOM: updateContent()
-        ContentLoader->>TranslationSystem: 触发翻译
-        ContentLoader->>UIStateManager: endLoad()
-    else 路径无效
-        ContentLoader->>PathProcessor: 尝试默认文件(index.md/README.md)
-        ContentLoader->>UIStateManager: handleError()
-    end
-    
-    用户->>NavigationHandler: 点击 .md 链接
-    NavigationHandler->>ContentLoader: 触发新内容加载
+### 1.1 版本管理机制
+
+版本号存储在 `index.html` 的自定义标签中：
+
+```html
+<markdown-html
+  version="1.20.2"
+  author="PJ568"
+  repo="https://github.com/PJ-568/markdown.html"
+  license="CC BY-SA 4.0 International"
+></markdown-html>
 ```
 
-## 关键逻辑说明
+**版本提取逻辑**：
+
+- 通过 `getVersion()` 函数从 DOM 中提取版本信息
+- 用于显示关于信息和版本检测
+
+### 1.2 Markdown 渲染流程
+
+#### 主要渲染函数：`showMarkdown()`
+
+**核心流程**：
+
+1. **路径解析**：通过 `decodeMDPath()` 解析 URL 参数 `?p=` 指定的 Markdown 文件路径
+2. **文件检测**：自动检测 `index.md` 或 `README.md` 文件
+3. **内容获取**：使用 `fetch()` API 获取 Markdown 文件内容
+4. **渲染处理**：调用 `getMarkdown()` 进行完整渲染
+
+#### Markdown 处理函数：`getMarkdown()`
+
+**处理步骤**：
+
+1. **原始渲染**：使用 `marked.parse()` 将 Markdown 转换为 HTML
+2. **链接处理**：自动转换相对路径为绝对路径
+3. **图片处理**：设置懒加载属性，转换相对路径
+4. **目录生成**：通过 `generateOutline()` 自动生成文档目录
+5. **内容包装**：添加文件路径信息和目录结构
+
+### 1.3 动画与状态管理
+
+**加载动画系统**：
+
+- `loadingState` 对象管理加载状态
+- 进度条动画通过 CSS 动画和 JavaScript 定时器实现
+- 支持多资源加载的并发计数
+
+**页面切换动画**：
+
+- 使用 CSS 动画实现页面切换效果
+- `waitForAnimationsEnd()` 函数等待动画完成
+
+## 2. 多语言支持系统
+
+### 2.1 翻译引擎集成
+
+**初始化流程**：`initTranslate()`
+
+1. 配置 translate.js 使用客户端翻译服务
+2. 设置自动语言检测
+3. 配置忽略翻译的 CSS 类
+4. 执行初始翻译
+
+**翻译提示系统**：`infoTranslate()`
+
+- 检测当前语言与原始语言的差异
+- 动态生成翻译提示信息
+- 提供切换回原始语言的按钮
+
+### 2.2 语言切换处理
+
+**自动检测**：
+
+- 通过 URL 参数控制语言切换
+- 支持浏览器语言偏好设置
+
+**手动切换**：
+
+- 通过 `translate.changeLanguage()` 函数实现语言切换
+
+## 3. PJAX 无刷新导航
+
+### 3.1 PJAX 初始化
+
+**配置**：`initPJAX()`
+
+- 选择器配置：`head title`, `.markdown-body`, `.pjax-reload`
+- 动画切换配置：侧滑动画效果
+- 缓存策略：禁用缓存破坏
+
+### 3.2 自定义 PJAX 处理
+
+**响应处理重写**：`initCustomPJAXResponse()`
+
+- 覆写 PJAX 的默认响应处理逻辑
+- 针对 Markdown 页面进行特殊处理
+- 保持标准 HTML 页面的正常处理
+
+**事件监听器**：`initCustomPJAXEventListener()`
+
+- 监听 `.md` 链接的点击事件
+- 实现自定义的无刷新页面切换
+- 错误处理和回退机制
+
+## 4. 深色模式支持
+
+### 4.1 Darkmode.js 集成
+
+**初始化**：`initDarkmode()`
+
+- 检测 Darkmode.js 库的可用性
+- 创建深色模式实例
+- 错误处理和兼容性保障
+
+### 4.2 切换控制
+
+**手动切换**：
+
+- 通过 `darkmode.toggle()` 函数切换模式
+- 支持跟随系统、浅色、深色三种模式
+
+## 5. 构建与发布系统
+
+### 5.1 Rust 构建工具
+
+项目使用 Rust 编写的构建工具 `src/main.rs` 生成不同版本的 HTML 文件。
+
+#### 核心功能：
+
+1. **HTML 压缩**：`minify_html()`
+
+   - 使用 `minify-html` 库进行压缩
+   - 保留关键标签结构
+   - 压缩 CSS 和 JavaScript
+
+2. **资源内联**：`all_in_one()`
+   - 自动下载外部 CSS 和 JavaScript 资源
+   - 使用 `scraper` 库解析 HTML DOM
+   - 内联替换外部资源为嵌入式内容
+
+#### 构建流程：
+
+```bash
+cargo run --release -- index.html
+```
+
+**生成文件**：
+
+- `index.min.html` - 压缩版本
+- `index.allinone.html` - 资源内联版本
+- `index.allinone.min.html` - 压缩的资源内联版本
+
+### 5.2 版本管理脚本
+
+#### `scripts/get-version.bash`
+
+- 从 HTML 文件中提取版本号
+- 支持自定义文件路径
+- 多语言错误提示
+
+#### `scripts/is-newer-version.bash`
+
+- 比较当前版本与 Git 标签
+- 使用 `sort -V` 进行版本号比较
+- 输出新版本号或 "0"（无更新）
+
+#### `scripts/release.bash`
+
+- 交互式版本发布工具
+- 版本格式验证（X.X.X）
+- 自动创建和推送 Git 标签
+
+### 5.3 GitHub Actions 工作流
+
+**自动化发布流程**：
+
+1. **版本检测**：检查是否需要发布新版本
+2. **标签创建**：自动创建 vX.X.X 格式标签
+3. **构建处理**：编译 Rust 程序并生成 HTML 文件
+4. **发布打包**：准备发布物文件结构
+5. **发布创建**：创建 GitHub Release 并部署到 Pages
+
+## 6. 错误处理机制
+
+### 6.1 客户端错误处理
+
+**文件加载错误**：`handleError()`
+
+- 显示友好的错误信息页面
+- 提供重新加载和返回功能
+- 自动恢复页面状态
+
+**网络请求错误**：
+
+- `fetch()` API 的错误处理
+- 超时和网络异常检测
+- 友好的用户提示
+
+### 6.2 构建时错误处理
+
+**Rust 错误处理**：
+
+- 自定义 `HtmlProcessorError` 类型
+- `Result<T, Box<dyn Error>>` 统一错误处理
+- 详细的错误日志输出
+
+## 7. 性能优化特性
+
+### 7.1 懒加载优化
+
+**图片懒加载**：
+
+- 自动设置 `loading="lazy"` 属性
+- 减少初始页面加载时间
+
+**资源按需加载**：
+
+- 外部 CSS 动态加载
+- 避免阻塞页面渲染
+
+### 7.2 缓存策略
+
+**PJAX 缓存**：
+
+- 禁用缓存破坏机制
+- 提高页面切换速度
+
+**浏览器缓存**：
+
+- 合理的缓存头设置
+- 减少重复资源下载
+
+## 8. 安全考虑
+
+### 8.1 XSS 防护
+
+**内容安全策略**：
 
-### 1. 内容加载流程 (`showMarkdown`)
+- 安全的 HTML 解析和处理
+- 避免脚本注入风险
 
-- **路径解析**：通过 `decodeMDPath()` 解析URL参数
-- **文件获取**：优先尝试 `index.md`，失败后回退 `README.md`
-- **链接转换**：将文档内 `.md` 相对路径转换为绝对路径
-- **DOM更新**：使用 `updateContent()` 注入生成的HTML
-- **加载状态**：通过 `loadingState` 计数器管理进度条动画
+**外部资源验证**：
 
-### 2. PJAX导航系统
+- 只加载可信的 CDN 资源
+- 资源完整性检查
 
-- **初始化**：`initPJAX()` 配置选择器和切换规则
-- **自定义处理**：覆写`handleResponse` 实现 Markdown 渲染
-- **事件委托**：拦截 .md 链接点击事件触发无刷新加载
-- **状态管理**：`customPushState()` 维护浏览历史层级
+### 8.2 隐私保护
 
-### 3. 翻译系统集成
+**翻译服务**：
 
-- **自动检测**：`setAutoDiscriminateLocalLanguage()` 设置语言
-- **DOM注入**：`infoTranslate()` 插入语言切换提示条
-- **动态刷新**：`refreshTranslate()` 处理动态内容翻译
+- 使用客户端翻译避免数据泄露
+- 可选的翻译功能
 
-### 4. 错误处理机制
+## 技术栈总结
 
-- **分级捕获**：try/catch 块覆盖关键操作节点
-- **友好提示**：`handleError()` 生成带操作按钮的错误界面
-- **状态恢复**：错误后自动回退到可用导航状态
+| 组件         | 技术                                | 用途                         |
+| ------------ | ----------------------------------- | ---------------------------- |
+| **前端渲染** | marked.js, highlight.js, mermaid.js | Markdown 解析和渲染          |
+| **用户体验** | translate.js, Darkmode.js, Pjax     | 多语言、深色模式、无刷新导航 |
+| **构建工具** | Rust, minify-html, scraper          | HTML 压缩和资源内联          |
+| **自动化**   | GitHub Actions, Bash 脚本           | 版本管理和发布流程           |
+| **部署**     | GitHub Pages, CDN                   | 静态资源分发                 |
 
-### 5. 动画与状态同步
+## 核心设计原则
 
-- **CSS动画**：使用 `Animated` 类实现页面过渡效果
-- **事件委托**：监听 `animationend` 事件清理DOM残留
-- **滚动管理**：内容加载后自动滚动到顶部
+1. **低依赖**：单一 HTML 文件包含所有必要功能
+2. **模块化**：各功能组件独立且可替换
+3. **可扩展**：易于添加新功能和集成
+4. **性能优先**：优化加载速度和用户体验
+5. **兼容性**：支持现代浏览器和移动设备