功能概览#

• 文章详情页顶部自动展示一段摘要
• 摘要以打字机动画逐字显示，标点处稍作停顿，模拟真人打字节奏
• 只在首次滚动到摘要区域时播放一次，不会重复触发
• 尊重用户系统设置：开启了「减少动态效果」的设备会直接静态显示全文
• 摘要内容优先读取你手动编写的 description 字段，没有时才由 AI 补全

摘要来源#

所有文章的摘要来源由 frontmatter 中的 descriptionSource 字段标记：

你完全可以自己写 description 并标记 descriptionSource: manual，这样就不会被 AI 覆盖。

如何手动编写摘要#

在你的文章 frontmatter 中添加 description 字段即可：

1
---
2
title: 我的文章标题
3
published: 2026-04-15
4
description: "一段自然的、像博客导语一样的摘要文字，60~120字左右。"
5
descriptionSource: manual
6
tags:
7
  - 标签
8
category: 分类
9
---

字段说明：

• description：文章的摘要内容。建议长度 60～120 字，自然、口语化，像博主在给读者做开场铺垫。
• descriptionSource：标记来源。manual 表示你自己写的，ai 表示由脚本生成的。

使用 AI 补全缺失摘要#

如果你的文章有 description 字段，脚本会直接跳过这篇文章，不会做任何改动。只有当你新增了一篇文章但没有写 description 时，补全脚本才会介入。

1
npx tsx scripts/fill-descriptions.ts

1
[09:15:32] 🚀  AI 摘要补全脚本启动
2
[09:15:32] 📡  模型: qwen-plus
3
[09:15:32] 📂  文章目录: src/content/posts
4
[09:15:32] 📊  扫描到 29 篇文章
5
[09:15:32] 📋  27 篇已有描述 -> 跳过
6
[09:15:32] 📝  2 篇缺少描述 -> 准备补全
7
[09:15:33] ⏳  正在生成: 技术分享/新文章.md
8
[09:15:34] ✅  补全完成: 技术分享/新文章.md
9
[09:15:34]    → 折腾了两天终于把Nginx反代配通了……
10
[09:15:35] 🏁  执行完毕
11
[09:15:35]    跳过（已有描述）: 27 篇
12
[09:15:35]    需要补全: 2 篇
13
[09:15:35]    ✅ 成功: 2 篇
14
[09:15:35]    ❌ 失败: 0 篇

AI 生成的摘要是「像人写的」吗？#

我们在补全脚本中内置了一套精心设计的提示词（Prompt），让千问知道：

• 不要用「本文主要讲述了」「这篇文章介绍了」这种机械开头
• 不要堆砌概念、不要写成说明书提纲
• 要自然、口语化，像一个真实的博主在给读者做开场铺垫
• 技术文章保持清晰但别冷冰冰，生活感文章语气柔和一些
• 保留原作者的情绪和语气

所以生成出来的摘要更像这样：

折腾了两天终于把Nginx反代配通了，中间踩了三个莫名其妙的坑，趁热记下来免得下次再掉进去 😤

而不是：

本文主要介绍了Nginx反向代理的配置方法，包括常见的错误排查和解决方案。

如何在构建前自动补全#

如果你希望每次 pnpm build 时自动补全新文章的摘要，可以修改 package.json 的 build 脚本：

1
{
2
  "scripts": {
3
    "build": "npx tsx scripts/fill-descriptions.ts && node scripts/generate-icons.js && astro build && pagefind --site dist"
4
  }
5
}

这样每次部署前都会自动检查并补全缺失的摘要，无需手动运行脚本。

注意事项#

1. 脚本不上传 GitHub：scripts/fill-descriptions.ts 已加入 .gitignore，因为它包含千问 API 密钥，确保不会泄露到公开仓库。
2. 只写 description 不写 content：脚本只修改 frontmatter 中的 description 和 descriptionSource，不会触碰文章正文内容。
3. 无描述不显示摘要：如果文章没有 description 且未运行过补全脚本，文章页面不会显示摘要区域，不影响正常页面渲染。
4. 千问模型选择：当前使用 qwen-plus（性价比之选），如有需要可切换为 qwen-max（质量更好）或 qwen-turbo（更快更便宜）。