MarsDawn

给 AI 代理的 marsdawn 参考

给调用 marsdawn 命令行工具的 AI 代理与脚本参考。本页每个范例都用目前源代码构建的工具实际运行过。

要把 Markdown 文件转成 PDF，运行 marsdawn export notes.md --json，再从 stdout 读取一个 JSON 对象。Mermaid 图表与代码高亮的呈现方式和 MarsDawn app 相同。export 不需要 app，open 需要。

能做什么

不做什么

export

marsdawn export notes.md --json

在 notes.md 旁写出 notes.pdf。选项：

marsdawn export notes.md -o out.pdf --theme classic --paper letter --force --json

成功，退出代码 0：

{"diagramErrors":[],"ok":true,"output":"/path/to/out.pdf","pages":1,"paper":"letter","theme":"classic"}

open

marsdawn open notes.md --json
marsdawn open notes.md:120 --json
marsdawn open notes.md --line 120 --json
marsdawn open . --json
marsdawn open notes.md --folder . --background --json

成功，退出代码 0：

{"app":"/Applications/MarsDawn.app","ok":true,"opened":[{"line":120,"path":"/path/to/notes.md"}]}

有文件夹时（marsdawn 0.5.1 以后），退出代码 0：

{"app":"/Applications/MarsDawn.app","folder":{"path":"/path/to/project","requested":true},"ok":true,"opened":[{"path":"/path/to/project/notes.md"}]}

marsdawn 0.2.x 的 opened 是路径字符串的清单。如果需要同时处理两种格式，请先查看 marsdawn --version。

在 Claude Code 编辑时打开文件

一个需要自行启用的 Claude Code hook：Claude 写入或编辑 Markdown 文件之后，在后台用 MarsDawn 打开那个文件，每个 session 每个文件只打开一次。除非你添加它，否则不会启用，而且要一个项目一个项目地添加，因为你没要求就弹出来的窗口会打断注意力。它运行的是 shell 命令，不花模型 token。

需要 marsdawn 0.5.1 或更新版本，才有 --background，以及 MarsDawn app。

把下面的内容保存为项目里的 .claude/hooks/marsdawn-open.sh，再用 chmod +x 让它可以执行：

#!/bin/sh
# Claude Code PostToolUse hook: open a Markdown file Claude just wrote or edited in MarsDawn,
# in the background, once per file per session. Never blocks Claude: every path exits 0.
input=$(cat)
file=$(printf '%s' "$input" | /usr/bin/jq -r '.tool_input.file_path // empty' 2>/dev/null)
session=$(printf '%s' "$input" | /usr/bin/jq -r '.session_id // "unknown"' 2>/dev/null)

case "$file" in
  *.md|*.markdown) ;;
  *) exit 0 ;;
esac
[ -f "$file" ] || exit 0
# A hook runs with Claude Code's PATH, which may not include Homebrew's.
marsdawn=$(command -v marsdawn || { [ -x /opt/homebrew/bin/marsdawn ] && echo /opt/homebrew/bin/marsdawn; }) || exit 0
[ -n "$marsdawn" ] || exit 0

# One list per session, so a file opens once however often Claude edits it.
seen="${TMPDIR:-/tmp}/marsdawn-hook/$session"
mkdir -p "$(dirname "$seen")"
grep -qxF "$file" "$seen" 2>/dev/null && exit 0
echo "$file" >> "$seen"

"$marsdawn" open --background "$file" >/dev/null 2>&1 || true
exit 0

然后把 hook 加到项目的 .claude/settings.json；如果只想自己用，改加到 .claude/settings.local.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/marsdawn-open.sh" }
        ]
      }
    ]
  }
}

失败

加上 --json 时，失败会在 stdout 输出一个 JSON 对象，并以对应的代码结束：

{"error":"output_exists","message":"/path/to/notes.pdf already exists. Pass --force to replace it.","ok":false}

JSON Schema

每种 --json 结果的 JSON Schema（draft 2020-12）：

环境变量

系统需求

安装

使用 Homebrew。在 Apple 芯片的 Mac 上，会直接安装预先构建好的版本，几秒就完成，不需要 Xcode。在 Intel Mac 上则会从源代码编译 marsdawn，需要几分钟，也需要 Xcode 26 以上。

brew tap redtear1115/tap && brew install marsdawn
marsdawn --version

也可以从源代码构建。第一次构建会下载依赖项并编译，同样需要几分钟。

git clone https://github.com/redtear1115/mars-dawn-kit.git
cd mars-dawn-kit
swift build -c release --product marsdawn
.build/release/marsdawn export notes.md --json

marsdawn --version 会输出版本号，例如 0.3.0，并以代码 0 结束。

接下来