sergicollado8/metrics-insight

# Metrics 洞察 `Metrics Insight` 是一款工程生产力工具，旨在通过 GitHub 数据（即将支持 Jira）分析团队绩效。它遵循**六边形架构** (Hexagonal Architecture)，并在所有计算中使用**工作时间 (08:00 - 20:00, 周一至周五, UTC)**。 ## 主要功能 - **获取指标：** 计算特定日期范围内的 PR Size、Life Time、Time to 1st Human Review 和 Rework。 - **Sprint 对比：** 跨多个时间窗口追踪团队轨迹（按 Sprint 进行分析）。 - **GitHub Actions 指标：** 分析 CI/CD 性能（持续时间、成功率及瓶颈）。 - **输出分组：** 在特定于仓库的子文件夹 (`output/{owner}_{repo}/`) 中自动组织 CSV。 ## 前置条件 - **Python 3.13+** - 具备 `repo` 范围的 **GitHub Personal Access Token**（经典或细粒度）。 - **Google Gemini API Key**（可选，用于 AI 驱动的功能）。 ## 安装与设置 ### 使用 Docker（推荐） 运行 `Metrics Insight` 最简单的方法是使用 Docker。这能确保所有的依赖项和 Python 版本都得到正确配置。 1. **克隆仓库：** git clone cd metrics_insight 2. **配置环境：** 在根目录中创建一个 `.env` 文件（以 `.env.template` 作为参考）： GITHUB_TOKEN=your_github_token GEMINI_API_KEY=your_gemini_api_key # 可选 3. **构建镜像：** make docker-build ### 本地安装（开发） 如果您希望在本地运行或为代码做贡献： ``` make install ``` ## 使用方法 该工具提供了多个命令。使用 Docker 时，请使用 `make docker-run ARGS=" "`，以确保加载您的 `.env` 并同步您的 `output/` 文件夹。 ### 1. 获取基本指标 提取 PR 指标并将其保存到 CSV。如果提供了 Gemini API 密钥，还会执行 AI 分析。 ``` make docker-run ARGS="fetch --repo owner/repo --start 2024-01-01 --end 2024-03-31" ``` ### 2. 比较 Sprint（轨迹） 比较多个时间窗口，查看团队绩效是否有所提升。 ``` make docker-run ARGS="compare --repo owner/repo --start 2024-01-01 --weeks 2 --sprints 4" ``` ### 3. 分析 GitHub Actions 分析工作流的执行时间和成功率。 ``` make docker-run ARGS="actions --repo owner/repo --start 2024-01-01 --end 2024-03-31" ``` *注意：对于不使用 Docker 的本地执行，请将 `make docker-run ARGS="..."` 替换为 `make ARGS="..."`（例如，用于获取数据的 `make run ARGS="..."`）。* ## 指标定义 - **PR Size：** 更改的总行数（additions + deletions）。 - **PR Life Time：** 从创建到合并/关闭的持续时间（工作时间）。 - **Time to 1st Review：** 从创建到首次人工审查的持续时间（工作时间）。 - **Rework：** 首次人工审查之后的提交次数（不包括合并）。 - **Success Rate (Actions)：** 以 `success` 结束的工作流运行百分比。 ## 项目结构 本项目遵循严格的**六边形架构**（端口与适配器）： - `src/metrics_insight/domain/`：纯业务逻辑、实体和 repository 接口（端口）。 - `src/metrics_insight/application/`：编排领域逻辑的用例。 - `src/metrics_insight/infrastructure/`： - `github/`：GitHub API 的适配器（使用 PyGithub）。 - `csv/`：用于导出 CSV 的适配器。 - `cli/`：命令行界面（使用 Click 和 Rich）。 - `ai/`：Google Gemini（生成式 AI）的适配器。 - `tests/`： - `unit/`：针对领域和应用逻辑的快速测试。 - `integration/`：针对基础设施适配器的测试。 - `acceptance/`：端到端工具验证。 ## 开发与质量标准 **强制性要求：** 每一项新功能和逻辑更改都必须包含相关的测试。 ### 命令 - **测试：** `make test`（运行 pytest） - **代码检查：** `make lint`（运行 ruff 和 mypy） - **构建：** `make build`（创建本地包） - **Docker：** `make docker-build` 和 `make docker-run` ## 许可证 MIT

标签：AI分析, API集成, CI/CD分析, DLL 劫持, Docker, GitHub Actions, GitHub集成, Hexagonal Architecture, PR分析, Python, Sprint分析, 代码审查, 企业级工具, 六边形架构, 可观测性, 团队绩效, 大语言模型, 安全规则引擎, 安全防御评估, 工程效能, 敏捷开发, 无后门, 瓶颈检测, 研发度量, 研发效能, 自动化报告, 自动笔记, 请求拦截, 软件工程管理, 逆向工具