概述
ts-morph-analyzer 是一个基于 ts-morph 的轻量级代码库分析工具，用于提取签名、JSDoc 和调用链，避免用完整文件读取占满上下文。其核心原则是：以最少的 token 用量获得最大的架构洞察。
适用场景
- 快速理解代码库的公开 API：使用 extract-signatures.ts
- 通过函数调用追踪缺陷：使用 trace-calls.ts
- 梳理某个模块导出了什么：使用 analyze-exports.ts
- 在深入之前检测架构问题：使用 code-smells.ts
- 理解 import/依赖结构：使用 analyze-exports.ts --deps
安装
在技能目录中执行：
cd ~/.claude/skills/ts-morph-analyzer
npm install
或运行安装脚本：
~/.claude/skills/ts-morph-analyzer/setup.sh
主要能力与使用方式
提取签名（最常用）
获取函数/方法签名与 JSDoc，无需读取完整文件：
# 文件中的所有签名
npx ts-node scripts/extract-signatures.ts src/api/users.ts
# 目录中的所有签名（递归）
npx ts-node scripts/extract-signatures.ts src/
# 仅筛选导出的内容
npx ts-node scripts/extract-signatures.ts src/ --exported
# 包含类型与接口
npx ts-node scripts/extract-signatures.ts src/ --types
# 以 JSON 输出以便后续处理
npx ts-node scripts/extract-signatures.ts src/ --json
输出示例：
// src/api/users.ts
/**
* Fetches user by ID from the database
* @param id - User's unique identifier
* @returns User object or null if not found
*/
export async function getUser(id: string): Promise<User | null>
/**
* Creates a new user account
* @throws ValidationError if email is invalid
*/
export async function createUser(data: CreateUserInput): Promise<User>
追踪调用层级
向上追踪（谁调用了这个函数？）或向下追踪（这个函数调用了什么？）：
# 谁调用了这个函数？
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --up
# 这个函数调用了什么？
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --down
# 完整调用链（双向，限制深度）
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --depth 3
# 以树形输出
npx ts-node scripts/trace-calls.ts src/api/users.ts:getUser --tree
输出示例（--up）：
getUser (src/api/users.ts:15)
├── called by: handleGetUser (src/routes/users.ts:23)
│ └── called by: router.get('/users/:id') (src/routes/users.ts:8)
├── called by: validateSession (src/middleware/auth.ts:45)
└── called by: getUserProfile (src/services/profile.ts:12)
分析导出
梳理模块的公开 API 表面：
# 这个模块导出了什么？
npx ts-node scripts/analyze-exports.ts src/api/
# 包含重新导出
npx ts-node scripts/analyze-exports.ts src/ --follow-reexports
# 显示依赖图
npx ts-node scripts/analyze-exports.ts src/ --deps
检测代码异味
快速进行架构评估：
# 完整分析
npx ts-node scripts/code-smells.ts src/
# 特定检查
npx ts-node scripts/code-smells.ts src/ --check circular-deps
npx ts-node scripts/code-smells.ts src/ --check large-functions
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc
npx ts-node scripts/code-smells.ts src/ --check many-params
架构评估模式
分析一个新代码库以发现潜在问题时：
1. 先看公开 API 表面
# 了解全貌：导出了什么？
npx ts-node scripts/extract-signatures.ts src/ --exported --json > api-surface.json
关注点：过度复杂的接口、命名不一致、公开 API 缺失 JSDoc。
2. 依赖结构
# 梳理 import——循环依赖是危险信号
npx ts-node scripts/code-smells.ts src/ --check circular-deps
关注点：循环依赖、过深的 import 链、模块边界不清晰。
3. 函数复杂度
# 找出可能需要重构的复杂函数
npx ts-node scripts/code-smells.ts src/ --check large-functions --check many-params
关注点：超过 50 行的函数、超过 5 个参数、过深的嵌套。
4. 文档覆盖率
# 公开 API 应当有文档
npx ts-node scripts/code-smells.ts src/ --check missing-jsdoc --exported
追踪数据流
调试时，无需读取完整文件即可追踪数据流：
模式：“这个值来自哪里？”
# 1. 找到调用该函数并传入错误值的地方
npx ts-node scripts/trace-calls.ts src/service.ts:processData --up --depth 5
# 2. 获取调用者的签名以理解参数流向
npx ts-node scripts/extract-signatures.ts src/caller.ts
模式：“这个返回值去了哪里？”
# 1. 找到谁使用了该函数的返回值
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down
# 2. 查看返回值如何被消费
npx ts-node scripts/trace-calls.ts src/api.ts:fetchUser --down --show-usage
模式：“某个缺陷的完整调用链”
# 获取从入口点到问题区域的完整路径
npx ts-node scripts/trace-calls.ts src/broken.ts:problematicFn --up --tree
脚本位置
所有脚本位于：~/.claude/skills/ts-morph-analyzer/scripts/
| 脚本 | 用途 |
|---|---|
| extract-signatures.ts | 提取函数/方法/类签名及 JSDoc |
| trace-calls.ts | 向上/向下追踪调用层级 |
| analyze-exports.ts | 梳理模块导出与依赖 |
| code-smells.ts | 检测架构问题 |
常见问题
| 问题 | 解决方案 |
|---|---|
| “Cannot find module 'ts-morph'” | 在技能目录中运行 npm install |
| 大型代码库上运行缓慢 | 添加 --include "src/**/*.ts" 限制范围 |
| 缺失类型信息 | 确保项目根目录存在 tsconfig.json |
| 内存问题 | 使用 --exclude "node_modules"（默认） |