Lry722/dsh-humanize

English | 简体中文

让推理模型专注干活，让交付内容好好说人话。

dsh-humanize 是一个面向 deepseek-harness 的插件，旨在解决编码特化模型在复杂任务中输出机器化黑话的问题。

---

为什么需要它？

编码特化模型能处理复杂工程推理，但输出的文字偏向机器化黑话。人类阅读这类文字要多花一份心思。

在主提示词里堆叠大量风格与修辞约束，会分散模型的推理注意力。复杂任务的效率随之下降。

---

核心构想

dsh-humanize 的核心理念是将逻辑推理与文风润色解耦：

• 按标记区分：在内容写入时，先区分纯代码或数据与面向人类阅读的内容。只有面向人类阅读的内容会触发写入审查。
• 风格约定：引入 PROSE.md，作为统一行文表达的标准。
• 逐条溯源：审查过程对照 PROSE.md 中的规范分点进行批注，定位表达不当之处。
• 延迟应用：审查在后台进行，主会话照常往下走，批注等用户需要时再合并。

---

安装

从 GitHub 安装：

dsh plugin --profile web add github:Lry722/dsh-humanize

本地开发时用 link 方式装载当前目录：

dsh plugin --profile web add link:/path/to/dsh-humanize

安装完成后重启 dsh 才会生效。

配置

在设置页的插件列表中找到 dsh-humanize，打开那一行的配置。设置页底部展示暂存批注和审查请求记录的实际保存位置，两条路径旁边都有复制按钮。下面这些参数改完之后立即生效：

• reviewProvider 与 reviewModel：审查用的模型，从宿主模型目录里下拉选择。默认跟随会话当前使用的模型。
• reviewReasoningEffort：审查模型的推理等级，从所选模型公布的等级里下拉选择。默认采用模型自身的默认值。
• mergeProvider 与 mergeModel：合并子代理用的模型，界面和审查模型一致。合并子代理包括 /humanize、/humanize-loop 和压缩触发的合并。默认跟随主会话当前使用的模型。两项必须成对填写，只填一项时整对跟随主会话。
• mergeReasoningEffort：合并子代理的推理等级，从所选模型公布的等级里下拉选择。默认跟随主会话当前使用的推理等级。
• reviewConcurrency：批次审查的并发数，最小值为 1，默认值为 3。
• reviewRetries：失败重试次数，最小值为 0，最大值为 3，默认值为 1。
• loopMaxRounds：循环合并的轮次上限，最小值为 1，最大值为 10，默认值为 3。
• mergeOnCompaction：上下文压缩结束时是否自动合并整个项目的暂存批注，默认值为 true。关掉这一项后，只在手动执行 /humanize 或 /humanize-loop 时合并。
• storageDir：暂存批注的保存位置，留空使用默认位置 ~/.dsh/humanize。

审查模型和合并子代理的模型下面各有一个测试按钮，发一条最小请求确认提供方、模型和推理等级能正常返回。模型选择留空表示跟随会话模型，两项都选好之后才能点测试按钮。

审查调用记录另存到系统临时目录，具体位置显示在设置页底部。审查结果解析失败时，模型的原始响应也写在调用记录旁边，便于排查时对照。

相对路径按进程工作目录解析。改动保存位置后，旧目录里的内容留在原处。

批次审查的并发数最多等于待审文件的数量。并发过高时可能触发模型提供方的速率限制。

触发速率限制的调用记为失败并重试。审查调用超时会被中止，这次审查按中止结束，不进入重试。其余失败每重试一次，间隔就比上一次长一点，超过重试次数记为失败。写入审查和批次审查共用这套重试。

批次审查结束后，会列出仍然失败的文件和原因，最多列出三条，其余只统计条数。写入审查连续失败时，任务列表会出现一条失败记录，提示检查审查模型的配置。

也可以在 profile 的 cordis.patch.yml 里为 dsh-humanize 条目传入同样的配置：

- id: dsh-humanize
  config:
    settings:
      reviewProvider: deepseek
      reviewModel: deepseek-chat

使用

在被审查文件的目录或上级目录放 PROSE.md 规范，用户全局规范放在 ~/.dsh/PROSE.md。多级目录的规范逐级叠加，范围越小的规范优先级越高。

PROSE.md 的文件头可以用 include 声明规范作用的文件范围，语法参考 .gitignore：

---
include:
  - '*.md'
  - 'docs/**/*.txt'
  - '!drafts/'
---

include 是整条规范链的属性。链里任何一级声明过 include，命中模式的文件才进入审查。写入审查和批次审查都按这个范围执行。整条链都没有 include 声明时，规范作用于所有文件。

图片、压缩包、字体和编译产物这类二进制文件跳过审查。判断取文件开头的样本，写入审查和批次审查都适用。批次审查的任务说明会报告跳过的文件数量。

模型写文件时必须声明 human_facing。面向人类阅读的内容传入 true，纯代码或数据传入 false。标记为 true 的写入会进入审查，其余写入跳过。程序化调用缺少这个字段时按 false 处理，并记一条警告。审查只看本次改动的区段。

同一文件的审查串行执行。不同会话或子代理的写入各自排队，待办按 agent 分开，互不覆盖。合并运行期间，发起合并的 agent 的审查让路。其他 agent 在这些目标文件上的审查同样让路。

批注暂存在 ~/.dsh/humanize/annotations/ 下。保存位置与被审查文件的路径一一对应。批注可以直接编辑。保存位置可以在设置页修改。

输入 /humanize 路径 合并指定文件或目录的批注。省略路径时使用当前工作目录。

批注合并在单独的上下文里进行。合并完成后，主会话会收到一份结果说明。

暂存文件中对应的批注随之清空。

插件随后会对刚改过的文件再跑一次审查，这次审查叫复审。复审产生的新批注同样留在暂存文件中。

合并结果写在主会话的结果说明里，复审结果写在任务行里。/humanize 和 /humanize-loop 复审失败时，任务以失败结束，不再判定为收敛，并在主会话补一条说明。

批注合并一开始，先中止正在运行的审查。排队中的审查直接丢弃，已经产出的批注也一并丢弃。其他会话在这些文件上的审查同样让路。

合并或复审期间遇到插件重载，这次运行到此结束。已经完成的合并照常清空暂存批注。未完成的合并保留暂存批注，重新执行命令即可继续。

输入 /humanize-loop 路径 循环执行批注合并与复审。每轮批注合并完成后，对刚合并过的文件逐个复审。复审产生的新批注进入下一轮批注合并。复审产出零条新批注或达到轮次上限时，循环结束。

批注合并的目标、轮次和待复审文件留在内存里。中途暂存的批注为空时，等复审跑完再判断是否还有新批注。同一时间只允许一条合并运行，跨会话也一样。

循环运行期间遇到插件重载时，这次运行到此结束。已经完成的合并照常清空暂存批注。未完成的合并保留暂存批注。

/humanize、/humanize-loop 和压缩触发的合并都会登记后台任务。循环合并的进度条显示当前是第几轮，以及本轮有多少条批注。

/humanize 和 /humanize-loop 的任务可以在任务列表里取消。循环合并的取消在下一轮开始前生效，已经完成的合并照常清空暂存批注。压缩触发的合并只报告结果，不能取消。

在 profile 里配置了 hmr 监听本插件目录时，改动本插件自己的源码会触发插件重载。重载会结束正在进行的合并运行，重新执行命令即可继续。

输入 /humanize-review 路径，派发一次批次审查。审查范围是项目中受 git 管理的文件。

审查在后台进行，显示为一个后台任务。进度条在输入框上方更新。会话头部的任务列表同样显示该任务。审查在单独的上下文里进行，读到的内容与会话本身分开。

目标目录需要是 git 仓库，并且仓库状态能正常读取。任一条件缺失时，任务以失败结束并给出原因。目标里没有可审查的文件时（没有受 git 管理，或不符合 include 模式），任务以完成结束，并提示没有可审查的文件。

提示词

发给模型的提示词都放在包的根目录 prompts/ 下，直接编辑即可：

• prompts/review-system.md：审查调用的 system 提示词，写入审查和批次审查共用。
• prompts/merge-request.md：派发合并子代理时发给它的用户消息，包含合并请求文件的路径。
• prompts/merge-header.md：合并消息开头的提示词，三种合并触发方式共用。
• prompts/human-facing-field.md：包装工具里 human_facing 字段的描述。

审查和合并每次调用都会重新读取对应的提示词文件。human_facing 字段的说明在注册包装工具时读取，改完后对新会话生效。