# v2 版本更新日志标准

使用本标准增量维护 `使用说明/更新日志/v2版本更新日志.md`。正式日志服务于普通软件用户，不是 Git 提交清单或开发流水账。

## 版本边界

1. 只记录名称严格匹配 `v2.<次版本>.<修订版本>` 的正式 Git 标签，不创建“未发布”章节。
2. 读取日志第一条版本标题作为已记录基线，只分析比它更新的正式标签。
3. 检查仓库是否为浅克隆，并确认基线标签和待写标签都能在本地解析。缺少历史、基线标签不存在或标签关系不明确时停止并询问用户。
4. 日志不存在时询问用户从哪个 v2 版本开始整理，不擅自生成全部 v2 历史。
5. 没有新标签时不改动文件。

## 确定性工具

从仓库根目录使用 `scripts/changelog_tool.py`，不要自行拼接多条 Git 或 PowerShell 写入命令。

只读收集基线、待写标签、提交和变更文件：

```powershell
python .agents/skills/yibiao-user-manual/scripts/changelog_tool.py inspect --json
```

`inspect` 只读取版本标题确定基线，不因既有标题缺少空行而中断。后续确有新版本时，`insert` 会在同一次写入中补齐必要空行，不增加独立修复流程。

完成专业分析后，使用一条命令直接原子写入：

```powershell
python .agents/skills/yibiao-user-manual/scripts/changelog_tool.py insert --apply --json `
  --version v2.19.1 `
  --new '新增用户可感知的功能。' `
  --optimize '优化已有流程的操作体验。' `
  --fix '修复特定场景下的问题。'
```

工具在同一进程中检查源文件并原子替换，只允许写入当前最早缺失的正式标签，固定栏目顺序和空行，拒绝重复版本、空条目、多行条目及不以中文句号结尾的句子。多个待写版本按从早到晚逐个处理，每次写入后重新运行 `inspect`。

## 分析方法

对每个待写版本按发布时间从早到晚分析，最终按版本从新到旧插入日志：

1. 查看相邻正式标签之间的提交标题、修改文件和整体差异。
2. 深入阅读与候选变化有关的页面、用户文案、业务服务和配置，不只依赖提交标题。
3. 判断普通用户是否能感知变化；合并同一能力的多次提交，避免按提交数量拆分条目。
4. 排除纯重构、测试、CI、依赖整理、代码格式、调试日志和仅供开发者使用的变化。
5. 如果版本只有安装包、更新流程等发布体验变化，可以记录真实的用户影响；没有可感知变化时不要杜撰业务功能。

提交记录和代码差异存在冲突时，以该正式标签中的实际产品行为为准。无法从证据确认的变化不写入日志。

## 固定格式

```markdown
# 易标投标工具箱版本更新日志

## v2.19.1

### 新增

- 新增用户可以直接感知的功能，并说明主要用途。

### 优化

- 优化已有流程的操作体验，并说明改善结果。

### 修复

- 修复特定场景下的问题，并说明原有影响。

### 调整

- 调整已有能力或服务范围，并说明用户需要注意的变化。
```

- 一级标题必须固定为“易标投标工具箱版本更新日志”。
- 版本标题必须使用 `## v2.x.x`，所有版本按语义版本严格倒序排列。
- 栏目只允许“新增”“优化”“修复”“调整”；新插入版本严格按此顺序排列，没有内容的栏目直接省略。
- 每个栏目至少包含一条 `- ` 列表，每条只写一个主题并以中文句号结尾。
- 一级标题、版本标题和栏目标题之后必须保留空行；版本与栏目之间也必须用空行分隔。
- 新版本统一插入一级标题之后，保留既有版本的内容、顺序和措辞。
- 更新既有日志时，以更新前第一条版本为校验基线；基线及更早的历史条目保留原文，基线之后新增的版本执行栏目顺序校验。

## 文风标准

- 使用简洁、客观、专业的中文，从用户能力、使用体验或问题影响出发。
- 保留界面中的正式产品名和功能名；同一术语在不同版本中保持一致。
- “新增”描述过去没有的用户能力；“优化”描述已有能力的改善；“修复”描述已解决的问题；“调整”描述支持范围、入口或行为变化。
- 一条变化涉及多个连续步骤时合并表达，避免把实现过程拆成多条。
- 不写提交号、提交类型前缀、文件路径、函数名、变量名、内部代号、测试过程或开发者自述。
- 不机械复制“新增某组件”“重构某服务”等提交标题，要改写为用户能理解的结果。
- 不使用夸张宣传、无法验证的效果数字或“全面提升”“大幅增强”等空泛判断；只有证据充分时才描述具体改善。

示例：

- 不写：`feat: add htmlChartRenderer and planner`。
- 应写：`新增 HTML 图表生成能力，可按需生成进度、组织架构和风险分析等图表。`
- 不写：`fix duplicate content in replaceSection()`。
- 应写：`修复方案扩写时替换位置识别失败，可能导致正文出现重复内容的问题。`
