JSDoc 类型定义提取器

问题：JSDoc 注释里的类型信息很难真正用起来

在纯 JavaScript 项目中，开发者通常会用 JSDoc 的 @typedef 和 @param 标签标注类型。这些注释能被 IDE 识别，也能通过 jsdoc 命令生成 HTML 文档，但它们本质上是文档，不是代码资产：

• TypeScript 无法直接消费这些定义，想迁移到 TS 时只能手工重建 .d.ts 文件；
• 团队想查「项目里到底有哪些自定义类型」时，只能翻文档站或全文搜索，没有结构化清单；
• @typedef 散布在多个文件里，重复定义、命名冲突、引用失效难以及时发现。

核心能力与工作方式

这个技能通过 jsdoc-api 解析器在代码库上运行 JSDoc 解析，完成两件事：

1. 提取与索引：扫描代码库中的 JSDoc 类型注解，包括 @typedef 定义和 @param 标签，建立类型目录；
2. 产出声明文件：生成 TypeScript 风格的 .d.ts 声明文件，让注释里描述的类型变成可被类型系统消费的结构化产物。

工作流大致是：定位代码库 → 解析 JSDoc 注解 → 收集类型定义 → 写出 .d.ts 文件与可搜索的类型目录。输出是稳定、可检索的格式，适合接入 CI 检查或团队知识库，而不是一次性的文档生成。

适用边界与注意点

• 输入是 JavaScript 代码库中的 JSDoc 注释；如果项目已是 TypeScript，直接用 tsc 更合适。
• 能力依赖上游 JSDoc 工具链，要求 Node.js 8.15.0 及以上的稳定版本。
• JSDoc 语法本身有局限：复杂推导类型、泛型约束等表达可能无法完整映射到 .d.ts，迁移后仍需人工核对。
• 解析结果是从注释重建的类型信息，不改变运行时行为，也不做类型检查——它只是把文档里的类型转写成声明文件。