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 上月

标准执行流程

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 只读，不覆盖。

2. 生成优化后 JSON（必做）

• 使用 resources/prompt.txt 对原始 JSON 中文化、报告化。
• 将 commit message 转为适合业务汇报的中文表述。
• 另存为新文件，例如：本周工作周报_ai.json。

3. 渲染 Word

node <skill_root>/scripts/weekly_render.js -i <优化后的JSON> -o <输出文件>.docx

4. 输出便于复制的任务清单

node <skill_root>/scripts/weekly_list.js -i <优化后的JSON>

• 输出格式为带数字序号的纯文本任务内容，便于直接复制。
• 序号格式固定为 1、2、3、...。

5. 返回结果

• 直接给出最终 .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。
• 对用户侧应以“描述需求 -> 自动生成报告”为主，不要求用户手动执行安装或构建命令。