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
可复制任务清单：
```text
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` / `month`
- `day_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：可跳过统计，直接执行：
```bash
node <skill_root>/scripts/weekly_render.js -i <已有JSON> -o <输出文件>.docx
说明
- 若未找到仓库，优先检查
repo_paths 或 repo_roots。
- 对用户侧应以“描述需求 -> 自动生成报告”为主，不要求用户手动执行安装或构建命令。