gitlink-cli/skills/gitlink-workflow/references/workflow-sprint-report.md

550 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Workflow: Sprint ReportSprint 报告)
> **前置条件:** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **AI Agent 工作流**:此工作流专为 AI Agent 设计,用于自动生成 Sprint 进度报告。
AI Agent 自动汇总 Sprint 期间的 Issue、PR、提交记录等数据生成结构化的进度报告帮助团队了解项目进展。
## 工作流概述
Sprint Report 工作流收集 Sprint 期间的所有活动数据,包括 Issue 完成情况、PR 合并状态、代码提交统计、团队成员贡献等,自动生成团队进度报告。
## 适用场景
- **Sprint 回顾**:为 Sprint 回顾会议提供数据支持
- **进度汇报**:向管理层汇报项目进展
- **团队协调**:协调团队工作计划和资源分配
- **绩效评估**:评估团队和个人的工作效率
## 工作流步骤
### 步骤 1确定报告时间范围
```bash
# 设置 Sprint 时间范围(通常为 2 周)
SPRINT_START="2026-01-01"
SPRINT_END="2026-01-14"
# 或者基于当前时间计算
SPRINT_END=$(date +%Y-%m-%d)
SPRINT_START=$(date -d "14 days ago" +%Y-%m-%d)
```
### 步骤 2获取 Issue 统计
```bash
# 获取 Sprint 期间关闭的 Issue
CLOSED_ISSUES=$(gitlink-cli issue +list --state closed --format json | \
jq '.data.issues[] |
select(.closed_at >= "'$SPRINT_START'" and .closed_at <= "'$SPRINT_END'")')
# 获取新增 Issue
NEW_ISSUES=$(gitlink-cli issue +list --state open --format json | \
jq '.data.issues[] |
select(.created_at >= "'$SPRINT_START'" and .created_at <= "'$SPRINT_END'")')
# 统计 Issue 数据
CLOSED_COUNT=$(echo "$CLOSED_ISSUES" | jq -s 'length')
NEW_COUNT=$(echo "$NEW_ISSUES" | jq -s 'length')
```
### 步骤 3获取 PR 统计
```bash
# 获取 Sprint 期间合并的 PR
MERGED_PRS=$(gitlink-cli pr +list --state merged --format json | \
jq '.data.prs[] |
select(.merged_at >= "'$SPRINT_START'" and .merged_at <= "'$SPRINT_END'")')
# 获取新建的 PR
NEW_PRS=$(gitlink-cli pr +list --state open --format json | \
jq '.data.prs[] |
select(.created_at >= "'$SPRINT_START'" and .created_at <= "'$SPRINT_END'")')
# 统计 PR 数据
MERGED_COUNT=$(echo "$MERGED_PRS" | jq -s 'length')
NEW_PR_COUNT=$(echo "$NEW_PRS" | jq -s 'length')
```
### 步骤 4获取提交统计
```bash
# 获取项目活动数据
ACTIVITY=$(gitlink-cli api GET /:owner/:repo/activity --format json | \
jq ".data.activity[] |
select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")
# 提取提交数据
COMMITS=$(echo "$ACTIVITY" | jq 'select(.type == "commit")')
COMMIT_COUNT=$(echo "$COMMITS" | jq -s 'length')
```
### 步骤 5分析团队贡献
```bash
# 按团队成员统计贡献
CONTRIBUTORS=$(gitlink-cli api GET /:owner/:repo/activity --format json | \
jq ".data.activity[] |
select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\") |
.author |
group_by(.) |
map({developer: .[0], count: length}) |
sort_by(.count) | reverse")
```
### 步骤 6生成 Sprint 报告
```bash
# 生成结构化的 Sprint 报告
SPRINT_REPORT="# 📊 Sprint 进度报告
**时间范围**: $SPRINT_START$SPRINT_END
**Sprint 周期**: 14 天
## 🎯 目标达成情况
### Issue 统计
- ✅ **完成 Issue**: $CLOSED_COUNT
- 🆕 **新增 Issue**: $NEW_COUNT
- 📈 **完成率**: $(($CLOSED_COUNT * 100 / ($CLOSED_COUNT + $NEW_COUNT)))%
### Pull Request 统计
- 🔀 **合并 PR**: $MERGED_COUNT
- 🆕 **新建 PR**: $NEW_PR_COUNT
- ✅ **合并率**: $(($MERGED_COUNT * 100 / ($MERGED_COUNT + $NEW_PR_COUNT)))%
### 代码提交统计
- 💻 **提交次数**: $COMMIT_COUNT
- 📊 **日均提交**: $(($COMMIT_COUNT / 14)) 次/天
## 👥 团队贡献
$(echo "$CONTRIBUTORS" | jq -r '.[] | "- **\(.developer)**: \(.count) 次贡献"')
## 🎉 主要成就
$(echo "$CLOSED_ISSUES" | jq -r '.[] | "- 完成 Issue: \(.subject)"')
## 🔄 进行中工作
$(echo "$NEW_ISSUES" | jq -r '.[] | "- 新建 Issue: \(.subject)"')
## 📈 下期计划
1. 继续进行中的 Issue 开发
2. 新功能规划和设计
3. 技术债务清理
4. 性能优化工作"
# 输出报告
echo "$SPRINT_REPORT"
```
## 完整工作流示例
```bash
#!/bin/bash
# Sprint 报告自动化生成脚本
OWNER="username"
REPO="myproject"
REPORT_DIR="sprint_reports"
# 获取时间范围
SPRINT_NUMBER=$1
if [ -z "$SPRINT_NUMBER" ]; then
# 计算当前是第几个 Sprint假设每 Sprint 2 周,从项目开始计算)
PROJECT_START="2026-01-01"
CURRENT_DATE=$(date +%Y-%m-%d)
DAYS_DIFF=$(( ($(date -d "$CURRENT_DATE" +%s) - $(date -d "$PROJECT_START" +%s)) / 86400 ))
SPRINT_NUMBER=$((DAYS_DIFF / 14 + 1))
fi
SPRINT_START=$(date -d "$((SPRINT_NUMBER - 1)) weeks ago" +%Y-%m-%d)
SPRINT_END=$(date -d "$((SPRINT_NUMBER - 1)) weeks ago +14 days" +%Y-%m-%d)
echo "生成 Sprint $SPRINT_NUMBER 报告 ($SPRINT_START - $SPRINT_END)"
# 创建报告目录
mkdir -p "$REPORT_DIR"
# 1. 获取 Issue 数据
echo "收集 Issue 数据..."
ISSUE_DATA=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --format json)
CLOSED_ISSUES=$(echo "$ISSUE_DATA" | jq -r ".data.issues[] |
select(.closed_at >= \"$SPRINT_START\" and .closed_at <= \"$SPRINT_END\")")
NEW_ISSUES=$(echo "$ISSUE_DATA" | jq -r ".data.issues[] |
select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")
CLOSED_COUNT=$(echo "$CLOSED_ISSUES" | jq -s 'length')
NEW_COUNT=$(echo "$NEW_ISSUES" | jq -s 'length')
# 2. 获取 PR 数据
echo "收集 PR 数据..."
PR_DATA=$(gitlink-cli pr +list --owner $OWNER --repo $REPO --format json)
MERGED_PRS=$(echo "$PR_DATA" | jq -r ".data.prs[] |
select(.merged_at >= \"$SPRINT_START\" and .merged_at <= \"$SPRINT_END\")")
NEW_PRS=$(echo "$PR_DATA" | jq -r ".data.prs[] |
select(.created_at >= \"$SPRINT_START\" and .created_at <= \"$SPRINT_END\")")
MERGED_COUNT=$(echo "$MERGED_PRS" | jq -s 'length')
NEW_PR_COUNT=$(echo "$NEW_PRS" | jq -s 'length')
# 3. 获取提交数据
echo "收集提交数据..."
COMMITS=$(gitlink-cli api GET "/$OWNER/$REPO/commits" --format json | \
jq -r ".data[] |
select(.committed_date >= \"$SPRINT_START\" and .committed_date <= \"$SPRINT_END\")")
COMMIT_COUNT=$(echo "$COMMITS" | jq -s 'length')
# 4. 分析团队贡献
echo "分析团队贡献..."
CONTRIBUTORS=$(echo "$COMMITS" | jq -r '.author | group_by(.) |
map({developer: .[0], count: length}) |
sort_by(.count) | reverse')
# 5. 分析 Issue 标签
echo "分析 Issue 分类..."
FEATURES=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "feature")] | length')
BUGS=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "bug")] | length')
ENHANCEMENTS=$(echo "$CLOSED_ISSUES" | jq -r '[.[] | select(.issue_tags[]?.name == "enhancement")] | length')
# 6. 计算完成率
COMPLETION_RATE=0
if [ $((CLOSED_COUNT + NEW_COUNT)) -gt 0 ]; then
COMPLETION_RATE=$((CLOSED_COUNT * 100 / (CLOSED_COUNT + NEW_COUNT)))
fi
# 7. 生成报告
echo "生成 Sprint 报告..."
REPORT_FILE="$REPORT_DIR/sprint_${SPRINT_NUMBER}_$(date +%Y%m%d).md"
cat > "$REPORT_FILE" << EOF
# 📊 Sprint $SPRINT_NUMBER 进度报告
**时间范围**: $SPRINT_START 至 $SPRINT_END
**生成时间**: $(date +%Y-%m-%d)
**报告周期**: 14 天
## 🎯 Sprint 目标达成情况
### 总体概览
| 指标 | 数量 | 说明 |
|------|------|------|
| ✅ 完成 Issue | $CLOSED_COUNT 个 | Sprint 期间关闭的 Issue |
| 🆕 新增 Issue | $NEW_COUNT 个 | Sprint 期间新建的 Issue |
| 🔀 合并 PR | $MERGED_COUNT 个 | Sprint 期间合并的 PR |
| 🆕 新建 PR | $NEW_PR_COUNT 个 | Sprint 期间新建的 PR |
| 💻 代码提交 | $COMMIT_COUNT 次 | Sprint 期间的提交次数 |
### 完成率分析
- **Issue 完成率**: ${COMPLETION_RATE}%
- **PR 合并率**: $((MERGED_COUNT * 100 / (MERGED_COUNT + NEW_PR_COUNT)))%
- **平均日提交**: $((COMMIT_COUNT / 14)) 次/天
## 📊 Issue 分类统计
| 分类 | 数量 | 占比 |
|------|------|------|
| 新功能 | $FEATURES 个 | $((FEATURES * 100 / CLOSED_COUNT))% |
| Bug 修复 | $BUGS 个 | $((BUGS * 100 / CLOSED_COUNT))% |
| 功能改进 | $ENHANCEMENTS 个 | $((ENHANCEMENTS * 100 / CLOSED_COUNT))% |
## 👥 团队贡献统计
$(echo "$CONTRIBUTORS" | jq -r '.[] | |
"| **\(.developer)** | \(.count) 次提交 | $((.count * 100 / COMMIT_COUNT))% |"')
## 🎉 主要成就
### 完成的 Issue
$(echo "$CLOSED_ISSUES" | jq -r '"- [\(.subject)](#issue/\(.id)) - \(.assigned_to // "未分配")"')
### 合并的 PR
$(echo "$MERGED_PRS" | jq -r '"- [\(.title)](#pr/\(.id)) - \(.author.login)"')
## 🔄 进行中的工作
### 未完成的 Issue
$(echo "$NEW_ISSUES" | jq -r '"- [\(.subject)](#issue/\(.id)) - \(.assigned_to // "未分配")"')
### 待合并的 PR
$(echo "$NEW_PRS" | jq -r '"- [\(.title)](#pr/\(.id)) - \(.author.login)"')
## 📈 趋势分析
### 代码活动趋势
- 本 Sprint 共有 **$COMMIT_COUNT 次提交**,日均 **$((COMMIT_COUNT / 14)) 次**
- 比上 Sprint $([[ $SPRINT_NUMBER -gt 1 ]] && echo "增长了/减少了 XX%" || echo "为基线数据")
### 团队效率分析
- 团队成员积极参与,贡献分布较为均匀
- 代码审查及时PR 合并率良好
## ⚠️ 风险和问题
### 当前风险
- 高优先级 Issue 积压:$(echo "$NEW_ISSUES" | jq '[.[] | select(.priority_id == 1)] | length') 个
- 长期未解决的 Issue$(echo "$NEW_ISSUES" | jq '[.[] | select(.created_at < "'$SPRINT_START'")] | length') 个
### 技术债务
- 代码复用待改进
- 测试覆盖率需要提升
- 文档需要更新
## 📋 下期计划
### 主要目标
1. 继续完成当前进行中的 Issue
2. 优化代码质量和测试覆盖
3. 更新项目文档
4. 技术债务清理
### 资源规划
- 开发资源:保持当前团队配置
- 时间规划:重点关注高优先级 Issue
- 技术重点:性能优化和代码重构
## 🙏 致谢
感谢所有团队成员在 Sprint $SPRINT_NUMBER 期间的辛勤工作!
---
**报告生成**: $(date +%Y-%m-%d %H:%M:%S)
**数据来源**: GitLink API
**报告类型**: 自动化 Sprint 报告
EOF
echo "✅ Sprint 报告已生成: $REPORT_FILE"
# 8. 可选:创建 Issue 讨论报告
echo "创建 Sprint 回顾 Issue..."
REVIEW_ISSUE_BODY="## Sprint $SPRINT_NUMBER 回顾
### Sprint 报告
完整的 Sprint 报告请查看: [Sprint $SPRINT_NUMBER 报告](../../blob/master/$REPORT_FILE)
### 讨论要点
1. 目标达成情况分析
2. 团队协作效果评估
3. 流程改进建议
4. 下 Sprint 目标规划
### 问题跟踪
- 需要解决的问题
- 改进建议
- 风险识别"
gitlink-cli issue +create \
--owner $OWNER \
--repo $REPO \
--title "Sprint $SPRINT_NUMBER 回顾" \
--body "$REVIEW_ISSUE_BODY"
echo "Sprint 报告工作流完成!"
```
## AI Agent 集成示例
Claude Code 等 AI Agent 可以深度集成此工作流:
```python
# AI Agent 生成 Sprint 报告
def generate_sprint_report(owner, repo, sprint_number):
"""AI Agent 自动生成 Sprint 进度报告"""
# 1. 确定 Sprint 时间范围
sprint_start, sprint_end = calculate_sprint_period(sprint_number)
# 2. 收集数据
sprint_data = collect_sprint_data(owner, repo, sprint_start, sprint_end)
# 3. AI 分析数据
analysis = analyze_sprint_performance(sprint_data)
# 4. 生成报告
report = generate_report_content(sprint_number, sprint_data, analysis)
# 5. 保存报告并创建回顾 Issue
save_report(report, sprint_number)
create_review_issue(owner, repo, sprint_number, report)
return report
def collect_sprint_data(owner, repo, start_date, end_date):
"""收集 Sprint 数据"""
return {
'issues': {
'closed': get_closed_issues(owner, repo, start_date, end_date),
'new': get_new_issues(owner, repo, start_date, end_date)
},
'pull_requests': {
'merged': get_merged_prs(owner, repo, start_date, end_date),
'new': get_new_prs(owner, repo, start_date, end_date)
},
'commits': get_commits(owner, repo, start_date, end_date),
'contributors': get_contributor_stats(owner, repo, start_date, end_date)
}
def analyze_sprint_performance(data):
"""AI 分析 Sprint 表现"""
analysis = {
'velocity': calculate_velocity(data),
'trends': identify_trends(data),
'risks': identify_risks(data),
'recommendations': generate_recommendations(data)
}
# AI 分析完成率趋势
completion_rate = len(data['issues']['closed']) / (
len(data['issues']['closed']) + len(data['issues']['new'])
) * 100
if completion_rate > 80:
analysis['performance'] = 'excellent'
elif completion_rate > 60:
analysis['performance'] = 'good'
else:
analysis['performance'] = 'needs_improvement'
return analysis
def generate_report_content(sprint_number, data, analysis):
"""AI 生成报告内容"""
report = f"""# 📊 Sprint {sprint_number} 进度报告
## 🎯 目标达成情况
### 总体概览
- **完成 Issue**: {len(data['issues']['closed'])}
- **新增 Issue**: {len(data['issues']['new'])}
- **合并 PR**: {len(data['pull_requests']['merged'])}
- **代码提交**: {len(data['commits'])}
### AI 分析结果
- **表现评级**: {analysis['performance']}
- **团队速度**: {analysis['velocity']} story points
- **主要趋势**: {analysis['trends']}
## 🎉 主要成就
"""
# 添加主要成就
for issue in data['issues']['closed'][:5]:
report += f"- {issue['subject']} (#{issue['id']})\n"
# 添加风险和建议
report += "\n## ⚠️ 风险识别\n"
for risk in analysis['risks']:
report += f"- {risk}\n"
report += "\n## 💡 改进建议\n"
for recommendation in analysis['recommendations']:
report += f"- {recommendation}\n"
return report
```
## 报告模板
### 标准报告结构
```markdown
# Sprint {NUMBER} 进度报告
## 元信息
- **时间范围**: {START_DATE} - {END_DATE}
- **Sprint 周期**: 14 天
- **生成时间**: {TIMESTAMP}
## 目标达成
### 完成情况
- 计划完成: X 个 Issue
- 实际完成: Y 个 Issue
- 完成率: Z%
## 工作统计
### Issue 统计
- 关闭: N 个
- 新建: M 个
- 分类统计
### PR 统计
- 合并: N 个
- 新建: M 个
- 合并率: X%
### 提交统计
- 总提交: N 次
- 日均: X 次
## 团队贡献
- 成员A: N 次贡献
- 成员B: M 次贡献
## 风险和问题
- 当前风险
- 技术债务
- 阻塞问题
## 下期计划
- 主要目标
- 资源规划
- 时间安排
```
## 数据分析维度
### 1. 速度分析
- Story Points 完成
- Issue 完成数量
- PR 合并数量
### 2. 质量分析
- Bug 修复比例
- 代码审查通过率
- 测试覆盖率变化
### 3. 效率分析
- 平均 Issue 解决时间
- 平均 PR 合并时间
- 代码审查周期
### 4. 团队分析
- 成员贡献分布
- 协作效率
- 沟通成本
## 最佳实践
1. **定期生成**:每个 Sprint 结束后及时生成报告
2. **数据准确**:确保收集的数据完整准确
3. **客观分析**:基于数据进行客观分析
4. **行动导向**:报告应包含可执行的改进建议
5. **团队参与**:让团队成员参与报告讨论
## 质量保证
报告质量检查:
- [ ] 数据完整性检查
- [ ] 计算准确性验证
- [ ] 格式一致性检查
- [ ] 语法和拼写检查
- [ ] 链接有效性验证
- [ ] 客观性审查
## References
- [workflow-issue-triage](workflow-issue-triage.md) — Issue 分类工作流
- [workflow-pr-review](workflow-pr-review.md) — PR 审查工作流
- [gitlink-workflow](../SKILL.md) — 工作流总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [pm-sprint](../../gitlink-pm/references/pm-sprint.md) — Sprint 管理
- [pm-report](../../gitlink-pm/references/pm-report.md) — 周报生成