城迹（Folder City）

城迹是一个本地文件夹可视化工具。它会扫描你选择的目录，把复杂的文件夹结构转成一张可探索的 2.5D 纸模城市地图：子目录是“街区”，直属文件是“建筑”，用户可以沿着面包屑逐层进入目录，快速理解项目或资料库的组织方式。

核心能力

• 将本地目录渲染为沉浸式 2.5D 城市视图
• 默认展示当前目录的直接子目录街区和直属文件建筑
• 点击目录街区进入下一层，点击面包屑返回上层
• 点击文件建筑查看文件名、路径、大小、修改时间和类型说明
• 点击目录街区查看总文件数、直属文件数、子目录数、总大小和主类型
• 按文件类型映射建筑颜色：代码、图片、视频、音频、文档、压缩包和其他
• 默认跳过工程缓存和依赖目录，让结构梳理更快、更干净

技术栈

• 后端：Python 3.13、FastAPI、Uvicorn
• 前端：Vue 3、Vite、Three.js、Lucide Icons
• 包管理：uv、npm

项目结构

folder-city/
├─ backend/                  # FastAPI 接口和目录扫描逻辑
│  ├─ main.py
│  └─ scanner.py
├─ frontend/                 # Vue + Vite 前端
│  ├─ src/
│  │  ├─ App.vue
│  │  ├─ components/
│  │  │  └─ IsometricCity.vue
│  │  ├─ main.js
│  │  └─ styles.css
│  ├─ package.json
│  └─ vite.config.js
├─ pyproject.toml
├─ uv.lock
└─ README.md

快速启动

先启动后端：

uv sync
uv run folder-city

默认后端地址：

http://127.0.0.1:8020

健康检查：

http://127.0.0.1:8020/api/health

再打开一个终端启动前端：

npm install
npm run dev

默认前端地址：

http://127.0.0.1:5173

扫描策略

为了让“目录街区”更适合梳理真实文件夹结构，后端默认跳过这些缓存或依赖目录：

.git
node_modules
.venv
venv
env
__pycache__
dist
build
coverage
.cache
.pytest_cache
.mypy_cache
.ruff_cache
.idea
target
out

被跳过的目录会记录在扫描结果的 summary.skipped 中。界面右下角状态条会显示跳过数量。

如果你确实需要全量扫描这些目录，可以这样启动后端：

$env:FOLDER_CITY_SCAN_ALL="1"
uv run folder-city

如果后端端口需要改动：

$env:FOLDER_CITY_API_PORT="8030"
uv run folder-city

同时前端也要指向新的后端地址：

$env:VITE_API_TARGET="http://127.0.0.1:8030"
npm run dev