gouzhuang/update-changelog

update-changelog 技能指南

技能概述

本技能用于根据Git已暂存的变更或当前会话内容自动更新CHANGELOG.md文件，确保变更日志与项目风格保持一致。

支持两种模式：

1. Git暂存变更模式 - 基于已暂存的Git变更生成日志（推荐用于代码提交）
2. 会话内容模式 - 基于当前会话内容生成日志（适用于非代码变更或手动说明）

核心功能

1. 自动查找CHANGELOG.md

   • 若用户指定文件路径，使用指定路径
   • 否则在项目根目录查找CHANGELOG.md文件
   • 不区分文件名大小写（支持CHANGELOG.md、changelog.md、Changelog.md等）
   • 如果不存在则创建新文件
   • 注意文件路径是否属于Git子模块(submodule)，如果是则所有git命令都需要在子模块目录下执行

2. 智能模式选择

   • 自动检查是否有已暂存的Git变更
   • 无暂存变更时默认进入会话内容模式
   • 有暂存变更时询问用户选择模式

模式选择与执行

步骤1：检查Git状态和模式选择

git status

检查是否有已暂存的变更：

• 无暂存变更：默认进入会话内容模式
• 有暂存变更：若用户明确指定模式，则进入该模式，否则询问用户希望采用的模式：

  检测到已暂存的Git变更。请选择日志生成模式：
  1. Git暂存变更模式 - 基于已暂存的Git变更生成日志
  2. 会话内容模式 - 基于当前会话内容生成日志
  

步骤2：查找CHANGELOG.md

在项目根目录查找CHANGELOG文件：

• CHANGELOG.md
• changelog.md
• Changelog.md

如果不存在，创建新文件。

步骤3：读取当前CHANGELOG.md

分析现有CHANGELOG的风格和格式：

• 日期格式
• 标题结构
• 章节组织
• 代码块风格

步骤4：分析Git变更或会话内容

分析Git变更（Git暂存变更模式）

git diff --cached
git diff --cached --stat

提取以下信息：

• 修改的文件列表
• 新增的文件列表
• 删除的文件列表
• 变更类型（新增/修复/优化/重构）
• 变更摘要

分析会话内容（会话内容模式）

从当前会话中提取以下信息：

• 用户请求的内容
• AI执行的操作
• 修改的文件（如果有）
• 新增的功能或特性
• 修复的问题
• 优化的内容
• 变更类型（新增/修复/优化/重构）
• 变更摘要

步骤5：确定变更类型

根据Git变更内容选择合适的分类：

• 如果是新增功能 → 新增
• 如果是修复bug → 修复
• 如果是性能优化/代码改进 → 优化
• 如果是代码重构/架构调整 → 重构

步骤6：生成日志条目

按照格式规范生成日志条目，Git暂存变更模式的特殊要求：

必需部分：

1. 标题行：## [日期] 分类：标题
2. 描述部分：选择合适的标题（问题描述/变更内容/功能概述）
3. 影响范围：列出修改的文件路径，若文件数量较多则可只列出主要文件或目录，相同路径前缀的文件可以合并为一个条目

可选部分（根据需要添加）：

1. 根本原因（修复类）
2. 技术实现（需要详细说明时）
3. 改进成果（有显著改进时）
4. 对比分析（有前后对比时）

注意：

• 如果会话中未提及具体文件路径，影响范围部分可以省略
• 如果会话内容不够详细，主动向用户询问补充信息
• 只记录明确的变更内容，不要添加推测性信息

示例

## [2026-01-26] 修复：填写记录排除草稿数据

### 问题描述

"我的填写记录"接口返回的问卷回答列表中包含了草稿状态的记录，导致显示不准确。

### 技术实现

修改 `src/dataController.js`：
- 在 `getMyResponses` 方法中添加 `is_draft = 0` 过滤条件
- 确保只返回正式提交的问卷回答
- 保持原有分页和排序逻辑

### 影响范围

- 新增：`tests/dataController.test.js`
- 修改：`src/dataController.js`
- 删除：`src/obosolete.js`

### 改进成果

- ✅ 修复填写记录显示不准确问题
- ✅ 草稿数据不再出现在正式记录中
- ✅ 用户体验提升

---

## [2026-01-26] 优化：用户界面响应式设计改进

### 变更内容

优化表单界面的移动端显示效果，改善移动设备上的用户体验。

### 详细说明

根据用户反馈，在移动设备上使用时，表单字段布局和按钮大小不够友好。本次优化：
- 调整表单字段在小屏幕上的间距和内边距
- 优化按钮点击区域大小
- 改进移动端滚动体验

### 改进成果

- ✅ 移动端用户体验显著提升
- ✅ 表单填写更便捷
- ✅ 跨设备一致性改善

---

步骤7：插入新日志

将新日志插入到CHANGELOG.md文件的第一个条目之前：

## [新日期] 分类：新标题

[新日志内容]

---

## [旧日期] 分类：旧标题

[旧日志内容]

步骤8：验证日志

检查生成的日志：

• 日期是否正确（使用当前日期）
• 格式是否一致
• 长度是否适中（不超过30行，不含代码块）
• 文件路径是否准确（Git暂存变更模式必需）
• 描述是否准确反映会话内容（会话内容模式）

步骤9：保存CHANGELOG.md

使用Write工具保存更新后的CHANGELOG.md文件。

变更类型分类

新增 (new)

• 新增功能
• 新增API接口
• 新增字段类型
• 新增数据库表/字段

示例标题：

• 新增：填写说明字段类型和评分计算修复
• 新增：患者检索与自动填充功能

修复 (fix)

• 修复bug
• 修复安全问题
• 修复逻辑错误

示例标题：

• 修复：填写记录排除草稿数据
• 修复：编辑问卷回答返回后问卷名称显示为undefined

优化 (optimize)

• 性能优化
• 代码重构
• 功能改进
• UI/UX优化

示例标题：

• 优化：数据导出功能改进
• 优化：填写记录表格展示改进
• 优化：草稿状态管理优化

重构 (refactor)

• 代码重构
• 架构调整
• 数据库结构变更

示例标题：

• 重构：问卷回答数据模型 - 患者标识字段分离

CHANGELOG.md 格式规范

标准条目格式

## [YYYY-MM-DD] 分类：标题

### 描述部分

[根据变更类型选择以下标题之一]
- 问题描述（修复类）
- 变更内容（优化/新增类）
- 功能概述（新增类）

### 详细说明

[详细描述变更内容]

### 技术实现

[如果需要，添加技术实现细节]

### 影响范围

- 文件：`路径1`
- 文件：`路径2`

### 改进成果

- ✅ 改进点1
- ✅ 改进点2

---

格式要求

1. 日期格式：YYYY-MM-DD，使用当前日期
2. 分类：新增/修复/优化/重构
3. 标题：简明扼要描述变更内容
4. 列表：
   • 使用-符号开始列表项
   • 子列表缩进2个空格
5. 代码块：
   • 使用```language语法
   • 主要语言：javascript、sql、bash
6. 分隔符：使用---分隔不同条目
7. 长度控制：每个条目不超过30行（不含代码块）

代码风格指南

日志内容要求

1. 简洁明了：用最少的文字表达核心信息
2. 结构化：使用标题和列表组织内容
3. 具体准确：文件路径和行号必须准确
4. 中文优先：使用中文描述，技术术语保留英文

代码块格式

// 使用语言标识
const example = 'value';

SELECT * FROM forms WHERE status = 'published';

npm run dev

列表格式

• 主要条目使用 - 符号
• 子条目缩进2个空格
• 改进成果使用 ✅ 符号

- 主要变更
  - 子变更1
  - 子变更2
- ✅ 改进点1
- ✅ 改进点2

常见场景处理

场景1：多个文件变更

当变更涉及多个文件时：

### 影响范围

**后端代码**
- 文件：`src/models/Form.js`
- 文件：`src/controllers/formController.js`

**前端代码**
- 文件：`src/public/js/app.js`
- 文件：`src/public/css/style.css`

场景2：小改动（<5行）

对于小改动，简化日志：

## [2026-01-26] 修复：日志目录路径配置优化

### 变更内容

Logger 类新增环境变量 `logging_path` 配置支持，允许自定义日志目录路径。

### 影响范围

- 文件：`src/utils/logger.js`

---

场景3：代码重构

对于代码重构，添加前后对比：

### 修改前后对比

#### 修改前
```javascript
// 旧代码

修改后

// 新代码

### 场景4：CHANGELOG不存在

如果CHANGELOG.md不存在，创建新文件：

```markdown
# 变更日志

## [2026-01-26] 新增：项目初始化

### 功能概述

初始化FormBase问卷云项目。

---

错误处理

情况1：Git暂存变更模式 - 无已暂存变更

如果用户选择Git暂存变更模式但暂存区为空，提示用户：

错误：暂存区为空，请先使用 git add 暂存变更，或选择会话内容模式。

情况2：会话内容模式 - 无可用内容

如果会话内容不足以生成有意义的日志，提示用户：

提示：当前会话内容不足以生成变更日志，请提供更多详细信息或选择Git暂存变更模式。

情况3：CHANGELOG格式不一致

如果现有CHANGELOG格式与标准不一致：

1. 遵循现有格式（向后兼容）
2. 仅在首次生成时创建新格式

最佳实践

1. 模式选择：
   • 代码提交前使用Git暂存变更模式，确保日志与代码变更同步
   • 文档更新或配置调整使用会话内容模式，灵活记录非代码变更
2. 每次提交前更新CHANGELOG：确保日志与提交同步
3. 保持日志简洁：避免过于冗长的描述
4. 使用明确的变更分类：正确选择新增/修复/优化/重构
5. 准确的文件路径：Git暂存变更模式中列出所有修改的文件
6. 日期正确：使用当前日期（YYYY-MM-DD格式）
7. 会话内容模式中补充信息：如果会话内容不够详细，主动向用户询问补充信息

验证清单

通用验证清单

• [ ] 日期使用当前日期（YYYY-MM-DD）
• [ ] 变更分类正确（新增/修复/优化/重构）
• [ ] 标题简明扼要
• [ ] 格式符合项目风格
• [ ] 使用中文描述
• [ ] 代码块有语言标识（如果有代码）
• [ ] 列表格式正确
• [ ] 日志长度适中（不超过30行，不含代码块）
• [ ] 分隔符完整（前后都有---）
• [ ] 改进成果使用✅符号（如果有）

Git暂存变更模式附加验证清单

• [ ] 文件路径准确
• [ ] 所有暂存的文件都被记录

会话内容模式附加验证清单

• [ ] 描述准确反映会话内容
• [ ] 文件路径准确（如果有提及）

注意事项

通用注意事项

1. 保持向后兼容：确保日志格式与现有CHANGELOG一致
2. 避免重复：检查是否已存在相同的变更日志
3. 环境变量引用：如需更新package.json中的版本号，请先询问用户确认

Git暂存变更模式注意事项

1. 只处理已暂存的变更：不要处理工作区未暂存的变更
2. 准确记录文件路径：确保所有暂存的文件都被记录

会话内容模式注意事项

1. 准确理解会话意图：仔细分析用户请求和AI响应
2. 补充缺失信息：如果会话内容不够详细，主动向用户询问
3. 避免过度解读：只记录明确的变更内容，不要添加推测性信息