blog-topic-research

为博客生成具备真实用户需求依据的话题候选。该技能旨在对抗虚构的 SEO 想法：每个提出的话题都必须指向一个可验证的 URL，证明确实有人在询问这个问题。

research <N> topics [for cluster <C>] [--append-to <path>]

• N - 返回的话题数量（默认 50；上限 100）
• cluster - 如果博客采用聚类分类体系，可限定在用户指定的某一聚类中
• --append-to <path> - 在展示结果后，询问用户是否将已接受的话题以 JSON 格式追加到指定路径（如待办文件、CSV 等博客使用的格式）

该技能仅关注内容生成：不自行进行网页抓取。它调用代理的 WebFetch 和 WebSearch 工具获取来源，并（可选）调用 Python 相似度脚本执行重复话题检测。

合同条款

对于技能输出的每一个话题，需记录以下字段：

硬性规则

• 无 URL，无话题。 若无法提供可验证的需求信号，该话题直接剔除。禁止“看起来是个好主题”这类推理。
• 证据不可改写。 evidence 字段必须逐字复制自原始来源（PAA 问题文本、GitHub Issue 标题、Reddit 帖子标题、论坛线程标题）。
• 禁止虚构版本号、价格、统计数据。 话题标题中的所有数字必须来自源链接，否则应省略。
• 信号分值 >=3。 每个信号按强度分级计分：1（存在）、2（有互动）、3（高互动）。只要一个 3 分信号即可，三个 1 分信号也足够。
• 具体性门槛。 标题必须满足以下任一条件：≥7 个词，或包含具体限定信息（版本号、错误代码/字符串、命名集成对 X to Y、特定边缘场景）。拒绝模糊标题如“n8n 教程”或“什么是自动化”。
• 重复话题检测。 当用户提供已有标题缓存时，执行三层检查：(1) Jaccard 词元重叠 ≥0.6 = 剔除；(2) 余弦相似度 ≥0.85 = 剔除；(3) 共享独特数值/错误码 + 共享工具关键词（无论余弦得分）= 剔除。余弦 0.75-0.85 且无词元重复 = 审查（保留但标记）。若用户无缓存，仅运行 Jaccard 检查，并在摘要末尾添加一行说明。
• 内容源于事实，而非臆造。 problem_summary、confirmed_fixes[]、version_context、question_variants[] 必须基于实际抓取内容推导，绝不允许编造。若原文未提修复方案，confirmed_fixes[] 保持空；若未提及版本，version_context 为 null。作者应视其为可信框架，但仍需至少重新获取一个主源以确认时效性。
• 杜绝填充。 若无法达到 N 个有效话题，返回已有的数量，并报告缺口。

需求信号分类体系

只有当信号类型属于以下类别，且链接页面包含原文证据时，才视为有效：

强度分级标准（用于计算 signal_score）

参与度统计值在抓取时从源页面读取。将该数值记录在信号条目中，以便用户审计（例如：[strength=3, 14 reactions]）。

不计入的情况：

• 该技能自身的直觉判断。
• 无链接的“常见痛点”。
• 无具体 URL 的“我在推特上看到过”。
• 无来源的文档转述。
• 未基于真实用户需求 URL 提取的 SEO 博客内容。

需挖掘的来源

用户需提供博客覆盖的来源列表（或请求技能推荐）。按集群类型提供的通用来源模板：

开发工具 / SaaS 集群

针对博客涵盖的每个工具，进行如下挖掘：

• 官方社区论坛（筛选“问题”/“Bug 报告”类别，按回复数排序）。
• GitHub 问题列表（按反应数降序，最近 90 天内）。
• 工具相关的 Reddit 子版块（按周榜 / 月榜排序）。
• Stack Overflow 上对应工具的标签页（按浏览量排序）。
• 供应商文档网站（变更日志、最近更新的页面、“常见错误”部分若存在）。
• 供应商博客（功能发布通知——每个新功能都会催生新的问题）。

编程语言 / 框架 集群

• 对应语言 / 框架的 Stack Overflow 标签页（按浏览量排序）。
• 框架的 GitHub 问题与讨论区。
• Reddit 上的 r/<language> 和 r/<framework> 版块。
• 最近的文档更新（一周内编辑过的页面通常回应了重复出现的问题）。

垂直领域集群（如 ecommerce、customer-support、marketing-ops）

• 专注该垂直领域的 Reddit 子版块（如 r/ecommerce、r/customerservice 等）。
• 供应商模板画廊（如 n8n 的工作流画廊、Make 的场景库、Zapier 的应用目录）——每个画廊条目都是经过验证的用户需求信号，因为人们会搜索特定结果。
• 以“如何实现 [目标]”为主题的高参与度论坛线程。

始终需要挖掘的来源

• Google 搜索建议自动补全：针对工具名 / 语言名 / 垂直领域名称。
• SERP 中的“人们也问”框：针对相同关键词。
• Google Trends 上的上升查询：针对集群核心术语。

若用户已有明确的集群列表，请先索取其来源 URL；若无，则建议一份列表并允许用户编辑。

处理流程

步骤 1 - 现有内容盘点（防止内容重复）

若用户已有现有文章清单文件（如 backlog.json、posts.csv、已发布文章的 RSS 源等），请提供路径及标题枚举方式。内容重复检测步骤需要基于这些已有标题构建嵌入缓存。

若具备 Python 嵌入脚本，用户可生成缓存（一个 JSON 文件，将每个已有标题映射到其 OpenAI text-embedding-3-small 向量），并指向该缓存文件。典型成本约为每百万 token $0.02。

若无 Python 环境或缓存，退而使用仅 Jaccard 的重复检测（成本低，准确率较低；可识别完全相同的标题，但无法发现同义重复）。

同时为每个已有标题构建一个词元集合（小写、仅字母数字、去除停用词），用于步骤 4 中的 Jaccard 预过滤。

步骤 2 - 计算集群目标

若用户提供集群权重（如“30% n8n，20% AI 编码，...”），则应用权重：减去当前文章清单中各集群的数量，再按比例分配剩余 N 个目标。

若指定了 cluster <C>，则将全部 N 分配给该集群。

若完全没有集群分类体系，将整个博客视为单一集群，并优先考虑格式多样性（参见步骤 3 的格式矩阵）。

步骤 3 - 按集群挖掘候选主题

对每个集群，遍历其来源列表。对每个来源 URL：

1. 使用 WebFetch（或对 SERP 衍生信号使用 WebSearch）获取内容。
2. 提取候选查询字符串：GitHub 问题标题、PAA 问题、Reddit 帖子标题、论坛线程标题、自动补全建议。
3. 记录来源 URL + 原文标题 + 参与度数据（反应数、评论数、点赞数、回复数），以便后续分配强度等级。
4. 挖掘正文，而非仅标题。 对于高参与度的问题 / 线程 / SO 问答，获取正文并提取：

- 错误字符串（如 Error:、TypeError:、Traceback、异常类名、堆栈帧头）。

- 三重反引号包裹的代码块（常包含实际出错的代码片段，揭示真实边缘情况）。

- 版本限定短语（如“升级至 1.65 后”、“在 Cursor 0.42 上”、“v3 版本发布后”）。

每个提取出的字符串本身即成为一个候选种子。长尾故障排查类查询通常是原始错误信息，这类信息通常不会出现在帖子标题中。

谷歌侧种子：使用 WebSearch 以以下模式运行，并解析自动补全和 PAA 结果。对每个集群运行完整集，不仅限于故障排查类——长尾多样性是防止语料库陷入全“如何修复”的关键。

每个工具 / 框架 / 垂直领域集群内重复此矩阵。

每种格式的来源指引（除集群内源列表外）：

• use-case - 供应商模板库是最高信号来源。每个库条目都是经过验证的用户需求信号（人们搜索特定结果）。Reddit 上类似 *"如何用 [工具] 实现 [结果]"* 的帖子，且评论较多，也具有参考价值。若某个种子仅来自现有 SEO 博客的列表，则应剔除——这是竞争对手信号，而非真实用户需求信号。
• listicle - 在 best <类别> 和 top <N> <类别> 上进行 Google 自动补全深度挖掘；分析竞争对手的汇总类 SERP（观察前 3 个结果列出的内容）。Reddit 上提问 *"Y 场景下最好的 X 是什么"* 且评论多的帖子得分较高。
• migration - 标题以 moving from / switching from 开头的 Reddit 帖子；Stack Overflow 上关于在两个工具间导出并重新导入的问题；供应商的迁移文档（文档存在是因为用户有相关需求）。
• release-recap - 已存在于源列表中的供应商更新日志，但需重点挖掘 过去 90 天内发布的具体版本。只有当满足以下条件时，撰写 <工具> <版本> 的发布回顾才有价值：(a) 该版本为当前版本或仅落后一个次要版本，且 (b) 更新日志中至少包含一条面向用户的变更，而非仅内部重构。过时的回顾会迅速失效。

每个提取出的查询都成为候选内容。其来源即为首个需求信号。

步骤 3b - 递归自动补全遍历

对每个通过步骤 3 的候选内容，附加一个额外限定词并重新查询 Google 建议。保留任何返回新变体的深层补全结果。这能帮你获取真正的长尾关键词而非中尾关键词——一次自动补全可发现 "如何修复 n8n webhook 错误"，第二次则可能发现 "如何修复 n8n webhook 错误 404 在重启后出现"。

常见可尝试的限定词（尝试多个，保留实际返回结果的）：

error、not working、after update、stuck、slow、timeout、free、limit、vs <已知竞品>、<当前年份>、self-hosted、cloud、docker

最多进行 两次递归遍历 以控制运行时间。每个新补全继承父级的第一个信号来源，并仍需独立通过步骤 4。

步骤 3c - 从源内容中提炼实质信息

对每个通过步骤 3b 的候选内容，通过重新阅读 最高互动量的需求信号（在强度表中得分为 2 或 3 的内容——通常是高响应度的 GitHub 问题、置顶论坛帖或热门 Stack Overflow 问答）构建写作者可用的框架。若已在步骤 3.4 中获取过内容，可复用；否则现在立即获取。

提取四个字段：

1. **problem_summary** - 用 1-2 句话以写作者口吻描述症状 + 触发条件。客观陈述，不含营销语言。示例：*"n8n 的 HTTP Request 节点在 OAuth2 凭据的访问令牌过期且刷新令牌授予缺少 offline_access 范围时返回 401 错误。"* 从正文提取动词和名词；不要改写标题。

1. **confirmed_fixes[]** - 列出 {kernel, source} 条目。每个 kernel 是一个简短短语，捕捉具体操作动作（设置环境变量、降级版本、切换开关、代码修改）。source 为该修复方法的来源链接（论坛回复、厂商文档、GitHub 提交、更新日志条目）。浏览回复、已接受答案块、厂商“常见问题”页面。忽略噪音：跳过“你试过重启吗？”这类建议，或与后续回复矛盾的修复方案。如果问题确实未解决且无有效修复方案，保持 confirmed_fixes[] 为空——写作者将围绕“目前已知情况”展开，而非虚构解决方案。

1. **version_context** - 从正文或线程中提取任何版本限定短语，用于界定问题范围（如 "升级到 n8n 1.65 后"、"Cursor 0.42 仅限"、"CrewAI 0.114 引入"、"Power Automate desktop V2"）。若提及多个版本，选择与故障最紧密相关的那个。若正文为版本无关，设为 null。

1. **question_variants[] - 2-4 个与主题近似但表达不同的问题变体，来源于 PAA 框、自动补全深度补全、同类论坛帖标题或 SO 相关问题。每个变体必须是来自真实来源的字符串 —— 不得自行编造**。这些内容将用于写作者的 FAQ 模块和 LSI 关键词扩展。

若任一字段无法从正文真实填充，保持默认空值（""、[]、null）而非虚构。信息稀疏的框架比虚构的更实用——写作者可重新调研，但无法信任被污染的数据。

步骤 4 - 分类、评分与验证

1. 聚类（Cluster） - 根据主题中提到的工具/框架/垂直领域确定。若主题涉及两个聚类，选择需求信号更强的那个。

1. 格式（Format） - 按照以下顺序匹配表述，首个匹配项生效：

- 从 X 迁移到 Y / 从 X 切换到 Y / 从 X 移动到 Y → migration

- X 版本中的新功能 / X 更新日志 / X 发布说明 / X v<N> 特性 → release-recap

- Y 的最佳 X / 前 N 个 X / 免费 X / X 替代方案 / 最受欢迎的 X → listicle

- X 对比 Y / X 或 Y → x-vs-y

- <错误信息> / 无法工作 / 修复 / 失败 / 损坏 → how-to-fix

- 将 X 与 Y 连接 / 集成 / 将 X 与 Y 集成 → how-to-connect

- 使用 X 构建 <结果> / <结果> 使用 X / X 用于 <垂直领域/使用场景> → use-case

- 自动化 X / <工具> 的 Y 工作流 → how-to-automate

- 什么是 X / X 解释 / X 如何工作 → what-is

模糊规则：当标题提及具体产物时（如“每日 Slack 摘要”、“发票提取代理”），优先选择 use-case；对于通用流程（如“自动化邮件分类”），优先选择 how-to-automate。当选项数量 ≥3 时选择 listicle，恰好 2 个时选择 x-vs-y。

1. 内容重复检测（Cannibalization） - 基于第一步构建的已有标题缓存进行三层检查：

- Jaccard 预过滤：候选标题与已有标题的词元集合重叠度 ≥0.6 时丢弃（快速剔除明显重复项）。

- 语义 + 词元重复检查（仅在已构建嵌入缓存时启用）：

- 与任一已有标题的余弦相似度 ≥0.85 → 丢弃，记录为 cannibalization-semantic。

- 词元重复：候选标题与缓存中任意标题共享独特数值/错误码且共享工具关键词（无论余弦相似度如何）→ 丢弃。（捕捉表面表达不同但实质重复的内容。例如：“让 AI 代理设置 40 秒超时” vs “让 HTTP 模块出现 40 秒超时错误”——余弦值 0.51，但共享 [40秒, 设置] 被标记。）

- 余弦相似度在 0.75–0.85 之间且无词元重复 → REVIEW（保留但标记）。用户在追加时自行判断。

- 余弦相似度 <0.75 且无词元重复 → 接受。

- 若未构建嵌入缓存，则仅运行 Jaccard 预过滤，并在摘要尾部添加一行 cannibalization: jaccard-only，提示用户检查已简化。

1. 评分信号（Score signals） - 每个信号按强度等级赋分 1–3 分。若总分 signal_score < 3，则获取额外一次 SERP 结果，查找更多信号（PAA、第二个论坛帖、Stack Overflow 问题、厂商文档）。若仍低于 3 分，标记为 low-signal-score 并丢弃。

1. 具体性门槛（Specificity floor） - 标题必须满足以下至少一项：

- 字数 ≥7 个；

- 包含具体限定词（版本号、错误代码/字符串、命名集成对、特定边缘情况）。

若不满足，尝试从原始文本中提取限定词重写标题；若无法实现，则标记为 low-specificity 并丢弃。

1. 主源（Primary source） - 必须找到至少一个可引用的官方来源：厂商文档 / GitHub Issue / 官方更新日志链接。若无，丢弃。

1. 关键词（Keywords） - 从原始文本中提取核心名词短语作为主关键词，并补充 3–5 个 LSI 变体。不得虚构变体。

第五步 - 输出

每条通过审核的主题输出一个固定格式的区块，便于用户扫描或管道处理：

[01/50] cluster=<cluster>  format=how-to-fix  priority=2
TOPIC: How to fix the n8n "Cannot read properties of undefined" error in Code node
slug:  n8n-cannot-read-properties-undefined-code-node
keywords: n8n Code node error, undefined property, JavaScript error, item access, $json
commentary: Specific to mistakes when accessing $json on the wrong item; vendor docs do not show the failure mode.
problem: The n8n Code node throws "Cannot read properties of undefined" when the script accesses $json on an item index that doesn't exist (typically the second iteration of a for-loop reading $items[1].json with only one input item).
fixes:
  - guard with $items[i]?.json before accessing  (https://github.com/n8n-io/n8n/issues/<id>#issuecomment-<n>)
  - use $input.item.json instead of $items[i] when iterating  (https://docs.n8n.io/code/builtin/data/)
version_context: n/a
question_variants:
  - "n8n Code node Cannot read properties of undefined reading 'json'"
  - "n8n JavaScript error TypeError undefined json"
  - "Code node loop fails when item missing"
demand: (signal_score=4)
  - github_issue: https://github.com/n8n-io/n8n/issues/<id>  ("Code node throws Cannot read properties of undefined") [strength=3, 14 reactions]
  - reddit:       https://www.reddit.com/r/n8n/comments/<id>  ("Help: Code node error when looping over items") [strength=1]
sources:
  - https://docs.n8n.io/code/builtin/data/  (n8n docs - Built-in data variables)

若 confirmed_fixes 为空（即问题开放但尚未有有效修复方案），则输出 fixes: (none documented yet - frame as 'what's known so far') 而非空列表。若 version_context 为 null，输出 version_context: n/a。若 question_variants 为空，整行省略（罕见但合法）。

若该主题处于重复检测的 REVIEW 区间，需附加一条 dedup_review 行，供用户知情决策：

dedup_review: cosine=0.81 vs "n8n Code node returns undefined when reading $json" (backlog-queued)

随后输出摘要尾部：

Requested: 50
Validated: <X>
Dropped:   <Y>  (cannibalization-jaccard: <a1>, cannibalization-semantic: <a2>, cannibalization-token-dupe: <a3>, low-signal-score: <b>, no primary source: <c>, off-cluster: <d>, low-specificity: <e>)
Cluster mix:  <cluster1>=__  <cluster2>=__  ...
Format mix:   how-to-fix=__  how-to-connect=__  how-to-automate=__  x-vs-y=__  what-is=__  use-case=__  listicle=__  migration=__  release-recap=__

技能：博客主题调研

版本：1.0.0

分块：5/5

如果传入了 --append-to <path> 参数：输出差异（数量 + 聚类混合变化），并提示 将 <X> 个主题追加到 <path>？[y/N]。当用户选择 y 时，将每个主题以 JSON 格式写入目标路径，格式如下：

{
  "id": "<slug>",
  "topic": "<标题>",
  "cluster": "<聚类>",
  "format": "<格式>",
  "priority": 100,
  "status": "queued",
  "tags": ["<格式标签>", "<工具标签>"],
  "notes": "<评论>",
  "added_at": "<YYYY-MM-DD>",
  "research_proof": {
    "demand_signals": [...],
    "primary_sources": [...],
    "keywords": [...],
    "problem_summary": "<来自最高互动信号正文的 1-2 句事实性描述>",
    "confirmed_fixes": [
      {"kernel": "<简短修复语句>", "source": "<url>"},
      {"kernel": "<简短修复语句>", "source": "<url>"}
    ],
    "version_context": "<版本限定词或 null>",
    "question_variants": ["<变体 1>", "<变体 2>", "<变体 3>"]
  },
  "published_slug": null,
  "published_at": null
}

research_proof 数据块在状态为 queued 时保留在待办列表中，供下游写稿技能后续读取（避免重复调研）。当主题正式发布后，移除该数据块，防止待办文件随规模增长而膨胀；已发布的文章保留引用信息。

防幻觉机制

• 仅使用 WebFetch / WebSearch。 永远不要虚构 URL。若获取失败，直接丢弃候选主题——不得自行编造响应。
• 原文证据。 每个 evidence 字符串按字节原样复制，不进行改写或转述。长度限制 120 字符，超长则用 ... 截断。
• 禁止虚构数字。 主题标题中的版本号、价格、错误码必须至少在一个来源 URL 中出现。若不确定，从标题中移除。
• 运行时间绑定。 所有来源 URL 必须在运行当日可访问。若返回 404 或已被删除，即使上周有效，该信号也视为无效。
• 信号评分 ≥3，严格执行。 累计强度低于 3 的归入 low-signal-score。评分层级表是唯一权威标准——不得自行定义评分规则。
• 具体性下限。 标题模糊且无具体限定词的归入 low-specificity。长尾特征由标题本身内容决定，而非主观声称“这是具体的”。
• 聚类规范。 严格遵循用户定义的聚类分类体系。运行过程中不得新增聚类；若主题不匹配，应丢弃或询问用户。
• 允许标签检查。 若博客设有标签白名单，发现新隐含标签时需向用户提示后再接受——不得静默扩展标签集合。
• 默认拒绝商业意图主题。 不接受 SaaS 评测、引流查询、 affiliate 驱动的对比类主题，除非用户明确表示需要。此类内容广告 RPM 较低，且易被 affiliate 站点竞争压制。

本技能不做的事

• 不撰写文章。 应与下游写稿技能配合使用。
• 不估算搜索量绝对数值（不依赖 Ahrefs / SEMrush / Keyword Planner）。需求判断基于来源 URL 的定性证据，而非虚构的 5400 / 月 数值。
• 不修改博客策略文档。 聚类目标和权重由用户决定。
• 不自动发布。 使用 --append-to <path> 时，仅将主题加入待办队列，状态为 queued；由用户决定下一个写作主题。
• 不自行定时运行。 如需每周或每月定期调研，需搭配调度技能使用。

一键命令摘要

research <N> topics [for cluster <C>] [--append-to <path>]

1. 若用户已有标题嵌入缓存，刷新或重建嵌入缓存。
2. 计算各聚类的目标数量。
3. 从聚类源列表中挖掘候选主题，捕获每条信号的原文内容 + URL + 互动数。同时挖掘问题帖/线程正文中的错误字符串和版本限定短语，不仅限于标题。
4. 对通过筛选的候选主题，递归调用 Google 建议（最多两轮）以从中期尾部推进至长尾。
5. 从最高互动信号的正文中提炼核心内容：problem_summary、confirmed_fixes[]、version_context、question_variants[]。空默认值可接受；绝不虚构内容。
6. 进行逐项验证：格式匹配、聚类适配、三层去重（Jaccard ≥0.6 或余弦 ≥0.85 或 token 重复 = 丢弃；余弦 0.75–0.85 = 待审）、signal_score ≥ 3、具体性下限、至少一个主来源、真实关键词。
7. 输出结构化主题块 + 总结页脚。
8. 若使用 --append-to <path>，提示用户确认后，将结果写入待办文件，并保留 research_proof 数据块。