企业官网建设流程全解析

本指南深入讲解 geo-seo-claude 仓库中geo-report-pdf技能（v2.0.0）的完整实现：如何把/geo audit生成的GEO-AUDIT-REPORT.md通过 pandoc + Chrome Headless 两条命令转换成带封面、彩色分数表、严重级别标注和 90 天路线图的客户端级 PDF。读完本文，你将掌握该流水线的每个命令行参数、模板注入机制、源码级定制入口与常见故障排查方法，可直接在你的 Claude Code 环境中复现整套交付流程。

技能定位与上游依赖

geo-report-pdf是整个 geo-seo-claude 技能包的"最后一公里"交付环节。它不负责审计，只负责渲染：将审计产出的 Markdown 报告包装成一份排版专业、可直接发给客户的 PDF 文档。其输入链路如下：

1. /geo audit <url>执行完整审计，输出GEO-AUDIT-REPORT.md（详见 命令参考 中/geo audit一节）；
2. （可选）/geo report可进一步聚合为面向企业主的GEO-CLIENT-REPORT.md，模板逻辑同样覆盖该格式（见 geo-report 技能）；
3. geo-report-pdf读取当前目录下的审计报告，执行 pandoc 与 Chrome 两条命令，产出GEO-REPORT.pdf。

技能元数据声明了其能力边界：allowed-tools: Read, Grep, Glob, Bash, Write，也就是说整个 PDF 生成过程完全由 Bash 命令驱动，不需要任何额外 Python 依赖。原文档明确强调：No Python dependencies. No ReportLab. No JSON data wrangling.这是该技能 v2.0.0 的关键设计决策——相比脚本式生成，它把排版工作交给 pandoc 模板与浏览器打印引擎。

需要说明的一个仓库内部差异：仓库 命令参考 与 技能清单 中/geo report-pdf的描述仍指向一个基于 ReportLab 的旧式generate_pdf_report.py脚本；而当前skills/geo-report-pdf/SKILL.md（v2.0.0）与仓库 templates 目录下的实际资源（geo-report-template.html、geo-report-style.css）表明，现行实现是 pandoc + Chrome Headless 流水线。本文以技能文件本身和 templates 目录中的真实模板为准。

环境依赖：两条命令，零 Python 依赖

前置条件非常轻量，只有两项：

Chrome 是唯一的浏览器打印引擎，因此技能对 Chrome 的安装位置做了硬性路径约定（见下方 Step 4 的命令）。在 Windows/Linux 环境下，需要将命令中的 Chrome 路径替换为对应平台的安装路径。

模板与样式表的部署位置由 install.sh 保证：安装脚本将仓库 templates/ 目录整体复制到~/.claude/skills/geo/templates/，并在安装验证阶段显式检查geo-report-template.html是否存在（见 install.sh 与安装校验逻辑）。因此技能文件中引用的路径~/.claude/skills/geo/templates/geo-report-template.html与geo-report-style.css在安装完成后必然存在；若 templates 缺失，安装脚本会直接警告"/geo report-pdfwill not work"。

工作原理：Markdown → HTML → PDF 的四步管线

整个技能的核心逻辑浓缩为四步，全部在当前目录完成，不产生中间态 JSON：

1. 读取当前目录下的GEO-AUDIT-REPORT.md（由/geo audit生成）；
2. 从报告头部提取封面元数据（品牌名、域名、GEO 分数、日期、经营地点等）；
3. 运行pandoc，配合仓库自带的 HTML 模板与 CSS，生成自包含的GEO-REPORT.html；
4. 运行 Chrome Headless 将 HTML 打印为GEO-REPORT.pdf。

其中第 3 步的模板（geo-report-template.html）承担了三类注入工作：

• 全出血深海军蓝封面区，右上角带圆形 GEO 分数徽章；
• 分区封面元数据（日期、业务类型、经营地点、CMS 平台），仅在元数据存在时渲染；
• 打印前在 Chrome 内执行的 JavaScript：对分数单元格按阈值着色，对发现（findings）章节按严重级别打上视觉标签。

换言之，颜色编码不是 pandoc 生成的静态样式，而是浏览器打印前由模板内嵌脚本动态计算的——这是理解"哪里改阈值"的关键（详见下文源码级剖析）。

五步工作流详解

Step 1：检查审计报告是否存在

技能的第一步是检查当前目录下是否存在GEO-AUDIT-REPORT.md。如果缺失，应向用户说明需先执行/geo audit <url>。也可以理解为：该技能不主动抓取网站，它只消费既有审计结果。

Step 2：从报告头部提取封面元数据

技能读取GEO-AUDIT-REPORT.md顶部，按标准头部格式逐字段提取。完整字段映射表如下：

这些字段随后作为--metadata键值对传给 pandoc，由模板中的$if()$...$else$...$endif$变量机制消费。字段在报告中缺失时，直接省略对应的--metadata标志即可，模板内置了安全的默认回退（例如封面标题回退为 "GEO Audit Report"，见 模板源码 的变量条件渲染逻辑）。仓库中 electron-srl.com 示例审计数据 展示了同类字段（brand_name、geo_score、scores、platforms、findings 等）在实际审计流程中的形态。

Step 3：运行 pandoc 生成 HTML

pandoc GEO-AUDIT-REPORT.md \ --to html5 \ --standalone \ --embed-resources \ --template ~/.claude/skills/geo/templates/geo-report-template.html \ --css ~/.claude/skills/geo/templates/geo-report-style.css \ --metadata title="GEO Audit Report — <brand_name>" \ --metadata brand_name="<brand_name>" \ --metadata domain="<domain>" \ --metadata geo_score="<geo_score>" \ --metadata score_label="<score_label>" \ --metadata date="<date>" \ --metadata business_type="<business_type>" \ --metadata locations="<locations>" \ --metadata platform="<platform>" \ -o GEO-REPORT.html

各标志的作用与选择理由：

注意--metadata title与--metadata brand_name是两回事：title填充 HTML<title>（同时也被模板页脚逻辑复用），brand_name决定封面标题与页脚落款。技能强调：字段未找到时省略对应 flag，让模板走默认值路径——尤其是封面元数据，绝不能填占位样例值，否则会把错误信息印上客户的报告封面。

Step 4：运行 Chrome Headless 打印 PDF

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --headless=new \ --disable-gpu \ --no-sandbox \ --print-to-pdf="$(pwd)/GEO-REPORT.pdf" \ --print-to-pdf-no-header \ --no-pdf-header-footer \ --virtual-time-budget=5000 \ "file://$(pwd)/GEO-REPORT.html"

标志逐项说明：

--virtual-time-budget是"PDF 空白"故障的关键旋钮——若 JS 尚未执行完毕就打印，动态样式不会生效。

Step 5：完成与交付

生成完成后，向用户报告：

• GEO-REPORT.pdf已生成于当前目录；
• 文件大小；
• 可选：运行open GEO-REPORT.pdf预览。

PDF 成品包含的内容

生成的 PDF 具备以下成品级特征（均来自技能文档并结合模板源码印证）：

• 封面页：深海军蓝渐变背景、品牌名、域名、按分数着色的 GEO 分数徽章、审计日期、业务类型、经营地点、CMS 平台。徽章在模板中是一个 108×108px 的圆形元素（见 样式表）；
• 分数表格：包含XX/100格式的单元格按阈值着色——≥80 绿色、≥65 蓝色、≥50 琥珀色、≥35 橙色、<35 红色。该逻辑由模板内嵌脚本scoreColor()计算（见 模板脚本），同时给所在表格行加左侧彩色边框；
• 发现章节：h3标题含 "Critical / High / Medium / Low" 关键词时，其后续段落/列表会被包裹进对应严重级别的彩色左边框提示块（红 / 橙 / 黄 / 绿），见 严重级别样式；
• 章节自动分页：High Priority、90-Day Roadmap、Component Score Summary、Generated Schema 等主要章节自动另起新页。分页由脚本维护的breakBefore关键词数组触发（见 模板脚本），配合样式表中的h2.section-break { page-break-before: always; }（样式表）实现；
• 代码块：JSON Schema 模板以深色主题等宽字体渲染（pre背景#0f172a、JetBrains Mono 字体栈）；
• 页脚：品牌名 · GEO Audit · 日期 + 页码，由 CSS@page的@bottom-center与@bottom-right区域控制（样式表）。

源码级剖析：模板注入机制的三处关键逻辑

深入 geo-report-template.html 可以看到三块决定 PDF 视觉呈现的核心代码，理解它们等于掌握全部定制入口。

1. 分数着色函数scoreColor()

function scoreColor(n) { if (n >= 80) return 'excellent'; if (n >= 65) return 'good'; if (n >= 50) return 'fair'; if (n >= 35) return 'poor'; return 'critical'; }

脚本遍历所有<td>，用正则/^(\d{1,3})\/100$/匹配纯分数单元格，为单元格与所在行同时添加score-*类。样式表为五档分别定义文字颜色与行首边框色。阈值调整只需改这个函数，颜色本身在 CSS 中定义。

2. 严重级别检测

脚本遍历所有h3，将标题小写后按关键词匹配critical、high、medium、low，命中后把该标题之后的兄弟节点（段落/列表，直到下一个标题为止）逐一套上finding-<severity>类。也就是说，报告的发现章节只要在 H3 标题中带上严重级别词，排版就会自动生成彩色提示块，无需人工干预。

3. 章节分页数组breakBefore

var breakBefore = [ 'high priority', 'medium priority', 'generated schema', '90-day roadmap', 'component score' ];

凡是 H2 标题文本包含以上任一关键词，该章节就会以新页开始。想在 PDF 中让其他章节分页，只需往这个数组追加关键词。

4. 页脚的品牌安全设计

模板头部内嵌了一段@page规则，页脚内容按footer_text→brand_name→ 中性回退 "GEO Audit" 的优先级解析，注释明确说明这是"每个报告按客户覆盖"的机制，避免跨客户串名。样式表中仅保留中性回退值content: "GEO Audit";（样式表），真正的客户名由模板按元数据注入。

定制指南：改哪里、怎么改

由于--embed-resources会把样式内嵌进最终 HTML，修改模板后重新跑 Step 3–4 即可生效，无需清缓存。注意这些文件位于安装目录（~/.claude/skills/geo/templates/），修改后不会被仓库更新覆盖，属持久化定制。

故障排查速查表

与整个技能包的协同及使用建议

• 审计先行：PDF 是审计链路的终点，务必先保证/geo audit产出标准格式的GEO-AUDIT-REPORT.md；若交付对象是业务决策者，可先跑/geo report生成面向企业主的GEO-CLIENT-REPORT.md再转 PDF。
• 报告结构约定：模板的严重级别检测与分页逻辑依赖报告遵循约定格式（H3 含严重级别词、H2 含90-day roadmap/component score等关键词），生成报告时保持这些章节命名即可自动获得全套排版。
• 适用场景：当交付物需要直接邮件发送给客户、且客户期待一份排版精美的文档而非 Markdown 文件时，使用/geo report-pdf（见 命令参考 的/geo report-pdf小节）；同时可配合/geo compare的月度增量报告，形成"审计 → 提案 → 交付 → 月度复盘"的完整服务闭环。
• 无图可选：该技能生成的 PDF 本身即最终交付物，流程中无截图或图表类中间产物，因此本指南不引入仓库 assets 中的项目宣传图，以上所有排版细节均以真实模板源码为准，可直接打开 geo-report-template.html 与 geo-report-style.css 逐一核对。