openspec-stat

用于追踪团队成员在 Git 仓库中的 OpenSpec 提案与代码变更的命令行工具。

English | 简体中文

安装

# 全局安装
npm install -g openspec-stat
# 或项目内开发依赖
npm install -D openspec-stat

快速开始

默认时间窗口：昨天 20:00 → 今天 20:00。

# 基础运行
openspec-stat

# 自定义时间范围
openspec-stat --since "2024-01-01 00:00:00" --until "2024-01-31 23:59:59"

# 多仓库（需配置文件）
openspec-stat multi -c .openspec-stats.multi.json

关键特性

• 按时间窗口与分支过滤追踪 Git 提交
• 识别同时包含 OpenSpec 提案与代码变更的提交
• 提案维度聚合，避免 merge commit 统计偏差
• 作者分组与名称映射（合并多个 Git 身份）
• 多分支通配与 多仓库模式（BETA）
• 输出：表格、JSON、CSV、Markdown；语言：en / zh-CN

常用参数（完整见 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：详细模式

多仓库模式（BETA）

一次运行分析多个本地/远程仓库。

openspec-stat init --multi                         # 交互式初始化
openspec-stat multi -c .openspec-stats.multi.json  # 聚合视图
openspec-stat multi -c .openspec-stats.multi.json --show-contributors

详见 多仓库模式指南。

远程缓存：远程仓库会首次克隆后复用，路径为 ~/.openspec-stat/cached/repos/<仓库名>-<哈希>。使用 --cache-mode temporary 可改为一次性克隆，或用 --force-clone 在单次运行中强制重新克隆。

配置（简版）

在仓库根目录创建 .openspec-stats.json 或 openspec-stats.config.json。

{
  "defaultBranches": ["origin/master", "origin/main", "origin/release/*"],
  "defaultSinceHours": -30,
  "defaultUntilHours": 18,
  "authorMapping": {"[email protected]": "张三"},
  "openspecDir": "openspec/",
  "excludeExtensions": [".md", ".txt", ".png", ".jpg", "..."],
  "activeUserWeeks": 2
}

关键字段：默认分支/时间窗口、作者映射（合并身份）、OpenSpec 目录、排除扩展名、活跃用户窗口。

输出示例

📊 OpenSpec 统计
时间：2024-01-01 00:00:00 ~ 2024-01-31 23:59:59
分支：origin/master
提交总数：8

提案汇总
┌──────────────┬─────────┬───────────┬───────────┐
│ 提案         │ 提交数  │ 文件数    │ 净变更    │
├──────────────┼─────────┼───────────┼───────────┤
│ feature-123  │ 5       │ 30        │ +656      │
└──────────────┴─────────┴───────────┴───────────┘

作者汇总
┌─────────┬─────────┬───────────┬───────────┐
│ 作者    │ 提交数  │ 提案数    │ 净变更    │
├─────────┼─────────┼───────────┼───────────┤
│ 张三    │ 8       │ 3         │ +667      │
└─────────┴─────────┴───────────┴───────────┘

更多格式：--markdown、--json、--csv。

语言

--lang en（默认）或 --lang zh-CN，支持按系统语言自动选择。

开发

pnpm install
pnpm dev
pnpm build
node dist/cjs/cli.js

贡献与发布

• 参见 CONTRIBUTING.md 获取开发与 PR 规范。
• 参见 RELEASE.md 了解基于 Changesets 的发布流程。

许可证

MIT