Kimi Code CLI Changelog 生成规范：从 git 提交到中英双语发布说明的完整工作流-港品优选

Kimi Code CLI Changelog 生成规范：从 git 提交到中英双语发布说明的完整工作流

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli

Kimi Code CLI 仓库在.agents/skills/gen-changelog/SKILL.md中定义了一个名为gen-changelog的 Agent Skill，用于为当前分支相对main的代码变更生成 changelog 条目，并同步到文档站点。本文以该 Skill 为骨架，结合仓库中的根CHANGELOG.md、子包 changelog、同步脚本与中英双语发布说明，完整讲解如何用统一的前缀约定、条目格式与工作流，把一次代码提交沉淀为面向用户的发布说明。读完本文，你将掌握 Kimi Code CLI 的 changelog 写作规范、前缀体系、同步命令，以及破坏性变更的双语处理流程。

为什么需要一个专门的 Changelog 生成 Skill

Kimi Code CLI 是一个同时发布根包与多个子包（packages/kosong、packages/kaos、sdks/kimi-sdk等）的 monorepo，其发布说明既要服务于终端用户（Shell/Web/CLI 等可见功能），也要服务 SDK 使用者，还要保持英文与中文两个文档站点的同步。如果每个提交者都按自己的习惯写 changelog，发布时会出现前缀混乱、粒度不一、中英文不同步等问题。

gen-changelogSkill 把这一整套约定固化成可执行的步骤，确保：

入口统一：所有条目都基于git log main..HEAD与git diff main..HEAD --stat生成，变更范围一目了然；
口径一致：根 CHANGELOG 使用固定的前缀表，禁止发明新前缀，避免各写各的；
多语言同步：英文 changelog 由脚本自动生成，中文版由人工按术语表翻译，保证「单一事实来源」；
用户视角：只写对用户有意义的变更，内部重构、测试改动、CI 调整一律不写。

Skill 的整体工作流

gen-changelogSkill 定义在 .agents/skills/gen-changelog/SKILL.md，其 frontmatter 只有两个字段：

--- name: gen-changelog description: Generate changelog entries for code changes. ---

工作流分为五步：

检查变更：运行git log main..HEAD --oneline查看提交列表，运行git diff main..HEAD --stat查看文件变更统计，确认本次要写进 changelog 的内容；
编辑根 CHANGELOG：在CHANGELOG.md的## Unreleased下按下方前缀表添加条目；如果变更只影响packages/或sdks/下的子包，同时更新该子包自己的CHANGELOG.md—— 子包 changelog 遵循各自的前缀约定（例如packages/kosong/CHANGELOG.md使用Kimi:/Anthropic:这类供应商前缀），只有根 CHANGELOG 才使用下文的前缀表；
同步英文文档：运行node docs/scripts/sync-changelog.mjs，把根CHANGELOG.md同步到docs/en/release-notes/changelog.md；
翻译中文：在docs/zh/release-notes/changelog.md的## 未发布下手写对应的中文条目，使用全角冒号：，并遵循docs/AGENTS.md的术语表；
处理破坏性变更：如有破坏性变更，在docs/en/release-notes/breaking-changes.md的## Unreleased下增加带Affected+Migration小节的说明，并在docs/zh/release-notes/breaking-changes.md的## 未发布下增加带受影响+迁移小节的说明。

值得注意的是，Skill 中并没有自动生成中文条目的脚本——第 4 步强调「hand-write」（手写），这是因为中文 changelog 需要符合 docs/AGENTS.md 的术语映射与排版约定，无法通过机械替换完成。

条目格式：一条可独立阅读的变更

Skill 对每一条 changelog 条目规定了严格格式：

- <Prefix>: <verb-led sentence, readable standalone> — <optional rationale / before-after / migration>

对应到实际仓库，例如根 CHANGELOG.md 中的条目：

- Shell: Defend against hallucinated CMD-style `2>nul` redirects on Windows by rewriting them to `2>/dev/null` before reaching git-bash — without this defense git-bash would create a file literally named `nul` (a Windows reserved device name) that breaks `git add .` and `git clone`; on Linux/macOS, `>nul` is a legitimate redirect to a file named `nul` and is left untouched

写作时必须遵守四条原则：

首句独立成篇：读者读完第一句话就应该能判断这条变更是否与自己相关，不能依赖后面的解释；
一条变更一个 bullet：不允许出现; also、; and或嵌套破折号来拼接多个变更，两个变更就写两条；
动词开头：使用Fix …/Add …/Switch …/Bump …等动词引导；
只写用户有意义的变更：内部重构、测试改动、CI 调整一律不写，唯一的例外是面向 SDK 的变更可以用Lib:前缀。

前缀表：16 个前缀，禁止发明新词

根 CHANGELOG 的前缀是 Skill 的核心约定，只能从前缀表中选择，不允许发明新前缀：

前缀	适用范围
`Shell`	交互式 TUI：按键、状态栏、斜杠命令、终端渲染
`Web`	`kimi web`
`Vis`	`kimi vis`追踪可视化器
`CLI`	顶层 flags、子命令、`--print`/`--yolo`/`--afk`
`ACP`	Zed / JetBrains 及其他 ACP 集成
`Core`	Agent 运行时、步骤循环、审批、配额、轮次、后台任务
`Tool`	任一内置工具；正文中须指明具体工具名（ReadFile、Grep、Todo、Plan 等）
`Skill`	Skill 发现/加载、Flow、Loop（始终用单数`Skill:`，不用`Skills:`）
`MCP`	MCP 服务器集成
`Plugin`	插件系统、`kimi plugin`子命令
`LLM`	供应商无关或跨供应商；正文中须指明供应商（Kimi / Anthropic / OpenAI / DeepSeek 等），不要为每个供应商创建独立前缀
`Kosong`	根 CHANGELOG 中体现的`kosong`LLM 抽象层变更（子包自己的 changelog 使用供应商前缀）
`Wire`	Wire 协议事件、版本
`Auth`	OAuth、token 刷新、`/login`
`Config`	配置 schema、环境变量
`Lib`	面向 SDK 的 API 变更
`Build`	Nix / Rust / Python / 打包

从源码结构看，这张表与仓库的模块划分一一对应：Shell对应 src/kimi_cli/ui/shell 的终端界面，Web对应 src/kimi_cli/web 与 web 前端，Vis对应 src/kimi_cli/vis，ACP对应 src/kimi_cli/acp，MCP对应 src/kimi_cli/acp/mcp.py 与 src/kimi_cli/mcp_oauth.py，Wire对应 src/kimi_cli/wire，Auth对应 src/kimi_cli/auth，Kosong对应 packages/kosong。

写作时如果拿不准该用哪个前缀，Skill 给出的兜底策略是：匹配同类既有条目，优先使用表中已有前缀；如果确实需要新前缀，必须与维护者沟通，并在同一个 PR 中更新前缀表，保证约定「单一来源」（single-sourced）。

此外还有两条排序约定：

前缀顺序：同一版本内，按前缀表从上到下的顺序分组排列条目；
组内顺序：同一前缀内部顺序自由，保持开发顺序即可。

对照根 CHANGELOG.md 的 1.40.0 一节可以看到，条目确实按CLI、Config、Shell、Web、Kosong、Core、Auth的前缀表顺序排列。

根 CHANGELOG 与子包 CHANGELOG 的分工

这是整个工作流最容易出错的地方。Skill 明确区分了两套 changelog：

根CHANGELOG.md：面向终端用户，使用上面前缀表，覆盖 CLI、UI、集成等用户可见变更；
子包 changelog（packages/kosong/CHANGELOG.md、packages/kaos/CHANGELOG.md、sdks/kimi-sdk/CHANGELOG.md等）：面向 SDK 使用者，遵循各自的前缀约定。

以 packages/kosong/CHANGELOG.md 为例，它的前缀是供应商粒度的：

- Kimi: Stop automatically sending the legacy `reasoning_effort` parameter when configuring thinking — requests now use `thinking.type` exclusively while preserving explicit legacy passthrough - Kimi: Preserve empty-string `reasoning_content` as `ThinkPart(think="")` in both streaming and non-streaming responses ... - Kimi: Add `GenerationKwargs.max_completion_tokens` and normalize the deprecated `max_tokens` alias to it before requests ... - Core: Expose the `x-trace-id` response header as `StreamedMessage.trace_id` ...

对比同一批变更在根 CHANGELOG.md 中的写法（合并为LLM:与Kosong:前缀、面向 CLI 用户描述），可以看出两套 changelog 的读者对象和粒度完全不同：子包用Kimi:/Anthropic:区分供应商，根 changelog 则刻意用供应商无关的LLM:前缀并在正文中点名供应商。因此，修改packages/kosong/src/kosong/下的代码时，既要在子包 changelog 写Kimi:条目，也要评估它是否值得在根 changelog 中体现（此时用Kosong:前缀）。

同步英文文档：sync-changelog.mjs 脚本

Skill 第 3 步运行的同步脚本位于 docs/scripts/sync-changelog.mjs，它把根CHANGELOG.md复制到docs/en/release-notes/changelog.md，并做三类格式化转换：

去掉顶部 HTML 注释块（），因为该注释只是给解析器看的说明；
去掉# Changelog标题，替换为文档站点专用的HEADER（# Changelog+ 一行说明）；
转换版本标题格式：## [0.69] - 2025-12-29→## 0.69 (2025-12-29)，正则^## \[([^\]]+)\] - (\d{4}-\d{1,2}-\d{1,2})负责匹配；
删除### Added/### Changed/### Fixed/### Improved/### Tools/### SDK等子标题，只保留版本号与 bullet。

脚本开头注释明确要求「从 docs 目录运行」：node scripts/sync-changelog.mjs。不过 docs/package.json 中已经封装了 npm scripts，日常更推荐：

cd docs && npm run sync

而且npm run dev与npm run build都会在执行 VitePress 命令前自动运行 sync，因此本地开发文档站点时英文 changelog 始终是最新的。这也是 docs/AGENTS.md 中「英文 changelog 是自动生成、禁止手工编辑」的机制保障。

中文翻译：术语、标点与全角冒号

Skill 第 4 步要求在docs/zh/release-notes/changelog.md的## 未发布下手写中文条目，并特别强调两点：使用全角冒号：，遵循docs/AGENTS.md 的术语表。

对照仓库中的中英文版本，例如英文条目：

- Core: Fix connection recovery not triggering OAuth refresh when the retry returns 401 — after recreating the HTTP client on `APIConnectionError` or `APITimeoutError`, ...

对应的中文条目（docs/zh/release-notes/changelog.md）：

- Core：修复连接恢复在重试返回 401 时未触发 OAuth 刷新——在 `APIConnectionError` 或 `APITimeoutError` 之后重建 HTTP 客户端时，重试会重新进入完整的恢复路径，...

可以看到：前缀与正文之间使用全角冒号，破折号前后语义与英文一致，专业术语（OAuth、HTTP 客户端、API 错误类型）保留英文并用行内代码标注。

docs/AGENTS.md 还规定了更细的翻译约定：中英文混排时中文字符与英文/数字/行内代码之间留一个空格；中文使用全角标点；API key译为API 密钥、tool call译为「工具调用」；术语如Kimi Code CLI、ACP、MCP、Wire保持英文；「终端」优先于「命令行」等。Skill 通过「遵循 docs/AGENTS.md 术语」这句话，把整套本地化规范纳入了 changelog 生成流程。

破坏性变更：Affected + Migration 双语模板

Skill 第 5 步针对破坏性变更给出了固定模板：英文文档docs/en/release-notes/breaking-changes.md使用Affected+Migration小节，中文文档docs/zh/release-notes/breaking-changes.md使用受影响+迁移小节，两处都挂在## Unreleased/## 未发布之下。

以 docs/en/release-notes/breaking-changes.md 中 1.40.0 的条目为例：

### `--print` now uses runtime AFK semantics instead of YOLO semantics Print mode still runs non-interactively and handles approvals automatically, but it now sets an invocation-only AFK overlay instead of enabling YOLO. ... - **Affected**: Scripts, wrappers, or custom integrations that inferred print-mode behavior from the explicit YOLO flag - **Migration**: Treat `--print` / `--quiet` as non-interactive AFK runs. Use `--yolo` only when you want to bypass permission approvals while a user remains reachable

中文版（docs/zh/release-notes/breaking-changes.md）：

### `--print` 现在使用 runtime AFK 语义而不是 YOLO 语义 Print 模式仍然是非交互运行，并且会自动处理审批，但现在设置的是仅本次调用生效的 AFK 覆盖，而不是启用 YOLO。... - **受影响**：通过显式 YOLO 标志推断 Print 模式行为的脚本、包装器或自定义集成 - **迁移**：把 `--print` / `--quiet` 视为非交互 AFK 运行。只有在用户仍可回应、但希望绕过权限审批时才使用 `--yolo`

模板的核心价值在于：受影响让用户快速判断「这与我有关吗」，迁移给出具体的行动步骤，两者结合把破坏性变更的升级成本降到最低。仓库中 1.42.0 的「Windows Shell 后端从 PowerShell 切换为 Git Bash」、1.43.0 的「MCP OAuth token 缓存迁移到~/.kimi/mcp-oauth/」都是同一模板的典型应用，其中迁移步骤往往以编号列表形式展开。

Highlights：为下个版本提炼亮点

Skill 还定义了Highlights机制，从下一个版本开始生效：

在每个版本标题下添加**Highlights**: …（1–3 条大多数用户会注意到的变更），中文版镜像为**亮点**：…；
只有内部变更或Lib:条目的版本可以跳过 Highlights；
Highlights 是摘要，每条被点名的变更仍然需要在下方保留完整 bullet；
不要为历史版本补写Highlights。

仓库中的实例是 CHANGELOG.md 的 1.49.0：

## 1.49.0 (2026-07-16) **Highlights**: The completion-token budget for Kimi providers now adapts to the model's remaining context window, reducing context-length overflow errors on long turns

中文镜像（docs/zh/release-notes/changelog.md）：

## 1.49.0 (2026-07-16) **亮点**：Kimi 供应商的补全 token 预算现在会根据模型剩余上下文窗口动态调整，减少长轮次中的上下文超限错误

Highlights 的作用是让用户在发布说明的最顶部一眼抓住本版本最重要的变化，而完整 bullet 则承载技术细节，二者配合既适合速读也适合深究。

结合源码：从变更到 changelog 的实际链路

把 Skill 的工作流映射到仓库源码，可以看到一条完整的链路：

开发者修改 src/kimi_cli 或 packages/kosong/src/kosong 等目录下的代码并提交到分支；
Agent 运行git log main..HEAD --oneline与git diff main..HEAD --stat定位变更；
按前缀表在根 CHANGELOG.md 的## Unreleased添加条目；子包变更同步更新对应的 packages/kosong/CHANGELOG.md 等文件；
运行docs/scripts/sync-changelog.mjs（或npm run sync）自动生成英文 changelog 页 docs/en/release-notes/changelog.md；
人工在 docs/zh/release-notes/changelog.md 的## 未发布下翻译中文条目；
破坏性变更按 Affected/Migration 模板分别写入中英文 breaking-changes 文档；
发布时（对应.agents/skills/release/SKILL.md的发布流程）把## Unreleased提升为带版本号和日期的标题，并补写 Highlights。

这条链路中，sync-changelog.mjs是唯一自动化环节，它保证了英文 changelog 与根 CHANGELOG 的一致性；中文翻译、破坏性变更与 Highlights 则依赖 Agent 与维护者的人工判断，这正是gen-changelogSkill 把规范「写进提示词」的意义所在——让每个参与提交的人都能按同一套标准产出高质量的发布说明。

小结

gen-changelogSkill 是 Kimi Code CLI 仓库中 changelog 写作的「活规范」：五步工作流覆盖检查变更、编辑根 CHANGELOG、同步英文、翻译中文、处理破坏性变更；16 前缀表约束了条目的分类口径；严格的条目格式保证了每条变更首句即可独立阅读；sync-changelog.mjs脚本把英文 changelog 变成自动生成的产物；Affected/Migration 双语模板让破坏性变更的升级路径清晰可循。这套约定不仅适用于本仓库，也为任何 monorepo 项目提供了一份可借鉴的发布说明管理实践。

【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析