1. 项目概述一个开源周报的诞生与价值在开源社区里项目维护者与贡献者之间最头疼的问题之一可能就是信息同步了。一个项目少则几个多则几十上百位贡献者每个人都在不同的时区、用不同的节奏提交代码、修复问题、讨论新功能。作为项目负责人你每周一打开GitHub面对的是几十条新的Issue、Pull Request和讨论而社区成员们可能还在为上周已经解决的问题反复提问。这种信息差不仅消耗精力更会拖慢整个项目的协作效率。这就是我最初创建semcod/weekly这个项目的初衷。它不是一个复杂的工具链而是一个极简、可复用的周报生成器专门为GitHub上的开源项目量身定制。它的核心功能很简单自动抓取过去一周或自定义时间段内指定仓库的所有活动——包括新的Issue、PR、Star、Fork、Release甚至是代码提交的统计——然后生成一份结构清晰、内容详实的Markdown格式周报。你可能会问GitHub本身不是有Insights和Activity页面吗没错但它们更偏向于数据可视化缺乏叙事性和总结性。semcod/weekly要做的是把零散的数据点编织成一个有逻辑的故事这周我们解决了哪些关键问题社区提出了什么有趣的新想法项目的健康状况如Issue关闭率如何这份自动生成的周报可以直接发布到项目的Wiki、Discussion板块或者作为内部同步邮件发送出去让所有人无论是核心维护者还是偶尔关注的用户都能在5分钟内了解项目的最新脉搏。2. 核心设计思路自动化、可定制与轻量级2.1 为什么选择“周报”这个载体在项目设计之初我考虑过多种信息同步形式实时聊天机器人、每日摘要邮件、复杂的仪表盘。但最终选择了“周报”主要基于三个考量节奏感每日信息流太频繁容易造成通知疲劳每月又太长信息容易滞后。一周是一个在敏捷开发和社区运营中公认的、恰到好处的复盘周期。叙事性周报不同于原始数据流它允许我们进行简单的归类和总结。例如将相似的Issue归类为“功能请求”或“Bug反馈”并标注处理状态这比单纯罗列标题更有价值。低门槛一份Markdown周报几乎可以在任何地方查看和传播对接收者零成本。它不依赖特定的平台或工具兼容性极佳。2.2 技术栈选型Python GitHub API为了实现轻量化和快速部署技术栈的选择非常明确核心语言Python。拥有极其丰富的第三方库如requests,PyGithub能快速处理HTTP请求和JSON数据编写脚本的效率很高。核心接口GitHub REST API v3。这是与GitHub交互的基石。它提供了几乎所有的数据端点包括获取仓库事件、Issue、PR、Star等。虽然也有GraphQL API更高效单次请求可获取嵌套数据但对于初期快速验证和大多数开源项目来说REST API的简单直观更具优势。输出格式Markdown。无需解释这是技术文档的通用语言可读性好且能被GitHub、GitLab等平台完美渲染。部署方式GitHub Actions。这是实现自动化的灵魂。通过配置一个定时任务如每周一凌晨让GitHub的服务器自动执行我们的Python脚本生成周报并提交回仓库或发送通知完全无需自己维护服务器。注意使用GitHub API有频率限制。对于未认证的请求每小时仅允许60次使用个人访问令牌PAT认证后可提升至5000次/小时。我们的脚本需要认证以避免在获取多个仓库或大量数据时被限流。2.3 可定制化架构设计一个开源项目的情况千差万别。有的项目Issue众多需要重点关注有的项目PR是主线需要详细审查列表。因此semcod/weekly被设计成高度模块化和可配置的。数据获取模块独立函数分别负责从GitHub API获取Issues、PRs、Stars、Releases等数据。这样如果你想在周报中增加“代码提交者排行榜”只需要新增一个获取commits数据的模块即可。模板引擎周报的格式不写死在代码里。我们使用一个template.md.j2Jinja2模板文件来定义周报的结构。在这个模板里我们用占位符如{{ new_issues }}、{{ closed_prs }}来标记数据插入的位置。想要改变周报的排版直接修改模板文件无需改动核心代码。配置文件使用config.yaml或config.json来存放所有可变参数repository: 目标仓库名如facebook/reacttoken: GitHub个人访问令牌敏感信息应使用Actions Secretstime_range: 周报覆盖的时间范围默认7d可改为14d等sections: 一个列表决定周报包含哪些部分如[issues, prs, stars, releases]output_path: 生成的周报文件存放路径。这种设计使得这个工具不仅能用于semcod/weekly自身更能被任何一个GitHub仓库fork和改造只需修改配置文件就能立刻拥有自己的自动化周报系统。3. 核心实现细节与实操步骤3.1 环境准备与依赖安装首先你需要一个Python环境3.7和基本的命令行操作知识。# 1. 克隆或下载项目代码 git clone https://github.com/semcod/weekly.git cd weekly # 2. 创建并激活虚拟环境推荐避免污染全局环境 python -m venv venv # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 3. 安装项目依赖 # 项目根目录通常会有一个 requirements.txt 文件 pip install -r requirements.txt一个典型的requirements.txt文件内容如下PyGithub1.55 python-dotenv0.19.0 Jinja23.0.0 pyyaml6.0PyGithub一个非常强大的封装了GitHub API的Python库让API调用变得像操作本地对象一样简单。python-dotenv用于从.env文件加载环境变量如你的GitHub Token便于本地测试。Jinja2流行的Python模板引擎用于渲染Markdown模板。pyyaml用于解析YAML格式的配置文件。3.2 获取并配置GitHub个人访问令牌这是整个流程的关键安全步骤。Token相当于你的密码绝对不能提交到公开仓库。登录GitHub点击右上角头像 -Settings。在左侧边栏最下方找到Developer settings。选择Personal access tokens-Tokens (classic)然后点击Generate new token。为Token起一个描述性名称例如Weekly Report Generator。选择权限Scopes这是最重要的部分。为了读取仓库信息至少需要勾选repo下的public_repo如果你只用于公开库或整个repo权限用于私有库。为了最小权限原则不建议勾选不必要的权限。点击Generate token生成后立即复制并保存到安全的地方。这个Token只会显示一次。在本地开发时在项目根目录创建一个.env文件GITHUB_TOKEN你的_token_字符串并在代码中使用python-dotenv加载它。务必确保.env文件在.gitignore中防止误提交。3.3 编写核心数据获取函数让我们以获取“过去一周新开且未关闭的Issue”为例看看核心代码如何编写。from github import Github from datetime import datetime, timedelta import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 def get_recent_issues(repo_name, token, days7): 获取指定仓库最近N天内的Issue # 初始化GitHub客户端 g Github(token) repo g.get_repo(repo_name) # 计算时间范围 since_date datetime.now() - timedelta(daysdays) # GitHub API查询参数since指定起始时间stateopen表示未关闭的 issues repo.get_issues(stateopen, sincesince_date) issue_list [] for issue in issues: # 过滤掉Pull Request在GitHub API中PR也是一种Issue if issue.pull_request: continue issue_list.append({ number: issue.number, title: issue.title, url: issue.html_url, created_at: issue.created_at.strftime(%Y-%m-%d %H:%M), user: issue.user.login, labels: [label.name for label in issue.labels] }) return issue_list代码解读与注意事项repo.get_issues(stateopen, sincesince_date)这里有一个关键细节。参数stateopen获取的是所有“打开”状态的Issue但since参数筛选的是“在此时间之后有更新”的Issue。这意味着一个一周前打开但昨天有人评论的旧Issue也会被包含进来。如果你严格只想获取“新创建”的Issue需要在循环中再判断issue.created_at since_date。我们的示例采用了更常见的“近期活跃Issue”的视角。if issue.pull_request:GitHub API中Pull Request是Issue的一个子集拥有pull_request属性。这个判断是为了将纯Issue和PR区分开。我们将Issue信息组织成一个字典列表方便后续模板渲染。同理可以编写获取PR、Star、Release等数据的函数。PyGithub库的方法名非常直观例如repo.get_pulls(stateclosed)获取已关闭的PRrepo.get_stargazers_with_dates()获取带时间的Star列表。3.4 设计Jinja2模板在templates/目录下创建weekly_report.md.j2文件# {{ repo_name }} 项目周报 ({{ start_date }} 至 {{ end_date }}) ## 本周概览 * **仓库地址**: [{{ repo_name }}](https://github.com/{{ repo_name }}) * **报告周期**: {{ start_date }} 至 {{ end_date }} * **新增Star**: {{ stats.new_stars }} 个 * **新增Fork**: {{ stats.new_forks }} 个 ## Issues 动态 ### 新开启的Issue ({{ new_issues|length }}个) {% if new_issues %} {% for issue in new_issues %} * [#{{ issue.number }} {{ issue.title }}]({{ issue.url }}) - 由 {{ issue.user }} 于 {{ issue.created_at }} 创建 {% if issue.labels %}标签: {{ issue.labels|join(, ) }}{% endif %} {% endfor %} {% else %} * 本周无新开启的Issue。 {% endif %} ### 已关闭的Issue ({{ closed_issues|length }}个) {% if closed_issues %} {% for issue in closed_issues %} * [#{{ issue.number }} {{ issue.title }}]({{ issue.url }}) - 由 {{ issue.closed_by }} 于 {{ issue.closed_at }} 关闭 {% endfor %} {% else %} * 本周无已关闭的Issue。 {% endif %} ## Pull Requests 动态 ### 新开启的PR ({{ new_prs|length }}个) ... ### 已合并的PR ({{ merged_prs|length }}个) ... ## 版本发布 {% if releases %} {% for release in releases %} ### [{{ release.tag_name }}]({{ release.url }}) - {{ release.name }} {{ release.body|default(暂无描述, true) }} {% endfor %} {% else %} * 本周无新版本发布。 {% endif %} --- *本报告由 [semcod/weekly](https://github.com/semcod/weekly) 自动生成*模板语法{{ variable }}用于插入变量{% if %}和{% for %}用于控制逻辑。这使得生成的内容能灵活应对数据有无的情况。3.5 主程序逻辑与模板渲染创建一个main.py文件串联所有模块import yaml from jinja2 import Environment, FileSystemLoader from datetime import datetime # 导入自己写的数据获取函数 from data_fetchers import get_recent_issues, get_prs, get_stars_stats, get_releases def main(): # 1. 加载配置 with open(config.yaml, r) as f: config yaml.safe_load(f) token os.getenv(GITHUB_TOKEN) repo_name config[repository] days config.get(time_range_days, 7) # 2. 获取数据 print(f正在为仓库 {repo_name} 获取近 {days} 天数据...) new_issues get_recent_issues(repo_name, token, days) # ... 调用其他数据获取函数 stats { new_stars: get_stars_stats(repo_name, token, days)[new], new_forks: get_forks_stats(repo_name, token, days)[new] } # 3. 准备模板上下文 end_date datetime.now().strftime(%Y-%m-%d) start_date (datetime.now() - timedelta(daysdays)).strftime(%Y-%m-%d) context { repo_name: repo_name, start_date: start_date, end_date: end_date, new_issues: new_issues, closed_issues: closed_issues, # ... 其他数据 stats: stats, } # 4. 渲染模板 env Environment(loaderFileSystemLoader(templates/)) template env.get_template(weekly_report.md.j2) output_text template.render(**context) # 5. 输出文件 output_path config.get(output_path, WEEKLY_REPORT.md) with open(output_path, w, encodingutf-8) as f: f.write(output_text) print(f周报已生成: {output_path}) if __name__ __main__: main()运行python main.py你将在本地得到一份完整的周报Markdown文件。4. 自动化部署使用GitHub Actions本地运行只是第一步我们的目标是全自动。在项目根目录创建.github/workflows/generate-weekly.yml文件。name: Generate Weekly Report on: schedule: # 每周一UTC时间00:00运行北京时间08:00 - cron: 0 0 * * 1 workflow_dispatch: # 允许手动触发 jobs: build: runs-on: ubuntu-latest permissions: contents: write # 需要写权限来提交生成的周报 steps: - name: Checkout repository uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - name: Generate Weekly Report env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 使用GitHub Actions内置令牌对当前仓库有权限 # 或者使用你自己创建的、具有更广权限的PAT # PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }} run: | python main.py # 假设你的配置config.yaml中repository就是当前仓库 # 如果需要为其他仓库生成可以在这里通过sed命令动态修改config.yaml - name: Commit and Push Report run: | git config --local user.email actiongithub.com git config --local user.name GitHub Action git add WEEKLY_REPORT.md git commit -m docs: 自动更新周报 [$(date %Y-%m-%d)] || echo 没有变更无需提交 git push关键配置解析on.schedule.cron:0 0 * * 1是Cron表达式表示“每周一0点0分”。你可以使用 crontab guru 这个网站来可视化调试你的Cron表达式。workflow_dispatch: 这个配置允许你在GitHub仓库的Actions页面手动点击按钮来运行这个工作流方便测试。permissions: contents: write: 这是关键一步。GitHub Actions默认的GITHUB_TOKEN只有读权限。我们需要显式声明写权限才能执行后面的git commit和git push。secrets.GITHUB_TOKEN: 这是GitHub Actions为每次运行自动生成的临时令牌拥有当前仓库的访问权限。对于操作自己的仓库这通常就足够了。如果你需要读取其他私有仓库的数据则需要将之前创建的Personal Access Token添加到仓库的Settings - Secrets and variables - Actions中命名为如PERSONAL_ACCESS_TOKEN然后在这里引用${{ secrets.PERSONAL_ACCESS_TOKEN }}。配置完成后将代码推送到GitHub。Actions会在预定时间自动运行生成周报并提交回仓库。你可以在仓库的Actions标签页查看运行日志。5. 高级定制与常见问题排查5.1 如何定制报告内容和样式1. 增加新数据部分假设你想增加“本周最活跃贡献者”板块。数据层在data_fetchers.py中新增一个函数使用repo.get_commits(sincesince_date)获取提交然后通过commit.author.login统计提交者次数。配置层在config.yaml的sections列表中添加active_contributors。模板层在weekly_report.md.j2中新增一个## 活跃贡献者章节使用新的模板变量{{ active_contributors }}来渲染。主程序在main.py中调用新函数并将结果加入context字典。2. 修改样式和排版直接修改Jinja2模板文件即可。你可以使用更丰富的Markdown语法如表格、任务列表、表情符号等让周报更美观。### 已合并的PR | PR编号 | 标题 | 合并者 | 合并时间 | |--------|------|--------|----------| {% for pr in merged_prs %} | [#{{ pr.number }}]({{ pr.url }}) | {{ pr.title }} | {{ pr.merged_by }} | {{ pr.merged_at }} | {% endfor %}5.2 常见问题与解决方案Q1: Action运行失败日志显示“Resource not accessible by integration”原因使用的GITHUB_TOKEN权限不足或者尝试访问了其他无权访问的私有仓库。解决如果操作的是当前仓库确保工作流YAML中配置了permissions: contents: write。如果需要访问其他仓库使用你自己创建的、具有相应仓库读权限的PAT并将其添加到仓库Secrets中在Action中替换GITHUB_TOKEN。Q2: 生成的周报数据不全缺少某些时间段的数据。原因GitHub API的某些查询如get_issues默认分页只返回第一页30条。如果一周内活动超过30条就会丢失数据。解决PyGithub的返回对象通常是PaginatedList你需要遍历它来获取所有数据。或者使用.get_page()方法但更简单的方法是使用列表推导式或循环因为PyGithub在迭代时会自动处理分页。确保你的数据获取函数中没有对结果进行过早的切片操作。Q3: Action定时任务没有按时触发。原因GitHub Actions的定时任务可能因为队列延迟、GitHub服务问题而稍有延迟但一般不会超过几分钟。如果完全没触发首先检查YAML语法特别是Cron表达式是否正确。其次检查仓库的Action功能是否被禁用。解决可以手动触发一次(workflow_dispatch)测试。确认Cron表达式无误后通常只需要等待。GitHub Actions的定时任务最小间隔是5分钟不支持秒级精度。Q4: 我想把周报发布到其他平台比如Discord或钉钉。思路在生成Markdown文件后增加一个步骤。例如对于Discord可以使用Webhook。在Action中新增一个Step使用curl命令将Markdown内容可能需要稍作格式转换POST到Discord的Webhook URL。- name: Post to Discord run: | # 将Markdown内容进行JSON转义并发送 REPORT_CONTENT$(cat WEEKLY_REPORT.md | python -c import sys, json; print(json.dumps(sys.stdin.read()))) curl -H Content-Type: application/json \ -X POST \ -d {\content\: $REPORT_CONTENT} \ ${{ secrets.DISCORD_WEBHOOK_URL }}将Webhook URL保存在仓库的Secrets中命名为DISCORD_WEBHOOK_URL。5.3 性能优化与最佳实践缓存API响应如果你的项目非常活跃API调用次数可能很多。可以考虑对变化不频繁的数据如Star/Fork的总数进行缓存例如将上次的结果存为文件本次只获取增量。错误处理与重试在数据获取函数中加入try-except块对网络超时或API限流返回429状态码进行重试。可以使用time.sleep()进行指数退避。敏感信息处理绝对不要在代码或配置文件中硬编码Token。始终使用环境变量.env本地和GitHub Secrets线上。模板国际化如果你的社区是多语言的可以准备多个Jinja2模板如weekly_report_zh.md.j2,weekly_report_en.md.j2并根据配置选择渲染哪一个。通过semcod/weekly这个项目我将一个常见的社区运营需求拆解成了一个可自动化、可定制、可复用的技术方案。它本身代码量不大但涵盖了从本地脚本开发、第三方API调用、模板渲染到持续集成自动化部署的完整链路。对于任何一个开源项目的维护者来说花上几个小时集成这样一套系统未来每周节省的沟通成本和提升的社区透明度回报是显而易见的。更重要的是这个过程本身就是对开源协作工具链的一次深刻实践。
