Fireflux —— 给 Firefly 博客配了一个本地管理客户端

🤔 缘起：一个静态博客的日常#

这个博客是用 Astro 静态生成的，主题是 Firefly。静态站的好处很实在 —— 没有服务端、没有数据库、不怕被打、内容全是纯文本，丢了也能从 git 里捞回来。

但「没有后台」这件事，代价全落在日常维护上。真实的一天大概是这样的：

• 写一篇文章：打开编辑器 → 在 src/content/posts/ 里找位置 → 新建 .md → 手写 frontmatter。而主题的 frontmatter 有十几个字段（标题、发布日期、草稿、分类、标签、封面、语言、系列、版权……），字段名和类型必须与 src/content.config.ts 里的 schema 严格对齐，写错一个字段名就是构建失败，而失败信息要到 CI 上才看得到。
• 插一张图：手动把图片复制到与文章同名的附件目录里，再手写一段相对路径。路径写错就是线上裂图，本地预览还未必看得出来。
• 改一个配置：主题有 25 个配置文件放在 src/config/ 下，全是带中文注释的 TypeScript。想关掉一个页面、换一套主题色、调一下导航顺序，都得先读代码、找字段、确认类型，改完还要小心别把注释和 as const 弄丢。
• 整理相册：图片顺序靠改文件名，封面靠改 galleryConfig.ts 里的字段，远程图和本地图还分两段、不能互跨。
• 发出去：回到终端 git add → git commit → git push，等 CI 构建完再看线上效果。
• 删错东西：rm 一时爽，找回来全靠 git —— 而如果是没提交过的附件，那就真没了。

单看每一步都不难，但它们散在编辑器、文件管理器、浏览器和终端之间。真正的问题是摩擦成本太高：想随手发一条动态，一想到要开三个软件、手写一段 YAML，就懒得发了。

🎯 目标：只做两件事#

于是决定自己写一个本地客户端来解决这件事。目标定得很窄，但很明确：

1. 按规则读写博客项目里的文件 —— 把 frontmatter、目录约定、配置结构这些「主题的隐性知识」固化进代码，用户只填内容。
2. 调用本机的 git —— 把「暂存 / 提交 / 推送」搬到界面上，不用再切终端。

同时划清边界，这几件事明确不做：

• 不改主题源码。主题仓库保持原样，升级主题不会被客户端拖住。
• 不加服务端、不加数据库、不做账号体系、不做云端同步。
• 不改变博客的形态：它依然是纯静态站，构建和部署链路原封不动。

一句话概括：客户端只是让「编辑文件 + 提交推送」顺手一点，博客本身什么都没变。

📦 它是什么#

• 一个 Windows 桌面应用，技术栈是 Tauri v2（Rust 后端）+ Svelte 5 + TypeScript。业务逻辑写在 Rust 侧，能脱离界面直接跑单元测试。
• 界面启动时是这样一张加载屏 —— 底图、标题、进度条都是纯 CSS，用来填掉 WebView 初始化那一两秒的空白：

• 当前版本 v1.0.0，提供两种 Windows x64 产物：单文件直接执行版（一个裸 exe，拷到哪都能双击运行）与 NSIS 安装包。两者功能完全一致，只是形态不同。

✨ 功能一览#

💬 动态发布#

远端模式直接把 Memos 嵌进窗口里，登录状态会被记住，发完刷新博客就能看到。

不想用 Memos 也可以切到本地模式，用表单 + Markdown 写，支持插图与从磁盘导入已有的 md：

📄 文章管理#

列表、编辑、分屏预览、新建都在同一页。新建时中文标题会自动转成拼音 slug（与主题自带的 new-post 脚本一致），并按内容类型生成对应的 frontmatter 骨架 —— 不用再对着 schema 手抄字段名。支持插入本地配图（自动复制到与文章同名的附件目录并生成引用路径）、从磁盘导入已有的 md、克隆、以及保存后扫描未被正文引用的附件。

「项目展示」和「Spec 页面」共用同一套编辑器，只是根目录不同。

🖼️ 相册管理#

相册列表与图片网格：拖动排序、拖到第一格设为封面、远程图（urls.txt）排序、图片别名、加密、克隆、软删除。右键可以在系统文件管理器里打开图片或相册目录。

🎛️ 配置中心#

主题的 25 个配置文件全部图形化：下拉框、开关、列表增删排序，以及图片 / 音乐 / 视频 / 二维码的导入（自动复制到约定目录并生成引用路径）。嵌套的子配置也能识别，比如看板娘的两块配置：

保存时只补丁被改动的字段，中文注释和其余代码原样保留。配置文件是写给人看的，不该被工具重新格式化一遍。

🚀 发布上线#

改动清单、原始 git 命令、提交信息、分支与远程仓库管理都在一页里。暂存、提交、推送是三个独立按钮 —— 推送是不可逆的对外动作，不该混在「一步到位」里。推送前还会再确认一次。

⚙️ 设置#

绑定 / 更换博客项目文件夹、主题色、壁纸与不透明度、数据目录、看板娘开关与大小位置、拖拽布局、即时预览都在这里调，改完即时生效并记住。

🚀 怎么用#

1
pnpm install
2
pnpm build        # 产出单文件可执行版与 NSIS 安装包

🔧 几个折腾过的地方#

• 配置改不坏：配置引擎是 Rust 侧自研的 TypeScript 字面量解析器，按 span 只替换被修改字段的字面量。写盘前会重新解析一遍复核，只要有一处对不上就整份不写。
• 看板娘不烧 CPU：只在指针移动、与它互动和动作尾随期间逐帧渲染，其余时间渲染完最后一帧就完全停住，静止态 CPU 归零。
• 布局可以自己排：侧栏每个模块、各页每张卡片都能拖。没有「编辑模式」，也没有拖拽图标 —— 按住空白处就拖，松手即落盘。这一块踩过两个坑：重排 Svelte 直接管理的顶层节点会破坏它的清理链（切页后卡片会残留在别的页面上），以及整块被 iframe 铺满的模块因为 pointerdown 不冒泡而 100% 拖不动。
• 附件跟着文章走：附件目录与 Markdown 同名、放在同一层。如果同名目录里已经有 Markdown，说明那是个内容分组目录，往里塞图会直接报错而不是静默换个地方。
• 接口契约有编译期断言：前端 api.d.ts 的声明与 tauri-api.ts 的实现会在 tsc 阶段双向比对，少一个方法就编译不过。
• 验证靠真界面：除了类型检查和 246 个 Rust 单元测试，还有 16 个 CDP 探针直接驱动运行中的窗口 —— 真的去拖分隔条、切页、弹确认框、走完一整条发帖流程。

🔐 数据与边界#

• 所有设置与壁纸都放在客户端自己的 data/ 目录，不写进博客项目、也不会被提交。
• 只允许操作白名单目录：src/content、src/config、public，主题源码不在其中。
• 没有账号体系，也没有云端同步，所有操作都在本机完成。
• 客户端不做请求级诊断：内嵌网页里的图片裂开、接口断连这类子资源失败在界面上看不到，需要更细的信息请按 F12 → Network 排查，或点「↗ 在浏览器打开」用系统浏览器对照。

📥 获取#

• GitHub 仓库：https://github.com/loveFirefly-26710/Fireflux
• Releases（下载）：https://github.com/loveFirefly-26710/Fireflux/releases
• 文档：参数说明 · 开发笔记 · 构建方案

🙏 致谢#

• 博客主题：Firefly —— 一款基于 Astro 的现代化个人博客主题。客户端的「配置中心」正是围绕它的配置文件做的，站点本身也跑在它上面。
• 主题的上游：Fuwari，Firefly 基于它二次开发。
• Live2D 看板娘模型：Iskongkongyo/Firefly-live2d，模型、纹理、动作、物理与音频均出自该项目。
• 技术栈：Tauri · Svelte · Astro