---
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 — 确认输入

在开始前，检查用户是否提供了以下内容：
- [ ] 明确的技术问题
- [ ] 源码目录或 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 三种图表形式中的至少两种。**

#### 文章结构模板

```markdown
# [问题标题]

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

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

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

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

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

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

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

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

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

#### 图表规范

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

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

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

#### 实操演练规范

每个实操场景必须包含：

```markdown
### 环境准备
（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. **中文优先**：文章默认用中文撰写，代码注释可用英文