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 与输出路径写入本地状态索引，但不得将索引或报告内容自动提交、推送。

前置检查

1. 确认是 git 仓库：git rev-parse --is-inside-work-tree，非 git 仓库 → 报错退出。
2. 确认有改动：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  # 结合 commit message 推断"为什么"

生成报告草稿（见"报告格式"）。"为什么"三源合成：

• 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/内部地址）

安全铁律

1. 只读——只用 git status/log/diff，绝不 commit/push/reset。
2. 无代码——报告含文件/位置级描述，绝不粘贴代码/行号/命令。
3. 无敏感——绝不把凭据/token/内部地址写进报告。
4. 不编造原因——"为什么"推断不出标"待确认"，用户确认前不落稿。
5. 输出路径——默认 报告文档/代码/<项目>/（md形式/word形式/变更记录.md），用户显式指定路径时以用户为准；目标文件已存在须确认覆盖。

边界与错误处理

• 非 git 仓库 → 报错退出。
• 无改动可报 → 提示退出。
• 无可用主干分支 → 回退最近 N 个 commit。
• change-log.md 不存在 → 跳过参照。
• docx 渲染失败 → md 源保留在 md形式，告知用户手动转换或重试。
• 会话上下文只提取与本次改动相关的"为什么"，不泄漏无关内容。