背景是这样的：最初的需求非常朴素——根据 git 历史记录自动生成周报，自动通过 Outlook 发出去。但从这个问题出发一路往下推：提交信息质量决定周报质量、git 里查不到下周计划、周报的目的其实是”可见度 + 留痕”、个人工具要不要给领导用、手里有专项工作怎么单独汇报……最后发现真正值得做的不是”周报生成器”，而是一套个人工作底稿系统：日常工作自动沉淀为底稿，所有汇报场景（周报、月报、季报、年终总结、述职）都从底稿一键生成。这篇文章完整记录这次推演，包括每个关键决策的理由和认知坑。

目录

1. 起点：一个朴素的自动化需求
2. 关键认知：AI 能整理信息，不能发明信息
3. 数据从哪来：git 之外的五个数据源
4. 周报模板与滚动状态：每期怎么跑
5. 归档的红利：月报季报年报从哪来
6. 发送通道与草稿模式
7. 目标重定义：从周报生成器到工作底稿系统
8. 系统架构：五层
9. 专项汇报扩展：Profile 与三个预留口子
10. 团队化升级：管理者角色怎么加才不翻车
11. 三阶段路线图
12. 四条设计红线
13. 终局图景
14. 落地：现在就能开工的部分

1. 起点：一个朴素的自动化需求

最初的设想是一条五环节流水线：

扫描 git 仓库 → 拉取上周提交并过滤 → 汇总成周报文案 → 生成邮件（草稿或直发）→ 定时调度

每个环节要定的事：

• 仓库清单：用配置文件（yml/json）列出各仓库本地路径 + 分支，避免硬编码；
• 先 fetch 再统计：本地 clone 的 log 只包含已 fetch 的提交，不先 fetch 会漏掉同事合入的内容——这是最容易踩的坑；
• 时间窗口：定死”上周一 00:00 ~ 上周日 24:00”（自然周），并注意时区；也可以用”上次发送至今”；
• 作者过滤：用 email 白名单而不是用户名，同一个人在不同仓库可能用不同邮箱；
• 提交清洗：--no-merges 排除合并提交、过滤 WIP / fix typo / bump version 这类噪音、注意 squash 和 rebase 导致的重复计数、决定只统计主干还是包含 feature 分支；
• 调度：Windows 任务计划程序每周五定时触发，机器关机要有错过策略，且要记录”已发送状态”避免重复报告。

到这里还只是个普通脚本。真正决定成败的是下面几条认知。

2. 关键认知：AI 能整理信息，不能发明信息

这是整个项目的第一性原理：AI 做的是翻译、归并、润色，原料里没有的信息它给不了。它不知道你花了多久、问题解决没解决、价值多大。提交信息越具体，周报越可信。

你的 git 提交质量	AI 能做到的效果
规范（feat/fix 前缀 + 说清做了什么）	几乎全自动，归并润色即可出稿
普通（中文白话，看得懂做了啥）	AI 归并 + 润色成周报，你花几分钟校对
零信息（”fix”、”1”、”update”、”修改”）	AI 只能产出空话，或者开始编造——最危险的情况

“够用”的标准其实很低：

坏:   fix
够用: 修复用户列表筛选后分页数量不对的问题
好:   feat(user): 修复筛选后分页计数错误 (PRD-1234)

不需要学 Conventional Commits 这种规范，只要三条最低限度的习惯：

1. 首行写清”做了什么”，让三个月后的自己能看懂；
2. 一次提交做一件事，别把五个不相关的改动堆在一条里；
3. 避开 “update”、”调一下” 这类零信息词。

如果连这个也不想改，补救办法是把 PR 标题/描述、分支名、diff 摘要一起喂给 AI——分支名 feature/user-auth 比提交信息 “fix” 有用得多。

3. 数据从哪来：git 之外的五个数据源

先修正一个常见误解：git 其实能”推断”出进行中——本周有大量提交但还没合并的分支、开着没合的 PR，大概率就是下周继续的事。AI 可以直接输出”推测：报表中心 v2 进行中（分支 feature/report-v2 有 7 个未合并提交）”。真正 git 里完全没有的是”下周计划”。完整的数据源分层：

数据源	能拿到什么	接入成本	定位
git 旁证（未合并分支/进行中 PR）	推断”正在做什么”	零（已有）	进行中的自动兜底
任务系统（Jira/TAPD/禅道/Azure DevOps）	指派任务、状态、冲刺计划	中（要 API token）	计划和进行中的最准来源
Outlook 日历	项目会议、评审、上线排期	中（Graph API）	辅助判断项目节奏
聊天记录	你在群里承诺/推进的事	难（见下）	补充上下文
一句话日志（人工）	每天一行	零	最可靠的兜底

聊天记录要先泼冷水：个人微信没有 API；企业微信/钉钉的”会话存档”接口要企业管理员开通加合规审批，个人项目基本走不通；Teams 走 Microsoft Graph 可以读自己的消息，且和发 Outlook 周报是同一套 M365 账号——如果公司用 Teams，这是唯一能正规自动化的路。务实做法是“导入”而不是”对接”：周五把当周关键讨论复制粘贴进一个 txt，让 AI 提取”本周推进了什么、承诺了什么交付、下周要做什么”。零审批、第一天就能用。

一句话日志是性价比最高的东西：每天下班前记一行（”8/31 报表中心 v2，写了导出功能”），存成 notes/2026-08-31.txt。它同时解决两个问题：给”下周计划”提供素材；给 AI 提供提交归类的上下文——知道你当天在做哪个任务，二十条提交的聚类会准很多。

4. 周报模板与滚动状态：每期怎么跑

模板设计的原则：槽位固定，数据来源标注清楚；周报条目不是提交的复述，而是”任务/成果”粒度。本周 20 条提交，最终呈现为 3~5 条条目。

【周报】张三 2026-W36（08/24 - 08/30）

一、本周完成                          ← 本周 git 提交，AI 聚类（自动）
  1. 完成用户认证模块开发，支持登录/登出/Token 刷新（12 commits，PR #88 已合并）
  2. 修复订单导出在数据量>1万条时超时的问题（PR #91）

二、进行中                            ← 上期周报滚动带下来（自动，人工微调）
  1. 报表中心 v2（进度约 60%，预计下周完成）

三、下周计划                          ← 本周写下的计划滚动 + 人工补充
  1. 完成报表中心 v2 并提测

四、风险与求助                        ← 纯人工（git 里没有这种信息）
  （无）

长期发送意味着每期不是孤立的，需要一个 state.json 在每期生成后写、生成前读：

{
  "last_sent_week": "2026-W36",
  "reported_commits": ["a1b2c3", "d4e5f6"],
  "in_progress": [
    { "title": "报表中心 v2", "started_week": "2026-W34", "progress": "60%" }
  ],
  "next_week_plan": [
    "完成报表中心 v2 并提测",
    "配合测试修复认证模块反馈的问题"
  ]
}

三个字段各解决一个长期问题：

• reported_commits：已报告过的提交 hash 集合 → 下期统计时排除，解决重复报告；
• in_progress：跨周任务 → 上周说”进行中”的事，这周要么变成”完成”要么继续挂着更新进度，解决”烂尾感”——领导最反感上周说在做、这周消失的事；
• next_week_plan：你本周填的计划 → 自动滚动成下期”下周计划”的底稿，你只需改，不用重写。

每期完整运行流程：

1. 自动计算上一个自然周的时间窗（不用每次手改日期）；
2. 各仓库 git fetch，拉取时间窗内提交，剔除 reported_commits 里已报告过的；
3. AI 把提交聚类成”成果条目”（附 PR 号/规模佐证）；
4. 读 state.json，合并”进行中”和上期计划，套模板生成完整周报；
5. 存成 Outlook 草稿，你花 5 分钟补”下周计划”、删改措辞、点发送；
6. 把本期的成果、进行中、计划写回 state.json，供下一期使用。

人工介入就固定在第 5 步那 5 分钟，其余全自动。

5. 归档的红利：月报季报年报从哪来

每期周报存档到 reports/2026-W36.md 这样的目录，长期积累后它本身就是数据资产：

• 月报/季报 = 让 AI 汇总最近 4~13 期周报，按主题归并、跨周去重、按影响力排序，几乎零成本；
• 年终总结/晋升材料 = 全年周报就是现成的工作成果清单，比回忆靠谱得多；
• 顺带还能看到自己的节奏（哪周在救火、哪周在铺新功能）。

关键点：月报季报年报不需要单独的数据管道，归档的周报本身就是原料。一条 digest --period month 命令的事。这正是”长期发送”最大的复利。

6. 发送通道与草稿模式

发送层的技术选型（以 Windows + Outlook 生态为例）：

方案	前提	评价
Microsoft Graph API（推荐）	Azure 应用注册 + Mail.Send 权限	最正规，不依赖 Outlook 客户端；缺点是公司租户可能需要管理员审批，建议最早去确认
mailto: 唤起邮件客户端	零配置	只能预填正文、需手动点发送、正文长度和格式受限；适合第一版 MVP
经典版 Outlook COM 自动化	需要 Office 许可证装经典版	本机自动化最成熟；注意”新版 Outlook”不支持 COM
SMTP 直发	公司 Exchange 允许	多数企业已禁用 SMTP AUTH，先问 IT

Graph API 有个很适合这个场景的用法：只调接口创建草稿（不发送），草稿会同步到你的 Outlook，你审一眼再点发送。技术上全自动、流程上保留人工确认。

这里有一条强烈建议：不要一步到位全自动直发。LLM 可能把小改动润色成大成果，或有幻觉，发给领导前必须可审。第一版用”存草稿 + 人工确认”，跑稳定两周后再考虑放开直发。

7. 目标重定义：从周报生成器到工作底稿系统

聊到这里该停下来问一句：周报的目的是什么？“周报”只是手段，真正要的是两样东西：工作可见度（别人知道你在干什么）和工作留痕（事后能证明你干过什么）。

渠道	覆盖谁	留痕	自动化潜力
git 提交 / GitLab 活动流	技术同事	有	已自动，但领导基本不看
任务看板（Jira/禅道流转状态）	同事+领导	有	已自动，前提是你认真维护状态
群里的阶段性同步（”xx 已提测”）	所有人	弱	半自动，AI 可从聊天提取
站会/周会口头同步	在场的人	无	—
周报/双周报	领导+全员	有	可自动化

注意分野：聊天、站会、看板解决”现在别人知道你在干嘛”，但都没有可靠留痕。半年后年终总结、晋升答辩、或者领导突然问”你下半年都做了什么”，能救你的只有书面归档。

周报里有三样东西别的渠道给不了：

1. 留痕——最硬的一项；
2. 向上管理的载体——风险、求助、期望管理只能主动书面说，没人会去你的提交记录里发现”这块被上游接口卡了两周”；
3. 逼你每周复盘——这个副产品长期看比汇报本身值钱。

所以项目的正确形态是把收集和输出解耦——收集层长期低成本运行，输出层按需可插拔：

收集层（每天/自动，几乎零成本）
  git 提交（自动） + 每日一句话日志（30秒） + 聊天导入（随手）
        ↓
  底稿库：state.json 滚动状态 + reports/ 归档
        ↓
输出层（按需，一条命令换格式）
  ├── 周报（如果公司要求，定时发）
  ├── 月报/季报
  ├── 年终总结、晋升述职材料
  ├── 1:1 前的谈话素材
  └── 被领导突然问"你最近在干嘛"时的即时答案

由此得到一个决策分叉：

• 领导明确要求周报 → 底座 + 定时生成 + 存草稿审后发，全自动收益最大；
• 没人要求，自发想记录 → 只建底座：自动收集 + 每天 30 秒日志 + 自动归档，不定期发送。推荐保留一个最低限度动作：每月生成一次月报给自己看，觉得有价值就顺手转发给领导——一次点击的事，可见度和留痕同时在线。

无论哪种情况，先建底座——它是两个分支的公共部分，不需要任何审批，git 收集第一天就能跑。

8. 系统架构：五层

数据层   collectors（可插拔，按需增加）
         git/codehub │ jira/todo │ wiki/blog │ 日历 │ 聊天导入 │ 一句话日志
              ↓
底稿层   事件 → AI 归并成成果条目 → 按期归档 + 滚动状态（去重/进行中/计划）
              ↓
智能层   AI 整理规则：只基于底稿不编造、归并去噪、按受众调整语言
              ↓
输出层   视图（可插拔）：周报 │ 月/季/年报 │ 年终述职 │ 1:1 素材 │ 即问即答
              ↓
角色层   成员（管理自己的源，看自己的底稿）
         管理者（只看自愿提交上来的聚合视图，无原始数据权限）

每一层独立演进：加数据源不动输出，加输出格式不动收集，加团队角色不动个人层。AI 层的提示词有几条硬约束：只允许基于给定内容写、不得编造成果；同类提交归并输出 3~8 条有分量的条目而不是流水账；按收件人调整语言（给领导用业务语言，技术细节进附录）；拿不准的地方标注”待补充”留给人填，而不是替人圆。

9. 专项汇报扩展：Profile 与三个预留口子

现实里很多人除了自己的周报，手里还有某一个专项/课题的汇报：要单独的统计口径、单独的收件人、单独的发送节奏，可能还要接一些自动化取数。核心思路一句话：不要把专项周报做成第二个系统，而是做成同一个引擎里的另一个”报告档案（Profile）”，为它预留三个口子。

9.1 核心抽象：报告档案（Profile）

个人周报、专项周报、月报，本质都是同一个四元组的实例：

报告 = Profile(数据范围 × 模板 × 收件人 × 日程)

个人周报是一个 profile（周五 17:00 发，范围=全部仓库）；专项周报是另一个 profile（周一 09:00 发，范围=只属于这个专项的仓库/任务标签）。引擎只有一套，profile 可以无限加。所以配置结构从第一天起就该按多 profile 设计——哪怕先只配一个。

9.2 口子一：收集器接口（拉）

每个收集器实现同一个契约：

class Collector:
    def fetch(self, profile, time_window) -> list[Event]

未来的”自动统计某业务系统数据”、”定时跑 SQL 出数”、”读共享盘 Excel”，都是新写一个 collector 文件扔进目录、在配置里注册，核心代码零改动。

9.3 口子二：ingest 入口（推）

预留一个 ingest 子命令（后期可升级为本地 HTTP 端点）：

main.py ingest --source erp-scraper --type metric --payload metrics.json

将来某个自动化脚本（定时爬另一个系统、别人写的工具）不需要了解系统内部，往这个口子推标准事件即可。这是最干净的扩展缝——P0 就把 ingest 命令做出来，哪怕暂时只有日志功能在用它。

9.4 唯一的硬约定：事件标准格式

所有数据源——git、jira、聊天、爬虫、手工日志——进来之前都归一成同一个 Event 结构：

{
  "time": "2026-08-31T14:30:00+08:00",
  "source": "git | jira | wiki | chat | log | ingest",
  "actor": "zhangsan@company.com",
  "type": "commit | ticket | doc | note | metric",
  "title": "完成订单导出超时修复",
  "detail": "……",
  "refs": { "repo": "order-service", "pr": 88, "ticket": "PRD-1234" },
  "metrics": { "resolved_tickets": 12 },
  "scope": ["personal", "专项-数据治理"]
}

scope 标签解决”一份数据多处用”：同一条记录既进个人周报、又进专项周报，靠 profile 声明的过滤条件（仓库、标签、关键字）来圈定，数据不用复制两份。

9.5 统计数据必须走”直通车道”，绝不过 AI

专项汇报里往往有硬数字（处理量、完成率、缺陷数、SLA）。这里有一条铁律：指标数字由模板槽位直接渲染，永远不让 LLM 碰——AI 负责叙述性内容的归并润色，数字必须从 collector 原样到页面，一个都不能”生成”。

narrative 事件 → AI 归并润色 → 模板叙述区
metric 事件   → 直通           → 模板数据区（表格/数字槽位）

另外专项汇报比个人周报多一个”里程碑/进度”维度，它天然属于 state 滚动状态（进行中、计划的延伸），不需要新机制。

9.6 专项 Profile 配置示例

profiles:
  personal-weekly:
    schedule: { day: friday, time: "17:00" }
    collectors: [git:all_repos, daily_log, chat_import]
    template: personal_weekly.md

  专项-数据治理:
    schedule: { day: monday, time: "09:00" }          # 专项有自己的节奏
    scope: { repos: [dgp-service], jira_label: "data-governance" }
    collectors: [git:scoped, jira:scoped, erp_stats]  # erp_stats 就是未来的自动抓数器
    metrics:
      - { id: resolved_tickets, from: jira,   query: "resolved this week" }
      - { id: quality_score,    from: ingest, source: "erp-scraper" }  # 外部自动化推送
    milestones: state 滚动维护
    template: project_weekly.md
    recipients: { to: [专项领导@company.com] }

9.7 P0 阶段就要做对的四件便宜的事

现在只花设计成本、不花开发成本的预留：

1. 配置按多 profile 组织（哪怕只有一个）；
2. 所有数据入口归一成统一 Event 结构再入库；
3. ingest 命令第一天就存在（哪怕只被日志功能用）；
4. 生成器内部叙述/指标双通道分开。

而收集器插件机制、HTTP ingest、专项模板、自动抓数 job——全部推迟到真有专项需求时再加。到时候的工作量就是：一个新 collector 文件 + 一段新 profile 配置 + 一个新模板，核心不动。

10. 团队化升级：管理者角色怎么加才不翻车

很自然的想法：让领导也成为系统角色，看所有人的产出，再用 AI 对比绩效。架构方向对一半，另一半是坑。

如果实现方式是”系统去各个系统里拉所有人的原始数据给老板看”，这个系统会死在政治上：员工发现老板有个 AI 监工工具在对比自己的提交，信任直接清零，然后大家开始刷提交数——指标一旦被考核就必然被 Game（Goodhart 定律），合规上也可能碰公司隐私红线。

正确的架构是把”采集”和”共享”分开：

个人层（每人一套，读自己的数据，权限天然合法）
  自己的 git/jira/wiki 底稿 → AI 生成汇报 → 自己审、自己改
        ↓  显式、自愿、审过的"提交"动作
团队层（聚合服务）
  汇总各人提交上来的汇报 → 团队周报/月报
  管理者视图：团队维度查询、AI 分析

关键原则：管理者看到的永远是别人自愿提交的成品，而不是原始监控数据。这样不需要任何特殊权限、政治干净，而且成员愿意用——因为工具先帮他们省了写周报的时间，共享只是顺手。推广时的说法也完全不同：”我写了个工具帮大家自动生成周报，顺便给您一个团队汇总视图”，而不是”我做了个系统监控大家的产出”。

另外有个中间路线：老板在 Jira/CodeHub 里本来就有的合法可见权限（他管的项目看板、他名下仓库的 PR）可以直接作为团队层数据源——用”角色已有的权限”，而不是新开监控。

AI 做绩效分析，能干和不能干的边界：

能干（价值真实存在）：

• 团队工作量分布、项目覆盖面（”这个季度 A 覆盖了支付线，B 覆盖了风控线”）；
• 识别瓶颈和跨人依赖（”C 的工作被 D 的接口卡了两周”）；
• 超负荷预警、季度回顾的一手材料。

不能干：直接横向排名、把 commit 数/任务数当产出、作为考核依据。不同岗位的产出形态差一个数量级，AI 一旦越权当裁判，系统就变成数字游戏。

一句话原则：AI 出材料，人做判断。AI 负责把原始记录整理成”可比的事实清单”，判断留给领导。

11. 三阶段路线图

阶段	定位	范围	完成标志
一：底稿引擎	“记下来”（个人 MVP，一两周量级）	git 收集器 + 一句话日志 + reports/ 归档 + generate 出本周底稿 + state 滚动去重；本地 CLI + 纯文本文件，零审批零外部依赖	连续跑 4 周，每周五花 5 分钟能得到一份可以直接发的周报
二：个人工作台	“说出去”（一到两个月量级）	接入 Jira/todo（补计划/进行中）、wiki/博客、聊天导入；定时生成 → 存 Outlook 草稿 → 审后发送；digest 月/季/年汇总、年终总结初稿、1:1 素材、即问即答	一次月报和一次年终总结预演，从底稿生成全程零额外手工
三：团队平台	“聚起来”（季度量级，需试点同事和领导支持）	结构化提交流程 + 团队聚合服务（公司内网部署）；成员配置自己的源、审自己的汇报、自愿提交；管理者只有聚合视图；AI 团队分析	3~5 人试点，每人周报成本降到 5 分钟以内，领导手里有一份他没开口要过的团队视图

12. 四条设计红线

这四条决定项目的口碑和生死，尤其是将来想推广给别人的时候：

1. 共享自愿：管理者视角建立在”别人审过并提交的成品”上，永远不碰原始监控数据——这是阶段三能不能推广出去的前提；
2. AI 出材料，人做判断：尤其涉及绩效的场景，AI 只整理可比的事实清单；
3. 审后发出：草稿确认是默认行为，全自动直发只是后期的高级选项；
4. 数据归属个人：本地优先、随时可导出，不锁死在任何平台里——换工作时整个文件夹拷走，底稿是个人资产。

13. 终局图景

• 周五下午，草稿箱里躺着一封写好的周报，改两行、点发送；
• 年终，一条命令生成述职初稿，素材是全年 50 期周报，比回忆可靠得多；
• 领导季度会前 10 分钟拿到团队回顾材料，出处是每个人自愿提交的汇报；
• 有人问”这个模块谁最熟”，底稿库能回答；
• 手里的专项每个周一自动出一份带统计数据的专项汇报，取数脚本通过 ingest 口子推数据进来，核心系统零改动。

14. 落地：现在就能开工的部分

阶段一不需要等任何人：不碰公司权限、不找 IT、不依赖 Graph API。开工前只有三件事要确认，且都不阻塞：

1. LLM 通道：有没有可用的 API key——没有就先跑纯模板版，生成层后面再接；
2. 发送通道：让 IT 一句话确认租户能否用 Graph API 发邮件——不能就先存草稿或 mailto 兜底；
3. 公司用什么 IM：决定聊天模块是走 Teams API 还是导入制。

P0 骨架清单：

personal-weekly-report/
├── config.yaml            # 多 profile 配置：仓库列表、email 白名单、收发件人、日程
├── collectors/
│   ├── git.py             # fetch 契约：git log 提取、作者过滤、剔除已报告提交
│   └── (jira.py / wiki.py / chat.py ……按需增加)
├── state/state.json       # 滚动状态：进行中、下周计划、已报告提交
├── notes/                 # 每天一句话日志
├── reports/               # 每期归档 2026-W36.md ← 月/季/年报的原料
├── generator.py           # 叙述/指标双通道 + 模板渲染 + digest 汇总模式
├── sender.py              # Graph API / COM / 存草稿（默认草稿，审过再发）
└── main.py                # generate / digest / ingest / send 子命令

P0 就要写对的三处预留：多 profile 配置结构、统一 Event 结构、ingest 命令。其他的——插件机制、HTTP 入口、专项模板、团队层——等个人版跑出价值再说。

最后总结成一句话：模板固定槽位，git 提交填充”本周完成”，状态文件负责”进行中/计划”的跨周滚动和去重，人工只保留每周 5 分钟校对补充；收集是长期的、低频投入的，输出是按需的、可插拔的。这个系统最便宜的部分（收集 + 归档）第一天就能跑起来，最贵的部分（团队平台）等底稿跑出复利再上。