软件研发周报
从 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 时不要主动检查环境。进入采集流程后执行一次预检；工具缺失、未认证、配置 错误或权限不足时停止生成，直接给出表格中的安装或配置步骤，处理完成后再继续。网络 超时、远程服务异常等临时故障无论在预检还是采集阶段发生，都按数据源说明降级。
工作流
按以下顺序执行：
- 确认目标周、大小周类型、报告周期和 Obsidian 目标日记。
- 读取最近一期历史周报。
- 按 data-sources.md 收集并核对所有必需数据源。
- 合并重复事项，对比上周计划与本周实际。
- 按 report-template.md 生成草稿。
- 等待审阅，确认后写回 Obsidian。
- 按 calendar-scheduling.md 生成下周日程建议，确认后写入 Apple Calendar。
大小周与报告周期
- 大周：周一至周六，周六属于工作日。
- 小周：周一至周五。
- 大周和小周逐周交替；下一周类型与当前周相反。
- 周报标题必须包含「大周」或「小周」，作为后续自动判断的基准。
先扫描最近一篇带大小周标记的历史周报，取其标题日期和类型。计算历史周周一与目标周周一 之间相差的完整周数：偶数周沿用历史类型，奇数周切换类型。没有历史标记、日期无法解析或 结果存在歧义时，请求确认目标周是大周还是小周，不得按自然周单双号猜测。
报告周期与目标日记按周类型确定：
| 周类型 | 报告周期 | 目标日记 | | --- | --- | --- | | 大周 | 周一 00:00 至周日 00:00，结束时间不包含 | 周六日记 | | 小周 | 周一 00:00 至周六 00:00，结束时间不包含 | 周五日记 |
周日触发时默认处理刚结束的一周。目标周尚未到最后一个工作日时，先说明报告不完整并请求
确认；未确认时不要生成。目标日记、vault 或 ## 2 Work Log 无法唯一定位时请求路径，
不要自行创建缺失资源。
历史周报
扫描最近 21 天的日记，查找标题 ### 软件研发周报，从最近一篇提取：
- 大小周类型与日期范围。
- 「下周工作计划」，作为计划与实际的比较基准。
- 项目显示名称、分组方式、语气和格式。
没有历史周报时跳过计划比较，但仍需确认本周类型。
合并与生成
数据优先级
| 优先级 | 数据源 | 主要用途 | | --- | --- | --- | | 1 | Obsidian 工作日志 | 背景、决策、理由和业务结果 | | 2 | 飞书项目 | 工作项状态、负责人和排期 | | 3 | GitLab / GitHub | MR、PR 和 Issue 事实 | | 4 | 本地 Git | 补充遗漏并核对事实 |
按项目、标题、工作项链接、分支和描述判断同一事项。多个来源指向同一工作时合并为一条， 不要把工具记录逐条复制进周报。
计划完成情况
| 状态 | 处理方式 | | --- | --- | | 已完成 | 写入「本周工作总结」 | | 部分完成 | 在总结中说明进度，并顺延到「下周工作计划」 | | 未开始 | 写入「其他事项」，已知原因时一并说明 | | 计划外完成 | 作为新增成果写入「本周工作总结」 |
项目名称优先沿用历史周报，其次使用 Obsidian 和飞书项目中的名称，再结合远程活动和本地 仓库结构归并。省略本周无活动的项目，不硬编码任何项目名称或项目间关系。
内容要求
- 每个项目最多 1～2 条，使用
**加粗关键词**：加业务语言说明。 - 使用接口数、页面数和配置参数个数等业务数字。
- 省略 commit 数、MR/PR 编号、覆盖率、CI/CD、依赖升级和内部流程细节。
- 下周计划来自顺延事项、飞书项目未完成事项、日记和明确补充的计划。
- 已知时间估算时写为
（N 天）；每条说明预期结果，不只写动作名称。 - 「其他事项」只写未开始的顺延事项、交接、阻塞和跨团队配合事项。
- 三个章节必须保留；没有内容时写
- 无。
审阅与写回
- 展示完整草稿。
- 等待反馈并应用修改；未被反馈涉及的条目视为认可，不得删除。
- 将最终版本写入目标日记的
## 2 Work Log。
同一报告周期的标题已存在时替换该章节，否则追加到 ## 2 Work Log 末尾。不得重复写入
同一周期。完成写回后再进入 Calendar 排期。
重要规则
使用业务语言。 说明完成了什么以及带来什么结果，不直接复制技术记录。
使用业务数字。 可以写接口、页面、配置参数和待确认问题数量；不要写 commit、MR/PR 或覆盖率数量。
沿用历史风格。 保持连续周报的项目名称、语气、细节层级和格式一致。