迭代design doc

Author: mahaichuan-qq

.github/workflows/md-to-pdf.yml

@@ -0,0 +1,74 @@
+# 将 docs/DARE_FRAMEWORK_DESIGN.md 转为 PDF（含 Mermaid 图渲染）并上传为 Artifact
+name: Build design doc PDF
+
+on:
+  push:
+    branches: [main, master, detailed_doc]
+    paths:
+      - 'docs/DARE_FRAMEWORK_DESIGN.md'
+  workflow_dispatch:
+
+jobs:
+  md-to-pdf:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install Chromium dependencies (for mermaid-cli)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
+            libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 \
+            libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 \
+            libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 \
+            libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 \
+            libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \
+            lsb-release wget xdg-utils
+
+      - name: Install mermaid-cli (mmdc)
+        run: npm install -g @mermaid-js/mermaid-cli
+
+      - name: Setup Python and pandoc-mermaid filter
+        run: |
+          sudo apt-get install -y python3 python3-venv python3-pip
+          python3 -m venv .venv
+          .venv/bin/pip install pandoc-mermaid-filter
+          echo "$GITHUB_WORKSPACE/.venv/bin" >> $GITHUB_PATH
+          echo "PATH=$GITHUB_WORKSPACE/.venv/bin:$PATH" >> $GITHUB_ENV
+
+      - name: Install Pandoc and LaTeX (XeLaTeX + CJK)
+        run: |
+          sudo apt-get install -y \
+            pandoc \
+            texlive-xetex \
+            texlive-fonts-recommended \
+            texlive-lang-chinese \
+            fonts-noto-cjk
+
+      - name: Build PDF (with Mermaid rendered as images)
+        run: |
+          pandoc docs/DARE_FRAMEWORK_DESIGN.md \
+            -o DARE_FRAMEWORK_DESIGN.pdf \
+            --pdf-engine=xelatex \
+            -V CJKmainfont="Noto Serif CJK SC" \
+            -V geometry:margin=2.5cm \
+            -V colorlinks=true \
+            --toc \
+            --toc-depth=3 \
+            --filter pandoc-mermaid
+        env:
+          LC_ALL: en_US.UTF-8
+
+      - name: Upload PDF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: DARE_FRAMEWORK_DESIGN-pdf
+          path: DARE_FRAMEWORK_DESIGN.pdf

docs/DARE_FRAMEWORK_DESIGN.md

@@ -1249,6 +1249,7 @@ sequenceDiagram
 
 ## 附录 B：PDF 导出
 
-- Typora：打开本 MD 后导出 PDF。
-- Pandoc：`pandoc docs/DARE_FRAMEWORK_DESIGN.md -o out.pdf --pdf-engine=xelatex -V CJKmainfont=\"SimSun\"`
+- **GitHub Actions**：推送 `docs/DARE_FRAMEWORK_DESIGN.md` 到 `main`/`master`/`detailed_doc` 或在 Actions 页手动触发 workflow「Build design doc PDF」；流水线会使用 pandoc-mermaid 将 Mermaid 代码块渲染为图片后生成 PDF，完成后在对应 run 的 Artifacts 中下载 `DARE_FRAMEWORK_DESIGN-pdf`。
+- **Typora**：打开本 MD 后导出 PDF（可正确渲染 Mermaid）。
+- **Pandoc 本地**：安装 `mmdc`（mermaid-cli）与 `pandoc-mermaid-filter` 后执行 `pandoc docs/DARE_FRAMEWORK_DESIGN.md -o out.pdf --pdf-engine=xelatex -V CJKmainfont="Noto Serif CJK SC" --filter pandoc-mermaid`，可得到含 Mermaid 图的 PDF。