MD Duck
English

使用指南

本地写作，集中审阅。

让任何 AI 写和改，在 MD Duck 阅读本地文件，把不满意的段落交回修改。读满意了再发布，本地仍有原稿。Mac 与 Windows 都可以这样用。

看看零散文章、系列和其他使用场景

本指南对应免费测试版 0.1.0-beta.7。查看发布状态

先走一遍完整流程

先读一遍，再放心发布。

MD Duck 直接读取你电脑里的文件。你常用的 AI 负责写和改，你在这里阅读、判断，再用自己的工具发布。这套流程无需注册 MD Duck 账号，也不要求在阅读器里填 AI 密钥。

下载这套演示文件 把规则交给你的 AI

内含修改前后文章、修改要求和发布交接示例。先解压，用演示文件走一遍，再用于自己的草稿。

五步操作 · Mac 实际截图 · 附 Windows 用法
你使用的系统

目录结构示例

▾ library/
▾ 01-clearer-product-inquiry/
article.md
article.zh.md

解压演示文件，再用 MD Duck 打开其中的 library 文件夹。

第 1 步 / 共 5 步

继续用你熟悉的 AI 写。

让 AI 把 Markdown 保存到本地文章文件夹。AI 没有文件权限时，由你保存它返回的内容。在 MD Duck 中打开文章库，点一篇文章开始阅读。使用这套演示时，解压后选择里面的 library 文件夹。

Mac：在 Finder 中解压，再按 ⌘ O 选择 library 文件夹。

Windows：在文件资源管理器中「全部解压缩」，再按 Ctrl O 选择 library 文件夹。

在 MD Duck 中选中原段落。
Mac 实际截图，点击查看原图。Windows 使用同样的文件流程。

第 2 步 / 共 5 步

找到还没有说清楚的地方。

调到舒服的字号，有译文时可以对照阅读。例如演示文章只说「告诉供应商你的需求」，却没有解释要写清哪些信息。选中这一段，或给它截一张图。

Mac：选中原文按 ⌘ C，或用 Shift ⌘ 4 截取这一段。

Windows：选中原文按 Ctrl C，或用 Win Shift S 截取这一段。

修改要求示例

“请说明要写清产品、规格、数量、收货城市和日期。未知信息用占位符，不要编造；同步更新中英文文件。”

附上文件名，以及原文或截图。

第 3 步 / 共 5 步

在原来的 AI 对话里继续修改。

粘贴原文或附上截图，补充文章文件名和具体要求：说明产品、规格、数量、收货城市和期望日期，未知信息用占位符，不要编造。让它同步更新中英文，并保留段落标记。

Mac：按 ⌘ V 粘贴原文，或把截图文件附到 AI 对话里。

Windows：按 Ctrl V 粘贴原文；AI 对话支持时也可以直接贴入截图。

MD Duck 中保存后的双语文章。
Mac 实际截图，点击查看原图。Windows 使用同样的文件流程。

第 4 步 / 共 5 步

保存到原位置，回来再读一遍。

有文件权限的 AI 可以直接更新文件；否则由你保存它返回的修改。MD Duck 会在保存后更新。检查改后的段落、译文和图片，不满意就继续这轮来回。

Mac：在编辑器按 ⌘ S 保存，再回到 MD Duck。

Windows：在编辑器按 Ctrl S 保存，再回到 MD Duck。

发布交接示例 · 未连接真实后台

“以这份确认好的文章为准。先给我检查目标位置和最终内容；等我确认后再发布，返回线上链接。保留本地文件。”

外部 AI 需要后台权限。MD Duck 不会操作你的 CMS。

第 5 步 / 共 5 步

只把你确认好的版本交出去。

文章满意后，让有后台权限的外部 AI 准备发布，或自己操作。确认目标位置和最终内容；发布后仍保留本地文章文件夹。MD Duck 本身只负责阅读，不会替你发布。

Mac：用文章的「⋯」菜单在 Finder 中显示；备份时保留整个文件夹。

Windows：用文章的「⋯」菜单在文件资源管理器中显示；备份时保留整个文件夹。

一次审阅多处问题时，可以用批注和「复制未完成」集中交给 AI；只改一段，截图或复制原文就够了。

查看 90 秒图文演示

记住四条文件规则就够了。

  1. 系列文件夹用数字编号。 例如 01-认识材料、02-如何选择，让预期顺序在程序和系统文件夹里都看得见。正文标题可以正常写。
  2. 原文和译文同目录、同名配对。 article.md + article.zh.md。没有译文也可以读；notes.md / notes.zh.md 这样的同名组合也适用。
  3. 图片用相对路径，段落标记保持稳定。 图片可写 assets/image.svg（两种系统都用正斜杠）。对应内容使用相同且唯一的标记，例如 <!-- block:intro -->；修改时保留已有标记名。
  4. 移动和备份时，保留整个文件夹。 包括隐藏的 .review 和 .mdduck 数据。整理优先用程序里的移动或归档；不要让 AI 改写这些管理目录。未保存的批注草稿和程序设置仍留在当前电脑。

几篇草稿可以直接放在一起，有图片或译文时再给文章独立目录。阅读时调好字号，只打开当前需要的侧面板；窗口较窄时可切成单语言阅读。

让你的 AI 也懂这套流程。

复制对应提示词，填上你的主题和要求。有文件权限的 AI 可以直接落盘；只能聊天的 AI 会按文件名输出完整 Markdown，由你保存。

创建文章或系列目录命名、双语结构、本地图片和完成检查。
根据截图或原文修改附原文或截图、文件名，再说清楚怎么改。
把确认好的文章交接发布确认目标和最终版本，保留本地原稿，发布后返回线上链接。
可选：根据多条批注集中修改需要一起改多处内容时，附上复制出的批注。

提示词可用于你自己的 AI 工作流；这个页面不会连接账号、授予文件权限，也不会发送文章。

在 Mac 上安装

MD Duck 免费提供。Mac 安装包面向 Apple Silicon（M 系列芯片），要求 macOS 13 或以上，目前在一台 macOS 27 的 Mac 上验证。安装包、版本和校验值以下载页面为准，Intel Mac 暂未提供安装包。

打开 DMG，把 MD Duck 拖到「应用程序」。复制完成后推出磁盘映像，再从「应用程序」中打开。更新测试版前，请备份整个文章库，包括隐藏的 .review/ 和 .mdduck/ 目录。

首次打开被 macOS 拦截？

测试版未使用 Apple Developer ID 签名，也未经过苹果公证。确认文件来自本项目发布入口且未被改动后，可按照苹果官方说明允许这一个程序：

  1. 先尝试打开 MD Duck，再进入「系统设置 → 隐私与安全性」。
  2. 找到与 MD Duck 对应的提示，点击「仍要打开」。
  3. 再次确认时点击「打开」，按系统提示完成认证。

如果没有「仍要打开」，或提示程序损坏、将损坏电脑，先停止安装，重新下载并核对发布校验值，再反馈具体提示。受单位管理的 Mac 可能需要管理员处理。

在 Windows 上安装

选择 Windows x64 安装包，适用于 Windows 10 或以上的 64 位 Intel / AMD 电脑。运行下载的 EXE，按向导选择安装位置，安装后从开始菜单打开 MD Duck。采用每用户安装，通常不需要管理员权限。Windows ARM 暂未提供安装包。

测试版未进行 Windows 发布者签名，系统可能显示来源提示。先确认文件来自本项目下载页，再核对 SHA-256；无需关闭系统防护。PowerShell 中可使用 Get-FileHash -Algorithm SHA256 "文件完整路径" 核对文件，Mac 可使用 shasum -a 256 "文件完整路径"。

本地朗读还需要 Microsoft Visual C++ v14 x64 运行库。如未安装，或点击朗读后无法启动，可按微软官方说明安装 x64 运行库，不需要购买 Visual Studio。运行库安装可能需要管理员权限；普通阅读和批注不需要这一步。

Windows 已通过自动化测试、安装、启动恢复、安装后的改动审阅及五声音离线合成检查；手动桌面操作和扬声器播放尚未验收。更新前备份整个文章库，包括隐藏的 .review/ 和 .mdduck/ 目录；将新版安装到原位置即可，文章继续保存在你选择的文件夹中。

打开一篇文章

在 MD Duck 中选择「打开文件夹」或「打开文件」，也可以把 Markdown 文件拖进窗口。打开文件夹后，从左侧目录选择文章；原文和关联的中文译文作为同一篇文章打开。

第一次用，可以先点「打开示例」，或下载双语示例文章，解压后打开 article.md。

想修改正文时，继续使用自己的 AI 或编辑器。保存文件后，MD Duck 会更新阅读界面。「阅读排版」可以调整字号；界面语言在设置中切换。

让 AI 写，你来读，再把这一段改好

MD Duck 负责把本地文章清楚地呈现出来。写作和修改仍在你熟悉的 AI 或编辑器中完成；发布交给你自己的后台工具。

  1. 把初稿放到本地。 给 AI 文件存放规则和写作提示词，指定文章库。如果它没有电脑文件权限，让它输出文件名与完整 Markdown，由你保存。
  2. 打开文章，认真读。 在 MD Duck 中检查逻辑、措辞、图片和需要的中文对照，不必先写批注。
  3. 把问题直接交回去。 复制不满意的段落，或截取这一段，粘贴到 AI 对话框。附上文章位置和具体要求，例如「这段只说适量和等待片刻，请补充用量和判断方法，其他内容不动」。仅有截图时，AI 还需要能读取最新文件，或由你提供原文。
  4. 保存后，回来看。 让 AI 改原文件，或把完整改稿保存回本地。用侧栏「有改动」找到改过的文章，点「查看改动」对照复核，读完再「标为已查看」。双语稿可再点「检查整篇」。多处意见需要留待以后处理时，再用批注。
  5. 定稿后，再发布。 用发布交接提示词把定稿交给有后台权限的 AI，先检查发布预览、确认后再上线；也可以自己发布。核对公开页面，本地保留定稿、译文和素材。

Mac 复制文字用 ⌘ C，Windows 用 Ctrl C。Mac 用 ⇧ ⌘ 4 截取区域，图片默认保存为文件，可拖入对话框；截图时按住 Control 可复制到剪贴板。Windows 用 Win Shift S 截图后粘贴。所用 AI 不支持图片时，复制原文即可。

这个流程不需要给 MD Duck 配置 AI 密钥。MD Duck 不编辑文章正文，也不连接后台或代你发布；截图和摘录由你自行交给外部 AI。想保留初稿和每轮改稿，可在修改前另存副本或使用版本管理。

AI 改完了，找到那一篇再复核

文章保存到磁盘，和你已经读过新内容，是两件事。MD Duck 会将当前原文、译文分别与上次确认的版本比较；内容没有变化的重复保存不会提醒。

  1. 找到文章。 侧栏会标出「更新」，文件夹旁显示待查看数量。点「有改动」只看当前「全部」或「已归档」范围里尚未确认的文章，搜索和原有排序继续有效。
  2. 查看改动。 打开文章后，顶部提示原文、译文或两者有改动。点「查看改动」看段落前后对照，用上一处、下一处检查，或定位到正文；删掉的文字也会保留在对照里。
  3. 明确确认。 读过这次修改后，点「标为已查看」清除提示。仅打开、切换或关闭文章不会清除提示，也不会把文章进度自动改成「已定稿」。

首次检查只建立起点。 升级后第一次读到文章时，会以当时的内容建立本地快照，不会把所有旧文章都标成更新，也无法追溯安装前的改稿。之后即使 AI 在 MD Duck 关闭时修改，重新打开文章库仍可发现变化。

只在本地保留上次确认的版本，用于下一轮复核，并非完整版本历史。要长期留存每一稿，请另存副本或使用版本管理。移动、归档和恢复仍沿用原来的文件夹操作；整理、备份时一起保留隐藏的 .mdduck/ 与 .review/ 目录。

用本地文件夹管理系列和归档

左侧目录对应磁盘上的真实文件夹。在 Finder 或 Windows 文件资源管理器中新增、修改、移动或改名，MD Duck 会更新；程序内的整理操作也直接作用于本地文件，不需要再维护一套分类。

几篇直接放，文章多了按系列

MD Duck 沿用你本地的目录，不会自动分类。临时看一篇，直接「打开文件」；几篇零散的 ideas.md、notes.md 可以共用一个文件夹。一次写十几篇时，再建系列子目录，用 01-、02- 表示阅读顺序。

有图片或译文时，推荐每篇一个文件夹：article.md、可选的 article.zh.md 与 assets/ 放在一起，方便移动和留存。没有译文就正常读单语，不必补空文件。只改一段时，截图或复制那段交给 AI，保存原文件后继续读。完成的文章或系列可以归档，需要时再恢复。

一次建立一个系列

  1. 打开文章库，点搜索旁的「＋」或文件夹的「…」，选择「新建文件夹」，以系列命名。
  2. 在系列文件夹中选择「批量新建文章」，每行粘贴一个标题，一次最多 50 篇。
  3. 每篇草稿会建立独立文件夹，内含带标题的 article.md。正文继续用自己的编辑器或 AI 修改，译文和图片可放在同一个文章文件夹中。

例如：

文章库/
  01-家庭咖啡指南/
    01-第一次冲煮/
      article.md
      article.zh.md
      assets/
    02-找到合适的风味/
      article.md

已有文件不用转换成这个结构。用搜索查找标题或路径，在文章的「…」中「标记进度」为写作中、待审阅、已定稿。顺序和进度随文章库保存，不修改正文。

排序入口： 侧栏可选择名称升序、名称降序、文章标题或手动顺序。默认按文件夹／文件的名称自然排序，2 会排在 10 前；独立文章文件夹按文件夹名排序，不会因为里面都叫 article.md 而混在一起。若希望手动安排篇目，切换到手动顺序后再用文章菜单的「上移／下移」。选择会在本机保存，筛选「有改动」时仍按你选择的顺序显示。

移动、重命名与归档

文章或文件夹的「…」提供「重命名」「移动到…」「归档」。单篇独立文件夹会整体整理，保留原文、译文、图片、批注和单词记录；本机批注草稿和阅读位置随路径更新。目标已有同名项目时停止操作，不覆盖已有文件。若文章引用了所属目录之外的共享图片或相对链接，按提示移动包含素材的完整上级目录。

归档会把文件实际移入文章库的 Archive/，可从「已归档」打开并选择「恢复归档」，回到原位置；若原位置已不存在或被占用，先按提示处理，或用「移动到…」选择新位置。归档不删除正文和批注。

外部移动或改名能可靠确认原文章时，关联记录会继续跟随。无法确认、文件暂时不可用或记录冲突时，程序会保留记录并提示检查，不会猜测合并。跨文章库搬迁或备份时，请一起保留原稿、译文、素材及隐藏的 .review/、.mdduck/；批注草稿仍保存在当前电脑上。生成译文期间，等完成或取消后再整理文件。

把原文和译文放在一起

顶栏的「英文」「中文」「对照」切换阅读方式。已有中文稿时，把两份文件放在同一目录，并使用对应的文件名：

notes.md          原文
notes.zh.md       中文译文

.markdown 文件也适用：notes.markdown 对应 notes.zh.markdown。译文用了其他名字，可以在缺译文提示中点「选择已有译文」，关联当前文件夹内的文件。

还没有译文？

连接自己的 AI 服务后，没有中文稿的文章会提供「生成中文译文」。

  1. 点击生成入口，确认服务和模型，再点「开始翻译」。正文会分段发送到所选服务，使用你的账户额度。
  2. 需要中断时点「停止」。已完成部分保存在本机，下次打开可以继续。
  3. 完成后点「打开对照」。译文另存为中文 Markdown 文件，原文保留，已有译文不会被覆盖。

没有配置 AI 也能正常阅读。需要对照时，点击「中文」或「对照」，再选择已有译文或连接服务即可。

让两份稿子逐段对应

AI 生成的译文会自动保存对应关系。自己准备的译文，可以在对应段落前加上相同的标记：

<!-- block:morning -->
On Saturday, I leave my phone at home.
<!-- block:morning -->
星期六，我把手机留在家里。

每组段落使用不同的标记名。设置中的「复制约定」可以把这份规则交给整理文章的人或 AI。没有可用的匹配标记、也没有有效翻译记录时，两份稿子仍可并排阅读，但不会精确逐段对齐。

检查整篇的段落配对

对照阅读中的配对提示会说明当前使用了哪些对应关系，以及是否存在未配对的内容。点击「检查整篇」，查看整篇的已配对、未配对数量和问题列表，不会因为只检查开头几段而漏掉后面的结构问题。

检查会提示重复、没有对应正文或另一侧缺失的标记，遗漏标记的内容、标记顺序和段落结构差异，以及已过期或无效的翻译记录。点击问题中的原文或中文行号，回到对应一侧并高亮附近的正文；标记本身不会显示在阅读正文中，可根据行号到自己的编辑器修改。

检查只读取文件，保留当前阅读方式，不会自动配对、补标记或重写原文与译文。修改并保存后，再次检查即可。结构对应不代表译文准确，句子的意思仍需要你结合原文判断。

想集中记录时，留一条批注

截图或复制一段就能交给 AI 修改。想读完整篇再改，或保留多轮意见时，可以用批注：选中一句话，点「批注」（Mac 为 Option + Enter，Windows 为 Alt + Enter），写下意见并保存。打开顶栏的「批注」，可以集中查看这篇文章的意见。

  • 点击引用，回到对应的英文或中文原文。
  • 点击铅笔，继续修改意见。未保存的内容会保留为本机草稿。
  • 复制一条或全部未完成意见，交给编辑器或 AI 处理。
  • 正文修改后，检查标为「待复核」的批注，确认问题已经解决。

批注单独保存在文章旁，不会写进正文。草稿可以从批注面板继续；如果本机草稿存储不可用，关闭程序时会提示返回保存，或明确放弃未保存草稿。

MD Duck 正文旁的批注面板，保留引用和对应的修改意见。
引用和意见一起保存。点击批注，就能回到原文。

读到生词，就地弄懂

点击正文里的英文单词，查看可用音标和读法提示。词卡中的「读这个词」「慢读」「读这一句」可以帮助你听清发音；首次朗读需先准备语音模型。

连接 AI 后，词卡会解释这个词在当前句子里的意思。想再多了解一点，点「详细讲解」，查看用法、例句、搭配和助记提示。成功获取的语境释义会随原句保存到本文的单词列表。

也可以选中词句，再点「翻译」理解整段意思。AI 的解释和译文可能有误，遇到关键含义时请结合原文核对。

听一遍，再读一遍

将鼠标移到段落旁，点击朗读按钮；也可以从词卡朗读单词或原句。在设置中选择声音和语速，按 Esc 停止。

朗读使用本机运行的 Kokoro 模型，提供五种英美声音。首次请求朗读时需要联网下载约 92 MB 模型，已有有效模型缓存会直接复用；打开程序不会触发下载。模型就绪后，语音在电脑上合成。英美音标供你参考，实际声音取决于设置中选择的语音。

连接你自己的 AI 服务

MD Duck 本身免费，阅读、批注和已准备好的本地朗读不需要 AI 密钥。想使用语境解释、词句翻译或整篇译文时，打开「设置 → AI 服务」，选择一种连接方式；服务商的 API 费用由你自己的账户承担。

OpenRouter：在浏览器中连接

点击「在浏览器中连接 OpenRouter」，在服务商页面登录并授权，然后回到 MD Duck。程序会自动测试连接。也可以从 OpenRouter 密钥页面创建密钥，直接粘贴到程序中。

DeepSeek：粘贴 API 密钥

在 DeepSeek 开放平台创建密钥并确认有可用 API 额度。在 MD Duck 中选择 DeepSeek，粘贴密钥，先点「保存配置」，再点「测试连接」。接口地址和默认模型已预填。

其他服务：填写兼容接口

选择「自定义服务（兼容 OpenAI）」，粘贴密钥。在「高级设置」填写接口基础地址和模型名称，先保存配置，再测试连接。接口需要支持 OpenAI Chat Completions；地址不包含 /chat/completions。

看到「连接可用」后，再开始使用。 每个服务分别保存配置；切换服务后需要保存。密钥框留空会保留已有密钥，移除时使用「清除此服务密钥」。

调用使用你自己的服务账户额度，连接测试也可能产生少量费用。网页聊天会员不一定包含 API 额度。遇到错误时，按提示检查密钥、账户额度、模型或网络，再重新测试。

文件留在哪里，哪些功能会联网？

文章由你保存在本机。MD Duck 从真实文件夹读取内容，批注、词义和翻译进度保存在文章旁的 .review/，文章库顺序、进度和路径关联保存在库内的 .mdduck/；应用设置和批注草稿保存在本机。文件夹管理与归档不需要联网。

你使用的功能 发生的网络请求
阅读、批注 不要求上传文章。正文包含远程图片时，会访问图片地址。
查看音标 优先查本地词表；没有收录时，把单词发送给 Free Dictionary API。
AI 解释和词句翻译 把选中的词句及必要上下文发送到你选择的服务。
生成整篇译文 确认开始后，正文分段发送到所选 AI 服务。
英文朗读 首次下载模型，之后在本机合成语音。
连接 AI 服务 测试发送简短文本；浏览器授权打开服务商页面，通过本机回调完成连接。

API 密钥通过系统安全存储加密后保存在本机，不会在界面回显；无法安全保存时会提示。清除程序内的密钥只移除本机副本，如需撤销密钥，请到对应服务平台操作。

本站没有登录、表单或访问统计脚本。服务器访问日志取决于实际部署配置。

遇到问题时

没有显示中文对照？

先检查原文和译文的文件名，例如 notes.md 与 notes.zh.md。也可以点「选择已有译文」手动关联。已有两份文件却没有逐段对应时，使用整篇配对检查，按问题行号检查标记和结构；仍可保留并排阅读。

能看音标，却没有词义解释？

音标可来自本地词表。当前句子的 AI 解释需要可用的服务连接；在设置中先「保存配置」，再「测试连接」，按提示排查后再试。

翻译中断，需要从头开始吗？

原文、服务地址和模型未变化时，可以继续已保存的进度。原文或配置变化后会重新翻译，避免混入旧结果。已有译文文件不会被覆盖。

朗读一直在准备？

首次使用需要下载并加载模型，时间取决于网络和电脑性能。等待期间仍可阅读和写批注。

移动文章，怎样带走批注？

在程序的「…」中使用「移动到…」「重命名」或「归档」，关联的译文、批注、素材、草稿和阅读位置会随文章整理。外部整理时尽量移动完整文章文件夹，并保留隐藏的 .review/ 与 .mdduck/。无法确认关联时程序会保留记录并提示检查；不要删除旧记录或手动覆盖。详见文件夹与归档。

批注保存失败？

检查文件夹写入权限、原文件位置，保留草稿后重试。也可以先复制意见；不要在保存失败时丢弃草稿。

现在能下载吗？支持哪些系统？

提供苹果芯片 Mac 和 Windows x64 的免费测试版，公开文件及发布状态以下载与版本页面为准。Intel Mac、Windows ARM 和 Linux 暂未提供安装包。首次安装可先看 Mac 安装步骤或 Windows 安装步骤。

从演示文件开始：读一段，提一个具体修改要求，再回来复核。

下载流程演示文件