内容
# 季度报告工具
**基于人工智能的季度成绩评估自动化工具，用于生成季度成绩报告。**
将季度评估准备时间从 **4-6 小时** 缩短至 **30 分钟**，通过自动化数据聚合、周期时间分析、成绩排名和叙述优化。
## 功能
- **周期时间分析**：识别运行时间最长的 PR 和 Jira 问题（战略性工作）
- **智能成绩排名**：根据周期时间、基础设施关键词和复杂度进行评分
- **三种叙述框架**：业务影响、技术深度或领导力框架
- **多平台支持**：Jira、GitHub、GitLab 数据聚合
- **三种使用模式**：Claude Code 技能、Cursor/IDE 无关或 MCP 服务器
## 快速入门
根据您的 IDE 和使用模式选择合适的使用方式：
### 1. Claude Code 技能
**最适合：** 在 Claude Code 中使用季度报告（每季度一次）
```bash
# 安装 CLI 工具
brew install jira-cli gh
jira init && gh auth login
# 克隆到插件目录
mkdir -p ~/.claude/plugins && cd ~/.claude/plugins
git clone https://github.com/redhat-community-ai-tools/quarterly-mcp-server.git quarterly-report-assistant
# 使用它
# 在 Claude Code 中：/quarterly-report
```
**原因：** 按需加载（令牌高效），简单的基于 CLI 的设置
### 2. Cursor / 任意 IDE
**最适合：** Cursor、Windsurf、Zed 或任意带有 Claude 的 IDE
```bash
# 安装 CLI 工具
brew install jira-cli gh
jira init && gh auth login
# 添加到您的 workspace
cd your-project
curl -O https://raw.githubusercontent.com/redhat-community-ai-tools/quarterly-mcp-server/master/QUARTERLY_REPORT_ASSISTANT.md
curl -O https://raw.githubusercontent.com/redhat-community-ai-tools/quarterly-mcp-server/master/.cursorrules
# 在 Cursor 中使用
# @QUARTERLY_REPORT_ASSISTANT.md generate my Q1 2026 report
```
**原因：** 在任意 IDE 中工作， 便携，无供应商锁定
### 3. MCP 服务器
**最适合：** 频繁查询、自动化、每日 Jira/GitHub 查询
```bash
# 使用 Python 设置 MCP 服务器
git clone https://github.com/redhat-community-ai-tools/quarterly-mcp-server.git
cd quarterly-mcp-server
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 配置和注册
# 查看 INSTALLATION.md 中的完整说明
```
**原因：** 始终可用的工具、程序化 API、自动化友好
---
**需要帮助选择？** 查看 [INSTALLATION.md](INSTALLATION.md) 以获取详细的比较。
---
## 您将获得
与其手动编写：
> "在 5 个版本中添加了 AWS UPI 作业"
您将获得 AI 优化的叙述：
> "我为企业客户启用了全面的 Windows 测试，使用用户配置的基础设施，交付了一个涵盖 5 个活跃的 OpenShift 版本（4.18-4.22）的单一 PR，而不是单独的努力。这展示了高效的交付和多版本思考 - 从创建到生产部署仅需 8 天，跨越 25 个文件，共 1,156 行。许多企业客户使用 UPI 而不是 IPI，此 PR 关闭了一个主要的平台覆盖缺口。"
## 完整文档
- **[INSTALLATION.md](INSTALLATION.md)** - 所有三种模式的完整安装指南
- **[QUARTERLY_REPORT_ASSISTANT.md](QUARTERLY_REPORT_ASSISTANT.md)** - 完整的 workflow 说明
- **[.claude-code/README.md](.claude-code/README.md)** - Claude Code 技能文档
- **MCP 服务器 API** - 参见以下章节
---
# MCP 服务器文档
## 功能
- **多平台聚合**：结合来自 Jira、GitHub 和 GitLab 的数据
- **灵活的日期范围**：查询任意时间段，内置季度报告生成
- **丰富的统计数据**：工单数量、PR 数量、关闭率、按状态/类型/优先级分类
- **周期时间分析**：识别运行时间最长的 PR 和问题，附带平均周期时间
- **基于 AI 的成绩识别**：根据周期时间、影响或复杂度对成绩进行排名
- **成绩优化**：将技术描述转换为精致的绩效评估叙述
- **MCP 集成**：与 Claude Code、Claude Desktop 和其他 MCP 客户端配合使用
- **团队友好**：任何拥有 MCP 的人都可以为自己的季度评估使用它
## 快速入门
### 1. 安装
```bash
git clone https://github.com/redhat-community-ai-tools/quarterly-mcp-server.git
cd quarterly-mcp-server
python3 -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
pip install -r requirements.txt
```
### 2. 配置
创建 `~/.quarterly-mcp-config.json`：
```json
{
"JIRA_URL": "https://your-jira-instance.atlassian.net",
"JIRA_EMAIL": "your-email@example.com",
"JIRA_API_TOKEN": "your-jira-api-token",
"GITHUB_TOKEN": "your-github-personal-access-token",
"GITLAB_URL": "https://gitlab.com",
"GITLAB_TOKEN": "your-gitlab-token"
}
```
**获取 API 令牌：**
- **Jira**：https://id.atlassian.com/manage-profile/security/api-tokens
- **GitHub**：https://github.com/settings/tokens （需要 `repo` 作用域）
- **GitLab**：https://gitlab.com/-/profile/personal_access_tokens （需要 `read_api` 作用域）
**注意：** GitLab 为可选。如果您不使用 GitLab，请省略 `GITLAB_TOKEN`。
### 3. 在 Claude Code 中注册
```bash
claude mcp add quarterly /path/to/quarterly-mcp-server/venv/bin/python -- /path/to/quarterly-mcp-server/server.py
```
验证注册：
```bash
claude mcp list
```
### 4. 测试它
启动 Claude Code 会话并询问：
```
Generate my Q1 2026 quarterly report (username: myusername, jira project: MYPROJECT, github org: myorg)
```
## MCP 工具
服务器为在 Claude Code 或其他 MCP 客户端中使用而公开了这些工具：
### `get_jira_summary`
获取指定日期范围内的 Jira 工单摘要。
**参数：**
- `username` （必填）：Jira 用户名或邮箱
- `start_date` （必填）：开始日期（YYYY-MM-DD）
- `end_date` （必填）：结束日期（YYYY-MM-DD）
- `project` （可选）：项目密钥过滤器（例如 'WINC'）
**示例：**
```
Get my Jira summary for Q1 2026 (username: rrasouli@redhat.com, project: WINC, start: 2026-01-01, end: 2026-03-31)
```
### `get_github_summary`
获取指定日期范围内的 GitHub PR Summary。
**参数：**
- `username` （必填）：GitHub 用户名
- `start_date` （必填）：开始日期（YYYY-MM-DD）
- `end_date` （必填）：结束日期（YYYY-MM-DD）
- `org` （可选）：组织过滤器（例如 'openshift'）
**示例：**
```
Get my GitHub PRs for Q1 2026 (username: rrasouli, org: openshift, start: 2026-01-01, end: 2026-03-31)
```
### `get_gitlab_summary`
获取指定日期范围内的 GitLab MR Summary。
**参数：**
- `username` （必填）：GitLab 用户名
- `start_date` （必填）：开始日期（YYYY-MM-DD）
- `end_date` （必填）：结束日期（YYYY-MM-DD）
- `group` （可选）：组过滤器（例如 'winc'）
**示例：**
```
Get my GitLab MRs for Q1 2026 (username: rrasouli, group: winc, start: 2026-01-01, end: 2026-03-31)
```
### `generate_quarterly_report`
生成结合所有平台的综合季度成绩报告。
**参数：**
- `username` （必填）：用户名（跨平台相同）
- `quarter` （必填）：季度编号（1-4）
- `year` （必填）：年份（例如 2026）
- `jira_project` （可选）：Jira 项目过滤器
- `github_org` （可选）：GitHub 组织过滤器
- `gitlab_group` （可选）：GitLab 组过滤器
**示例：**
```
Generate my Q2 2026 quarterly report (username: rrasouli, quarter: 2, year: 2026, jira_project: WINC, github_org: openshift)
```
### `analyze_cycle_times`
分析 Jira 问题和 GitHub PR 的周期时间，以识别运行时间最长的作业。
**参数：**
- `username` （必填）：基本用户名（如果未提供特定于平台的用户名，则使用）
- `start_date` （必填）：开始日期（YYYY-MM-DD）
- `end_date` （必填）：结束日期（YYYY-MM-DD）
- `jira_project` （可选）：Jira 项目过滤器
- `github_org` （可选）：GitHub 组织过滤器
- `jira_username` （可选）：Jira 特定用户名（邮箱）
- `github_username` （可选）：GitHub 特定用户名
- `top_n` （可选）：返回的顶部项目数量（默认：10）
**返回：** 包含平均周期时间和来自两个平台的运行时间最长的项目 JSON。
**示例：**
```
Analyze my cycle times for Q1 2026 (username: rrasouli, jira_username: rrasouli@redhat.com, start_date: 2026-01-01, end_date: 2026-03-31, jira_project: WINC, github_org: openshift)
```
### `identify_top_achievements`
根据周期时间、影响或复杂度识别顶级成绩。
**参数：**
- `username` （必填）：基本用户名
- `start_date` （必填）：开始日期（YYYY-MM-DD）
- `end_date` （必填）：结束日期（YYYY-MM-DD）
- `metric` （可选）：排名指标 - "cycle_time"（最长的作业）、"impact"（最复杂的）或 "recent"（最新的）。默认："cycle_time"
- `jira_project` （可选）：Jira 项目过滤器
- `github_org` （可选）：GitHub 组织过滤器
- `jira_username` （可选）：Jira 特定用户名
- `github_username` （可选）：GitHub 特定用户名
- `top_n` （可选）：返回的顶级成绩数量（默认：5）
**返回：** 包含排名成绩和叙述构建上下文的 JSON。
**示例：**
```
Identify my top 5 achievements by impact for Q1 2026 (username: rrasouli, metric: impact, start_date: 2026-01-01, end_date: 2026-03-31)
```
### `refine_achievement`
将技术 PR/Jira 描述转换为精致的成绩叙述，用于绩效评估。
**参数：**
- `raw_description` （必填）：技术描述（例如 "在 5 个版本中添加了 AWS UPI 作业"）
- `context` （可选）：附加上下文（PR 元数据，Jira 详细信息，团队影响）
- `style` （可选）：叙述风格 - "business_impact"， "technical_depth" 或 "leadership"。默认："business_impact"
**返回：** 用于将技术描述转换为精致叙述的优化指南和示例。
**示例：**
```
Refine this achievement: "Added AWS UPI jobs across 5 releases" with business_impact style
```
## 使用示例
### 基本季度报告
```
Generate my Q1 2026 quarterly report (username: jdoe, quarter: 1, year: 2026)
```
### 按项目/组织过滤
```
Generate my Q2 2026 report for WINC project and openshift org (username: jdoe, quarter: 2, year: 2026, jira_project: WINC, github_org: openshift)
```
### 自定义日期范围
```
Get my Jira summary from 2026-01-15 to 2026-02-15 (username: jdoe, start_date: 2026-01-15, end_date: 2026-02-15)
```
### 单个平台查询
```
Get my GitHub PRs merged in March 2026 (username: jdoe, start_date: 2026-03-01, end_date: 2026-03-31, org: redhat)
```
### 基于 AI 的绩效评估工作流程
**步骤 1：分析周期时间**
```
Analyze my Q1 2026 cycle times (username: jdoe, jira_username: jdoe@company.com, start_date: 2026-01-01, end_date: 2026-03-31, jira_project: MYPROJECT, github_org: myorg)
```
**步骤 2：识别顶级成绩**
```
Identify my top 5 achievements by impact for Q1 2026 (username: jdoe, metric: impact, start_date: 2026-01-01, end_date: 2026-03-31)
```
**步骤 3：优化每个成绩**
```
Refine this achievement: "Added infrastructure support for BYOH provisioning" with business_impact style and context: "37 files changed, +666 lines, 17 days, enables all future BYOH testing"
```
**步骤 4：生成完整报告**
```
Generate my Q1 2026 quarterly report (username: jdoe, quarter: 1, year: 2026, jira_project: MYPROJECT, github_org: myorg)
```
此工作流程将数小时的手动评估准备时间转换为 30 分钟的聚焦优化。
## 输出格式
`generate_quarterly_report` 工具生成一份 Markdown 报告，包含：
- **执行摘要**：跨所有平台的高级统计数据
- **Jira 活动**：总工单数量、关闭率、按状态/类型/优先级分类
- **GitHub 活动**：合并的 PR 总数、按存储库分类
- **GitLab 活动**：合并的 MR 总数、按项目分类（如果配置）
- **详细成就**：关闭的工单和合并的 PR/MR 列表
## 适用于经理
经理可以使用此工具：
1. **生成团队报告**：查询每个团队成员的成就
2. **比较季度**：跟踪团队速度随时间的变化
3. **识别瓶颈**：查看关闭率和正在进行的作业
4. **聚合指标**：合并个人报告生成团队级摘要
示例管理器查询：
```
Generate quarterly reports for my team (Alice: alice@example.com, Bob: bob@example.com, Carol: carol@example.com) for Q1 2026 in the TEAM project
```
## 配置选项
您可以配置服务器通过：
1. **配置文件** (`~/.quarterly-mcp-config.json`)
2. **环境变量** （覆盖配置文件值）：
- `JIRA_URL`
- `JIRA_EMAIL`
- `JIRA_API_TOKEN`
- `GITHUB_TOKEN`
- `GITLAB_URL`
- `GITLAB_TOKEN`
环境变量优先于配置文件值。
## 故障排除
### "Jira 配置缺失" 错误
确保 `JIRA_URL` 和 `JIRA_API_TOKEN` 在您的配置文件或环境中设置。
### "GitHub 令牌缺失" 错误
确保 `GITHUB_TOKEN` 在您的配置文件或环境中设置。
### 身份验证失败
- **Jira**：验证您的邮箱和 API 令牌是否正确
- **GitHub**：确保您的令牌具有 `repo` 作用域
- **GitLab**：确保您的令牌具有 `read_api` 作用域
### 未返回结果
- 检查日期范围（YYYY-MM-DD 格式）
- 验证用户名是否与您的平台用户名匹配
- 对于 Jira：检查项目密钥是否正确
- 对于 GitHub：检查组织名称是否正确
## 贡献
欢迎贡献！此工具设计用于 Red Hat 社区，但对任何进行季度评估的人都很有用。
**如何贡献：**
1. 分叉仓库
2. 创建一个功能分支
3. 进行更改
4. 提交拉取请求
**贡献想法：**
- 支持其他平台（Linear、Asana、Prow CI、Jenkins）
- 导出到不同格式（CSV、JSON、PDF）
- 识别矿业（从 PR/问题评论中提取同行肯定）
- 团队聚合功能
- 交互式评估对话框（引导式成就叙述构建）
- 数据驱动的目标设定（根据历史速度建议目标）
- Slack/email 集成用于自动化报告
## 许可证
Apache License 2.0 - 查看 [LICENSE](LICENSE) 获取详情。
## 相关项目
- [ci-failure-tracker](https://github.com/redhat-community-ai-tools/ci-failure-tracker) - 自动 CI 失败跟踪和报告
- [ci-dashboard](https://github.com/redhat-community-ai-tools/ci-dashboard) - CI 测试通过率可视化
## 支持
- **问题**：https://github.com/redhat-community-ai-tools/quarterly-mcp-server/issues
- **讨论**：https://github.com/redhat-community-ai-tools/quarterly-mcp-server/discussions
---
**Built with FastMCP** | **Part of the Red Hat Community AI Tools**
