在编程开发中，长期与代码打交道，难免会遇到这样的问题：代码编译通过且类型检查无误，但运行时却报错？或者一个依赖包的小版本升级，竟导致整个项目崩溃？问题的根源往往隐藏在未被清晰识别的依赖关系链中。CodeBuddy 正是为解决此类问题而设计——它提供 workspace-aware 依赖图谱、第三方库调用链定位、版本兼容性语义比对及交互式依赖树可视化四大能力，覆盖静态结构、动态调用、跨包影响与可视化诊断。

当开发过程中遇到模块调用失败、版本冲突报错，或不确定某个包是否被其他子包实际引用时，本质上意味着项目的依赖关系链条尚未被完整识别和验证。CodeBuddy 正是针对这一场景设计的，它提供多种方式从不同维度检查依赖关系，覆盖静态结构、动态调用、跨包影响与可视化诊断。

启用 workspace-aware 依赖图谱分析

该方法特别适用于 monorepo 项目（例如使用 pnpm、Lerna、Nx 管理的多包仓库）。它能精准识别包之间的真实引用路径、peer 依赖的隐式约束以及导出边界，避免仅凭 package.json 就下结论的误判。

操作步骤如下：

第一步，确保项目根目录存在有效的 workspace 配置文件。例如，pnpm-workspace.yaml 中的 packages 字段必须非空且路径可解析。若该字段为空数组，或路径通配符无法匹配任何子包，则后续生成的图谱将为空。

第二步，在 VS Code 或 JetBrains IDE 的 CodeBuddy 设置中，将“Dependency Analysis Scope”显式切换为“Workspace-level”。默认设置为“Package-level”，此设置下不会跨包扫描。

第三步，执行命令行指令：codebuddy analyze-deps --mode=graph。该命令会生成一个 deps-graph.svg 文件，并输出环状依赖警告——此类结构极易导致构建失败或运行时循环 require，需额外警惕。

查看第三方库在项目中的实际调用链

无需逐一打开 node_modules 目录查看源码。CodeBuddy 能够自动定位某个库在当前项目中被哪些文件、哪几行、以何种参数形式调用过，定位精准。

有两种操作方法：

方法一：在 VS Code 中点击左侧 CodeBuddy 图标，进入“依赖洞察”面板，输入要查询的库名（例如 axios、lodash、@nestjs/common），点击“分析该库”。

方法二：在编辑器中右键点击任意 import 语句（如 import { get } from 'axios'），选择“CodeBuddy → Find Usages in Project”。此方法比 IDE 原生查找更精准，因为它会跳过类型声明、测试 mock 和未激活的条件分支。

注意事项：首次分析需等待 AST 解析完成，大型项目可能耗时 10～30 秒；期间请勿关闭面板或切换文件，否则中断后需重新执行。

检测依赖版本兼容性风险

这是许多项目中最容易出问题的地方。当多个子包引用同一个依赖但版本不一致时，TypeScript 类型检查可能通过，但运行时由于模块解析歧义，极易崩溃。CodeBuddy 基于 TS 接口签名进行语义级比对，而非简单的字符串匹配。

操作流程如下：

① 确认每个子包的 tsconfig.json 已启用 "composite": true，且 "types" 指向编译后的声明文件（例如 ./dist/index.d.ts）。

② 在项目根目录执行命令：codebuddy check-versions --impact=type-safe。

③ 输出结果中带有 ⚠️ 标记的条目表明：子包 A 使用 @myorg/utils@2.1.0 导出的接口，而子包 B 依赖 3.0.0 版本，两者的类型定义发生了不兼容的变更。即使 package.json 允许版本共存，TypeScript 构建时也必然报错。

生成依赖树并定位冲突节点

面对 npm ls 或 yarn list 输出的嵌套信息，仅凭肉眼难以快速定位真正的冲突源。CodeBuddy 提供了结构化的可视化能力来破解这一难题。

执行命令：codecli dependency-tree --format=graph。该命令将启动一个本地 HTTP 服务，并自动打开浏览器显示交互式依赖图——节点大小反映引用深度，红色边线标记版本冲突路径，鼠标悬停时可查看具体包名与版本号。

例如，若发现某个基础工具包（如 lodash）被 12 个子包以 5 种不同版本引入，可立即在根目录的 package.json 中添加 resolutions 字段强制统一版本，无需逐个修改子包。这才是高效解决问题的正确方法。