openspec-stat 1.4.4 → 1.4.5

package/README.md

@@ -10,279 +10,127 @@ English | [简体中文](./README.zh-CN.md)
 
 A CLI tool for tracking team members' OpenSpec proposals and code changes in Git repositories.
 
-## Features
-
-- ✅ Track Git commits within specified time ranges
-- ✅ Identify commits containing both OpenSpec proposals and code changes
-- ✅ **Proposal-based statistics summary** - Aggregate statistics by proposal to avoid merge commit bias
-- ✅ Group statistics by author (commits, proposals, code changes)
-- ✅ Support multiple branches and wildcard filtering
-- ✅ Author name mapping (handle multiple Git accounts for the same person)
-- ✅ Track only recently active members (default: 2 weeks)
-- ✅ Multiple output formats: Table, JSON, CSV, Markdown
-- ✅ Internationalization support: English and Chinese (简体中文)
-- ✅ **🆕 Multi-repository mode (BETA)** - Analyze multiple local/remote repositories in one run
-
-## Installation
-
-### Global Installation
+## Install
 
 ```bash
+# global install
 npm install -g openspec-stat
-# or
-pnpm add -g openspec-stat
-```
-
-### Local Project Installation
-
-```bash
-npm install openspec-stat --save-dev
-# or
-pnpm add -D openspec-stat
+# or local (dev dependency)
+npm install -D openspec-stat
 ```
 
-## Usage
-
-### Basic Usage
+## Quick start
 
-Run in a Git repository directory:
+Default window: yesterday 20:00 → today 20:00.
 
 ```bash
+# basic run
 openspec-stat
-```
-
-This will track commits in the default time range (yesterday 20:00 ~ today 20:00).
-
-### Multi-Repository Mode (BETA)
-
-⚠️ **Experimental Feature**: Multi-repository mode allows analyzing multiple repositories (local or remote) in a single run.
 
-```bash
-# Initialize multi-repo configuration (interactive wizard)
-openspec-stat init --multi
+# custom time range
+openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
 
-# Run multi-repo analysis
+# multi-repo (uses config)
 openspec-stat multi -c .openspec-stats.multi.json
-
-# Run with detailed contributor statistics
-openspec-stat multi -c .openspec-stats.multi.json --show-contributors
-
-# Generate template
-openspec-stat init --template multi -o config.json
 ```
 
-**Perfect for team managers who:**
-- Have local access to backend repos but not frontend repos
-- Need to track contributions across multiple repositories
-- Want combined statistics without running multiple commands
+## Key features
 
-**Note**: By default, multi-repo mode only shows aggregated statistics to avoid information overload. Use `--show-contributors` to see detailed statistics for each contributor.
+- Track Git commits in a time window and per-branch filters
+- Detect commits containing both OpenSpec proposals and code changes
+- Proposal-based aggregation to avoid merge-commit bias
+- Author grouping with name mapping (multiple Git identities per person)
+- Multi-branch wildcards and **multi-repository mode (BETA)**
+- Outputs: table, JSON, CSV, Markdown; languages: en / zh-CN
 
-See [Multi-Repository Guide](./MULTI_REPO_GUIDE.md) for detailed documentation.
+## Common flags (full list: `openspec-stat --help`)
 
-### Command Line Options
+- `-r, --repo <path>`: repository path (default: current directory)
+- `-b, --branches <list>`: comma-separated branches, supports wildcards
+- `-s, --since <datetime>` / `-u, --until <datetime>`: time window
+- `-a, --author <name>`: filter by author
+- `-c, --config <path>`: config file
+- `--json | --csv | --markdown`: output format
+- `-l, --lang <language>`: `en` or `zh-CN`
+- `-v, --verbose`: verbose output
 
-```bash
-openspec-stat [options]
-
-Options:
-  -r, --repo <path>           Repository path (default: current directory)
-  -b, --branches <branches>   Branch list, comma-separated (e.g., origin/master,origin/release/v1.0)
-  -s, --since <datetime>      Start time (default: yesterday 20:00)
-  -u, --until <datetime>      End time (default: today 20:00)
-  -a, --author <name>         Filter by specific author
-  --json                      Output in JSON format
-  --csv                       Output in CSV format
-  --markdown                  Output in Markdown format
-  -c, --config <path>         Configuration file path
-  -v, --verbose               Verbose output mode
-  -l, --lang <language>       Language for output (en, zh-CN) (default: "en")
-  -V, --version               Display version number
-  -h, --help                  Display help information
-```
+## Multi-repo mode (BETA)
 
-### Examples
+Analyze multiple local/remote repositories in one run.
 
 ```bash
-# Track default time range
-openspec-stat
-
-# Track specific time range
-openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
-
-# Track specific branches
-openspec-stat --branches "origin/master,origin/release/v1.0"
-
-# Track specific author
-openspec-stat --author "John Doe"
-
-# Output JSON format
-openspec-stat --json > stats.json
-
-# Output Markdown report
-openspec-stat --markdown > report.md
-
-# Verbose output mode
-openspec-stat --verbose
-
-# Use custom configuration file
-openspec-stat --config ./my-config.json
+openspec-stat init --multi                         # interactive setup
+openspec-stat multi -c .openspec-stats.multi.json  # aggregated view
+openspec-stat multi -c .openspec-stats.multi.json --show-contributors
+```
 
-# Use Chinese output
-openspec-stat --lang zh-CN
+See [Multi-Repository Guide](./MULTI_REPO_GUIDE.md) for full details.
 
-# Combine with other options
-openspec-stat --lang zh-CN --verbose
-```
+**Remote cache**: remote repos are cloned once and reused under
+`~/.openspec-stat/cached/repos/<repo-name>-<hash>`. Use `--cache-mode temporary`
+to force one-off clones, or `--force-clone` to refresh a single run.
 
-## Configuration File
+## Configuration (short)
 
-Create `.openspec-stats.json` or `openspec-stats.config.json` in the project root:
+Create `.openspec-stats.json` or `openspec-stats.config.json` in the repo root.
 
 ```json
 {
-  "defaultBranches": [
-    "origin/master",
-    "origin/main",
-    "origin/release/*"
-  ],
+  "defaultBranches": ["origin/master", "origin/main", "origin/release/*"],
   "defaultSinceHours": -30,
   "defaultUntilHours": 18,
-  "authorMapping": {
-    "John Doe": "John Doe",
-    "john.doe@company.com": "John Doe",
-    "johnd": "John Doe"
-  },
+  "authorMapping": {"john.doe@company.com": "John Doe"},
   "openspecDir": "openspec/",
-  "excludeExtensions": [
-    ".md",
-    ".txt",
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".gif",
-    ".svg",
-    ".ico",
-    ".webp"
-  ],
+  "excludeExtensions": [".md", ".txt", ".png", ".jpg", "..."],
   "activeUserWeeks": 2
 }
 ```
 
-### Configuration Options
-
-- **defaultBranches**: Default branches to track (supports wildcards)
-- **defaultSinceHours**: Default start time offset (hours, negative means going back)
-- **defaultUntilHours**: Default end time (hour of the day)
-- **authorMapping**: Author name mapping to unify multiple Git accounts for the same person
-- **openspecDir**: OpenSpec proposals directory (default: `openspec/`)
-- **excludeExtensions**: File extensions to exclude (not counted as code changes)
-- **activeUserWeeks**: Active user time window (weeks, default: 2)
-
-## Statistics Logic
-
-The tool identifies commits that meet both conditions:
-
-1. Contains file changes in the `openspec/` directory (OpenSpec proposals)
-2. Contains code file changes (excluding documentation files)
-
-Statistics include:
-
-- **Commits**: Total number of qualifying commits
-- **OpenSpec Proposals**: Counted by `openspec/changes/{proposal-name}` directories
-- **Code Files**: Number of modified code files
-- **Additions**: Lines of code added
-- **Deletions**: Lines of code deleted
-- **Net Changes**: Additions - Deletions
-
-The tool provides two perspectives:
+Key fields: default branches/time window, author mapping (merge identities), OpenSpec directory, excluded extensions, active user window.
 
-1. **Proposal Summary**: Aggregates statistics by proposal, showing total code changes per proposal and all contributors. This avoids statistical bias from merge commits.
-2. **Author Summary**: Groups statistics by contributor, showing individual author contributions.
-
-## Output Formats
-
-### Table Format (Default)
+## Output
 
 ```
-📊 OpenSpec Statistics Report
-Time Range: 2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
+📊 OpenSpec Report
+Time: 2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
 Branches: origin/master
-Total Commits: 15
-
-📋 Proposal Summary (by proposal)
-┌──────────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ Proposal     │ Commits │ Contributors     │ Code Files │ Additions │ Deletions │ Net Changes │
-├──────────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
-│ feature-123  │ 5       │ John Doe, Jane S.│ 30         │ +890      │ -234      │ +656        │
-│ feature-456  │ 3       │ John Doe         │ 15         │ +344      │ -100      │ +244        │
-└──────────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
-  📊 Total: 2 proposals | 8 commits | 45 files | +1234/-334 lines (net: +900)
-
-👥 Author Summary (by contributor)
-┌──────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ Author   │ Commits │ OpenSpec Proposals│ Code Files │ Additions │ Deletions │ Net Changes │
-├──────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
-│ John Doe │ 8       │ 3                │ 45         │ +1234     │ -567      │ +667        │
-│ Jane S.  │ 7       │ 2                │ 32         │ +890      │ -234      │ +656        │
-└──────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
-```
-
-### JSON Format
-
-```bash
-openspec-stat --json
-```
-
-### CSV Format
-
-```bash
-openspec-stat --csv > stats.csv
-```
-
-### Markdown Format
-
-```bash
-openspec-stat --markdown > report.md
+Total Commits: 8
+
+Proposal Summary
+┌──────────────┬─────────┬───────────┬───────────┐
+│ Proposal     │ Commits │ Files     │ Net Δ     │
+├──────────────┼─────────┼───────────┼───────────┤
+│ feature-123  │ 5       │ 30        │ +656      │
+└──────────────┴─────────┴───────────┴───────────┘
+
+Author Summary
+┌─────────┬─────────┬───────────┬───────────┐
+│ Author  │ Commits │ Proposals │ Net Δ     │
+├─────────┼─────────┼───────────┼───────────┤
+│ John D. │ 8       │ 3         │ +667      │
+└─────────┴─────────┴───────────┴───────────┘
 ```
 
-## Language Support
+Use `--markdown`, `--json`, or `--csv` for other formats.
 
-The tool supports both English and Chinese output. You can specify the language using the `--lang` option:
+## Language
 
-```bash
-# English output (default)
-openspec-stat --lang en
-
-# Chinese output
-openspec-stat --lang zh-CN
-```
-
-The tool will also automatically detect your system language. If your system locale is set to Chinese, the output will default to Chinese.
-
-For a Chinese version of this README, see [README.zh-CN.md](./README.zh-CN.md).
+`--lang en` (default) or `--lang zh-CN`. Locale-based auto-detection is also supported.
 
 ## Development
 
 ```bash
-# Install dependencies
 pnpm install
-
-# Development mode
 pnpm dev
-
-# Build
 pnpm build
-
-# Local testing
 node dist/cjs/cli.js
 ```
 
 ## Contributing & Release Process
 
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, branching, and pull-request expectations.
-- See [RELEASE.md](./RELEASE.md) for the Changesets-driven versioning and publishing workflow.
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and PR expectations.
+- See [RELEASE.md](./RELEASE.md) for the Changesets-driven publishing workflow.
 
-## LICENSE
+## License
 
 MIT

package/README.zh-CN.md

@@ -4,280 +4,130 @@
 [![NPM downloads](http://img.shields.io/npm/dm/openspec-stat.svg?style=flat)](https://npmjs.com/package/openspec-stat)
 [![CI](https://github.com/Orchardxyz/openspec-stat/actions/workflows/ci.yml/badge.svg)](https://github.com/Orchardxyz/openspec-stat/actions/workflows/ci.yml)
 
-用于追踪团队成员在 Git 仓库中的 OpenSpec 提案和代码变更的命令行工具。
+用于追踪团队成员在 Git 仓库中的 OpenSpec 提案与代码变更的命令行工具。
 
 [English](./README.md) | 简体中文
 
-## 功能特性
-
-- ✅ 追踪指定时间范围内的 Git 提交
-- ✅ 识别同时包含 OpenSpec 提案和代码变更的提交
-- ✅ **提案维度统计汇总** - 按提案聚合统计，避免 merge commit 导致的统计偏差
-- ✅ 按作者分组统计（提交数、提案数、代码变更）
-- ✅ 支持多分支和通配符过滤
-- ✅ 作者名称映射（处理同一人的多个 Git 账号）
-- ✅ 仅追踪最近活跃的成员（默认：2 周）
-- ✅ 多种输出格式：表格、JSON、CSV、Markdown
-- ✅ 国际化支持：英文和中文
-- ✅ **🆕 多仓库模式（BETA）** - 一次运行分析多个本地/远程仓库
-
 ## 安装
 
-### 全局安装
-
 ```bash
+# 全局安装
 npm install -g openspec-stat
-# 或
-pnpm add -g openspec-stat
-```
-
-### 本地项目安装
-
-```bash
-npm install openspec-stat --save-dev
-# 或
-pnpm add -D openspec-stat
+# 或项目内开发依赖
+npm install -D openspec-stat
 ```
 
-## 使用方法
-
-### 基本用法
+## 快速开始
 
-在 Git 仓库目录中运行：
+默认时间窗口：昨天 20:00 → 今天 20:00。
 
 ```bash
+# 基础运行
 openspec-stat
-```
-
-这将追踪默认时间范围内的提交（昨天 20:00 ~ 今天 20:00）。
-
-### 多仓库模式（BETA）
-
-⚠️ **实验性功能**：多仓库模式允许在单次运行中分析多个仓库（本地或远程）。
 
-```bash
-# 初始化多仓库配置（交互式向导）
-openspec-stat init --multi
+# 自定义时间范围
+openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
 
-# 运行多仓库分析
+# 多仓库（需配置文件）
 openspec-stat multi -c .openspec-stats.multi.json
-
-# 运行并显示详细的贡献者统计
-openspec-stat multi -c .openspec-stats.multi.json --show-contributors
-
-# 生成配置模板
-openspec-stat init --template multi -o config.json
 ```
 
-**适用于以下场景的团队管理者：**
-- 拥有后端仓库的本地访问权限，但没有前端仓库
-- 需要跨多个仓库追踪贡献情况
-- 希望获得合并统计结果，而无需运行多个命令
+## 关键特性
 
-**注意**：默认情况下，多仓库模式仅显示聚合统计信息，以避免信息过载。使用 `--show-contributors` 可查看每个贡献者的详细统计信息。
+- 按时间窗口与分支过滤追踪 Git 提交
+- 识别同时包含 OpenSpec 提案与代码变更的提交
+- 提案维度聚合，避免 merge commit 统计偏差
+- 作者分组与名称映射（合并多个 Git 身份）
+- 多分支通配与 **多仓库模式（BETA）**
+- 输出：表格、JSON、CSV、Markdown；语言：en / zh-CN
 
-详细文档请参阅 [多仓库模式指南](./MULTI_REPO_GUIDE.md)。
+## 常用参数（完整见 `openspec-stat --help`）
 
-### 命令行选项
+- `-r, --repo <path>`：仓库路径（默认当前目录）
+- `-b, --branches <list>`：逗号分隔分支，支持通配
+- `-s, --since` / `-u, --until`：时间范围
+- `-a, --author <name>`：按作者过滤
+- `-c, --config <path>`：配置文件
+- `--json | --csv | --markdown`：输出格式
+- `-l, --lang <language>`：`en` 或 `zh-CN`
+- `-v, --verbose`：详细模式
 
-```bash
-openspec-stat [选项]
-
-选项：
-  -r, --repo <path>           仓库路径（默认：当前目录）
-  -b, --branches <branches>   分支列表，逗号分隔（例如：origin/master,origin/release/v1.0）
-  -s, --since <datetime>      开始时间（默认：昨天 20:00）
-  -u, --until <datetime>      结束时间（默认：今天 20:00）
-  -a, --author <name>         按特定作者筛选
-  --json                      以 JSON 格式输出
-  --csv                       以 CSV 格式输出
-  --markdown                  以 Markdown 格式输出
-  -c, --config <path>         配置文件路径
-  -v, --verbose               详细输出模式
-  -l, --lang <language>       输出语言（en, zh-CN）（默认："en"）
-  -V, --version               显示版本号
-  -h, --help                  显示帮助信息
-```
+## 多仓库模式（BETA）
 
-### 使用示例
+一次运行分析多个本地/远程仓库。
 
 ```bash
-# 追踪默认时间范围
-openspec-stat
-
-# 追踪特定时间范围
-openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"
-
-# 追踪特定分支
-openspec-stat --branches "origin/master,origin/release/v1.0"
-
-# 追踪特定作者
-openspec-stat --author "张三"
-
-# 输出 JSON 格式
-openspec-stat --json > stats.json
-
-# 输出 Markdown 报告
-openspec-stat --markdown > report.md
-
-# 详细输出模式
-openspec-stat --verbose
+openspec-stat init --multi                         # 交互式初始化
+openspec-stat multi -c .openspec-stats.multi.json  # 聚合视图
+openspec-stat multi -c .openspec-stats.multi.json --show-contributors
+```
 
-# 使用自定义配置文件
-openspec-stat --config ./my-config.json
+详见 [多仓库模式指南](./MULTI_REPO_GUIDE.md)。
 
-# 使用中文输出
-openspec-stat --lang zh-CN
+**远程缓存**：远程仓库会首次克隆后复用，路径为
+`~/.openspec-stat/cached/repos/<仓库名>-<哈希>`。使用 `--cache-mode temporary`
+可改为一次性克隆，或用 `--force-clone` 在单次运行中强制重新克隆。
 
-# 组合多个选项
-openspec-stat --lang zh-CN --verbose
-```
+## 配置（简版）
 
-## 配置文件
-
-在项目根目录创建 `.openspec-stats.json` 或 `openspec-stats.config.json`：
+在仓库根目录创建 `.openspec-stats.json` 或 `openspec-stats.config.json`。
 
 ```json
 {
-  "defaultBranches": [
-    "origin/master",
-    "origin/main",
-    "origin/release/*"
-  ],
+  "defaultBranches": ["origin/master", "origin/main", "origin/release/*"],
   "defaultSinceHours": -30,
   "defaultUntilHours": 18,
-  "authorMapping": {
-    "张三": "张三",
-    "zhangsan@company.com": "张三",
-    "zs": "张三"
-  },
+  "authorMapping": {"zhangsan@company.com": "张三"},
   "openspecDir": "openspec/",
-  "excludeExtensions": [
-    ".md",
-    ".txt",
-    ".png",
-    ".jpg",
-    ".jpeg",
-    ".gif",
-    ".svg",
-    ".ico",
-    ".webp"
-  ],
+  "excludeExtensions": [".md", ".txt", ".png", ".jpg", "..."],
   "activeUserWeeks": 2
 }
 ```
 
-### 配置选项说明
-
-- **defaultBranches**：默认追踪的分支（支持通配符）
-- **defaultSinceHours**：默认开始时间偏移（小时，负数表示往前推）
-- **defaultUntilHours**：默认结束时间（当天的小时数）
-- **authorMapping**：作者名称映射，用于统一同一人的多个 Git 账号
-- **openspecDir**：OpenSpec 提案目录（默认：`openspec/`）
-- **excludeExtensions**：排除的文件扩展名（不计入代码变更）
-- **activeUserWeeks**：活跃用户时间窗口（周，默认：2）
-
-## 统计逻辑
-
-工具会识别同时满足以下两个条件的提交：
-
-1. 包含 `openspec/` 目录中的文件变更（OpenSpec 提案）
-2. 包含代码文件变更（排除文档文件）
-
-统计内容包括：
-
-- **提交数**：符合条件的提交总数
-- **OpenSpec 提案**：按 `openspec/changes/{提案名称}` 目录统计
-- **代码文件**：修改的代码文件数量
-- **新增行数**：新增的代码行数
-- **删除行数**：删除的代码行数
-- **净变更**：新增行数 - 删除行数
-
-工具提供两个统计视角：
+关键字段：默认分支/时间窗口、作者映射（合并身份）、OpenSpec 目录、排除扩展名、活跃用户窗口。
 
-1. **提案汇总**：按提案聚合统计，显示每个提案的总代码变更量和所有贡献者，避免 merge commit 导致的统计偏差
-2. **作者汇总**：按贡献者分组统计，显示各个作者的个人贡献情况
-
-## 输出格式
-
-### 表格格式（默认）
+## 输出示例
 
 ```
-📊 OpenSpec 统计报告
-时间范围：2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
+📊 OpenSpec 统计
+时间：2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
 分支：origin/master
-总提交数：15
-
-📋 提案汇总（按提案统计）
-┌──────────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ 提案         │ 提交数  │ 贡献者           │ 代码文件   │ 新增行数  │ 删除行数  │ 净变更      │
-├──────────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
-│ feature-123  │ 5       │ 张三, 李四       │ 30         │ +890      │ -234      │ +656        │
-│ feature-456  │ 3       │ 张三             │ 15         │ +344      │ -100      │ +244        │
-└──────────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
-  📊 总计：2 个提案 | 8 次提交 | 45 个文件 | +1234/-334 行（净变更：+900）
-
-👥 作者汇总（按贡献者统计）
-┌──────────┬─────────┬──────────────────┬────────────┬───────────┬───────────┬─────────────┐
-│ 作者     │ 提交数  │ 提案数           │ 代码文件   │ 新增行数  │ 删除行数  │ 净变更      │
-├──────────┼─────────┼──────────────────┼────────────┼───────────┼───────────┼─────────────┤
-│ 张三     │ 8       │ 3                │ 45         │ +1234     │ -567      │ +667        │
-│ 李四     │ 7       │ 2                │ 32         │ +890      │ -234      │ +656        │
-└──────────┴─────────┴──────────────────┴────────────┴───────────┴───────────┴─────────────┘
+提交总数：8
+
+提案汇总
+┌──────────────┬─────────┬───────────┬───────────┐
+│ 提案         │ 提交数  │ 文件数    │ 净变更    │
+├──────────────┼─────────┼───────────┼───────────┤
+│ feature-123  │ 5       │ 30        │ +656      │
+└──────────────┴─────────┴───────────┴───────────┘
+
+作者汇总
+┌─────────┬─────────┬───────────┬───────────┐
+│ 作者    │ 提交数  │ 提案数    │ 净变更    │
+├─────────┼─────────┼───────────┼───────────┤
+│ 张三    │ 8       │ 3         │ +667      │
+└─────────┴─────────┴───────────┴───────────┘
 ```
 
-### JSON 格式
+更多格式：`--markdown`、`--json`、`--csv`。
 
-```bash
-openspec-stat --json
-```
+## 语言
 
-### CSV 格式
-
-```bash
-openspec-stat --csv > stats.csv
-```
-
-### Markdown 格式
-
-```bash
-openspec-stat --markdown > report.md
-```
-
-## 语言支持
-
-工具支持英文和中文输出。您可以使用 `--lang` 选项指定语言：
-
-```bash
-# 英文输出（默认）
-openspec-stat --lang en
-
-# 中文输出
-openspec-stat --lang zh-CN
-```
-
-工具还会自动检测您的系统语言。如果您的系统区域设置为中文，输出将默认使用中文。
+`--lang en`（默认）或 `--lang zh-CN`，支持按系统语言自动选择。
 
 ## 开发
 
 ```bash
-# 安装依赖
 pnpm install
-
-# 开发模式
 pnpm dev
-
-# 构建
 pnpm build
-
-# 本地测试
 node dist/cjs/cli.js
 ```
 
-## 贡献与发布流程
+## 贡献与发布
 
-- 请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解开发环境、分支策略和 PR 规范。
-- 请阅读 [RELEASE.md](./RELEASE.md) 了解基于 Changesets 的版本与发布流程。
+- 参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 获取开发与 PR 规范。
+- 参见 [RELEASE.md](./RELEASE.md) 了解基于 Changesets 的发布流程。
 
 ## 许可证
 

package/dist/esm/cli.js

@@ -4,7 +4,7 @@ import { runSingleRepoCommand } from "./commands/single.js";
 import { runMultiRepoCommand } from "./commands/multi.js";
 import { runInitCommand } from "./commands/init.js";
 const program = new Command();
-program.name('openspec-stat').description("Track team members' OpenSpec proposals and code changes in Git repositories").version("1.4.4").enablePositionalOptions().passThroughOptions();
+program.name('openspec-stat').description("Track team members' OpenSpec proposals and code changes in Git repositories").version("1.4.5").enablePositionalOptions().passThroughOptions();
 
 // Default command for single-repository mode (for backward compatibility)
 program.argument('[repo]', 'Repository path', '.').option('-r, --repo <path>', 'Repository path (alternative)', '.').option('-b, --branches <branches>', 'Branch list, comma-separated').option('--no-interactive', 'Disable interactive branch selection').option('-s, --since <datetime>', 'Start time (default: yesterday 20:00)').option('-u, --until <datetime>', 'End time (default: today 20:00)').option('-a, --author <name>', 'Filter by specific author').option('--json', 'Output in JSON format').option('--csv', 'Output in CSV format').option('--markdown', 'Output in Markdown format').option('-c, --config <path>', 'Configuration file path').option('-v, --verbose', 'Verbose output mode').option('-l, --lang <language>', 'Language for output (en, zh-CN)', 'en').option('--no-fetch', 'Skip fetching remote branches').action(async (repo, options) => {
@@ -13,7 +13,7 @@ program.argument('[repo]', 'Repository path', '.').option('-r, --repo <path>', '
     repo: repo || options.repo || '.'
   });
 });
-program.command('multi').description('Multi-repository analysis mode (BETA)').option('-c, --config <path>', 'Configuration file path', '.openspec-stats.multi.json').option('-s, --since <datetime>', 'Override start time').option('-u, --until <datetime>', 'Override end time').option('-a, --author <name>', 'Filter by specific author').option('--json', 'Output in JSON format').option('--csv', 'Output in CSV format').option('--markdown', 'Output in Markdown format').option('-v, --verbose', 'Verbose output mode').option('-l, --lang <language>', 'Language (en, zh-CN)', 'en').option('--no-cleanup', 'Do not cleanup temporary directories').option('--show-contributors', 'Show detailed contributor statistics (default: only show summary)').option('--no-fetch', 'Skip fetching remote branches for local repositories').action(async options => {
+program.command('multi').description('Multi-repository analysis mode (BETA)').option('-c, --config <path>', 'Configuration file path', '.openspec-stats.multi.json').option('-s, --since <datetime>', 'Override start time').option('-u, --until <datetime>', 'Override end time').option('-a, --author <name>', 'Filter by specific author').option('--json', 'Output in JSON format').option('--csv', 'Output in CSV format').option('--markdown', 'Output in Markdown format').option('-v, --verbose', 'Verbose output mode').option('-l, --lang <language>', 'Language (en, zh-CN)', 'en').option('--no-cleanup', 'Do not cleanup temporary directories').option('--cache-mode <mode>', 'Cache mode for remote repositories: persistent|temporary').option('--cache-max-age <ms>', 'Max cache age in milliseconds (optional)').option('--force-clone', 'Force fresh clone even if cache exists').option('--show-contributors', 'Show detailed contributor statistics (default: only show summary)').option('--no-fetch', 'Skip fetching remote branches for local repositories').action(async options => {
   await runMultiRepoCommand(options);
 });
 program.command('init').description('Initialize configuration file').option('--multi', 'Create multi-repository configuration (interactive)').option('--template <type>', 'Generate template (single|multi)').option('-o, --output <path>', 'Output file path').action(async options => {

package/dist/esm/commands/multi.js

@@ -12,114 +12,208 @@ export async function runMultiRepoCommand(options) {
   try {
     initI18n(options.lang || 'en');
     const isQuiet = Boolean(options.json || options.csv || options.markdown);
-    const spinner = new SpinnerManager(isQuiet);
+    const rerunKey = 'r';
+    const quitKey = 'q';
     console.log(chalk.yellow.bold(t('multi.beta.warning')));
     console.log(chalk.gray(t('multi.beta.feedback')));
     console.log();
-    if (isQuiet) {
-      console.log(chalk.blue(t('multi.loading.config')));
-    } else {
-      spinner.start(t('multi.loading.config'));
-    }
-    const configPath = resolve(process.cwd(), options.config);
-    if (!existsSync(configPath)) {
-      throw new Error(`Configuration file not found: ${configPath}`);
-    }
-    const rawConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
-    const config = validateAndFillDefaults(rawConfig);
-    if (!isQuiet) {
-      spinner.succeed();
-    }
-    if (options.verbose) {
-      printConfigSummary(config);
-    }
-    let since;
-    let until;
-    if (options.since || options.until) {
-      since = options.since ? parseDateTime(options.since) : getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours).since;
-      until = options.until ? parseDateTime(options.until) : getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours).until;
-    } else {
-      const defaultRange = getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours);
-      since = defaultRange.since;
-      until = defaultRange.until;
-    }
-    console.log(chalk.blue(t('info.timeRange', {
-      since: since.toLocaleString(),
-      until: until.toLocaleString()
-    })));
-    const analyzer = new MultiRepoAnalyzer(config, {
-      quiet: isQuiet
-    });
-    analyzer.registerCleanupHandlers();
-    if (options.cleanup === false) {
-      config.remoteCache = config.remoteCache || {
-        dir: '/tmp/openspec-stat-cache',
-        autoCleanup: false,
-        cleanupOnComplete: false,
-        cleanupOnError: false
+    const runAnalysis = async () => {
+      const spinner = new SpinnerManager(isQuiet);
+      if (isQuiet) {
+        console.log(chalk.blue(t('multi.loading.config')));
+      } else {
+        spinner.start(t('multi.loading.config'));
+      }
+      const configPath = resolve(process.cwd(), options.config);
+      if (!existsSync(configPath)) {
+        throw new Error(`Configuration file not found: ${configPath}`);
+      }
+      const rawConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const config = validateAndFillDefaults(rawConfig);
+      const ensureCacheConfig = () => {
+        if (!config.remoteCache) {
+          config.remoteCache = {
+            autoCleanup: true,
+            cleanupOnComplete: false,
+            cleanupOnError: true,
+            mode: 'persistent'
+          };
+        }
+        return config.remoteCache;
       };
-      config.remoteCache.cleanupOnComplete = false;
-    }
+      if (options.cacheMode) {
+        const cacheCfg = ensureCacheConfig();
+        cacheCfg.mode = options.cacheMode;
+        if (options.cacheMode === 'temporary') {
+          cacheCfg.cleanupOnComplete = true;
+        }
+      }
+      if (options.cacheMaxAge !== undefined) {
+        const parsed = Number(options.cacheMaxAge);
+        if (!Number.isNaN(parsed)) {
+          const cacheCfg = ensureCacheConfig();
+          cacheCfg.maxAge = parsed;
+        }
+      }
+      if (!isQuiet) {
+        spinner.succeed();
+      }
+      if (options.verbose) {
+        printConfigSummary(config);
+      }
+      let since;
+      let until;
+      if (options.since || options.until) {
+        since = options.since ? parseDateTime(options.since) : getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours).since;
+        until = options.until ? parseDateTime(options.until) : getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours).until;
+      } else {
+        const defaultRange = getDefaultTimeRange(config.defaultSinceHours, config.defaultUntilHours);
+        since = defaultRange.since;
+        until = defaultRange.until;
+      }
+      console.log(chalk.blue(t('info.timeRange', {
+        since: since.toLocaleString(),
+        until: until.toLocaleString()
+      })));
+      if (options.cleanup === false) {
+        const cacheCfg = ensureCacheConfig();
+        cacheCfg.autoCleanup = false;
+        cacheCfg.cleanupOnComplete = false;
+        cacheCfg.cleanupOnError = false;
+      }
 
-    // Handle --no-fetch option
-    if (options.noFetch) {
-      config.autoFetch = false;
-    }
-    const repoResults = await analyzer.analyzeAll(since, until);
-    const successResults = repoResults.filter(r => r.success);
-    const failedResults = repoResults.filter(r => !r.success);
-    const summaryDivider = '-'.repeat(64);
-    console.log(chalk.gray(summaryDivider));
-    console.log(chalk.blue(t('multi.summary.title')));
-    console.log(chalk.gray(summaryDivider));
-    console.log(chalk.blue(t('multi.summary.repos', {
-      total: String(repoResults.length),
-      success: String(successResults.length),
-      failed: String(failedResults.length)
-    })));
-    if (failedResults.length > 0) {
-      console.log(chalk.yellow(`\n${t('multi.summary.failedTitle')}`));
-      failedResults.forEach(r => {
-        console.log(chalk.red(`  - ${r.repository}: ${r.error}`));
+      // Handle --no-fetch option
+      if (options.noFetch) {
+        config.autoFetch = false;
+      }
+      const analyzer = new MultiRepoAnalyzer(config, {
+        quiet: isQuiet,
+        forceClone: options.forceClone
       });
-      console.log();
-    }
-    const allAnalyses = successResults.flatMap(r => r.analyses);
-    if (allAnalyses.length === 0) {
-      console.log(chalk.yellow(t('warning.noQualifyingCommits')));
+      analyzer.registerCleanupHandlers();
+      const repoResults = await analyzer.analyzeAll(since, until);
+      const successResults = repoResults.filter(r => r.success);
+      const failedResults = repoResults.filter(r => !r.success);
+      const summaryDivider = '-'.repeat(64);
+      console.log(chalk.gray(summaryDivider));
+      console.log(chalk.blue(t('multi.summary.title')));
+      console.log(chalk.gray(summaryDivider));
+      console.log(chalk.blue(t('multi.summary.repos', {
+        total: String(repoResults.length),
+        success: String(successResults.length),
+        failed: String(failedResults.length)
+      })));
+      if (failedResults.length > 0) {
+        console.log(chalk.yellow(`\n${t('multi.summary.failedTitle')}`));
+        failedResults.forEach(r => {
+          console.log(chalk.red(`  - ${r.repository}: ${r.error}`));
+        });
+        console.log();
+      }
+      const allAnalyses = successResults.flatMap(r => r.analyses);
+      if (allAnalyses.length === 0) {
+        console.log(chalk.yellow(t('warning.noQualifyingCommits')));
+        return;
+      }
+      console.log(chalk.blue(t('info.qualifyingCommits', {
+        count: String(allAnalyses.length)
+      })));
+      if (isQuiet) {
+        console.log(chalk.blue(t('loading.activeUsers')));
+      } else {
+        spinner.start(t('loading.activeUsers'));
+      }
+      const activeAuthors = await getActiveAuthorsFromMultiRepo(config, repoResults);
+      if (!isQuiet) {
+        spinner.succeed();
+      }
+      if (options.verbose && activeAuthors.size > 0) {
+        console.log(chalk.gray(t('info.activeUsers', {
+          weeks: String(config.activeUserWeeks || 2),
+          users: Array.from(activeAuthors).join(', ')
+        })));
+      }
+      const aggregator = new StatsAggregator(config, activeAuthors);
+      const allBranches = [...new Set(repoResults.flatMap(r => config.repositories?.find(repo => repo.name === r.repository)?.branches || []))];
+      const result = aggregator.aggregate(allAnalyses, since, until, allBranches, options.author);
+      const formatter = new OutputFormatter();
+      const showContributors = options.showContributors || false;
+      if (options.json) {
+        console.log(formatter.formatJSON(result, showContributors));
+      } else if (options.csv) {
+        console.log(formatter.formatCSV(result, showContributors));
+      } else if (options.markdown) {
+        console.log(formatter.formatMarkdown(result, showContributors));
+      } else {
+        console.log(formatter.formatTable(result, options.verbose, showContributors));
+      }
+    };
+    await runAnalysis();
+    if (isQuiet || !process.stdin.isTTY) {
       return;
     }
-    console.log(chalk.blue(t('info.qualifyingCommits', {
-      count: String(allAnalyses.length)
-    })));
-    if (isQuiet) {
-      console.log(chalk.blue(t('loading.activeUsers')));
-    } else {
-      spinner.start(t('loading.activeUsers'));
-    }
-    const activeAuthors = await getActiveAuthorsFromMultiRepo(config, repoResults);
-    if (!isQuiet) {
-      spinner.succeed();
-    }
-    if (options.verbose && activeAuthors.size > 0) {
-      console.log(chalk.gray(t('info.activeUsers', {
-        weeks: String(config.activeUserWeeks || 2),
-        users: Array.from(activeAuthors).join(', ')
+    const stdin = process.stdin;
+    stdin.setEncoding('utf8');
+    stdin.resume();
+    stdin.setRawMode?.(true);
+    const cleanupStdin = () => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+    };
+    const prompt = () => {
+      console.log(chalk.bgGreen.black(` ${t('multi.rerun.finished')} `));
+      const formattedRerunKey = chalk.bold(rerunKey);
+      const formattedQuitKey = chalk.bold(quitKey);
+      console.log(chalk.gray(t('multi.rerun.prompt', {
+        rerunKey: formattedRerunKey,
+        quitKey: formattedQuitKey
       })));
-    }
-    const aggregator = new StatsAggregator(config, activeAuthors);
-    const allBranches = [...new Set(repoResults.flatMap(r => config.repositories?.find(repo => repo.name === r.repository)?.branches || []))];
-    const result = aggregator.aggregate(allAnalyses, since, until, allBranches, options.author);
-    const formatter = new OutputFormatter();
-    const showContributors = options.showContributors || false;
-    if (options.json) {
-      console.log(formatter.formatJSON(result, showContributors));
-    } else if (options.csv) {
-      console.log(formatter.formatCSV(result, showContributors));
-    } else if (options.markdown) {
-      console.log(formatter.formatMarkdown(result, showContributors));
-    } else {
-      console.log(formatter.formatTable(result, options.verbose, showContributors));
+    };
+    const waitKeyPress = () => new Promise(resolve => {
+      const onData = data => {
+        stdin.off('data', onData);
+        resolve(data.toString());
+      };
+      stdin.on('data', onData);
+    });
+    console.log();
+    prompt();
+    let running = false;
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const keyRaw = await waitKeyPress();
+      const key = keyRaw[0];
+      if (!key) {
+        continue;
+      }
+      if (key === '\u0003') {
+        cleanupStdin();
+        process.exit(130);
+      }
+      const normalized = key.toLowerCase();
+      if (normalized === quitKey) {
+        cleanupStdin();
+        process.exit(130);
+        return;
+      }
+      if (normalized === rerunKey) {
+        if (running) {
+          continue;
+        }
+        running = true;
+        console.log(chalk.blue(t('multi.rerun.running')));
+        try {
+          await runAnalysis();
+        } catch (error) {
+          cleanupStdin();
+          throw error;
+        } finally {
+          running = false;
+          console.log();
+          prompt();
+        }
+      }
     }
   } catch (error) {
     console.error(chalk.red(t('error.prefix')), error);

package/dist/esm/i18n/locales/en.json

@@ -87,6 +87,7 @@
   "multi.repo.header": "  [{{current}}/{{total}}] {{repo}}{{typeSuffix}}",
   "multi.repo.type.remote": " (remote)",
   "multi.repo.cloning": "    - Cloning {{repo}}...",
+  "multi.repo.updating": "    - Updating cache for {{repo}}...",
   "multi.repo.cloned": "    - Clone completed: {{repo}}",
   "multi.repo.cloneFailed": "    - Clone failed: {{repo}} ({{error}})",
   "multi.repo.fetching": "    - Fetching remote branches...",
@@ -102,6 +103,9 @@
   "multi.progress.batch": "Processing batch {{current}}/{{total}} ({{count}} repositories)...",
   "multi.table.repository": "Repository",
   "multi.table.type": "Type",
+  "multi.rerun.finished": "FINISHED",
+  "multi.rerun.prompt": "Press {{rerunKey}} to rerun stats, {{quitKey}} to quit",
+  "multi.rerun.running": "Re-running multi-repo statistics...",
 
   "init.welcome": "\nOpenSpec Configuration Wizard\n",
   "init.welcomeMulti": "\nOpenSpec Multi-Repository Configuration Wizard (BETA)\n",

package/dist/esm/i18n/locales/zh-CN.json

@@ -87,6 +87,7 @@
   "multi.repo.header": "  [{{current}}/{{total}}] {{repo}}{{typeSuffix}}",
   "multi.repo.type.remote": "（远程）",
   "multi.repo.cloning": "    - 正在克隆 {{repo}}...",
+  "multi.repo.updating": "    - 正在更新缓存 {{repo}}...",
   "multi.repo.cloned": "    - 克隆完成：{{repo}}",
   "multi.repo.cloneFailed": "    - 克隆失败：{{repo}}（{{error}}）",
   "multi.repo.fetching": "    - 正在拉取远程分支...",
@@ -102,6 +103,9 @@
   "multi.progress.batch": "正在处理批次 {{current}}/{{total}}（{{count}} 个仓库）...",
   "multi.table.repository": "仓库",
   "multi.table.type": "类型",
+  "multi.rerun.finished": "已完成",
+  "multi.rerun.prompt": "按 {{rerunKey}} 重新运行统计，按 {{quitKey}} 退出",
+  "multi.rerun.running": "正在重新运行多仓库统计...",
 
   "init.welcome": "\nOpenSpec 配置向导\n",
   "init.welcomeMulti": "\nOpenSpec 多仓库配置向导（测试版）\n",

package/dist/esm/multi/cache-path.js

@@ -0,0 +1,12 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+export const GLOBAL_CACHE_DIR = join(homedir(), '.openspec-stat', 'cached', 'repos');
+export function ensureGlobalCacheDir() {
+  if (!existsSync(GLOBAL_CACHE_DIR)) {
+    mkdirSync(GLOBAL_CACHE_DIR, {
+      recursive: true
+    });
+  }
+  return GLOBAL_CACHE_DIR;
+}

package/dist/esm/multi/config-validator.js

@@ -1,3 +1,4 @@
+import { GLOBAL_CACHE_DIR } from "./cache-path.js";
 import chalk from 'chalk';
 import { t } from "../i18n/index.js";
 const DEFAULT_MULTI_REPO_CONFIG = {
@@ -13,10 +14,10 @@ const DEFAULT_MULTI_REPO_CONFIG = {
     timeout: 600000
   },
   remoteCache: {
-    dir: '/tmp/openspec-stat-cache',
     autoCleanup: true,
-    cleanupOnComplete: true,
-    cleanupOnError: true
+    cleanupOnComplete: false,
+    cleanupOnError: true,
+    mode: 'persistent'
   }
 };
 export function validateAndFillDefaults(config) {
@@ -99,7 +100,7 @@ export function printConfigSummary(config) {
   }));
   console.log(chalk.cyan(t('config.summary.remoteCache')));
   console.log(t('config.summary.cacheDir', {
-    dir: config.remoteCache?.dir || '/tmp/openspec-stat-cache'
+    dir: GLOBAL_CACHE_DIR
   }));
   console.log(t('config.summary.autoCleanup', {
     enabled: config.remoteCache?.cleanupOnComplete ? 'Yes' : 'No'

package/dist/esm/multi/multi-repo-analyzer.js

@@ -1,21 +1,25 @@
 import simpleGit from 'simple-git';
-import { mkdtempSync, rmSync, existsSync, mkdirSync } from 'fs';
-import { tmpdir } from 'os';
+import { mkdtempSync, rmSync, existsSync, statSync } from 'fs';
 import { join, resolve } from 'path';
+import { createHash } from 'crypto';
 import chalk from 'chalk';
 import { GitAnalyzer } from "../git-analyzer.js";
 import { t } from "../i18n/index.js";
 import { SpinnerManager } from "../ui/spinner.js";
+import { ensureGlobalCacheDir } from "./cache-path.js";
 export class MultiRepoAnalyzer {
   config;
   tempDirs = new Set();
   isQuiet;
+  forceClone;
+  shouldCleanupTemps = false;
   cloneOrder = new Map();
   totalCloneTargets = 0;
   nextCloneIndex = 1;
   constructor(config, options) {
     this.config = config;
     this.isQuiet = options?.quiet ?? false;
+    this.forceClone = options?.forceClone ?? false;
   }
   async analyzeAll(since, until) {
     const repos = this.config.repositories || [];
@@ -23,6 +27,7 @@ export class MultiRepoAnalyzer {
     this.cloneOrder.clear();
     this.nextCloneIndex = 1;
     this.totalCloneTargets = enabledRepos.filter(repo => repo.type === 'remote').length;
+    let hadError = false;
     try {
       const localRepos = enabledRepos.filter(repo => repo.type === 'local');
       const remoteRepos = enabledRepos.filter(repo => repo.type === 'remote');
@@ -30,8 +35,12 @@ export class MultiRepoAnalyzer {
       const localResults = await this.processInBatches(localRepos, (repo, context) => this.analyzeRepository(repo, since, until, context), maxConcurrent);
       const remoteResults = await this.processInBatches(remoteRepos, (repo, context) => this.analyzeRepository(repo, since, until, context), maxConcurrent);
       return [...localResults, ...remoteResults];
+    } catch (error) {
+      hadError = true;
+      throw error;
     } finally {
-      if (this.config.remoteCache?.cleanupOnComplete) {
+      const shouldCleanup = Boolean(this.config.remoteCache?.cleanupOnComplete || this.config.remoteCache?.cleanupOnError && hadError || this.shouldCleanupTemps);
+      if (shouldCleanup) {
         await this.cleanupTempDirs();
       }
     }
@@ -115,14 +124,102 @@ export class MultiRepoAnalyzer {
     }
   }
   async cloneRemoteRepository(repo) {
-    const cacheDir = this.config.remoteCache?.dir || join(tmpdir(), 'openspec-stat-cache');
-    if (!existsSync(cacheDir)) {
-      mkdirSync(cacheDir, {
-        recursive: true
+    const cacheMode = repo.cacheMode || this.config.remoteCache?.mode || 'persistent';
+    if (cacheMode === 'temporary') {
+      this.shouldCleanupTemps = true;
+      return this.cloneToTempDirectory(repo);
+    }
+    const cachePath = this.getCacheRepoPath(repo);
+    const timeout = this.config.parallelism?.timeout || 600000;
+    const validCache = this.forceClone ? false : await this.isCacheValid(cachePath, repo.url);
+    if (validCache) {
+      console.log(chalk.cyan(t('multi.repo.updating', {
+        repo: repo.name
+      })));
+      await this.withTimeout(this.updateCachedRepository(cachePath, repo), timeout, `Update timeout for ${repo.name}`);
+      return cachePath;
+    }
+    if (existsSync(cachePath)) {
+      rmSync(cachePath, {
+        recursive: true,
+        force: true
       });
     }
-    const tempDir = mkdtempSync(join(cacheDir, `${repo.name}-`));
+    return this.cloneToPath(cachePath, repo, false);
+  }
+  ensureCacheDir() {
+    return ensureGlobalCacheDir();
+  }
+  getCacheRepoPath(repo) {
+    const baseDir = this.ensureCacheDir();
+    const safeName = this.getSafeRepoName(repo);
+    const hash = createHash('sha256').update(repo.url || repo.name).digest('hex');
+    const id = hash.slice(0, 12);
+    return join(baseDir, `${safeName}-${id}`);
+  }
+  getSafeRepoName(repo) {
+    const sanitize = value => {
+      return value.replace(/[^a-zA-Z0-9-_]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+    };
+    const fromName = repo.name ? sanitize(repo.name) : '';
+    if (fromName) return fromName;
+    const rawUrl = repo.url || '';
+    const normalizedUrl = rawUrl.startsWith('git@') ? `ssh://${rawUrl.replace(':', '/')}` : rawUrl;
+    try {
+      const parsed = new URL(normalizedUrl);
+      const parts = parsed.pathname.split('/').filter(Boolean);
+      const repoPart = parts.pop();
+      const ownerPart = parts.pop();
+      const base = repoPart ? repoPart.replace(/\.git$/, '') : ownerPart;
+      const combined = ownerPart && base ? `${ownerPart}-${base}` : base;
+      const cleaned = combined ? sanitize(combined) : '';
+      if (cleaned) return cleaned;
+    } catch {
+      // ignore parsing errors and fallback
+    }
+    return 'repo';
+  }
+  async isCacheValid(cachePath, repoUrl) {
+    if (!existsSync(cachePath)) return false;
+    if (!existsSync(join(cachePath, '.git'))) return false;
+    const maxAge = this.config.remoteCache?.maxAge;
+    if (maxAge !== undefined) {
+      try {
+        const stats = statSync(cachePath);
+        if (Date.now() - stats.mtimeMs > maxAge) {
+          return false;
+        }
+      } catch {
+        return false;
+      }
+    }
+    try {
+      const git = simpleGit(cachePath);
+      const remotes = await git.getRemotes(true);
+      const originUrl = remotes.find(r => r.name === 'origin')?.refs?.fetch;
+      return originUrl === repoUrl;
+    } catch {
+      return false;
+    }
+  }
+  buildCloneArgs(repo) {
+    const cloneArgs = ['--progress'];
+    if (repo.cloneOptions?.depth !== null && repo.cloneOptions?.depth !== undefined) {
+      cloneArgs.push(`--depth=${repo.cloneOptions.depth}`);
+    }
+    if (repo.cloneOptions?.singleBranch) {
+      cloneArgs.push('--single-branch');
+    }
+    return cloneArgs;
+  }
+  async cloneToTempDirectory(repo) {
+    const cacheDir = this.ensureCacheDir();
+    const safeName = this.getSafeRepoName(repo);
+    const tempDir = mkdtempSync(join(cacheDir, `${safeName}-tmp-`));
     this.tempDirs.add(tempDir);
+    return this.cloneToPath(tempDir, repo, true);
+  }
+  async cloneToPath(targetPath, repo, trackTemp) {
     const progressSuffix = this.getProgressSuffix(repo.name);
     const cloneSpinner = this.isQuiet ? undefined : new SpinnerManager(false);
     this.reportCloneStatus('start', repo.name, progressSuffix, cloneSpinner);
@@ -145,27 +242,35 @@ export class MultiRepoAnalyzer {
     const git = simpleGit({
       progress: progressReporter
     });
-    const cloneArgs = [];
-
-    // Enable git's progress output so simple-git can emit progress events
-    cloneArgs.push('--progress');
-    if (repo.cloneOptions?.depth !== null && repo.cloneOptions?.depth !== undefined) {
-      cloneArgs.push(`--depth=${repo.cloneOptions.depth}`);
-    }
-    if (repo.cloneOptions?.singleBranch) {
-      cloneArgs.push('--single-branch');
-    }
+    const cloneArgs = this.buildCloneArgs(repo);
     const timeout = this.config.parallelism?.timeout || 600000;
     try {
-      await this.withTimeout(git.clone(repo.url, tempDir, cloneArgs), timeout, `Clone timeout for ${repo.name}`);
+      await this.withTimeout(git.clone(repo.url, targetPath, cloneArgs), timeout, `Clone timeout for ${repo.name}`);
       this.reportCloneStatus('success', repo.name, progressSuffix, cloneSpinner);
-      return tempDir;
+      if (trackTemp) {
+        this.tempDirs.add(targetPath);
+      }
+      return targetPath;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.reportCloneStatus('fail', repo.name, progressSuffix, cloneSpinner, errorMessage);
       throw error;
     }
   }
+  async updateCachedRepository(cachePath, repo) {
+    const git = simpleGit(cachePath);
+    const timeout = this.config.parallelism?.timeout || 600000;
+    await this.withTimeout(git.fetch(['--all', '--prune']), timeout, `Fetch timeout for ${repo.name}`);
+    if (repo.branches.length > 0) {
+      const mainBranch = repo.branches[0].replace(/^origin\//, '');
+      try {
+        await git.checkout(mainBranch);
+        await git.reset(['--hard', `origin/${mainBranch}`]);
+      } catch {
+        // If branch checkout fails, continue with fetched state
+      }
+    }
+  }
   resolveLocalPath(path) {
     if (path.startsWith('/') || path.match(/^[A-Za-z]:\\/)) {
       return path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-stat",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "Track team members' OpenSpec proposals and code changes in Git repositories",
   "type": "module",
   "main": "dist/esm/index.js",