Nex Changelog

面向客户的发布沟通用变更日志（Changelog）与版本说明生成工具。支持按变更类型和目标受众组织代码变更，可从 Git 提交记录导入内容，并导出多种格式的专业发布说明（如 Keep a Changelog、客户邮件、Telegram 消息等）。

适用场景

当用户提出以下需求时，请启用本技能：

• 为项目生成变更日志或发布说明
• 创建版本更新说明或“新增功能”摘要
• 撰写面向客户的发布公告
• 记录破坏性变更（breaking changes）或安全更新
• 按类型（如新增功能、修复问题、破坏性变更等）归类代码变更
• 将 Git 提交消息导入为变更日志条目
• 跨多个项目跟踪变更
• 为新版本创建 Telegram 或邮件形式的更新通知
• 区分不同受众（内部团队、客户、公开用户）进行内容管理
• 以标准格式导出变更日志

触发关键词：“changelog”、“release notes”、“version update”、“what changed”、“client email”、“release announcement”、“breaking changes”、“new features”、“fixed issues”、“generate changelog”、“import commits”、“what's new”

快速初始化

若数据库尚不存在，请运行初始化脚本：

bash setup.sh

该脚本将创建数据目录、安装依赖项并初始化数据库。

可用命令

命令行工具名为 nex-changelog，所有命令输出均为纯文本。

添加条目

手动添加一条变更日志条目：

nex-changelog add --project "Ribbens Airco Website" --type added --description "Contact form with email notification" --audience client

nex-changelog add --project "My App" --description "Fixed the header menu on mobile" --type fixed --author "John Doe"

nex-changelog add --project "API Service" --type security --description "Patched SQL injection vulnerability" --breaking

支持的变更类型：ADDED、CHANGED、FIXED、REMOVED、SECURITY、DEPRECATED、PERFORMANCE

支持的受众类型：INTERNAL、CLIENT、PUBLIC

从 Git 导入

从 Git 仓库导入提交记录作为变更日志条目：

nex-changelog git /path/to/repo --project "My App" --version 1.3.0

nex-changelog git /path/to/repo --since v1.2.0 --project "My App"

nex-changelog git /path/to/repo --project "API" --description "REST API service"

该工具会自动执行以下操作：

• 解析符合 Conventional Commits 规范的提交（如 feat:、fix:、chore:、security: 等）
• 将提交归类至对应变更类型
• 判断受众范围（内部使用 or 面向客户）
• 提取作者名与提交哈希（commit hash）

创建发布版本

为指定版本创建正式发布记录：

nex-changelog release --project "Ribbens Airco Website" --version 1.3.0 --summary "Mobile fixes and contact form"

nex-changelog release --project "My App" --version 2.0.0 
  --summary "Major rewrite" 
  --client-notes "New dashboard and improved performance" 
  --internal-notes "API v2, deprecated v1 endpoints"

显示变更日志

展示某项目的变更日志：

nex-changelog show --project "Ribbens Airco Website" --format keepachangelog

nex-changelog show --project "My App" --version 1.3.0 --format simple

nex-changelog show --project "API Service" --type fixed --format table

nex-changelog show --project "My App" --audience client --format json

支持的输出格式：keepachangelog、simple、table、json

列出条目

带筛选条件列出全部变更日志条目：

nex-changelog list --project "My App"

nex-changelog list --type fixed --audience client

nex-changelog list --version 1.3.0

nex-changelog list --project "API" --type security

未发布条目

显示尚未归属到任何发布版本的条目：

nex-changelog unreleased --project "Ribbens Airco Website"

生成客户邮件

为一次发布生成专业、面向客户的邮件内容：

nex-changelog email --project "Ribbens Airco Website" --version 1.3.0

nex-changelog email --project "My App" --version 1.3.0 --client "Acme Corp"

输出内容包含：

• 亲切友好的问候语
• 按变更类型组织的更新内容（含 Emoji 表情）
• 面向客户的语言表达（避免技术术语）
• 署名信息

生成 Telegram 消息

生成简洁紧凑、适配 Telegram 的更新消息：

nex-changelog telegram --project "Ribbens Airco Website" --version 1.3.0

输出内容简洁且含 Emoji 表情，适用于 Telegram 或 Slack 发布。

项目管理

新增、列出或查看项目信息：

nex-changelog project add 
  --name "Ribbens Airco Website" 
  --repo-path /path/to/repo 
  --client-name "Ribbens Airco" 
  --client-email "contact@ribbens-airco.be" 
  --description "Corporate website with contact form"

nex-changelog project list

nex-changelog project show --name "Ribbens Airco Website"

导出变更日志

将完整变更日志导出为 Markdown 文件：

nex-changelog export --project "My App" --output CHANGELOG.md

搜索条目

在全部条目中执行全文检索：

nex-changelog search --query "security"

nex-changelog search --query "header menu" --project "Ribbens Airco Website"

nex-changelog search --query "performance" --project "API"

统计信息

查看各项目的汇总统计数据：

nex-changelog stats

输出内容包括：

• 各项目的条目总数
• 各项目的发布次数
• 各项目的最新版本号
• 全局统计摘要

交互示例

用户：“Ribbens Airco 最新版本有哪些变更？”
Agent 执行：nex-changelog show --project "Ribbens Airco Website" --format simple
Agent：自然呈现格式化后的变更日志。

用户：“为 1.3.0 版本生成一封客户邮件”
Agent 执行：nex-changelog email --project "Ribbens Airco Website" --version 1.3.0
Agent：展示已准备就绪、可直接发送的专业邮件。

用户：“从代码仓库导入最近的提交记录”
Agent 执行：nex-changelog git /path/to/repo --project "My App"
Agent：确认已成功导入条目并完成归类。

用户：“新增一条：修复 SSL 重定向问题”
Agent 执行：nex-changelog add --project "My App" --description "Fixed the SSL redirect issue" --type fixed --audience client
Agent：确认该条目已成功添加。

用户：“为 ECHO Management 网站创建 2.1.0 版本发布”
Agent 执行：nex-changelog release --project "ECHO Management" --version 2.1.0
Agent：确认发布已成功创建。

输出解析规则

所有 CLI 输出均为结构化的纯文本，便于程序解析：

• 章节标题后跟随 --- 分隔线
• 列表项以 - 或 • 开头
• 时间戳采用 ISO-8601 格式
• 每条命令输出末尾均附有 [Nex Changelog by Nex AI | nex-ai.be]

向用户呈现输出时，请移除页脚行，并以自然、易读的方式组织信息。

数据存储

所有变更日志数据均本地存储于 ~/.nex-changelog/ 目录下：

• changelog.db —— SQLite 数据库，保存项目、条目及发布记录
• exports/ —— 生成的 Markdown 文件及其他导出内容

无任何数据上传至外部服务器，整个工具完全离线运行。

Conventional Commits 支持

该工具自动识别并解析符合 Conventional Commits 规范的提交消息：

feat: add new feature          → ADDED 类型，CLIENT 受众
fix: resolve issue             → FIXED 类型，CLIENT 受众
docs: update documentation     → CHANGED 类型，INTERNAL 受众
style: formatting changes      → CHANGED 类型，INTERNAL 受众
refactor: code reorganization  → CHANGED 类型，INTERNAL 受众
perf: performance improvements → PERFORMANCE 类型，CLIENT 受众
test: add test coverage        → CHANGED 类型，INTERNAL 受众
chore: dependency update       → CHANGED 类型，INTERNAL 受众
security: fix vulnerability    → SECURITY 类型，CLIENT 受众

含感叹号的提交（如 feat! 或 fix!）将被自动标记为破坏性变更（breaking changes）。

重要说明

• 所有数据均本地存储于 ~/.nex-changelog/，不采集遥测数据，也不调用任何外部 API。
• 数据库支持多项目管理，各项目拥有独立的变更日志。
• 条目支持按类型、受众、版本号、项目名等多种维度筛选。
• 发布版本通过版本号自动关联对应条目。
• Git 提交将依据 Conventional Commits 规范自动分类。
• 客户邮件仅展示标记为 CLIENT 或 PUBLIC 受众的条目。
• 内部视图默认展示全部条目，不受受众限制。

故障排查

• “Project not found”：运行 nex-changelog project list 查看已有项目，或使用 nex-changelog project add 新建项目。
• “No entries found”：运行 nex-changelog list 查看全部条目，或使用 nex-changelog add 添加新条目。
• “Git import failed”：请确认仓库路径正确，且目标目录中存在 .git 子目录。
• 数据库错误：数据库会在首次运行时自动初始化；请检查 ~/.nex-changelog/ 目录是否存在且具有写入权限。
• Conventional Commits 未被识别：请确认提交消息格式符合 type(scope): description 规范。

致谢

由 Nex AI（https://nex-ai.be）开发 —— 专注比利时中小企业的数字化转型服务。