# Shuorenhua Skill

> 说人话.skill — 把难懂、别扭、不通顺的中文改成一读就懂的人话，意思一个字不变。双外脑改写：GPT-4o 和 Gemini（走 OpenRouter）各改一版，本地 agent 对照原文逐句查「意思有没有跑」，合成终稿；原文永远保留。两个固定时机：备料（写作素材先洗一遍）、出稿（交付前最后捋一遍）；也可以单独对任何一段文字用。首次使用需要用户配一个 OpenRouter key。 触发词：「说人话」「这段话看不懂」「帮我捋顺这段」「太绕了」「翻译成人话」「大白话讲一下」「备料清洗」「出稿前过一遍」「读不通」「翻译腔太重」。

- Skill: `swaylq/shuorenhua-skill` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add swaylq/shuorenhua-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swaylq/shuorenhua-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: swaylq (https://skillmd.com/u/swaylq)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/swaylq/shuorenhua-skill

---


# 说人话 · 双外脑中文改写

> 看不懂的话，让两个模型各说一遍人话，再对着原文裁判。意思不变是底线，流畅是目标。

## 核心理念

三条，全部来自实践：

1. **改写交给外脑，裁判留在本地。** 让 GPT-4o 和 Gemini 各改一版——两个模型的坏习惯不一样，一个改绕了另一个往往是直的。本地 agent 不动笔，只对照原文逐句检查意思、挑句子、合终稿。自己改自己查，查不出问题。
2. **原文永远不动、永远保留。** 改写附在原文后面，不覆盖。改砸了随时能退回去；两版都失败就明说失败，绝不输出改了一半的东西。（这条抄自 gvzdv/claudish-to-english：它给 Claude 的回复附一段大白话翻译，原文照旧。）
3. **意思不变优先于一切。** 数字、人名、术语、引文、结论，一个都不能变。改得再顺，意思跑了就是废稿。拿不准的地方保留原词，宁可难懂，不能编。

跟 MrGeDiao/shuorenhua（1.2k★ 的规则库路线）的区别：那个是给本地模型一套「AI 痕迹清单」照着自查，主攻去 AI 味；这个是把活儿外包给两个模型交叉改写，主攻「看不懂的话变成看得懂的」。两个可以叠着用。

## 三个入口

| 入口 | 什么时候 | 目标 | `--scene` |
|------|----------|------|-----------|
| **单独用** | 用户扔来一段看不懂的文字 | 读一遍就懂 | 不加 |
| **备料** | 写作前，素材本身难啃（采访转写、翻译腔文档、论文摘要、会议纪要） | 素材能直接用；信息一条不能丢 | `beiliao` |
| **出稿** | 成稿交付前 | 句子通顺；作者的观点、语气、结构不动 | `chugao` |

在任何写作流程里挂两刀：素材进来时过一遍备料，稿子出去前过一遍出稿。中间的创作不管。

## 执行流程

### 第 0 步 · key

引擎需要 OpenRouter key（一个 key 就能同时调 GPT-4o 和 Gemini）。先直接跑第 1 步，脚本自己会按顺序找：`--key-env` 指定的环境变量 → `OPENROUTER_API_KEY` → `~/.config/shuorenhua/key`。

退出码 2 = 没 key。这时停下来向用户要，话术照这个说：

> 需要一个 OpenRouter key（openrouter.ai/keys 免费注册就能领，按量付费）。**别把 key 贴进对话**——聊天记录会留底。请在终端里自己执行 `python3 tools/shuorenhua.py --save-key`（输入不回显，存到本机、权限 600），或者 `export OPENROUTER_API_KEY=…`，配好回我一声。

用户有凭据管理器（比如 `secret` CLI）的话优先走它：`secret exec 你的KEY名 -- python3 tools/shuorenhua.py 文件 --key-env 你的KEY名`。key 永远不进命令行参数、不进对话、不进日志。

### 第 1 步 · 双模型改写

```bash
python3 tools/shuorenhua.py 输入文件.md                 # 单独用
python3 tools/shuorenhua.py 素材.md --scene beiliao     # 备料
python3 tools/shuorenhua.py 稿子.md --scene chugao      # 出稿
echo "一段话" | python3 tools/shuorenhua.py -           # 管道也行
```

输出三段：原文、人话版 A（GPT-4o）、人话版 B（Gemini）。key 没余额（HTTP 402）时，`--models` 换成带 `:free` 后缀的免费档模型也能跑通全流程（名单在 `https://openrouter.ai/api/v1/models` 里搜 `:free`，中文改写推荐 minimax 系）。一个模型挂了就用剩下那版继续（终稿说明里提一句）；两个都挂，退出码 3，向用户如实报告，把原文原样还给用户，**不要自己顺手代写一版当作引擎结果**——本地也可以改，但要明说是本地改的。

档位（默认不加；用户明确要求时才用）：

| 档位 | 效果 |
|------|------|
| `--style tldr` | 太长不看：压成三五句话，只留主干 |
| `--style 5y` | 五岁版：日常词 + 生活比喻，省细节不改事实 |
| `--style caveman` | 原始人版：最短最钝的句子（彩蛋，致敬 claudish-to-english） |

### 第 2 步 · 裁判合稿（本地，不联网）

1. **先立事实清单，再读改写**：只看原文，列出每个数字和它描述的对象、人名/机构/产品、谁做了什么谁负责、时间与跨度、不确定语气与条件（可能/初步/若…）。先立账后对账，免得被顺畅的改写带着走。分类细则见 `references/protected-spans.md`。
2. **机械初筛**：`python3 tools/check_drift.py 原文 改写版`，两版各跑一次。数字丢失会直接非零退出，那版不能当底稿；标识符、引号内容、字数留存率只报警，逐段核对后放行或退回（tldr/5y 这类压缩档忽略留存率报警）。
3. **语义对账**：拿事实清单逐段核对两版。实测最常见的两种漂移机械筛不出来，全靠这步：谨慎语气被硬化（「这提示」变「这表明」）、术语被同义替换（「异质性」变「个体差异」）。
4. **合终稿**：选整体更顺的那版当底，把另一版更好的句子换进来；漂移点一律改回原文的意思。两版都不顺的句子才允许自己动笔重捋。
5. **丢了整句要报**：改写比原文少了整句或信息点、而你打算接受的，写进改动说明的「已删内容」清单交用户拍板，不许默认吞掉。
6. **过雷区**：终稿对照 `references/ai-qiang-checklist.md` 扫一遍，别把人话改成机器腔。改完自问一句：这段话念出来，像不像一个人在正常说话？

用户说「只标问题、别改」时，做完 1–3 就停：交事实清单、两版漂移记录和原文难读点列表，不出终稿。

### 第 3 步 · 交稿

输出顺序固定：

1. **终稿**
2. **改动说明**：三五条，说清楚改了哪类问题（长定语拆了几处、被动改主动几处、哪个漂移点改回去了）
3. **两个模型的原始版本 + 原文**：正文太长就写进文件附上，别省略——原文和两版是用户核对的依据

备料场景多做一步：把终稿存成新文件（如 `素材.renhua.md`），原文件不动。

## 边界

- **只处理中文**（输出一定是中文；夹杂的英文句子会被译成中文，术语保留）。
- 改写不是核查：原文事实错的，改完还是错的，发现明显硬伤可以在改动说明里提一句，但不改正文。
- 诗歌、法律条文、合同原文别用——这些文体「别扭」本身有含义，改顺了就变味或失效。
- 超过两三千字建议分段跑，一次塞两万字质量会掉（脚本会提醒）。

## 项目文件

- `prompts/rewrite.md` — 发给两个模型的完整提示词（脚本直接读它，改提示词只改这一个文件）
- `tools/shuorenhua.py` — 引擎，零依赖 Python
- `tools/check_drift.py` — 机械保真粗核（数字硬判，其余报警）
- `references/protected-spans.md` — 裁判立事实清单时的分类（学 MrGeDiao/shuorenhua）
- `references/ai-qiang-checklist.md` — 裁判用的中文机器腔雷区清单
- `references/design.md` — 为什么这么设计（含出处）
- `examples/` — 真实跑出来的前后对照
- `dist/shuorenhua-prompt.md` — 单文件版，没装 agent 时直接贴给 GPT-4o / Gemini 网页版用