用途
tl-complexity-assessment 用于在 TypeScript/JavaScript/React 代码库中找出需要拆分的文件，输出一份按优先级排序、基于证据的复杂度热点列表，并附带具体的重构建议。它适合在大型重构之前、接手新代码库时、或为减少技术债做冲刺规划时使用。
主要能力
该技能从六个维度评估复杂度：
- 规模指标：文件行数（>500 高，300-500 中）、函数行数（>50 高，30-50 中）、组件行数（>300 高，150-300 中）。
- 职责指标：每文件导出数（>10 高，6-10 中）、类数（>2 高）、函数数（>15 中）。
- 耦合指标：import 语句数（>20 高，10-20 中）、跨域导入（>5 个不同域为高）、循环依赖（任何情况均为严重）。
- 圈复杂度代理：嵌套条件（>3 层高）、switch 分支（>7 中）、三元链（>2 中）、回调深度（>3 层高）。
- React 特有异味：useEffect 钩子（每组件 >3 高，2-3 中）、useState 钩子（>5 中）、内联子组件（任何情况中）、props 数量（>7 中）、页面中的业务逻辑（非平凡为高）。
- 结构异味：god 文件（utils.ts、helpers.ts、common.ts、shared.ts 为高）、兜底路由（>10 条内联路由高）、巨型 schema（>10 个不相关表高）、混合关注点（API 与 UI 同文件为中）、桶文件膨胀（index.ts 超过 50 个再导出为中）。
使用方式
快速开始：运行扫描脚本获取报告。
Bash：
./scripts/complexity-scan.sh src/
PowerShell：
.\scripts\complexity-scan.ps1 -TargetDir src/
如需引导式评估，按以下阶段进行：
- 自动化发现：运行命令收集指标，例如查找大文件、统计导出/导入数、查找 god 文件、查找钩子较多的 React 组件、查找深层嵌套条件等。
- 人工分析：对候选文件阅读、识别职责、检查耦合、评估内聚、记录证据。
- 评分：按 0-10 打分，公式为 Score = (Severity × 2) + (Impact × 2) + (Effort_Inverse)。
- 报告：为每个发现输出文件路径、评分、严重度、工作量、指标、观察、建议和证据。
该技能强调“铁律”：没有证据不得声称复杂。每个发现必须包含文件路径、行数或指标以及具体观察。
适用场景
- 寻找复杂文件、需要拆分的文件、单体文件、god 文件。
- 评估复杂度、代码健康检查、识别重构候选。
- 重大重构之前、接手新代码库、技术债减少的冲刺规划。
限制
不适用于查找 bug（应使用调试技能）、评估安全漏洞（应使用安全审计）、审查代码风格（应使用 lint/格式化工具），以及已经很小且职责单一的文件（<150 行）。
相关技能
tl-knip（查找未使用导出）、codebase-audit（更广泛的代码健康评估）、ui-audit（UI 复杂度与漂移检测）、semgrep/skills/code-security（安全漏洞检测）。
参考文档
references/react-patterns.md、references/coupling-analysis.md、references/refactoring-strategies.md。