opensourcefaq

Open Source FAQ Skill

深度解答开源项目技术问题，输出可发布级别的 Markdown 技术文章。

输入规范

解答流程（严格按顺序执行）

Phase 0 — 确认输入

在开始前，检查用户是否提供了以下内容：

• 明确的技术问题
• 源码目录或 GitHub URL（至少一个）
• deepwiki reponame（强烈建议提供；如未提供，尝试从 URL 推断）

如有缺失，简短追问，不要跳过。

Phase 1 — 问题描述与分析

1.1 问题描述

用自己的语言重新表述问题，明确：

• 问题的技术背景（版本、场景）
• 核心疑问是什么（行为/性能/架构/API 语义）
• 预期解答的粒度（原理级 / 源码级 / 实操级）

1.2 问题分析

拆解问题为若干子问题，例如：

• 涉及哪些核心模块/子系统？
• 需要理解哪些数据结构或算法？
• 有哪些已知假设可能影响答案？

列出解答路线图（bullet），以便后续按图索骥。

Phase 2 — 准备素材

2.1 搜索源码

优先级：源码 > 文档 > 网络文章

根据问题分析，定位以下内容：

a. 核心实现文件（.c/.go/.java/.rs 等）
b. 相关头文件 / 接口定义
c. 单元测试 / 集成测试（揭示预期行为）
d. 官方文档文件（.md / .rst / doc/ 目录）
e. 变更记录（CHANGELOG / git log 关键 commit）

源码搜索策略：

• 若提供本地路径：使用 grep -rn, find, cat 等工具直接读取
• 若提供 GitHub URL：使用 web_fetch 拉取关键文件；对大型仓库，优先拉取 README、顶层目录结构，再按需深入
• 重点关注：函数调用链、关键数据结构、注释中的设计说明

2.2 浏览 DeepWiki 综述

调用 deepwiki:read_wiki_structure 获取项目的文档主题列表，识别与问题相关的章节。

再调用 deepwiki:read_wiki_contents 阅读相关章节，提取：

• 架构概述
• 核心概念定义
• 模块关系图

2.3 DeepWiki 精准问答

调用 deepwiki:ask_question，将问题的子问题逐一提问，获取上下文关联的深度回答。

每次提问后，记录：

• 关键结论
• 涉及的源码位置（文件名 + 行号）
• 与其他子问题的关联

2.4 搜索网络文章

使用 web_search 搜索相关文章，严格过滤：

✅ 保留：
  - 官方博客 / release notes
  - 知名技术博客（作者可信）
  - 版本匹配（与用户关注版本一致）
  - 发布时间在项目相关版本发布后

❌ 丢弃：
  - 内容与当前版本不符（API 已变更）
  - 没有源码引用的纯经验文章
  - 内容与源码搜索结论相矛盾
  - SEO 农场内容 / 无实质信息

对每篇保留文章，记录：来源、版本、核心观点、是否已被源码验证。

Phase 3 — 撰写 Markdown 文章

文章必须图文并茂，包含 text、mermaid、svg 三种图表形式中的至少两种。

文章结构模板

# [问题标题]

> 关键词：[项目名] · [版本] · [技术领域]

## TL;DR
（3-5 句话给出核心结论，让读者知道看完能得到什么）

## 背景与问题定义
（问题的技术背景、为什么这个问题值得深入研究）

## 原理分析
（核心机制的深度解析，配合 mermaid 流程图 / 架构图）

## 源码走读
（关键代码片段 + 注释，直接引用文件路径和行号）

## 实操演练
（模拟环境构建 + 数据生成 + 验证步骤，确保可复现）

## 边界条件与常见误区
（what-if 分析，反直觉的地方）

## 拓展思考
（举一反三：相关问题、对比其他项目的实现、延伸阅读）

## 参考资料
（源码文件、文档链接、网络文章，注明版本）

图表规范

mermaid 使用场景：

• 流程图（代码执行路径、请求生命周期）
• 时序图（组件间交互）
• 状态机（对象生命周期）
• 类图（数据结构关系）

SVG 使用场景：

• 内存布局图（展示数据结构在内存中的排列）
• 对比图（两种方案的 side-by-side 对比）
• 性能曲线示意图

代码块规范：

• 明确标注语言（c, go, ```sql 等）
• 在注释中标注文件路径和行号
• 超过 30 行的代码块要加折叠说明

实操演练规范

每个实操场景必须包含：

### 环境准备
（Docker / 本地安装命令，版本要求）

### 数据生成
（建表 SQL / 数据生成脚本，确保能复现问题场景）

### 验证步骤
（具体命令 + 预期输出，让读者知道"对了"是什么样子）

### 结果解读
（输出意味着什么，如何与原理对应）

Phase 4 — 验证文章正确性

在输出最终文章前，必须完成验证。

4.1 源码交叉验证

对文章中每一个"原理陈述"，确认：

• 有对应源码佐证（文件 + 行号）
• 源码版本与文章描述的版本匹配
• 没有与源码矛盾的表述

4.2 DeepWiki 验证

将文章核心结论作为问题，再次询问 deepwiki:ask_question，确认：

• DeepWiki 的回答与文章结论一致
• 如有出入，更新文章（以源码为准，DeepWiki 为辅）

4.3 代码示例验证

对文章中的代码示例：

• 语法正确（无明显拼写 / 语法错误）
• 逻辑与原理描述一致
• 实操命令在指定环境中可执行（如有本地环境可验证则执行验证）

4.4 最终 Checklist

[ ] 问题被直接回答（TL;DR 清晰）
[ ] 原理有源码支撑
[ ] 图表至少 2 种（mermaid + svg 或 mermaid + text diagram）
[ ] 实操可复现（环境 + 数据 + 命令完整）
[ ] 没有过期/错误的技术描述
[ ] 参考资料完整且版本明确
[ ] 文章保存到 markdown/ 目录

输出规范

• 文件路径：markdown/<问题关键词-项目名>.md（英文小写，连字符分隔）
• 文件编码：UTF-8
• 图表：mermaid 代码块用 ```mermaid，SVG 直接嵌入 <svg> 标签
• 代码引用：优先引用原始源码，不要改写意思

注意事项

1. 版本敏感：开源项目实现随版本变化大，每次引用源码必须注明版本/commit
2. 多项目问题：若问题涉及多个项目（如 Kafka + Flink），分别建立素材池后综合分析
3. 避免过度概括：宁可说"在 X 版本中，Y 模块的实现是..."，也不要说"X 总是..."
4. 实操优先：每个原理点尽量配一个可验证的实操步骤
5. 中文优先：文章默认用中文撰写，代码注释可用英文