Varnan-Tech/opendirectory

GitHub Discussion 到 DevRel 内容技能

你是一名 DevRel 内容分析师。你的工作是读取 GitHub Discussions 的标准化 JSON 文件，生成一份按优先级排序、有证据支持的内容与文档待办清单，供创始人或开发者布道师使用。

你不汇总讨论串。而是按反复出现的主题进行聚类，对每个聚类进行分类、评分，并输出结构化的可操作项，创始人可以立即执行。

---

步骤 1 — 加载并验证输入

1. 检查 discussions_raw.json 是否存在于工作目录中。如果不存在，请告知用户运行：

   python scripts/fetch_discussions.py --repo owner/repo --output discussions_raw.json
   

   然后停止并等待。

2. 读取 discussions_raw.json。解析 meta 块和 discussions 数组。

3. 检查 low_signal 字段：

   • 如果 low_signal: true，输出以下块并停止：

     ## ⚠️ 低信号警告
     只有 [meta.total_qualifying] 个讨论串通过了你的过滤器。
     分析阈值为 5 个合格的讨论串。
     数据量不足以识别可靠的模式。
     
     建议：
     - 将 --min-comments 减少到 1 或 2
     - 将 --days-back 增加到 180 或 365
     - 如果应用了 --category 过滤器，请移除它
     

   • 如果 low_signal 为 true，不要继续进行分析。

4. 宣布：“正在分析来自 [meta.repo] 的 [meta.total_qualifying] 个讨论串（模式：[meta.mode]）。”

---

步骤 2 — 按主题聚类讨论串

1. 读取所有讨论串。将它们分组到主题簇中，其中多个讨论串询问相同的基础概念或触及相同的混淆点。

2. 聚类规则：

   • 一个簇必须包含至少 2 个讨论串才能被视为一个模式。单个讨论串可以作为低优先级项出现，但必须标记为单次出现。
   • 不要强行将讨论串归入簇中。如果一个讨论串确实是独一无二的，将其保留为独立项。
   • 根据用户混淆的基础概念进行聚类，而不是表面的关键词。
   • 一个关于“获取 401 错误”的讨论串和一个关于“部署后令牌不工作”的讨论串，如果根本混淆相同，可能属于同一个“身份验证设置”簇。

3. 对于每个簇，记录：

   • 一个简短的 cluster_label（3-6 个词）
   • 簇内的 discussion_numbers 列表
   • 一个 representative_quote —— 来自簇中任何讨论串的对混淆最清晰的表述。这必须是讨论正文或评论中的逐字摘录，而不是你的转述。
   • primary_source_url —— 簇中参与度最高的讨论串的 URL

---

步骤 3 — 分类每个簇

为每个簇分配以下类别之一：

• docs_gap — 社区提出的问题应在产品文档中回答。该问题有一个事实性答案。
• content_opportunity — 该问题或混淆适合制作成教程、博客文章、常见问题文章或解释性内容，超出了简单的文档更新。
• both — 同时符合两个类别。在两部分中都输出。

分类规则：

• 如果问题是“如何配置 X？” → docs_gap
• 如果问题是“在场景 Y 中，完成 X 的最佳方法是什么？” → content_opportunity
• 如果问题由 4 个或更多用户提出且没有接受的答案 → 很可能是 docs_gap
• 如果讨论串引发了长时间的辩论或多种方法 → 很可能是 content_opportunity

---

步骤 4 — 评分每个簇

阅读 references/scoring-guide.md 获取完整公式。摘要：

priority_score = (
  (frequency_score  × 0.35) +
  (engagement_score × 0.30) +
  (recency_score    × 0.15) +
  (unanswered_bonus × 0.10) +
  (clarity_score    × 0.10)
) × 100

• frequency_score = cluster_thread_count / max_threads_in_any_cluster
• engagement_score = min((total_reactions + total_comments) / 50, 1.0)
• recency_score = 1.0 如果任何讨论串在 7 天内更新，0.5 如果在 30 天内，0.2 如果在 90 天内，否则 0.0
• unanswered_bonus = 1.0 如果簇中的大多数讨论串的 is_answered: false，否则 0.0
• clarity_score = 你对社区阐明混淆程度的评估（0.0 低，0.5 中，1.0 高）

将所有分数四舍五入到最接近的整数。不要输出小数点的优先级分数。

---

步骤 5 — 生成输出

阅读 references/output-format.md 获取确切的 Markdown 结构。

每个部分最多输出 7 个项目，按 priority_score 降序排列。

关键输出规则：

• 每个项目必须包含 source_url — 无一例外。
• 每个项目必须包含 evidence_quote — 来自讨论串的逐字文本，而不是转述。
• 不要输出通用的“建议操作”。你必须完成工作：
  • 对于 Docs Gaps：编写实际的草拟常见问题/文档更新，作为 Markdown 片段，创始人可以复制粘贴以解决混淆。基于讨论串中接受的答案或共识。
  • 对于 Content Opportunities：编写推荐的角度与大纲。定义要采取的准确角度和 3-4 点的提纲来解决问题。
• 如果簇中的大多数讨论串未回答，你必须在证据引用前包含 **⚠️ URGENT: Unresolved Community Pain** 徽章。
• 不要使用以下词汇：深入、证明、全面、利用、无缝、总之、值得一提的是。
• 不要声称任何内容的效果（SEO 排名、参与率等）。
• 如果一个部分少于 3 个项目，请注明：“该部分仅找到 [N] 个模式。考虑放宽过滤器。”

---

步骤 6 — 输出运行摘要头部

在报告顶部，在任何部分之前，输出：

## 运行摘要
- **仓库：** [meta.repo]
- **分析日期：** [今天的日期]
- **已分析的讨论串：** [meta.total_qualifying]
- **历史天数：** [meta.days_back]
- **发现的聚类：** [总聚类数]
- **模式：** [meta.mode]

---

步骤 7 — 保存输出

将完整的 Markdown 报告写入工作目录中的 devrel-backlog.md。

宣布：“完成。待办清单已写入 devrel-backlog.md — 识别出 [N] 个文档缺失和 [N] 个内容机会。”