| name | commit-update-writer |
| description | 基于用户指定的改动范围（默认当前工作区）分析上下游依赖并产出改动说明，按时间顺序增量写入 docs/CHANGELOG.md 最上方。用户要求“生成本次改动文档/更新记录/changelog”时触发。 |
Commit Update Writer
用于对“用户指定范围”的改动做完整理解，并将结果以项目既有文风写入 docs/CHANGELOG.md。
该 skill 的目标不是罗列 diff，而是解释改动目的、业务逻辑、实现结果、上下游影响与风险。
触发时机
- 用户要求“生成本次改动说明 / 更新日志 / 变更文档 / changelog”
- 用户要求“基于 git diff 写 markdown 到 docs/CHANGELOG.md”
- 用户要求“分析改动及其依赖、被依赖影响并沉淀文档”
范围判定（强制）
- 默认范围是
working tree（未提交改动），不自动混入 HEAD~1..HEAD。
- 仅当用户明确提到“上次提交 / HEAD~1 / 最近一次 commit / 已提交改动”时，才使用
HEAD~1..HEAD。
- 仅当用户明确要求“包含已提交 + 未提交”时，才使用混合范围：
HEAD~1..HEAD + working tree。
- 若用户说“本次改动/本次变动/当前改动”且工作区同时存在已提交与未提交差异，默认解释为
working tree；若语义不清，必须先向用户确认范围再写文档。
强制输入约定
base_commit 默认：HEAD~1（仅用于记录 Base Commit 与需要时的提交范围对比）compare_scope 必填：working_tree_only | last_commit_only | last_commit_plus_working_tree
强制执行规则
- 每次必须在文档中显式写出基线 commit id（
Base Commit）。
- 每次必须读取并遵循风格参考：
.trae/skills/commit-update-writer/reference/language-style.md
- 输出文件固定为：
docs/CHANGELOG.md（注意拼写）。
- 只能把新记录增量插入到文件最上方，禁止修改/删除已有历史记录内容。
- 若
docs/CHANGELOG.md 不存在，先创建，再写入首条记录。
- 每次必须显式写出“当前内容撰写时间”，格式固定为
YYYY-MM-DD HH:mm（24 小时制）。
- 每次输出区块末尾必须给出一条建议
git commit message，遵循 git-cz 规范（type(scope): subject），语义准确且长度适中（建议不超过 72 个字符）。
- 生成正文前，必须先在草稿里写明“本次采用的 compare scope”；若与用户指令不一致，必须停止并重新确认，禁止继续写入。
分析范围（强制）
不仅要读 diff 文件，还要覆盖以下上下文：
- 改动代码本身（变更 hunks）
- 改动部分直接依赖的上游（imports、被调用函数/类、配置来源）
- 依赖改动部分的下游（调用方、消费方、命令入口、graph 节点链路）
- 相关业务链路（CLI、channel、graph、service、database、prompt）
执行步骤
- 判定范围
- 先根据“范围判定（强制）”确定
compare_scope。
- 若存在歧义，先问用户，不得猜测。
- 锁定基线
- 解析并记录
HEAD~1 对应 commit 的完整/短 SHA（作为 Base Commit）。
- 收集变更
- 按
compare_scope 获取文件级和 hunk 级 diff。
- 标注新增、修改、删除、重命名。
- 构建上下游依赖图
- 对每个改动点定位：上游依赖、下游调用、运行入口。
- 识别是否存在“改动点未同步其依赖方”的断链风险。
- 还原业务逻辑
- 改动前行为是什么。
- 改动动机是什么（要解决什么问题）。
- 改动后行为和结果是什么。
- 评估影响与风险
- 功能正确性、兼容性、稳定性、性能、可维护性。
- 明确“已验证项 / 未验证项 / 建议补充验证”。
- 按风格生成文档片段并写入
- 生成一个“本次改动记录”区块。
- 插入到
docs/CHANGELOG.md 最上方，保持整体按时间从新到旧排列。
- 生成建议 commit message
- 根据本次改动主线，产出 1 条 git-cz 风格 message：
type(scope): subject。
subject 需简洁，不写空泛词，不堆叠多主题。
顶部增量写入模板（必须包含）
## CHANGELOG - <YYYY-MM-DD HH:mm> - <一句话主题>
### 撰写时间
- <YYYY-MM-DD HH:mm>
### Base Commit
- <commit_id>
### Compare Scope
- <working_tree_only | last_commit_only | last_commit_plus_working_tree>
### 背景与改动目标
- <为什么改>
### 改动概览
- <改了哪些模块/文件，核心动作是什么>
### 关键链路解析（含上下游）
- 上游依赖：<依赖了什么，是否变更>
- 当前改动：<核心实现与逻辑>
- 下游影响：<谁依赖它，是否需要同步改>
### 改动结果与业务影响
- <结果、收益、边界、代价>
### 风险与待办
- <潜在风险>
- <建议补充验证 / 后续动作>
### 建议 Commit Message（git-cz）
- `<type>(<scope>): <subject>`
质量标准
- 文档必须能回答：
- 改动是否合理
- 是否可能引入新问题
- 是否可能导致上下游依赖链路异常
- 不得只贴 diff，不得只列文件名。
- 结论必须有代码依据，不写无依据猜测。
禁止事项
- 禁止覆盖、改写或重排单条历史记录的正文内容。
- 禁止写入
docs/UPDATE.md（文件名错误）或其他非目标文件（除非用户明确改口）。
- 禁止省略
Base Commit（其值应来自 HEAD~1）。
- 禁止省略
Compare Scope。
- 禁止省略“撰写时间”（
YYYY-MM-DD HH:mm）。
- 禁止输出不符合 git-cz 的 commit message，或过长、语义不清的 subject。
- 禁止忽略依赖与被依赖影响分析。
- 禁止在用户未授权时自动把“已提交改动”与“未提交改动”混写为同一条记录。
