Change Report

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

## 前置检查

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 取第一个存在的主干：

```bash
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，生成报告草稿

```bash
git diff --stat              # 改动概览
git diff -- <主要文件>        # 细读关键改动（判断模块作用）
git log <主干>..HEAD -p --stat  # 结合 commit message 推断"为什么"
```

生成报告草稿（见"报告格式"）。"为什么"三源合成：
- diff + commit message 推断
- 会话上下文提取
- 推断不出 → 标"原因待确认"，不得编造
- 验证结果从会话上下文提取本次跑过的测试/检查；无记录 → 标"未验证"，不编造。

### ④ 展示草稿，用户确认
展示草稿，重点请用户确认/补充"大点原因"。确认前不落稿。

### ⑤ 落变更记录
确认后，把本次改动追加到 `报告文档/代码/<项目>/变更记录.md`：

```markdown
## 2026-08-12
- [改动主题] <具体改动地方：文件/位置 + 动作 + 作用>
```

只追加，绝不覆盖或改动历史条目。同主题已记录 → 跳过并提示"该改动已记录"，或提示合并到已有条目。

### ⑥ 输出报告 + 委托 docx skill 渲染
- 写 md 源 → `报告文档/代码/<项目>/md形式/<范围起点>.md`
- 委托 docx skill 把 md 转 Word → `报告文档/代码/<项目>/word形式/<范围起点>.docx`
- 渲染失败 → md 源保留在 md形式，告知用户手动转换或重试
- md 源是报告源，保留（不删除）；无其他中间草稿需清理

### ⑦ 报告
输出：.docx 路径 + 报告摘要（一句话目标 + 大点列表）。

## 报告格式（面向上级 · 正式 + 精简 · 强调具体改动 + 改动文件）

```markdown
# 变更报告 · 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形式，告知用户手动转换或重试。
- 会话上下文只提取与本次改动相关的"为什么"，不泄漏无关内容。