前言¶
在 DSH 或智能体相关项目里发版时，常见做法是对着 git log 逐条筛选，把能给用户看的改动手打进 CHANGELOG.md。约定式提交里的 chore、docs、merge 与真正面向用户的功能改动混在一起，还容易漏掉中文提交或忘写版本号段，下一次发版又要重来一遍。
dsh-changelog（npm 包名 @deepwhale-cn/dsh-changelog）把「这一版对外说了什么」从本地提交历史里直接生成，并按约定式提交归类、过滤内部改动，支持中文润色映射与幂等写入变更日志。维护者为 feely0208，源码托管于 GitHub，许可证为 MIT（0.1.0）。
这是什么¶
这是一款 DeepSeek Harness（DSH）插件，面向需要在发版前整理版本说明的开发者。它只读本地 Git 仓库，不联网、不 fetch；范围判断依赖本地已有的 tag 与 package.json 中的版本号。
装好后面板侧栏会出现「深鲸版本说明」；命令行入口为 dsh-changelog，二者共用同一套逻辑。
核心功能¶
下面按 README 已写明的能力归纳。
提交归类与过滤¶
- 按约定式提交归类：
feat→ 新增，fix→ 修复，其余（如perf、refactor、revert等）→ 其他。 - 自动过滤不宜对外的条目：
chore、docs、ci、test、merge 提交，以及纯版本号类提交（如1.2.3、bump、release）。 - merge 提交通过
git log --no-merges排除，不会出现在任何分组里。
版本范围¶
读 package.json 版本与上一个版本 tag（默认 tag 前缀 v）；本地没有 tag 时退化为「首个版本，全量列出」。
中文润色映射¶
--map <file> 指定 JSON 映射，把提交前缀或关键词转成面向用户的表述。未命中的条目原样保留并标记 [待润色]。执行前会提示本版将写入 changelog 的条数及待润色条数。
三种输出¶
- 终端中文分组预览（默认）。
--md：幂等写入CHANGELOG.md（默认文件名，可用--changelog修改）；若已有该版本段则跳过；写入前自动备份为.bak。--json：机器可读输出，含 commit hash，便于追溯。
Web 面板¶
侧栏「深鲸版本说明」：填写路径 → 生成预览 → 一键写入 CHANGELOG.md。
安装与启用¶
DSH 要求：dsh 版本 >=0.1.0-rc.6 <0.3.0，Node >=18。本插件在 DSH 的 web profile 下安装；安装前请自行查看源码与 MIT 许可证，并知晓插件以当前 DSH 进程权限访问本地 Git 仓库。
官方安装命令如下：
dsh plugin --profile web add @deepwhale-cn/dsh-changelog
装好后侧栏会出现面板，命令行也可直接调用 dsh-changelog。
典型用法¶
命令行¶
在目标仓库路径上执行：
dsh-changelog /path/to/repo # 终端中文预览
dsh-changelog /path/to/repo --json # 机器可读（含 hash）
dsh-changelog /path/to/repo --md # 写进 CHANGELOG.md（幂等 + 备份）
dsh-changelog /path/to/repo --md --dry-run # 只看会写什么，不落盘
dsh-changelog /path/to/repo --map .changelog-map.json
退出码：0 正常，1 无有效提交，2 参数或 git 错误。可用 echo $? 检查。
常用参数：
--since <ref>：指定起始点。--version <v>：覆盖版本号。--tag-prefix <p>：修改 tag 前缀（默认v）。--changelog <file>：修改目标文件（默认CHANGELOG.md）。
润色映射文件¶
JSON 对象，key 越具体匹配优先级越高：
{
"feat(ui)": "支持深色模式",
"feat: 支持批量导入": "支持批量导入素材（最多 2000 个文件）",
"fix: 登录": "修复登录偶尔超时的问题",
"fix": "修复若干问题",
"perf": "长列表滚动更顺"
}
匹配优先级：整句 > type(scope) > type:关键词 > 任意关键词（最长优先）> 仅 type。未命中则原样保留并带 [待润色]。
适用场景与注意¶
适合谁： 团队已使用或愿意使用约定式提交，希望在发版前快速得到分组好的中文版本说明，并可选映射成用户可读文案的项目。
已知限制（以 README 为准）：
- 只读本地 git，不联网；没有对应 tag 时范围判断会受影响。
- 写入
CHANGELOG.md时只追加本版段落、插在一级标题之后（最新在上），不重排旧内容。 [待润色]会原样写入文件，发布前需通过--map或手工修改。- 不判断「这条改动是否值得对外」；提交信息不规范的条目可能落到「其他」。
社区目录页与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本介绍中的安装与用法均以仓库 README 与 package.json 为准。
链接¶
- 目录页：https://www.skillhub.cn/plugins/feely0208/dsh-changelog
- GitHub：https://github.com/feely0208/dsh-changelog
经过上面的步骤，你可以在本地 Git 历史与 package.json 版本的基础上，用一条命令或侧栏面板生成对外版本说明，减少发版前手工整理 CHANGELOG 的重复劳动。
