| name | change-report |
| description | 按指定记录、commit 或范围分析 Git 改动，生成面向上级的精简 Word 变更报告（具体改动地方 + 改动文件说明），并落一条变更记录。全程只读，无代码、无敏感信息。输出到 `报告文档/代码/<项目>/`（md形式 + word形式 + 变更记录.md），委托 docx skill 渲染。触发词：提交报告、改动报告、本周工作总结、给上级的报告、change report、这次改了什么。 |
Change Report
按本次 git 改动生成面向上级的正式变更报告：具体改了什么、改在哪些文件、为什么改。结构与 worklog 平行：md/word 分目录 + 变更记录流水 + 按改动范围起点命名。全程只读（git status/log/diff），无代码、无敏感信息。
存储布局
按项目分目录：<项目> = 报告文档/代码/_projects.json 里仓库路径的映射名；未映射的仓库用 git 根目录名。仓库里 scripts/project_name.py 是同一条规则的可执行副本：python scripts/project_name.py <git-root> [_projects.json]。
报告文档/代码/<项目>/
├── 变更记录.md # 变更流水账，只追加从不覆盖
├── md形式/<范围起点>.md # md 报告源，可重复生成
└── word形式/<范围起点>.docx # Word 报告（docx skill 渲染）
<范围起点> = 本次改动范围最旧 commit 的日期（git show -s --format=%cs <base>）；仅未提交改动时用今天。目标文件已存在 → 先确认覆盖。
V3：可组合、可恢复的执行模型（优先于下文任何冲突规则）
change-report 可在 commit 前、push 前、push 后或补记后调用；不要求固定顺序，也绝不为了凑齐流程而编造状态。
报告状态如实标记：
draft：存在未提交改动local-commit：已有本地 commit，尚未确认已推送pushed：本地远端跟踪信息或状态索引证明已推送unknown：无法可靠确认远端状态
重复调用同一范围时，默认展示或更新 md 草稿，再重新渲染。md 源保留在 md形式/。成功生成后可将 reported 与输出路径写入本地状态索引，但不得将索引或报告内容自动提交、推送。
前置检查
- 确认是 git 仓库：
git rev-parse --is-inside-work-tree，非 git 仓库 → 报错退出。
- 确认有改动：git status --short 有内容，或主干分支存在 commit → 否则提示"没有可报告的改动"退出。
工作流
① 圈定改动范围（先问用户）
展示候选范围（未提交改动 / 未推送 commit / 已推送未合并 commit），请用户选择或显式指定：
--record <ID> / --range <base>..<head> / --commit <SHA>- 不得以"最近 N 个 commit"作为无提示默认范围
- 无可用主干分支时回退最近 N 个 commit（默认 5）
比较基准按 origin/main → main → master 取第一个存在的主干：
git status --short
git log origin/main..HEAD --oneline 2>/dev/null || git log main..HEAD --oneline 2>/dev/null || git log master..HEAD --oneline 2>/dev/null || git log HEAD --oneline -5
② 读 change-log.md 参照
读 docs/change-log.md（若存在）——提取本次改动相关条目作背景/细节参照。不存在则跳过。
③ 分析 diff，生成报告草稿
git diff --stat
git diff -- <主要文件>
git log <主干>..HEAD -p --stat
生成报告草稿（见"报告格式"）。"为什么"三源合成：
- diff + commit message 推断
- 会话上下文提取
- 推断不出 → 标"原因待确认"，不得编造
- 验证结果从会话上下文提取本次跑过的测试/检查；无记录 → 标"未验证"，不编造。
④ 展示草稿，用户确认
展示草稿，重点请用户确认/补充"大点原因"。确认前不落稿。
⑤ 落变更记录
确认后，把本次改动追加到 报告文档/代码/<项目>/变更记录.md：
## 2026-08-12
- [改动主题] <具体改动地方：文件/位置 + 动作 + 作用>
只追加，绝不覆盖或改动历史条目。同主题已记录 → 跳过并提示"该改动已记录"，或提示合并到已有条目。
⑥ 输出报告 + 委托 docx skill 渲染
- 写 md 源 →
报告文档/代码/<项目>/md形式/<范围起点>.md
- 委托 docx skill 把 md 转 Word →
报告文档/代码/<项目>/word形式/<范围起点>.docx
- 渲染失败 → md 源保留在 md形式，告知用户手动转换或重试
- md 源是报告源，保留（不删除）；无其他中间草稿需清理
⑦ 报告
输出：.docx 路径 + 报告摘要（一句话目标 + 大点列表）。
报告格式（面向上级 · 正式 + 精简 · 强调具体改动 + 改动文件）
# 变更报告 · YYYY-MM-DD
## 一句话目标
本次完成了<什么>，达成了<什么>。
## 背景
<1-2 句正式书面语：本次迭代在做什么、为什么值得做。>
## 本次改动
**<大点 1：主题>**
原因：<该主题现状的正式问题>
- <小点 a>：<文件/位置 + 具体改动 + 作用>
- <小点 b>：<文件/位置 + 具体改动 + 作用>
**<大点 2：主题>**
原因：<...>
- <小点 a>：<...>
## 改动文件
<按模块分组列出本次改动涉及的文件路径（git diff --name-only <主干>..HEAD）>
## 验证结果
- <验证方式 + 结果，1-2 条>
结构规则：
- 大点：按功能主题聚类（非按目录），1-3 个；原因放大点层，与改动一一对应；超 3 个 → 提示合并或裁剪
- 小点：按依赖链排序（设计/数据库 → 后端 → 前端）；每点 = 文件/位置 + 具体改动 + 作用
- 背景 = 业务总述，只出现一次，不重复大点原因
- 改动文件：
git diff --name-only <主干>..HEAD 取清单，按模块分组（如 Java Agent / Rust 后端 / Flutter 前端 / 配置与工程化），直接列文件路径；只列路径，无行号、无代码、无命令
风格铁律：
- 措辞正式书面，不用"我改/为什么改"对话口吻
- 短句、直接、不堆套话；每行 ≤ 25 字；正文尽量一页，改动文件清单可另起/紧凑排列
- 只有文件/位置 + 具体改动 + 作用，绝不出现代码片段、文件行号、命令
- 改动文件段只列文件路径（无行号/代码/命令）；每行一个路径，小字号紧凑排列
- 绝不写敏感信息（凭据/token/内部地址）
安全铁律
- 只读——只用 git status/log/diff，绝不 commit/push/reset。
- 无代码——报告含文件/位置级描述，绝不粘贴代码/行号/命令。
- 无敏感——绝不把凭据/token/内部地址写进报告。
- 不编造原因——"为什么"推断不出标"待确认"，用户确认前不落稿。
- 输出路径——默认
报告文档/代码/<项目>/（md形式/word形式/变更记录.md），用户显式指定路径时以用户为准；目标文件已存在须确认覆盖。
边界与错误处理
- 非 git 仓库 → 报错退出。
- 无改动可报 → 提示退出。
- 无可用主干分支 → 回退最近 N 个 commit。
- change-log.md 不存在 → 跳过参照。
- docx 渲染失败 → md 源保留在 md形式，告知用户手动转换或重试。
- 会话上下文只提取与本次改动相关的"为什么"，不泄漏无关内容。
