Kimi Code CLI Changelog 生成规范从 git 提交到中英双语发布说明的完整工作流【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKimi Code CLI 仓库在.agents/skills/gen-changelog/SKILL.md中定义了一个名为gen-changelog的 Agent Skill用于为当前分支相对main的代码变更生成 changelog 条目并同步到文档站点。本文以该 Skill 为骨架结合仓库中的根CHANGELOG.md、子包 changelog、同步脚本与中英双语发布说明完整讲解如何用统一的前缀约定、条目格式与工作流把一次代码提交沉淀为面向用户的发布说明。读完本文你将掌握 Kimi Code CLI 的 changelog 写作规范、前缀体系、同步命令以及破坏性变更的双语处理流程。为什么需要一个专门的 Changelog 生成 SkillKimi 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下增加带AffectedMigration小节的说明并在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 2nul 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按键、状态栏、斜杠命令、终端渲染Webkimi webViskimi vis追踪可视化器CLI顶层 flags、子命令、--print/--yolo/--afkACPZed / JetBrains 及其他 ACP 集成CoreAgent 运行时、步骤循环、审批、配额、轮次、后台任务Tool任一内置工具正文中须指明具体工具名ReadFile、Grep、Todo、Plan 等SkillSkill 发现/加载、Flow、Loop始终用单数Skill:不用Skills:MCPMCP 服务器集成Plugin插件系统、kimi plugin子命令LLM供应商无关或跨供应商正文中须指明供应商Kimi / Anthropic / OpenAI / DeepSeek 等不要为每个供应商创建独立前缀Kosong根 CHANGELOG 中体现的kosongLLM 抽象层变更子包自己的 changelog 使用供应商前缀WireWire 协议事件、版本AuthOAuth、token 刷新、/loginConfig配置 schema、环境变量Lib面向 SDK 的 API 变更BuildNix / Rust / Python / 打包从源码结构看这张表与仓库的模块划分一一对应Shell对应 src/kimi_cli/ui/shell 的终端界面Web对应 src/kimi_cli/web 与 web 前端Vis对应 src/kimi_cli/visACP对应 src/kimi_cli/acpMCP对应 src/kimi_cli/acp/mcp.py 与 src/kimi_cli/mcp_oauth.pyWire对应 src/kimi_cli/wireAuth对应 src/kimi_cli/authKosong对应 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、集成等用户可见变更子包 changelogpackages/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使用AffectedMigration小节中文文档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:条目的版本可以跳过 HighlightsHighlights 是摘要每条被点名的变更仍然需要在下方保留完整 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 models 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），仅供参考