## ⚡ 问题陈述：代码库上下文缺口 理解大型、遗留或无文档的代码库是任何工程团队最耗时的工作之一。传统的文档生成工具（如 Sphinx 或 JSDoc）完全依赖开发者手动编写文档字符串。当文档字符串缺失、过期或缺乏架构上下文时，生成的文档在功能上毫无用处。 **AutoDocLM** 通过自主逆向工程你的仓库来解决这个问题。结合抽象语法树（AST）解析、静态依赖提取以及 PageRank 风格的图中心性评分，AutoDocLM 识别系统中最重要的组件。然后，它将这些结构化遥测数据输入高容量的大型语言模型（LLM），原生生成人类可读的、结构精美的 MkDocs 网站。 ## 📖 概述 AutoDocLM 是一个确定性多阶段流水线，旨在评估并记录复杂的软件架构。它提取原始代码，隔离有意义的执行片段，通过图论过滤噪声，并利用外部 LLM 推理提供程序综合深度架构洞察。 与简单的“总结此文件”工具不同，AutoDocLM 测量**结构重要性**： - **语义分块**：文件使用语言原生解析器（Python 的 `ast`、JS/TS 的 `tree-sitter`）被物理分解为原子函数和类，以保留准确的限定符号和装饰器。 - **跨文件调用图**：解析跨文件的函数调用，以建立真正的执行依赖关系，而不仅仅是文件级导入。 - **中心性评分**：通过数学方式丢弃在主导入/调用图中无权的“垃圾”或“工具”文件，从而强制执行严格的上下文限制。 ### 🧪 系统架构（拓扑） 系统运行为一个 14 阶段确定性数据流水线。提取与解析（基于 CPU）与语义合成（基于 API 推理）严格分离。 ``` graph TD subgraph "Phase 1: Ingestion & Parsing" R[Repo Clone/Extract] --> F[File Filter & Classify] F --> C[AST / Tree-sitter Chunking] end subgraph "Phase 2: Graph Theory" C --> S[Static Dependency Auth] S --> IG[Import Graph Extraction] IG --> CG[Cross-File Call Graph] CG --> CS[PageRank Centrality Scoring] end subgraph "Phase 3: Semantic Synthesis" CS --> LLM[LLM Inference Queue] LLM -.-> |"API Request"| Ext[External Provider: nscale/Qwen] Ext -.-> |"Manifest"| LLM end subgraph "Phase 4: Site Generation" LLM --> MD[MkDocs Markdown Generaton] MD --> D[Mermaid Diagram Generation] D --> Output((MkDocs Site Build)) end ``` ### 🔍 核心功能与范围 | 阶段类别 | 描述 | 实现限制 | | :--- | :--- | :--- | | **摄入** | 从 Git URL 克隆或提取本地 `.zip` 文件。 | 受本地存储限制。 | | **分块** | 通过 Python `ast` 完美捕获文档字符串/装饰器。JS/TS 使用二级 Tree-sitter。三级备用正则表达式。 | 支持原生：`.py`、`.js`、`.ts` | | **调用图** | 推断大规模仓库中的父子执行循环，以确定架构边。 | 最大文件数：200（中心性截断） | | **推理范式** | 完全与本地 GPU 分离。通过标准 API URL 和密钥访问外部提供方。仅本地 Ollama 用于确定性嵌入。 | 动态上下文窗口。 | | **输出** | 编译高度美观的 `MkDocs` Material 主题静态站点，可部署到 Git Pages 或 S3。 | - | ### 📐 文档输出与工件 最终生成的站点包括： 1. **仓库概览**：系统功能的执行摘要。 2. **文件夹结构与模块**：每个子系统的分解及其核心职责。 3. **核心文件深度分析**：基于 PageRank 的前 200 个最重要文件，包含详细的输入/输出预期与交互。 4. **交互式图表**： - 高级文件夹依赖关系图。 - 由 Mermaid 生成的低级文件调用图。 ### 1️⃣ 安装 克隆仓库并使用 `uv` 同步依赖。`uv` 是 `pip` 的高速即插即用替代品。 ``` git clone https://github.com/KaushalrajPuwar/AutoDocLM.git cd AutoDocLM uv sync ``` ### 2️⃣ 环境配置 在根目录创建 `.env` 文件以存储推理密钥。 ``` # External API for Inference API_KEY="your-key-here" BASE_URL="https://inference.api.nscale.com/v1" # Local Embeddings (Requires Ollama running locally) DEFAULT_EMBEDDING_MODEL="qwen3-embedding:0.6b" ``` ### 3️⃣ 运行流水线 对公共仓库执行流水线。输出将在 `outputs/` 文件夹中动态生成。 ``` # Analyze an external Git repository uv run python main.py --repo-url https://github.com/username/repo.git # Generate documentation from a local zipped repository uv run python main.py --repo-zip ./my_codebase.zip ``` ## 🤝 项目状态 该项目目前处于积极开发中。 - ✅ **步骤 1：** 仓库摄入与 CLI - ✅ **步骤 2：** 文件过滤 - ✅ **步骤 3：** 文件分类 - ✅ **步骤 4：** AST 与 Tree-sitter 分块 - ✅ **步骤 5：** 静态分析（导入图、跨文件调用、中心性） - ✅ **步骤 6：** 嵌入与 ChromaDB 设置 - ✅ **步骤 7：** LLM 推理 - ⬜ **步骤 8：** 文档撰写 / Markdown 生成 - ⬜ **步骤 9：** Mermaid 图表生成 - ⬜ **步骤 10：** MkDocs 与站点构建

标签：AI 文档生成, AI风险缓解, AST 解析, ChromaDB, DLL 劫持, LLM 推理, LLM评估, Mermaid 图表, MkDocs 生成, NetworkX, Ollama, PageRank, Python, Qwen, 云安全监控, 代码文档化, 图中心性, 大语言模型, 层次推理, 无后门, 架构感知, 模块依赖图, 源码可视化, 特权检测, 确定性管道, 突变策略, 自动化payload嵌入, 自动化文档, 逆向工具, 遗留系统文档, 静态分析