# 周报工作台 · weekly-report-studio

> 把 git log 和零散笔记变成上级愿意读完、愿意转发的周报。
> 官方工作室自研 skill · 3/3 自测任务通过 · 样例为真实运行产出。

## 你会拿到什么

跑完这一个 skill，你手上会有三样东西：

1. `weekly-report.md` — 300 字以内的周报正文，直接粘进邮件 / 飞书 / 钉钉；
2. 一行纯文本摘要 — 放消息列表里就能看清这周干了什么；
3. `qa.txt` — 机器校验结果，证明没有虚词、没有编造数字。

不是给你一堆模板让你自己填，是把你已有的工作痕迹直接翻译成结果。

## 什么时候用它

用户说出以下任意一种意思：

- 「写周报」「整理本周工作」「汇报进展」「weekly report」
- 「这周干的事有点乱，帮我捋一下」
- 「老板要周报，我不知道写什么」

## 开工前要准备什么

| 需要的材料 | 从哪来 | 没有怎么办 |
|---|---|---|
| 本周提交记录 | `git log --since="7 days ago" --author="<你>"` | 用笔记代替 |
| 零散笔记 / 待办 | 备忘录、飞书文档、聊天记录 | 直接口述给 agent |
| 本周最想被知道的一件事 | 你自己 | 必答，不能跳过 |

环境：能跑 `git` 与 `python3`，不联网、不需要 API key、不产生费用。

## 工作流（7 步）

### 1 · 收集原料

优先顺序：**git log > 用户笔记 > 对话里已出现的工作内容**。

```bash
git log --since="7 days ago" --author="$(git config user.name)" \
  --pretty=format:"%h %ad %s" --date=short
```

原料不足时不要硬编，一次问完三个问题（别来回追问）：

1. 本周最想被知道的一件事是什么？
2. 最卡的一件事是什么？
3. 下周必须完成的一件事是什么？

追问话术见 `references/followup-questions.md`。

### 2 · 把动作翻译成结果

这是周报唯一真正值钱的动作。公式：**动词 + 对象 + 可感知结果**。

| 原始提交 | 错误翻译 | 正确翻译 |
|---|---|---|
| `fix login bug` | 修复了登录 bug | 修复登录偶发失败（影响约 12% 日活），上线后相关工单清零 |
| `update docs` | 更新了文档 | 重写部署文档，新同事按文档一次装成，省去 2 次答疑 |
| `refactor utils` | 重构工具函数 | 合并 3 处重复代码，测试覆盖率 61% → 74% |
| `wip: payment` | 推进支付功能 | 支付接入待联调（阻塞：等对方开放测试账号） |

没有数字时不编造，写状态：「上线后观察中」「待验证」「已交付未验收」。
完整对照表见 `references/result-translation.md`。

### 3 · 排序与删减

- 只保留**最多 3 条**本周结果，按「对上级决策的价值」排序，不按工作量排序。
- 三条之外的删掉。塞进去只会稀释重点。
- 正文控制在 **300 字以内**（不含标题）。

### 4 · 按模板组装

```markdown
# 周报 · <姓名> · <日期区间>

## 本周结果（按重要性排序，不超过 3 条）
- <结果1，带数字或状态>
- <结果2>
- <结果3>

## 风险与求助（没有就写"无"）
- <风险> → <需要的决策/支持>

## 下周计划（可交付的承诺，不超过 3 条）
- <计划1>
- <计划2>
```

邮件 / 飞书 / 钉钉的语气与排版差异见 `references/template-variants.md`。

### 5 · 自检

```bash
python3 scripts/validate_report.py demo/output/weekly-report.md
```

校验四件事：字数、三区结构、禁用虚词、每条是否带数字或状态。全绿才发。

### 6 · 出两个版本

- Markdown 正文：粘进邮件或文档
- 一行摘要：`本周交付 X；风险 Y；下周 Z`

### 7 · 归档

追加到 `reports/YYYY-Www.md`。连续 4 周之后，你自己就能看出哪些事在重复、哪些承诺没兑现——这是周报真正的复利。

## 质量红线

1. 不写「持续推进」「持续优化」「赋能」「闭环」「抓手」这类无信息量短语，校验脚本直接判 FAIL。
2. 不夸大：未上线写「待上线」，未验证写「待验证」，未验收写「待验收」。
3. 风险区不许写「一切正常」。至少写「无阻塞」，或诚实写真实风险。
4. 不编数字。任何百分比、金额、人数都必须能追到 git log、监控截图或用户原话。
5. 不做心理按摩。周报是决策材料，不是表态材料。

更多反例见 `references/anti-patterns.md`。

## 常见错误（新手前三次几乎都会犯）

| 症状 | 根因 | 修法 |
|---|---|---|
| 写成流水账 | 按时间写，不按价值排序 | 先定 3 条结论，再补细节 |
| 全是形容词 | 没做第 2 步翻译 | 每条强制带数字或状态 |
| 太长 | 怕漏 | 删到 300 字，删不掉说明没想清楚 |
| 风险写「无」 | 怕暴露问题 | 写真实阻塞 + 需要的支持 |
| 下周计划宏大 | 讨好式承诺 | 只写能交付的，宁少不多 |

## 自测任务（出厂前必须全过）

1. **满料**：输入 24 条杂乱 commit（`inputs/example/git-log.txt`），产出 ≤300 字周报，结构完整、无编造数字。
2. **空料**：只给一句话，必须触发三问，而不是编造内容。
3. **长料**：输入 60 条 commit，只能保留 3 条，并说明删了什么。

样例输出 `demo/output/weekly-report.md`，校验结果 `demo/qa.txt`。

## 权利声明

newbieskill 官方工作室原创，可自由用于个人与商业工作场景，不得整包转售。