brain-pdf

brain-pdf — 将 Brain 页面渲染为出版级 PDF

约定： 输出规则见 conventions/quality.md。PDF 只是一种渲染结果，绝不是主要产物。如果存在 PDF，其背后必定有源 brain 页面。

核心规则

brain 页面始终是事实来源。PDF 只是它的渲染结果，绝不是独立产物。只要存在 PDF，就必须有对应的 brain 页面。

功能说明

使用 gstack make-pdf 二进制文件，将 brain 页面（带 frontmatter 的 Markdown）渲染为出版级 PDF。输出适用于以下场景：

• 通过邮件或 Telegram 分享个性化的书籍镜像
• 以干净的阅读版本交付战略阅读手册
• 生成带页眉和页码的简报或报告
• 以便携格式归档长篇文章

前置条件：gstack make-pdf

本技能依赖位于以下路径的 gstack make-pdf 二进制文件：

$HOME/.claude/skills/gstack/make-pdf/dist/pdf

用户必须同时安装 gstack。若缺少该文件，本技能无法运行。 未来的 v0.26+ 版本可能会内置备用 PDF 渲染器；对于 v0.25.1，gstack 是软性前置依赖。

调用前请先确认其存在：

P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"
[ -x "$P" ] || { echo "make-pdf not installed; install gstack" >&2; exit 1; }

工作流程

1. RESOLVE  → Confirm the brain page exists (gbrain get <slug>).
2. STRIP    → Remove YAML frontmatter — the renderer would otherwise
              dump it as a full page of raw metadata text.
3. RENDER   → Invoke make-pdf with sane defaults (no --cover, no --toc).
4. DELIVER  → Hand the PDF to the requester via the agent's preferred
              channel (do not use raw `MEDIA:` tags on Telegram —
              they fail silently).

调用方式

SLUG="path/to/page"
P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"

# 1. Confirm the page exists.
gbrain get "$SLUG" > /dev/null || { echo "Page $SLUG not found" >&2; exit 1; }

# 2. Get the raw markdown. Two paths: read from the brain repo (if user
#    syncs locally) OR ask gbrain for the body via the API.
BRAIN_DIR=$(gbrain config get sync.repo_path 2>/dev/null || echo)
if [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/$SLUG.md" ]; then
  RAW="$BRAIN_DIR/$SLUG.md"
else
  RAW=$(mktemp /tmp/brain-page-XXXXXX.md)
  gbrain get "$SLUG" > "$RAW"   # prints the page as markdown with frontmatter
fi

# 3. Strip the leading YAML frontmatter block only: line 1 '---' through
#    the next '---'. A later '---' (a horizontal rule) and a page without
#    frontmatter are kept as written. Plain awk, so it behaves the same with
#    BSD (macOS) and GNU tools. Stop if nothing is left to render.
CLEAN=$(mktemp /tmp/brain-page-clean-XXXXXX.md)
awk 'NR==1 && /^---[[:space:]]*$/ {f=1; next} f==1 && /^---[[:space:]]*$/ {f=2; next} f!=1' "$RAW" > "$CLEAN"
[ -s "$CLEAN" ] || { echo "brain-pdf: nothing to render for $SLUG after removing frontmatter" >&2; exit 1; }

# 4. Render. NO --cover, NO --toc by default — they look corporate
#    and waste space. Add them only if explicitly requested.
OUT="/tmp/$(basename "$SLUG").pdf"
CONTAINER=1 "$P" generate "$CLEAN" "$OUT"

echo "Rendered: $OUT"

在容器化环境中必须设置 CONTAINER=1，它会告诉 Playwright 跳过 Chromium 沙箱。在裸机环境中设置此项也无害。

常见模式

# Default — clean PDF, no cover, no TOC
brain-pdf <slug>

# Draft watermark for in-progress work
CONTAINER=1 "$P" generate --watermark DRAFT "$CLEAN" "$OUT"

# Optional cover + TOC if the user explicitly asks
CONTAINER=1 "$P" generate --cover --toc "$CLEAN" "$OUT"

# Custom title + author override (otherwise pulled from frontmatter)
CONTAINER=1 "$P" generate --title "Custom Title" --author "Custom Author" "$CLEAN" "$OUT"

默认设置：不含封面，不含目录

这些选项默认关闭，因为它们显得过于正式，而且对大多数个人知识内容来说会浪费篇幅。只有当用户明确要求“正式”输出时（例如要发送给董事会或作为正式交付物打印），才添加这些选项。

字体要求

渲染器需要：

• fonts-liberation（Helvetica/Arial 的替代字体）
• fonts-noto-cjk（中文、日文、韩文字符）
• 正文最小字号：10pt（页面装饰元素 9pt）
• 正文文字：11pt

如果运行环境中缺少这些字体，请通过宿主系统的包管理器安装（在 Debian/Ubuntu 容器中执行 apt install fonts-liberation fonts-noto-cjk）。

交付

渲染完成后，通过 Agent 偏好的渠道交付：

• Telegram： 使用 message 工具，附件为 filePath="/tmp/<slug>.pdf"。切勿使用原始 MEDIA: 标签，它们会静默失败。
• 邮件： 通过宿主的邮件工具添加附件。
• 直接文件响应： 输出 PDF 路径，用户可手动获取。

交付消息中始终附上 brain 页面链接，以便用户也能在 GitHub 或本地查看。PDF 只是渲染结果，源页面才是产物。

失败处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循 agent operator protocol。针对本技能的具体情况：

• gbrain get <slug> 返回 page_not_found 时：在渲染前停止，先找到真实的 slug；只有在按标题搜索后仍找不到，才报告页面缺失。
• make-pdf 二进制文件缺失：这是 gstack 的依赖问题，不是 gbrain 错误。告知用户安装 gstack；不要自行拼凑 PDF。

反模式

• ❌ 未先确认 brain 页面存在就生成 PDF。没有源文件就没有 PDF。
• ❌ 跳过 frontmatter 剥离。渲染器会把 frontmatter 以原始文本形式输出在第一页上，非常难看。
• ❌ 跳过 emoji 清理。无法映射到渲染字体的 emoji 会显示为 □ 方框。
• ❌ 默认添加 --cover 或 --toc。除非被要求，否则不要添加。
• ❌ 使用原始 MEDIA: 标签进行 Telegram 交付。应使用带 filePath 的 message 工具。

相关技能

• skills/book-mirror/SKILL.md — 生成的 brain 页面可自然地作为 brain-pdf 的输入（逐章个性化分析）。
• skills/strategic-reading/SKILL.md — 形态相同，为问题视角变体。
• skills/publish/SKILL.md — 将 brain 页面分享为带密码保护的 HTML（不同的渲染目标）。

契约

本技能保证：

• 路由与 frontmatter 中的标准触发词一致。
• 输出写入 writes_to: 中列出的目录（如适用）。
• 所引用的约定（quality.md、brain-first.md、_brain-filing-rules.md）均得到遵循。
• 隐私契约得到保持：不包含真实姓名、不包含分叉特定的文件系统路径字面量，也不包含上游分叉引用。

完整的行为契约记录在上方正文各节中；本节存在的目的是供一致性测试使用。

输出格式

本技能的输出结构在正文各节中有内联说明（参见“Output”“Brain page format”或同类章节）。此处的字面章节标题存在的目的是供一致性测试（test/skills-conformance.test.ts）使用。