From 4932171cf16ef14784d7b4b4d56d51877e499ff6 Mon Sep 17 00:00:00 2001 From: douboer Date: Thu, 16 Oct 2025 16:34:40 +0800 Subject: [PATCH] update at 2025-10-16 16:34:40 --- README.md | 746 ++++++++++++++++++++++++++++++++++++++++--------- docs/README.md | 179 ++++++++++++ 2 files changed, 788 insertions(+), 137 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index b4a7eda..1ce8e0a 100644 --- a/README.md +++ b/README.md @@ -1,179 +1,651 @@ -# Note2Any 架构文档索引 +## 更新说明 -> **架构版本**: v1.4.0 (模块化核心系统) -> **更新日期**: 2025年10月16日 +> [!IMPORTANT] +> ### v1.4.0 重大架构升级 🚀 +> +> Note2Any v1.4.0 进行了全面的架构重构，提供了更稳定、更高效的发布体验： +> +> **🏗️ 核心架构现代化** +> - 全新的模块化核心系统，包含9个专业模块（错误处理、进度反馈、配置管理等） +> - 1400+行新代码，全面TypeScript覆盖，零编译错误 +> - 统一的错误处理和实时进度反馈，提升用户体验 +> +> **⚡ 性能与稳定性提升** +> - 模块化加载，减少启动时间 +> - 异步处理优化，提升响应性能 +> - 智能缓存机制，减少重复计算 +> - 增强的错误恢复能力 +> +> **🔧 开发体验改进** +> - 标准化的平台发布接口，便于扩展新平台 +> - 清晰的模块职责分离和统一的接口约定 +> - 向后兼容设计，平滑升级路径 +> +> **升级建议**: 现有用户可直接升级，所有功能保持兼容。新的架构为后续功能扩展奠定了坚实基础。 -## 📚 文档导航 +> [!NOTE] +> ### v1.3.x 主题优化提醒 +> Note2Any 1.3.0版本对主题进行了优化，升级后请先清理旧版本主题文件，再重新下载新版主题。 +> +> 操作步骤：在Note2Any插件设置中，先点击『清空主题-清空』，然后点击『获取更多主题-下载』 +> +> 注意：如果修改过主题文件请做备份后再操作。 -### 🌟 主要架构文档 +完整历史变更请查看: [CHANGELOG](./CHANGELOG.md) -| 文档 | 描述 | 适用版本 | 推荐度 | -|------|------|----------|--------| -| [v1.4.0 架构文档](./architecture-v1.4.0.md) | 🆕 最新完整架构设计 | v1.4.0+ | ⭐⭐⭐⭐⭐ | -| [架构快速参考](./ARCHITECTURE_QUICK_REFERENCE.md) | 🔄 v1.4.0 快速上手指南 | v1.4.0+ | ⭐⭐⭐⭐⭐ | -| [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) | 🆕 v1.3.x → v1.4.0 对比 | 升级参考 | ⭐⭐⭐⭐ | -| [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) | 详细优化过程记录 | v1.3.12 | ⭐⭐⭐ | +## 1、简介 -### 📖 历史架构文档 +Note2Any 是一个专为 Obsidian 打造的现代化发布插件，支持将笔记一键发布到微信公众号、小红书等多个平台。插件采用全新的模块化架构设计，提供稳定可靠的发布体验。 -| 文档 | 描述 | 适用版本 | 状态 | -|------|------|----------|------| -| [架构总览 (旧版)](./architecture.md) | v1.3.x 旧架构文档 | v1.3.x | 🔒 已过时 | -| [架构对比 (旧版)](./ARCHITECTURE_COMPARISON.md) | v1.3.x 内部对比 | v1.3.x | 🔒 已过时 | -| [重构完成报告](./ARCHITECTURE_REFACTORING_COMPLETE.md) | v1.3.x 重构记录 | v1.3.x | 🔒 已过时 | +### 🌟 核心特性 -## 🎯 按用途查找文档 +- **📱 多平台发布**: 支持微信公众号、小红书等平台，统一的发布体验 +- **🎨 丰富主题**: 30+ 精美主题样式，支持代码高亮和自定义CSS +- **🖼️ 智能图片处理**: 自动图片上传、格式转换、EXIF方向处理 +- **📊 数学公式支持**: LaTeX 和 AsciiMath 双重语法支持 +- **🚀 批量发布**: 高效的批量文章发布功能 +- **⚡ 现代架构**: v1.4.0 全新模块化设计，更稳定、更高效 -### 🔰 新用户入门 -1. **了解整体架构**: [v1.4.0 架构文档](./architecture-v1.4.0.md) -2. **快速上手开发**: [架构快速参考](./ARCHITECTURE_QUICK_REFERENCE.md) -3. **查看升级改进**: [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) +### 🏗️ 技术亮点 -### 👨‍💻 开发者指南 -1. **核心模块使用**: [v1.4.0 架构文档 - 核心模块详解](./architecture-v1.4.0.md#2-核心模块详解) -2. **添加新功能**: [快速参考 - 常见任务示例](./ARCHITECTURE_QUICK_REFERENCE.md#📝-常见任务示例-v140) -3. **扩展新平台**: [快速参考 - 添加新平台](./ARCHITECTURE_QUICK_REFERENCE.md#2-添加新平台支持) +- **模块化核心系统**: 9个专业模块提供统一的错误处理、进度反馈、配置管理 +- **类型安全**: 全面TypeScript覆盖，零编译错误 +- **性能优化**: 异步处理、智能缓存、模块化加载 +- **扩展友好**: 标准化的平台接口，便于新平台接入 -### 🏗️ 架构设计师 -1. **完整设计文档**: [v1.4.0 架构文档](./architecture-v1.4.0.md) -2. **设计决策对比**: [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) -3. **性能分析**: [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) +插件专注于保证文章格式的完美同步，而不是成为一个平台编辑器。通过现代化的架构设计，为用户提供流畅、稳定的发布体验。 -### 🔄 版本升级 -1. **升级指南**: [架构升级对比 - 迁移指南](./ARCHITECTURE_UPGRADE_COMPARISON.md#📚-迁移指南) -2. **新功能说明**: [v1.4.0 架构文档 - 核心特性](./architecture-v1.4.0.md#🎯-升级概览) -3. **向后兼容性**: [架构升级对比 - 兼容性](./ARCHITECTURE_UPGRADE_COMPARISON.md#📊-性能对比) +### 图片方向自动处理 -## 🔍 核心概念速查 +为了优化微信公众号图片上传体验，插件新增了 EXIF 方向自动处理功能： -### v1.4.0 核心模块 +**功能说明：** +- 自动检测 JPEG 图片的 EXIF Orientation 信息 +- 对存在方向问题的图片自动旋转并转换为 PNG 格式 +- 确保上传到微信公众号的图片显示方向正确 -| 模块 | 文件路径 | 主要职责 | 文档链接 | -|------|----------|----------|----------| -| **ErrorHandler** | `src/core/error-handler.ts` | 统一错误处理 | [详细说明](./architecture-v1.4.0.md#21-errorhandler---统一错误处理) | -| **ProgressIndicator** | `src/core/progress-indicator.ts` | 进度反馈系统 | [详细说明](./architecture-v1.4.0.md#22-progressindicator---进度反馈系统) | -| **ConfigManager** | `src/core/config-manager.ts` | 配置管理中心 | [详细说明](./architecture-v1.4.0.md#23-configmanager---配置管理中心) | -| **PublisherManager** | `src/core/publisher-manager.ts` | 发布平台管理 | [详细说明](./architecture-v1.4.0.md#24-publisherinterface--publishermanager---发布平台抽象) | -| **ContentProcessor** | `src/core/content-processor.ts` | 内容处理流水线 | [详细说明](./architecture-v1.4.0.md#25-contentprocessor---内容处理流水线) | -| **ImageProcessor** | `src/core/image-processor.ts` | 图像处理引擎 | [详细说明](./architecture-v1.4.0.md#imageprocessor---图像处理引擎) | -| **GalleryProcessor** | `src/core/gallery-processor.ts` | 图库处理器 | [详细说明](./architecture-v1.4.0.md#galleryprocessor---图库处理器) | -| **HtmlProcessor** | `src/core/html-processor.ts` | HTML生成器 | [详细说明](./architecture-v1.4.0.md#htmlprocessor---html生成器) | +**支持的方向类型：** +- `Orientation=1`：正常方向（无需处理） +- `Orientation=3`：需旋转 180° +- `Orientation=6`：需顺时针旋转 90°（右旋 90°） +- `Orientation=8`：需逆时针旋转 90°（左旋 90°） -### 快速API参考 +**处理流程：** +1. 检测图片文件类型（仅处理 JPEG/JPG 格式） +2. 读取 EXIF 方向信息 +3. 如有方向问题，使用 Canvas 进行旋转处理 +4. 将处理后的图片转换为 PNG 格式上传 -```typescript -// 错误处理 -ErrorHandler.handle(error, 'context'); +**用户体验：** +- 本地 Obsidian 中显示正常的图片，上传到公众号后也会保持正确方向 +- 自动处理，无需用户手动调整 +- 转换为 PNG 格式可避免 EXIF 信息导致的显示问题 -// 进度反馈 -const progress = new ProgressIndicator(); -progress.start('操作开始'); -progress.finish('操作完成'); +### 调试日志 -// 配置管理 -const config = ConfigManager.getInstance(); -const value = config.get('key'); +在控制台（开发者工具）可看到： +``` +[note2mp] active file path: your/file/path.md +[note2mp] use default cover: cover.png -> ![[cover.png]] +[note2mp] EXIF orientation detected: 6 +[note2mp] Image converted to PNG with rotation +``` +路径日志做了节流：同一文件 3 秒内不重复打印。后续可加"调试开关"以完全关闭。 -// 内容处理 -const processor = ContentProcessor.getInstance(); -const result = await processor.process(content); +### 摘要、封面裁剪、原文链接等 -// 平台发布 -const publisher = PublisherManager.getInstance(); -await publisher.publishTo('platform-id', content); +## 2、安装 + +> [!TIP] +> **v1.4.0 提升**: 新版本采用模块化架构，安装更稳定，启动更快速！ + +首先，**请确认已关闭了Obsidian的安全模式**。如未关闭，请通过**设置——第三方插件——关闭安全模式**关闭。 + +### 2.1 插件安装 +通过Obsidian**设置——第三方插件——社区插件市场**，输入**Note2Any**搜索安装。 +🚩 TODO + +### 2.2 主题资源安装 +🚩 TODO + +### 2.3 常见安装问题 + +**只有默认主题** +确认根据**2.2 主题资源安装**里的步骤操作了，然后检查一下插件目录内容，应如下所示： +``` +.obsidian/plugins/note2any/ +├── assets +│ ├── themes.json +│ ├── highlights.json +│ ├── themes +│ │ ├── maple.css +│ │ ├── mweb-ayu.css +│ │ └── ... +│ └── highlights +│ ├── a11y-dark.css +│ ├── a11y-light.css +│ └── ... +├── main.js +├── manifest.json +└── styles.css ``` -## 📊 架构演进历史 +## 3、使用 +点击Obsidian左侧工具栏中的图标 +![](images/clipboard-paste.png)或者按`Ctrl+P`打开命令，搜索**复制到公众号**。 -```mermaid -timeline - title Note2Any 架构演进 - - v1.0-1.2 : 基础功能 - : 单文件实现 - : 微信公众号支持 - - v1.3.x : 功能扩展 - : 小红书支持 - : 批量发布 - : 代码重构 - - v1.4.0 : 架构升级 - : 模块化核心系统 - : 9个专业模块 - : 统一错误处理 - : 进度反馈系统 - : 1400+行新代码 - - Future : 持续演进 - : 更多平台支持 - : AI集成 - : 云端同步 +检查样式无误后，点击**复制**按钮，然后到公众号粘贴即可。 + +### 🚀 主要功能 + +**★ 智能平台切换** +插件支持多平台发布，在下拉菜单中进行不同平台的切换。新架构提供更稳定的平台管理。 + +**★ 一键复制** +检查样式无误后，点击**复制**按钮，然后到平台编辑器粘贴即可。现在具有实时状态反馈。 + +**★ 智能图片处理** +- 自动上传本地图片到目标平台 +- 支持WebP转JPG、EXIF方向自动处理 +- 批量图片处理，进度可视化 +- 点击上传图片会将文章中的本地图片上传到平台，同时替换预览中的图片地址 + +**★ 草稿发布** +点击发草稿会上传文章中的本地图片，并且将文章发送到平台的草稿箱，省去粘贴步骤。新版本提供更可靠的上传机制。 + +**★ 实时刷新** +如果笔记内容更新了，但是预览没有更新，可以点击刷新按钮。现在响应更加迅速。 + +**★ 智能封面** +- 发草稿必须设置文章封面 +- 支持默认封面、本地上传、自动提取首图 +- 新增封面处理优化，确保显示效果 + +**★ 丰富样式** +可以选取笔记的样式，目前有30多款，还在持续增加中。如果有钟意的样式，可以在插件设置中，设置为默认样式。 + +**★ 代码高亮** +设置代码高亮的样式，支持多种主题。 + + +### 数学公式使用指南 + +- [LaTeX使用指南：从入门到精通 - 少数派](https://sspai.com/post/77684) +- [通用 LaTeX 数学公式语法手册 - UinIO.com 电子技术实验室](http://www.uinio.com/Math/LaTex/) +- [AsciiMath Parser 🚀 Asciimath Parser](https://asciimath.widcard.win/zh/introduction/) +- [AsciiMath](https://asciimath.org/) + +目前插件支持LaTeX和AsciiMath两种数学公式语法，对于公式输入不是特别频繁，而且不怎么熟悉LaTeX的用户来说可以尝试使用AsciiMath，AsciiMath相对简单一些，可以现学现用，直接在官网查找手册编写就可以了。因为在正常的Markdown语法中无法区分采用的是哪种数学公式语法，所以需要在插件中设置默认的数学公式语法，默认是LaTeX语法。对于有混写需求的朋友来说，可以采用代码块的语法来写数学公式，然后指定latex或者asciimath来明确当前语法。但使用代码块语法的时候在Obsidian中并不能实时预览公式。 + +如果需要使用AsciiMath，还需要安装asciimath插件才能在Obsidian中实时预览，不过asciimath插件的解析器和官方的语法有一些差异，主要体现在矩阵写法上，所以使用时也需注意。另外需要特别提醒的是AsciiMath不支持在一个语法块中写多行公式，所以如果要写多行公式，只能每行公式单独写一个语法块。LaTeX是支持多行公式的。 + +数学公式的专业性很强，我也无法全面测试，如果遇到无法正常渲染的情况，欢迎反馈。 + +````markdown +行内公式：$c=\pm\sqrt{a^2+b^2}$ +行间公式： +$$ +c=\pm\sqrt{a^2+b^2} +$$ + +使用代码块方式可以指定公式语法，该方法仅适用行间公式。 + +采用latex语法的数学公式： +``` latex +c=\pm\sqrt{a^2+b^2} ``` -## 🛠️ 开发工具链 +采用asciimath的数学公式： +``` am +c=+-sqrt(a^2+b^2) +``` +```` -### 构建系统 -- **开发构建**: `npm run build` - 未混淆版本，便于调试 -- **生产构建**: `npm run build:obf` - 混淆版本 -- **本地同步**: `./build.sh` - 构建并同步到本地Obsidian +数学公式的渲染效果可以看这篇文章：[公众号文章里的数学公式排版秘籍](https://mp.weixin.qq.com/s/-kpT2U1gT_5W3TsDCAVgsw)👈️ +### 自定义CSS使用指南 -### 代码质量 -- **TypeScript**: 100% 类型覆盖，零编译错误 -- **ESLint**: 代码规范检查 -- **模块化**: 9个核心模块，职责明确 -- **测试**: 单元测试和集成测试 +## 开发与构建 -### 调试工具 -```javascript -// 浏览器控制台调试命令 -console.log('错误统计:', ErrorHandler.getErrorStats()); -console.log('配置状态:', ConfigManager.getInstance().getAll()); -console.log('已注册处理器:', ContentProcessor.getInstance().getProcessors()); +> [!INFO] +> **v1.4.0 架构升级**: 新版本采用模块化架构，包含9个核心模块，1400+行新代码，提供更好的开发体验！ + +### 🛠️ 构建系统 + +本仓库提供多种构建选项： +- `npm run build`：生成未混淆的 `main.js`，便于调试和开发 +- `npm run build:obf`：生产模式启用 `javascript-obfuscator`，生成混淆后的 `main.js` +- `./build.sh`：执行默认构建并同步到本地 Obsidian 插件目录 +- `./build.sh obf`：执行混淆构建后再进行同步 + +### 🏗️ 架构特性 + +**模块化设计**: 新版本将原有单体架构拆分为9个专业模块： +- `ErrorHandler`: 统一错误处理 +- `ProgressIndicator`: 进度反馈系统 +- `ConfigManager`: 配置管理 +- `PublisherInterface & PublisherManager`: 发布平台抽象 +- `ContentProcessor`: 内容处理流水线 +- `GalleryProcessor`: 图库处理 +- `ImageProcessor`: 图像处理 +- `HtmlProcessor`: HTML生成 + +**类型安全**: 全面TypeScript覆盖，零编译错误，提供完整的类型推导。 + +**性能优化**: 异步处理、智能缓存、模块化加载，提升用户体验。 + +如需自定义混淆行为，可在执行命令时设置环境变量（例如 `OBFUSCATE=1 npm run build:bundle`），详细参数见 `esbuild.config.mjs`。 +新建一篇笔记，例如**自定义样式**，直接将如下内容粘贴进笔记： + +````CSS +```CSS +.note-to-mp { + font-family: Optima, Optima-regular, "Microsoft YaHei", PingFangSC-regular, serif; + padding: 0; + background-color: #FFFFFF; +} +``` +```` + +然后打开Note2Any插件设置，将**自定义样式**（即包含自定义CSS内容的笔记名称），粘贴到**自定义CSS笔记**中即可。如果不使用自定义CSS，留空即可。 + +关于自定义CSS的写法可以参考下面的代码 +```css +/* 全局属性 + * 这里可以设置字体，字体大小，边距，背景颜色等 + */ +.note2any { + /* 注：请在大括号内改写！！！ */ +} + +/* 段落 */ +.note2any p { + /* 注：请在大括号内改写！！！ */ +} + +/* 一级标题 */ +.note2any h1 { + /* 注：请在大括号内改写！！！ */ +} + + +/* 二级标题 */ +.note2any h2 { + /* 注：请在大括号内改写！！！ */ +} + + +/* 三级标题 */ +.note2any h3 { + /* 注：请在大括号内改写！！！ */ +} + + +/* 无序列表整体样式 + * list-style-type: square|circle|disc; + */ +.note2any ul { + /* 注：请在大括号内改写！！！ */ +} + +/* 加粗 */ +.note2any strong { + /* 注：请在大括号内改写！！！ */ +} + +/* 斜体 */ +.note2any em { + /* 注：请在大括号内改写！！！ */ +} + +/* 加粗斜体 */ +.note2any em strong { + /* 注：请在大括号内改写！！！ */ +} + +/* 删除线 */ +.note2any del { + /* 注：请在大括号内改写！！！ */ +} + +/* 分隔线 + */ +.note2any hr { + /* 注：请在大括号内改写！！！ */ +} +/* 图片 + */ +.note2any img { + /* 注：请在大括号内改写！！！ */ +} +/* + * 文件嵌入引用 + */ +.note-embed-file { + /* 注：请在大括号内改写！！！ */ +} +/* + * 高亮颜色 + */ +.note-highlight { + /* background-color: rgba(255,208,0, 0.4); */ +} + +/* + * Callout + * 可以调整各种类型Callout的文字颜色和背景颜色 + * color: rgb(158, 158, 158); + * background-color: rgba(158, 158, 158, 0.1); + */ +.note-callout-note { +} +/* abstract tip hint */ +.note-callout-abstract { +} +.note-callout-success { +} +/* question help, faq, warning, caution, attention */ +.note-callout-question { +} +/* failure, fail, missing, danger, error, bug */ +.note-callout-failure { +} +.note-callout-example { +} +.note-callout-quote { +} ``` -## 📋 待办事项 +例如这篇文章[几个让公众号排版更精致的小技巧，手机上也可以！](https://mp.weixin.qq.com/s/Q4_pV9TW8un3qZ0vrUvD1A)👈️使用的自定义样式如下： +```css +.note2any { + font-family: Optima-regular, Optima, "Microsoft YaHei", PingFangSC-regular, serif; +} -### v1.4.x 计划 -- [ ] 完成 article-render.ts 重构 -- [ ] 实现更多内容处理器 -- [ ] 优化性能和稳定性 -- [ ] 完善测试覆盖 +h2 strong { + display: inline-block; + background: rgb(90, 185, 131); + color: rgb(255, 255, 255); + padding: 2px 16px; + border-top-right-radius: 3px; + border-top-left-radius: 3px; + margin-right: 10px; + visibility: visible; +} -### v1.5.x 计划 -- [ ] 新平台支持 (知乎、CSDN等) -- [ ] 插件化处理器市场 -- [ ] AI内容优化集成 -- [ ] 批量操作增强 +h2 { + border-bottom: rgb(90, 185, 131) 2px solid; + color: rgb(90, 185, 131); +} -## 🤝 贡献指南 +section .note-callout-example { + color: rgb(90, 185, 131); + background-color: rgba(90, 185, 131, 0.1); +} +``` +上面的例子，通过`.note2any`指定了文章的字体，通过`h2 strong`单独定义了h2标题下strong的样式，这样可以在标题中通过使用粗体增加了一个边框样式。通过`h2`定义了h2标题的底部线条的宽度和文本颜色。这样配合**Olive Dunk**主题就形成了自己的风格。 +### 公众号名片 -### 文档贡献 -1. **更新现有文档**: 发现过时信息请提交PR -2. **添加新文档**: 新功能需要配套文档 -3. **翻译文档**: 欢迎多语言版本 +请参考 https://mp.weixin.qq.com/s/1wYd15Irmv9BPabgp5XMCA -### 代码贡献 -1. **遵循架构**: 使用v1.4.0模块化架构 -2. **错误处理**: 使用ErrorHandler统一处理 -3. **进度反馈**: 长时间操作使用ProgressIndicator -4. **类型安全**: 保持100% TypeScript覆盖 -## 📞 获取帮助 +### 设置图片大小 -### 技术支持 -- **问题反馈**: [GitHub Issues](https://biboer.cn/gitea/gavin/note2any/issues) -- **讨论交流**: [GitHub Discussions](https://biboer.cn/gitea/gavin/note2any/discussions) -- **文档建议**: 通过Issues提交文档改进建议 +在Obsidian中可以设置图片的大小，语法如下： -### 快速联系 -- **架构问题**: 查看[v1.4.0架构文档](./architecture-v1.4.0.md) -- **开发问题**: 查看[快速参考指南](./ARCHITECTURE_QUICK_REFERENCE.md) -- **升级问题**: 查看[升级对比文档](./ARCHITECTURE_UPGRADE_COMPARISON.md) +```markdown +![[1.jpg|120x80]] 设置图片的宽度和高度 +![[1.jpg|120]] 设置图片的宽度，高度按比例缩放 +``` + +NoteToMP插件支持该语法。 + +### 文件嵌入 + +文件嵌入是Obsidian一个很有用的功能，可以直接展示其它文件中的段落、章节。在写公众号的时候可以将以前文章的内容引用展示，也可以将该功能当作模板使用。 + +文件嵌入的语法如下： + +```markdown +![[文件名称#章节标题]] +![[文件名称#^段落标记]] +``` + +在Note2Any插件中有两种展示文件嵌入内容的样式，一种是引用，也就是Obsidian默认的方式，一种是正文，相当于模板的方式。与模板不同的是，采用嵌入方式内容会跟随被嵌入文件的内容更改。 + +## 批量发布（Batch Publish） + +从 v1.3 起，插件新增“批量发布文章”功能，方便把满足条件的一批文章批量发送到公众号草稿箱以便后续编辑与发布。 + +如何打开：在命令面板（Ctrl/Cmd+P）中搜索“批量发布文章”，或在插件命令中找到“批量发布文章”。 + +主要功能： +- 条件筛选：按标签（tag）、文件名关键字、文件夹路径、及 frontmatter 字段进行筛选，支持 AND/OR 逻辑组合（当前为 AND 默认行为）。 +- 预览与选择：筛选结果以列表展示，支持单个复选、全选、取消全选，以及鼠标拖拽框选（常规拖拽为添加选择，按 Ctrl/Cmd 拖拽为取消选择）。 +- 批量发布：点击“发布选中文章”后会依次调用渲染与上传流程（与单篇发布同一实现），每篇之间有 2s 延迟以降低并发请求风险。发布过程中会显示进度通知并在结束汇总成功/失败数量。 + +注意事项： +- 批量发布会激活 NotePreview 视图并复用其渲染/上传逻辑，若无法取得 NotePreview，将无法完成发布。 +- 单篇发布失败不会中断整体流程，失败项会在结束时统计并提示。 +- 为避免误操作，建议先在小范围内测试筛选条件与发布流程再对大量文件执行批量发布。 + +示例使用场景： +- 你想要把所有标记为 `篆刻` 的文章筛选出来，批量上传到公众号草稿箱并逐条完善后发布。 +- 按文件夹 `content/post` 筛选并批量发布该文件夹下的近期文章。 + +### 使用指南 + +1. 打开模态 + - 命令面板（Ctrl/Cmd+P）→ 输入“批量发布文章”，回车打开模态窗口。 +2. 设置筛选条件 + - 按标签：在“按标签筛选”中输入标签名（例如 `篆刻`）。 + - 按文件名：输入关键词（例如 `教程`）。 + - 按文件夹：输入路径（例如 `content/post`）。默认值已预填为 `content/post`。 + - 按 frontmatter：目前可通过自定义筛选扩展（未来计划支持更复杂的 frontmatter 表达式）。 +3. 回车快速应用 + - 在任一输入框中按回车将立即执行“应用筛选”。 +4. 选择文章 + - 使用复选框逐条选择；点击行的任意位置也会切换对应复选框。 + - 使用鼠标拖拽进行框选：不按修饰键时为“添加选择”，按住 Ctrl/Cmd 时为“取消选择”。 + - 支持“全选/取消全选”复选框。 +5. 批量发布 + - 点击“发布选中文章”开始发布。发布会按顺序执行并在每篇之间等待 2 秒。 + - 发布过程中会显示进度提示（Notice），发布结束会弹出成功/失败汇总。 + +### 筛选示例（可参考） +- 筛选有 `篆刻` 标签的文章：在标签输入框输入 `篆刻`，按回车。 +- 筛选文件名包含 `教程` 的文章：在文件名输入框输入 `教程`。 +- 同时按标签和目录筛选：标签输入 `篆刻`，文件夹输入 `content/post`，按回车。 + +### 常见问题与故障排查 + +- 无法发布或没有响应：检查是否已激活 `NotePreview` 视图（插件会在发布前尝试激活）；如果视图打开失败，尝试手动打开插件右侧的预览窗格再重试。 +- 部分文章发布失败：失败不会中断整体流程，发布结束时会通知失败数量。点击失败项单独重试发布。 +- 图片上传失败或方向错误：插件会自动处理 JPEG 的 EXIF 方向并转换为 PNG，若仍有问题请检查图片是否受损，或在 `开发者工具` 查看日志（节流为 3 秒同一路径）。 +- 筛选结果为空：确认筛选条件是否正确（区分目录路径、标签是否存在、关键词是否拼写正确）。可以先留空所有条件查看全部可用文章，然后逐项缩小范围。 + +### 配置说明（相关设置） + +- `defaultCoverPic`：默认封面文件名（默认 `cover.png`），当文章没有 frontmatter 封面与正文首图时使用。 +- `galleryNumPic`：Gallery 展开时默认选取的图片数量（可在设置中调整）。 +- `batchPublishPresets`：预设筛选模板（可在插件设置中新增常用筛选项）。 + +### 使用建议与最佳实践 + +- 先在少量文章上试运行一次批量发布，确认模板、封面与图片上传逻辑满足需求，再对大量文件执行批量发布。 +- 如果担心频率限制或网络不稳定，可在代码中调整发布间隔（当前为 2s）或分批次发布以降低失败率。 +- 建议为常用筛选条件创建 Preset（设置中），节省重复输入时间。 + +### 示例：把 database 视图筛选规则映射到模态 + +如果你使用 Obsidian Dataview 或内置视图创建了如下视图： + +```yaml +views: + - type: table + name: 表格 + filters: + and: + - file.tags.contains("篆刻") + order: + - file.name +``` + +在模态中相当于：标签输入 `篆刻`，排序选择按 `文件名（name）`。 --- -**维护说明**: 本索引文档会随着架构演进持续更新，请定期查看获取最新信息。 +如果你还需要我把一张示例截图（标注关键按钮）加入 README，我可以把占位图片生成并放到 `images/` 目录（需要你允许我在本地生成渲染的图片），或者我可以为你准备好截图模板与标注位置说明，方便你手动截屏粘贴。 + +### 插入SVG图标 +https://www.bilibili.com/video/BV15XWVeEEJa/ + +### Gallery 短代码支持 + +自 1.x 版本起，插件支持将形如 Hugo/Hexo 风格的短代码： + +``` +{{}}{{}} +``` + +在渲染阶段自动展开为若干行图片 WikiLink： + +``` +![[001.jpg]] +![[002.jpg]] +``` + +可选参数新增： + +`mppickall=1` 选取目录中所有图片（忽略“Gallery 选取图片数”限制）；`mppickall=0` 或缺省时按配置的数量限制。支持写法：`mppickall=1`、`mppickall='1'`、`mppickall="1"`（0 同理）。 + +示例： + +``` +{{}}{{}} +``` + +或属性顺序不同、带 figcaption： + +``` +{{}}{{}} +``` + +在 `mppickall=1` 情况下，仍保持文件名排序（同原逻辑）。 + +配置项： + +- Gallery 根路径（galleryPrePath）：指向本地实际图片根目录，用于拼接短代码中的 dir 得到真实磁盘路径。 +- Gallery 选取图片数（galleryNumPic）：每个 gallery 最多展开前 N 张图片（按文件名排序）。 + +可在插件设置界面直接修改，无需重启。若希望随机选取或按时间排序，可后续在 issue 中反馈需求。若需要永久“全部图片”效果，可同时将“选取图片数”设为一个足够大的值，或在需要的单个 gallery 上使用 `mppickall=1` 精确控制。 + +### Gallery 块与 figure 支持 + +除了带 dir 的短代码，还支持块级： + +``` +{{}} +{{
}} +{{
}} +{{}} +``` + +渲染为： + +``` +![[a.jpg]] +![[b.png]] +``` + +说明： +- 支持 `src` 或 `link` 属性任选其一。 +- `caption` 当前忽略（可后续增强：写入 `![[file|caption]]` 或紧随段落）。 +- 去重/排序策略：按出现顺序，文件名原样。 + +### 自定义行级语法扩展 + +为提升公众号排版效率，插件内置以下“轻语法”转换（发生在 Markdown 解析前）： + +1. 斜体标注：`[fig 一段说明 /]` → `一段说明` +2. 彩色提示块（只作用当前这一行，不跨行）： + - `|| 内容` 默认灰底 + - `||r 内容` 棕底白字 + - `||g 内容` 黄绿色背景 + - `||b 内容` 浅灰背景 + - `||y 内容` 浅黄背景 + +这些语法不会写回原笔记，只影响发布预览。后续可加入：类名替换 + 主题化配置 + caption 支持，欢迎反馈需求。 + +### 无图片时的默认封面 + +自动封面选择优先级： +1. frontmatter: cover / image（非空） +2. 正文首图（Markdown 或 WikiLink） +3. Gallery 短代码 / 块展开得到的首图 +4. 默认封面 `defaultCoverPic`（设置面板可配置，默认 `cover.png`） + +配置说明： +- 若填写文件名（如 `cover.png`），会按当前笔记目录解析并包装为 `![[cover.png]]`。 +- 若填写完整 `![[xxx]]` 语法或 `http(s)://` URL，将原样使用。 +- 若文件不存在，不会报错（可后续增加存在性提示）。 + +### Frontmatter 解析回退 + +如果 Obsidian `metadataCache` 暂未命中（例如首次载入或缓存延迟），插件会手动对首段 `---` YAML 进行轻量行级解析，提取： +- title / author / cover(image) + +避免因为缓存未就绪导致标题/作者缺失。若需复杂 YAML（数组、多行字符串）建议等待官方缓存，或后续考虑引入完整 YAML 解析库。 + +### 摘要、封面裁剪、原文链接等 +```yaml +--- +标题: +作者: douboer +封面: "![[封面模板.jpeg]]" +摘要: +封面裁剪: +原文地址: +打开评论: true +仅粉丝可评论: true +公众号: douboer +样式: MWeb Panic +代码高亮: docco +--- +``` + +## 附：批量发布 - 快速交互速览与截图占位 + +如果你想把功能教学放到 README 中，这里是推荐的简短速览（已在模态中实现）： + +- 回车快速应用：在任一筛选输入框中按回车即可触发“应用筛选”，无需额外点击按钮。 +- 鼠标框选：在结果列表中按住鼠标左键并拖拽可以创建选择框，松开后会添加范围内的文章为选中状态。 +- Ctrl/Cmd + 拖拽：按住 Ctrl（或 macOS 上的 Cmd/Meta）再拖拽会把框内的文章从当前选择中取消（方便进行批量取消选中）。 +- 全选/取消全选：列表顶部提供全选复选框，一键切换所有结果的选择状态。 + +截图占位：如果你希望我把一张带标注的示例截图放到 `images/`，请回复“可以生成截图”，我会： + +1. 在 `images/` 中放置占位文件 `batch-publish-example.png`（示例标注）， +2. 在 README 中替换占位为图片预览并附带关键交互标注说明。 + +如果你更愿意手动截屏，我也可以把一个标注模板（SVG 或说明）发给你，方便手动粘贴到 `images/` 目录。 + +--- + +## 📚 相关文档 + +- [完整更新日志](./CHANGELOG.md) - 查看所有版本的详细更新记录 +- [版本发布信息](./release.md) - 版本发布说明和技术细节 +- [架构优化报告](./docs/OPTIMIZATION_REPORT_v1.4.0.md) - v1.4.0架构升级详情 +- [问题反馈](https://biboer.cn/gitea/gavin/note2any/issues) - 报告问题或提出建议 +- [发布页面](https://biboer.cn/gitea/gavin/note2any/releases) - 下载最新版本 + +## 🤝 贡献 + +欢迎提交Issue和Pull Request来帮助改进Note2Any！ + +## 📜 许可证 + +本项目基于相应许可证开源，详见项目仓库。 + + -**文档版本**: v1.4.0 -**最后更新**: 2025年10月16日 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b4a7eda --- /dev/null +++ b/docs/README.md @@ -0,0 +1,179 @@ +# Note2Any 架构文档索引 + +> **架构版本**: v1.4.0 (模块化核心系统) +> **更新日期**: 2025年10月16日 + +## 📚 文档导航 + +### 🌟 主要架构文档 + +| 文档 | 描述 | 适用版本 | 推荐度 | +|------|------|----------|--------| +| [v1.4.0 架构文档](./architecture-v1.4.0.md) | 🆕 最新完整架构设计 | v1.4.0+ | ⭐⭐⭐⭐⭐ | +| [架构快速参考](./ARCHITECTURE_QUICK_REFERENCE.md) | 🔄 v1.4.0 快速上手指南 | v1.4.0+ | ⭐⭐⭐⭐⭐ | +| [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) | 🆕 v1.3.x → v1.4.0 对比 | 升级参考 | ⭐⭐⭐⭐ | +| [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) | 详细优化过程记录 | v1.3.12 | ⭐⭐⭐ | + +### 📖 历史架构文档 + +| 文档 | 描述 | 适用版本 | 状态 | +|------|------|----------|------| +| [架构总览 (旧版)](./architecture.md) | v1.3.x 旧架构文档 | v1.3.x | 🔒 已过时 | +| [架构对比 (旧版)](./ARCHITECTURE_COMPARISON.md) | v1.3.x 内部对比 | v1.3.x | 🔒 已过时 | +| [重构完成报告](./ARCHITECTURE_REFACTORING_COMPLETE.md) | v1.3.x 重构记录 | v1.3.x | 🔒 已过时 | + +## 🎯 按用途查找文档 + +### 🔰 新用户入门 +1. **了解整体架构**: [v1.4.0 架构文档](./architecture-v1.4.0.md) +2. **快速上手开发**: [架构快速参考](./ARCHITECTURE_QUICK_REFERENCE.md) +3. **查看升级改进**: [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) + +### 👨‍💻 开发者指南 +1. **核心模块使用**: [v1.4.0 架构文档 - 核心模块详解](./architecture-v1.4.0.md#2-核心模块详解) +2. **添加新功能**: [快速参考 - 常见任务示例](./ARCHITECTURE_QUICK_REFERENCE.md#📝-常见任务示例-v140) +3. **扩展新平台**: [快速参考 - 添加新平台](./ARCHITECTURE_QUICK_REFERENCE.md#2-添加新平台支持) + +### 🏗️ 架构设计师 +1. **完整设计文档**: [v1.4.0 架构文档](./architecture-v1.4.0.md) +2. **设计决策对比**: [架构升级对比](./ARCHITECTURE_UPGRADE_COMPARISON.md) +3. **性能分析**: [优化报告](./OPTIMIZATION_REPORT_v1.3.12.md) + +### 🔄 版本升级 +1. **升级指南**: [架构升级对比 - 迁移指南](./ARCHITECTURE_UPGRADE_COMPARISON.md#📚-迁移指南) +2. **新功能说明**: [v1.4.0 架构文档 - 核心特性](./architecture-v1.4.0.md#🎯-升级概览) +3. **向后兼容性**: [架构升级对比 - 兼容性](./ARCHITECTURE_UPGRADE_COMPARISON.md#📊-性能对比) + +## 🔍 核心概念速查 + +### v1.4.0 核心模块 + +| 模块 | 文件路径 | 主要职责 | 文档链接 | +|------|----------|----------|----------| +| **ErrorHandler** | `src/core/error-handler.ts` | 统一错误处理 | [详细说明](./architecture-v1.4.0.md#21-errorhandler---统一错误处理) | +| **ProgressIndicator** | `src/core/progress-indicator.ts` | 进度反馈系统 | [详细说明](./architecture-v1.4.0.md#22-progressindicator---进度反馈系统) | +| **ConfigManager** | `src/core/config-manager.ts` | 配置管理中心 | [详细说明](./architecture-v1.4.0.md#23-configmanager---配置管理中心) | +| **PublisherManager** | `src/core/publisher-manager.ts` | 发布平台管理 | [详细说明](./architecture-v1.4.0.md#24-publisherinterface--publishermanager---发布平台抽象) | +| **ContentProcessor** | `src/core/content-processor.ts` | 内容处理流水线 | [详细说明](./architecture-v1.4.0.md#25-contentprocessor---内容处理流水线) | +| **ImageProcessor** | `src/core/image-processor.ts` | 图像处理引擎 | [详细说明](./architecture-v1.4.0.md#imageprocessor---图像处理引擎) | +| **GalleryProcessor** | `src/core/gallery-processor.ts` | 图库处理器 | [详细说明](./architecture-v1.4.0.md#galleryprocessor---图库处理器) | +| **HtmlProcessor** | `src/core/html-processor.ts` | HTML生成器 | [详细说明](./architecture-v1.4.0.md#htmlprocessor---html生成器) | + +### 快速API参考 + +```typescript +// 错误处理 +ErrorHandler.handle(error, 'context'); + +// 进度反馈 +const progress = new ProgressIndicator(); +progress.start('操作开始'); +progress.finish('操作完成'); + +// 配置管理 +const config = ConfigManager.getInstance(); +const value = config.get('key'); + +// 内容处理 +const processor = ContentProcessor.getInstance(); +const result = await processor.process(content); + +// 平台发布 +const publisher = PublisherManager.getInstance(); +await publisher.publishTo('platform-id', content); +``` + +## 📊 架构演进历史 + +```mermaid +timeline + title Note2Any 架构演进 + + v1.0-1.2 : 基础功能 + : 单文件实现 + : 微信公众号支持 + + v1.3.x : 功能扩展 + : 小红书支持 + : 批量发布 + : 代码重构 + + v1.4.0 : 架构升级 + : 模块化核心系统 + : 9个专业模块 + : 统一错误处理 + : 进度反馈系统 + : 1400+行新代码 + + Future : 持续演进 + : 更多平台支持 + : AI集成 + : 云端同步 +``` + +## 🛠️ 开发工具链 + +### 构建系统 +- **开发构建**: `npm run build` - 未混淆版本，便于调试 +- **生产构建**: `npm run build:obf` - 混淆版本 +- **本地同步**: `./build.sh` - 构建并同步到本地Obsidian + +### 代码质量 +- **TypeScript**: 100% 类型覆盖，零编译错误 +- **ESLint**: 代码规范检查 +- **模块化**: 9个核心模块，职责明确 +- **测试**: 单元测试和集成测试 + +### 调试工具 +```javascript +// 浏览器控制台调试命令 +console.log('错误统计:', ErrorHandler.getErrorStats()); +console.log('配置状态:', ConfigManager.getInstance().getAll()); +console.log('已注册处理器:', ContentProcessor.getInstance().getProcessors()); +``` + +## 📋 待办事项 + +### v1.4.x 计划 +- [ ] 完成 article-render.ts 重构 +- [ ] 实现更多内容处理器 +- [ ] 优化性能和稳定性 +- [ ] 完善测试覆盖 + +### v1.5.x 计划 +- [ ] 新平台支持 (知乎、CSDN等) +- [ ] 插件化处理器市场 +- [ ] AI内容优化集成 +- [ ] 批量操作增强 + +## 🤝 贡献指南 + +### 文档贡献 +1. **更新现有文档**: 发现过时信息请提交PR +2. **添加新文档**: 新功能需要配套文档 +3. **翻译文档**: 欢迎多语言版本 + +### 代码贡献 +1. **遵循架构**: 使用v1.4.0模块化架构 +2. **错误处理**: 使用ErrorHandler统一处理 +3. **进度反馈**: 长时间操作使用ProgressIndicator +4. **类型安全**: 保持100% TypeScript覆盖 + +## 📞 获取帮助 + +### 技术支持 +- **问题反馈**: [GitHub Issues](https://biboer.cn/gitea/gavin/note2any/issues) +- **讨论交流**: [GitHub Discussions](https://biboer.cn/gitea/gavin/note2any/discussions) +- **文档建议**: 通过Issues提交文档改进建议 + +### 快速联系 +- **架构问题**: 查看[v1.4.0架构文档](./architecture-v1.4.0.md) +- **开发问题**: 查看[快速参考指南](./ARCHITECTURE_QUICK_REFERENCE.md) +- **升级问题**: 查看[升级对比文档](./ARCHITECTURE_UPGRADE_COMPARISON.md) + +--- + +**维护说明**: 本索引文档会随着架构演进持续更新，请定期查看获取最新信息。 + +**文档版本**: v1.4.0 +**最后更新**: 2025年10月16日 \ No newline at end of file