墨织 InkWeave · 双面板 EPUB 阅读器 + 可视化编辑器

InkWeave — Dual-panel EPUB Reader & Visual Editor

简体中文 · English

左右双栏：左侧阅读预览，右侧图文可视化编辑，全程不暴露 HTML/CSS。 A dual-panel desktop app: reading preview on the left, rich visual editing on the right — no HTML/CSS ever exposed.

支持 TXT/EPUB 导入、自动分章、富文本排版、插图、封面裁剪、元数据、导出标准 EPUB 3、以及可被 MCP 驱动的主题系统。 Import TXT/EPUB, auto-detect chapters, rich-text formatting, image insertion, cover cropping, metadata editing, standards-compliant EPUB 3 export, and an MCP-driven theme system.

下载 · Download

Windows 用户无需安装环境，直接在 Releases 下载 InkWeave-<版本>.exe 便携版，双击即用。 Windows users can grab the portable InkWeave-<version>.exe from Releases — no install required, just double-click.

快速开始 · Getting Started

npm install
npm run dev      # 开发 Dev server (http://localhost:5173)
npm run build    # 类型检查 + 打包 Type-check + bundle
npm run preview  # 预览构建产物 Preview the production build

需 Node 18+。已内置 3 套主题，首次打开默认「暖纸书卷」。 Requires Node 18+. Ships with 3 built-in themes; defaults to "Warm Paper" on first launch.

桌面 EXE 打包 · Desktop EXE Packaging

# 国内网络建议先设镜像（否则 Electron 下载会报证书错误）
# In mainland China, set mirrors first (otherwise Electron downloads fail with cert errors)
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"

npm run dist      # 构建 + 打包 Build + package → release/InkWeave-<版本>.exe
npm start         # 以 Electron 运行 Run in Electron (需先 npm run dev)

• 产物为单文件便携版 EXE，双击即用（release/InkWeave-0.1.0.exe）。 Output is a single portable EXE (release/InkWeave-0.1.0.exe).
• 未签名，首次运行 Windows SmartScreen 可能提示，选「更多信息 → 仍要运行」即可。 Unsigned — Windows SmartScreen may warn on first run; choose "More info → Run anyway".
• 导出 EPUB / 保存工程在桌面版走系统保存对话框（electron/main.cjs + preload.cjs 的 IPC）。 EPUB export / project save use the native save dialog in the desktop build (IPC via electron/main.cjs + preload.cjs).

项目结构 · Project Structure

src/
├─ types/index.ts            # 数据模型 Data model: Book / Chapter / Asset / BookMeta / Theme
├─ store/
│  ├─ useBookStore.ts        # 书籍状态 + 撤销/重做 Book state + undo/redo (structural ops)
│  ├─ useThemeStore.ts       # 主题状态 Theme state: switch / import / preview
│  ├─ useUiStore.ts          # 分栏宽度、阅读器排版、对话框 Pane width, reader typography, dialogs
│  ├─ useEditorStore.ts      # 持有 Tiptap 实例 Holds the Tiptap instance
│  └─ useToast.ts            # 全局提示 Global toasts
├─ lib/
│  ├─ txtParser.ts           # TXT 解码 + 自动分章 TXT decode + auto chaptering
│  ├─ epubParser.ts          # EPUB 解包 EPUB unpack: OPF/spine/assets/CSS inlining
│  ├─ epubExporter.ts        # 打包标准 EPUB 3 Package standard EPUB 3 (cover/nav/ncx/chapters/styles/images)
│  ├─ themeRegistry.ts       # token→CSS 变量 + 主题导入 token→CSS vars + theme import/persist
│  └─ utils.ts               # 文件解码、下载、图片裁剪 File decode, download, image crop
├─ themes/builtin.ts         # 3 套内置主题 3 built-in themes (暖纸书卷 / 暗夜沉浸 / 复古杂志)
├─ mcp/themeSchema.ts        # MCP 主题配置 JSON Schema + 契约 MCP theme JSON Schema + contract
├─ components/
│  ├─ Toolbar.tsx            # 导入/导出/保存/新建/撤销重做/封面/元数据/主题
│  ├─ SplitPane.tsx          # 可拖拽分栏 Draggable split pane
│  ├─ reader/ReaderPanel.tsx # 阅读器 Reader (iframe 隔离 + 滚动/翻页 + 进度记忆)
│  ├─ editor/
│  │  ├─ EditorPanel.tsx
│  │  ├─ ChapterList.tsx     # 章节目录 Chapter TOC (增删改/排序/合并/拆分)
│  │  ├─ RichTextEditor.tsx  # Tiptap 编辑器主体 Tiptap editor core
│  │  ├─ FormatToolbar.tsx   # 段落样式/富文本/排版/插图 Paragraph styles / rich text / layout / images
│  │  └─ extensions/         # blockStyle(行距缩进段距) + image(宽/对齐/边距)
│  └─ dialogs/               # 元数据 / 封面裁剪 / 插图 / 主题导入
└─ styles/global.css         # 全部走 CSS 变量，随主题联动 All CSS vars, theme-driven

数据模型 · Data Model

Book        // 一本书 A book: meta + cover + chapters + assets + styles(EPUB内嵌CSS)
├─ BookMeta  // title/author/description/language/publisher/publishedDate
├─ Chapter[] // id / title / content(HTML) —— 数组顺序即目录顺序 Array order = TOC order
├─ Asset[]   // 图片资源 Image assets: id / name / mimeType / dataUrl
└─ cover     // 封面 Cover Asset | null

• 编辑器与阅读器共用同一份 Book，实现「所见即所得、即读即所得」。 Editor and reader share one Book — what you see is what you read.
• 章节内容统一存 Tiptap 输出的 HTML；导出时映射为 XHTML，图片 data URL 回收为独立资源文件。 Chapter content is stored as Tiptap HTML; on export it maps to XHTML and image data URLs are recovered as standalone asset files.

主题系统与 MCP 契约 · Theme System & MCP Contract

主题是「token 配置」，通过 applyTheme() 映射为全局 CSS 变量，界面/编辑器/阅读器即时刷新。 A theme is a "token config"; applyTheme() maps tokens to global CSS variables so the UI/editor/reader refresh instantly.

tokens: {
  colors:  { bg, surface, surfaceAlt, border, text, textMuted, accent, accentText,
             readerBg, readerText, readerSecondary, editorBg, editorText, selection, danger, success }
  fonts:   { ui, reading, heading, mono }
  spacing: { unit, radiusSm, radiusMd, radiusLg }
  texture: { type: 'none'|'paper'|'grid'|'noise', opacity, image? }
  effects: { shadow, transition }
}

MCP 接入流程 MCP integration（见 src/mcp/themeSchema.ts）：

1. MCP 输出符合 THEME_SCHEMA 的 JSON。MCP outputs JSON conforming to THEME_SCHEMA.
2. 前端 importThemeJSON(json) 解析并容错补全。The frontend parses and safely fills defaults via importThemeJSON(json).
3. 「预览」走 previewThemeJson（临时应用，不落库）；「应用并保存」走 importTheme （写入 localStorage 的自定义主题列表）。 "Preview" uses previewThemeJson (temporary, not persisted); "Apply & save" uses importTheme (persisted to a custom-theme list in localStorage).

UI 上通过工具栏「主题 → 导入主题」即可粘贴/上传 JSON 预览与应用。 In the UI, paste or upload JSON via toolbar "Theme → Import theme" to preview and apply.

已实现能力 · Features

• 双面板可拖拽布局 + 顶部工具栏 — Resizable dual-panel layout + top toolbar
• TXT 导入自动分章（第X章 / Chapter X / 空行规则）— TXT import with auto chaptering (第X章 / Chapter X / blank-line rules)
• EPUB 导入（解包 + 图片内联 + CSS 保留）— EPUB import (unpack + image inlining + CSS preserved)
• 可视化富文本：加粗/斜体/下划线/删除线/颜色/高亮/对齐/行距/缩进/段距/列表/引用/分割线 — Visual rich text: bold/italic/underline/strike/color/highlight/align/line-height/indent/spacing/lists/quote/divider
• 段落样式：正文 / 标题1-3 / 引用 / 居中 / 落款 — Paragraph styles: body / heading 1-3 / quote / centered / signature
• 插图：本地选图、调宽度/对齐/边距、自动纳入 EPUB 资源 — Images: local pick, width/align/margin, auto-included as EPUB assets
• 封面：上传 + 2:3 裁剪预览 + 自动生成封面页与元数据 — Cover: upload + 2:3 crop preview + auto cover page & metadata
• 元数据编辑（书名/作者/简介/语言/出版社/日期）— Metadata editing (title/author/description/language/publisher/date)
• 章节管理（新建/删除/重命名/排序/合并/光标处拆分）— Chapter management (add/delete/rename/reorder/merge/split-at-cursor)
• 导出标准 EPUB 3（含 nav + ncx，兼容 Apple Books / Calibre / 微信读书）— Standards-compliant EPUB 3 export (nav + ncx; compatible with Apple Books / Calibre / WeChat Read)
• 3 套主题 + 阅读器排版调节（字号/行距/亮度/边距）+ 阅读进度记忆 — 3 themes + reader typography controls (font-size/line-height/brightness/margin) + reading-progress memory
• 撤销/重做（结构操作走 book 级历史，正文编辑走编辑器内 history）— Undo/redo (book-level history for structural ops, editor history for text edits)

后续扩展点 · Roadmap

• 正文级联撤销/重做（当前正文撤销由编辑器 history 提供，跨章节不持久）— Cross-chapter text undo/redo
• 图片资源管理器（Book.assets 已预留）— Image asset manager (Book.assets already reserved)
• 阅读翻页改为真实 JS 分页（当前翻页用 CSS 多栏水平滚动近似）— Real JS pagination (currently CSS multi-column horizontal scroll)
• Tauri/Electron 桌面壳封装（当前为纯 Web，可 npm run build 后接入）— Tauri/Electron desktop shell (currently pure web)