周报生成器 (Weekly Report Generator)

概述

自动扫描本机 Git 仓库，提取本周（周一到今天）的 commit 记录，按项目分类提炼为标准化周报格式，并通过微信频道推送给用户。支持 Mac / Linux / Windows 全平台，支持作者过滤、容错处理、消息分批发送。

工作流程

Step 1: 确认项目路径

1. 使用 mcp__agent-memory__memory (action: search, query: "项目路径" or "project_path") 检查是否已保存项目根目录
2. 如果已有记录，直接使用该路径，跳到 Step 2
3. 如果没有记录，友好地询问用户：

   "方便告诉我你公司的项目文件夹在本机哪个位置吗？比如 D:/projects 这样的路径。告诉我一次我就记住了，以后每次生成周报都直接用，不用再问你。如果不提供的话，我也会默认帮你全局搜索，只是指定路径会更快更准。"

4. 获取路径后，使用 mcp__agent-memory__memory (action: update) 将路径写入 FACT.md，格式：

   ## 项目信息
   - 项目根目录: <用户提供的路径>
   - 操作系统: 
   - Git 用户名: <通过 git config 获取>
   

5. 如果用户不提供路径，跳过指定，使用默认策略：在用户主目录下搜索所有 .git 目录（见 Step 4 兜底逻辑）。同时写入标记到 FACT.md，避免下次再询问：

   - 项目根目录: 未指定(使用全局搜索)
   

6. 同时使用 mcp__agent-memory__memory (action: append, tags: ["setup", "project_path"]) 记录到日志

Step 2: 确认周报模板

1. 使用 mcp__agent-memory__memory (action: search, query: "周报模板" or "weekly_report_template") 检查是否已保存周报模板
2. 如果已有模板记录，直接使用该模板，跳到 Step 3
3. 如果没有记录，友好地询问用户：

   "你之前写过周报吗？如果方便的话发一份给我，我来学习你的格式和风格，以后生成的周报就会跟你以前写的一模一样。只需要配置一次，我就会记住。如果不提供也没关系，我会用一个通用的标准模板来生成。"

4. 如果用户提供了历史周报：
   • 分析其结构（标题格式、段落划分、用词风格、表格/列表偏好）
   • 提炼出模板规则（标题怎么写、总结怎么分、问题怎么列、计划怎么写）
   • 使用 mcp__agent-memory__memory (action: update) 将模板规则写入 FACT.md：

     ## 周报模板
     - 标题格式: <用户周报的标题格式>
     - 结构: <用户周报的段落划分方式>
     - 用词风格: <正式/简洁/技术向>
     - 字数要求: <每项控制在多少字以内>
     - 特殊要求: <其他个性化需求>
     - 示例: <用户提供的周报原文摘录>
     

5. 如果用户没有提供或不想提供，使用下方的"默认模板"。同时写入标记到 FACT.md，避免下次再询问：

   ## 周报模板
   - 模板类型: 默认模板
   

Step 3: 确认 Git 作者并计算日期范围

3a. 获取 Git 用户名和邮箱

AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

保存到 FACT.md 中，后续过滤使用。

3b. 检测操作系统并计算日期范围

必须兼容 Mac / Linux / Windows 三个平台，使用平台检测分支。注意周日边界处理：

# 检测操作系统
OS="$(uname -s)"
DOW=$(date +%u)  # 1=Monday, 7=Sunday

case "$OS" in
  Darwin*)
    # Mac (BSD date)
    if [ "$DOW" = "1" ]; then
      MONDAY=$(date +%Y-%m-%d)
    elif [ "$DOW" = "7" ]; then
      MONDAY=$(date -v-6d +%Y-%m-%d)  # 周日：本周一是6天前
    else
      MONDAY=$(date -v-monday +%Y-%m-%d)
    fi
    TODAY=$(date +%Y-%m-%d)
    TOMORROW=$(date -v+1d +%Y-%m-%d)
    ;;
  Linux*)
    # Linux (GNU date)
    if [ "$DOW" = "1" ]; then
      MONDAY=$(date +%Y-%m-%d)
    elif [ "$DOW" = "7" ]; then
      MONDAY=$(date -d "6 days ago" +%Y-%m-%d)  # 周日：本周一是6天前
    else
      MONDAY=$(date -d "last monday" +%Y-%m-%d)
    fi
    TODAY=$(date +%Y-%m-%d)
    TOMORROW=$(date -d "tomorrow" +%Y-%m-%d)
    ;;
  MINGW*|MSYS*|CYGWIN*)
    # Windows Git Bash (GNU date)
    if [ "$DOW" = "1" ]; then
      MONDAY=$(date +%Y-%m-%d)
    elif [ "$DOW" = "7" ]; then
      MONDAY=$(date -d "6 days ago" +%Y-%m-%d)
    else
      MONDAY=$(date -d "last monday" +%Y-%m-%d)
    fi
    TODAY=$(date +%Y-%m-%d)
    TOMORROW=$(date -d "tomorrow" +%Y-%m-%d)
    ;;
  *)
    # 兜底
    if [ "$DOW" = "1" ]; then
      MONDAY=$(date +%Y-%m-%d 2>/dev/null)
    elif [ "$DOW" = "7" ]; then
      MONDAY=$(date -d "6 days ago" +%Y-%m-%d 2>/dev/null || date -v-6d +%Y-%m-%d 2>/dev/null)
    else
      MONDAY=$(date -d "last monday" +%Y-%m-%d 2>/dev/null || date -v-monday +%Y-%m-%d 2>/dev/null)
    fi
    TODAY=$(date +%Y-%m-%d 2>/dev/null)
    TOMORROW=$(date -d "tomorrow" +%Y-%m-%d 2>/dev/null || date -v+1d +%Y-%m-%d 2>/dev/null)
    ;;
esac

echo "周报范围: $MONDAY ~ $TODAY"

重要：日期范围使用 --since=$MONDAY --until=$TOMORROW，确保精确覆盖"本周一到今天"，而不是模糊的"最近7天"。

Step 4: 扫描 Git 仓库并获取提交记录

4a. 查找所有 Git 仓库

使用 find 递归搜索，排除无效目录，限制深度：

# 有指定路径时：在指定路径下搜索
find "<项目根目录>" -name ".git" -type d -maxdepth 3 
  -not -path "*/node_modules/*" 
  -not -path "*/.Trash/*" 
  -not -path "*/Library/*" 
  -not -path "*/AppData/*" 
  -not -path "*/.npm/*" 
  -not -path "*/.cache/*" 
  2>/dev/null | while read gitdir; do
    dir=$(dirname "$gitdir")
    echo "$dir"
done

# 无指定路径时（兜底）：在用户主目录下搜索
find ~ -name ".git" -type d -maxdepth 4 
  -not -path "*/node_modules/*" 
  -not -path "*/.Trash/*" 
  -not -path "*/Library/*" 
  -not -path "*/AppData/*" 
  -not -path "*/.npm/*" 
  -not -path "*/.cache/*" 
  -not -path "*/.vscode/*" 
  -not -path "*/.git/*" 
  2>/dev/null | while read gitdir; do
    dir=$(dirname "$gitdir")
    echo "$dir"
done

注意：-maxdepth 3（指定路径）或 -maxdepth 4（全局兜底）防止在 node_modules 等深层目录中卡死。

4b. 获取提交记录

使用 git -C 替代 cd，避免目录切换开销和路径问题：

AUTHOR="$AUTHOR_NAME"
SINCE="$MONDAY"
UNTIL="$TOMORROW"

RESULT=""
ERROR_COUNT=0
ERROR_PROJECTS=""
TOTAL_COMMITS=0

for dir in <上面查找到的所有目录>; do
  proj=$(basename "$dir")

  # 使用 git -C 直接在目标目录执行，无需 cd
  commits=$(git -C "$dir" log --since="$SINCE" --until="$UNTIL" --author="$AUTHOR" --format="%ai | %an | %s" 2>/dev/null)

  if [ $? -ne 0 ]; then
    ERROR_COUNT=$((ERROR_COUNT + 1))
    ERROR_PROJECTS="${ERROR_PROJECTS}  - ${proj}: git log 执行失败n"
    continue
  fi

  if [ -n "$commits" ]; then
    # 使用 grep -c 计算行数，避免 wc -l 在无换行符时返回 0 的问题
    count=$(echo "$commits" | grep -c '')
    TOTAL_COMMITS=$((TOTAL_COMMITS + count))
    RESULT="${RESULT}===PROJECT:${proj}===n${commits}n"
  fi
done

容错规则：

• 每个仓库独立 try-catch，出错后 continue 继续下一个
• 收集错误信息，在周报末尾提示用户
• 使用 git -C 替代 cd，更快且避免路径丢失风险
• 使用 grep -c '' 替代 wc -l，避免空字符串计数陷阱
• 使用 --author 过滤（模糊匹配 Name 和 Email），只统计本人提交
• 如果用户名包含特殊字符（如 .），使用 git -C "$dir" log --author="$AUTHOR_EMAIL" 用邮箱精确匹配

Step 5: 分类总结为周报格式

将获取的 commit 按以下规则处理：

1. 按项目分组：每个有提交的项目作为一个独立板块
2. 按日期排序：每个项目内的提交按时间倒序
3. 提炼分类：将 commit message 按类型分组：
   • feat: / 新增 / 新功能 → 功能开发
   • fix: / 修复 / bug → Bug 修复
   • refactor: / 重构 / 优化 → 优化改进
   • docs: / 文档 → 文档
   • style: / 样式 / css → 样式调整
   • chore: / 配置 / 构建 → 工程配置
   • init / 初始化 → 项目初始化
   • 其他 → 其他
4. 字数控制：每个工作事项精简到 150 字以内，保留核心信息
5. 生成总结：每个项目末尾写一段 1-2 句的总结

注意：项目名称直接使用 Git 仓库目录名，不加业务描述括号。例如直接写 shiotp-web-jintan，不写 shiotp-web-jintan（后勤管理系统）。

Step 6: 输出周报

默认模板（无历史周报时使用）

当前对话版（支持 Markdown 表格）：

XX周工作周报（YYYY年MM月DD日 - MM月DD日）

一、本周工作总结

共涉及 N 个项目，M 次提交。

| 项目 | 提交数 | 主要工作 |
|------|--------|---------|
| 项目A | X次 | 采购模块API开发 |
| 项目B | X次 | 图片上传功能优化 |
| 项目C | X次 | 新项目初始化 |

项目A：shiotp-web-jintan
- 新增采购申请管理模块API接口
- 重构数量和金额的计算逻辑，新增格式化方法
- 新增出库单管理模块API，支持申请单列表查询

项目B：HOMEdecor
- 新增收藏功能，优化商品展示逻辑
- 重构上传文件功能，添加图片上传压缩
- 优化涂抹功能，支持原图信息和高清导出

二、其他需反馈的事项（选填）
- （如有需协调/反馈的事项）

微信推送版（纯文本，不使用 Markdown 表格，因为微信聊天框不支持渲染）：

XX周工作周报（YYYY年MM月DD日 - MM月DD日）

一、本周工作总结
共涉及 N 个项目，M 次提交：

1. 项目A (X次)：采购模块API开发
2. 项目B (X次)：图片上传功能优化
3. 项目C (X次)：新项目初始化

项目A：shiotp-web-jintan
- 新增采购申请管理模块API接口
- 重构数量和金额的计算逻辑
- 新增出库单管理模块API

项目B：HOMEdecor
- 新增收藏功能
- 重构上传文件功能
- 优化涂抹功能

二、其他需反馈的事项
- （选填）

用户自定义模板（有历史周报时使用）

从 Step 2 保存的记忆中提取模板结构，严格按照用户的历史格式生成。优先遵循：

• 用户的标题格式
• 用户的段落划分方式
• 用户的用词风格
• 用户的字数要求

Step 7: 确认并发送

7a. 人工确认（必须）

周报生成后，先询问用户确认，不要直接发送：

"周报已生成，请查看上方内容。是否需要修改或补充？或者直接回复'发送'推送到微信。"

原因：AI 的归类可能不完全符合员工想向老板表达的意图，增加一次确认能大幅提高准确度。

7b. 发送

用户确认后执行发送：

1. 当前对话：周报已在确认环节展示（必做）
2. 微信推送（可选）：
   • 使用 mcp__claw__config (action: status) 检查微信频道是否已连接（connected: true）
   • 如果已连接，使用 mcp__claw__notify (message: 微信推送版内容, channel_id: 微信频道ID) 推送
   • 微信推送必须使用纯文本版，不使用 Markdown 表格
   • 如果推送到 0 个会话，提醒用户需要先在微信上给机器人发一条消息建立会话
   • 如果未连接，告知用户微信未连接，跳过推送

7c. 微信消息长度控制

微信单条消息建议不超过 2000 字符。如果周报内容超过此限制，按以下策略分批发送：

1. 计算总长度：发送前先计算完整周报的字符数
2. 如果 <= 2000 字符：一次性发送完整周报
3. 如果 > 2000 字符：分批策略：
   • 第一条：摘要（标题 + 项目汇总列表 + 各部分标题概述）
   • 后续条：按项目逐条发送（每个项目作为一条独立消息）
   • 每条消息末尾标注 [第X条/共N条]

发送时使用循环逐条调用 mcp__claw__notify，每条之间不设间隔。

记忆隔离规则

只记忆静态配置，不记忆运行时数据：

原因：LLM 的上下文和记忆库有限，几周的 commit 积累会冲垮 Token 限制，且让后续检索变慢。

输出建议

• 突出工作重点，舍去非关键细节
• 用明确、简洁的语言表达
• 加强列表、表格等格式的利用
• 最后检查字数控制情况
• 确保每个工作事项精简到 150 字以内
• 不要使用 emoji，保持正式文档风格

注意事项

• commit message 保持原样，不要篡改内容
• 如果没有提交记录，告知用户"本周暂无 Git 提交记录"
• 日期范围严格使用本周一到今天，不用"最近7天"
• 只统计当前用户的提交，排除同事提交
• 周报中不包含文件变更详情，只展示 commit message
• 微信单条消息不超过 2000 字符，超出时按项目分批发送
• 微信推送使用纯文本版，不使用 Markdown 表格
• 单个仓库出错不影响整体，错误信息在周报末尾提示
• 如果有处理失败的项目，在周报末尾附加警告信息
• 跨平台兼容：date 命令需根据 OS 分支处理（Darwin=Mac, Linux/MSYS=GNU date）
• 注意周日边界：周日的"last monday"会回到上周一，需特殊处理
• 使用 git -C 替代 cd，性能更好且避免路径丢失
• 使用 find 递归搜索 .git，排除 node_modules 等无效目录
• 使用 grep -c '' 替代 wc -l，避免无换行符时计数为 0
• 发送前必须经过用户确认
• 不使用 emoji，保持专业周报风格
• 项目名称直接使用仓库目录名，不加业务描述括号
• 不提供路径或模板时写入标记到 FACT.md，避免下次重复询问