unslop-file

Unslop Humanize

目的

重写自然语言记忆文件（CLAUDE.md、AGENTS.md、待办事项、偏好设置、文档），让它们读起来像是人写的：不谄媚、不堆砌陈词滥调、不套用五段式作文结构、不用三段式填充内容。所有技术内容保持原样：代码块、行内代码、URL、文件路径、命令、标题、表格。

两种模式：

• --deterministic — 快速运行正则处理，去除典型的 AI 腔表达并精简三段式表达。不调用 API，也不需要 ANTHROPIC_API_KEY。适用于批量处理和 CI。
• LLM 模式（默认） — 调用 Claude（通过 Anthropic SDK，或在需要时回退到 claude --print CLI），进行全面重写，调整语句节奏、重组刻意修饰的段落，并贴合原有语气。速度较慢，但质量更好。

人性化改写后的版本会覆盖原文件。系统会先写入 FILE.original.md 备份。编辑 .original.md 后重新运行即可生成新版本。

强度级别（--mode）

模式	执行内容	适用场景……
subtle	仅处理陈词滥调。	结构没问题，只想去掉 AI 用语。
balanced	（默认。）处理谄媚、模棱两可、过渡语、陈词滥调、权威话术、提示语、刻意营造的平衡，并限制破折号的使用。	日常文档 / README / CLAUDE.md。
full	在 balanced 的基础上，还处理填充短语、否定式并列三段表达，并使用更严格的 LLM 提示词。	营销文案、发行说明、AI 腔浓重的 LLM 输出。

两阶段审查

先运行确定性处理并生成报告，再修复遗漏的问题：

humanize --deterministic --report audit.json doc.md     # writes audit + humanized
humanize doc.md                                         # optional LLM polish on top

audit.json 会列出所有触发的规则、每组“修改前 → 修改后”的内容，以及 counts_by_rule。在决定是否合并差异前，可借此检查正则修改了哪些内容。

触发方式

/unslop-file <filepath>、/unslop:humanize <filepath>，或“humanize memory file”“de-slop this doc”“strip AI tone from this file”。

处理流程

脚本位于与此 SKILL.md 相邻的 scripts/ 目录中。

常见目录结构：

• 完整仓库：unslop/SKILL.md + unslop/scripts/
• 同步镜像：skills/unslop-file/SKILL.md + skills/unslop-file/scripts/
• Codex 套件：plugins/unslop/skills/unslop-file/SKILL.md + 同级的 scripts/

始终优先使用当前已加载的 SKILL 文件旁边的 scripts/。

步骤：

1. 找到包含此 SKILL.md 的目录及其同级的 scripts/ 目录。
2. 在该目录中运行：python3 -m scripts <absolute_filepath>（LLM 模式）；正则处理则添加 --deterministic。
3. CLI 流程：检测文件类型 → 写入 .original.md 备份 → 进行人性化改写 → 验证（检查内容是否保留 + 检查残留的 AI 腔表达）→ 验证出错时：调用 LLM 针对性修复 → 最多重试 2 次。
4. 最终失败时：报告错误、还原原文件，并以状态码 2 退出。
5. 成功时：报告人性化改写后的文件和 .original.md 备份的路径，并以状态码 0 退出。
6. 将结果返回给用户。

人性化改写规则

移除（典型的 AI 套话）

• 谄媚式开场白：“问得好！”、“当然！”、“绝对没问题！”、“没问题！”、“我很乐意帮忙”、“真是个有趣的话题……”
• 陈词滥调词汇：delve、tapestry、testament（表示赞誉）、navigate/embark/journey（比喻用法）、realm、landscape（比喻用法）、pivotal、paramount、seamless、holistic、leverage（作为填充动词）、robust（作为填充词）、comprehensive（能用“完整”表达时）、cutting-edge、state-of-the-art（作为填充词）、interplay、intricate、vibrant、underscore(s)/d/ing（比喻用法）、crucial、vital（描述作用、重要性或组成部分时）、ever-evolving、ever-changing、in today's (digital) world/age、dynamic landscape。
• 模棱两可的开场白：“需要注意的是”、“值得一提的是”、“一般来说”、“本质上”、“从根本上说”、“应该注意的是”、“还值得指出的是”。
• 权威腔套话（句首）：“从根本上说，”、“实际上，”、“根本而言，”、“真正重要的是”、“问题的关键在于”、“X 的核心是”。
• 提示性公告：“让我们深入探讨……”、“让我们逐一分析”、“以下是你需要了解的内容”、“话不多说”、“本文将……”、“做好准备”。
• 过渡语癖（句首）：“此外，”、“而且，”、“另外，”、“总之，”、“概括来说，”。
• 刻意两面兼顾：在每个观点后都加上“然而”或“另一方面”。
• 破折号堆砌（每段超过两个破折号）。
• 填充短语（仅 --mode full）：将“为了”改为“以便”，将“由于……这一事实”改为“因为”，将“在……之前”改为“之前”，将“关于”改为“有关”，将“种类繁多的”改为“许多”，将“在这个时间点”改为“现在”，将“……这一事实”改为“……”，等等。
• 否定式三连句（仅 --mode full）：“不靠猜测、不添冗余、不出意外。”——这种修辞性的否定三连句。

精简

• 三连列举：“X、Y 和 Z”这类堆叠，能用两项表达时就删去较弱的一项
• 列表堆砌：三条表达同一意思的项目应合并为一句
• 五段式作文结构：调整段落长度；不要写四段长度相同的段落

原样保留（绝不修改）

• 围栏代码块（...）——逐字节保留
• 缩进代码块（4 个空格）
• 行内代码（...）
• URL 和 Markdown 链接
• 文件路径（./src/、/etc/、C:\Users\...）
• 命令（npm install、git rebase、docker run）
• 技术术语、专有名称、API 名称
• 日期、版本号、数字
• 环境变量（$HOME、${NODE_ENV}）

保留结构

• 所有 Markdown 标题（文字完全一致）
• 项目符号层级与嵌套
• 编号列表
• 表格（可压缩单元格内容，但须保留结构）
• YAML 前置内容

关键规则

``` ... ``` 内的所有内容均为只读。不得更改注释、空白字符或行顺序。行内反引号内容也必须原样保留。代码是基础；只对代码区域之间的散文进行润色。

模式（处理前 → 处理后）

#	处理前	处理后（确定性，--mode balanced）
1	请务必注意，在推送更改之前运行测试是一项全面的最佳实践。此外，值得一提的是，这样做可以防止构建失败。	在推送更改之前运行测试是一项全面的最佳实践。这样可以防止构建失败。
2	该应用采用微服务架构，由多个彼此独立的组件构成。	该应用使用微服务架构，由多个彼此独立的组件构成。
3	从根本上说，缓存以占用内存为代价换取更低的延迟。	缓存以占用内存为代价换取更低的延迟。
4	让我们开始吧。这是第一步。	这是第一步。
5	缓存与延迟之间错综复杂的相互作用至关重要。	缓存与延迟之间的详细联系很重要。
6	在当今的数字世界中，我们快速交付。	如今，我们快速交付。

在 --mode full 模式下，还会进行以下处理：

#	处理前	处理后
7	我们运行测试是为了验证修复。	我们运行测试以验证修复。
8	构建失败，这是因为磁盘已满。	磁盘已满，因此构建失败。
9	不猜测、不臃肿、无意外。	(已剔除)

参考资料

• blader/unslop — Claude-Code 技能，列出了 30 多种 AI 写作特征；我们采用了其中最显著的特征。
• Wikipedia：AI 写作的迹象 — 用于词汇的公开分类体系，经交叉参考后采用。
• 完整对比与差距分析：docs/research/IMPLEMENTATION_TRACE.md。

边界

• 仅处理 .md、.txt、.markdown、.rst 文件，或无扩展名的自然语言文件。
• 切勿修改 .py、.js、.ts、.json、.yaml、.yml、.toml、.env、.lock、.css、.html、.xml、.sql、.sh 文件。
• 同时包含文本和代码的文件：仅润色文本，保留围栏代码不变。
• 如果无法确定文件是文本还是代码，则保持不变。
• 覆盖文件前会写入备份 FILE.original.md。切勿润色名称已为 *.original.md 的文件。
• 敏感路径（匹配 .env*、*.pem、*.key、~/.ssh/、~/.aws/ 等的路径）会在读取文件或进行任何 API 调用前被拒绝。
• 超过 500 KB 的文件会被拒绝。