DeepSeek Harness 插件：dsh-pr-description

前言¶

DeepSeek Harness (DSH) 的理念是“一切皆插件”。在 DSH 社区中，代码评审类的插件已较为丰富，但针对 PR 描述的自动生成工具相对稀缺。dsh-pr-description 是 DSH 原生工具，定位为模型推理（Model Inference）开发辅助，它能分析当前分支的 diff，生成符合 Conventional Commits 规范的 PR 标题、描述和自审清单，解决开发者手动编写 PR 文档的痛点。

功能¶

插件通过 pr_describe 工具执行一个确定性的工作流，主要包含以下步骤：

确定范围：执行 git diff --name-status，对比当前分支与基线（base）的差异。
统计与归类：统计新增/修改/删除的文件数及行数，并根据文件扩展名和变更内容（如符号变更、关键词）将变更归类为 docs、test、chore、feat、fix 或 refactor。
提取符号：通过轻量级正则提取新增的函数、类或导出符号。
生成文本：拼装 Conventional Commits 标题（feat(scope): 动词短句）和五段式描述（动机/方案/影响/测试/风险），并生成自审清单。
输出与交互：将结果写入 PR_DESCRIPTION.md 并在会话内渲染。支持交互确认（confirm）和直接调用 gh CLI 提交 PR（openPr）。

安装与启用¶

插件通过 bundle patch 的方式挂载，安装后可直接使用。

dsh plugin --profile demo add ./dsh-pr-description

在 DSH 的配置文件 cordis.yml 中，插件会自动以裸包名 dsh-pr-description 挂载，指向 lib/index.js。

用法¶

会话内调用¶

在会话中直接调用 pr_describe 工具：

分析当前分支的改动，用 pr_describe 生成 PR 描述并确认后写入

工具参数¶

参数	类型	默认值	说明
`workdir`	string	配置 `workdir` 或进程 cwd	git 仓库目录
`base`	string	自动探测	对比基线，支持 `origin/HEAD` 等多种探测路径
`titleStyle`	string	`conventional`	标题风格，可选 `conventional` 或 `plain`
`confirm`	boolean	`false`	生成前 ask-user 交互确认，取消则不落盘
`openPr`	boolean	`false`	gh 可用时直接提 PR，不可用则跳过
`output`	string	`PR_DESCRIPTION.md`	输出文件路径（相对 workdir）
`locale`	string	`zh`	模板语言，支持 `zh` 或 `en`

插件配置¶

在 cordis.yml 中插入配置项：

- insert:
    - id: pr-describe
      name: 'dsh-pr-description'
      config:
        locale: 'zh'
        defaultTitleStyle: 'conventional'
        outputFile: 'PR_DESCRIPTION.md'
        defaultBase: ''        # 留空 = 自动探测
        workdir: ''            # 留空 = 进程 cwd

开发¶

本插件依赖 DeepSeek Harness 的源码检出，使用 link: 依赖指向相邻的 dsh-src。

开发者需要在同级目录检出官方 Harness 并构建：

# 在同级 dsh-src 目录执行
pnpm install && pnpm run build
# 回到本仓库执行
pnpm install --offline && pnpm build

测试命令包括离线冒烟测试和 E2E 测试：

node tests/smoke.offline.mjs
pnpm test:e2e
pnpm build

注意事项¶

确定性生成：当前版本的五段描述为确定性模板拼装，未调用 LLM 进行语义润色。如需更灵活的语义生成，需在生成后接入模型处理。
权限边界：插件需要读取面（git diff）、命令面（固定 argv，非 shell）、写面（写入 PR_DESCRIPTION.md）及外部服务（gh CLI）权限。所有命令执行采用固定 argv，不拼接 shell 字符串。
失败边界：当 diff 过大（DIFF_TOO_LARGE）、基线探测失败或分类规则收敛失败时，插件会返回结构化错误。
依赖前置：生产环境版本会尽量将 link: 依赖替换为 npm registry 真实版本。

总结¶

dsh-pr-description 为 DSH 开发者提供了一套标准化的 PR 描述生成流程。通过确定性规则而非大模型，保证了生成结果的可复现性和可控性，适合需要在 CI 或本地工作流中快速产出规范 PR 文档的场景。更多细节可查看 GitHub 仓库。