npm package: @local-inspector/git
Description: 本项目是一个本地 Git 仓库可视化与实时洞察工具，通过本地运行的 HTTP + WebSocket 服务，实时监听 `.git` 目录变化，并在浏览器中提供仓库基础指标、提交历史、分支、贡献者、文件热度等信息的快速浏览。
Author: Elone Hoo
Latest version: 0.0.4

# Git Inspector

本项目是一个本地 Git 仓库可视化与实时洞察工具，通过本地运行的 HTTP + WebSocket 服务，实时监听 `.git` 目录变化，并在浏览器中提供仓库基础指标、提交历史、分支、贡献者、文件热度等信息的快速浏览。

> 当前版本：`0.0.3`（原型阶段 / 基础功能验证）

## 🎯 产品定位转向：迈向 “Git Desktop” Web App
你希望它不仅是“只读的分析仪表盘 (Inspector)”，而是一个“类 GitHub Desktop / SourceTree 的 Web 形态 Git 客户端”。因此 Roadmap 需要从 “统计洞察” 扩展到 “日常 Git 操作 + 可视化 + 安全抽象”。下面给出新的目标体系与阶段迁移策略。

### Two Tracks 双轨并进策略
| Track | 目标 | 保留价值 |
|-------|------|----------|
| A: Inspector (现有) | 快速洞察、指标、历史可视化 | 形成差异化分析能力，可独立模块化 |
| B: Desktop (新增) | 常规 Git 操作（查看 / 修改 / 提交 / 分支 / 合并 / 冲突解决） | 承载主要使用频率，扩大受众 |

建议保持核心代码内聚：抽象一个 GitAdapter（只读 / 读写能力分层），Inspector 继续调用只读接口，Desktop UI 叠加写操作。做到 “读写解耦 + 模块增量引入”。

### Desktop 视角核心能力层次
1. 基础读取：状态、分支、提交、文件树、差异（已具部分能力）
2. 工作区操作：暂存 / 取消暂存 / 部分分块暂存 (hunks) / 提交
3. 分支与历史：创建 / 删除 / rename / checkout / merge / rebase（后期）
4. 冲突解决：解析冲突块、可视化合并工具（最难 UX 部分之一）
5. 高级操作：stash / cherry-pick / revert / reset / tag / squash
6. 多仓管理：侧边栏多仓切换 / 最近打开列表 / 快速搜索
7. 扩展生态：插件（签名校验、规范钩子、质量扫描）
8. 协同 & 自动化：分享 patch、预检查（lint/test 钩子）、AI Commit Msg 建议

### 关键设计抽象
| 抽象 | 说明 | 初步字段 | 备注 |
|------|------|---------|------|
| GitAdapter | 统一 Git 操作接口 | read / mutate / stream | 支持 CLI 或后续 libgit2/wasm |
| RepositoryContext | 当前仓库 session | root、capabilities | 可缓存统计/索引
| WorkingDirectoryFile | 文件工作区状态 | path、status、stagedHunks | 用于增量 diff
| Operation | 长耗时动作 | id、type、state、progress | merge / rebase / fetch 等
| DiffChunk(Hunk) | 局部差异 | oldRange、新Range、lines | 允许局部暂存
| Conflict | 冲突单元 | file、sections[] | 每个 section 标记 ours / base / theirs

### 安全与隔离注意
* 严格限制允许的 git 子命令白名单（防注入）
* 路径校验：禁止跳出仓库根目录 (path traversal)
* 写操作需串行队列化（避免并发修改 index）
* 操作日志（调试 & 回溯）
* 未来：基于 --no-pager、--porcelain 格式化输出，减少解析脆弱性

### 性能与可扩展策略
| 场景 | 策略 |
|------|------|
| 大仓文件树 | 延迟加载目录 / 分页 / LRU 缓存 |
| 大量提交 | 分段滚动加载 + REST/流式 (NDJSON) |
| Diff 大文件 | 行数阈值 > N 时折叠 / 仅加载可视区域 |
| 重复 git log | 基于最近 HEAD 记录增量补齐 |
| 并发读写 | 任务队列 + 乐观 UI 更新回滚 |

### Desktop 方向迭代里程碑 (建议与现有 Inspector 交错)
M0 (✔ 进行中)：只读指标与提交/文件基础
M1 文件树 & Diff
M2 暂存/取消暂存 (全文件 + Hunks) + 提交面板
M3 分支管理（创建/切换/删除）+ 快速 HEAD 切换
M4 合并 & 冲突检测（文本冲突可视化，只读 diff）
M5 冲突交互解决（选择 ours/theirs，局部 hunks 合并）
M6 Rebase / Cherry-pick / Revert / Stash 管理
M7 多仓库管理（Recent / Pin / 快速切换）
M8 操作历史面板（可回看执行日志 / 错误重试）
M9 插件 API（注册面板 / 扩展命令 / 数据钩子）
M10 协同能力（生成 patch 链接 / 导出 diff / AI Commit Message）

### Desktop 关键任务拆分（可转换为 Issues）
#### M1 文件树 & Diff
- [ ] GitAdapter: ls-files + 生成分层目录树（含状态：新增/修改/删除/重命名）
- [ ] Diff 服务：支持 `git diff --name-status` + 单文件 `--unified=...`
- [ ] 前端：文件树组件（虚拟滚动）
- [ ] 前端：双栏 Diff 视图（添加、删除高亮）
- [ ] 性能：>5000 文件时渐进渲染 + 搜索过滤

#### M2 暂存与提交
- [ ] 解析 diff hunks 映射到结构化 JSON
- [ ] 局部暂存：构造 patch (`git apply --cached`)
- [ ] UI：Hunk 展开/折叠 + 勾选暂存
- [ ] Commit 面板：消息输入、校验（空消息阻止）
- [ ] 可选 pre-commit 钩子执行（lint/test）+ 结果展示

#### M3 分支管理
- [ ] 列出本地 + 远程分支（标记当前）
- [ ] 创建 / 重命名 / 删除 / checkout
- [ ] 快速比较：分支提交差异计数
- [ ] UI：分支搜索过滤

#### M4~M5 合并与冲突解决
- [ ] 检测 merge 产生的冲突文件 (`git ls-files -u`)
- [ ] 解析冲突区块 markers => sections[]
- [ ] 冲突可视化：三栏 (base / ours / theirs) 或 双栏 + 标识
- [ ] 选择性解决 + 标记已解决 (`git add`)
- [ ] 生成临时快照/撤销（防数据丢失）

#### M6 变基/挑拣/还原/储藏
- [ ] Stash 列表（create/apply/pop/drop）
- [ ] Cherry-pick & Revert 操作封装
- [ ] Rebase（基础线性 rebase，不含交互编辑）
- [ ] 操作进度与错误捕获（UI Toast + 详情）

#### M7+ 后续扩展（简列）
- [ ] 多仓 session 缓存 + 最近列表存储 (localStorage)
- [ ] 插件 API 规格文档草稿
- [ ] Diff 体验增强：内联/并排切换、忽略空白、侧边 mini map
- [ ] AI 辅助：自动生成提交信息 / 变更摘要

### 数据与调用边界建议
| 层级 | 说明 |
|------|------|
| Adapter 层 | 封装 git 命令模板 + 统一错误类型化（GitErrorCode）|
| Service 层 | 组合多次 Git 调用（如 commit 前验证 → diff 生成 → 执行）|
| Transport 层 | RPC/REST/WebSocket；写操作考虑 CSRF/幂等处理 |
| UI 状态层 | 以 repoId + filePath + opId 组织缓存，支持 optimistic 更新 |

### 演进策略 TL;DR
1. 先抽象 GitAdapter（拆分 read / write）
2. 补文件树 & diff → 赋能“查看”
3. 引入暂存/提交 → 形成最小可用桌面客户端
4. 逐步覆盖日常 80% Git 场景（分支、合并、冲突）
5. 叠加高级操作 & 多仓，沉淀操作日志体系
6. 提供插件 API 打开生态，最后再做智能加值

> 下方原始 Inspector 视角 Roadmap 仍保留，可按需合并/裁剪。

## ✨ 已具备的核心能力（当前代码分析）
- ✅ CLI 启动：`npx git-local-inspector` / 通过 `cac` 解析，自动打开浏览器
- ✅ 动态端口：优先 7777，冲突回退端口区间
- ✅ 静态构建 + Nuxt 前端单页（概览、提交、贡献者、文件 四个 Tab）
- ✅ WebSocket 通道：基于 `birpc` 双向 RPC（广播仓库变更事件）
- ✅ `.git` 目录多路径监听（refs / HEAD / index / logs），带去抖处理（800ms）
- ✅ Git 数据采集：
  - 仓库信息（当前分支 / 提交总数 / 文件数 / 贡献者数）
  - 提交历史（哈希 / 作者 / 时间 / 信息 / 变更文件数）
  - 分支列表（含当前标记与最近提交哈希）
  - 贡献者统计（提交次数 / 增加行 / 删除行）
  - 文件统计（提交次数 / 增删行 / 最近修改时间，当前限前 100 个）
- ✅ UI 交互：Tab 切换 + 近期 Commit / Top Contributors / 热门文件展示
- ✅ 响应式刷新：仓库变更后自动触发全量数据重新抓取（并行刷新）
- ✅ 样式体系：UnoCSS + Tailwind Reset + 暗色模式基础适配
- ✅ 构建与打包：`unbuild` 产出库入口，支持 ESM

## 🔍 架构速览
```
CLI (cac) → createHostServer() → HTTP Server (h3) + Static Assets
                              ↘ createWsServer() → WebSocket + birpc 广播
.git 监听 (fs.watch) → debounce → rpc.broadcast.onRepoChanged() → 前端 repoChangeEvent
前端 useAsyncState + birpc rpc → 拉取 Git 信息（同步 shell 执行 git 命令）
```

## 🚧 已识别的技术/产品局限
| 维度 | 当前状况 | 潜在风险 |
| ---- | -------- | -------- |
| Git 调用 | `execSync` 同步串行 | 大仓库/高频触发阻塞事件循环 |
| 文件统计 | 仅前 100 个文件 | 热点可能被截断，缺少分页/筛选 |
| 贡献者 | 粗粒度（全局聚合） | 无时间范围 / 无身份合并（多邮箱） |
| 安全 | 直接执行本地 `git` 命令 | 未做路径校验 / 命令注入防护（虽内部使用） |
| 监听实现 | fs.watch 多路径 | 跨平台一致性与稳定性未知（Windows / 网络文件系统） |
| 前端表现 | 纯列表 + 原始数字 | 缺少图表、趋势、交互分析能力 |
| 缓存策略 | 无缓存 / 全量刷新 | 重复执行大量 `git log` 开销大 |
| 测试体系 | 缺失 | 升级或重构风险高 |
| 发布渠道 | 仅 pnpm 包 | 缺少 Homebrew / Scoop / Docker 镜像 |
| 可扩展性 | 无插件机制 | 难以外部扩展新指标/面板 |

## 🗺️ Roadmap
### 里程碑分层（可迭代发布节奏建议）
- M0（当前）: 原型可运行，核心基础指标 & UI 验证
- M1（可用版）: 性能 / 稳定性 / 数据结构打底 + 基础图表
- M2（增强版）: 分析维度扩展 + 交互强化 + 配置化
- M3（专业版）: 热点/趋势/质量指标 + 多仓 + 持久化
- M4（生态版）: 插件体系 + 第三方集成 + 发布渠道完善
- M5（洞察平台）: 智能分析 / 异常检测 / 团队指标治理

### 详细任务拆解
#### M1 可用稳定版
- [ ] 重构 Git 调用为异步（`child_process.spawn` / 批量并行）
- [ ] 引入缓存层（按 commit hash / 文件路径 memo）
- [ ] 文件统计分页与搜索（路径前缀/扩展名过滤）
- [ ] 基础折线/饼图（提交趋势 / 作者占比 / 文件 churn）
- [ ] CLI 增加参数：`--port` / `--open=false` / `--root=...`
- [ ] 健壮性：监听失败降级（轮询 fallback）
- [ ] 单元测试：Git 数据解析（使用 fixture 仓库）
- [ ] E2E 测试：启动 + WebSocket 刷新
- [ ] 添加 README（本次完成）与基本徽章（license/version）

#### M2 进阶分析与体验
- [ ] 时间窗口过滤（最近 7 / 30 / 90 天）
- [ ] 作者别名合并（多邮箱映射）
- [ ] 分支对比（提交差异 / 未合并提交）
- [ ] 文件热度算法优化（综合 churn + 近期活跃度）
- [ ] Diff 预览（最近提交的变更片段）
- [ ] 深色/浅色自动切换 + 自定义主题
- [ ] 导出数据（JSON / CSV）
- [ ] 命令行无头模式：输出 JSON（便于 CI）

#### M3 高级洞察
- [ ] Hotspot 检测（高 churn + 高复杂度候选，需集成简单复杂度分析）
- [ ] Bus Factor（单人主导文件识别）
- [ ] 活跃度热力图（日历视图）
- [ ] 文件/目录层级聚合统计（treemap / sunburst）
- [ ] 多仓库仪表盘（串行/并行抓取）
- [ ] 本地轻量数据库存储（SQLite / better-sqlite3）缓存历史快照
- [ ] 增量更新（基于最近 commit 而非全量 git log）

#### M4 生态与扩展
- [ ] 插件系统（Hooks：数据收集阶段 / 聚合阶段 / 前端面板注册）
- [ ] 插件开发模板 & 类型定义
- [ ] 配置文件 `.gitinspector.config.ts`
- [ ] 发布多渠道：Homebrew / Scoop / Docker / Web(只读模式? )
- [ ] CI 集成（GitHub Action 输出报告 artifact）
- [ ] 国际化（i18n，多语言 UI）
- [ ] SSO 或 Token 保护（用于共享只读访问）

#### M5 智能洞察
- [ ] 异常变更检测（提交规模 / 提交频率异常）
- [ ] 风险提示（大量删除 / 可疑提交模式）
- [ ] 历史趋势建模（产生预测：提交量、贡献者活跃度）
- [ ] 提交消息质量评分（正则 + 简单 NLP）
- [ ] 质量指标汇总：平均 PR Lead Time（需扩展到远程 API）

### 横切关注点（贯穿各里程碑）
- 安全：输入规范化，限制 root 目录出界
- 性能：大仓库（>10k commits）应支持渐进加载与流式传输
- 可观测性：日志等级 / 统计指标（执行耗时、缓存命中率）
- DX：类型严格化 + ESLint 规则补充 + 提交规范
- 文档：架构图、二次开发指南、插件接口文档
- 可维护性：抽象数据层（Data Provider）与前端视图解耦

## 🧪 建议的测试策略
| 层级 | 内容 | 工具建议 |
| ---- | ---- | -------- |
| 单元 | git 输出解析 / 统计聚合 | vitest + fixture 仓库 |
| 集成 | CLI 启动 / WebSocket 事件 | vitest / playwright (无头) |
| 端到端 | 实际操作 git（新建分支 / 提交）触发刷新 | 临时 sandbox 目录 |
| 性能 | 大量 commits 仓库基准 | 采样执行时间与内存 |

## 📦 使用与开发
### 安装
```bash
pnpm i git-local-inspector -g
# 或
npx git-local-inspector
```

### 本地开发
```bash
pnpm install
pnpm dev
```

### 构建
```bash
pnpm build
```

## 🔧 潜在技术选型（后续阶段）
| 场景 | 候选 | 备注 |
| ---- | ---- | ---- |
| Git 数据层抽象 | `simple-git` / `isomorphic-git` | 异步 & 便于测试 |
| 可视化 | `echarts` / `apexcharts` / `chart.js` | 图表组件化 |
| 数据持久化 | `better-sqlite3` | 零依赖 / 本地缓存 |
| 插件隔离 | VM / 动态 import | 安全沙箱需评估 |

## 🤝 贡献指南（规划）
1. Fork & 分支：`feat/xxx` / `fix/xxx`
2. 保持提交原子化，遵循 Conventional Commits
3. 新增功能附带最少 1~2 个测试用例
4. 避免在同一 PR 同时做重构 + 功能

## 📄 License
待补充（建议 MIT）

---
如果你有功能建议或想提前实现 Roadmap 中的条目，欢迎提出 Issue 或 PR 🙌