Weekly Digest（Git 周报生成器）

从 Git 历史生成可核验的中文周报。先采集事实，再按受众重组表达；不得把 Git 无法证明的信息写成事实。

语言与事实边界

• 所有面向用户的输出使用中文；代码、路径、变量名保持原文。
• 提交数、代码行数、文件数、作者、项目名必须来自 scripts/collect.sh 或等价的真实 Git 命令，且保留其统计范围。
• Git 只能证明代码活动，不能证明上线、完成度、业务结果、阻塞、风险、下周计划或客户承诺。缺少用户提供的佐证时，省略这些字段，或标为「待补充」，不得推断。
• 不向客户或高管视图暴露 commit hash、作者邮箱、内部路径、代码行数等实现细节，除非用户明确要求。

口令与视图

默认使用工程视图。用户同时指定多个受众时，先输出一个“事实底稿”，再分别渲染受众版本，避免不同版本的数据不一致。

执行流程

1. 确定范围与项目来源

1. 用户明确列出仓库路径时，直接使用这些仓库；当前目录是 Git 仓库且未要求多项目时，直接使用当前仓库。
2. 用户要求多项目、扫描目录，或当前目录不是 Git 仓库且未提供项目列表时，进入“扫描并选择”流程。不要擅自扫描用户主目录、工作区根目录或其他宽泛目录。
3. 用户给出日期时，以该日所在周为本周；否则本周为本周一至今天，上周为上周一至上周日。
4. 解析受众视图、贡献者视图、是否包含上周、PR 关联和导出要求。

2. 扫描并让用户选择项目

这是目录扫描模式的必经步骤，先发现活跃仓库、再征求选择、最后才采集周报详情。

1. 确定扫描目录：优先使用用户明确给出的目录；否则读取 ~/.claude/weekly-digest-projects.json 中的 scan_roots。两者都没有时，询问用户：“请提供要扫描的目录绝对路径，例如 /Users/name/workspace。”

2. 扫描活跃仓库：运行以下命令，仅寻找本周当前分支有非 merge 提交的 Git 仓库：

   ./scripts/scan-repos.sh /path/to/workspace

   传入指定周的起始日：

   ./scripts/scan-repos.sh /path/to/workspace 2026-05-19

   默认只识别普通 .git 目录，扫描时不向已识别的仓库内部继续递归；嵌套仓库需要用户显式提供其路径。扫描只读，不修改仓库。

3. 展示候选清单：将脚本结果按提交数降序编号，给出项目名、路径、提交数和最新提交摘要。例如：

   发现 3 个本周有变更的仓库：
   1. loanfe-h5 — 8 次提交 — /work/loanfe-h5
      最新：feat(order): add repayment entry
   2. kj-skills — 3 次提交 — /work/kj-skills
      最新：docs: refine weekly digest
   3. admin-web — 1 次提交 — /work/admin-web
      最新：fix: handle empty state
   
   请选择要生成周报的项目：输入编号（如 `1,3` 或 `1-3`）、`全部`，或项目名；回复“取消”则结束。

4. 等待用户选择：目录扫描模式下必须等待用户对候选项目作出选择；不能因为仓库有提交就自动生成全部项目的详细周报。用户选择不合法时，重新展示清单并说明可用格式。
5. 解析选择：支持逗号分隔编号、闭区间（1-3）、全部、精确项目名与“取消”。将选中的仓库作为多项目输入；如果只选择一个仓库，也保留用户选择的项目名。
6. 无活跃仓库时：明确告知扫描目录、统计周期及“本周未发现有非 merge 提交的 Git 仓库”；可让用户改选时间范围或目录。

3. 采集事实

对每个项目运行（传入指定周起始日时同时传入上周起始日）：

./scripts/collect.sh /path/to/repo

脚本默认过滤 merge commit，输出本周/上周的时间范围、提交、文件数、增删行与贡献者。收集失败时说明原因，不得补估数据。只有用户说「含 merge」或「全分支」时才修改采集命令，并在报告中注明口径。

4. 归类并写事实底稿

按以下优先级合并提交，而非逐条转抄：

1. 若为贡献者视图，按 author_name + author_email 分组；同名不同邮箱必须分开。
2. 提取 conventional commit 的 scope（如 feat(auth) → auth）。
3. 按关键词归为新功能、Bug 修复、文档、重构、测试、维护/基础设施或其他。
4. 合并同主题的小提交；优先呈现影响面大、涉及核心模块或新增行数较多的 3–5 项。

每一项写清“做了什么 + 为什么重要 + 涉及模块”。只根据 commit/message 和变更路径能确定的事实描述；不确定时使用保守措辞，如“完成了实现/调整”，而非“已上线/提升了转化”。

5. 按受众渲染

先使用 assets/templates/single-project.md 或 assets/templates/multi-project.md 生成工程事实底稿；再根据 references/audience-views.md 的选择规则输出受众版本。

• 工程视图（默认）：保留主题、统计、上周对比和文件/模块信息，适合研发复盘。
• 直属领导视图：先给 1–2 句结论，再列关键产出、风险/需支持和下周重点。没有用户提供的风险、支持或计划时标「待补充」。
• 团队视图：强调模块变化、协作关注项与可验证的后续工作；避免按个人绩效排序。
• 高管视图：控制在约 15 行内，包含状态（仅在有里程碑/风险证据时判断，否则“待确认”）、TL;DR、关键产出、风险/决策。省略代码统计。
• 客户视图：使用对外交付语言和简短邮件式结构；不展示内部统计/路径/作者，未确认的发布时间、里程碑、风险与下一步均标「待确认」。

多项目模式先输出项目概览，再按相同受众规则汇总；项目详情默认折叠。若输出多个版本，标题中明确受众，且每个版本的核心产出均能回溯到同一事实底稿。

6. 可选增强

• 按人统计：使用 contributors 统计添加表格；“主要贡献”来自该作者的提交主题，不能由行数推断绩效。
• 关联 PR：通过 gh CLI 获取 PR/Issue 时注明数据来源与查询时间；不可用时保留 Git 周报，不阻塞交付。
• 导出周报：写入前确认目标目录存在；不覆盖用户已有文件，除非用户明确允许。

边界情况

交付前检查

• Git 采集成功；统计数字未估算，且本周/上周口径一致。
• 目录扫描模式下，已展示本周活跃仓库清单并取得用户选择；只对选中的仓库生成详细周报。
• 提交已按主题合并，重点不超过 3–5 项；每项说明影响范围。
• 默认工程视图含本周、上周和趋势；多项目视图含项目概览与整体趋势；“只看本周”例外。
• 受众视图未泄露不适合该受众的内部信息，且未把 Git 无法证明的事项写为事实。
• 贡献者按姓名 + 邮箱区分；趋势百分比与原始统计一致。
• 单项目工程版不超过 100 行、多项目工程版不超过 200 行；高管摘要约 15 行内。

资源

• scripts/collect.sh：跨平台 Git 数据采集。
• scripts/scan-repos.sh：扫描目录中本周有提交的 Git 仓库。
• assets/templates/single-project.md：工程事实底稿模板。
• assets/templates/multi-project.md：多项目工程事实底稿模板。
• references/audience-views.md：领导、团队、高管、客户视图模板与边界。
• references/projects-config.md：多项目配置。