Metadata-Version: 2.4
Name: repo-fractal-viz
Version: 0.1.0
Summary: Interactive 3D fractal hotspot visualization for Git repositories. 把任意 Git 仓库渲染成可交互的 3D 分形热点图。
Author: Repo Fractal Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/hankhu/code-viz
Project-URL: Repository, https://github.com/hankhu/code-viz
Keywords: git,repository,visualization,3d,fractal,threejs,hotspot,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: requires-python

# RepoFractal

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

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

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

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

## 快速开始

```bash
# 本地仓库
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 高效渲染、动态热点光晕、追热点灯光、星空背景、四种色板

## 命令行

```text
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 提示词调整算法

```bash
# 未配置 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`）：

```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`
  六项权重及曲线，无需重新生成

## 实现结构

```text
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
```

## 开发与测试

```bash
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`
