周报生成器

从Git提交记录自动生成专业工作周报，支持单周/多周批量生成。

核心原则

主子分离：主智能体负责调度，子智能体负责实际生成
精简输出：只输出提交消息数组，不包含冗余信息
只读Git日志：禁止读取项目源代码文件
必须内容清洗：技术术语转换为业务语言（AI执行，不可跳过）
任务管理：使用 TodoWrite 工具创建任务清单，追踪每个周报的生成状态

快速开始

生成周报只需 2 个步骤：

Step 1: 运行编排脚本准备数据 → Step 2: 并行处理每个周报

Step 1: 运行编排脚本（准备数据）

python scripts/orchestrate_reports.py \
  --paths "E:\项目1,E:\项目2" \
  --time "本月" \
  --output "E:\周报输出" \
  --template "E:\模板.docx" \
  --format docx \
  --naming "第一周周报,第二周周报,第三周周报,第四周周报"

脚本自动完成：

解析时间表达式（本周/本月/2025-1-1-2025-1-31）
验证项目路径和输出路径
分析模板文件（识别需要补充的章节）
为每个周生成独立任务配置文件
生成二次确认信息和 Claude Code 调用说明

输出文件（位于 {输出路径}/tmp/）：

time_result.json - 时间解析结果
template_structure.json - 模板结构（如果提供模板）
week_XX-task.json - 每个周的任务配置
claude_instruction.md - Claude Code 调用说明

Step 2: 并行处理每个周报（AI 执行）

创建任务清单（必须）：

# 使用 TodoWrite 工具创建任务清单
todos = [
  {"content": "读取调用说明和参考文档", "status": "pending", "activeForm": "读取调用说明和参考文档"},
  {"content": "为第1周启动子智能体", "status": "pending", "activeForm": "为第1周启动子智能体"},
  {"content": "为第2周启动子智能体", "status": "pending", "activeForm": "为第2周启动子智能体"},
  # ... 为每个周创建一个任务
  {"content": "汇总所有结果并清理临时文件", "status": "pending", "activeForm": "汇总所有结果并清理临时文件"}
]

读取参考文档：

需要脚本参数：读取 references/script-api-reference.md 查看详细参数

工作流程：

读取调用说明：{输出路径}/tmp/claude_instruction.md（标记第一个任务为 in_progress）
并行启动子智能体：使用 Task 工具为每个周启动独立的 general-purpose 子智能体
- 📘 调用方法：参考 references/workflow.md 第 2.2 节的详细示例
- 在同一个响应中调用多次 Task 工具实现并行处理
- 为每个子任务标记状态（启动时 → in_progress，完成时 → completed）
- ⚠️ 重要：子智能体必须只返回简短的成功/失败状态，不要输出详细报告
汇总结果：收集所有子任务的成功/失败状态（标记为 in_progress）
清理临时文件：删除成功的临时文件，保留失败的用于调试（标记为 completed）

⚠️ 子智能体输出规范（重要）：

✅ 只返回简短状态："✅ 第X周周报生成成功" 或 "❌ 第X周周报生成失败：[原因]"
❌ 不要输出详细的工作内容、数据统计、术语转换示例等
❌ 不要输出详细的执行步骤说明
✅ 严格按模板输出：
- 如果提供了模板（--template参数）：只输出模板格式的周报文件

完整的工作流程和 Task 工具调用示例：📘 workflow.md

参考文档

📘 workflow.md

完整的工作流程指南，包含：

详细的 Step 2 执行步骤
子智能体任务提示模板（可直接复制使用）
临时文件结构和清理规则

📘 examples.md

常见使用场景示例：

示例1：生成本月周报（Markdown格式）
示例2：使用Word模板
示例3：批量生成多周周报
示例4：多项目汇总

📘 script-api-reference.md

Python 脚本详细调用参数和使用示例：

parse_time.py - 时间解析
analyze_template.py - 模板分析
get_git_logs.py - Git日志获取（精简模式）
fill_template.py - 模板填充和导出
orchestrate_reports.py - 编排所有步骤

参数说明

orchestrate_reports.py 参数

--paths（必须）：项目路径列表，逗号分隔
--time（必须）：时间表达式
- 相对时间：本周、上周、本月、上月、本年、去年
- 绝对时间：YYYY-MM-DD 或 YYYY-MM-DD-YYYY-MM-DD
--output（必须）：输出目录路径
--template（可选）：模板文件路径（支持 .md 和 .docx）
--format（可选，默认 md）：输出格式（md 或 docx）
--naming（可选）：周报命名规则列表，逗号分隔
- 推荐使用：为每个周报指定自定义文件名
- 示例：--naming "华电第一周周报,华电第二周周报"
- 命名规则数量必须与生成的周报数量一致
- 不提供时使用默认命名：第X周周报.docx

时间表达式示例

表达式	说明	生成的周报
`本周`	当前周的周一到周五	1份
`本月`	本月1日到最后一日（按周划分）	4-5份
`2025-1-1-2025-1-31`	指定时间范围	按周划分
`2025-1-15`	指定日期所在周	1份

常见问题

Q: 临时文件保存在哪里？ A: {输出路径}/tmp/ 目录，成功后自动清理

weekly-report-generator