releasenotes

releasenotes

一份变更日志，面向两类受众。产品使用者想知道有哪些与自己相关的变化，用直白的语言说明，并把可能影响其工作流的内容放在最前面。基于产品构建的人员则想了解所有内容，包括用户看不到的内部条目。手动从同一份变更日志分别撰写两种内容，容易造成不一致，因此 releasenotes 会根据同一组条目生成两种内容：两种输出，而不是复制粘贴。

你需要提供发布版本和变更日志条目——每个条目都包含一个分组（例如 Added、Fixed 或 Changed）及其文本，还可以设置两个可选标记：表示重大变更的 breaking，以及指定条目面向对象的 audience（user、developer 或 both）。根据这些信息，releasenotes 会生成：

• 用户说明（## What's new in <version>）——首先是 Breaking changes 部分，按输入顺序列出所有面向用户的重大变更条目；接着每个分组各有一个部分，列出该分组中其余非重大且面向用户的条目。仅面向开发者的条目不会出现在这里。如果没有面向用户的内容，说明中只包含标题和“此版本没有面向用户的变更。”这一行。
• 开发者说明（## Release <version> — developer notes）——每个分组各有一个部分，按输入顺序列出所有条目；重大变更会显示为 - BREAKING: <text>，以便在完整列表中醒目呈现，而不是单独归入一个部分。

各部分按解析后的分组顺序排列：可选的 group_order 中指定的分组按其顺序排在前面（重复项会被忽略），未指定的分组则按其在条目中首次出现的顺序排列。每个部分中的条目保持输入顺序。两种说明的各部分之间都恰好有一个空行，且末尾没有换行符。

结果还会统计条目数量：总数、重大变更数、面向用户的条目数（user 或 both），以及仅面向开发者的条目数。格式错误的输入——例如缺少版本或版本为空、缺少条目列表或列表为空、条目缺少分组或文本、breaking 不是布尔值、audience 不属于三个允许值之一，或 group_order 格式错误——会导致验证错误，并指出有问题的路径（例如 entries[1].audience must be one of "user", "developer", "both"），且不会生成部分结果。计算过程纯粹且在本地执行：不访问网络、不需要配置，也不会读取你传入的输入之外的文件。

CLI

npx @reneturcios/releasenotes generate --input args.json
npx @reneturcios/releasenotes --version

args.json 包含完整的参数对象：

{
  "version": "2.0.0",
  "group_order": ["Added", "Fixed"],
  "entries": [
    { "group": "Changed", "text": "Config files now use TOML.", "breaking": true },
    { "group": "Added", "text": "Dark mode for the dashboard." },
    { "group": "Fixed", "text": "Crash on empty search.", "audience": "user" },
    { "group": "Changed", "text": "Internal cache rewritten.", "audience": "developer" }
  ]
}

每个条目的 breaking 默认为 false，audience 默认为 "both"；group_order 为可选项。结果会以 JSON 格式输出：

{
  "version": "2.0.0",
  "user_notes": "## What's new in 2.0.0\n\n### Breaking changes\n- Config files now use TOML.\n\n### Added\n- Dark mode for the dashboard.\n\n### Fixed\n- Crash on empty search.",
  "developer_notes": "## Release 2.0.0 — developer notes\n\n### Added\n- Dark mode for the dashboard.\n\n### Fixed\n- Crash on empty search.\n\n### Changed\n- BREAKING: Config files now use TOML.\n- Internal cache rewritten.",
  "counts": { "entries": 4, "breaking": 1, "user_facing": 3, "developer_only": 1 }
}

退出码：成功时为 0，发生运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/releasenotes mcp

MCP 客户端配置：

{
  "mcpServers": {
    "releasenotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/releasenotes", "mcp"]
    }
  }
}

工具

• generate_release_notes — 根据变更日志条目生成两种发布说明。

  • version（字符串，必填，不能为空）— 发布说明所对应的版本
  • entries（数组，必填，至少一个条目）— 变更日志条目，格式为 {group, text, breaking?, audience?} 对象；group 和 text 是非空字符串，breaking 默认为 false，audience 的值为 user、developer 或 both（默认为 both）
  • group_order（数组，可选）— 分组顺序；未列出的分组按首次出现顺序排列，重复项会被忽略

  返回 {version, user_notes, developer_notes, counts}。

Docker

docker run -i ghcr.io/cloudcorprecords/releasenotes
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/releasenotes generate --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios