12 KiB

Raw Blame History

PM 周报生成

前置条件： 先阅读 ../../gitlink-shared/SKILL.md 了解认证、全局参数和安全规则。注意：PM 功能需要项目开启 PM 模块，并通过项目 ID 访问。

GitLink PM 周报功能提供项目一周工作情况的自动汇总，包括 Issue、Pull Request、提交记录等数据。

命令

# 查看周报数据
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123'

# 查看当前仓库的项目 ID
gitlink-cli repo +info --format json | jq '.data.project_id'

# 组合命令：自动获取项目 ID 并查看周报
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID"

# 查看特定日期范围的周报
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123&start_date=2026-01-01&end_date=2026-01-07'

# 查看 Issue 标签统计
gitlink-cli api GET /pm/issue_tags --query 'project_id=123'

参数

参数	必填	说明
`project_id`	是	项目 ID（通过 `repo +info` 获取）
`start_date`	否	开始日期（格式：YYYY-MM-DD）
`end_date`	否	结束日期（格式：YYYY-MM-DD）
`--owner`	否*	仓库所有者（自动从 git remote 解析）
`--repo`	否*	仓库名称（自动从 git remote 解析）
`--format`	否	输出格式: `json`/`table`/`yaml`
`--debug`	否	启用调试输出

*如果在 GitLink 仓库目录下执行，--owner 和 --repo 可自动推断。

API

GET /api/pm/weekly_issues?project_id={project_id}&start_date={start_date}&end_date={end_date}

响应示例：

{
  "ok": true,
  "data": {
    "period": {
      "start_date": "2026-01-01",
      "end_date": "2026-01-07",
      "week_number": 1
    },
    "summary": {
      "total_issues": 15,
      "new_issues": 8,
      "closed_issues": 5,
      "in_progress_issues": 2,
      "total_prs": 6,
      "merged_prs": 4,
      "total_commits": 42
    },
    "issues": [
      {
        "id": 456,
        "subject": "实现用户认证功能",
        "status": "closed",
        "author": "developer1",
        "assigned_to": "developer2",
        "created_at": "2026-01-02T10:00:00Z",
        "closed_at": "2026-01-05T15:30:00Z",
        "labels": ["feature", "authentication"]
      }
    ],
    "pull_requests": [
      {
        "id": 123,
        "title": "Feature: User authentication",
        "status": "merged",
        "author": "developer1",
        "merged_at": "2026-01-05T16:00:00Z",
        "additions": 245,
        "deletions": 18
      }
    ],
    "commits": [
      {
        "id": "abc123",
        "message": "Implement user login",
        "author": "developer1",
        "committed_date": "2026-01-03T14:20:00Z"
      }
    ],
    "team_contributions": [
      {
        "developer": "developer1",
        "issues_created": 3,
        "issues_closed": 2,
        "prs_created": 2,
        "prs_merged": 2,
        "commits_count": 15
      }
    ]
  }
}

Workflow

Get Project ID using repo +info.
Execute gitlink-cli api GET /pm/weekly_issues --query 'project_id=<id>'.
Display weekly report data.

[!NOTE] This is a Read Operation — no confirmation needed.

Use Cases

工作汇报：自动生成周工作总结
进度跟踪：监控项目一周的进展情况
团队管理：了解团队成员的工作贡献
数据分析：分析项目发展趋势和效率

Weekly Report Structure

典型周报结构：

周报（2026-01-01 至 2026-01-07）

## 概览统计
- 新增 Issue：8 个
- 关闭 Issue：5 个
- 进行中 Issue：2 个
- 合并 PR：4 个
- 代码提交：42 次

## 详细内容
### Issue 活动
- 新建：8 个 Issue
- 完成：5 个 Issue
- 持续工作：2 个 Issue

### Pull Request 活动
- 创建：6 个 PR
- 合并：4 个 PR

### 团队贡献
- developer1：15 次提交，2 个合并 PR
- developer2：12 次提交，1 个合并 PR

Common Operations

周报常用操作：

生成简明周报

# 生成简明周报摘要
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '# 周报摘要
     "\n## 项目周报 (\(.data.period.start_date) 至 \(.data.period.end_date))",
     "\n### 统计概览",
     "- 新增 Issue: \(.data.summary.new_issues) 个",
     "- 完成 Issue: \(.data.summary.closed_issues) 个",
     "- 合并 PR: \(.data.summary.merged_prs) 个",
     "- 代码提交: \(.data.summary.total_commits) 次"'

分析团队贡献

# 按贡献度排序团队成员
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '.data.team_contributions | sort_by(.commits_count) | reverse |
      .[] | "\(.developer): \(.commits_count) 次提交, \(.prs_merged) 个合并 PR"'

查看活动趋势

# 按日期统计活动
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json | \
  jq '[.data.commits[] | .committed_date | split("T")[0]] |
     group_by(.) |
     map({date: .[0], count: length}) |
     sort_by(.date)'

Report Metrics

周报关键指标：

指标	说明	用途
新增 Issue 数	一周内新建的 Issue 数量	反映新需求产生速度
关闭 Issue 数	一周内关闭的 Issue 数量	反映问题解决速度
合并 PR 数	一周内合并的 PR 数量	反映代码集成速度
提交次数	一周内的代码提交次数	反映开发活跃度
参与人数	有贡献活动的团队成员数	反映团队参与度

Analysis Examples

周报数据分析示例：

# 1. 获取项目 ID
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')

# 2. 查看完整周报
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json

# 3. 生成团队贡献排名
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '.data.team_contributions | sort_by(.commits_count) | reverse |

# 4. 计算完成率
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '(.data.summary.closed_issues / .data.summary.new_issues * 100) |
      "本周完成率: \(.)%"'

# 5. 分析代码变更量
gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
  jq '{additions: [.data.pull_requests[].additions] | add,
       deletions: [.data.pull_requests[].deletions] | add,
       net_change: ([.data.pull_requests[].additions] | add) - ([.data.pull_requests[].deletions] | add)}'

Custom Report Generation

自定义报告生成：

# 生成 Markdown 格式的周报
generate_weekly_report() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    END_DATE=$(date +%Y-%m-%d)
    START_DATE=$(date -d "7 days ago" +%Y-%m-%d)
    
    echo "# 项目周报 ($START_DATE 至 $END_DATE)"
    echo ""
    
    gitlink-cli api GET /pm/weekly_issues \
        --query "project_id=$PROJECT_ID&start_date=$START_DATE&end_date=$END_DATE" \
        --format json | \
        jq -r '
            "## 概览统计",
            "- 新增 Issue: \(.data.summary.new_issues) 个",
            "- 完成 Issue: \(.data.summary.closed_issues) 个", 
            "- 合并 PR: \(.data.summary.merged_prs) 个",
            "- 代码提交: \(.data.summary.total_commits) 次",
            "",
            "## 团队贡献",
            (.data.team_contributions | sort_by(.commits_count) | reverse |
             .[] | "- **\(.developer)**: \(.commits_count) 次提交, \(.prs_merged) 个合并 PR"),
            "",
            "## 主要完成",
            (.data.issues[] | select(.status == "closed") |
             "- [\(.subject)](#issue/\(.id)) - \(.assigned_to)"),
            "",
            "## 代码合并",
            (.data.pull_requests[] | select(.status == "merged") |
             "- [\(.title)](#pr/\(.id)) - \(.author) (+\(.additions) -\(.deletions))")
        '
}

Tips

周报数据可以帮助团队了解工作进展
定期生成周报可以保持项目进度的可视化
结合其他 PM 数据可以实现完整的项目管理
使用 JSON 格式输出便于自动化报告生成

Integration with Other Features

与其他功能集成：

# 周报 + 详细操作
# 1. 生成周报概览
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' --format json

# 2. 查看特定 Issue 详情
gitlink-cli issue +view --issue 456

# 3. 查看特定 PR 详情  
gitlink-cli pr +view --pr 123

Best Practices

周报生成最佳实践：

定期生成：每周固定时间生成周报
数据验证：生成后验证数据的准确性
格式统一：使用统一的报告格式
趋势分析：比较不同周报的数据趋势
团队分享：及时分享周报给团队成员

Advanced Usage

高级用法示例：

# 比较两周的数据
compare_weeks() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    
    # 本周数据
    THIS_WEEK=$(gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json)
    
    # 上周数据（计算日期）
    LAST_START=$(date -d "14 days ago" +%Y-%m-%d)
    LAST_END=$(date -d "8 days ago" +%Y-%m-%d)
    LAST_WEEK=$(gitlink-cli api GET /pm/weekly_issues \
        --query "project_id=$PROJECT_ID&start_date=$LAST_START&end_date=$LAST_END" --format json)
    
    # 比较输出
    echo "## 周环比分析"
    echo "新增 Issue: $THIS_WEEK ↓ $LAST_WEEK"
    echo "完成 Issue: $THIS_WEEK ↓ $LAST_WEEK"
}

# 导出为文件
export_weekly_report() {
    PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
    DATE=$(date +%Y-%m-%d)
    
    gitlink-cli api GET /pm/weekly_issues --query "project_id=$PROJECT_ID" --format json | \
        jq '.' > "weekly_report_$DATE.json"
}

Team Collaboration

团队协作建议：

定期分享：每周固定时间分享周报
数据透明：保持团队对项目进度的了解
问题讨论：基于周报数据讨论问题和改进
成果认可：认可和庆祝团队成就
持续改进：基于周报分析优化工作流程

Error Handling

常见错误及解决方案：

错误	原因	解决方案
`400`	PM 模块未开启	联系项目管理员开启 PM 模块
`404`	项目不存在	检查 project_id 是否正确
`400`	日期格式错误	确保日期格式为 YYYY-MM-DD
`403`	权限不足	确认有查看该项目的权限
`404`	数据不存在	指定日期范围内可能没有活动数据

Report Templates

报告模板示例：

# 项目周报（第{{week_number}}周）

**时间范围**：{{start_date}} 至 {{end_date}}

## 📊 核心指标
- ✅ 完成 Issue：{{closed_issues}} 个
- 🆕 新增 Issue：{{new_issues}} 个  
- 🔀 合并 PR：{{merged_prs}} 个
- 💻 代码提交：{{total_commits}} 次

## 👥 团队贡献
{{#each team_contributions}}
### {{developer}}
- 提交：{{commits_count}} 次
- 合并 PR：{{prs_merged}} 个
- 完成 Issue：{{issues_closed}} 个
{{/each}}

## 🎯 主要成果
{{#each closed_issues}}
- {{subject}} ({{assigned_to}})
{{/each}}

## 🔄 进行中工作
{{#each in_progress_issues}}
- {{subject}} ({{assigned_to}})
{{/each}}

References

pm-kanban — 看板管理
pm-sprint — Sprint 管理
gitlink-pm — 项目管理总览
gitlink-shared — 认证和全局参数
repo +info — 获取仓库信息

12 KiB Raw Blame History Unescape Escape

PM 周报生成

命令

参数

API

Workflow

Use Cases

Weekly Report Structure

Common Operations

生成简明周报

分析团队贡献

查看活动趋势

Report Metrics

Analysis Examples

Custom Report Generation

Tips

Integration with Other Features

Best Practices

Advanced Usage

Team Collaboration

Error Handling

Report Templates

References

12 KiB

Raw Blame History