Commit Message 规范

参考 Angular 规范（阮一峰《Commit message 和 Change log 编写指南》），结合本仓库实际情况本地化。纯约定，无工具强制——提交前自查。

格式

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

Header 必需；Body / Footer 可省略。任何一行不超过 72 显示列 （中文按双宽计，约 24~36 个汉字；此约束针对 commit message， markdown 文档本身不受限），避免自动换行破坏格式。

Header

type（必需）

type	用途	进 Change log
`feat`	新功能	是
`fix`	修 bug	是
`docs`	仅文档变动	否
`style`	格式调整（不影响代码运行：空格、格式、标点）	否
`refactor`	既非新增功能、也非修 bug 的代码变动	否
`test`	增加或修改测试	否
`chore`	构建过程或辅助工具的变动	否
`perf`	性能优化（Angular 后续补充，本仓库已在使用）	建议

revert 特殊格式：以 revert: 开头，后跟被撤销 commit 的 Header； Body 固定写 This reverts commit <hash>.

scope（可选）

影响的范围，用模块/包名，如 text、audio、renderer、core、collect、 tts、shared、templates、deploy（Docker/配置/部署）、web、cli。跨多个模块时可省略 scope 或用主导模块名，不要罗列一长串。

subject（必需）

不超过 50 字符（约 17~25 个汉字）。细节一律下沉到 Body，标题保持一行可读。
以动词开头，第一人称现在时（"新增"而非"新增了"），结尾不加句号。
现有提交常用「主题——要点」破折号补充形式；若要点放不下标题，移入 Body。

Body

分点列出改动时，每条先写动机与新旧行为对比，再写做法——说明"为什么改" 比罗列"改了什么"更重要：
- 差：「CLI/web 客户端只透传」
- 好：「模型解析收敛到 core 一处（原 CLI/web 各自合并兜底，行为不一致且静默回退到硬编码旧模型）；现在未配置显式报错，快速失败」
接口/契约变更、删除的兜底逻辑等行为变更必须显式写出旧行为。

Footer

只用于两种情况：

不兼容变动：以 BREAKING CHANGE: 开头，说明变动内容、理由、迁移方法：

BREAKING CHANGE: DocumentRunConfig.llm.model 改为可选。

迁移：调用方不再需要自行兜底默认模型；runDocument 在三者均未设置时抛错。

关闭 Issue：Closes #234，多个用逗号分隔。

此外允许追加 Co-Authored-By: ... trailer（git 惯例，注明协作生成方），放在上述条目之后。

示例

feat(core): LLM 模型三级解析

模型解析收敛到 core runDocument 一处：--llm-model > LLM_MODEL env >
config.llm.model。原来 CLI 与 web 各自合并兜底（硬编码 gpt-4o/glm-5.1），
配置缺失时静默降级到过期模型；现在未配置直接报错，容器部署可仅注入
LLM_MODEL 切换模型，无需改配置文件或重建镜像。

BREAKING CHANGE: DocumentRunConfig.llm.model 由必填改为可选，
调用方传入的 model 不再参与兜底。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

发版流程

tag 采用 vN.N.N annotated tag，双远端推送（Gitee + Gogs）；release 分支仅推 Gogs（触发外部 CI/CD）。详见 docs/DEPLOYMENT.md。

若后续引入 conventional-changelog，本规范的 feat/fix/BREAKING CHANGE 约束可直接支撑自动生成 Change log；当前未启用。

COMMIT_CONVENTION.md 3.8 KB تاريخچه خام