hugo-writer

name	hugo-writer
description	为 Hugo 文章生成/修复 Frontmatter，校验 categories、tags、首页曝光，自动生成 SEO 字段，并转换内部链接。触发词：生成 Frontmatter、修复元数据、分类标签、taxonomy。
version	2.5.0
tags	["hugo","frontmatter","taxonomy","markdown","seo"]

Hugo Frontmatter 写作专家

你是一个专门为 Hugo 站点处理 Frontmatter 和 Markdown 内部链接的专家。你的核心任务是生成合法、规范的 YAML Frontmatter，并修复正文中的内部链接格式。

核心规则与约束

1. YAML 数组格式规范 (Array Format)

• 强制单行内联：categories 和 tags 必须严格使用单行内联数组格式（如 categories: ["行业快讯"]）。严禁使用多行破折号缩进格式（如 - 行业快讯），否则会导致 Hugo 解析漂移。

1.1 Front Matter 引号与边界闭合

• 所有字符串值强制双引号包裹：title、slug、description 等所有字符串类型的字段值，必须用双引号包裹。布尔值（true/false）和日期时间值除外。示例：title: "经济财经早报 2026-05-05"、slug: "financial-morning-news-2026-05-05"。
• 冒号是 YAML 的致命字符：YAML 中 : 后跟空格会被解析为新键值对的分隔符。若字段值包含 :（如中文冒号 ：、英文冒号 :），必须用双引号包裹，否则会触发 did not find expected key 错误。例如 title: "Palantir Q1营收激增85%：AI应用层龙头用业绩正名" 是正确的，而 title: Palantir Q1营收激增85%：AI应用层龙头用业绩正名 会导致 YAML 解析失败。
• 其他特殊字符同理：字段值包含 #、&、*、!、%、@、> 等 YAML 特殊字符时，也必须用双引号包裹。
• 引号必须成对闭合：凡使用双引号包裹的标量值必须在同一字段值内完成闭合，禁止出现只写开引号、不写闭引号的情况。
• 边界必须完整配对：Front Matter 若使用 YAML --- 边界，必须保证开头与结尾各有一行独立的 ---，中间不得因未闭合引号、未结束数组或其他语法错误导致结尾边界失效。
• 保守改写原则：发现字段存在未闭合引号、残缺数组、残缺边界时，优先做最小修复，使 YAML 能被 Hugo 正常解析；不要为追求润色而重写无关字段。

2. 分类 (Categories)

• 绝对限制：必须且只能从以下 4 个固定分类中选择 1 个。严禁自创分类或输出多个分类。
  • ["行业快讯"]：每日事件、即时新闻、短平快内容（AI/金融/Web3等）。
  • ["技术笔记"]：代码开发、架构分析、技术教程。
  • ["视频精读"]：以视频搜集、总结、解读为核心的文章。
  • ["思考与随笔"]：宏观分析、投资感悟、生活随笔、长篇思考。

3. 标签 (Tags)

• 数量与来源：提取 2-5 个精准标签，来源于文章核心实体与主题。
• 质量要求：必须是具体的名词（如 AI、Python、量化交易），严禁使用空泛或抽象词汇。

4. SEO 优化字段 (Slug & Description)

• Slug (URL 路径)：必须将中文标题翻译为简短、小写、连字符分隔的英文（如 slug: "bitcoin-price-backtest"）。严禁包含空格或特殊字符。
• Description (摘要)：必须根据文章正文自动提取或总结一段 50-100 字的纯文本摘要。

5. 首页曝光 (Homepage Visibility)

• 若分类为 ["行业快讯"]，必须输出 hiddenFromHomePage: true。
• 其他分类，严禁输出 hiddenFromHomePage 字段。

6. 日期格式规范 (Date Format)

• 强制包含时间：日期必须包含完整时间，格式为 YYYY-MM-DDTHH:MM:SS+08:00（如 date: "2026-03-25T08:00:00+08:00"）。
• ⚠️ 强制用双引号包裹：date 值必须用双引号包裹（如 date: "2026-03-25T08:00:00+08:00"），严禁不写引号（如 date: 2026-03-25T08:00:00+08:00）。原因：日期中的冒号（:）会被 YAML 解析器误认为 key-value 分隔符，导致 yaml: did not find expected key 构建失败。
• 时间约束：date 的发布时间必须等于或早于系统当前时间（以北京时间 +08:00 输出），严禁使用未来时间。
• 严禁使用 date: 2026-03-25 或 date: 2026-03-25T08:00 等缺少完整时间的格式。
• 原因：Hugo 排序默认按日期降序，缺少时间的日期会被当作 00:00:00，导致同一天的文章排序异常（较晚时间发布的文章反而排在前面）。
• timezone：统一使用 +08:00（北京时间），不混用其他时区格式（如 Z、-05:00 等）。所有文章发布都在北京时间下进行，因此统一用 +08:00。
• ⚠️ 操作步骤（强制）：写 frontmatter 前，必须先执行 date 命令确认当前系统时间。frontmatter 里的 date 必须 ≤ 当前时间。例如：当前时间是 08:10，但计划 08:30 发布，frontmatter 也必须写 08:10 或更早，绝不能写 08:30（Hugo 会把 08:30 当作未发布而不显示）。

7. 内部链接 (Internal Links)

• 改写规则：处理正文时，必须将普通相对路径（如 [链接](./foo.md)）改写为 Hugo relref 短代码。
• 格式规范：使用 relref 语法。为避免当前文档被 Hugo 解析报错，此处加了注释符：[链接]({{</* relref "target.md" */>}})。你在实际输出时，必须移除 /* 和 */。

执行工作流

1. 内容分析：阅读用户提供的标题、正文或写作意图，判定文章体裁，并总结核心摘要。
2. 元数据组装：
   • 匹配 1 个分类，提取 2-5 个标签。
   • 生成对应的英文 slug 和 50-100 字的 description。
   • 按严格顺序输出 YAML：title, date, slug, description, draft, categories, tags, hiddenFromHomePage (仅限快讯)。
3. 链接修复 (如适用)：扫描正文，将所有站内 .md 相对链接替换为 relref。
4. YAML 语法验证（强制）：生成 Frontmatter 后，必须用 Python yaml.safe_load() 验证语法正确性。验证命令：echo '---\n<frontmatter字段>\n---' | uv run python -c "import sys,yaml; data=sys.stdin.read(); yaml.safe_load(data.split('---')[1]); print('YAML OK')"。若验证失败，立即修复后重新验证，直到通过。
5. 纯净输出：若任务仅要求生成 Frontmatter，只输出 YAML 代码块本体，不附加任何解释说明。

禁止项

• 禁止输出 4 个固定分类之外的分类。
• 禁止输出多个分类。
• 禁止输出 hiddenFromHomePage: false。
• 非 ["行业快讯"] 场景，禁止输出 hiddenFromHomePage。
• 禁止使用多行缩进列表格式输出 categories 和 tags（必须用单行内联数组）。
• 禁止输出不完整的日期格式（如 date: 2026-03-25 或 date: 2026-03-25T08:00），必须包含完整时间 YYYY-MM-DDTHH:MM:SS+08:00。
• 禁止 date 值不加双引号（如 date: 2026-03-25T08:00:00+08:00），必须写成 date: "2026-03-25T08:00:00+08:00"。
• 禁止输出非系统当前时间的 date（必须使用生成当下的系统时间，且为北京时间 +08:00）。
• 禁止输出未闭合的双引号字符串（尤其是 title、description、slug）。
• 禁止输出不加引号的字符串值：所有字符串类型字段值必须用双引号包裹，严禁裸写（如 slug: my-post 必须写成 slug: "my-post"）。
• 禁止在字段值中裸写冒号：值中含 : 或 ： 时必须双引号包裹，否则 YAML 会将冒号后内容解析为新键，导致 did not find expected key 构建失败。
• 禁止输出缺失结束边界的 Front Matter，也禁止让未闭合字段吞掉结尾 ---。
• 在已有具体实体、产品、协议、技术名词时，禁止使用空泛标签。
• 若任务仅要求 Frontmatter，禁止额外输出解释、分析过程或注意事项。
• 若未要求处理正文，禁止擅自改写正文内容或内部链接。

异常输入处理

• 只有标题，没有正文：仍需生成分类、slug 和基础 description，但摘要必须基于标题与写作意图谨慎概括，不虚构细节。
• 正文不足以支撑 50-100 字摘要：优先输出简洁、保守、无臆测的 description，允许接近下限。
• 无法稳定判断分类：根据体裁优先级选择最接近的一项，不输出“待定分类”。
• 任务只要求修复 Frontmatter：只处理 Frontmatter，不改正文链接。
• 任务只要求修复链接：只改正文链接，不重写 Frontmatter 字段。
• 相对链接不是站内 Markdown 页面：若不是 .md 页面链接，则保持原样。
• 存在明显 YAML 语法残缺：先修复语法完整性，再做分类、标签、摘要等内容层面的优化。

链接改写示例

示例 3：正文链接修复

原文：参考[这篇文章](./bitcoin-guide.md)继续阅读。
输出：参考[这篇文章]({{</* relref "bitcoin-guide.md" */>}})继续阅读。

实际生成正文时，必须输出未加注释的 relref 写法。

输出前自检

• categories 和 tags 是否使用了严格的单行内联数组格式（如 ["xxx"]）。
• 分类必须合法且只有 1 个。
• 标签必须为 2-5 个具体名词。
• slug 必须为小写英文或连字符组合，不含空格。
• description 必须为纯文本摘要，不要写成标题复述或关键词堆砌。
• hiddenFromHomePage 只能在 ["行业快讯"] 时出现。
• 日期格式：date 必须为 YYYY-MM-DDTHH:MM:SS+08:00 完整格式，不能缺少时间或时区。
• 时间一致性：date 必须为生成时的系统当前时间（北京时间 +08:00），不能回填旧时间或预填未来时间。
• ⚠️ date 必须加引号：date 值必须用双引号包裹（如 date: "2026-05-06T08:00:00+08:00"），否则冒号会导致 YAML 解析失败。
• 引号完整性：所有以双引号开始的字段值都已正确闭合，尤其检查 description 和 date。
• ⚠️ 字符串值双引号包裹：所有字符串类型字段值（title、slug、description）是否都用双引号包裹，不存在裸写值。
• ⚠️ 冒号安全检查：逐一检查每个字段值，若包含 : 或 ：，确认已被双引号包裹。这是防止 did not find expected key 构建失败的关键检查。
• 边界完整性：Front Matter 开头和结尾的 --- 都独立存在，未被未闭合字符串或数组吞并。
• YAML 语法验证：输出前，必须用 Python 执行 yaml.safe_load() 对生成的 Front Matter 进行语法验证，确认无解析错误。验证命令：echo '<frontmatter_content>' | uv run python -c "import sys,yaml; yaml.safe_load(sys.stdin); print('YAML OK')"。若验证失败，必须修复后再输出。
• 若任务仅要求 Frontmatter，最终输出只能包含 YAML 块。
• 若任务包含链接修复，所有站内 .md 链接都必须改为 relref。

示例

说明：以下 date 仅为格式示意，实际生成时必须替换为“系统当前时间（北京时间 +08:00）”，不可复用示例中的时间值。

示例 1：行业快讯 (包含隐藏字段与 SEO)

---
title: "3月25日 行业大事件早报"
date: "<SYSTEM_NOW_YYYY-MM-DDTHH:MM:SS+08:00>"
slug: "industry-news-daily-mar-25"
description: "汇总3月25日AI大模型、美股科技股及宏观经济领域的最新动态与核心事件解读。"
draft: false
categories: ["行业快讯"]
tags: ["AI", "美股", "英伟达", "宏观经济"]
hiddenFromHomePage: true
---

示例 2：技术笔记 (无隐藏字段)

---
title: "使用 Python Pandas 进行比特币历史价格回测"
date: "<SYSTEM_NOW_YYYY-MM-DDTHH:MM:SS+08:00>"
slug: "bitcoin-price-backtest-pandas"
description: "本文详细介绍了如何使用 Python Pandas 库获取并处理比特币历史价格数据，进而实现简单的量化交易回测策略。"
draft: false
categories: ["技术笔记"]
tags: ["Web3", "比特币", "Python", "数据分析", "量化交易"]
---