PasteMD 详细部署教程

项目概述

PasteMD 是一款常驻系统托盘的开源效率工具，专为解决从 AI 对话网站或 Markdown 编辑器复制内容到 Word、WPS、Excel 时格式错乱的问题而设计。它从剪贴板读取 Markdown 或 HTML 富文本，调用 Pandoc 进行格式转换，并自动插入到当前光标位置，尤其擅长处理数学公式和表格。

核心功能：

  • 一键热键粘贴：默认 Ctrl+Shift+B，将剪贴板内容转换后直接插入 Office 应用
  • 智能表格识别：自动识别 Markdown 表格并粘贴到 Excel，避免在 Word 中错乱
  • 公式与格式保留：对 LaTeX 公式、粗体、代码块等格式友好，适合学术和技术文档
  • 应用扩展：可为不同应用（如语雀、Overleaf、QQ）配置 HTML/Markdown/LaTeX/文件等不同的粘贴模式
  • 转换增强：支持按转换类型配置 Pandoc Filters，自动修复部分 LaTeX 语法问题

部署前准备

系统要求

项目 要求
操作系统 Windows 10/11 或 macOS（macOS 需额外权限）
内存 2GB 及以上
磁盘空间 200MB（一体化安装包已包含 Pandoc）
目标应用 Microsoft Word、WPS Writer、Excel

前置依赖

PasteMD 依赖 Pandoc 进行格式转换。有两种方式满足此依赖：

  1. 一体化安装包（推荐）：自带 Pandoc，无需单独配置
  2. 便携版：需要你本机已安装 Pandoc 并能在命令行运行

方案一：使用一体化安装包（推荐）

这是最简单的方式，适合绝大多数用户。

步骤 1：下载安装包

访问 GitHub Releases 页面，下载 PasteMD_pandoc-Setup.exe（一体化安装包，自带 Pandoc）。

步骤 2：运行安装程序

双击安装文件，按照向导完成安装。安装程序会自动配置好 Pandoc 环境。

步骤 3：启动应用

安装完成后启动 PasteMD，程序会自动驻留在系统托盘：

  • Windows：在任务栏右下角查找 📋 图标
  • macOS：在菜单栏右上角查找 📋 图标

方案二：从源码运行（开发/自定义）

如果你需要修改源码或进行二次开发，可以从源码运行。

步骤 1：克隆仓库

1
2
git clone https://github.com/RICHQAQ/PasteMD.git
cd PasteMD

步骤 2：安装 Python 依赖

建议使用 Python 3.12 (64位)：

1
pip install -r requirements.txt

步骤 3：安装 Pandoc

如果使用便携版，需要单独安装 Pandoc：

Windows：

1
winget install --source winget --exact --id JohnMacFarlane.Pandoc

macOS：

1
brew install pandoc

步骤 4：运行

1
python main.py

步骤 5：使用 PyInstaller 打包（可选）

如果需要生成独立可执行文件：

1
2
3
4
5
6
7
pyinstaller --clean -F -w -n PasteMD \
  --icon assets\icons\logo.ico \
  --add-data "assets\icons;assets\icons" \
  --add-data "pastemd\i18n\locales\*.json;pastemd\i18n\locales" \
  --add-data "pastemd\lua;pastemd\lua" \
  --hidden-import plyer.platforms.win.notification \
  main.py

生成的程序在 dist/PasteMD.exe。

使用方法

基础工作流

使用 PasteMD 只需四步：

  1. 复制内容：从 AI 对话网站（ChatGPT、DeepSeek、Kimi 等）、Markdown 编辑器或本地 .md 文件复制内容
  2. 打开目标应用：打开 Word、WPS 或 Excel，将光标放在需要插入的位置
  3. 按下热键：默认 Ctrl+Shift+B
  4. 完成：PasteMD 会自动读取剪贴板、检测内容类型、转换格式并插入

智能识别规则

内容类型 目标应用 行为
Markdown 表格 Excel 自动粘贴到 Excel
普通 Markdown Word/WPS 转换为 DOCX 并插入
HTML 富文本 Word/WPS 直接插入保留格式
LaTeX 公式 Word/WPS 转换为可编辑公式对象

配置说明

首次运行会在用户数据目录生成 config.json：

  • Windows：%APPDATA%\PasteMD\config.json
  • macOS：~/Library/Application Support/PasteMD/config.json

核心配置项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "hotkey": "<ctrl>+<shift>+b",
  "pandoc_path": "pandoc",
  "save_dir": "%USERPROFILE%\\Documents\\pastemd",
  "keep_file": false,
  "notify": true,
  "enable_excel": true,
  "excel_keep_format": true,
  "paste_delay_s": 0.3,
  "no_app_action": "open",
  "md_disable_first_para_indent": true,
  "move_cursor_to_end": true,
  "enable_latex_replacements": true,
  "fix_single_dollar_block": true,
  "language": "zh-CN"
}

关键字段说明

字段 说明
hotkey 全局热键，语法如 <ctrl>+<alt>+v
pandoc_path Pandoc 可执行文件路径
save_dir 保留文件时的保存目录
keep_file 是否保留生成的 DOCX 文件
enable_excel 是否启用智能识别表格并粘贴到 Excel
excel_keep_format Excel 粘贴时是否保留 Markdown 格式（粗体、斜体等）
paste_delay_s 粘贴前的延迟秒数
no_app_action 未检测到目标应用时的动作：open/save/clipboard/none
move_cursor_to_end 插入内容后是否将光标移动到末尾
enable_latex_replacements 自动修复部分不兼容的 LaTeX 语法
fix_single_dollar_block 自动识别并修复单独一行的 $...$ 公式块
language 界面语言：zh-CN/en-US/ja-JP

修改后可在托盘菜单选择 “重载配置/热键” 立即生效。

高级功能

自定义 Pandoc Filters

Pandoc Filter 是在转换过程中对内容进行自定义处理的插件。PasteMD 支持配置多个 Filter，按顺序处理文档内容。

使用场景示例：Mermaid 图表支持

  1. 安装 mermaid-filter（需先安装 Node.js）：

    1
    npm install --global mermaid-filter

  2. 在配置文件中添加：

    1
    2
    3
    4
    5
    {
      "pandoc_filters": [
        "%APPDATA%\\npm\\mermaid-filter.cmd"
      ]
    }

  3. 测试：复制包含 Mermaid 图表的 Markdown，使用 PasteMD 转换，图表将被渲染为图片插入 Word。

应用扩展配置

在设置 → 应用扩展 中可为不同应用配置粘贴模式，支持按窗口标题正则匹配：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "extensible_workflows": {
    "html": {
      "enabled": true,
      "apps": [
        {
          "name": "语雀",
          "id": "/path/语雀.exe",
          "window_patterns": []
        }
      ]
    },
    "latex": {
      "enabled": true,
      "apps": [
        {
          "name": "chrome",
          "id": "/path/chrome.exe",
          "window_patterns": [".*overleaf.*"]
        }
      ]
    },
    "file": {
      "enabled": true,
      "apps": [
        {
          "name": "QQ",
          "id": "/path/qq.exe",
          "window_patterns": []
        }
      ]
    }
  }
}

工作流说明：

  • HTML/Markdown：适合语雀等富文本笔记软件
  • LaTeX：适合 Overleaf 等学术网站
  • 文件：适合 QQ、微信等作为附件粘贴的应用

AI 网站兼容性

根据官方测试，PasteMD 对主流 AI 网站的兼容性如下：

AI 网站 复制 Markdown（无公式） 复制 Markdown（含公式） 复制网页内容（含公式）
Kimi ✅ 完美支持 ✅ 完美支持 ⚠️ 无法显示公式
DeepSeek ✅ 完美支持 ✅ 完美支持 ✅ 完美支持
通义千问 ✅ 完美支持 ✅ 完美支持 ⚠️ 无法显示公式
ChatGPT ✅ 完美支持 ⚠️ 公式显示为代码 ✅ 完美支持
Gemini ✅ 完美支持 ✅ 完美支持 ✅ 完美支持
Claude ✅ 完美支持 ✅ 完美支持 ✅ 完美支持

建议：优先使用 AI 网站自带的”复制”按钮，而非手动全选复制，以确保完整的 Markdown 和 LaTeX 标记被保留。

托盘菜单功能

右键点击托盘图标可访问以下功能：

菜单项 说明
启用/禁用热键 临时开关全局热键
弹窗通知 开关系统通知
无应用时动作 未检测到目标应用时的默认动作
插入后移动光标到末尾 插入内容后是否移动光标
HTML 格式化 删除线 ~~ 转换为 <del> 等
设置热键 图形界面录制新热键
保留生成文件 勾选后生成的 DOCX 保存在 save_dir
打开保存目录 查看转换文件
查看日志 检查错误日志
编辑配置 高级配置选项
重载配置/热键 应用配置更改
检查更新 检查新版本

常见问题排查

问题 解决方案
应用未响应 检查托盘图标是否存在，确认程序正在运行
转换后公式显示为代码 ChatGPT 复制 Markdown 时公式可能以 LaTeX 代码显示，需在 Word 中手动使用公式编辑器
粘贴到 Excel 失败 确认 enable_excel 为 true，且 Excel 已打开
热键冲突 在托盘菜单选择”设置热键”重新录制
Mermaid 图表未转换 确认已安装 mermaid-filter 并正确配置路径
macOS 权限问题 需在系统偏好设置中授予辅助功能权限
Pandoc 未找到 使用一体化安装包，或手动安装 Pandoc 并配置 pandoc_path

从 AI 网站复制公式的最佳实践

根据实测经验，正确复制 AI 生成公式的关键是保留完整的 LaTeX 源码：

  1. 点击 AI 回复下方的”复制”按钮，而非手动全选
  2. 确保公式被 $...$ 或 $$...$$ 包裹
  3. 如果 AI 返回的内容没有这些标记，让它重新生成

更新与维护

检查更新

在托盘菜单选择 “检查更新”，如有新版本会显示条目，点击可打开下载页面。

备份配置

配置文件位于用户数据目录，可随时备份：

  • Windows：%APPDATA%\PasteMD\config.json
  • macOS：~/Library/Application Support/PasteMD/config.json

总结

部署方式 适用场景 难度 推荐度
一体化安装包 大多数用户 ⭐ ⭐⭐⭐⭐⭐
从源码运行 开发/自定义 ⭐⭐⭐ ⭐⭐

对于大多数用户，一体化安装包是最简单直接的选择：从 Releases 页面下载 PasteMD_pandoc-Setup.exe，安装后程序自动驻留托盘。复制 Markdown 或网页内容，在 Word/WPS/Excel 中按下 Ctrl+Shift+B，内容即可完美插入。

如需进阶功能，可通过编辑 config.json 配置 Pandoc Filters、应用扩展工作流等。修改配置后在托盘菜单选择”重载配置/热键”即可立即生效。