CHANGELOG

> 该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。

CHANGELOG.md

项目版本变更记录

文档版本： v1.0文档状态： 持续维护最后更新： 2026-07-27文档性质： 项目历史变更事实源适用对象： 项目负责人、AI开发助手、测试人员、部署人员、后续维护者

0. 本文件是什么

本文件用于记录：

项目从过去到现在，到底发生了什么变化。

它回答：

哪个版本增加了什么

哪个版本修了什么

哪个版本改了什么

哪个版本删除了什么

哪个版本改了数据库

哪个版本改了API

哪个版本改了权限

哪个版本修了安全问题

哪个版本改变了部署方式

哪个版本引入了新依赖

哪个版本可能造成兼容问题

1. 本文件不负责什么

当前项目状态

查看：

PROJECT_STATUS.md

项目架构

查看：

ARCHITECTURE.md

配置入口

查看：

CONFIGURATION.md

当前Bug

查看：

BUG_TRACKER.md

部署方式

查看：

DEPLOYMENT.md

2. CHANGELOG核心原则

本文件记录的是：

已经实际发生的变化。

不是：

未来计划。

不是：

待办事项。

不是：

建议。

不是：

AI认为以后应该做什么。

例如：

错误：

未来应该重构登录系统。

正确：

Changed- 将登录请求统一迁移到 Auth Service。

3. 禁止根据聊天记录猜历史

如果某个历史变更无法确认：

不要伪造版本。

可以记录：

【历史变更，具体版本待确认】

只有能够从：

Git代码文件时间历史文档Bug记录正式开发记录

确认的内容：

才写成确定事实。

4. 推荐版本号规则

正式版本推荐使用：

MAJOR.MINOR.PATCH

例如：

1.0.01.1.01.1.12.0.0

含义：

MAJOR

重大版本。

例如：

1.0.0 → 2.0.0

通常代表：

大规模架构变化

核心业务变化

重大不兼容

整体产品阶段变化

MINOR

功能版本。

例如：

1.1.0 → 1.2.0

通常代表：

新增功能

新增模块

新页面

新API

新管理功能

且总体保持兼容。

PATCH

修复版本。

例如：

1.2.0 → 1.2.1

通常代表：

Bug修复

小范围安全修复

UI修复

兼容修复

小优化

5. 开发阶段版本

如果尚未正式发布：

可以使用：

0.x.x

例如：

0.1.00.2.00.4.3

当前项目如仍处于开发阶段：

不必强行标记：

1.0.0

6. 预发布版本

如需要：

可以使用：

1.0.0-alpha.11.0.0-beta.11.0.0-rc.1

含义：

alpha早期测试beta较完整测试版本rcRelease Candidate，上线候选

7. 当前版本

当前真实版本：

【待确认】

如果项目目前还没有版本号体系：

建议从：

0.1.0

开始。

但必须由项目负责人确认后启用。

8. 版本状态

可使用：

DEVELOPMENTTESTINGRCRELEASEDDEPRECATEDROLLBACK

9. 每个版本统一结构

每个版本使用：

[版本号] - YYYY-MM-DD

例如：

[0.4.2] - 2026-07-27

然后按类别记录。

10. 变更分类

统一使用：

AddedChangedFixedSecurityRemovedDeprecatedPerformanceDatabaseAPIUIConfigDependenciesBuildDeploymentDocumentationKnown Issues

不需要每个版本全部出现。

没有内容的分类可以省略。

11. Added

记录：

新增加的功能。

例如：

Added- 新增管理员登录页面。- 新增用户个人中心。- 新增AI实验器件展示组件。- 新增错误页。- 新增健康检查接口。

12. Changed

记录：

已有功能发生变化。

例如：

Changed- 将字体配置从页面级CSS迁移到统一字体配置。- 将前端API请求统一通过API Client发送。- 调整登录后的默认跳转逻辑。

13. Fixed

记录：

修复Bug。

最好关联：

BUG-XXXX

例如：

Fixed- 修复刷新页面后登录状态丢失的问题。关联：BUG-0012- 修复首页字体样式继承失败的问题。关联：BUG-0018

14. Security

记录：

安全相关变化。

例如：

Security- 增加管理员接口后端权限校验。- 增加登录接口频率限制。- 移除前端暴露的第三方API Secret。

如果有关联Bug：

关联：BUG-0023

15. Removed

记录正式删除内容。

例如：

Removed- 删除已废弃的旧登录Demo。- 删除未再使用的旧字体加载脚本。

删除前必须已经确认：

不会破坏当前功能。

16. Deprecated

记录：

仍存在，

但未来准备废弃。

例如：

Deprecated- 旧版 /api/user/login 接口进入废弃阶段，未来统一使用 /api/auth/login。

17. Performance

记录性能变化。

例如：

Performance- 首页图片改为懒加载。- 减少重复API请求。- 优化字体重复加载。

最好写：

优化对象。

不要只写：

优化性能。

18. Database

任何数据库变化必须单独记录。

例如：

Database- 新增 users.last_login_at 字段。- 为 users.email 增加唯一索引。- 新增管理员审计日志表。

必须说明：

是否需要Migration：是否兼容旧数据：是否需要备份：

19. API

记录接口变化。

例如：

API- 新增 POST /api/auth/login- 修改 GET /api/users/me 返回结构- 废弃 /api/user/info

如果是不兼容变化：

必须明确写：

BREAKING CHANGE

20. UI

记录明显用户可见的视觉/交互变化。

例如：

UI- 调整首页实验室入口动画。- 统一按钮圆角与Hover状态。- 修复移动端导航遮挡问题。

21. Config

记录配置体系变化。

例如：

Config- API Base URL改为环境变量管理。- 新增 FONT_PRIMARY 配置。- 新增AI请求超时配置。

如果只是：

配置值从20改为30，

一般不用记录。

除非影响重要业务行为。

22. Dependencies

记录：

新增依赖。

删除依赖。

升级依赖。

降级依赖。

例如：

Dependencies- 新增 xxx，用于 xxx。- 将 xxx 从 1.x 升级至 2.x。- 删除未使用依赖 xxx。

核心依赖升级：

必须说明兼容风险。

23. Build

记录：

构建体系变化。

例如：

Build- 新增Production Build脚本。- 修复正式构建时字体路径错误。- 调整静态资源输出目录。

24. Deployment

记录：

部署方式变化。

例如：

Deployment- 新增Nginx反向代理配置。- API正式环境改为同域 /api 访问。- 新增HTTPS配置。

25. Documentation

记录重要文档变化。

例如：

Documentation- 新增 AI_START_HERE.md- 新增六大AI永久规则- 新增 PROJECT_STATUS.md- 新增 ARCHITECTURE.md- 新增 CONFIGURATION.md- 新增 BUG_TRACKER.md

普通文字修正：

不用每次进入CHANGELOG。

26. Known Issues

发布版本时：

如存在已知但暂不阻断的问题：

可以记录：

Known Issues- 移动端某动画存在轻微掉帧。关联：BUG-0081

P0不得出现在：

正常Released版本Known Issues中。

P1原则上也不应带入正式上线。

27. Breaking Change

任何可能导致旧功能、旧API、旧数据、旧配置无法继续使用的变化：

必须标记：

BREAKING CHANGE

例如：

BREAKING CHANGE- 用户认证从Session迁移至JWT，旧Session将不再有效。

28. 数据库破坏性变化

例如：

删除字段更改字段类型删除表改变主键改变唯一约束

必须：

BREAKING CHANGE

或明确高风险。

29. API破坏性变化

例如：

原：

GET /api/user

改为：

GET /api/users/me

且旧接口删除。

必须明确：

BREAKING CHANGE

30. 配置破坏性变化

例如：

原：

API_URL

改成：

API_BASE_URL

旧变量失效。

应记录：

Migration：API_URL → API_BASE_URL

31. 文件结构重大变化

如果目录变化导致：

旧脚本

部署

引用

文档

可能失效：

也应记录。

32. 每个版本必须记录日期

格式统一：

YYYY-MM-DD

例如：

2026-07-27

33. 日期以实际发生为准

不要根据：

AI当前聊天日期

去猜旧版本发布日期。

历史日期不确定：

写：

日期待确认

34. Unreleased区域

文件顶部建议保留：

[Unreleased]

所有：

已经完成

但还没正式形成版本

的改动先进入这里。

发布时：

把内容移动到正式版本。

35. Unreleased示例

[Unreleased]### Added- 新增管理员审计日志。### Fixed- 修复移动端首页按钮遮挡问题。关联：BUG-0027

36. 发布版本时

例如准备：

0.5.0

将：

Unreleased

内容整理成：

[0.5.0] - 2026-08-01

然后创建新的空：

[Unreleased]

37. 不允许AI每改一个字符就增加版本

例如：

改错别字：

不必：

0.4.1 → 0.4.2

版本号应代表：

有意义的发布节点。

38. 开发过程中的小修改

可以先进入：

Unreleased

等形成一个稳定节点：

再发布版本。

39. PATCH版本适合

例如：

Bug修复兼容修复小安全修复UI小修复

40. MINOR版本适合

例如：

增加个人中心增加管理员系统增加新工具增加新展示模块

41. MAJOR版本适合

例如：

重构整个认证体系改变核心产品结构全面更换技术架构产生大量不兼容

42. 版本号不能由AI随便决定

AI可以建议。

最终正式版本号：

应根据项目发布策略确定。

43. CHANGELOG记录的是用户和维护者关心的变化

不要记录大量无意义内容：

错误：

修改了第32行变量。

更好：

修复首页实验器件点击跳转错误。

44. 技术变化如果有意义要记录

例如：

将API地址集中到统一配置层。

这对维护者非常重要。

应该记录。

45. 不需要记录每个文件保存动作

CHANGELOG不是：

编辑器操作日志。

46. Bug修复与CHANGELOG

重要Bug：

BUG_TRACKER.md

记录完整病历。

CHANGELOG只写：

Fixed- 修复xxx。关联：BUG-XXXX

不要把整个Bug报告复制过来。

47. Bug复发

如果：

BUG-0010

以前修过。

后来再次修复。

新版本CHANGELOG仍可以写：

Fixed- 再次修复xxx复发问题。关联：BUG-0010

Bug Tracker负责完整历史。

48. Security变更

安全问题尽量描述：

修了什么类型的风险。

但不要暴露：

可直接利用漏洞的敏感细节。

尤其在公开仓库。

49. Secret轮换

可以记录：

Security- 完成某第三方服务密钥轮换。

但：

绝不记录密钥内容。

50. 数据库Migration

任何需要部署时执行的迁移：

必须在CHANGELOG明确写。

例如：

Database- 新增管理员审计日志表。Migration Required: Yes

51. 部署注意事项

如果新版本上线需要特别操作：

添加：

Upgrade Notes

例如：

Upgrade Notes- 部署前先执行数据库Migration。- 新增环境变量 ADMIN_SESSION_SECRET。- 部署后需重启Backend。

52. Upgrade Notes非常重要

因为未来AI可能问：

为什么代码更新完服务起不来？

然后发现：

新版本多了3个环境变量。

😂

所以重要版本必须记录升级条件。

53. 回滚信息

如果某版本存在特殊回滚注意事项：

记录：

Rollback Notes

例如：

数据库Migration不可直接回滚，回滚前请恢复备份。

54. 回滚版本

如果某个版本上线后撤回：

记录：

Status: ROLLBACK

以及：

回滚原因：回滚至：是否影响数据：

55. 热修复

紧急生产修复可使用：

Hotfix

标签。

例如：

[0.6.3] - 2026-08-05Hotfix### Fixed- 修复生产环境登录接口异常。

56. 生产事故修复

如果由事故触发：

可以关联：

INCIDENT-XXXX

例如：

关联：BUG-0048INCIDENT-0002

57. CHANGELOG与Git的区别

Git记录：

每次代码提交

CHANGELOG记录：

对项目有意义的版本变化

二者不是同一个东西。

58. CHANGELOG与Commit Message关系

理想情况下：

多个Commit

最终整理成：

一个版本CHANGELOG。

59. CHANGELOG不能代替Git

CHANGELOG不是代码备份。

60. Git不能代替CHANGELOG

因为：

几百条Commit

很难让项目负责人快速知道：

这个版本到底变了什么。

61. AI每次正式任务结束

如果任务造成：

明显产品变化

核心Bug修复

安全变化

架构变化

配置变化

依赖变化

数据库变化

部署变化

则应判断：

是否更新：

CHANGELOG.md

62. 以下情况必须更新CHANGELOG

新增正式功能删除正式功能修复重要Bug修复安全漏洞改变API改变数据库改变认证改变权限增加重要配置更换重要依赖修改Build修改部署架构正式发布版本

63. 以下情况通常不用更新

改注释改格式改单个错别字没有行为变化的微小代码整理

64. 大规模重构

即使用户功能不变：

如果维护方式发生明显变化：

可以记录：

Changed- 重构认证模块内部结构，外部API保持兼容。

65. 架构变更后

如果关系发生变化：

同时更新：

ARCHITECTURE.md

CHANGELOG写：

发生了什么。

ARCHITECTURE写：

现在是什么。

66. 配置变更后

如果配置入口变化：

同时更新：

CONFIGURATION.md

CHANGELOG：

API配置迁移到环境变量。

CONFIGURATION：

以后去哪修改API。

67. 状态变化

如果一个版本使：

项目阶段改变。

例如：

首次Production Build通过

可以同步：

PROJECT_STATUS.md

68. Bug修复状态

CHANGELOG里写：

Fixed

之前：

关联Bug最好已经：

VERIFIED

如果只是代码改了但没测试：

不要急着进入正式Released版本。

69. 已知未验证修改

开发阶段可以放：

Unreleased

并备注：

Verification Pending

但正式发布前应清理。

70. 一个版本的标准结构

推荐：

[0.5.0] - 2026-XX-XXStatus: RELEASED### Added…### Changed…### Fixed…### Security…### Database…### API…### Config…### Dependencies…### Deployment…### Documentation…### Upgrade Notes…### Known Issues…

按需保留。

71. 当前CHANGELOG初始化

当前还没有完整历史版本事实。

因此：

不要假装已经存在：

v0.1v0.2v0.3

详细发布历史。

当前先从：

Unreleased

开始。

72. 当前 Unreleased

[Unreleased]

Documentation

建立 AI_START_HERE.md，作为AI进入项目的统一入口。

建立 /AI_RULES/ 六大永久规则体系：

01_REQUIREMENTS_RULES.md

02_DESIGN_SYSTEM_RULES.md

03_ENGINEERING_RULES.md

04_SECURITY_RULES.md

05_TESTING_RULES.md

06_RELEASE_OPERATIONS_RULES.md

建立 PROJECT_STATUS.md，用于维护项目当前真实状态。

建立 ARCHITECTURE.md，用于维护项目技术架构与模块关系。

建立 CONFIGURATION.md，用于维护配置入口与修改方式。

建立 BUG_TRACKER.md，用于管理Bug、风险、修复和验证状态。

建立 CHANGELOG.md，用于维护项目长期版本变化历史。

Changed

项目开发方式开始从“依赖AI聊天上下文”转向“项目文件作为长期事实与规则来源”。

建立AI任务前读取规则、任务后验证与报告的项目治理方式。

Known Issues

当前真实项目架构、配置、API、数据库、认证、管理员、安全、Build与部署状态仍需通过代码扫描和实际运行继续补充。

当前完整正式版本号体系尚未确认。

73. 历史已知变化区

以下属于过去已经知道发生过的变化，

但具体版本尚未确认。

因此：

暂不强行归入某个正式版本。

【历史变更，版本待确认】

Font System

字体系统曾进行配置化调整。

曾出现：

font-config.jsonfont-loader.js字体CSS

等结构。

目标为：

字体配置↓加载器↓CSS变量↓全局页面

当前最新状态需重新扫描确认。

Fixed

曾发现并修复普通CSS中存在类似Sass/Less组合类的非法语法问题。

关联历史问题：

BUG-HISTORY-001

当前版本是否完全不存在同类问题：

待重新扫描。

Fixed

曾对 lunar.js 中太阳高度相关计算代码进行整理和修复。

当前最新版本：

待重新验证。

74. 历史变更迁移规则

如果未来从：

Git历史

旧版本包

正式文档

确认：

某项变化属于：

0.2.0

则可以从：

【历史变更，版本待确认】

迁移到：

[0.2.0] - 日期

75. 不要伪造完整历史

如果过去：

没有正式版本体系。

那就从现在建立。

没必要为了让项目“看起来专业”：

编造：

v0.1.0v0.2.0v0.3.0

76. 从现在开始建立可靠历史

未来每个稳定发布节点：

正式记录。

这样一年以后：

历史自然完整。

77. 版本发布流程

建议：

开发↓Unreleased↓功能完成↓测试↓Bug修复↓Production Build↓上线验收↓确定版本号↓整理CHANGELOG↓发布

78. 发布前CHANGELOG检查

□ 本版本新增功能已记录□ 重要修改已记录□ Bug修复有关联编号□ 安全变化已记录□ API变化已记录□ 数据库变化已记录□ 配置变化已记录□ 依赖变化已记录□ 部署注意事项已记录□ Known Issues已确认□ 日期正确□ 版本号正确

79. 版本发布后

更新：

PROJECT_STATUS.md

例如：

当前版本：0.5.0

80. 重大版本变更

同时检查：

ARCHITECTURE.mdCONFIGURATION.mdDEPLOYMENT.md.env.example

是否需要更新。

81. AI新增CHANGELOG条目规则

AI不得直接写：

优化了系统。

必须描述：

具体变化。

例如：

• 将前端API地址从多个组件中的固定值统一迁移至API配置层。

82. AI不得写虚假成功

如果功能：

代码已改

但没测试。

不要正式写：

Fixed

可以暂时在Unreleased标记：

Changed- 调整xxx实现，验证待完成。

或者先不进入正式变更记录。

83. AI不能擅自宣布正式版本

用户没有决定发布：

AI可以更新：

Unreleased

不能自己：

发布 v1.0.0

84. 版本历史必须保持时间顺序

推荐：

最新版本在上。

旧版本在下。

结构：

Unreleased0.8.00.7.20.7.10.7.0

85. 删除历史版本

原则上禁止删除已经发布版本的记录。

如果版本错误：

新增说明。

不要让历史消失。

86. 版本撤回

例如：

[0.7.0] - 2026-XX-XXStatus: ROLLBACK

保留。

不要假装这个版本从没存在。

87. 项目负责人快速查看区

以后文件顶部建议长期维护：

当前版本：当前状态：上次发布：下一版本：当前Unreleased变更数量：

当前：

当前版本：待确认当前状态：DEVELOPMENT上次正式发布：待确认下一版本：待决定Unreleased：已建立

88. CHANGELOG项目价值

这个文件最大的价值不是：

看起来专业。

而是未来某个AI看到一段奇怪代码时：

可以查：

为什么以前改成这样？

可能会看到：

0.6.2Fixed- 为解决Safari字体加载失败，保留本地Fallback。

于是它不会：

“这个Fallback没用，我删掉。”

然后Safari又炸一次。😂

89. 变更原因

对于明显的架构或技术变化：

建议写：

原因：

例如：

Changed- API Base URL迁移至统一配置层。原因：避免开发环境地址硬编码导致生产部署失败。

普通小修复无需每条都写原因。

90. 重大决策

如果变化背后是重大架构选择：

CHANGELOG只写变化。

详细原因建议进入：

ADR

或：

ARCHITECTURE.md

91. CHANGELOG与AI长期记忆

新的AI不需要记得：

半年以前谁改过什么。

它只需要：

读取CHANGELOG

即可知道：

项目是怎么走到今天的。

92. CHANGELOG也是防止AI反复改回去的机制

例如：

Changed- 为避免生产环境路径问题，将资源路径改为相对Base Path。

未来AI就不应该：

因为觉得绝对路径更简单

又改回去。

93. 变更记录语言

建议以：

简洁

明确

可理解

为原则。

不要充满：

只有原作者才能看懂的缩写。

94. 安全信息原则

公开或可能共享的CHANGELOG：

禁止记录：

真实Secret

内部密码

可直接利用的漏洞Payload

服务器敏感地址

95. 当前文件状态

CHANGELOG体系：✅ 已建立正式版本号：⚪ 待确认历史完整度：🟡 从现在开始可靠记录Unreleased：✅ 已建立历史变更：🟡 已保留待确认区域

96. 下一份文档

下一步建议建立：

DEPLOYMENT.md

它负责回答：

项目换一台电脑、换一个AI、换一个服务器以后，到底怎么重新跑起来？

END

本文件是：

项目长期版本变化的主要事实源。

记录：

已经真实发生的变化。

不记录：

未来愿望。

不编造：

不存在的历史版本。

无法确认的历史：

明确标记待确认。

从本文件建立之日起：

每次正式版本变化应持续维护。