product-changelog

用途

Product Changelog 是一个撰写产品更新日志（changelog）与发布说明（release notes）的技能，目标是让更新内容被用户真正阅读和关心。它提供了条目格式、语言规范、分类体系、版本编号、页面结构、配图方式与分发渠道的完整写作指引。

主要能力

条目结构规范

好的条目遵循如下结构：分类标签 → 面向用户的标题 → 用户现在能做什么 → 怎么操作 → 改变了什么 → 视觉配图。示例：

### New: Bulk Export for Reports 📊

You can now export up to 10,000 rows at once from any report view.
Select your rows, click Export, and choose CSV or Excel format.

Previously limited to 500 rows per export.

![Bulk export button in the reports toolbar](screenshot.png)

面向用户的语言

文档强调要写“用户能做什么”，而不是“你构建了什么”。

不推荐（内部语言）：

"Implemented batch processing queue for the export service"
"Refactored the ReportExporter class to support pagination"
"Fixed bug in CSV serialization (PR #4521)"

推荐（面向用户）：

"You can now export up to 10,000 rows at once from any report"
"Reports now load 3x faster when filtering large datasets"
"Fixed an issue where exported CSV files had missing columns"

写作规则包括：使用现在时；以 "You can now..." / "Reports now..." / "Fixed an issue where..." 开头；说明收益而非仅讲机制。

分类体系

技能定义了五类标准分类及对应颜色与图标：

分类	颜色	图标	用途
New	绿色	✨ 或 🆕	全新功能或能力
Improved	蓝色	⚡ 或 🔧	对现有功能的增强
Fixed	黄色/橙色	🐛 或 🔨	Bug 修复
Removed	红色	🗑️ 或 ⚠️	弃用或移除的功能
Security	紫色	🔒	安全补丁

分类规则：New 指用户此前完全做不到的事；Improved 指原本能做、现在更好/更快/更简单；Fixed 指原本损坏、现在正常。不建议使用 "Updated"，因为它含义模糊。

版本编号

支持两种方式：

语义化版本（SemVer）MAJOR.MINOR.PATCH：

MAJOR：破坏性变更、重大改版（2.0.0 -> 3.0.0）
MINOR：新增功能、向后兼容（3.1.0 -> 3.2.0）
PATCH：Bug 修复、小幅改进（3.2.0 -> 3.2.1）

日期式版本：如 2026-02-08、2026.02.08 或 February 8, 2026，适合持续部署的 SaaS 产品。

Changelog 页面结构

文档给出按日期分组、按分类罗列的页面模板，含 New / Improved / Fixed 分区及条目示例（如 Bulk Export、Dark Mode、Dashboard Loading、API Webhooks 等）。

视觉配图

不同变更类型建议配不同视觉：新 UI 功能配功能截图，UI 改版配前后对比，新工作流配分步截图或短视频，性能改进配改善图表，复杂功能配动图或视频演示。

技能通过 inference.sh CLI（belt）提供配图命令，需先安装并登录：

npx skills add belt-sh/cli
belt login

生成功能截图：

belt app run infsh/agent-browser --input '{
  "url": "https://your-app.com/new-feature",
  "action": "screenshot"
}'

生成前后对比图：

belt app run infsh/stitch-images --input '{
  "images": ["before-screenshot.png", "after-screenshot.png"],
  "direction": "horizontal"
}'

生成带标注截图：

belt app run bytedance/seededit-3-0-i2i --input '{
  "prompt": "add a red circle highlight around the export button in the top right area",
  "image": "screenshot.png"
}'

生成功能公告横幅：

belt app run falai/flux-dev-lora --input '{
  "prompt": "clean modern product announcement banner, gradient blue to purple background, abstract geometric shapes, professional SaaS aesthetic, wide format",
  "width": 1248,
  "height": 832
}'

破坏性变更处理

文档要求破坏性变更特别标注，需说明：变更内容、用户需要做什么（含迁移步骤与迁移指南链接）、时间线（何时可用、何时告警、何时停止）、以及支持联系方式。

分发渠道

不同渠道对应不同形式与时机：changelog 页面（每次发布、完整详情）、应用内通知（1-2 行摘要）、邮件（重点精选、含视觉，重大发布时月度/季度发送）、博客文章（大发布时深度解读）、社交媒体（单功能高亮）、Slack/Discord（简短公告）。社交媒体系采用固定片段格式。

写作建议与常见错误

建议：合并相关变更、最大的变更放最前、复杂功能链接文档、标注用户呼声（"By popular request:"）、展示迁移路径、为每条目标日期。

避免：写 "various bug fixes"、包含内部引用（PR 号、工单 ID、分支名）、无说明的 "Updated [feature]"、列出无人关心的变更（依赖升级、内部重构）、直接堆提交记录。

发布频率

按产品类型区分：持续部署 SaaS 每周批量汇总；重大功能按发布节点；版本化软件按版本发布（对应 semver）；API 按版本加弃用通知（含迁移指南）；移动应用按应用商店发布（与商店 "What's New" 一致）。

使用方式

该技能通过 npx skills add 安装使用。安装命令：

npx skills add belt-sh/cli

适用场景

适用于 SaaS 产品、版本化软件、API 服务、移动应用等需要向用户传达产品变更的团队，覆盖从条目撰写、配图生成到多渠道分发的整个流程。

限制

资料未提供该技能的具体收费、价格信息；亦未说明可支持的语言范围、平台兼容细节或效果保证，相关内容暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制