opensourcefaq

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 三种图表形式中的至少两种。 文章结构模板 # [问题标题] > 关键词：[项目名] · [版本] · [技术领域] ## 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> 标签 代码引用 ：优先引用原始源码，不要改写意思 注意事项 版本敏感 ：开源项目实现随版本变化大，每次引用源码必须注明版本/commit 多项目问题 ：若问题涉及多个项目（如 Kafka + Flink），分别建立素材池后综合分析 避免过度概括 ：宁可说"在 X 版本中，Y 模块的实现是..."，也不要说"X 总是..." 实操优先 ：每个原理点尽量配一个可验证的实操步骤 中文优先 ：文章默认用中文撰写，代码注释可用英文