# Weekly Report

> 仅适用于 macOS。用于生成结构化的软件研发周报，适用于「周报」「软件研发周报」 「本周工作总结」「写周报」、weekly report、end-of-week summary，以及需要向主管或 团队提交工作总结的情况。不用于个人日记、月度回顾、OKR 总结、会议记录或季度回顾。

- Skill: `niracler/weekly-report` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add niracler/weekly-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/niracler/weekly-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: niracler (https://skillmd.com/u/niracler)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/niracler/weekly-report

---


# 软件研发周报

从 Obsidian、飞书项目、GitLab、GitHub 和本地 Git 收集事实，生成主管可读的中文周报。
审阅完成后写回 Obsidian，并把下周计划安排到 Apple Calendar。

## 前置条件

| 工具或资源 | 类型 | 必需 | 安装或配置方式 |
| --- | --- | --- | --- |
| Git | `cli` | 是 | `brew install git` |
| Node.js | `cli` | 是 | `brew install node` |
| Obsidian | `system` | 是 | 提供已存在且包含工作日志的 vault |
| macOS Calendar | `system` | 是 | macOS 内置，通过 `osascript` 访问 |
| `meegle` | `cli` | 是 | `npx @lark-project/meegle@latest install` |
| GitLab MCP | `mcp` | 是 | 在 Codex MCP 配置中启用已安装的 GitLab MCP，设置自建地址和访问令牌，再重启会话 |
| `gh` | `cli` | 是 | `brew install gh`，然后运行 `gh auth login` |

> 加载 Skill 时不要主动检查环境。进入采集流程后执行一次预检；工具缺失、未认证、配置
> 错误或权限不足时停止生成，直接给出表格中的安装或配置步骤，处理完成后再继续。网络
> 超时、远程服务异常等临时故障无论在预检还是采集阶段发生，都按数据源说明降级。

## 工作流

按以下顺序执行：

1. 确认目标周、大小周类型、报告周期和 Obsidian 目标日记。
2. 读取最近一期历史周报。
3. 按 [data-sources.md](references/data-sources.md) 收集并核对所有必需数据源。
4. 合并重复事项，对比上周计划与本周实际。
5. 按 [report-template.md](references/report-template.md) 生成草稿。
6. 等待审阅，确认后写回 Obsidian。
7. 按 [calendar-scheduling.md](references/calendar-scheduling.md) 生成下周日程建议，确认后写入
   Apple Calendar。

## 大小周与报告周期

- **大周**：周一至周六，周六属于工作日。
- **小周**：周一至周五。
- 大周和小周逐周交替；下一周类型与当前周相反。
- 周报标题必须包含「大周」或「小周」，作为后续自动判断的基准。

先扫描最近一篇带大小周标记的历史周报，取其标题日期和类型。计算历史周周一与目标周周一
之间相差的完整周数：偶数周沿用历史类型，奇数周切换类型。没有历史标记、日期无法解析或
结果存在歧义时，请求确认目标周是大周还是小周，不得按自然周单双号猜测。

报告周期与目标日记按周类型确定：

| 周类型 | 报告周期 | 目标日记 |
| --- | --- | --- |
| 大周 | 周一 00:00 至周日 00:00，结束时间不包含 | 周六日记 |
| 小周 | 周一 00:00 至周六 00:00，结束时间不包含 | 周五日记 |

周日触发时默认处理刚结束的一周。目标周尚未到最后一个工作日时，先说明报告不完整并请求
确认；未确认时不要生成。目标日记、vault 或 `## 2 Work Log` 无法唯一定位时请求路径，
不要自行创建缺失资源。

## 历史周报

扫描最近 21 天的日记，查找标题 `### 软件研发周报`，从最近一篇提取：

1. 大小周类型与日期范围。
2. 「下周工作计划」，作为计划与实际的比较基准。
3. 项目显示名称、分组方式、语气和格式。

没有历史周报时跳过计划比较，但仍需确认本周类型。

## 合并与生成

### 数据优先级

| 优先级 | 数据源 | 主要用途 |
| --- | --- | --- |
| 1 | Obsidian 工作日志 | 背景、决策、理由和业务结果 |
| 2 | 飞书项目 | 工作项状态、负责人和排期 |
| 3 | GitLab / GitHub | MR、PR 和 Issue 事实 |
| 4 | 本地 Git | 补充遗漏并核对事实 |

按项目、标题、工作项链接、分支和描述判断同一事项。多个来源指向同一工作时合并为一条，
不要把工具记录逐条复制进周报。

### 计划完成情况

| 状态 | 处理方式 |
| --- | --- |
| 已完成 | 写入「本周工作总结」 |
| 部分完成 | 在总结中说明进度，并顺延到「下周工作计划」 |
| 未开始 | 写入「其他事项」，已知原因时一并说明 |
| 计划外完成 | 作为新增成果写入「本周工作总结」 |

项目名称优先沿用历史周报，其次使用 Obsidian 和飞书项目中的名称，再结合远程活动和本地
仓库结构归并。省略本周无活动的项目，不硬编码任何项目名称或项目间关系。

### 内容要求

- 每个项目最多 1～2 条，使用 `**加粗关键词**：` 加业务语言说明。
- 使用接口数、页面数和配置参数个数等业务数字。
- 省略 commit 数、MR/PR 编号、覆盖率、CI/CD、依赖升级和内部流程细节。
- 下周计划来自顺延事项、飞书项目未完成事项、日记和明确补充的计划。
- 已知时间估算时写为 `（N 天）`；每条说明预期结果，不只写动作名称。
- 「其他事项」只写未开始的顺延事项、交接、阻塞和跨团队配合事项。
- 三个章节必须保留；没有内容时写 `- 无`。

## 审阅与写回

1. 展示完整草稿。
2. 等待反馈并应用修改；未被反馈涉及的条目视为认可，不得删除。
3. 将最终版本写入目标日记的 `## 2 Work Log`。

同一报告周期的标题已存在时替换该章节，否则追加到 `## 2 Work Log` 末尾。不得重复写入
同一周期。完成写回后再进入 Calendar 排期。

## 重要规则

**使用业务语言。** 说明完成了什么以及带来什么结果，不直接复制技术记录。

**使用业务数字。** 可以写接口、页面、配置参数和待确认问题数量；不要写 commit、MR/PR
或覆盖率数量。

**沿用历史风格。** 保持连续周报的项目名称、语气、细节层级和格式一致。