前言¶

发版或写 Release 说明时，常见做法是手工翻 git log、按类型归类，再润色成中文。模型生成的摘要容易混入未在仓库里出现过的表述；提交信息若是英文，直接翻译又可能偏离原文。DeepSeek Harness（DSH）把能力拆成可挂载的插件；社区目录在 SkillHub 上独立维护，与 DeepSeek / 幻方无官方从属关系。下面介绍维护者 dingchenhui0618-arch 的 dsh-changelog-zh（当前版本 0.1.0，MIT 许可证）：只读 git 历史（可选叠加会话记录），产出两份中文变更日志，并在每条变更上标注 commit SHA 与「已验证／未验证」。

这是什么¶

dsh-changelog-zh 从真实 git 历史生成两份中文变更日志：

• 用户版（短）：适合贴进群公告或 Release 正文；
• 开发者版（长）：每条提交带完整 SHA、分类依据、文件增减、验证证据原文。

工具不联网、不调用模型 API；除只读 git 外不执行其他进程；默认不改仓库（不发提交、不打标签、不写 notes）。CLI 仅在指定 --out 时写入文件。

三个设计约束¶

README 将其归纳为三条承诺：

1. 只说历史里有的事。 分类依赖约定式提交前缀和一张小关键词表；识别不出则写「未分类」，不猜测。
2. 「已验证」必须有可引用证据。 四类证据之外一律标「未验证」，并说明缺哪一类；仅有 verified: true 而无证据同样算未验证。
3. 不翻译提交信息。 未提供中文标题的提交原样保留主题，并统计「有 N 条没有中文标题」。

「未验证」只表示提交历史里没有可引用的验证证据，不代表改动有问题；用户版页脚会说明这一点。

已验证／未验证如何判定¶

只有下列四类可引用证据存在时标「已验证」：

trailer 键名支持中英多种写法（如 Verified、已验证、测试 等，大小写不敏感）。从严规则包括：同一提交若既有通过证据又有失败验证记录，按未验证处理；会话里只有 "verified": true 而无命令／退出码／计数，标为「声称已验证但没有证据」。匹配到会话记录本身不等于已验证。

核心能力概览¶

• 双格式输出：format 可取 user、dev、both。
• 自动范围：无标签时取最近提交；有标签时取 最近标签..HEAD；若最新标签已在 HEAD 上，回退到上一个标签，避免重复已发布提交。
• 会话记录叠加：支持 JSON 数组、单个 JSON 对象或 JSONL；commit 可用完整 sha、唯一前缀（≥4 位）或短 sha，有歧义则列入歧义清单而不猜测。
• 中文标题来源：--titles 映射优先，其次会话里的 title / titleZh / summary，高于提交 trailer。
• 脱敏：渲染前替换 GitHub token、sk- 类 key、JWT、私钥块、带密码连接串、本机用户路径等，并在文案中报告隐去数量。

合并提交默认不进入日志；需要时 CLI 加 --merges。

安装与启用¶

本插件为零依赖纯 JS 包，通过 package.json 中的 dsh.bundle.patch 与 dsh.client 声明接入；将仓库挂入 DSH 插件目录即可。仓库自带 cordis.patch.yml，片段示例如下：

# cordis.patch.yml（本仓库自带）
- insert:
    - id: dsh-changelog-zh
      name: dsh-changelog-zh

装上以后有三个入口：

• 会话面板：对话视图「变更日志」标签页，填写仓库／范围／会话记录即可生成，可一键复制；
• HTTP 路由：GET /dsh-changelog-zh/state、POST /dsh-changelog-zh/generate、POST /dsh-changelog-zh/clear；
• 工具：changelog_zh，参数 { repo, range, since, limit, includeMerges, sessions, format }。

插件配置（均可选）：

{
  "roots": [],
  "defaultRepo": "",
  "defaultRange": "",
  "sessionsPath": "",
  "titlesPath": "",
  "maxCommits": 300
}

roots 非空时仅允许生成白名单路径下的仓库。插件在 DSH 进程权限下运行，安装前请自行审阅源码与 MIT 许可证。

运行环境：Node ≥ 22 与本机 git（零运行时依赖）。

典型用法¶

命令行¶

在仓库根目录或指定 --repo 生成两份 Markdown：

$ node bin/changelog-zh.mjs --repo D:\Projects\某项目 --title v1.1.0
已写入 D:\Projects\某项目\CHANGELOG-user.md  —— 用户版（短）
已写入 D:\Projects\某项目\CHANGELOG-dev.md  —— 开发者版（长）
范围 v1.0.0..HEAD · 6 条提交 · 已验证 3 · 未验证 3 · 已隐去 0 处 · 会话记录匹配 2 条

常用参数包括 --range（如 v1.0.0..HEAD）、--since、--limit（默认 300，上限 5000）、--sessions、--titles、--format user|dev|both、--stdout、--json、--no-authors / --no-emails。退出码：0 成功、2 参数错误、1 生成失败。

演示仓库上的用户版输出示例（README 原文）：

$ node bin/changelog-zh.mjs --repo tmp/demo-repo \
    --sessions tmp/demo-sessions.jsonl --title v1.1.0 \
    --out tmp/demo-out --no-emails --stdout --format user

会话记录片段¶

会话文件为约定摘要格式，非 DSH 内部会话库格式：

{"commit":"182d11c","title":"支持把结果导出成 Markdown","commands":[{"command":"node --test","exitCode":0},{"command":"npm run lint"}],"tests":{"passed":46,"failed":0}}
{"commit":"af2971a","verification":{"command":"node --test","exitCode":0,"evidence":"46 passed"}}

DSH 工具调用¶

在智能体或自动化流程中可调用工具 changelog_zh，传入 repo、range、format 等字段，与面板、HTTP 路由共用同一套生成逻辑。

适用场景与注意¶

适合：需要基于真实 git log 写中文版 Release／群公告，且希望每条变更有 SHA、分类与验证状态可追溯；愿意用 trailer、git notes 或 JSONL 会话记录留下验证证据的团队。

不适合：期望自动翻译全部英文提交、或由工具推断「大概测过了」的场景——本插件明确不做翻译与推断。

生态对照（依据各仓库公开描述，非穷尽调研）：7dgroup-ai/dsh-skill-7d-git-commit 侧重提交信息规范校验（写提交之前）；andyfan1094/dsh-github 侧重 GitHub 认证与本地 Git 工作流。两者不产出「从真实变更生成可公开的中文文案」；本插件补的是发版说明这一环。

作者说明未在自有 DSH 配置中跑过面板截图，面板行为由 test/host.test.mjs 等契约测试覆盖。

链接¶

• 社区目录：dingchenhui0618-arch/dsh-changelog-zh
• 源码与完整说明：GitHub — dingchenhui0618-arch/dsh-changelog-zh