jimmc414/claude-repo-xray

# repo-xray 解决 AI 编码助手的冷启动问题。两个阶段：快速确定性扫描，然后是可选的 LLM 驱动的深度调查。 ``` Phase 1 — X-Ray: python xray.py /path/to/project # 5 seconds, ~15K tokens, zero dependencies Phase 2 — Deep Crawl: /deep-crawl full # 30-70 min, ~60K words, every claim cited ``` **第一阶段（X-Ray）** 在几秒内运行，不消耗 API 调用或推理 token。它生成一个精简的、确定性的代码库地图——骨架、依赖图、复杂性热点、git 风险、副作用——可以容纳在单个上下文窗口中。相同的输入，相同的输出，每次都是。这对于大多数任务已经足够：AI 知道要注意哪里，以及要小心什么。 **第二阶段（深度爬取）** 是可选的第二阶段，当您需要全面理解时使用。它使用 X-Ray 输出作为地图，然后生成并行 LLM 代理来读取实际源代码、追踪请求路径、验证信号，并用 `file:line` 证据引用记录它们发现的一切。结果是一份完整的 onboarding 文档，会在未来的每个 AI 会话中自动加载。运行一次，受益数月。 大多数用户只需要第一阶段。第二阶段在代码库需要多个 AI 会话长期工作时才能收回成本——生成成本分摊到每个读取文档的未来会话中。 ### 示例：Kosmos（802 个文件，约 2.4M tokens） [Kosmos](https://github.com/jimmc414/Kosmos) 是一个 AI Scientist 平台——802 个 Python 文件，总计超过 240 万 tokens。对于任何 AI 上下文窗口来说都太大了。以下是每个阶段产生的结果： - **第一阶段输出**：[X-Ray 扫描](examples/KOSMOS_XRAY.md) — 约 15K tokens 的确定性地图。骨架、依赖图、复杂性热点、git 风险、副作用、安全问题、静默失败。几秒内生成。 - **第二阶段输出**：[深度爬取 onboarding 文档](examples/KOSMOS_DEEP_ONBOARD.md) — 约 58K 字的经验证行为文档，包含 444 个 `[FACT]` 引用。关键路径、模块分析、陷阱、变更手册、错误处理——fresh AI 会话在这个代码库中自信工作所需的一切。验证：12/12 标准问题，10/10 抽查，对抗性测试通过。 ### 使用输出 生成后，将输出文件附加到您的 AI 会话提示中。对于 Kosmos，那就是 [KOSMOS_XRAY.md](examples/KOSMOS_XRAY.md) 和 [KOSMOS_DEEP_ONBOARD.md](examples/KOSMOS_DEEP_ONBOARD.md)。以下是它的样子： ``` I'm providing two reference documents for the Kosmos codebase: 1. KOSMOS_XRAY.md — A deterministic structural scan (architecture, dependencies, complexity hotspots, risk signals) 2. KOSMOS_DEEP_ONBOARD.md — A comprehensive onboarding document with verified code citations covering critical paths, module behavior, error handling, gotchas, and change playbooks Use these documents to orient yourself before reading or modifying any code. When the documents reference specific files and line numbers, trust those as your starting points but verify current state since code may have changed since generation. The codebase is located at: /path/to/Kosmos My task: [describe what you want the AI to do] ``` 如果您只运行了第一阶段，X-Ray 扫描本身就足以完成大多数定向任务。第二阶段对于开放式工作、复杂修改或当多个 AI 会话将在同一代码库上长期工作时最有价值。示例文件夹中包含可重用的[示例提示](examples/sample_prompt.md)。 ## 问题 当一个新的 AI 代理进入一个不熟悉的代码库时，它会做两件事之一：随机读取文件并在实现细节上浪费上下文，或者什么都不读然后猜测。两者都会产生自信的、看似合理但错误的建议。 成本不仅仅是糟糕的建议本身——而是复合效应。会话早期的错误心智模型会影响每一个后续决策。一个错误识别架构风格的代理会写出技术上能工作但与现有设计冲突的代码。一个不知道共享缓存的代理会引入并发问题。一个不知道哪些文件是生成的代理会浪费一半上下文来读取没有人写过的代码。 代码库可能跨越 200 万 tokens。上下文窗口容纳 20 万。代理无法读取所有内容，但必须理解架构才能知道要读什么。这就是冷启动问题。 ## 两个阶段 **第一阶段：X-Ray**（确定性扫描器） | | | |---|---| | 速度 | 500 个文件 5 秒 | | 输出 | 约 15K tokens（可配置：2K-15K）| | 依赖 | 无。仅 Python 3.8+ 标准库。| | 确定性 | 相同输入每次产生相同输出 | | 提取内容 | 49+ 信号：AST 骨架、导入层、复杂性、git 风险、副作用、调用图、中心模块、安全问题、静默失败、异步违规、SQL 模式、弃用标记、爆炸半径、HTTP 路由、装饰器详情、资源泄漏、不安全反序列化、魔法方法、导入时副作用 | | 无法做到 | 语义读取代码。它知道一个函数 CC=25 有 8 个调用者。不知道为什么。| **第二阶段：深度爬取**（LLM 驱动的调查，可选） | | | |---|---| | 速度 | 30-70 分钟（并行子代理）| | 输出 | 约 60K 字，17 个部分，每个声明都有 `file:line` 引用 | | 依赖 | Claude Code 支持子代理（Opus/Sonnet）| | 确定性 | 非确定性。两次运行产生不同文档。价值在于调查。| | 做什么 | 端到端追踪请求路径，读取模块源代码，记录错误处理，发现陷阱，构建变更手册 | | 前置条件 | X-Ray 输出（第一阶段必须先运行）| 扫描器告诉您一个函数的圈复杂度是 25，有 8 个模块调用它。它无法告诉您这个函数静默吞掉超时错误，或者更改它的返回类型会破坏三个模块之外的未文档化集成。只有读取代码才能告诉您这些。深度爬取会读取代码。 ## 快速开始 ``` git clone https://github.com/jimmc414/claude-repo-xray.git cd claude-repo-xray # Layer 1: 扫描任何 Python 项目 python xray.py /path/to/project # Full analysis to stdout python xray.py /path/to/project --output both --out /tmp/xray # Markdown + JSON to files python xray.py /path/to/project --preset minimal # ~2K tokens, quick survey # Layer 2: 深度爬取（需要 Claude Code） cd /path/to/project python /path/to/xray.py . --output both --out /tmp/xray # Scanner first /deep-crawl full # Then exhaustive investigation ``` 要求：Python 3.8+。无需 `pip install`。第二层需要 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)。 ## 第一层：扫描器 ### 提取内容 | 维度 | 信号 | |-----------|---------| | **结构** | 骨架、tokens、文件、接口、类层次结构 | | **架构** | 导入层、依赖距离、循环依赖、中心模块、孤立模块 | | **复杂性** | 每个函数的圈复杂度、热点、异步模式 | | **行为** | 副作用（DB、API、文件、子进程）、跨模块调用图 | | **历史** | 风险分数、共修改耦合、新鲜度、作者专业度 | | **上下文** | CLI 参数、环境变量、Pydantic 验证器、linter 规则 | | **安全** | 安全问题（exec/eval/compile）、不安全反序列化（pickle/yaml/marshal）、静默失败（bare except、except-pass）、资源泄漏（open without with）、危险文件 | | **质量** | 异步/同步违规、SQL 字符串字面量、弃用标记、环境变量回退 | | **影响** | 爆炸半径（每个模块的传递依赖影响）、HTTP 路由检测（方法、路径、处理器、副作用）| | **细节** | 装饰器参数（位置+关键字）、魔法方法（is_dunder 标志）、导入时副作用 | 一个 10K token 的源文件通常产生 500 token 的骨架。在保留每个公共接口和类型注解的同时减少了 95%。 ### 预设 | 预设 | Tokens | 信号 | 用例 | |--------|--------|---------|----------| | `minimal` | ~2K | 骨架+导入 | 快速侦察 | | `standard` | ~8K | 8 次分析 | 平衡覆盖 | | （默认）| ~15K | 全部 17 次 | 全面地图 | ### 配置 三种控制输出的方式： ``` # CLI 标志 python xray.py . --no-logic-maps --no-test-example --no-prose # 项目配置（自动检测） echo '{"sections": {"logic_maps": false}}' > .xray.json python xray.py . # 生成完整配置模板 python xray.py --init-config > .xray.json ``` ### 输出格式 **Markdown** — 人/AI 可读的格式，包含表格、Mermaid 图表、代码块。在 GitHub、VS Code、Obsidian 中渲染。 **JSON** — 用于程序化消费的完整结构化数据。代理使用 JSON 进行特定查找，使用 markdown 进行定向。 ``` python xray.py . --output both --out ./analysis # 创建：analysis.md, analysis.json ``` ### 精选分析示例 **骨架提取** — 类精简为签名： ``` class OrderEngine: # L45 def __init__(self, provider: PaymentProvider): ... def process(self, order: Order) -> Result: ... # CC=25 def validate(self, order: Order) -> bool: ... ``` **逻辑图** — 复杂函数（CC > 15）的符号控制流： ``` process_order(order): -> validate(order) -> valid? {status = processing} * for item in items: -> check_inventory(item) [DB: reserve(item)] -> calculate_total [DB: save(order)] -> Return(success) ``` **共修改耦合** — 没有导入关系但一起更改的文件，通过提交历史上的频繁项集挖掘发现： ``` api/router.py <-> tests/test_api.py (87% co-change, 23 commits) models/order.py <-> migrations/0047.py (71% co-change, 14 commits) ``` **调查目标** — 爬取代理的优先信号：模糊接口、耦合异常、高不确定性模块、共享可变状态。扫描器低成本计算"这个函数可能令人困惑"来自名称通用性和类型覆盖，节省昂贵的爬取代理决定要调查的时间。 ## 第二层：深度爬取 扫描器产生地图。深度爬取产生理解。 它生成并行调查代理，系统地跨六个协议读取源代码，然后将发现汇编成全面的 onboarding 文档。每个声明都有证据支持。文档通过 CLAUDE.md 传递，这样每个未来的代理会话都会自动接收它。 ### 六阶段管道 ``` Phase 0 SETUP Working directory, context management, calibration Phase 1 PLANNING Investigation strategy from X-Ray signals Phase 2 CRAWL Parallel sub-agents execute six investigation protocols Phase 3 ASSEMBLY Curate findings into structured document Phase 4 CROSS-REF Link sections, verify consistency Phase 5 VALIDATE Independent QA (12 questions, 10 spot-checks, adversarial test) Phase 6 DELIVER Copy to docs/, update CLAUDE.md, report metrics ``` ### 调查协议 | 协议 | 焦点 | 输出 | |----------|-------|--------| | **A** | 请求追踪——端到端追踪关键路径 | `findings/traces/` | | **B** | 模块读取——每个模块的行为细节 | `findings/modules/` | | **C** | 横切关注点——错误处理、配置、共享状态 | `findings/cross_cutting/` | | **D** | 约定文档——模式、测试、编码风格 | `findings/conventions/` | | **E** | 反向依赖和变更影响——中心模块、爆炸半径 | `findings/impact/` | | **F** | 变更场景演练——逐步手册 | `findings/playbooks/` | 批次 1-3 并行运行。批次 4 等待 1-3（约定受益于更早的发现）。批次 5（影响分析）等待 1-4（读取模块发现）。批次 6（手册）等待 1-5（引用影响数据）。 ### 证据标准 输出文档中没有推断或未验证的信号。 | 标签 | 标准 | 示例 | |-----|----------|---------| | `[FACT]` | 读取特定代码，引用 `file:line` | "3x 重试 with backoff [FACT] (stripe.py:89)" | | `[PATTERN]` | 在 >= 3 个示例中观察到，说明数量 | "DI via `__init__` [PATTERN: 12/14 services]" | | `[ABSENCE]` | 搜索并确认不存在 | "No rate limiting [ABSENCE: grep -- 0 hits]" | 引用密度是机械强制执行的：调查发现中每 100 个词 >= 5.0 个 `[FACT]`，组装部分中有分层下限（高证据 3.0，中等 2.0，叙事 1.0）。每个来自发现的引用都经过验证，确保进入最终文档。 ### 领域检测 爬取根据检测到的框架调整其调查： | 领域 | 检测 | 额外调查 | |--------|-----------|------------------------| | Web API | FastAPI、Flask、Django | 路由、auth 中间件、CORS、请求生命周期 | | CLI 工具 | argparse、click、typer | 命令结构、参数解析、输出格式 | | ML 管道 | torch、tensorflow、keras | 训练循环、数据加载、模型序列化 | | 数据管道 | airflow、dagster、prefect | DAG 结构、幂等性、阶段依赖 | | 异步服务 | asyncio、aiohttp、trio | 事件循环、同步/异步边界、取消 | | 基础设施 | subprocess、boto3、ansible | 幂等性、回滚、凭证处理 | 检测使用导入分析 + 目录模式。领域特定的调查提示和 grep 模式在 `configs/domain_profiles.json` 中定义。 ### 深度爬取产生什么 **DEEP_ONBOARD.md** — 包含 17 个部分的全面 onboarding 文档： - 身份和技术栈 - 关键路径（端到端追踪并带有代码引用） - 模块行为索引（每个被调查的模块） - 变更影响索引（中心模块、爆炸半径） - 关键接口（带有使用模式的公共 API） - 数据契约（跨边界流、模式演进风险） - 错误处理策略（模式、恢复机制） - 共享状态（全局变量、缓存、单例） - 领域词汇表（代码库特定术语） - 配置表面（环境变量、配置文件、功能开关） - 约定（编码模式、测试方法） - 陷阱（按子系统聚类、严重性标记，每个都有 `file:line` 证据） - 危险文件（避免读取的文件） - 扩展点（在哪里添加新功能） - 变更手册（带有验证命令的逐步修改指南） - 阅读顺序（手动探索的推荐文件序列） - 环境引导（设置说明） 文档通过 CLAUDE.md 自动加载。提示缓存将后续读取成本降低约 90%。 ### 命令 | 命令 | 模式 | 做什么 | |---------|------|--------------| | `/deep-crawl full` | 并行子代理 | 完整管道，最大质量 | | `@deep_crawl full` | 顺序回退 | 相同管道，单一代理 | | `@deep_crawl plan` | 顺序 | 仅生成调查计划 | | `@deep_crawl resume` | 顺序 | 从上一个检查点继续 | | `@deep_crawl validate` | 顺序 | QA 现有文档 | | `@deep_crawl refresh` | 顺序 | 代码变更的增量更新 | | `@deep_crawl focus ./path` | 顺序 | 深度爬取特定子系统 | ### 验证管道 第五阶段生成一个独立的验证器，无法访问发现或 X-Ray 输出——它只能看到最终文档和实际源代码。验证器： 1. 仅从文档回答 12 个标准问题（它能指导新开发者吗？） 2. 抽查 10 个随机 `[FACT]` 声明与实际源文件（9/10 必须验证） 3. 运行对抗性测试：5 个故意棘手的场景来发现漏洞 4. 检查结构可导航性（部分数量、陷阱聚类、模块覆盖） 5. 验证文档大小满足根据代码库规模调整的下限 ## 代理生态系统 四个代理，三层验证： | 代理 | 角色 | 方法 | |-----|------|----------| | **repo_xray** | 来自 X-Ray 信号的快速 onboarding | 四阶段：定向、调查、合成、验证 | | **deep_crawl** | 详尽调查 | 六阶段管道并行子代理 | | **deep_onboard_validator** | 独立 QA | 7 检查协议（完整性、准确性、覆盖、对抗性）| | **repo_retrospective** | 文档审计 | 五阶段：清单、覆盖、验证、可操作性、建议 | `repo_xray` 是轻量级路径——它使用 X-Ray 输出作为地图，并通过定向文件读取添加判断。输出标记有 `[VERIFIED]`、`[INFERRED]` 和 `[X-RAY SIGNAL]` 置信度。 `deep_crawl` 是详尽路径——它读取所有值得阅读的内容，并产生每个声明都有 `[FACT]` 引用的文档。它成本更高，但输出被许多未来会话读取。生成成本被分摊。 ## 增量更新 代码在变，但文档保持不变，直到有人重新运行管道。完整的深度爬取很昂贵。增量系统（已设计，尚未实现）使用三种机制： **依赖范围重新调查** — `git diff` 识别更改的文件。导入图计算 1 跳和 2 跳依赖项。只有受影响的模块被重新调查。典型的 5 文件 PR 触及约 15 个模块而不是整个代码库。 **变更日志** — 目标仓库 CLAUDE.md 中的规则指示模型在修改影响文档声明的代码时追加到 `docs/.onboard_changes.log`： ``` 2026-04-01T14:23:00Z | executor.py:617 | Gotchas / Process Management | Changed timeout mechanism 2026-04-01T14:30:00Z | api_router.py:45 | Critical Paths / API Request | Added rate limiting ``` 部分引用告诉差异爬取确切地在哪里查看文档，而不仅仅是哪个源文件更改了。咨询性的，不是权威性的——依赖分析仍然运行。 **发现合并** — 之前的发现保存在磁盘上。新发现只覆盖受影响的条目。汇编读取合并的目录，不关心文件是新的还是重用的。 ## 工作原理 ### 扫描器内部 使用 Python 的 `ast` 模块进行单次 AST 遍历。每个文件解析一次；多个分析器从同一棵树中提取不同的信号。 | 技术 | 用于 | |-----------|----------| | `ast.walk()` | 扁平遍历（复杂性计数、副作用检测）| | `ast.NodeVisitor` | 状态遍历（调用图、骨架提取）| | `collections.Counter` | 频率分析（模式检测）| | `collections.deque` | BFS（依赖距离计算）| | Git 日志解析 | 风险分数、耦合、新鲜度 | ### 性能 对于 500 文件的代码库： - AST 分析：约 2 秒 - Git 分析：约 1 秒 - 总计：约 5 秒 无外部依赖。仅 Python 3.8+ 标准库。 ### 深度爬取内部 所有中间状态保存在磁盘上（`/tmp/deep_crawl/`），而不是对话上下文中。子代理将发现写入单独的 markdown 文件。编排器在汇编之前从不读取发现内容——它只检查哨兵文件以完成。 发现在批次之间进行质量门控。如果发现少于 200 个词或 5 个 `[FACT]` 引用，子代理会重新生成并带有纠正指令。批次 2（模块深度读取）使用更高的阈值：400 个词和 10 个引用。 在主爬取之前进行校准运行：三个示例调查（一个追踪、一个模块、一个横切关注点）建立质量基准。所有后续子代理提示都引用这些示例。 ## 设计决策**为什么扫描器只用 AST。** 我们考虑了 pytest 追踪、coverage 集成和运行时类型捕获。每一个都会产生更准确的数据。我们拒绝它们，因为它们增加依赖、需要工作的测试套件、需要几分钟而不是几秒，并产生非确定性输出。扫描器的价值在于它可以在任何 Python 代码库上零设置工作。 **为什么输出是给 AI 而不是人类的。** 早期版本服务于两个受众。结果对 AI 来说太冗长（浪费上下文在散文上），对人类来说太结构化（表格和紧凑符号）。我们选择 AI 受众，因为那里有杠杆——人类可以直接读取代码，但 AI 的效率受限于上下文能容纳的内容。 **为什么扫描器中有调查目标。** 扫描器最初是纯观察。我们添加了调查目标（模糊接口、耦合异常、高不确定性模块），因为没有它们，爬取代理会在决定要调查什么上浪费大量时间。扫描器低成本计算"这可能令人困惑"来自名称通用性和类型覆盖。作为优先列表呈现使爬取代理效率提高 2-3 倍。 **为什么通过 CLAUDE.md 交付而不是按需读取。** 一个必须知道查找 onboarding 文档的代理有时不会。一个自动在系统上下文中接收它的代理总是拥有它。自动加载的 token 成本低于代理在没有定向的情况下工作的单个会话的成本。提示缓存使持续成本可以忽略不计。 **为什么深度爬取无限制生成预算。** 文档被许多未来会话读取。以输出质量为代价优化廉价生成是错误的经济计算，因为输出被读取数百次。我们移除了 token 预算上限，让内容决定大小。 ## 限制 - **仅 Python。** 扫描器使用 Python 的 AST 解析器。代理层和文档格式是语言无关的——未来的 TypeScript 或 Rust 扫描器可以接入同一管道。 - **需要 Git 历史** 用于风险、耦合和新鲜度信号。没有 git 也能工作，只是信号较少。 - **副作用检测是启发式的。** 函数名上的模式匹配（`session.commit`、`requests.post`）。有一个白名单来减少误报，但不会捕获新模式。SQL 字符串检测可能标记包含 SQL 类关键字的文档字符串。 - **文档会过时。** 代码在变但文档保持不变直到刷新。稍微过时的 onboarding 文档比没有好。 - **深度爬取输出是非确定性的。** 同一代码库的两次运行产生不同文档。价值来自调查和合成，而不是可重现性。扫描器提供可重现的基础。 ## 文件结构 ``` repo-xray/ ├── xray.py Entry point + orchestration ├── lib/ │ ├── ast_analysis.py Single-pass AST extraction │ ├── import_analysis.py Dependency graph, layers, hub detection │ ├── call_analysis.py Cross-module call sites, reverse lookup │ ├── git_analysis.py Risk scores, coupling, freshness │ ├── gap_features.py Logic maps, hazards, data models, mermaid │ ├── investigation_targets.py Prioritized signals for crawl agents │ ├── blast_analysis.py Transitive impact via BFS over import+call graph │ ├── route_analysis.py HTTP route detection (method, path, handler, side effects) │ ├── file_discovery.py Python file discovery, ignore patterns │ ├── test_analysis.py Test file detection, pattern extraction │ ├── tech_debt_analysis.py TODO/FIXME markers │ └── config_loader.py Config file loading, validation ├── formatters/ │ ├── markdown_formatter.py Human/AI-readable output │ └── json_formatter.py Structured output ├── configs/ │ ├── default_config.json All sections enabled │ └── presets.json Preset definitions ├── tools/ │ └── enrich_onboard.py Inject git signals into DEEP_ONBOARD.md ├── tests/ │ ├── test_gap_features.py Gap analysis tests │ ├── test_investigation_targets.py Signal computation tests │ └── test_scanner_enhancements.py v3.2 detection category tests ├── docs/ │ └── PLAN_INCREMENTAL_CRAWL.md Incremental refresh design └── .claude/ ├── agents/ │ ├── repo_xray.md Investigation agent │ ├── deep_crawl.md Sequential fallback agent │ ├── deep_onboard_validator.md Independent QA agent │ └── repo_retrospective.md Documentation audit agent └── skills/ └── deep-crawl/ ├── SKILL.md Orchestrator instructions (1,600 lines) ├── configs/ │ ├── domain_profiles.json Framework detection + investigation prompts │ ├── quality_gates.json Citation density, word count floors │ └── compression_targets.json Section size targets └── templates/ ├── DEEP_ONBOARD.md.template ├── CRAWL_PLAN.md.template └── VALIDATION_REPORT.md.template ``` ## 安装 ``` git clone https://github.com/jimmc414/claude-repo-xray.git cd claude-repo-xray python xray.py /path/to/your/project ``` 要求：Python 3.8+，无外部依赖。 在 Claude Code 中全局安装深度爬取技能： ``` ./setup_deep_crawl.sh ``` 这创建了一个符号链接，这样 `/deep-crawl full` 在任何项目目录中都可用。 ## 许可证 MIT

标签：AI编码助手, C2, Git分析, Python AST, Python代码分析, Token优化, 上下文窗口优化, 云安全监控, 代码分析框架, 代码复杂度分析, 代码审查工具, 代码库扫描, 代码库理解, 代码搜索引擎优化, 代码文档生成, 代码理解, 代码知识库, 代码索引, 代码结构分析, 代码风险评估, 代码骨架提取, 依赖图分析, 冷启动问题, 副作用分析, 威胁情报, 开发者工具, 网络安全研究, 自动化payload嵌入, 自动化文档, 静态分析