repo-xray 是面向 Python 代码库的 X-Ray 扫描器，用于解决 AI 编程助手面对超大代码库时的冷启动问题。它基于 AST 提取结构、行为与历史等 37+ 信号，将数百万 token 的代码压缩为可操作情报。
主要能力：结构方面提供文件树与 token 估算、类与函数骨架、类型注解覆盖率、装饰器清单；架构方面提供分层导入图、依赖距离、循环依赖、枢纽模块与孤立文件；历史方面提供风险评分、共同修改耦合、新鲜度分类与 Git 专家归属；复杂度方面提供圈复杂度、热点排名与异步模式；行为方面提供副作用分类、跨模块调用图、状态变更与复杂函数逻辑图；上下文方面提供入口点、CLI 参数、环境变量、Pydantic 校验器、linter 规则与测试模式；安全方面提供危险文件与排除 glob。
使用方式：运行 python xray.py /path/to/project --output both 可同时生成 Markdown 摘要与 JSON 数据。支持 --preset minimal/standard/full 控制输出规模，--output markdown/json/both 选择格式，--out 指定输出位置，--no-logic-maps、--no-hazards、--no-git 关闭部分分析，--verbose 显示进度。可用 python xray.py --init-config > .xray.json 生成配置模板，在项目根目录放置 .xray.json 自动检测。
适用场景：探索架构、提取接口、映射依赖、生成上手文档，以及为 AI 代理提供代码库地图。代理工作流分四阶段：ORIENT 读取 Markdown 摘要，INVESTIGATE 用 Read/Grep/Glob 验证信号并发现缺口，SYNTHESIZE 生成上手文档，VALIDATE 自测输出。
限制：仅支持 Python 3.8+，无外部依赖（仅标准库），Git 历史分析需安装 Git。大型代码库（>500 文件）建议分而治之或优先处理。资料未提供收费、价格与平台信息。