report 技能说明
这个技能是做什么的
- 从一个或多个 Git 仓库收集提交记录，自动生成日报/周报/月报。
- 产出三类文件：
原始 JSON、优化后 JSON、Word(.docx)。 - 适合把开发提交快速整理成可汇报材料。
何时使用
- 用户说“生成日报/周报/月报”。
- 用户说“根据 Git 提交出报告/周报/月报”。
- 用户已有报告 JSON，需要渲染成 Word。
输入与前置条件
- Node.js 18+。
- 可访问的 Git 仓库（单仓库或多仓库）。
- 可选作者过滤：
author（姓名/邮箱，支持逗号分隔或数组）。 - 当用户明确要求日报/周报/月报时，分别使用：
- 日报 -> stat_mode=day - 周报 -> stat_mode=week - 月报 -> stat_mode=month
参数与口径说明
weekly.js支持参数：
- -m, --stat-mode <mode>：统计模式。
stat_mode兼容输入：
- 日：day / daily / 日 / 日报 - 周：week / weekly / 周 / 周报 - 月：month / monthly / 月 / 月报
- 时间偏移口径：
- day_offset=0 今天，1 昨天 - week_offset=0 本周，1 上周 - month_offset=0 本月，1 上月
标准执行流程
- 生成原始 JSON
node <skill_root>/scripts/weekly.js --stat-mode day|week|month- 也支持中文参数：
日报/周报/月报。 - 输出文件示例：
本日工作日报_YYYY-MM-DD.json、本周工作周报_YYYY-MM-DD.json。 - 默认输出到
output_dir（若未配置则回退到~/Desktop，再回退到当前目录）。 - 原始 JSON 只读，不覆盖。
- 生成优化后 JSON（必做）
- 使用
resources/prompt.txt对原始 JSON 中文化、报告化。 - 将 commit message 转为适合业务汇报的中文表述。
- 另存为新文件，例如：
本周工作周报_ai.json。
- 渲染 Word
node <skill_root>/scripts/weekly_render.js -i <优化后的JSON> -o <输出文件>.docx- 输出便于复制的任务清单
node <skill_root>/scripts/weekly_list.js -i <优化后的JSON>- 输出格式为带数字序号的纯文本任务内容，便于直接复制。
- 序号格式固定为
1、2、3、...。
- 返回结果
- 直接给出最终
.docx完整路径。 - 同时给出优化后 JSON 的完整路径。
- 不需要再询问“是否继续渲染 Word”。
- 必须额外返回带数字序号的任务内容清单，便于用户直接复制。
- 任务内容清单必须使用纯文本代码块输出，禁止使用 Markdown 有序列表。
- 推荐固定回复格式如下：
Word：/absolute/path/to/report.docx
JSON：/absolute/path/to/report_ai.json
可复制任务清单：1、第一条任务 2、第二条任务
配置与异常处理
- 配置文件读取顺序：
1. REPORT_CONFIG 指向的文件 2. WEEKLY_REPORT_CONFIG（兼容） 3. 当前目录 report.config.json 4. 当前目录 weekly.config.json（兼容） 5. ~/.config/report/config.json 6. ~/.config/weekly-report/config.json（兼容） 7. ~/.report.json 8. ~/.weekly-report.json（兼容）
- 字段示例：
resources/config.example.json。 - 可用
REPORT_REPO_ROOTS临时指定仓库根目录（系统路径分隔符分隔）。 - 兼容环境变量：
WEEKLY_REPORT_REPO_ROOTS。 - 可用
REPORT_OUTPUT_DIR临时指定输出目录。 - 兼容环境变量：
WEEKLY_REPORT_OUTPUT_DIR。 - 首次运行若未找到配置，会自动生成默认配置到
~/.config/report/config.json并立即退出。 - 当输出包含
CONFIG_INIT_REQUIRED时，必须停止后续流程，仅提示用户先完成配置再重跑。
关键配置项
stat_mode:day/week/monthday_offset: 0=今天，1=昨天week_offset: 0=本周，1=上周month_offset: 0=本月，1=上月repo_roots: 仓库根目录列表（递归扫描）repo_paths: 显式仓库路径（非空时优先）company_git_patterns: 按远程地址关键词过滤仓库max_scan_depth: 扫描深度（默认4）output_dir: 报告默认输出目录
输出结构（用于优化与渲染）
- 原始 JSON 关键字段：
- report_type: 日报 / 周报 / 月报 - period.start_date / period.end_date - statistics.total_commits / statistics.total_tasks - projects[].project_name + tasks[] - tasks[] 每项包含：content / completion_standard / status / notes / project_name
weekly_render.js最少依赖：
- report_type - period.start_date, period.end_date - statistics.total_commits - tasks[]
常见失败处理
CONFIG_INIT_REQUIRED：先补全配置再重跑，不继续后续流程。- 扫描到 0 个仓库：优先检查
repo_paths、repo_roots、company_git_patterns。 - 需要只渲染 Word：可跳过统计，直接执行：
node <skill_root>/scripts/weekly_render.js -i <已有JSON> -o <输出文件>.docx说明
- 若未找到仓库，优先检查
repo_paths或repo_roots。 - 对用户侧应以“描述需求 -> 自动生成报告”为主，不要求用户手动执行安装或构建命令。