新技术学习指南生成专家

要解决什么问题

调研一项新技术时，最常见的失败不是「查不到资料」，而是查完之后产出的东西没法长期用：架构图写在裸 Mermaid 里，离线打开就渲染不出来；竞品对比表里的数字说不出出处，半年后没人敢信；每份文档格式都不一样，接手的人得重新适应一套私人约定。tech-research-guide 把「调研 → 文档产出」当成一条流水线，在每个环节都固化了硬约束，目标是让任意新技术都能得到统一、准确、可溯源、离线自包含的技术指南。

它如何工作

方法论拆成 5 个阶段，每个阶段都有明确的输入、产出和纪律：

• 调研取证：并行抓取官网、GitHub README、LICENSE 文件与官方架构文档。基础信息（官网 / 仓库 / 所属公司 / 核心维护者 / 开源协议）必须来自一手来源，不得臆测；社区规模数据要标注获取时间。非国产技术额外检索中文文档、镜像站与排障经验。
• 内容富集：精选约 5 个官方公开案例，按「背景规模 → 遇到的问题 → 解决方法 → 量化成效 → 关键经验 → 来源 URL」逐条拆解，非官方报道要加免责声明。至少调研 2 个适用范围最广的竞品的官方架构，性能指标必须带上测试规模。
• 架构图绘制：强制遵循 diagram-builder 的分层规范（虚线分组框、胶囊标题、朝右箭头 marker、底部图例），用 scripts/gen_architecture_svg.py 产出静态 SVG。严禁裸 Mermaid + CDN，因为离线即失效。
• 成文与转换：以 assets/template.md 为骨架填充六章结构，所有对比、量化指标、竞品论断都必须带来源，文末汇总 URL 映射。scripts/convert_md.py 负责生成自包含 HTML：内联同目录 SVG、生成侧边栏嵌套 TOC、注入锚点、零 CDN 依赖，外链一律新标签打开并保留可溯源入口。

适用边界与注意点

• 它是一套方法论 + 脚本，不是自动抓取器：阶段 1 的取证质量取决于运行时可用的搜索与抓取能力。
• 阶段 3 依赖 diagram-builder skill 的规范，脱离它单独跑脚本，产出的图不符合分层架构标准。
• 校稿是可选步骤，只在用户明确要求时以独立角色执行，不默认运行，避免拖慢常规产出。
• 转换脚本只处理与 Markdown 同目录的 *.svg，图表文件必须放在同一目录，否则仍会断图。
• 文档末尾不允许出现「AI 助理」这类泛化署名，只保留最后更新时间与许可证信息。