第一次在 Agent 的技能清单里看到 Humanizer 这个名字，我以为是某种"拟人化人格"插件，点进去才发现完全不是——它干的是把机器写出来的文字，改回人写的样子。这件事听起来很小，实际做过内容流水线的人都知道它有多麻烦：模型生成的稿子语法没错、逻辑也通，但读三行就能闻出那股味道，虚词堆得密、句式长度整齐得像用尺子量过、每段结尾都要升华一句。Humanizer 就是把这套"去味"工作固化成一个可复用、可测试、可被 Agent 自动调用的技能。这篇东西写给两类人：一类是已经在搭 Agent 工作流、想给输出质量加一道闸的开发者；另一类是天天要交付文案、被"一眼AI味"折磨的内容从业者。下面从它是什么、内部怎么运转、怎么装、怎么用、怎么踩坑，一路讲到怎么验收。

1. Humanizer 到底在解决什么问题：从"一眼AI味"说起

1.1 为什么"写得更自然"这件事必须做成一个技能

绝大多数人的第一反应是写一段提示词："请用自然、口语化的语言重写，避免套话"。这句话本身没错,问题在于它不可维护。风格约束不是三条五条能说清的，它是一份长尾清单：哪些词是高频套话、哪些句式是典型机器指纹、段落长度该怎么分布、连接词该用多少、什么时候允许句子不完整。这份清单少说四五十条，全塞进系统提示词里，每次对话都要占掉一大块上下文，而且改一条就得动整个提示词，没法单独测试。

做成技能就不一样了。技能的本质是"按需加载的能力包"：平时不占上下文，Agent 判断当前任务需要润色文字时才把它读进来；规则以独立文件形式存在，改某一类规则只动一个文件；还能挂脚本，把"词表扫描""句长统计"这种机械活交给代码做，模型只负责需要判断力的部分。我在两个内容项目里对比过，同样的规则集，写成提示词版本和维护成技能版本，前者三个月后基本没人敢改，后者加规则像加词条一样简单。

还有一个更实际的理由：可测试。提示词版本你没法回归测试，改了一句话不知道会影响哪些场景；技能版本可以挂一组固定的样例文本，每次改规则跑一遍，看命中数和保留率有没有退化。这一点在后面第 7 节会详细讲。

1.2 能力边界：它能改什么，不能改什么

把边界划清楚比把功能做全更重要，因为越界的改写是最容易出事故的地方。

它擅长改的东西：句式节奏（把连续的二十字长句拆成短句混排）、虚词密度（"值得注意""综上所述""不仅而且"这类）、连接方式（用口语连接替代"首先其次最后"）、段落切分（一段塞五种意思的拆成两段）、语气（书面语往口语靠一点）、重复表达（同一个意思换着说三遍的删掉两遍）。

它绝对不能碰的东西：数字、单位、日期、条件状语、否定词、专有名词、代码片段、引用原文、结论性判断。这几类东西一旦被"顺手润色"，事故等级直接从排版问题升到事实错误。我在规则文件里把这一条写成硬红线，并且用脚本做二次校验——数字必须在改写前后完全一致，不一致就整段回退。

它做不到的事：凭空补细节。有些人指望 Humanizer 把干巴巴的段落写得血肉丰满，这属于内容生成，不是风格改写。硬要它补，结果只能是编造案例，这在任何场景下都不可接受。技能里我明确写了"禁止新增原文不存在的事实、数据、案例、引语"，这条比任何风格规则优先级都高。

2. 拆开看：Humanizer 技能包的文件结构与规则内核

2.1 一个能跑起来的技能目录长什么样

技能包的结构不用复杂，但分层要清楚，否则规则一多就成一锅粥。我用的目录形态大致是这样：

skills/ └── humanizer/ ├── SKILL.md # 技能说明与触发条件 ├── rules/ │ ├── 01-hard.yaml # 硬红线：不可改动项 │ ├── 02-lexicon.yaml # 词表：套话、虚词、滥用连接词 │ ├── 03-pattern.yaml # 句式指纹：正则与结构模板 │ ├── 04-rhythm.yaml # 节奏：句长、段长、重复度 │ └── 05-voice.yaml # 语气：按场景切换的口吻包 ├── scripts/ │ ├── detect.py # 扫描命中项，输出问题清单 │ └── verify.py # 改写后一致性校验 └── tests/ ├── cases/ # 固定样例文本 └── baseline.json # 基线指标

关键在编号前缀。规则文件按 01 到 05 排序，意味着执行顺序固定：先确认哪些不能动，再查词，再查句式，再调节奏,最后调语气。顺序反过来会出问题——先调语气再查词表，语气改写引入的新虚词就漏检了。

SKILL.md里我一般只放三样东西：技能干什么、什么时候该用、读哪些文件。不把具体规则抄进去，规则永远只在 rules 目录里维护一份，避免双份维护导致不一致。

2.2 三层规则：硬性词表、句式指纹、结构节奏

规则不是平铺的一堆词，按性质分三层，处理方式完全不同。

第一层，词表命中。这一层最机械，也最容易见效。典型条目包括：总结类虚词（"综上所述""总而言之""总的来说"）、强调类（"值得注意的是""需要指出的是"）、时代开篇（"在当今这个……的时代"）、万能动词（"赋能""助力""打造""构建"）、三段式连接（"首先/其次/最后"连用）。这一层可以直接用字符串匹配做，命中就给替换建议。词表的好处是明确、可数、可量化，坏处是容易过拟合——把"构建"全禁了，写技术文档时会很难受。所以要配一个白名单，允许在特定场景下保留。

第二层，句式指纹。这一层用正则和结构规则描述，比词表抽象一档。常见的几条："不是A，而是B"连续出现两次以上；破折号插入语一篇文章超过三处；同一段落里三个并列短语字数高度接近（一眼排比）；每段首句都是概括句、末句都是升华句的"三明治结构"；形容词连续堆叠超过四个。这一层靠模型判断更靠谱，脚本只负责标出可疑位置。

第三层，节奏指标。这一层不针对具体词句，看的是整体统计特征。人类写的段落，句长方差大，有长句也有五字短句；机器写的段落，句长集中在某个区间，方差小。段长也一样。还有重复度：同一个信息点在不同段落被复述的次数。这些指标用脚本算，给出数字，模型据此决定要不要打散重排。

三层各管一段，词表管"显性痕迹"，句式管"隐性模板"，节奏管"整体观感"。只做第一层，改完还是像机器写的；三层都做，效果才明显。

2.3 改写循环：检测、重写、复核的三段式

Humanizer 不是一个"一步到位"的改写器，它是循环。流程固定为三步：

第一步，detect.py扫描原文，输出一份问题清单，格式大致是每条命中带位置、类型、严重度。严重度分三级：block（硬红线，比如要改数字）、warn（明显痕迹）、hint（可选优化）。

第二步，模型拿着问题清单做定点改写，而不是整篇重写。这一点很关键——整篇重写每次结果都不一样，而且容易丢信息。定点改写只动被标记的句子，其余部分原样保留，可控性高得多。

第三步，verify.py做一致性校验：数字集合是否一致、专有名词是否保留了、引用块是否完整、改写比例是否超过阈值。校验不通过就把这一段回退，标记为"需人工处理"，而不是硬改。

循环最多跑两轮。跑三轮以上，文字会越来越碎，风格越来越飘，最后连原意都变形。这个上限我试过几次不同设置，两轮是最稳的。

3. 安装与接入：把 Humanizer 挂到你的 Agent 上

3.1 目录式安装与清单文件写法

大多数支持技能机制的 Agent 框架，安装方式都是"把目录放到约定位置"。有两种放法：项目级放在工作目录下的skills/，跟着项目走，适合每个项目规则不同的情况；用户级放在用户主目录的配置区，全局可用，适合规则统一的情况。我的习惯是规则主体放用户级，项目特有的补充规则放项目级，加载时合并，项目级优先。

清单文件的写法决定了技能能不能被正确调用。我用的模板长这样：

--- name: humanizer version: 1.3.0 description: > 文本去机器味改写技能。当任务涉及"润色、改写、去AI味、口语化、 让文字更自然、去掉套话、调整语气"时加载。适用于中文长文、技术文档、 客服话术、营销文案的二次加工。不适用于：从零生成内容、翻译、 代码重构、需要保持严格公文格式的文本。 --- # Humanizer ## 何时使用 - 用户明确要求改写、润色、去模板化 - 输出交付前需要过一道风格检查 - 同一批文本需要统一口吻 ## 执行顺序 1. 读取 rules/01-hard.yaml，锁定不可改动项 2. 运行 scripts/detect.py，获取问题清单 3. 按严重度从高到低定点改写，不整篇重写 4. 运行 scripts/verify.py 校验一致性 5. 校验失败则回退该段并标注原因 ## 硬约束 - 不新增原文不存在的事实、数据、案例 - 数字、日期、否定词、专有名词原样保留 - 单段改写比例不超过 40%

注意description这一段是全篇最重要的部分，它不是给人看的介绍，是给 Agent 判断"要不要加载我"用的。写得含糊，技能就永远不会被调用。

3.2 触发描述怎么写才不会"该用的时候不调用"

这是我踩过的第一个大坑。最初description写的是"一个提升文本自然度的技能"，结果跑了二十次任务，一次都没被触发。原因很简单：Agent 的任务描述里不会出现"提升文本自然度"这种词，用户说的是"这段太像AI写的了，帮我改改"。

修法是把触发词写成用户实际会说的口语，尽量穷举。我后来的写法是把触发词分三组：

排除项比触发项还重要。没有排除项，技能会在不该用的时候乱入，把一份需要严格格式的说明文改成聊天口吻，返工成本比不做还高。

还有个细节：description里不要写太多技术术语。Agent 判断触发靠的是语义匹配，用户说的话越口语，描述里就越该用口语词对应。

3.3 依赖与运行环境：脚本、字典、评分器三样东西

技能要用起来，除了目录和清单，还得准备三样东西。

脚本运行环境。detect.py和verify.py我都是用 Python 写的，只依赖标准库加一个 YAML 解析库。刻意不引入重依赖，因为技能会被不同环境加载，依赖越少越不容易在别人机器上炸。脚本入口统一接受文件路径和--json参数，输出结构化结果，方便 Agent 解析。

词表字典。词表不是写完就完事的，它需要持续扩充。我的做法是建一个"候选池"文件，平时读文章遇到新的机器味表达就往里记，每周筛一次并入正式词表。词表条目建议带三个字段：词本身、替换建议、适用场景白名单。比如"构建"这个词，在技术文档里是正常用词，在营销文案里就是套话，白名单字段能避免一刀切。

评分基线。至少要有一组固定样例和一份基线指标。样例不用多，十到二十段足够，覆盖长文、短文案、技术文档、口语化内容四类。基线指标包括词表命中密度、句长标准差、改写比例。没有基线，你根本不知道这次改规则是变好了还是变坏了。

4. 使用方法：四种调用姿势与参数配置

4.1 单段改写：最小可用调用

最简单的用法是直接给一段文字。调用时只需要两个信息：待改文本、场景标签。场景标签决定加载哪套语气规则，不给的话默认按"通用书面语"处理。

实际交互大概是这样：

{ "skill": "humanizer", "input": "（待改写的原文）", "params": { "scene": "tech_doc", "intensity": 2, "preserve": ["API 名称", "版本号", "错误码"], "max_edit_ratio": 0.4 } }

返回结果我要求包含三部分：改写后的文本、改动说明（哪句改了什么类型）、未处理项（哪些标了但因为风险没动）。第三部分经常被忽略，但它很重要——它告诉你哪些地方模型不敢动，往往就是需要人工过一眼的地方。

第一次用建议intensity设 1，看看改动幅度是否可接受，再往上调。直接从 3 开始，大概率改得你认不出原文。

4.2 批量处理：文件级与目录级流水线

批量场景要的是稳定和可追溯，不是单篇效果最大化。我的流水线是这样跑的：

1. 目录扫描，收集所有.md文件，跳过node_modules、.git之类的目录
2. 逐个文件跑detect.py，把结果汇总成一张问题总表，先看整体分布——如果某个词在八十个文件里出现六百次，那说明它是模板化写作的根因，值得单独处理
3. 按严重度排序，先处理block级，再处理warn级
4. 每处理完一个文件就落盘一次，同时写一份.humanizer.log记录改动，方便回滚
5. 全部跑完后统一跑verify.py，输出一份校验报告

批量的坑在于"一改全改"。有次我调了一条规则，一次跑完两百多个文件，结果发现某个术语被全量替换，改回来花了半小时。后来加了--dry-run参数，先输出改动预览不动文件，确认没问题再实跑。

4.3 嵌入工作流：写作、润色、复核三阶段分离

把 Humanizer 塞进写作流水线时，最容易犯的错是让它和生成步骤混在一起。正确做法是三段分离：

生成阶段只负责把内容写出来，不管风格，允许它写得啰嗦、模板化。这时候追求的是信息完整。

润色阶段调 Humanizer，拿着生成阶段的稿子做定点改写，只动被标记的句子。

复核阶段再调一次verify.py加人工抽检，确认事实没变、术语没换、逻辑没断。

三段分离的好处是每一步都可单独调优。生成阶段写得太干，你去调生成提示词；润色阶段改过头，你去调intensity和规则阈值；复核阶段老出问题，说明校验脚本漏了某类检查项。混在一起你就分不清是哪一步的问题。

4.4 关键参数表：强度、保留项、禁用词

参数不多，但每一个都会显著影响结果，值得单独列一下。

intensity和max_edit_ratio是有联动的：intensity设 3 但max_edit_ratio只有 0.2，模型会在小范围内反复折腾同一句，越改越别扭。两者大体保持同向调整，强度高时改动比例也要放开。

5. 案例应用：三个真实场景的落地拆解

5.1 技术文档的口语化改写

技术文档是最考验分寸的场景。改得太保守，机器味还在；改得太狠，专业性和严肃感全丢。

我处理过一份内部接口说明，原文的典型问题是：每段都用"本接口用于……"开头，中间用"首先/其次/然后"串流程，结尾统一"综上所述，本接口具备以下优势"。改的时候按三步走。

第一步，锁定硬约束。接口名、参数名、错误码、返回示例全部进preserve列表，脚本层面做校验。这一步不做，后面所有工作都是白费。

第二步，处理结构。把"本接口用于"开头改成直接说场景，比如"调用方需要拉取分页数据时用这个接口"。把"首先/其次/然后"换成动作之间的自然衔接，比如"先拿 token，再拿列表，最后按需补详情"。结论段整段删掉——技术文档不需要升华。

第三步，调节奏。原文每句都是二十五到三十字，读起来像在念说明书。改成短句和长句交错，关键操作单独成句。intensity用 2，max_edit_ratio控制在 0.3。

改完之后，一位同事的评价是"像人写的了，但没变得不专业"。这个平衡点就是技术文档的目标。

5.2 客服话术的去模板化

客服场景的机器味来源和文档完全不同。文档是句式太整齐，客服话术是"共情模板"用滥了："非常理解您的心情""给您带来不便深表歉意""感谢您的耐心等待"。这些话本身没错，问题是每一条回复都用，用户一眼就知道是复制粘贴。

改这个场景，词表是第一生产力。我整理了一份客服高频模板句清单，大概四十条，逐条给替换方案。替换原则不是"别说抱歉"，而是"道歉要具体"：把"给您带来不便深表歉意"换成"这个确实是我们这边没处理好，您多等了两天"。具体的道歉比笼统的道歉更有信息量，也更像真人说话。

还有一个改动是删掉过度共情。真人客服不会每句话前面都加一句"理解您的心情",通常是在关键节点说一次。改成"开头说一次、结尾说一次，中间直接说事"之后，整段回复短了三分之一，用户满意度反馈反而更好。

这个场景intensity可以开高一点，用 3，max_edit_ratio放开到 0.45，因为话术本身就没什么硬信息，可改空间大。但订单号、金额、时效承诺这些必须进preserve，一个字都不能动。

5.3 长文的结构重排与节奏打散

长文是最难的一类，因为问题不在句子，在整体架构。典型症状是：每段开头一句概括、中间三点展开、结尾一句总结，四十段全是这个模子。单看每段都合格，连起来读就是灾难。

处理这类稿子，得先看统计再看句子。我一般先跑一遍指标：段落长度分布、句长方差、段落首句的句式相似度。有一次跑出来首句相似度 0.72，意思是七成段落的开头用了同一种句式结构，这种稿子光改词没用，必须动结构。

重排的原则是：拆掉一部分"总—分—总"结构，让某些段落直接从细节切入；把连续三个同长度的段落打散，插入一段短的；把每段末尾的升华句删掉一大半，只在真正需要停顿的地方留一句。

这一步有个风险：keep_structure设成 false 后，模型可能把段落顺序也调了，导致上下文断裂。我的处理是分两步走——先只改句子不动顺序，跑一遍；再单独做结构调整，人工确认顺序没问题。一次改到底，出事概率太高。

6. 踩坑实录：过度改写、语义漂移与风格坍塌

6.1 语义漂移：改完之后数字和条件全乱了

这是我遇到最严重的一次。一份带条件的说明文字，原文是"连续三次失败后触发熔断"，改写后变成了"多次失败后会触发熔断"。"连续三次"这个关键条件被当成啰嗦表达优化掉了。

事后复盘，问题出在两处。一是硬约束文件里只写了"数字不可改"，没写"数量词、频次词、条件连词不可改"；二是verify.py只校验了阿拉伯数字，没校验中文数词。

修法有三条。第一，硬约束扩展到一整类：数量词、频次词、条件词（如果/除非/仅当/至少/不超过）、否定词（不/无/未/禁止）、时间状语。第二，校验脚本加一条规则：原文出现的所有数字（含中文数词）必须在改写后完全一致，集合比对，缺一个就报错。第三，给这类句子加保护标记，命中保护规则的句子直接跳过改写。

verify.py的核心逻辑大概是这样：

import re CN_NUM = "零一二三四五六七八九十百千万两半" def extract_numbers(text): patterns = [ r"\d+(?:\.\d+)?%?", # 阿拉伯数字 rf"[{CN_NUM}]{{1,6}}(?:次|个|天|小时|分钟|秒|倍|成|条|项|元)", ] found = [] for p in patterns: found.extend(re.findall(p, text)) return sorted(found) def check(before, after, threshold=0.4): a, b = extract_numbers(before), extract_numbers(after) if a != b: return False, f"数字不一致: 原文 {a} / 改写 {b}" ratio = 1 - similarity(before, after) if ratio > threshold: return False, f"改动比例 {ratio:.2f} 超过阈值 {threshold}" return True, "ok"

这段代码不复杂，但它拦下来的事故比任何风格规则都多。写完那段脚本之后，我再没遇到过数量条件被改掉的情况。

6.2 过度口语化：专业文档被改成朋友圈

第二个坑方向相反。intensity开到 3，scene选错成casual，一份需要发给外部合作方的方案说明，被改成了"咱们这个方案呢，主要是想解决三个事儿"。

这类问题的本质是场景标签和实际交付场景不匹配。修法不能只靠"记得选对标签"，得在流程上加约束。我的做法是：scene必须显式传，不传就报错，不给默认值。默认值是万恶之源——一旦有默认，人就会忘记传。

另外加了一条兜底规则：如果原文中检测到大量专业术语、代码块、表格，自动降级intensity到 1，并在返回结果里提示"检测到专业内容，已自动降低改写幅度"。这条规则救过好几次。

口语化还有个隐性代价：可读性下降。口语表达依赖上下文，一句"这个事儿吧，得先看看情况"在对话里很自然，在文档里就是含糊。判断标准很简单——改完之后，一个没看过上下文的人能不能看懂。看不懂就是改过头了。

6.3 触发失灵与重复改写的死循环

第三个坑有两半，都跟调用时机有关。

触发失灵。前面第 3.2 节讲过，description写得太抽象，技能不被调用。另一半是反过来：description写得太宽，几乎每个任务都触发，把不该改的东西也改了。这半更隐蔽，因为你不容易发现。我的做法是定期看调用日志，统计触发率和实际有用率，触发率高但有用率低，就说明描述太宽，得收紧排除项。

死循环。批量跑的时候遇到过：某一段改写后校验失败，回退，再改写，再失败。原因是这段文本里有个数字表述，"三次"被改成了"3次"，校验判定数字不一致，回退后又改一遍，反复。解决办法是加熔断：同一段连续失败两次就跳过，标记为"需人工处理"并输出失败原因，不再重试。熔断阈值不设，批量任务可能卡死在一个段上。

还有个相关的坑是结果不稳定。同样的输入跑两次，改写结果差很多，因为模型输出带随机性。对需要版本管理的文档，这个不可接受。我的处理是把改写结果和输入一起存快照，同一批任务用同一个快照，不重新生成。

7. 验收与调优：怎么判断这版 Humanizer 是好用的

7.1 一套可量化的自检指标

改得好不好，不能靠"我觉得自然多了"来判断。我给自己定了一套指标，每次改规则跑一遍，跟基线比。

前三个指标看"改到位没有"，中间两个看"有没有改坏"，最后一个看"结构有没有动"。

用这套指标有个技巧：不要只看平均数，要看分布。平均套话密度降了 50%，但可能有十段完全没动，那十段就是漏网的。我一般会额外输出一份"未改动段落清单"，逐个人工扫一眼，看是本来就干净，还是漏检了。

7.2 规则库的迭代节奏与回归测试集

规则库是要长期养的，节奏比强度重要。

每周一次小迭代：把候选池里的新词筛进正式词表，一般加五到十条，不多加。一次加太多，你没法判断是哪条规则起了作用。

每月一次回归测试：跑一遍固定样例集，对比基线指标，看有没有退化。退化通常是加规则加过头导致的，比如把"其实""说实话"这类口语连接词也禁了，结果文字变得生硬。

每季度一次大清理：把三个月内一次都没命中的规则删掉，把误报率高的规则降级成hint。规则库最怕只增不减，最后变成一堆互相矛盾的条目，跑出来的结果谁也解释不清。

回归测试集我建议至少包含四类样例：技术文档（考术语保留）、客服话术（考共情度）、长文（考结构）、短文案（考信息密度）。每类三到五段，都是带有典型问题的真实文本，脱敏后存起来。这十几段文本是你判断"这版到底行不行"的唯一依据，比任何主观感受都可靠。

提示：回归测试集不要用自己改过的文本当样例。改过的文本已经被"调教"过，用它测出来的效果会虚高。用原始的、未经处理的真实稿件。

最后说点个人体会。Humanizer 这类技能的价值，不在于它能写出多漂亮的文字，而在于它把"什么算好"这件事从模糊感觉变成了可维护的规则集。我最早做内容的时候，改稿全靠眼睛扫，一篇文章读三遍，改完还是心里没底。现在有了固定的检测清单和校验脚本，至少能保证每次交付之前，那些最容易翻车的地方——数字、术语、否定词——是被机器盯住的。剩下的"读起来顺不顺"，还是得人来判断，这部分短期内我看不到被替代的可能。倒是有一个小技巧值得分享：每次改完一批稿子，挑最不满意的三段存起来，下个月再读一遍，如果还是觉得别扭，那多半是规则库缺了某一类条目，而不是模型不行——顺着这三段去找规律，比漫无目的地读一百篇范文有用得多。