用 Python + 大模型自动生成技术周报：提交记录、任务总结和下周计划

作者：AI 爪客
适合读者：AI 应用工程师、后端开发、技术负责人、研发效能工具建设者
关键词：Python、LLM、技术周报、Git Commit、自动化办公、提示词工程、研发效能

---

摘要

很多研发同学每到周五都会遇到一个熟悉的问题：这一周明明做了不少事，但要写周报时，却突然想不起来具体完成了哪些任务、修了哪些问题、下周应该怎么规划。

本文将起草一个可复用的技术方案：使用 Python + Git 提交记录 + 任务文本 + 大模型 API，自动生成一份结构化技术周报，内容包括：

• 本周提交记录汇总；
• 本周完成事项总结；
• 风险与阻塞问题提炼；
• 下周计划自动生成；
• Markdown 周报导出；
• 提示词模板与错误排查思路。

需要说明的是，本文提供的是一套工程实现思路与示例代码草案，代码中的 API Key 均使用占位符，实际使用时需要根据你接入的大模型服务、网络环境、企业规范进行适配和验证。本文不声称示例代码已经在你的环境中真实运行通过。

---

一、问题背景

1. 技术周报为什么难写？

技术周报看起来只是一个文档任务，但对研发人员来说，它往往存在几个痛点：

1. 信息分散
   工作内容散落在 Git commit、需求文档、即时通讯、任务系统、代码评审记录中。

2. 回忆成本高
   周五下午再回顾本周工作，很容易遗漏细节，尤其是临时修复、联调支持、线上排障等事项。

3. 表达需要结构化
   技术人员习惯写“做了什么”，但周报通常更需要体现“产生了什么结果”“当前有什么风险”“下周如何推进”。

4. 重复性强
   每周都要整理类似结构的内容，非常适合用自动化工具处理。

2. 为什么适合引入大模型？

传统脚本可以提取 Git commit，但很难将零散提交记录转化为自然、清晰、面向管理视角的周报。大模型擅长：

• 对文本进行归纳总结；
• 将技术细节改写为业务可读表达；
• 从记录中识别风险、阻塞和后续计划；
• 按指定格式生成 Markdown 文档。

因此，一个比较自然的方案是：

Python 负责采集和清洗数据，大模型负责理解和生成周报。

---

二、最终效果预览

最终我们希望生成一份类似下面这样的 Markdown 周报：

# 技术周报：2026-05-18 ~ 2026-05-24

## 一、本周工作概览

本周主要围绕智能体任务编排、周报自动化工具和接口稳定性优化展开。整体进展符合预期，核心功能已完成初版联调。

## 二、本周完成事项

### 1. 周报自动化脚本初版
- 完成 Git commit 采集逻辑，支持按日期范围筛选提交记录。
- 增加任务文本输入能力，可合并手动记录与提交历史。
- 初步设计大模型提示词模板，用于生成结构化周报。

### 2. 接口稳定性优化
- 修复任务状态更新接口在空返回场景下的异常处理问题。
- 增加请求超时与错误重试提示。

## 三、风险与问题

- 当前自动生成内容依赖输入记录质量，如果 commit message 过于简略，生成结果可能偏泛。
- 大模型接口调用需要考虑费用、限流和企业数据安全要求。

## 四、下周计划

- 接入任务系统 API，减少手动输入任务记录的成本。
- 增加周报模板配置能力，支持个人版和团队版。
- 对生成结果增加人工确认环节，避免直接发布未经校对的内容。

---

三、技术方案总览

整体流程可以拆成 5 步：

┌──────────────────┐
│ 1. 读取 Git 记录  │
└────────┬─────────┘
         │
         v
┌──────────────────┐
│ 2. 读取任务记录   │
└────────┬─────────┘
         │
         v
┌──────────────────┐
│ 3. 清洗与结构化   │
└────────┬─────────┘
         │
         v
┌──────────────────┐
│ 4. 调用大模型生成 │
└────────┬─────────┘
         │
         v
┌──────────────────┐
│ 5. 导出 Markdown  │
└──────────────────┘

数据来源设计

数据来源	示例	作用
Git commit	feat: add weekly report generator	还原代码层面的实际工作
手动任务记录	完成周报工具提示词优化	补充非代码工作
Issue / 需求系统	修复登录态过期问题	对齐需求和问题背景
会议纪要	确定下周接入任务系统 API	提炼计划和协作事项

本文为了保持示例清晰，先使用：

• Git commit；
• 本地 tasks.md 手动任务记录；
• Python 脚本；
• 大模型 Chat Completions 风格接口。

---

四、环境准备

1. Python 版本

建议使用 Python 3.10+。

python --version

2. 安装依赖

如果你使用的是 OpenAI 风格接口，可以准备如下依赖：

pip install requests python-dotenv

如果你接入的是其他大模型服务，例如通义千问、智谱、DeepSeek、火山方舟、私有化模型网关等，可以根据官方 SDK 或 HTTP API 文档调整请求部分。

3. 准备环境变量

不要把真实 API Key 写进代码仓库。可以创建 .env 文件：

LLM_API_KEY=你的_API_KEY_占位符
LLM_API_BASE=https://api.example.com/v1/chat/completions
LLM_MODEL=your-model-name

注意：上面只是占位示例，请替换成你实际服务商提供的地址和模型名。

4. 准备任务记录文件

在项目根目录创建一个 tasks.md：

# 本周任务记录

- 完成周报自动生成脚本的需求梳理。
- 调研 Git commit 到周报内容的自动总结方式。
- 优化智能体任务编排中的异常提示。
- 协助排查测试环境接口超时问题。
- 计划下周接入任务系统 API。

---

五、核心代码示例

下面给出一个单文件示例：weekly_report_generator.py。

说明：示例重点展示实现结构，真实项目中建议拆分为 git_reader.py、llm_client.py、prompt_builder.py、report_writer.py 等模块。

1. 读取 Git 提交记录

import subprocess
from datetime import datetime, timedelta
from pathlib import Path


def get_git_commits(repo_path: str, since: str, until: str) -> list[dict]:
    """
    读取指定时间范围内的 Git commit 记录。

    参数：
    - repo_path: Git 仓库路径
    - since: 开始日期，例如 2026-05-18
    - until: 结束日期，例如 2026-05-24

    返回：
    - commit 列表，每个元素包含 hash、author、date、message
    """
    command = [
        "git",
        "log",
        f"--since={since}",
        f"--until={until} 23:59:59",
        "--pretty=format:%h|%an|%ad|%s",
        "--date=short",
    ]

    result = subprocess.run(
        command,
        cwd=repo_path,
        capture_output=True,
        text=True,
        encoding="utf-8",
        errors="ignore",
    )

    if result.returncode != 0:
        raise RuntimeError(f"读取 Git 记录失败：{result.stderr}")

    commits = []
    for line in result.stdout.splitlines():
        parts = line.split("|", 3)
        if len(parts) != 4:
            continue
        commit_hash, author, date, message = parts
        commits.append(
            {
                "hash": commit_hash,
                "author": author,
                "date": date,
                "message": message,
            }
        )

    return commits

这段代码使用 git log 获取指定日期范围内的提交记录，并将其转换为结构化字典。

2. 读取手动任务记录

def read_task_notes(task_file: str) -> str:
    """读取本地任务记录文件。"""
    path = Path(task_file)
    if not path.exists():
        return ""
    return path.read_text(encoding="utf-8")

Git commit 更适合记录代码变化，但很多工作不会体现在提交中，例如：

• 方案设计；
• 会议沟通；
• 排查定位；
• 文档编写；
• 支持其他同学联调。

所以建议保留一个轻量的任务记录入口，让生成结果更完整。

3. 构造提示词

import json


def build_prompt(commits: list[dict], task_notes: str, since: str, until: str) -> list[dict]:
    """构造发送给大模型的 messages。"""
    system_prompt = """
你是一名资深研发效能助手，擅长根据 Git 提交记录和任务记录生成技术周报。
请用中文输出，语言专业、简洁、客观，不要夸大成果。
如果输入信息不足，请明确说明“根据当前记录推测”。
不要编造没有依据的具体数据、接口名称或上线结果。
""".strip()

    user_prompt = f"""
请根据以下信息生成一份技术周报。

时间范围：{since} ~ {until}

【Git 提交记录】
{json.dumps(commits, ensure_ascii=False, indent=2)}

【手动任务记录】
{task_notes}

请按以下结构输出 Markdown：

# 技术周报：{since} ~ {until}

## 一、本周工作概览
用 1-2 段总结本周主要工作。

## 二、本周完成事项
按主题分组总结，避免简单罗列 commit。

## 三、关键技术细节
说明本周涉及的核心技术点、实现思路或工程改动。

## 四、风险与阻塞
列出潜在风险、待确认事项、依赖问题。如果没有明显风险，请写“暂无明显阻塞”。

## 五、下周计划
基于本周记录和待办事项，生成 3-5 条可执行计划。

## 六、需要协同的事项
列出需要产品、测试、后端、前端、运维或其他角色配合的内容。
""".strip()

    return [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ]

这里的关键点是：不要只让模型“总结一下”，而是明确告诉它：

• 输入是什么；
• 输出语言是什么；
• 输出结构是什么；
• 哪些内容不能编造；
• 信息不足时如何处理。

4. 调用大模型接口

下面使用通用 HTTP 请求示例。不同服务商的字段可能略有差异，请以实际 API 文档为准。

import os
import requests
from dotenv import load_dotenv


load_dotenv()


def call_llm(messages: list[dict]) -> str:
    """调用大模型生成周报。"""
    api_key = os.getenv("LLM_API_KEY", "你的_API_KEY_占位符")
    api_base = os.getenv("LLM_API_BASE", "https://api.example.com/v1/chat/completions")
    model = os.getenv("LLM_MODEL", "your-model-name")

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }

    payload = {
        "model": model,
        "messages": messages,
        "temperature": 0.3,
    }

    response = requests.post(
        api_base,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()
    data = response.json()

    # OpenAI 风格返回格式示例：
    return data["choices"][0]["message"]["content"]

注意事项：

• temperature 建议设置低一些，例如 0.2 ~ 0.5，减少发散；
• API Key 使用环境变量读取，不要硬编码实际密钥；
• 生产环境应增加重试、限流、日志脱敏和异常兜底；
• 如果输入包含公司敏感信息，需要优先确认数据合规要求。

5. 保存 Markdown 周报

def save_report(content: str, output_file: str) -> None:
    """保存周报到 Markdown 文件。"""
    path = Path(output_file)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")

6. 串联主流程

def get_default_week_range() -> tuple[str, str]:
    """
    获取默认周报时间范围：本周一到本周日。
    可根据团队习惯调整为周五到下周四等周期。
    """
    today = datetime.today()
    monday = today - timedelta(days=today.weekday())
    sunday = monday + timedelta(days=6)
    return monday.strftime("%Y-%m-%d"), sunday.strftime("%Y-%m-%d")


def main():
    repo_path = "."
    task_file = "tasks.md"
    output_file = "output/weekly-report.md"

    since, until = get_default_week_range()

    commits = get_git_commits(repo_path, since, until)
    task_notes = read_task_notes(task_file)
    messages = build_prompt(commits, task_notes, since, until)

    report = call_llm(messages)
    save_report(report, output_file)

    print(f"周报已生成：{output_file}")


if __name__ == "__main__":
    main()

完整流程执行后，会在 output/weekly-report.md 中生成一份 Markdown 技术周报。

再次提醒：以上代码是通用示例，真实运行前需要配置模型接口、安装依赖、确认仓库路径，并根据实际返回格式调整解析逻辑。

---

六、提示词模板

下面给出一个更完整的提示词模板，可直接作为项目中的 prompt_template.md 参考。

你是一名资深研发效能助手，请根据输入的研发记录生成技术周报。

生成要求：
1. 使用中文。
2. 输出 Markdown。
3. 语言专业、客观、简洁。
4. 不要编造没有依据的上线结果、性能指标、用户反馈或业务收益。
5. 如果信息不足，请使用“根据当前记录推测”进行说明。
6. 将零散 commit 聚合为主题，不要逐条机械翻译。
7. 下周计划要具体、可执行，避免空泛表达。

输入信息：
- 时间范围：{{since}} ~ {{until}}
- Git 提交记录：{{commits}}
- 手动任务记录：{{task_notes}}
- 可选需求记录：{{issues}}

输出结构：

# 技术周报：{{since}} ~ {{until}}

## 一、本周工作概览

## 二、本周完成事项

## 三、关键技术细节

## 四、风险与阻塞

## 五、下周计划

## 六、需要协同的事项

提示词设计要点

1. 约束模型不要编造

周报场景很容易出现“看起来很漂亮但事实不准确”的内容。提示词中要明确：

不要编造没有依据的上线结果、性能指标、用户反馈或业务收益。

2. 让模型做归类，而不是翻译

Git commit 往往很碎，例如：

fix: handle empty response
feat: add weekly summary prompt
chore: update config example

如果直接翻译，会得到很散的内容。更好的指令是：

将零散 commit 聚合为主题，不要逐条机械翻译。

3. 下周计划要可执行

不建议生成：

继续优化系统能力。

更好的输出是：

- 补充接口异常场景测试，覆盖超时、空响应和鉴权失败三类情况。
- 将周报模板抽离为配置文件，支持不同团队按需调整栏目。

---

七、常见错误与排查

1. git log 没有输出

可能原因：

• 当前目录不是 Git 仓库；
• 指定日期范围内没有提交；
• 系统时间或日期格式不符合预期；
• 分支切换导致记录不在当前分支。

排查方式：

git status
git log --since=2026-05-18 --until="2026-05-24 23:59:59" --oneline

2. 中文乱码

可能原因：

• Windows 控制台编码问题；
• Git commit message 编码不统一；
• 文件读写没有指定 utf-8。

建议：

Path("output.md").write_text(content, encoding="utf-8")

调用 subprocess.run 时也建议显式设置：

subprocess.run(..., text=True, encoding="utf-8", errors="ignore")

3. 大模型接口返回 401

常见原因：

• API Key 未配置；
• API Key 写错；
• 请求头格式不符合服务商要求；
• 当前 Key 没有调用目标模型的权限。

排查建议：

• 检查 .env 是否被正确加载；
• 打印脱敏后的配置，例如只显示 Key 前后几位；
• 对照服务商文档确认 Authorization 写法。

不要在日志中打印完整 API Key。

4. 大模型接口返回 429

429 通常表示限流或额度不足。可以考虑：

• 降低调用频率；
• 增加指数退避重试；
• 缩短输入内容；
• 升级服务额度；
• 在团队内部做统一网关和调用队列。

简单重试示例：

import time


def post_with_retry(url, headers, payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload, timeout=60)
        if response.status_code != 429:
            response.raise_for_status()
            return response
        wait_seconds = 2 ** attempt
        time.sleep(wait_seconds)
    response.raise_for_status()

5. 生成内容太空泛

可能原因：

• commit message 太简单，例如大量 update、fix bug；
• 任务记录缺少背景；
• 提示词没有要求按主题聚合；
• 没有提供需求、Issue 或模块信息。

优化建议：

• 改善 commit 规范；
• 在任务记录中补充背景和结果；
• 提示词中要求“每个完成事项包含背景、动作、结果”；
• 引入 Issue 标题和描述作为补充上下文。

6. 生成内容包含不确定结论

如果模型写出了“已上线”“性能提升 30%”之类没有来源的内容，需要增强约束：

除非输入中明确提供，否则不要输出上线状态、性能提升比例、用户反馈和业务收益。

也可以在生成后增加二次校验提示词，让模型检查哪些句子缺少依据。

---

八、优化方向

1. 接入任务系统

如果团队使用 Jira、禅道、飞书多维表格、企业微信审批或自研任务平台，可以通过 API 拉取本周任务：

• 任务标题；
• 任务状态；
• 经办人；
• 截止日期；
• 评论记录；
• 需求优先级。

这样生成的周报会比单纯依赖 Git commit 更完整。

2. 支持多人团队周报

个人周报关注“我做了什么”，团队周报更关注：

• 团队目标；
• 模块进展；
• 风险依赖；
• 下周排期；
• 需要管理者协调的问题。

可以在提示词中增加人员维度：

请按成员维度和模块维度分别总结，不要将所有人的工作混在一起。

3. 增加数据脱敏

在调用外部模型前，应考虑脱敏：

• 用户手机号；
• 邮箱；
• 访问 Token；
• 内部域名；
• 客户名称；
• 合同金额；
• 未公开项目代号。

可以在 Python 中加入简单脱敏函数：

import re


def mask_sensitive_text(text: str) -> str:
    text = re.sub(r"[\w\.-]+@[\w\.-]+", "[邮箱已脱敏]", text)
    text = re.sub(r"1[3-9]\d{9}", "[手机号已脱敏]", text)
    text = re.sub(r"Bearer\s+[A-Za-z0-9\._\-]+", "Bearer [Token已脱敏]", text)
    return text

这只是基础示例，真实企业场景建议结合安全规范做更严格的处理。

4. 加入人工确认环节

周报自动生成不等于自动发送。更稳妥的流程是：

自动采集数据 → 自动生成草稿 → 人工确认修改 → 发布到群或文档系统

这样既能提升效率，又能避免错误内容直接对外扩散。

5. 固化团队周报模板

不同团队关注点不同：

• 算法团队关注实验进展、指标、数据集；
• 后端团队关注接口、稳定性、性能；
• 前端团队关注页面、交互、兼容性；
• AI 应用团队关注场景、提示词、工具调用链路、用户反馈。

建议将模板配置化，例如：

report_template:
  sections:
    - 本周工作概览
    - 重点项目进展
    - 技术问题与解决方案
    - 风险与依赖
    - 下周计划

---

九、资产复制区

本节整理一些可以直接复制到项目中的资产。

1. .env.example

LLM_API_KEY=你的_API_KEY_占位符
LLM_API_BASE=https://api.example.com/v1/chat/completions
LLM_MODEL=your-model-name

2. tasks.md 模板

# 本周任务记录

## 已完成

- 

## 进行中

- 

## 遇到的问题

- 

## 下周计划草稿

- 

3. requirements.txt

requests
python-dotenv

4. 周报生成命令示例

python weekly_report_generator.py

5. Commit 规范建议

feat: 新功能
fix: 问题修复
docs: 文档变更
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建、依赖或工程配置

示例：

feat: add weekly report prompt builder
fix: handle empty git commit output
docs: add task note template

---

十、结尾互动

自动生成周报的核心价值，不是让大模型“替你编周报”，而是把研发过程中已经存在的记录重新组织起来，减少回忆成本，提高表达质量。

如果你准备在团队里落地这个工具，建议先从一个很小的版本开始：

1. 只读取 Git commit 和 tasks.md；
2. 只生成 Markdown 草稿；
3. 保留人工确认；
4. 再逐步接入任务系统、IM、文档平台和自动发送能力。

你也可以根据自己的团队情况继续扩展：

• 接入 Jira / 禅道 / 飞书任务；
• 生成个人周报和团队周报两个版本；
• 增加敏感信息脱敏；
• 将周报自动发布到知识库；
• 增加周报质量评分和依据检查。

欢迎在评论区聊聊：

• 你们团队现在是怎么写技术周报的？
• 你更希望自动化工具帮你生成“个人周报”还是“团队周报”？
• 如果接入大模型，你最担心的是准确性、数据安全，还是格式不稳定？

如果这篇文章对你有启发，可以收藏后动手改一个适合自己团队的版本。下一篇我们可以继续拆解：如何把生成好的周报自动同步到企业微信、飞书或知识库系统。