dsh-shuorenhua

Readme

# dsh-shuorenhua (说人话)

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![DeepSeek Harness](https://img.shields.io/badge/DSH-Plugin-success.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/neuneed/dsh-shuorenhua)
---

## 📖 简介

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

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

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

---

## ✨ 核心特性

- 🎯 **无缝嵌入**：原生注入 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](https://github.com/MrGeDiao/shuorenhua)、[op7418/Humanizer-zh](https://github.com/op7418/Humanizer-zh)、[nothing0here/humanizer-zh](https://github.com/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 深度技术分享与插件原理](./docs/technical-sharing.md)**
  - DSH 全插件微内核原理与 Cordis 架构
  - 与 VSCode / Chrome / Webpack 插件的本质差异
  - Fiber 生命周期状态机与 Effect 副作用管理（为何不能直接注册）
  - 注册机制避坑：硬依赖 `inject`、动态 `ctx.inject` 与安全探测 `ctx.get`
  - 同端口 SSE 流式通信与断连处理
  - UI 插槽机制与响应式消息上下文获取
  - 从零开发 DSH 插件的标准工程规范与打包全景

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 授权。