brief-outline-generator

简要大纲生成器

生成格式化的 .docx 文件，内容为一份大纲。输出是骨架——包括章节标题、简短的主题提示，以及各章节的切入角度，供写作者填入自己的结论、数据和正文。

这是大纲生成器，不是简报生成器。 如果输出读起来像用笔记形式写成的文章，那就写过头了。生成前请阅读 references/section-rules.md。

始终通过运行 scripts/generate-brief.py 生成 DOCX。不要重新实现渲染器，也不要编写内联 docx 代码。请组装配置 JSON 并运行脚本。

---

输入——继续操作前向用户收集

字段	必填	备注
title	✅	博客文章标题。超过 70 个字符时发出警告。
focus_keyword	✅	主要关键词
sitemap_url	✅	完整的网站地图 URL，例如 https://firefly.ai/sitemap.xml。系统会据此自动推导 domain_url。
word_count_range	✅	例如 1500-2000
target_intent	✅	Informational、Commercial、Transactional 或 Navigational
target_product	⬜	产品名称——如果提供，则添加产品集成章节
secondary_keywords	⬜	预先提供的列表；如果已提供，则跳过生成

---

执行工作流——按顺序遵循以下步骤

第 1 步——验证输入

• title：不能为空；超过 70 个字符时发出警告（但不阻止操作）
• focus_keyword：不能为空
• sitemap_url：不能为空，且必须以 http:// 或 https:// 开头（接受任意路径——.xml、.xml.gz 或无扩展名的动态 URL 均有效）
• word_count_range：两个以 - 分隔的正整数（例如 1500-2000）
• target_intent：必须是 Informational、Commercial、Transactional 或 Navigational 之一（不区分大小写）

根据 sitemap_url 推导两个值：

• domain_url——去掉路径，得到源站，例如 https://firefly.ai/sitemap.xml → https://firefly.ai。用于配置 JSON。
• domain_hostname——再去掉协议，例如 https://firefly.ai → firefly.ai。用于需要纯主机名的工具调用（例如 site:firefly.ai）。

继续操作前，先停止并报告所有验证错误。

---

第 2 步——阅读规则

现在完整阅读 references/section-rules.md。 其中包含：

• 大纲与简报的区别（最重要的规则）
• 要点的硬性规则（≤ 12 个词，不得虚构数字，不得给出结论，不得使用破折号从句）
• 结构的硬性规则（不允许使用 topic_summary，不允许添加 Writer Directives 框，TLDR 中包含 2–3 个主题提示）
• 四种文章类型（Listicle、Comparison、How-to、Concept/Explainer）及各自的章节集合
• 各章节规则，以及正反要点示例
• 生成 DOCX 前要执行的最终质量检查

不要跳过此步骤。 不阅读规则就生成，每次都会产出简报风格的内容。

---

第 3 步——领域分析

DataForSEO 工具延后加载——调用前先加载。 在此步骤开始时调用 tool_search(query="on_page content parsing")。

3a——发现网站 URL

对 sitemap_url 调用 web_fetch。

• 可读 XML（响应中包含 <loc> 标签）→ 提取所有 <loc> URL。这些就是网站 URL。
• 二进制／压缩内容（响应不可读）→ 备用方案：调用 dataforseo:serp_organic_live_advanced，并传入 keyword="site:{domain_hostname}"（例如 site:firefly.ai），获取所有已编入索引的 URL。

最多保留 20 个 URL。如果超过 20 个，按以下优先级筛选：首页 → 产品／用例页面 → 博客／资源页面。

3b——读取完整页面内容

对 3a 中的每个 URL，调用 dataforseo:on_page_content_parsing，并设置 enable_javascript: true。

此调用会返回完整渲染的页面文本——包括标题、正文、产品说明等。收集所有输出。

如果某个页面读取失败（机器人防护、超时），则跳过并继续处理，不要中止。

3c — 提取元标题和描述

从 3b 中解析的首页内容提取：

• 页面 <title> → meta_title
• <meta name="description"> 的内容 → meta_description

如果字符数超出建议范围，则显示提示：

• meta_title 少于 50 个字符或多于 60 个字符 → "注意：获取的元标题为 N 个字符（建议：50–60 个）。"
• meta_description 少于 150 个字符或多于 160 个字符 → "注意：获取的元描述为 N 个字符（建议：150–160 个）。"

这些内容会作为 meta_title 和 meta_description 传入配置，并呈现在元数据表格中。

3d — 编译 domain_context

从所有解析的页面内容中提取并存储：

• 产品名称和核心价值主张
• 网站使用的关键技术术语和词汇
• 目标受众信号（提及的角色、团队类型和用例）
• 现有内容主题 — 用于避免大纲中的内容重复

存储为 domain_context。不要在输出文档中呈现 domain_context。 如果所有抓取均失败，则将 domain_context = null 并继续。

---

第 4 步 — 判定标题的类型

根据标题模式，选择以下一种：

• 列表文章 / 工具综述 — “Top N”、“Best X”、“X Alternatives”
• 对比 / 二选一 — “X vs Y”、“X or Y”
• 操作指南 / 实施指南 — “How to X”、“How do X teams Y”、“Implementing X”
• 概念 / 说明文 — “What is X”、“Designing X”、“[Function/Pattern]: Designing X”

如果看起来符合多种类型，请采用 section-rules.md 中的默认类型。如果仍不明确，请询问用户。

生成之前，先向用户说明选定的类型 — 用一行文字，例如："检测到的类型：操作指南。正在生成包含引言 → 策略 → 案例研究 → 实施 → 常见问题解答的大纲。" 如果用户有异议，可让其更改。

---

第 5 步 — 生成关键词搜索量

使用 DataForSEO 获取焦点关键词和每个次要关键词在美国的月搜索量。

DataForSEO 工具需延迟加载 — 调用前先加载。

1. 调用 tool_search(query="keyword search volume google ads")，加载 DataForSEO 关键词工具。
2. 使用完整关键词列表（焦点关键词 + 所有次要关键词）调用 dataforseo:kw_data_google_ads_search_volume，一次性提交。美国的 location_code 使用 2840。
3. 从响应中提取每个关键词的 search_volume 字段。
4. 将每个搜索量格式化为带千位分隔符的字符串（例如，3400 → "3,400"）。低于 1,000 的搜索量保持为纯数字（例如，"500"、"30"）。搜索量为 0 时应显示为 "0"，而不是 "N/A" — 这是一个真实数据点。
5. 如果关键词没有返回数据，则将其搜索量设为 "N/A" 并继续。不要中止整个流程。
6. 如果 tool_search 未返回任何 DataForSEO 工具（未安装连接器），则将所有搜索量设为 "N/A"，并显示一行警告："DataForSEO 连接器不可用 — 关键词搜索量已设为 N/A。"

不得省略任何关键词的搜索量字段。 每一行都必须包含一个搜索量。

标记搜索量差异。 如果焦点关键词的搜索量比任何次要关键词小 10 倍以上，请在生成前告知用户："注意：焦点关键词的搜索量为 X，但次要关键词 Y 的搜索量为 Z。请考虑是否应将 Y 设为焦点关键词。" 由用户决定；不要自动调换。

存储为：

"focus_keyword_volume": "2,400",
"secondary_keywords": [
  { "keyword": "disaster recovery plan", "volume": "1,900" },
  { "keyword": "cloud DR strategy",      "volume": "N/A"   }
]

如果未提供次要关键词，则通过组合焦点关键词中的基础词、领域中的主要关键词以及修饰语（"best practices"、"guide"、"checklist"、"for teams"、当前年份）生成 5 个次要关键词。然后以相同方式获取它们的搜索量。

---

第 6 步 — 使用该类型的章节集合构建大纲

使用第 4 步中为所选类型确定的章节集合。不要强行将每个主题都套进操作指南模板。 列表式文章没有问题或案例研究章节。对比文章没有实施步骤。

每个章节对象的结构：

{
  "heading": "H2",
  "title": "Section Title",
  "rules": ["short topic prompt 1", "short topic prompt 2"],
  "subsections": [
    {
      "heading": "H3",
      "title": "Subsection Title",
      "rules": ["..."],
      "subsections": []
    }
  ]
}

从先前架构中移除的字段（请勿使用）：

• topic_summary — 已移除。大纲不含摘要。
• directives — 已移除。要点本身会说明方向。
• visual — 已移除。如果视觉元素很重要，请将其写成要点提示：“加入对比表：维度 × 工具”。
• faqs — 已移除。FAQ 只包含问题（放在 rules 中）；答案由作者撰写。

rules 中的要点须遵循 section-rules.md 的硬性规则：

• 每条不超过 12 个词
• 必须具体且意思完整
• 不得编造数字
• 不得给出结论——只能提供主题提示
• 不得使用破折号引出的解释性从句

长度应取决于内容，而不是固定上限。 每个章节需要多少条要点就写多少条——需要 2 条就写 2 条，需要 9 条就写 9 条。section-rules.md 中的“典型范围”仅供参考，不是限制。为了达到目标数量而凑数是错误的；为了达到目标数量而删减同样错误。

TLDR 章节： 加入一个 TLDR 标题，并提供 2–3 条简短的主题提示（每条不超过 12 个词），说明作者在 TLDR 中应涵盖什么。提示应是主题，而不是已经写好的结论。内容应取自文章的核心矛盾、读者应做出的主要转变，以及实际的下一步。请参阅 references/section-rules.md 中的 TLDR 章节，了解正反示例。

FAQ 章节： 在 rules 字段中使用问题字符串列表——只写问题，不写答案。实际答案由作者撰写。每个问题单独作为一条要点。重点关注问题的表述方式：具体且以行动为导向（“如何安装 Claude skill？”），而非抽象（“Claude 如何决定调用哪个 skill？”）。所有用户提供的关键词（核心词和每个次要关键词）都必须自然地出现在问题列表中——改写成真实搜索者会输入的表达，切勿堆砌关键词。通常为 5–8 个问题，但没有固定上限。请参阅 section-rules.md 中的 FAQ 章节，了解示例。

---

第 7 步 — 执行最终质量检查

整理配置前，检查大纲并确认以下各项（内容摘自 section-rules.md）：

1. 作者只需添加过渡词就能发布这篇文章吗？→ 如果可以，请删减内容。
2. 每条要点读起来是否都是主题提示，而非句子？（FAQ 问题除外，它们自然是完整句子。）→ 如果不是，请重写。
3. 作者是否可能以 3 种不同方式猜测每条要点的含义？→ 如果可能，这条要点就太抽象了。请指出具体对象（文件、组件、技术术语）。
4. 每条要点大声读出来时是否都意思完整？→ 如果某条是没有意义的句子片段（“适用对象：正在做 X 的构建者”），请补全意思。
5. 每项技术声明是否准确？→ Skills 是软件包，不是文件夹；Claude 会读取 SKILL.md，而不是一开始就主动读取整个 skill。如不确定，请改写以避免作出此类声明。
6. 是否有编造的数字？→ 请删除。
7. 是否有看起来本身就像一个 H2 的子要点？→ 请将其提升为 H2。
8. H2 标题是否针对文章主题，而非泛泛的动词短语？→ 将“明确限定任务范围”改为“明确说明 skill 应完成什么”。
9. 章节顺序是否符合文章类型？→ 请核实。
10. 是否未包含 topic_summary、directives 或 faqs 字段？→ 如果包含，请删除。FAQ 问题应以独立要点的形式放在 rules 中。
11. 用户提供的所有关键词（核心词和每个次要关键词）是否都自然地出现在 FAQ 问题中？→ 如果有遗漏，请重写一个问题，将其纳入。
12. FAQ 问题是否具体且以行动为导向（“如何安装……”“……之间有什么区别？”），而非抽象的（“Claude 如何决定……”）？→ 请重写含糊的问题。

以上 12 项全部通过后，即可继续。

---

步骤 8 — 组装配置 JSON

将完整配置写入 /home/claude/brief-config.json：

{
  "title": "...",
  "focus_keyword": "...",
  "focus_keyword_volume": "N/A",
  "domain_url": "...",
  "word_count_range": "...",
  "target_intent": "...",
  "target_product": "...",
  "archetype": "how_to",
  "meta_title": "...",
  "meta_description": "...",
  "secondary_keywords": [
    { "keyword": "...", "volume": "N/A" }
  ],
  "output_path": "/mnt/user-data/outputs/outline-{file_slug}.docx",
  "outline": [ ... ]
}

Slug 说明： 内部会生成两个 slug：

• URL Slug（显示在元数据表中）——根据 focus_keyword 生成，例如 "cloud disaster recovery" → cloud-disaster-recovery。
• 文件 slug（用于文件名）——根据 title 生成，例如 "How Do Platform Teams Implement Cloud Disaster Recovery" → outline-how-do-platform-teams-implement-cloud-disaster-recovery.docx。

配置中的 output_path 应反映基于标题生成的文件 slug。

请勿在配置中包含 domain_context。 它用于上游生成过程，不会出现在渲染后的文档中。

---

步骤 9 — 运行生成器脚本

python /path/to/skill/scripts/generate-brief.py --config /home/claude/brief-config.json

脚本会处理所有 DOCX 渲染工作。请勿自行编写任何 docx 代码。

如果脚本以非零状态退出，请报告 stdout/stderr 中的错误，并以纯文本形式展示大纲作为备用方案。

---

步骤 10 — 提供文件

使用输出路径调用 present_files。报告：

✅ Outline generated: outline-{file_slug}.docx
   Archetype:     {archetype}
   Slug (URL):    {url_slug}  (from focus keyword)
   Slug (file):   {file_slug}  (from title)
   Audience:      {audience}
   Focus KW:      {focus_keyword} ({volume})
   Secondary KWs: {kw} ({vol}), ...
   Sections:      {N} sections

---

脚本渲染的内容（仅供参考 — 请勿重新实现）

脚本会生成一个 .docx 文件，其中包含：

1. 元数据 + 关键词表 — 3 列：Field | Value | USA Search Volume。标准行（Title、URL Slug、Word Count、Target Intent、Target Audience、Meta Title (50-60 chars)、Meta Description (150-160 chars)）跨越第 2 列和第 3 列。**URL Slug 根据 focus_keyword 而非标题生成。**焦点关键词和每个次要关键词各占一行，第 3 列显示搜索量（琥珀色背景）。表格中不包含 Domain 和 Domain Context 行。
2. H1 标题
3. 章节 — 每个 heading 字段都会渲染为 [H2] 或 [H3] 灰色标签前缀 + 标题文本。rules 会渲染为项目符号。没有 topic_summary 区块，也没有 Writer Directives 框——这些已从格式中移除。

---

参考文件

• references/section-rules.md — 大纲优先规则、文章类型、分章节规则、优劣示例。请在步骤 2 中、开始任何其他操作之前阅读。
• scripts/generate-brief.py — DOCX 渲染器。始终运行此脚本。切勿重新实现。
• examples/ — 规范的优质大纲，仅供参考。阅读这些内容以校准项目符号的长度、密度和语气——不要照搬章节结构、标题或主题。references/section-rules.md 中的文章类型规则决定当前主题的结构。即使主题看起来相似，也切勿将示例大纲用作用户大纲的模板。