# third-party-dependency-analyzer ## 目标 通用化的第三方依赖分析 Skill，支持多语言项目扫描，输出详细格式报告： - **目录 → 文件 → 三方件引用 → 具体使用功能** **支持的语言：** - Python, C/C++, Java, Go, Rust, Node.js, JavaScript/TypeScript --- ## 核心原则：分析时阅读 → 分析后丢弃 **重要**：分析过程中需要完整阅读文件，但分析完成后立即丢弃代码内容，只保留结构化结果。 ``` 分析流程： 1. 完整阅读文件（需要深度分析隐含依赖） 2. 提取结构化摘要（import、API、用途） 3. 【立即丢弃】代码内容 4. 继续下一个文件 ``` **单文件分析策略：** | 场景 | 操作 | |------|------| | 核心文件（verifier/tuner 等工具） | **必须通读**，发现隐含依赖 | | 测试文件 | 通读，发现 torch_npu 等隐式硬件依赖 | | 辅助文件（脚本、配置） | 快速扫描 import 即可 | **结构化摘要格式（分析后保留）：** ```python # 每个文件的分析结果 - 分析后丢弃代码，只保留这个结构 file_result = { "path": "tools/verifier/tensor_diff.py", "imports": ["import torch", "import pandas as pd", "from tabulate import tabulate"], "api_usages": [ {"line": 103, "api": "torch.gt(ab_sub_abs, tol)", "purpose": "误差阈值判断，超差标记"}, {"line": 138, "api": "torch.argwhere(mask_warn)", "purpose": "找出超差元素索引位置"}, {"line": 163, "api": "torch.topk(tensor, k)", "purpose": "获取 TopK 最大误差值"}, {"line": 50, "api": "pd.DataFrame()", "purpose": "创建差异结果表格"} ], "implicit_deps": [], # 隐式依赖（如 torch_npu） "notes": "核心精度对比工具，torch 用于 tensor 计算，pandas 用于结果表格化" } # 分析完成后【丢弃】代码内容，只保留 file_result ``` --- ## 核心思路 分析第三方依赖的核心思路是 **"多源交叉验证" + "深度引用分析"** : ``` 代码仓 │ ├─► 工具扫描 (depscan / 语言特定工具) │ └── import 语句自动发现 + 功能分析 │ ├─► 依赖声明文件 (requirements.txt, CMakeLists.txt, go.mod, Cargo.toml) │ └── 显式依赖 + 版本信息 │ └─► 源代码引用分析 └── 每个 import/include 的具体使用方式 ``` ### 多语言支持矩阵 | 语言 | 依赖文件 | import 语句 | 三方件特征 | |------|----------|-------------|-----------| | **Python** | requirements.txt, pyproject.toml, setup.py | `import xxx`, `from xxx import` | 非标准库 | | **C/C++** | CMakeLists.txt, cmake/third_party/ | `#include <xxx>`, `#include "xxx"` | 非 `<>`/项目内 | | **Java** | pom.xml, build.gradle | `import xxx.yyy` | 非 java.lang.* | | **Go** | go.mod, go.sum | `import "xxx"`, `import xxx` | 非标准库 | | **Rust** | Cargo.toml, Cargo.lock | `use xxx::yyy`, `extern crate` | 非 prelude | | **Node.js** | package.json, package-lock.json | `require()`, `import from` | 非内置模块 | | **TypeScript** | package.json, tsconfig.json | `import from`, `require()` | @scope/* | --- ## Phase 1: 环境准备 ### Step 1.1: 确定项目类型 ```bash # 识别项目类型（可能有多种语言混合） ls <project_path> # 检查特征文件 [ -f "pyproject.toml" ] && echo "Python" || echo "No Python" [ -f "CMakeLists.txt" ] && echo "C++" || echo "No C++" [ -f "go.mod" ] && echo "Go" || echo "No Go" [ -f "Cargo.toml" ] && echo "Rust" || echo "No Rust" [ -f "package.json" ] && echo "Node.js" || echo "No Node.js" [ -f "pom.xml" ] && echo "Java" || echo "No Java" ``` ### Step 1.2: 安装语言特定工具 ```bash # Python pip install depscan pipdeptree # 其他语言按需安装工具（可选） # Go: go list -m all # Rust: cargo tree # Node.js: npm ls ``` --- ## Phase 2: 依赖声明文件扫描 ### Step 2.1: 扫描所有语言的依赖文件 ```bash # 查找所有语言的依赖文件 find <project_path> -name "requirements*.txt" -type f # Python find <project_path> -name "pyproject.toml" -type f # Python find <project_path> -name "setup.py" -type f # Python find <project_path> -name "CMakeLists.txt" -type f # C++ find <project_path> -name "go.mod" -type f # Go find <project_path> -name "Cargo.toml" -type f # Rust find <project_path> -name "package.json" -type f # Node.js/JS find <project_path> -name "pom.xml" -type f # Java find <project_path> -name "build.gradle" -type f # Java ``` ### Step 2.2: 解析各语言依赖文件 #### Python ```bash cat <project_path>/requirements.txt grep -A20 "dependencies\|\[" <project_path>/pyproject.toml ``` #### C++ (CMake) ```bash cat <project_path>/CMakeLists.txt ls <project_path>/cmake/third_party/ ``` #### Go ```bash cat <project_path>/go.mod ``` #### Rust ```bash cat <project_path>/Cargo.toml ``` #### Node.js ```bash cat <project_path>/package.json | grep -A50 '"dependencies"' cat <project_path>/package.json | grep -A50 '"devDependencies"' ``` #### Java ```bash cat <project_path>/pom.xml | grep -A20 "<dependencies>" cat <project_path>/build.gradle | grep -A20 "dependencies" ``` --- ## Phase 3: 多语言源代码分析 ### 分析策略：通读 → 提取 → 丢弃 **单文件分析流程：** 1. 根据语言类型选择扫描模式 2. 通读核心文件，分析隐含依赖 3. 提取结构化摘要 4. 丢弃代码内容 ### Step 3.1: 按语言扫描 import 语句 #### Python ```bash # 获取所有 Python import（排除标准库和内部模块） grep -rn "^import\|^from" <project_path> --include="*.py" | \ grep -v "^from \." | \ grep -v "^from pypto" | \ grep -v "^import pypto" ``` #### C/C++ ```bash # 获取所有 #include（排除标准库和项目内部） grep -rn "^#include" <project_path> --include="*.cpp" --include="*.h" --include="*.hpp" | \ grep -v "^#include <stdlib" | \ grep -v "^#include <string" | \ grep -v "^#include <vector>" | \ grep -v "^#include <unordered" | \ grep -v "^#include \"tilefwk" | \ grep -v "^#include \"pypto" ``` #### Java ```bash # 获取所有 import（排除 java.lang.*） grep -rn "^import " <project_path> --include="*.java" | \ grep -v "import java.lang" ``` #### Go ```bash # 获取所有 import grep -rn "^import\|^import (" <project_path> --include="*.go" ``` #### Rust ```bash # 获取所有 use 语句（排除 prelude） grep -rn "^use \|^pub use " <project_path> --include="*.rs" ``` #### Node.js / JavaScript / TypeScript ```bash # 获取 require 和 import grep -rn "require(\|require(" <project_path> --include="*.js" --include="*.ts" grep -rn "^import \|^import from" <project_path> --include="*.js" --include="*.ts" ``` ### 分析策略：通读 → 提取 → 丢弃 **单文件分析流程：** ```bash # 1. 先用 grep 找到需要分析的文件列表 grep -l "import torch\|import numpy\|import pandas" tools/verifier/*.py # 2. 逐个通读核心文件 # 分析完成后立即提取摘要，丢弃代码内容 ``` **必须通读的文件类型：** - **核心工具**: tools/verifier/*.py, tools/scripts/tuner/*.py - **测试入口**: tests/st/*.py (发现 torch_npu 等隐式依赖) - **配置文件**: build_ci.py, setup.py **快速扫描即可的文件：** - 纯业务代码（无三方件引用） - 重复模式的测试文件 ### Step 3.1: 通读核心文件，分析隐含依赖 对于核心工具文件，**必须完整阅读**才能发现隐式依赖： ```bash # 读取完整文件进行分析 read_file("tools/verifier/tensor_diff.py") # 完整阅读 read_file("tools/scripts/tuner/xgb_tuner.py") # 完整阅读 read_file("python/tests/st/test_where_onboard.py") # 完整阅读，发现 torch_npu ``` **隐式依赖识别要点：** | 隐式依赖 | 发现方式 | |----------|----------| | `torch_npu` | 测试文件中 `import torch_npu` | | `torch.cuda` | `torch.cuda.set_device()` | | 传递依赖 | 二方件的内部 import | | 可选依赖 | `try: import xxx; except:` | **隐式依赖示例分析：** ```python # 文件：python/tests/st/test_where_onboard.py # 阅读后发现： 隐式依赖: torch_npu 发现依据: import torch_npu (第17行) 影响范围: 昇腾 NPU 测试专用 建议: 由用户提供，无需声明在 requirements.txt 隐式依赖: scipy.optimize 发现依据: xgb_tuner.py 中 from scipy import optimize 影响范围: 超参数优化 建议: 建议添加到 tools/requirements.txt ``` ### Step 3.2: 提取结构化摘要 **通读完成后，立即提取并丢弃：** ```python # 提取摘要 file_summary = { "file": "tools/verifier/tensor_diff.py", "imports": [ "import torch", "import pandas as pd", "from tabulate import tabulate" ], "core_apis": { "torch": [ {"api": "torch.gt()", "lines": "103-107", "purpose": "误差阈值判断"}, {"api": "torch.argwhere()", "lines": "138-147", "purpose": "找超差元素索引"}, {"api": "torch.isnan()", "lines": "155", "purpose": "NaN 检测"}, {"api": "torch.topk()", "lines": "163", "purpose": "TopK 误差"} ], "pandas": [ {"api": "pd.DataFrame()", "lines": "50,77", "purpose": "创建差异表格"} ] }, "implicit_deps": [], "summary": "tensor 精度对比核心工具" } # 【丢弃代码内容，只保留 file_summary】 ``` ### Step 3.3: 功能归类 根据通读分析结果归类： | 功能类型 | 识别模式 | 示例 | |----------|----------|------| | 数值计算 | `np.array()`, `np.dot()`, `np.sum()` | 数组/矩阵运算 | | 深度学习 | `torch.nn`, `torch.tensor`, `model()` | 神经网络 | | 数据分析 | `pd.DataFrame`, `pd.read_csv()` | Pandas 数据处理 | | 科学计算 | `scipy.optimize`, `scipy.stats` | 科学计算 | | 机器学习 | `xgb.train()`, `sklearn.fit()` | ML 模型 | | 可视化 | `plt.plot()`, `matplotlib.pyplot` | 绘图 | | 测试 | `pytest.fixture`, `pytest.mark` | pytest 框架 | | 配置解析 | `yaml.load()`, `yaml.dump()` | YAML 处理 | | 进程管理 | `psutil.Process()`, `setproctitle` | 系统/进程 | | 富文本 | `rich.progress`, `rich.print` | 终端输出 | | 表格 | `tabulate()`, `tabulate(tabular)` | 表格格式化 | ### Step 3.2: 各语言标准库过滤 分析时需要排除标准库： | 语言 | 标准库 | |------|--------| | Python | os, sys, json, typing, dataclasses, collections, ast, inspect, logging, functools, re, pathlib, datetime, unittest, io, copy, struct, threading, multiprocessing, queue, random, time, warnings | | C++ | std::, cstdint, cstring, cassert, cmath, limits, memory, algorithm, vector, string, map, unordered_map, set, list, deque, array, tuple, functional, iostream, fstream, sstream | | Java | java.lang.*, java.util.*, java.io.*, java.nio.*, java.math.* | | Go | fmt, os, io, bufio, bytes, strings, strconv, time, math, log, errors, context, sync, encoding, container, reflect | | Rust | std::, core::, alloc::, std::prelude | | Node.js | assert, buffer, child_process, cluster, crypto, dgram, dns, domain, events, fs, http, https, net, os, path, process, punycode, querystring, readline, repl, stream, string_decoder, sys, timers, tty, url, util, vm, zlib | | JavaScript | assert, buffer, child_process, console, crypto, events, fs, http, https, net, os, path, process, punycode, querystring, stream, string_decoder, sys, timers, tty, url, util, vm, zlib | ### Step 3.3: 通读核心文件，分析隐含依赖 对于核心文件，**必须完整阅读**才能发现隐式依赖： #### Python 隐式依赖识别 | 隐式依赖 | 发现方式 | |----------|----------| | `torch_npu` | 测试文件中 `import torch_npu` | | `torch.cuda` | `torch.cuda.set_device()` | | 传递依赖 | 二方件内部 import | | 可选依赖 | `try: import xxx; except:` | #### C++ 隐式依赖识别 | 隐式依赖 | 发现方式 | |----------|----------| | 模板库 | `#include <boost/xxx>` | | 系统库 | `#include <pthread.h>` | | 第三方头文件 | cmake/third_party/ 目录 | #### Java 隐式依赖识别 | 隐式依赖 | 发现方式 | |----------|----------| | 传递依赖 | Maven/Gradle 传递 | | 测试框架 | JUnit, TestNG | ### Step 3.4: 提取结构化摘要 **通读完成后，立即提取并丢弃：** ```python # 各语言结构化摘要格式 python_result = { "file": "tools/verifier/tensor_diff.py", "imports": ["import torch", "import pandas as pd"], "api_usages": [ {"line": 103, "api": "torch.gt()", "purpose": "误差阈值判断"} ], "implicit_deps": [] } cpp_result = { "file": "framework/src/core/engine.cpp", "includes": ["#include <nlohmann/json.hpp>", "#include <gtest/gtest.h>"], "usages": [ {"line": 15, "api": "json::parse()", "purpose": "解析配置"}, {"line": 42, "api": "EXPECT_EQ()", "purpose": "单元测试断言"} ], "implicit_deps": ["pthread"] # pthread.h 被直接使用 } ``` ### Step 3.4B: 生成文件级依赖表格（附录格式） **分析完成后，生成文件级依赖表格作为报告附录：** ```markdown ### 附录 A: Python 文件级依赖清单 | 文件 | 目录 | 三方件 | API 列表 | 行号 | 主要作用 | |------|------|--------|--------|---------|------|--------| | tensor_diff.py | tools/verifier | torch, pandas | torch.gt(), torch.argwhere(), pd.DataFrame() | 50,103-147 | 精度验证 | | parse_dump_tensors.py | tools/verifier | numpy, pandas | np.array(), pd.read_csv() | 20,80 | 数据解析 | | xgb_tuner.py | tools/scripts/tuner | xgboost, scipy | XGBClassifier(), scipy.optimize | 15,42 | 超参优化 | ### 附录 B: C++ 文件级依赖清单 | 文件 | 目录 | 三方件 | API 列表 | 行号 | 主要作用 | |------|------|--------|---------|------|--------| | ConfigParser.cpp | framework/src | nlohmann_json | json::parse(), json::dump() | 15,42 | 配置解析 | | engine_test.cpp | test/ut | googletest | TEST(), EXPECT_EQ() | 20,35 | 单元测试 | | serializer.cpp | src/core | protobuf | Serialize(), Deserialize() | 18,55 | 数据序列化 | ``` ### Step 3.5: 功能归类 根据各语言使用方式归类： | 功能类型 | Python | C++ | Go | Rust | Node.js | |----------|--------|-----|-----|------|--------| | 数值计算 | numpy | Eigen, armadillo | gonum | ndarray | mathjs | | JSON 解析 | json, pyyaml | nlohmann_json | encoding/json | serde_json | json | | HTTP | requests, httpx | libcurl, cpp-httplib | net/http | reqwest | axios, node-fetch | | 测试 | pytest | gtest, gmock | testing | test, proptest | jest, mocha | | 日志 | logging | spdlog, log4cpp | log | log, tracing | winston, pino | | 并发 | asyncio, threading | std::thread, pthread | goroutine | tokio | worker_threads | --- ## Phase 4: C++ 特殊分析 ### Step 4.1: 扫描 cmake/third_party/ C++ 项目通常在 cmake/third_party/ 中管理第三方库： ```bash ls -la <project_path>/cmake/third_party/ cat <project_path>/cmake/third_party/*/CMakeLists.txt 2>/dev/null || cat <project_path>/cmake/third_party/*/*.cmake ``` ### Step 4.2: 分析 C++ 第三方库 | 三方件 | 版本 | 来源 | 用途 | |--------|------|------|------| | nlohmann_json | 3.11.3 | cmake/third_party/nlohmann_json/ | JSON 解析 | | GoogleTest | 1.14.0 | cmake/third_party/googletest/ | 单元测试 | | libboundscheck | 1.1.16 | cmake/third_party/libboundscheck/ | 安全函数 | --- ## Phase 4B: 构建态依赖 vs 运行态依赖 分类分析 > **重要**：现代项目需要区分两类依赖： > - **构建态依赖 (Build-time)**: 编译/构建时需要，安装后即卸载 > - **运行态依赖 (Runtime)**: 运行时需要，持续存在 ### Step 4B.1: 识别构建工具和构建脚本 ```bash # 构建入口文件 ls <project_path>/build.sh # Shell 构建脚本 ls <project_path>/CMakeLists.txt # CMake 构建 ls <project_path>/setup.py # Python 包构建 ls <project_path>/pyproject.toml # Python 项目配置 ls <project_path>/Makefile # Make 构建 ls <project_path>/pom.xml # Java 构建 ls <project_path>/build.gradle # Gradle 构建 ``` ### Step 4B.2: 扫描构建配置文件 #### 构建依赖声明文件 ```bash # Python 构建依赖（可能分散在多处） cat <project_path>/build.sh | grep -E "python|pip|cmake|gcc|g\+\+" cat <project_path>/docs/build.md | grep -A20 "前置依赖\|编译依赖\|Build" | head -30 cat <project_path>/docs/build.md # 通常包含完整依赖列表 # 查找任何包含版本要求的文档 find <project_path> -name "*.md" -exec grep -l "依赖\|dependence\|requirement" {} \; ``` #### 从文档提取构建依赖 很多项目在 `docs/build.md` 或 `README.md` 中明确列出构建依赖： | 文档位置 | 提取内容 | |----------|----------| | `docs/build.md` | 编译前置依赖 | | `docs/DEVELOP.md` | 开发环境依赖 | | `README.md` | 快速开始依赖 | | `CONTRIBUTING.md` | 贡献指南依赖 | ### Step 4B.3: 构建态依赖分类矩阵 根据构建工具类型自动识别： | 构建工具 | 构建态依赖 | 运行态依赖 | |----------|-----------|------------| | **CMake + gcc/g++** | cmake, gcc, g++, make | openssl, rdma-core | | **setuptools** | setuptools, wheel, pip | - | | **pip/pipenv** | pip, virtualenv | numpy, pandas | | **Maven** | mvn, maven-wrapper | - | | **Gradle** | gradle, gradle-wrapper | - | | **Cargo** | cargo | - | | **npm** | npm, nodejs | - | ### Step 4B.4: 构建脚本依赖扫描 分析 build.sh, build.py 等构建脚本： ```bash # 扫描构建脚本中的工具调用 grep -E "python|pip|cmake|gcc|g\+\+|make" <project_path>/build.sh # 典型构建脚本示例： # build.sh: bash build.sh --pkg # → 需要: bash, cmake, gcc, g++, make, python ``` ### Step 4B.5: Python 脚本依赖分析 如果项目使用 Python 脚本做构建，需要分析脚本的 import： ```bash # 扫描所有 Python 构建/打包脚本 find <project_path>/scripts -name "*.py" -type f # 提取所有 import（只保留第三方） grep -rh "^import\|^from" <project_path>/scripts --include="*.py" | \ sort -u | \ grep -v "^[from ]*import os$\|import sys\|import subprocess\|import logging\|import argparse\|import typing\|import collections\|import datetime\|import pathlib\|import functools\|import itertools\|import re\|import glob\|import shutil\|import hashlib\|import struct\|import xml\|import traceback\|import csv\|import binascii\|import ctypes\|import textwrap\|from typing\|from collections\|from datetime\|from functools\|from itertools\|from operator\|from pathlib" ``` **Python 标准库（无需安装）：** ``` os, sys, subprocess, logging, argparse, typing, collections, datetime, pathlib, functools, itertools, re, glob, shutil, hashlib, struct, xml.etree, traceback, csv, binascii, ctypes, textwrap, copy, inspect, io, signal, socket, tempfile, urllib, base64, configparser, gzip, zipfile, encodings ``` ### Step 4B.6: 文档依赖提取模板 从 `docs/build.md` 提取编译依赖的标准模式： ```markdown # 从 docs/build.md 提取 ### 前置依赖 / 编译依赖 / Build Dependencies - python >= 3.7.0 # → Python 解释器 - pip3 >= 20.3.0 # → pip 包管理器 - setuptools >= 45.0.0 # → Python 包构建 - wheel >= 0.34.0 # → Python 包格式 - gcc & g++ : 7.3.0 至 13.3.x # → C++ 编译器 - cmake >= 3.16.0 # → 构建系统 - pkg-config >= 0.29.1 # → 库配置工具 ``` ### Step 4B.7: 分类结果输出模板 ```markdown ## 依赖分类总结 ### 1. 构建态依赖 (Build-time Dependencies) | 依赖 | 版本要求 | 用途 | 来源 | |------|----------|------|------| | **python** | >= 3.7.0 | 构建脚本解释器 | docs/build.md | | **pip3** | >= 20.3.0 | 包管理 | docs/build.md | | **setuptools** | >= 45.0.0 | Python 包构建 | docs/build.md | | **wheel** | >= 0.34.0 | Python 包格式 | docs/build.md | | **gcc/g++** | 7.3.0 - 13.3.x | C++ 编译器 | docs/build.md | | **cmake** | >= 3.16.0 | 构建系统 | docs/build.md | | **pkg-config** | >= 0.29.1 | 库配置工具 | docs/build.md | ### 2. 运行态依赖 (Runtime Dependencies) | 依赖 | 版本 | 用途 | 来源 | |------|------|------|------| | **openssl** | 3.0.9 | TLS 加密 | cmake/third_party/ | | **rdma-core** | - | RDMA 通信 | 系统库 | ### 3. Python 运行时依赖（仅标准库） 项目 Python 脚本仅使用标准库，无第三方依赖： - os, sys, subprocess, logging, argparse, hashlib, struct, xml.etree, typing ``` --- ## Phase 4C: 源码级依赖图谱构建（核心） > **目标**：建立 仓 → 文件夹 → 文件 → 三方件 → 功能 → 使用次数 的完整图谱 ### Step 4C.1: 扫描所有 import/include 语句 ```bash # Python: 获取所有 import 语句（排除标准库） grep -rn "^import \|^from" <project_path> --include="*.py" | \ grep -v "^from \." | \ grep -v "^[from ]*import os$\|import sys\|import subprocess\|import logging\|import argparse\|import typing\|import collections\|import datetime\|import pathlib\|import functools\|import itertools\|import re\|import glob\|import shutil\|import hashlib\|import struct\|import xml\|import traceback\|import csv\|import binascii\|import ctypes\|import textwrap\|from typing\|from collections\|from datetime\|from functools\|from itertools\|from operator\|from pathlib" | \ sort -u # C++: 【重要改进】使用正向匹配 + cmake/third_party 目录扫描 # 方法1: 扫描 cmake/third_party/ 中声明的库 ls <project_path>/cmake/third_party/*.cmake | xargs -I {} basename {} .cmake # 方法2: 扫描第三方头文件（包含项目内部 include 目录） grep -rn "^#include" <project_path> --include="*.cpp" --include="*.h" --include="*.hpp" | \ grep -E "#include.*(eigen|abseil|boost|gtest|google|protobuf|openssl|rdma|json|nlohmann)" | \ sort -u # 方法3: 扫描项目无法识别的头文件（需要结合 cmake/third_party/） # 常见第三方库头文件模式： # - "utils/eigen_*.h" → eigen # - "utils/gtest/*.h" → googletest # - <gtest/gtest.h> → googletest # - "absl/*.h" → abseil grep -rn "^#include" <project_path> --include="*.cpp" --include="*.h" --include="*.hpp" | \ grep -v "^#include <stdlib" | \ grep -v "^#include <string" | \ grep -v "^#include <vector>" | \ grep -v "^#include <unordered" | \ grep -v "^#include <memory>" | \ grep -v "^#include <algorithm>" | \ grep -v "^#include <map>" | \ grep -v "^#include <set>" | \ grep -v "^#include <list>" | \ grep -v "^#include <array>" | \ grep -v "^#include <deque>" | \ grep -v "^#include <stack>" | \ grep -v "^#include <queue>" | \ grep -v "^#include <bits/" | \ grep -v "^#include <cstdint" | \ grep -v "^#include <climits" | \ grep -v "^#include <cstring" | \ grep -v "^#include <cwchar" | \ grep -v "^#include <cassert" | \ grep -v "^#include <cctype" | \ grep -v "^#include <cerrno" | \ grep -v "^#include <cfenv" | \ grep -v "^#include <cmath" | \ grep -v "^#include <csignal" | \ grep -v "^#include <cstdio" | \ grep -v "^#include <ctime" | \ grep -v "^#include <cstdlib" | \ grep -v "^#include <new>" | \ grep -v "^#include <typeinfo" | \ grep -v "^#include <exception" | \ grep -v "^#include <initializer" | \ grep -v "^#include <functional" | \ grep -v "^#include <atomic>" | \ grep -v "^#include <thread>" | \ grep -v "^#include <mutex>" | \ grep -v "^#include <condition" | \ grep -v "^#include <chrono>" | \ grep -v "^#include <ratio>" | \ grep -v "^#include <regex>" | \ grep -v "^#include <locale>" | \ grep -v "^#include <codecs" | \ grep -v "^#include <sstream" | \ grep -v "^#include <iomanip" | \ grep -v "^#include <iosfwd" | \ grep -v "^#include <iostream" | \ grep -v "^#include <limits>" | \ grep -v "^#include <optional" | \ grep -v "^#include <variant" | \ grep -v "^#include <any>" | \ grep -v "^#include <tuple>" | \ grep -v "^#include <utility>" | \ grep -v "^#include <random>" | \ grep -v "^#include <fstream>" | \ grep -v "^#include <sstream>" | \ grep -v "^#include <stdint.h>" | \ # 【关键】不要排除项目内部目录，只排除真正的项目代码前缀 # grep -v "include \"log/" | \ # 这些可能是真实的第三方依赖 # grep -v "include \"kernel_" | \ # grep -v "include \"register/" | \ # grep -v "include \"opdev/" | \ sort -u ``` ### Step 4C.1B: 结合 cmake/third_party/ 扫描 > **重要**：很多第三方库通过 CMake 引入，需要交叉验证 ```bash # 1. 列出所有 cmake/third_party/*.cmake 文件 ls <project_path>/cmake/third_party/ # 2. 从 CMakeLists.txt 扫描 find_package grep -rn "find_package\|include.* third_party" <project_path>/CMakeLists.txt # 3. 从官方声明文件扫描 cat <project_path>/Third_Party_Open_Source_Software_List.yaml # 4. 交叉验证：cmake 声明的库是否在源码中被引用 # 如果 cmake 声明但源码不引用，可能是传递依赖或可选组件 ``` ### Step 4C.2: 按文件夹聚合统计 ```bash # Python: 按文件夹统计 import 次数 for dir in $(ls -d */); do count=$(grep -rh "^import \|^from" "$dir" --include="*.py" 2>/dev/null | wc -l) echo "$dir: $count" done # C++: 按文件夹统计 #include 次数 for dir in $(ls -d */); do count=$(grep -rh "^#include" "$dir" --include="*.cpp" --include="*.h" 2>/dev/null | wc -l) echo "$dir: $count" done ``` ### Step 4C.3: 核心文件深度分析 对核心文件进行深度分析，提取： - 具体使用的 API - 在项目中的功能 - 使用频率 ```bash # 示例：分析单个文件的依赖 read_file("tools/tuner/xgb_tuner.py") # 提取： # - import xgboost: 第10行, XGBClassifier, 模型训练 # - import scipy: 第15行, scipy.optimize, 超参数优化 # - from sklearn: 第20行, cross_val_score, 模型评估 ``` ### Step 4C.4: 生成依赖图谱 **模板**： ```markdown ### Python 依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | tools/verifier | tensor_diff.py | torch, pandas, tabulate | tensor计算/表格化 | 15+ | 精度验证 | | tools/scripts/tuner | xgb_tuner.py | xgboost, scipy | 超参优化 | 8+ | 模型调优 | | tests/st | test_*.py | torch_npu | NPU测试 | 20+ | 功能测试 | ### C++ 依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | framework/src | ConfigParser.cpp | nlohmann_json | 配置解析 | 5+ | 配置文件读取 | | test/ut | unit_test.cpp | googletest | 单元测试 | 100+ | 自动化测试 | | src/core | Serializer.cpp | protobuf | 数据序列化 | 3+ | 数据传输 | ### 依赖图谱统计汇总 | 三方件 | 引用文件数 | 使用次数 | 主要功能领域 | |--------|-----------|---------|-------------| | numpy | 15 | 45+ | 数值计算 | | pandas | 8 | 20+ | 数据处理 | | torch | 25 | 80+ | 深度学习 | | nlohmann_json | 12 | 35+ | 配置解析 | | googletest | 50 | 200+ | 单元测试 | ``` ### Step 4C.5: 交叉验证与差异分析 > **重要**：官方声明 vs 源码引用可能存在差异，需要分析原因 ```bash # 1. 官方声明的库列表 cat <project_path>/Third_Party_Open_Source_Software_List.yaml # 2. cmake/third_party 声明的库 ls <project_path>/cmake/third_party/*.cmake # 3. 源码中实际引用的库 grep -rn "#include.*eigen\|#include.*abseil\|#include.*gtest" <project_path> ``` ### Step 4C.6: 差异分析模板 | 三方件 | 官方声明 | 源码引用 | 差异原因 | |--------|----------|----------|----------| | **eigen** | run (5.0.0) | 63 次 | ✅ 真实使用（半精度计算） | | **abseil-cpp** | plugin | 0 次 | ❌ 未直接使用（CMake 引入） | | **makeself** | build | - | 构建工具，不在源码中 | | **json** | run | - | JSON 解析 | **差异原因分析**： | 类型 | 说明 | |------|------| | **传递依赖** | 第三方库引入，非直接使用 | | **可选组件** | 声明但当前未启用 | | **构建工具** | makeself 等构建时使用，不在源码 | | **CMake 引入** | 通过 find_package 引入，未直接 include | | **隐藏依赖** | 二方件 CANN SDK 引入 | --- ## Phase 5: 版本信息获取 ### Step 5.1: 从依赖文件获取版本 ```bash # Python grep -E "^[a-zA-Z]" <project_path>/requirements.txt | grep -v "^#" # C++ grep -E "project.*version" <project_path>/CMakeLists.txt # Go grep "require" <project_path>/go.mod # Rust grep -A2 "\[dependencies\]" <project_path>/Cargo.toml ``` ### Step 5.2: 常用包版本映射表 | 语言 | 包名 | 版本说明 | |------|------|----------| | Python | numpy | >=1.21 | | Python | torch | 用户环境提供 | | Python | pandas | >=1.3 | | Python | pytest | >=7.0 | | Python | scipy | 随 numpy 版本 | | C++ | nlohmann_json | 3.11.3 | | C++ | googletest | 1.14.0 | | rich | - | >=10.0 通常 | | pyyaml | - | >=6.0 通常 | --- ## Phase 6: 报告生成 ### 输出格式：按语言分层结构 ```markdown # {项目名} 第三方依赖分析报告 ## 项目概述 - **项目类型**: Python/C++ 混合 - **支持语言**: Python, C++, Go, Rust, Node.js, Java, JavaScript/TypeScript - **主要目录**: python/, tools/, framework/ - **分析时间**: {date} --- ## 1. 按语言依赖汇总 + 按状态分类 ### 1.1 构建态依赖 (Build-time) | 依赖 | 版本 | 用途 | 来源 | |------|------|------|------| | python | >= 3.7.0 | 构建脚本解释器 | docs/build.md | | cmake | >= 3.16.0 | 构建系统 | docs/build.md | | gcc/g++ | 7.3.0 - 13.3.x | C++ 编译器 | docs/build.md | ### 1.2 运行态依赖 (Runtime) | 依赖 | 版本 | 用途 | 来源 | |------|------|------|------| | openssl | 3.0.9 | TLS 加密 | cmake/third_party/ | | CANN 软件 | >= 8.0.0 | AI 框架基础 | 系统依赖 | ### 1.3 Python 依赖 | 三方件 | 版本 | 引用文件数 | 主要功能 | |--------|------|-----------|---------| | pytest | >=7.0 | 35+ | 测试框架 | | numpy | >=1.21 | 15+ | 数值计算 | ### 1.4 C++ 依赖 | 三方件 | 版本 | 来源 | 用途 | |--------|------|------|------| | nlohmann_json | 3.11.3 | cmake/third_party/ | JSON 解析 | | GoogleTest | 1.14.0 | cmake/third_party/ | 单元测试 | ### 1.5 其他语言依赖 （按项目实际包含的语言添加） --- ## 2. 文件级依赖详情（依赖图谱） > **核心**：建立仓 → 文件夹 → 文件 → 三方件 → 功能 → 使用次数 的完整图谱 ### 2.1 Python 文件依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | tools/verifier | tensor_diff.py | torch, pandas, tabulate | tensor计算/表格化 | 15+ | 精度验证 | | tools/scripts/tuner | xgb_tuner.py | xgboost, scipy | 超参优化 | 8+ | 模型调优 | | tests/st | test_*.py | torch_npu | NPU测试 | 20+ | 功能测试 | ### 2.2 C++ 文件依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | framework/src | ConfigParser.cpp | nlohmann_json | 配置解析 | 5+ | 配置文件读取 | | test/ut | unit_test.cpp | googletest | 单元测试 | 100+ | 自动化测试 | | src/core | Serializer.cpp | protobuf | 数据序列化 | 3+ | 数据传输 | ### 2.3 依赖图谱统计模板 ```markdown ### Python 依赖图谱汇总 | 三方件 | 引用文件数 | 使用次数 | 主要功能领域 | |--------|-----------|---------|-------------| | numpy | 15 | 45+ | 数值计算 | | pandas | 8 | 20+ | 数据处理 | | torch | 25 | 80+ | 深度学习 | ### C++ 依赖图谱汇总 | 三方件 | 引用文件数 | 使用次数 | 主要功能领域 | |--------|-----------|---------|-------------| | nlohmann_json | 12 | 35+ | 配置解析 | | googletest | 50 | 200+ | 单元测试 | | protobuf | 8 | 15+ | 数据序列化 | ### 隐式依赖发现 从代码分析中发现的隐式依赖： | 三方件 | 发现位置 | 隐式程度 | 建议处理 | |--------|----------|---------|----------| | torch_npu | tests/st/*.py | 高（硬件特定） | 由运行环境提供 | | acl | src/*.cpp | 高（CANN SDK） | 由 CANN 提供 | ``` --- ## 3. 文件级依赖详情 ### 3.1 Python 文件 ### tools/verifier/tensor_diff.py | 三方件引用 | 行号 | 具体使用方式 | 在本项目中的作用 | |-----------|------|-------------|------------------| | `import torch` | 15 | `torch.dtype` | 指定计算精度类型 | | `import torch` | 103 | `torch.gt()` | 误差阈值判断 | | `import pandas as pd` | 50 | `pd.DataFrame()` | 创建差异数据表格 | ### 2.2 C++ 文件 ### framework/src/core/ConfigParser.cpp | 三方件引用 | 行号 | 具体使用方式 | 在本项目中的作用 | |-----------|------|-------------|------------------| | `#include <nlohmann/json.hpp>` | 15 | `json::parse()` | 解析配置文件 | | `#include <gtest/gtest.h>` | 20 | `TEST()` | 单元测试 | --- ## 3. 隐式依赖（按语言） ### 3.1 Python 隐式依赖 | 三方件 | 发现位置 | 使用方式 | 作用 | 建议 | |--------|----------|---------|------|------| | torch_npu | tests/st/*.py | `import torch_npu` | 昇腾 NPU 特定 API | 由用户提供 | | scipy | tuner/*.py | `scipy.optimize` | 超参数优化 | 建议添加 | ### 3.2 C++ 隐式依赖 | 三方件 | 发现位置 | 使用方式 | 作用 | 建议 | |--------|----------|---------|------|------| | pthread | framework/src/ | `#include <pthread.h>` | POSIX 线程 | 系统提供 | --- ## 4. 依赖关系图 ``` Python ├─ tools/verifier/ │ ├─ tensor_diff.py → torch, pandas, tabulate │ └─ parse_dump_tensors.py → numpy, pandas └─ tools/scripts/tuner/ └─ xgb_tuner.py → xgboost, scipy C++ ├─ framework/src/ │ ├─ ConfigParser.cpp → nlohmann_json │ └─ UnitTests.cpp → GoogleTest, gmock └─ cmake/third_party/ └─ nlohmann_json/, googletest/, libboundscheck/ ``` --- ## 5. 多语言标准库过滤说明 分析时已过滤以下标准库： | 语言 | 已过滤标准库 | |------|-------------| | Python | os, sys, json, typing, collections, ast, logging, functools, re, datetime, unittest | | C++ | std::, cstdint, cstring, vector, string, map, algorithm, memory | | Java | java.lang.*, java.util.* | | Go | fmt, os, io, strings, time, math, log, errors | | Rust | std::, core::, alloc:: | --- ## 6. 依赖图谱（附录） ### 6.1 Python 依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | tools/verifier | tensor_diff.py | torch, pandas, tabulate | tensor计算/表格化 | 15+ | 精度验证 | | tools/scripts/tuner | xgb_tuner.py | xgboost, scipy | 超参优化 | 8+ | 模型调优 | ### 6.2 C++ 依赖图谱 | 文件夹 | 文件 | 引用三方件 | 功能用途 | 次数 | 主要作用 | |--------|------|------------|----------|--------|------| | framework/src | ConfigParser.cpp | nlohmann_json | 配置解析 | 5+ | 配置文件读取 | | test/ut | unit_test.cpp | googletest | 单元测试 | 100+ | 自动化测试 | ### 6.3 依赖图谱统计汇总 | 三方件 | 引用文件数 | 使用次数 | 主要功能领域 | |--------|-----------|---------|-------------| | numpy | 15 | 45+ | 数值计算 | | pandas | 8 | 20+ | 数据处理 | | torch | 25 | 80+ | 深度学习 | | nlohmann_json | 12 | 35+ | 配置解析 | | googletest | 50 | 200+ | 单元测试 | | eigen | 10 | 63+ | 半精度计算 (Eigen::half) | **【重要】差异分析示例**： | 三方件 | 官方声明 | 源码引用 | 差异原因 | |--------|----------|----------|----------| | eigen | run (5.0.0) | 63 次 | ✅ 真实使用（半精度计算） | | abseil-cpp | plugin | 0 次 | ❌ 未直接使用（CMake 引入） | ### 6.4 基于图谱的依赖分类 根据依赖图谱，对依赖进行最终分类： | 分类 | 判断标准 | 示例 | |------|---------|------| | **构建态** | 构建脚本、编译工具、仅开发时需要 | cmake, gcc, setuptools | | **运行态** | 运行时必须存在 | numpy, openssl, eigen | | **测试态** | 仅测试时需要 | googletest, pytest | | **可选** | try/except 捕获的导入 | torch_npu, acl | --- ## 常用命令速查 ### Python ```bash pip install depscan pipdeptree depscan ./python --no-save grep -rn "^import\|^from" ./python --include="*.py" | grep -v "^from \." ``` ### C++ ```bash ls cmake/third_party/ grep -rn "^#include" ./framework --include="*.cpp" --include="*.h" ``` ### 多语言混合项目 ```bash # 快速识别项目语言 find . -maxdepth 2 \( -name "*.py" -o -name "*.cpp" -o -name "*.go" -o -name "*.rs" \) | head -10 # 查找所有依赖文件 find . \( -name "requirements*.txt" -o -name "pyproject.toml" -o -name "CMakeLists.txt" -o -name "go.mod" -o -name "Cargo.toml" -o -name "package.json" \) ``` --- ## 输出字段说明 | 字段 | 说明 | |------|------| | 目录 | 三方件被引用的顶级目录 | | 文件 | 具体引用的文件路径 | | 三方件引用 | 原始 import/include 语句 | | 行号 | import 语句所在行号 | | 具体使用方式 | 代码中调用的具体 API | | 在本项目中的作用 | 该 API 在本项目中的具体功能 | --- ## 常见三方件功能映射表 ### Python #### pytest | 使用方式 | 作用 | |----------|------| | `@pytest.fixture` | 测试数据准备 | | `@pytest.mark.parametrize` | 测试参数化 | | `pytest.raises()` | 异常测试 | #### numpy | 使用方式 | 作用 | |----------|------| | `np.array()` | 创建数组 | | `np.random.rand()` | 生成随机测试数据 | | `np.allclose()` | 数值对比 | | `np.mean()` / `np.sum()` | 统计计算 | #### torch | 使用方式 | 作用 | |----------|------| | `torch.tensor()` | 创建 tensor | | `torch.randn()` | 随机 tensor | | `.npu()` / `.cuda()` | 设备迁移 | | `torch.gt()` | 数值比较 | #### pandas | 使用方式 | 作用 | |----------|------| | `pd.DataFrame()` | 创建数据框 | | `pd.read_csv()` | 读取数据 | ### C++ #### nlohmann_json | 使用方式 | 作用 | |----------|------| | `json::parse()` | 解析 JSON | | `json::dump()` | 序列化 JSON | #### GoogleTest | 使用方式 | 作用 | |----------|------| | `TEST()` | 定义测试用例 | | `EXPECT_EQ()` | 断言相等 | | `ASSERT_TRUE()` | 断言为真 | --- 每个 Phase 完成后，确认以下清理： ### Phase 1 (环境准备) - [ ] 工具已安装（不需要保留安装过程） - [ ] 项目结构已记录（不需要保留目录列表） ### Phase 2 (依赖声明文件扫描) - [ ] 所有语言的依赖文件已扫描 - [ ] 包名列表已记录 - [ ] C++ cmake/third_party/ 已检查 - [ ] 不需要重新扫描 ### Phase 3 (深度引用分析) **← 重点** - [ ] 核心文件已通读（发现隐式依赖） - [ ] 每个文件的 import 摘要已记录 - [ ] 每个文件的 API 使用已记录 - [ ] 隐式依赖已识别（如 torch_npu） - [ ] **代码内容已丢弃**（只保留结构化摘要） - [ ] 文件级汇总已完成 ### Phase 4 (C++ 特殊分析) - [ ] cmake/third_party/ 第三方库已记录 - [ ] #include 语句已扫描 ### Phase 5 (版本信息) - [ ] 版本信息已记录 - [ ] 不需要保留依赖文件内容 ### Phase 6 (报告生成) - [ ] 报告已生成 - [ ] 过程数据已清理 - [ ] 只保留最终报告 ### 多语言扫描检查 | 语言 | 检查项 | |------|--------| | Python | `import xxx`, `from xxx import` | | C++ | `#include <xxx>`, cmake/third_party/ | | Java | `import xxx.yyy` | | Go | `import "xxx"` | | Rust | `use xxx::yyy` | | Node.js | `require()`, `import from` | ### 隐式依赖识别检查 分析每个核心文件时，必须检查： | 检查项 | 隐式依赖 | 发现位置 | |--------|----------|----------| | [ ] 昇腾 NPU | `import torch_npu` | tests/st/*.py | | [ ] CUDA | `torch.cuda.set_device()` | GPU 测试 | | [ ] scipy | `from scipy import optimize` | tuner/*.py | | [ ] rich | `rich.progress` | dump_tensor/*.py | | [ ] ml_dtypes | `ml_dtypes.float8_*` | verifier/*.py | **发现隐式依赖后：** 1. 记录到 implicit_deps 列表 2. 判断是否需要添加到 requirements.txt 3. 丢弃代码内容 --- ## 快速扫描模板 ### 核心文件必须通读 **使用 subagent 并行通读核心文件：** ```bash # 每个 subagent 通读文件 → 提取摘要 → 丢弃代码 /task "通读 tools/verifier/tensor_diff.py，分析 torch/pandas/tabulate 的使用方式和作用，返回结构化摘要" /task "通读 tools/verifier/parse_dump_tensors.py，分析 numpy 的使用方式和作用，返回结构化摘要" /task "通读 tools/verifier/run_float_diff.py，分析 torch/numpy/matplotlib 的使用方式和作用，返回结构化摘要" /task "通读 tools/scripts/tuner/xgb_tuner.py，分析 xgboost/scipy 的使用方式和作用，返回结构化摘要" /task "通读 tools/scripts/tuner/tuner.py，分析 scipy 的使用方式和作用，返回结构化摘要" /task "通读 python/tests/st/test_where_onboard.py，识别所有隐式依赖（特别是 torch_npu），返回结构化摘要" ``` ### 返回格式要求 每个 subagent 只返回结构化摘要，不保留代码内容： ```json { "file": "tensor_diff.py", "imports": ["torch", "pandas", "tabulate"], "core_apis": { "torch": [ {"api": "torch.gt()", "lines": "103-107", "purpose": "误差阈值判断"}, {"api": "torch.argwhere()", "lines": "138-147", "purpose": "找超差元素索引"} ] }, "implicit_deps": [], "summary": "tensor 精度对比核心工具" } ``` ### 测试文件隐式依赖扫描 测试文件是发现隐式依赖的关键来源： ```bash # 扫描所有测试文件中的硬件相关 import grep -rn "torch_npu\|torch\.cuda\|torch\.npu" python/tests/ --include="*.py" /task "通读所有 tests/st/*.py，识别 torch_npu 等硬件隐式依赖，返回隐式依赖清单" ```