Post 自动摘要功能实现指南

在 Hugo 博客中，摘要（Summary）对于列表页展示和 SEO 至关重要。传统方式需要手动在 Front Matter 中编写 description 或使用 `

` 截断，既耗时又难以保持风格统一。

本项目实现了一套全自动摘要生成方案：当你提交文章时，系统会自动调用本地部署的 LLM，根据文章内容生成一段高质量的摘要，并自动写入文件。

核心原理

  1. Git Hook 拦截: 利用 Git 的 pre-commit 钩子，在 git commit 执行前拦截操作。
  2. Python 脚本处理: 调用 Python 脚本扫描暂存区中的 Markdown 文件。
  3. LLM 生成摘要: 脚本读取文章前 1500 字，发送给本地 Ollama 服务，获取生成的摘要。
  4. 自动更新文件: 脚本将摘要写入文件的 description 字段，并重新 git add，完成无感提交。

实现步骤

1. 编写 Python 脚本 (generate_summaries.py)

在项目根目录创建 generate_summaries.py。该脚本负责核心逻辑：

  • 使用 python-frontmatter 库解析 Markdown 的 YAML 头部。
  • 使用 ollama 库与本地模型通信。
  • 定义 Prompt，要求模型生成 50-150 字的摘要。
# 核心代码片段
import frontmatter
import ollama

# 禁用代理，确保直连本地服务
os.environ['HTTP_PROXY'] = ''
os.environ['NO_PROXY'] = 'localhost,127.0.0.1'

MODEL_NAME = "minicpm-v:8b-2.6-q4_k_m"
PROMPT = "请为以下博客文章生成一段摘要（50-150字），直接输出摘要内容，不要包含前缀。\n文章内容：\n{content}"

def process_posts():
    # 扫描文章
    # 调用 ollama.chat 生成摘要
    # 更新 post['description']
    # 保存文件

2. 配置 Git Hook (.git/hooks/pre-commit)

在 .git/hooks/ 目录下创建或编辑 pre-commit 文件（需赋予执行权限 chmod +x）。

#!/bin/sh
# 获取暂存区中的 md 文件
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '^content/posts/.*\.md$')

if [ -n "$FILES" ]; then
    echo "🤖 正在使用本地 LLM 生成文章摘要..."
    # 运行 Python 脚本
    .venv/bin/python3 generate_summaries.py $FILES
    # 将修改后的文件重新加入暂存区
    git add $FILES
fi

3. 修改 Hugo 配置 (hugo.yaml)

为了让 Hugo 优先使用我们生成的 description 而不是自动截取，需要在配置文件中设置：

# 禁用自动摘要截取，长度设为 0
summaryLength: 0

4. 覆盖主题列表页模板 (layouts/_default/list.html)

PaperMod 主题默认读取 .Summary。我们需要修改列表页模板，使其优先读取 .Description。

在 layouts/_default/list.html 的摘要显示部分修改逻辑：

<div class="entry-content">
  <!-- 优先显示 LLM 生成的 description -->
  <p>{{ with .Description }}{{ . | plainify | htmlUnescape }}{{ else }}{{ .Summary | plainify | htmlUnescape }}{{ end }}</p>
</div>

5. 安装依赖

确保你的 Python 环境安装了必要的库：

pip install python-frontmatter ollama

使用效果

配置完成后，你只需要像往常一样写文章：

  1. 撰写 Markdown 内容。
  2. 执行 git add . 和 git commit -m "New post"。
  3. 终端会自动显示：🤖 正在使用本地 LLM 生成文章摘要...
  4. 提交完成后，打开文件你会发现 description 字段已经被自动填好。
  5. 首页列表页将直接展示这段由 AI 生成的优美摘要。

注意事项

  • 本地模型: 需要确保 Ollama 服务正在运行，且已拉取相应的模型。
  • 首次加载: 模型首次加载到内存可能需要 10-30 秒，后续调用会非常快。
  • 网络环境: 脚本中已配置禁用代理，确保能直连 localhost:11434。

通过这套方案，你的博客将拥有高质量、风格统一的自动摘要，极大地提升了写作效率和阅读体验。

实际生成效果