SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场deep-dive-analysis

deep-dive-analysis

编程与开发

查看项目

更新于 10-15 09:52

技能介绍

用途

Deep Dive Analysis 是一个 AI 驱动的系统性代码库分析技能，旨在将机械式结构提取与 Claude 的语义理解相结合，生成全面的代码库文档。与简单的 AST 解析不同，该技能不仅记录代码做了什么（结构、函数、类），还记录它为何存在（业务目的、设计决策）、如何集成（依赖、契约、流程）以及变更的后果（副作用、失败模式）。

适用场景包括：分析不熟悉的代码库、生成解释 WHY 而非仅 WHAT 的文档、识别架构模式与反模式、进行带语义理解的代码审查、新项目上手。

主要能力

机械分析（脚本）：提取代码结构（类、函数、导入）、映射依赖（内部/外部）、查找代码库中的符号使用、跟踪分析进度、按关键性分类文件。

语义分析（Claude AI）：识别架构与设计模式、识别红旗与反模式、追踪数据与控制流、记录契约与不变量、评估质量与可维护性。

文档维护：审查与维护文档（第 8 阶段）、修复失效链接并更新导航索引、按 antirez 标准分析并重写代码注释。

五层理解：WHAT（类、函数、导入，由脚本 AST 完成）、HOW（算法细节、数据流，Claude 首轮）、WHY（业务目的、设计决策，Claude 深度分析）、WHEN（触发器、生命周期、并发，Claude 行为分析）、CONSEQUENCES（副作用、失败模式，Claude 系统思维）。

模式识别：架构模式（Repository、Service、CQRS、Event-Driven）、行为模式（State Machine、Strategy、Observer、Chain）、弹性模式（Circuit Breaker、Retry、Bulkhead、Timeout）、数据模式（DTO、Value Object、Aggregate）、并发模式（Producer-Consumer、Worker Pool）。

红旗识别：架构类（上帝类、循环依赖、泄漏抽象）、可靠性类（吞异常、缺失超时、竞态条件）、安全类（硬编码密钥、SQL 注入、缺失验证）。

语言支持

  • Python（.py、.pyi）：stdlib ast，始终可用
  • Java（.java）：tree-sitter（首选）或 regex
  • JavaScript（.js、.mjs、.cjs、.jsx）：tree-sitter（首选）或 regex
  • TypeScript（.ts、.tsx、.mts、.cts）：tree-sitter（首选）或 regex，额外支持接口、枚举、类型别名
  • SQL（.sql、.ddl、.dml）：regex DDL 提取
  • PL/SQL Oracle（.pks、.pkb、.plsql 等）：regex 提取
  • Rust（.rs）：tree-sitter（首选）或 regex

.sql 文件通过检查 Oracle 特定标记与 PL/SQL 区分；PostgreSQL plpgsql 被正确归类为 SQL。

使用方式

该技能由 /deep-dive-analysis 命令调用，命令在目标目录下的 .deep-dive/ 中自动创建和管理状态。脚本设计为仅用 Python 标准库即可开箱即用，tree-sitter 为可选依赖，可提升 Java/JavaScript/TypeScript 的解析精度：

pip install -r scripts/requirements.txt
# 或
uv pip install -r scripts/requirements.txt

主要命令包括：分析单个文件（analyze_file.py）、检查进度（check_progress.py）、查找符号使用、生成阶段报告、文档健康扫描（doc_review.py scan）、链接校验（validate-links）、对照源码验证（verify）、更新导航索引（update-indexes）、完整文档维护（full-maintenance），以及注释质量分析、扫描、报告和重写（rewrite_comments.py）。

核心原则

该技能生成的文档是项目的绝对且不容置疑的事实来源。任何未经源代码中不可辩驳证据验证的信息都是虚假、不可靠且不可接受的。强制规则包括：绝不未读源码就记录任何内容、绝不假设现有文档或注释准确、始终从实际代码中推导真相、为每个技术声明提供源文件与限定符号名、使用限定符号名而非行号、将无法验证的陈述标记为 [UNVERIFIED - REQUIRES CODE CHECK]。

禁止读取的文件

分析绝不读取或包含敏感文件内容：.env、.env.、credentials.、secrets.、.pem、.key、.p12、.pfx、id_rsa、id_ed25519*、.npmrc、.pypirc、.netrc 或任何包含 API 密钥、密码或令牌的文件。如遇到，仅记录文件存在，绝不引用内容。

文件分类标准

  • 关键（Critical）：处理认证、安全、加密、敏感数据，强制验证
  • 高复杂度（High-Complexity）：>300 LOC、>5 依赖、状态机、异步模式，强制验证
  • 标准（Standard）：常规业务逻辑、数据模型、工具，推荐验证
  • 工具（Utility）：纯函数、辅助函数、常量，可选验证

团队模式

对于 monorepo、多语言仓库或大型代码库，可切换到团队变体 /agent-teams:team-deep-dive <target>。团队命令自动检测分区（工作区、顶层目录或语言集群），每个分区生成三个 deep-dive 工作者分两波运行（第一波=结构；第二波=行为+质量），并合成向后兼容的 .deep-dive/01..07.md 文档集，额外添加 .deep-dive/08-interconnect-map.md 提供全局调用图、契约、不变量和集成热点视图。

限制

该技能的具体收费、价格、平台等信息暂未提供。