neuneed/dsh-shuorenhua

dsh-shuorenhua（说人话）

DeepSeek Harness 对话去 AI 味与大白话润色插件
一键过滤 AI 回答中的废话套话与公文黑话，让输出回归干净利落的大白话，代码与公式百分之百原样保真。

License: MIT
DeepSeek Harness
Listed on dsh-plugin.org

📖 简介

在日常使用大语言模型时，回答常常充斥着令人烦躁的固有模式：
- 废话寒暄：“好的，很高兴为您解答这个问题！针对您提到的...”
- 结尾套话：“希望以上内容对您有所帮助！如果您还有其他疑问，欢迎随时向我提问！”
- 公文八股与大词堆砌：“赋能业务逻辑”、“形成有效抓手与闭环”、“毋庸置疑标志着新范式”...
- 机械式三段论：无论问什么都要“首先... 其次... 再次... 综上所述...”。

dsh-shuorenhua 是为 DeepSeek Harness (DSH) 量身打造的全栈原生插件。它在每轮 AI 回答下方的操作条中无缝嵌入「💬 说人话」按钮。点击后，通过现代毛玻璃弹窗与实时打字机流式输出，将冗长套话快速提炼润色为通俗易懂的自然大白话，并提供字数精简统计与一键复制功能。

💡 面向开发者的进阶学习：
本项目也是开发 DSH 插件的标杆参考案例。如果你想向团队分享或学习 DSH 插件底层机制（生命周期、双端同体、WebServer SSE、UI 插槽等），请阅读专门编写的 👉 《dsh-shuorenhua 深度技术分享与插件原理》。

✨ 核心特性

- 🎯 无缝嵌入：原生注入 DSH Web 聊天操作条（复制与分支按钮之间，order: 12），浑然一体。
- ⚡ 实时打字机流式：直接复用 DSH 宿主配置的底层 LLM，点击弹窗即刻开始逐字流式打字机渲染，无需漫长等待。
- ✂️ 深度去 AI 味（对标 MrGeDiao/shuorenhua 标准）：
- 去名词化（动词还原）：将“完成了对重试策略的调整”重构为“调整了重试策略”，消灭公文官腔与欧化完成时机器翻译腔；
- 剔除车轱辘话与完全重复：自动切除前后语义 100% 重叠的复述句（如前文已叙述调整，后文复述“重试策略已经调整过了”）；
- 行文标记词剔除：直接清理“简而言之”、“值得注意的是”、“综上所述”、“总而言之”等无效行文包装。
- 🛡️ 代码公式与技术指标绝对保真：
- 采用占位符保护伞算法，代码块 (  - 数据与核心事实绝对保真，严禁擅自抽象概括（严禁将“从 24 次降到 7 次”改成含糊的“大幅改善”）。
- 🪟 现代毛玻璃弹窗：遵循 Apple 极简美学设计，提供深浅双色自适应主题，直观呈现精简字数对比与优化比例。
- 📋 快捷退出与复制：支持一键将润色结果写入剪贴板；支持按下键盘 ESC 键或点击遮罩外部任意位置秒退。
- 🤖 双模可用 & 双轨容灾：
- 用户交互模式 (Web UI)：前端点选操作；
- 智能体模式 (Agent Tool)：向自主智能体注册 shuorenhua_simplify 工具，采用 “LLM 智能流式生成优先 + 离线增强规则引擎兜底” 机制，无论宿主是否配置大模型，均能顺畅改写，告别 savedPercentage: 0 假死。
- 💾 润色结果本地缓存：每条消息的润色结果持久化在 Host 存储（ctx.storageDomain，storage-json/sqlite），再次点开同一消息直接显示上次结果，零重复 API 调用，节省模型额度。
- 🔌 零额外网络端口：完全复用 DSH 既有的 WebServer，同源无跨域，无需开启多余端口或进程。

🧠 润色哲学与改写标准

本项目深度吸收了社区优秀项目（MrGeDiao/shuorenhua、op7418/Humanizer-zh、nothing0here/humanizer-zh）的改写精髓：

| 维度 | AI 常见机器味 / 公文腔 | “说人话”改写后 |
| :--- | :--- | :--- |
| 去名词化（动词还原） | 本次完成了对重试策略的调整。 | 本次调整了重试策略。 |
| 去车轱辘话（切除循环复述） | 本次调整了重试策略。重试策略已经调整过了。重复请求从 24 次降到 7 次。 | 本次调整了重试策略，重复请求从 24 次降到 7 次。 |
| 去行文包装语 | 值得注意的是，本轮调整了重试策略。简而言之，重试策略已经调整过了。 | 本轮调整了重试策略。 |
| 技术指标绝对保真 | 失败请求数从 24 次降到 7 次。 | 失败请求数从 24 次降到 7 次。（严禁改成“请求更稳定了”或乱算百分比） |
| 事实抽象度不篡改 | 这一方法充分展现了分层设计的潜力，有望改善模块协作。 | 这一方法充分展现了分层设计的潜力，有望改善模块协作。（不脑补未发生的成果） |

🖥️ 交互与效果演示

1. 按钮位置
在每条 AI 回答气泡下方的操作栏中：
┌────────────────────────────────────────────────────────┐
│  AI 回答文本内容...                                    │
│                                                        │
│  [📋 复制]  [💬 说人话]  [🔀 分支]  [⏱ 耗时]            │
└────────────────────────────────────────────────────────┘

2. 点击后弹窗效果
点击「💬 说人话」后，居中弹出毛玻璃对话框：
┌────────────────────────────────────────────────────────┐
│  💬 说人话润色                        已精简 38%  [✕]   │
├────────────────────────────────────────────────────────┤
│                                                        │
│  经过润色后的大白话内容（实时打字机逐字输出中...）▍     │
│                                                        │
├────────────────────────────────────────────────────────┤
│  原字数: 320 字 ──> 润色后: 198 字      [📋 一键复制]   │
└────────────────────────────────────────────────────────┘

🚀 快速上手

方式一：从 GitHub 一键安装（用户首选）
如果你已经在系统中使用 dsh CLI，无需手动编译，一条命令直接安装：bash
一键安装到 Web profile 中
dsh plugin --profile web add github:neuneed/dsh-shuorenhua

启动 DSH Web
dsh web
也可在 DSH Web 侧边栏的【插件 (Plugin)】管理页，直接输入 github:neuneed/dsh-shuorenhua 图标化安装。

方式二：本地源码开发与调试（开发者模式）

1. 编译构建bash
git clone https://github.com/neuneed/dsh-shuorenhua.git
cd dsh-shuorenhua

安装依赖
pnpm install

运行完整检查（含类型检查、12项单测、双端打包）
pnpm run check

2. 软链接至 DSH 运行环境bash
mkdir -p ~/.dsh/profiles/web/node_modules
ln -s "$(pwd)" ~/.dsh/profiles/web/node_modules/dsh-shuorenhua

3. 启动并测试bash
通过 --patch 参数加载插件
pnpm dsh web --patch cordis.patch.yml

⚙️ 插件配置

在 cordis.patch.yml 中支持配置以下选项：
yaml
- insert:
- id: dsh-shuorenhua
name: dsh-shuorenhua
config:
可选：指定模型提供商（缺省时自动使用 DSH 当前激活的默认主模型）
provider: deepseek-official
可选：指定模型名称（缺省时自动使用当前主模型）
model: deepseek-chat
可选：是否向 Agent 注册 shuorenhua_simplify 工具（默认 true）
enableTool: true
可选：是否持久化每条消息的润色结果，重开同一消息直接显示、不再调模型（默认 true）
enableCache: true
可选：缓存条数上限（LRU 逐出，默认 100）
cacheMaxEntries: 100

🏗️ 架构概览

本项目采用典型的 DSH 双端同体微内核架构：

┌─────────────────────────┐
│      dsh-shuorenhua     │
└────────────┬────────────┘
│
┌─────────────────────┴─────────────────────┐
▼                                           ▼
┌───────────────────────┐                   ┌───────────────────────┐
│   Host 宿主端 (Node)  │                   │  Client 浏览器端 (Web) │
├───────────────────────┤   POST SSE 流式   ├───────────────────────┤
│ • ctx.llm (大模型调用) │ <════════════════ │ • assistant-actions   │
│ • /shuorenhua/stream  │   (同端口 3080)   │   操作栏插槽注入      │
│ • Agent Tools 注册    │                   │ • 打字机流式毛玻璃弹窗 │
│ • Typert RPC 回退服务 │                   │ • 中英多语言文案字典  │
└───────────────────────┘                   └───────────────────────┘

- Host 端 (src/runtime.ts)：提供底层数据服务，注入润色专用 System Prompt，调度宿主模型流式输出，并挂载同端口 SSE 路由；
- Client 端 (src/client/)：通过 DSH ctx.slots 机制声明式注入操作栏按钮，消费 SSE 响应流并完成打字机渲染。

📚 深度开发文档

想要向团队分享或深入掌握 DSH 插件开发的核心技术？请参阅技术专题文档：
- 📖 dsh-shuorenhua 深度技术分享与插件原理
- DSH 全插件微内核原理与 Cordis 架构
- 与 VSCode / Chrome / Webpack 插件的本质差异
- Fiber 生命周期状态机与 Effect 副作用管理（为何不能直接注册）
- 注册机制避坑：硬依赖 inject、动态 ctx.inject 与安全探测 ctx.get
- 同端口 SSE 流式通信与断连处理
- UI 插槽机制与响应式消息上下文获取
- 从零开发 DSH 插件的标准工程规范与打包全景

📄 开源协议

本项目采用 MIT License 授权。