| name | opensourcefaq |
| description | 解答与开源产品有关的深度技术问题，输出图文并茂的 Markdown 技术文章。触发条件：用户提出与开源项目（如 PostgreSQL、Redis、Kafka、Kubernetes、ClickHouse、Flink 等）相关的技术问题，并提供源码目录或 URL、deepwiki repo 名称。即使用户只说"帮我解答这个开源问题"或"分析一下这个项目的某个机制"，也应使用本 skill。输出文章保存到项目 markdown/ 目录，要求直击问题、图文并茂、有实操细节和原理分析。 |
Open Source FAQ Skill
深度解答开源项目技术问题，输出可发布级别的 Markdown 技术文章。
输入规范
| 字段 | 说明 | 示例 |
|---|
| 问题 | 要解答的技术问题 | "PostgreSQL 为什么用 B-Tree 而不是 LSM-Tree？" |
| 源码目录 / URL | 涉及的开源项目本地路径或 GitHub URL（可多个） | /mnt/user-data/uploads/postgres/ 或 https://github.com/postgres/postgres |
| deepwiki reponame | deepwiki 中的 repo 标识，用于拉取结构化文档 | postgres/postgres |
解答流程（严格按顺序执行）
Phase 0 — 确认输入
在开始前，检查用户是否提供了以下内容：
如有缺失，简短追问，不要跳过。
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，确认：
4.3 代码示例验证
对文章中的代码示例：
4.4 最终 Checklist
[ ] 问题被直接回答（TL;DR 清晰）
[ ] 原理有源码支撑
[ ] 图表至少 2 种（mermaid + svg 或 mermaid + text diagram）
[ ] 实操可复现（环境 + 数据 + 命令完整）
[ ] 没有过期/错误的技术描述
[ ] 参考资料完整且版本明确
[ ] 文章保存到 markdown/ 目录
输出规范
- 文件路径：
markdown/<问题关键词-项目名>.md（英文小写，连字符分隔）
- 文件编码：UTF-8
- 图表：mermaid 代码块用
```mermaid，SVG 直接嵌入 <svg> 标签
- 代码引用：优先引用原始源码，不要改写意思
注意事项
- 版本敏感：开源项目实现随版本变化大，每次引用源码必须注明版本/commit
- 多项目问题：若问题涉及多个项目（如 Kafka + Flink），分别建立素材池后综合分析
- 避免过度概括：宁可说"在 X 版本中，Y 模块的实现是..."，也不要说"X 总是..."
- 实操优先：每个原理点尽量配一个可验证的实操步骤
- 中文优先：文章默认用中文撰写，代码注释可用英文
