新技术调研与文档整理指南（tech-research-guide）
Overview
本 skill 提供一套可复用的「新技术系统调研 → 结构化文档产出」方法论。它把一次完整的
技术调研拆解为 5 个阶段（调研 → 富集 → 绘图 → 成文 → 转换），并固化了格式规范、
来源标注纪律、架构图标准与一致性规则，确保任何新技术都能产出统一、准确、可溯源、
离线自包含的技术指南。
详细格式规范见 references/research_format.md；架构图规范与避坑见
references/diagram_compliance.md；Markdown 骨架见 assets/template.md；
可复用脚本见 scripts/。
When to Use
- 用户要求"调研 / 整理 / 分析 / 对比"某个具体技术、工具、框架、平台或开源项目。
- 用户需要产出一份带架构图、竞品对比、示例代码、最佳实践的完整技术文档。
- 用户做技术选型，需要"某技术 vs 竞品"的带来源对比表。
- 用户已有一份技术资料，要求补全案例、对比、图表或转成 HTML。
Workflow
阶段 1 · 调研取证（Research）
并行检索，优先一手来源：
- WebSearch + WebFetch 抓取：官网、GitHub README、LICENSE 文件、官方架构文档。
- 核实第 1 章基础信息：官网 / 仓库 / 所属公司 / 核心维护者 / 开源协议 必须来自一手来源，不得臆测。
- 记录社区规模（Stars / Contributors / 部署数）并标注获取时间。
- 若技术源自国外，检索中文学习资源（见阶段 1b）。
1b. 国外技术的中文资源（仅当技术非国产时执行）：
- WebSearch 关键词："{{技术名}} 中文文档 / 中文教程 / 中文社区 / 国内学习"。
- 产出「国内学习资源」小节：中文站/镜像、CSDN/掘金/博客园/GitCode 教程，逐条给链接与类型。
- 附国内排障提示（官方镜像拉取慢 → 建议配国内加速器，安装耗时显著下降）。
阶段 2 · 内容富集（Enrich）
- 企业案例：精选 5 个左右官方公开案例，每个拆解「背景规模 → 遇到的问题 → 解决方法/实现 →
量化成效 → 关键经验 → 信息来源(URL)」。非官方报道须标注"社区报道、非官方认证"的免责声明。 - 竞品对比：选至少 2 个适用范围最广的竞品，调研各自官方架构。
- 性能/功能指标：标注测试规模（如"200 万资产下 1200 req/s、零失败率"）。
阶段 3 · 架构图绘制（Diagram，强制用 skill）
- 调用
diagram-builderskill（「架构图与流程图绘制专家」），遵循其分层架构图规范：
虚线分组框 + 胶囊标题 + 朝右箭头 marker + 底部图例 +viewBox="0 0 680 H"。 - 用
scripts/gen_architecture_svg.py生成静态 SVG（可 importbuild/features_grid
复用核心函数，按新技术的层数据传参）。生成{{tech}}_architecture.svg及竞品对比图。 - 严禁用裸 Mermaid + CDN（离线失效）。详见
references/diagram_compliance.md避坑清单。 - 若需在对话即时展示，先
read_me(modules=["diagram"])再用show_widget内联 SVG。
阶段 4 · 成文（Markdown）
- 复制
assets/template.md骨架，按六章结构填充（详见references/research_format.md）。 - 强约束（一致性规则）：
1. 标题层级 h1→h2→h3→h4，禁止跳级；手写目录只列一级标题。
2. 所有对比、量化指标、竞品论断必须带来源（URL 或缩写，文末汇总 URL 映射）。
3. 文档末尾禁止"作者: AI 助理"泛化落款；可保留"最后更新/许可证"。
4. 图表用引用，由转换脚本内联，杜绝断图。
5. 竞品连接器数量、图存储类型、部署组件数等易错点，以官方文档为准修正。
阶段 5 · 转换与交付（HTML）
- 运行
scripts/convert_md.py (输入.md) [输出.html] [标题]： - 自动剔除手写目录块、解析 h2~h4 生成侧边栏嵌套 TOC、注入锚点 id。
- 自动内联同目录
*.svg、应用标题层级 CSS、零外部 CDN 依赖。 - 所有外链可点击：
https?://外链自动加target="_blank" rel="noopener noreferrer"
新标签打开（不会离开文档），并带下划线与↗图标，确保读者可一键溯源。 - 校验：锚点零断链、无 img 标签残留、SVG 已内联、TOC 层级分明、外链均可点击。
- 交付：同时给出
.md源文件与自包含.html（浏览器预览）。
阶段 6 · 校稿（可选，用户要求时执行）
文章生成后，若用户明确要求校稿，则以独立的「校稿角色」对成稿做三方核查，并产出结构化校稿报告（可独立成 {{tech}}_校稿报告.md 或在对话直接给出）。
① AI 味 / 可读性检测
- 扫描堆砌词（赋能/助力/闭环/全链路/一站式/基座/坐镇/显著/可观/卓越等）、无数据支撑的修饰副词（"显著提升""可观影响"）。
- 标注长从句嵌套、需多次回读的句子，建议拆句或改写。
- 输出：问题句 + 位置(章/行) + 改写建议。
② 信息来源准确性
- 抽样 WebFetch/WebSearch 核验关键外链是否仍存活。
- 检查所有量化指标、竞品论断是否都带来源；无来源论断标记「缺来源」。
③ 错误 / 结论 / 数据核查
- 对硬事实（年份、版本号、协议、开源时间、部署数）抽样比对一手来源。
- 对案例量化数据（如"X→Y 提速""节省 N 小时"）比对官方案例页原数据。
- 标记严重度：🔴 硬错误（直接修正文档并说明） / 🟡 存疑待补精度（加注说明） / 🟢 已核实准确。
- 校稿发现的问题直接修正文档，存疑点加注而非删除，保持可追溯。
> 校稿是「可选」步骤，仅在用户明确要求时执行，不默认运行，避免拖慢常规产出。
Accuracy & Consistency Discipline（交付前必查）
- [ ] 基础信息均来自一手来源；社区数据标注时间
- [ ] 国外技术已检索并标注中文学习资源
- [ ] 所有竞品对比表每个单元格都带来源
- [ ] 架构图遵循 diagram-builder 规范（虚线分层框 + 胶囊标题 + 箭头 + 图例）
- [ ] 标题层级无跳级、TOC 一致（只列一级或全列举）
- [ ] 无"AI 助理"署名
- [ ] HTML 零外部 CDN、零断图、锚点零断链、外链均可点击（target=_blank + 下划线 + ↗）
Resources
scripts/
convert_md.py— 通用 MD→自包含 HTML 转换器（侧边栏 TOC + 内联 SVG + 标题层级 CSS，零 CDN）。gen_architecture_svg.py— 生成符合 diagram-builder 规范的分层架构 SVG（build/features_grid可复用）。
references/
research_format.md— 六章结构定义、各章写作纪律、一致性规则、准确性自查清单。diagram_compliance.md— 架构图规范、避坑清单（箭头裁切 / Mermaid 离线 / 断图 / slug 错位 / 层级不分）。
assets/
template.md— 六章 Markdown 骨架模板（含来源列、SVG 引用位、附录溯源表），供新调研直接复制。proofread_report_template.md— 校稿报告模板（AI 味 / 来源 / 错误数据 三节 + 严重度标记），校稿角色直接填充。
