RepoFractal

把任意 Git 代码仓库渲染成可交互的三维分形热点图。

仓库中的对象（目录、文件、branch、tag、release）是图中的节点。工具从 Git 历史与 GitHub 元数据中计算每个节点的重要性和热度，再把它们映射到 3D 分形空间：

• 节点大小 = 重要性
• 节点颜色 / 光晕 / 标签 = 热度
• 越靠近分形末梢越细节，越亮越热的节点越突出
• 三种分形布局：分形树、银河螺旋、霍普夫球

输出为一个完全离线的 HTML 文件（内置 three.js，不依赖 CDN），浏览器打开即可交互。

快速开始

# 本地仓库
python3 -m repo_fractal /path/to/repo -o repo.html --open

# GitHub 仓库（自动克隆到缓存目录，可用 GITHUB_TOKEN 读取 stars/releases）
python3 -m repo_fractal https://github.com/psf/requests -o requests.html --open

# 安装为命令
pip install .
repo-fractal https://github.com/owner/repo --profile hot --open

功能

• 节点类型：dir、file、branch（本地与远端）、tag、release
• 重要性由代码体量、目录结构度、协作作者数等特征计算
• 热度由近期提交活跃度、提交新鲜度、版本/release 强度等特征计算
• 内置计算方案：balanced、important、hot、hotspots
• 计算权重可通过 JSON 配置定制；打开 HTML 后还可用滑杆实时调整全部权重
• 交互：拖拽旋转、滚轮缩放、右键平移、搜索过滤、类型过滤、最小分数过滤、标签密度、光晕开关
• 视觉：InstancedMesh 高效渲染、动态热点光晕、追热点灯光、星空背景、四种色板

命令行

python3 -m repo_fractal URL_OR_PATH \
  -o OUTPUT.html \          # 输出文件
  --format html|json|jsonl  # 格式，默认 html
  --profile balanced        # balanced / important / hot / hotspots
  --config config.json      # 自定义权重与显示参数
  --ai-prompt "..."         # 用 AI/自然语言提示词调整算法
  --ai-prompt-file prompt.txt
  --ai-provider auto        # auto / openai / anthropic / local
  --ai-model MODEL          # 覆盖默认模型
  --save-ai-config out.json # 保存提示词生成的配置
  --layout fractal_tree     # fractal_tree / galaxy / hopf_sphere
  --max-nodes 4000          # 超大仓库节点上限
  --max-commits 600         # 参与热度计算的历史提交数
  --no-fetch-github         # 不访问 GitHub API
  --open                    # 生成后调用浏览器

--format json 输出节点、特征、分数与 3D 坐标，便于接入其他管线。

用 AI 提示词调整算法

# 未配置 API key 时自动使用内置本地规则引擎，完全离线
python3 -m repo_fractal /path/to/repo \
  --ai-prompt "更重视最近修改的文件，降低目录结构权重，突出 release，新鲜度半衰期30天" \
  --save-ai-config ai-config.json -o repo.html

# 配置 OpenAI 兼容接口后，自动调用 LLM 生成更细的配置
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1   # 可选
export OPENAI_MODEL=gpt-4o-mini                     # 可选
python3 -m repo_fractal /path/to/repo \
  --ai-prompt "主要看代码体量和提交活跃度，版本因素不重要，使用排名归一化和线性混合" \
  --ai-provider openai -o repo.html

# 使用 Anthropic
export ANTHROPIC_API_KEY=...
python3 -m repo_fractal /path/to/repo --ai-provider anthropic \
  --ai-prompt "突出目录结构，release 节点权重提高 50%" -o repo.html

--ai-provider auto 的决策顺序：有 ANTHROPIC_API_KEY 用 Anthropic， 否则有 OPENAI_API_KEY / OPENAI_BASE_URL 用 OpenAI，都没有则用本地规则引擎。 本地规则引擎支持中英文关键词，如“更重视 / 突出 / 降低 / 只看 / 忽略”、 节点类型、半衰期天数、归一化方式、线性/几何混合等。

深度定制重要性与热度

配置文件是 JSON（完整示例见 config.example.json）：

{
  "balance": 0.7,
  "importance": {
    "file": { "size": 0.4, "degree": 0.1, "refs": 0.5 },
    "dir":  { "size": 0.3, "degree": 0.5, "refs": 0.2 }
  },
  "hotness": {
    "file": { "activity": 0.8, "recency": 0.2 }
  },
  "normalization": "robust",
  "clip_low": 0.02,
  "clip_high": 0.98,
  "combine_formula": "weighted_sum",
  "mix_formula": "geometric",
  "recency_half_life_days": 75,
  "size_source": "auto",
  "feature_transforms": { "size": "sqrt", "activity": "log1p" },
  "kind_boost": { "release": 1.5 },
  "importance_exp": 1.0,
  "hotness_exp": 1.0,
  "display": {
    "theme": "aurora",
    "labels": 30,
    "auto_rotate": true
  }
}

说明：

• importance / hotness：按节点类型（dir/file/branch/tag/release）和特征加权
• normalization：robust（默认，2% / 98% 截断）、minmax、rank
• clip_low / clip_high：robust 归一化截断点
• combine_formula：特征如何聚合，weighted_sum（加权和）或 weighted_product（几何平均，惩罚短板）
• mix_formula：重要性与热度如何合成，geometric / linear / harmonic
• recency_half_life_days：新鲜度指数衰减半衰期，越小越“喜新厌旧”
• size_source：代码体量口径，auto / bytes / lines / max
• feature_transforms：每个特征可再做 none / log1p / sqrt / square 变换
• kind_boost：对某类节点做跨类型增益，例如让 release 更容易进入热点榜
• importance_exp / hotness_exp：后端分数曲线；HTML 中仍有对应滑杆
• display / layout_params：HTML 初始显示参数
• HTML 内的滑杆可以继续调整 size / degree / refs / activity / recency / version 六项权重及曲线，无需重新生成

实现结构

repo_fractal/
├── cli.py            # 命令行入口
├── source.py         # URL 解析、克隆缓存、GitHub API
├── graph.py          # git ls-tree / log / for-each-ref 提取对象图
├── ai_tuner.py       # AI 提示词 / 本地规则引擎 -> 指标算法配置
├── metrics.py        # 特征归一化、重要性与热度公式
├── layout.py         # Python 参考版 3D 分形布局
├── html_renderer.py  # 离线 HTML 生成
├── web/template.html # 交互式前端（控制面板 + three.js 场景）
└── static/three.min.js

开发与测试

python3 -m unittest discover -s tests -v

备注

• 远程仓库首次运行需要 git clone；默认使用 --filter=blob:none 减少流量，失败时自动回退
• GitHub API 未配置 token 时仍会尝试公开接口；失败则把版本 tag 推断为 release
• 对于非常大的仓库，建议 --max-nodes 3000 --max-commits 300 --no-count-lines