任务要求

自从用 Hugo、GitHub 和 Cloudflare 搭建起这个个人博客后，一个痛点便如影随形：更新流程实在太繁琐了。

每次写文章，我都得先打开 VS Code，在纯文本的编辑器里敲下内容。写完正文，还要手动去配置 Title、SEO 描述、标签等一系列 Front Matter 元数据。稍有疏忽，格式出错或是构建失败，原本连贯的创作思路瞬间被打断。这种机械的消耗，反而违背了我当初选择静态博客、想要“专注内容本身”的初衷。

为了解决这个问题，我决定向 AI 求助。我把需求原封不动地抛给了千问：

“我用 Hugo 技术，在 GitHub、Cloudflare 上搭建了一个个人博客，平时都用 VS Code 进行更新。你能帮我做一个本地运行的小程序或脚本吗？实现以下功能：当我输入文章内容后，程序能自动帮我完成排版、校对、提取摘要与描述、生成标签，甚至自动生成封面图片。”

同时，我也在心里确立了一个明确的技术目标：利用 Hugo 的原生能力处理基础排版，通过本地调用大模型来实现智能分析，最终自动化生成所有元数据与封面图。

拿到千问给出的详细架构方案后，我又把它喂给了 OpenCode。接下来的过程，就是无尽的“测试、修改、再测试、再修改”。整整一天的时间，我就在这枯燥的代码调试中度过。

直到夜幕降临，看着这个终于达到预期、能够完美运行的自动化系统，我却突然陷入了深深的沉思。脑海中不由自主地浮现出那个经典的哲学终极命题：我是谁？我在哪？我要干什么？

回想最初，我图简单省事、追求纯粹高效，毅然放弃了臃肿的 WordPress，选择了极简的 Hugo。结果现在，为了让它用起来不那么费劲，我又硬生生花了一整天的时间，给它手搓了一个“智能后台”。

这究竟是一场弄巧成拙的悲剧，还是一个程序员永远无法逃脱的宿命循环？

罢了，工具终究只是工具。折腾完这一切，是时候放下代码，好好写点东西了。

一、功能实现框架

1. 核心组件设计

  • 本地 CLI 工具：用 Python/Node.js 编写，处理 Markdown 文件的解析、AI 请求封装、Hugo 资源生成。
  • VSCode 集成：通过任务配置或扩展实现一键触发，无需离开编辑器。
  • AI 功能边界：
    • 敏感数据不外传：仅将脱敏后的内容（如摘要、关键词）发送至大模型 API。
    • 支持离线模式：校对/摘要等基础功能可用本地模型（如 llama.cpp）降级处理。

2. 关键流程

  1. 用户在 VSCode 中编辑 Markdown 文件（含 Front Matter）。
  2. 通过快捷键触发工具，自动：
    • 排版校对 → 修正 Markdown 语法与格式。
    • 提取元数据 → 生成摘要、描述、标签。
    • 生成封面图 → 基于标题/关键词调用本地图片生成工具。
  3. 更新文件 Front Matter 并保存结果。

二、具体实现步骤

1. 排版与校对自动化

(1) Markdown 规范化

  • 使用 markdownlint 自动修正格式问题（如标题层级、空行、列表缩进）： 
    npx markdownlint-cli2 "content/**/*.md" --fix
  • 校对逻辑：集成 proselint 或 language-tool 检查语法错误，无需联网。

(2) Front Matter 补全

  • 工具自动补全缺失字段（如 date、lastmod），确保 Hugo 构建一致性： 
    # 示例：Python 脚本片段（检查并补全 Front Matter）
if not front_matter.get("description"):
    front_matter["description"] = "本文由 Hugo 内容辅助工具自动生成摘要"

2. 元数据智能生成

(1) 摘要与描述提取

  • 调用本地大模型 API（如通义千问、Llama 3）：
    • 仅发送文章前 500 字至 API，避免全文外传。
    • 提示词模板： 
      请用 150 字内总结以下技术文章的核心内容，语言简洁专业，**不包含任何个人观点**：
{文章片段}
  • 结果写入 Front Matter： 
    description: "本文详解 Hugo 博客的自动化工作流，涵盖排版校对、元数据生成..."
summary: "Hugo 内容辅助工具通过本地 CLI 与 VSCode 集成，实现 Markdown 自动化处理..."

(2) 标签（Tags）生成

  • 关键词提取逻辑：
    1. 用 TF-IDF 算法筛选高频技术词（本地处理）。
    2. 调用大模型验证关键词相关性（提示词示例）： 
      从以下列表中选出 3-5 个最贴合文章主题的标签（2-5 字），优先复用已有标签：
候选词：Hugo, GitHub Pages, 静态博客, 自动化, Markdown...
文章主题：{标题}
  • 结果写入 Front Matter： 
    tags: ["Hugo", "自动化", "静态博客"]

隐私保护：所有 API 调用需通过本地代理（如 ollama），API 密钥仅存储于本地环境变量。

3. 封面图片生成

(1) 方案选择

  • 推荐本地生成：使用 Stable Diffusion + ComfyUI 本地部署，避免依赖外部服务。
  • 替代方案：调用 tcardgen 生成固定模板图片（需预置字体/背景图）。

(2) 自动化流程

  1. 从 Front Matter 提取 title 和 tags。
  2. 生成提示词（Prompt）： 
    Minimalist tech blog cover, {tags} theme, clean lines, dark background, no text
  3. 调用本地图片生成工具，输出至 static/images/covers/。
  4. 自动更新 Front Matter： 
    banner: "/images/covers/hugo-automation-20260604.webp"

三、VSCode 集成方案

1. 任务配置（无需安装扩展）

在 .vscode/tasks.json 中添加：

{
  "label": "生成 Hugo 元数据",
  "type": "shell",
  "command": "python",
  "args": [
    "${workspaceFolder}/scripts/hugo-assist.py",
    "--file", "${file}",
    "--api-key", "${input:qwenApiKey}"
  ],
  "inputs": [ {
    "id": "qwenApiKey",
    "type": "promptString",
    "description": "输入通义千问 API Key（留空跳过 AI 步骤）"
  } ]
}
  • 触发方式：右键 Markdown 文件 → 运行任务 → 选择“生成 Hugo 元数据”。

2. 关键脚本逻辑（hugo-assist.py）

def process_content(file_path, api_key=None):
    # 1. 读取 Markdown 文件并分离 Front Matter 与正文
    front_matter, content = parse_markdown(file_path)
    
    # 2. 本地校对（无需 API）
    corrected_content = markdown_lint(content)
    
    # 3. 调用 AI 生成元数据（若提供 API Key）
    if api_key:
        summary = generate_summary(content[:500], api_key)
        tags = generate_tags(front_matter["title"], api_key)
        # 更新 Front Matter
        front_matter.update({"summary": summary, "tags": tags})
    
    # 4. 生成封面图（本地 SD 或 tcardgen）
    cover_path = generate_cover(front_matter["title"], front_matter["tags"])
    front_matter["banner"] = cover_path
    
    # 5. 保存结果
    save_markdown(file_path, front_matter, corrected_content)

四、注意事项与优化建议

1. 隐私与安全

  • API 密钥本地化：通过环境变量（如 QWEN_API_KEY）传递，不在脚本中硬编码。
  • 离线降级：若 API 不可用，自动切换至本地关键词提取（TF-IDF）和默认封面模板。

2. 性能优化

  • 缓存机制：对相同内容哈希值跳过重复处理。
  • 增量处理：仅分析新修改的段落，避免每次全文重处理。

3. Hugo 兼容性

  • Front Matter 格式：严格遵循 YAML/TOML 规范，避免 Hugo 构建失败。
  • 资源路径：封面图默认存至 static/ 目录，确保 Hugo 直接引用。

五、部署与验证

  1. 初始化工具链： 
    # 安装依赖（Python 示例）
pip install python-frontmatter markdownlint-cli2
  2. 测试流程：
    • 编辑一篇草稿 Markdown 文件。
    • 在 VSCode 中触发任务，检查 Front Matter 是否自动补全。
    • 验证 static/images/covers/ 是否生成新封面图。
  3. 效果验证：
    • 摘要长度 严格控制在 150 字内。
    • 标签 复用已有词汇（避免碎片化）。
    • 封面图路径 正确写入 Front Matter。

此方案完全本地化运行，仅元数据生成环节可选联网（敏感内容可关闭），符合 Hugo 静态博客的轻量、可控特性。关键优势在于无缝嵌入现有工作流，无需改变你的 GitHub/Cloudflare 部署架构。